PAP-10440: group artifacts by task stacks (#7654)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The artifacts surface is where board users inspect files, media, and documents produced by agents. > - Grouped artifact stacks make that surface easier to scan by task, but the first pass still made grouping feel secondary to media filters. > - The follow-up request was to make grouping the default and give the grouping control the same icon-only outline treatment used on the issues page. > - This pull request keeps the existing artifact grouping API/UI, then polishes the artifacts toolbar state and Storybook review coverage. > - The benefit is that `/artifacts` now opens in the task-stack view by default while preserving explicit flat-mode filtering via `groupBy=none`. ## Linked Issues or Issue Description No public GitHub issue exists for this internal Paperclip task. ### Subsystem affected ui/ — React + Vite board UI. ### Problem or motivation The `/artifacts` grouping affordance was visually placed after the media filters, rendered as a text button, and defaulted to a flat artifact list. Internal follow-up `PAP-10465` requested the grouping icon move left of the filters, become an icon-only outlined button like `/issues`, and make Task grouping the default. ### Proposed solution Default `/artifacts` to grouped Task stacks, keep explicit flat mode available as `groupBy=none`, move the grouping control before the media chips, and restyle it as the shared icon-only outline button pattern. ### Alternatives considered Leaving flat mode as the implicit default was rejected because it does not satisfy the follow-up. Keeping a text label on the grouping trigger was rejected because `/issues` already established the icon-only outline pattern for this class of toolbar control. ### Roadmap alignment This aligns with the `Artifacts & Work Products` roadmap item by making generated outputs easier to inspect and operate from the board UI. ## What Changed - Defaulted the `/artifacts` page to `groupBy=task` when no grouping URL param is present, while keeping explicit flat mode available with `groupBy=none`. - Moved the group control before the media filter chips and changed it to an icon-only outlined button using the shared `Button` pattern. - Updated artifact page tests to cover default Task grouping, explicit flat mode, trigger ordering, and icon-only outline metadata. - Updated the artifact Storybook story so its toolbar mock matches the production ordering and grouped Task is documented as the default mode. ## Verification - `pnpm exec vitest run ui/src/pages/Artifacts.test.tsx ui/src/components/artifacts/ArtifactGroupCard.test.tsx` — passed. - `pnpm --filter @paperclipai/ui typecheck` — passed. - `pnpm --filter @paperclipai/server typecheck` — passed. - `git diff --check` — passed. - QA visual validation from internal follow-up PAP-10466 passed desktop/mobile scenarios. Screenshot evidence attached there: - Desktop default: http://paperclip-dev:3100/api/attachments/bc81305d-f5de-485c-abeb-9e7c3d9d8539/content - Desktop toolbar close-up: http://paperclip-dev:3100/api/attachments/3375a62b-2110-48f3-bafa-ea98c00f99f7/content - Mobile default: http://paperclip-dev:3100/api/attachments/bfc5642e-9248-431e-9bac-36284dec1c89/content - Mobile toolbar close-up: http://paperclip-dev:3100/api/attachments/ca79401a-5ba8-464d-bc6e-aeffd47fe695/content - GitHub PR checks on head `431964c8b` — passed, including Greptile 5/5. ## Risks Low to medium risk. The main behavior shift is intentional: `/artifacts` now queries grouped Task stacks by default. Existing flat mode remains available through the grouping menu and explicit `groupBy=none` URLs. ## Model Used OpenAI Codex, GPT-5.4 class coding model in this Paperclip heartbeat environment, with shell, git, test, and GitHub CLI tool use. Context window managed by the Codex runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -97,7 +97,7 @@ function TextPreview({ artifact }: { artifact: CompanyArtifact }) {
|
||||
);
|
||||
}
|
||||
|
||||
function ArtifactPreview({ artifact }: { artifact: CompanyArtifact }) {
|
||||
export function ArtifactPreview({ artifact }: { artifact: CompanyArtifact }) {
|
||||
switch (artifact.mediaKind) {
|
||||
case "image":
|
||||
return <ImagePreview artifact={artifact} />;
|
||||
|
||||
@@ -0,0 +1,121 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { flushSync } from "react-dom";
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { MemoryRouter } from "react-router-dom";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { ArtifactGroupCard } from "./ArtifactGroupCard";
|
||||
import type { CompanyArtifact, CompanyArtifactGroup } from "@/api/artifacts";
|
||||
|
||||
vi.mock("@/context/CompanyContext", () => ({
|
||||
useCompany: () => ({ selectedCompany: null, selectedCompanyId: "company-1" }),
|
||||
}));
|
||||
|
||||
function sampleArtifact(overrides: Partial<CompanyArtifact> = {}): CompanyArtifact {
|
||||
return {
|
||||
id: "artifact-1",
|
||||
source: "attachment",
|
||||
mediaKind: "image",
|
||||
title: "Hero shot",
|
||||
previewText: null,
|
||||
contentType: "image/png",
|
||||
contentPath: "/files/hero.png",
|
||||
openPath: "/files/hero.png",
|
||||
downloadPath: "/files/hero.png?download=1",
|
||||
issue: { id: "issue-1", identifier: "PAP-42", title: "Ship launch" },
|
||||
project: null,
|
||||
createdByAgent: null,
|
||||
updatedAt: "2026-06-01T00:00:00.000Z",
|
||||
href: "/PAP/issues/PAP-42#attachment-1",
|
||||
...overrides,
|
||||
} as CompanyArtifact;
|
||||
}
|
||||
|
||||
function sampleGroup(overrides: Partial<CompanyArtifactGroup> = {}): CompanyArtifactGroup {
|
||||
return {
|
||||
id: "task:issue-1",
|
||||
groupBy: "task",
|
||||
issue: { id: "issue-1", identifier: "PAP-42", title: "Ship launch" },
|
||||
title: "Ship launch",
|
||||
count: 3,
|
||||
mediaKinds: ["image"],
|
||||
previewArtifacts: [sampleArtifact()],
|
||||
updatedAt: "2026-06-01T00:00:00.000Z",
|
||||
href: "/PAP/artifacts?groupBy=task&groupIssueId=issue-1",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function render(group: CompanyArtifactGroup, to = "?groupBy=task&groupIssueId=issue-1") {
|
||||
const container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
const root = createRoot(container);
|
||||
flushSync(() => {
|
||||
root.render(
|
||||
<MemoryRouter>
|
||||
<ArtifactGroupCard group={group} to={to} />
|
||||
</MemoryRouter>,
|
||||
);
|
||||
});
|
||||
return { container, root };
|
||||
}
|
||||
|
||||
describe("ArtifactGroupCard", () => {
|
||||
let mounted: { container: HTMLElement; root: ReturnType<typeof createRoot> } | null = null;
|
||||
|
||||
beforeEach(() => {
|
||||
mounted = null;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
if (mounted) {
|
||||
flushSync(() => mounted!.root.unmount());
|
||||
mounted.container.remove();
|
||||
mounted = null;
|
||||
}
|
||||
});
|
||||
|
||||
it("shows a stack effect and plural count when count > 1", () => {
|
||||
mounted = render(sampleGroup({ count: 3 }));
|
||||
const card = mounted.container.querySelector('[data-testid="artifact-group-card"]') as HTMLElement;
|
||||
expect(card).not.toBeNull();
|
||||
expect(card.getAttribute("data-stacked")).toBe("true");
|
||||
expect(card.getAttribute("data-count")).toBe("3");
|
||||
// Two decorative stack layers sit behind the card.
|
||||
expect(mounted.container.querySelectorAll('[data-testid="artifact-stack-layer"]').length).toBe(2);
|
||||
expect(mounted.container.textContent).toContain("3 artifacts");
|
||||
});
|
||||
|
||||
it("omits the stack effect and uses singular count when count === 1", () => {
|
||||
mounted = render(sampleGroup({ count: 1 }));
|
||||
const card = mounted.container.querySelector('[data-testid="artifact-group-card"]') as HTMLElement;
|
||||
expect(card.getAttribute("data-stacked")).toBe("false");
|
||||
expect(card.getAttribute("data-count")).toBe("1");
|
||||
expect(mounted.container.querySelectorAll('[data-testid="artifact-stack-layer"]').length).toBe(0);
|
||||
expect(mounted.container.textContent).toContain("1 artifact");
|
||||
expect(mounted.container.textContent).not.toContain("1 artifacts");
|
||||
});
|
||||
|
||||
it("links to the provided stack destination and shows the task subject", () => {
|
||||
mounted = render(sampleGroup());
|
||||
const anchor = mounted.container.querySelector("a") as HTMLAnchorElement;
|
||||
expect(anchor).not.toBeNull();
|
||||
expect(anchor.getAttribute("href")).toContain("groupIssueId=issue-1");
|
||||
expect(mounted.container.textContent).toContain("PAP-42");
|
||||
expect(mounted.container.textContent).toContain("Ship launch");
|
||||
});
|
||||
|
||||
it("renders the first preview artifact image", () => {
|
||||
mounted = render(sampleGroup());
|
||||
const img = mounted.container.querySelector("img") as HTMLImageElement;
|
||||
expect(img).not.toBeNull();
|
||||
expect(img.getAttribute("src")).toBe("/files/hero.png");
|
||||
});
|
||||
|
||||
it("falls back to a placeholder when there are no preview artifacts", () => {
|
||||
mounted = render(sampleGroup({ previewArtifacts: [] }));
|
||||
expect(mounted.container.querySelector("img")).toBeNull();
|
||||
const card = mounted.container.querySelector('[data-testid="artifact-group-card"]') as HTMLElement;
|
||||
expect(card).not.toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,87 @@
|
||||
import { Layers } from "lucide-react";
|
||||
import type { To } from "react-router-dom";
|
||||
import type { CompanyArtifactGroup } from "@/api/artifacts";
|
||||
import { Link } from "@/lib/router";
|
||||
import { ArtifactPreview } from "@/components/artifacts/ArtifactCard";
|
||||
import { formatDate } from "@/lib/utils";
|
||||
|
||||
interface ArtifactGroupCardProps {
|
||||
group: CompanyArtifactGroup;
|
||||
/** Destination for opening this stack (preserves active filters/search). */
|
||||
to: To;
|
||||
}
|
||||
|
||||
/**
|
||||
* A stack card rendered in grouped mode. It mirrors the dimensions and preview
|
||||
* of {@link ArtifactCard} so grouped and flat grids share the same rhythm, and
|
||||
* layers a subtle "stack" effect behind the card only when it represents more
|
||||
* than one artifact.
|
||||
*/
|
||||
export function ArtifactGroupCard({ group, to }: ArtifactGroupCardProps) {
|
||||
const stacked = group.count > 1;
|
||||
const preview = group.previewArtifacts[0];
|
||||
const countLabel = `${group.count} artifact${group.count === 1 ? "" : "s"}`;
|
||||
|
||||
return (
|
||||
<div className="relative">
|
||||
{stacked ? (
|
||||
<>
|
||||
<div
|
||||
aria-hidden="true"
|
||||
data-testid="artifact-stack-layer"
|
||||
className="pointer-events-none absolute inset-0 translate-x-[8px] translate-y-[8px] rounded-[8px] border border-border bg-muted/40 shadow-sm"
|
||||
/>
|
||||
<div
|
||||
aria-hidden="true"
|
||||
data-testid="artifact-stack-layer"
|
||||
className="pointer-events-none absolute inset-0 translate-x-[4px] translate-y-[4px] rounded-[8px] border border-border bg-muted/70 shadow-sm"
|
||||
/>
|
||||
</>
|
||||
) : null}
|
||||
|
||||
<Link
|
||||
to={to}
|
||||
title={countLabel}
|
||||
data-testid="artifact-group-card"
|
||||
data-group-id={group.id}
|
||||
data-count={group.count}
|
||||
data-stacked={stacked ? "true" : "false"}
|
||||
className="group relative flex flex-col overflow-hidden rounded-[8px] border border-border bg-card transition-colors hover:border-foreground/20"
|
||||
>
|
||||
<div className="relative">
|
||||
{preview ? (
|
||||
<ArtifactPreview artifact={preview} />
|
||||
) : (
|
||||
<div className="flex aspect-video w-full items-center justify-center bg-accent/20 text-muted-foreground/50">
|
||||
<Layers className="h-7 w-7" aria-hidden="true" />
|
||||
</div>
|
||||
)}
|
||||
<span className="absolute right-2 top-2 inline-flex items-center gap-1 rounded-full bg-background/85 px-2 py-0.5 text-[11px] font-medium text-foreground/90 shadow-sm backdrop-blur">
|
||||
<Layers className="h-3 w-3" aria-hidden="true" />
|
||||
{group.count}
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<div className="flex flex-1 flex-col gap-1 p-3">
|
||||
<div className="flex h-7 items-center gap-2">
|
||||
<span className="shrink-0 font-mono text-[11px] text-muted-foreground">
|
||||
{group.issue.identifier}
|
||||
</span>
|
||||
<h3
|
||||
className="min-w-0 flex-1 truncate text-sm font-medium leading-7 text-foreground/85"
|
||||
title={group.title}
|
||||
>
|
||||
{group.title}
|
||||
</h3>
|
||||
</div>
|
||||
|
||||
<div className="mt-0.5 flex items-center gap-1.5 text-[11px] text-muted-foreground/65">
|
||||
<span>{countLabel}</span>
|
||||
<span className="text-muted-foreground/50">·</span>
|
||||
<span>Updated {formatDate(group.updatedAt)}</span>
|
||||
</div>
|
||||
</div>
|
||||
</Link>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user