refactor(webapp): compose practice adoption from shared design-system parts

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/adopt-without-leaving-practice-setup.md

@@ -2,4 +2,4 @@
 "hephaestus": patch
 ---
 
-Adding practices from the library no longer takes you away from Practice setup. A practice or an area opens in a panel over the page you were already on, and opening a practice from inside an area stacks a second panel on top of the first — step back one at a time with Escape, the browser's Back button, or a swipe. Adding a practice now returns you to the library with the row marked Added, instead of dropping you into an edit form, so a run of five practices is five clicks rather than five round trips. Every panel is addressable: the URL you are looking at is the URL you can share, and it reopens exactly the panels you had open.
+Adding practices from the library no longer takes you away from Practice setup. A practice or an area opens in a panel over the page you were already on, and opening a practice from inside an area stacks a second panel on top of the first — step back one at a time with Escape, a press on the page beside the panel, the browser's Back button, or a swipe. The page behind stays readable rather than blurred, and each panel leaves a column of the one beneath it showing, so you can see where you are in the stack. Adding a practice now returns you to the library with the row marked Added, instead of dropping you into an edit form, so a run of five practices is five clicks rather than five round trips. Every panel is addressable: the URL you are looking at is the URL you can share, and it reopens exactly the panels you had open.

webapp/src/components/admin/curated-catalog/CuratedCatalogTree.tsx

@@ -1,7 +1,7 @@
 import { Link } from "@tanstack/react-router";
 import { GripVertical, MoreHorizontal } from "lucide-react";
 import type { CuratedArea, CuratedPracticeSummary } from "@/api/types.gen";
-import { getAreaVisual } from "@/components/admin/practice-catalog/area-visuals";
+import { AreaPill } from "@/components/admin/practice-catalog/AreaPill";
 import { automatedReviewLimitationLabel } from "@/components/admin/practice-catalog/evidence-presentation";
 import {
 	type CatalogEntryMoveActions,
@@ -26,7 +26,6 @@ import { Item, ItemContent, ItemDescription, ItemTitle } from "@/components/ui/i
 import { Spinner } from "@/components/ui/spinner";
 import { Switch } from "@/components/ui/switch";
 import { artifactKindLabel } from "@/lib/artifact-kinds";
-import { cn } from "@/lib/utils";
 import { CuratedEntryBadges } from "./CuratedEntryBadges";
 
 type TreeArea = CuratedArea & { displayOrder: number; name: string };
@@ -139,19 +138,13 @@ export function CuratedCatalogTree({
 }
 
 function AreaIcon({ area }: { area: TreeArea }) {
-	const { Icon, pill } = getAreaVisual(
-		area.slug,
-		area.definition.name,
-		area.definition.icon,
-		area.definition.color,
-	);
 	return (
-		<span
-			className={cn("flex size-8 shrink-0 items-center justify-center rounded-md", pill)}
-			aria-hidden
-		>
-			<Icon className="size-4" />
-		</span>
+		<AreaPill
+			slug={area.slug}
+			name={area.definition.name}
+			icon={area.definition.icon}
+			color={area.definition.color}
+		/>
 	);
 }
 

webapp/src/components/admin/practice-adoption/AreaAdoptionPanel.stories.tsx

@@ -7,9 +7,11 @@ import {
 	mockPullRequestBinding,
 	mockPullRequestPolicy,
 } from "@/mocks/fixtures/practice";
+import { withPageBehind } from "@/stories/decorators";
+import { Stateful } from "@/stories/stateful";
 import { expectGenuinelyDisabled } from "@/test/controls";
 import { expectSettledVisible } from "@/test/overlay";
-import { AreaAdoptionPanel } from "./AreaAdoptionPanel";
+import { AreaAdoptionPanel, type AreaAdoptionState } from "./AreaAdoptionPanel";
 
 const practice = {
 	slug: "describe-what-and-why",
@@ -59,28 +61,36 @@ const preview: CatalogAreaAdoptionPreview = {
 	],
 };
 
+const ready = (over: Partial<CatalogAreaAdoptionPreview> = {}, adding = false) =>
+	({ status: "ready", preview: { ...preview, ...over }, adding }) as const;
+
 /**
  * An area states each practice's outcome on the practice's own row, so the panel needs no prose
- * explaining which of four lists a name ended up in — and no embedded copy of the definition,
- * which opens as its own level on top instead.
+ * explaining which of four lists a name ended up in — and no embedded copy of the definition, which
+ * opens as its own level on top instead.
  */
 const meta = {
 	title: "Workspace admin/Practice adoption/Area panel",
 	component: AreaAdoptionPanel,
-	parameters: { layout: "fullscreen", chromatic: { viewports: [320, 1440] } },
+	parameters: { layout: "fullscreen" },
+	decorators: [withPageBehind],
 	args: {
-		preview,
-		isLoading: false,
-		isError: false,
-		isPending: false,
-		onRetry: fn(),
+		state: ready(),
 		onConfirm: fn(),
 		onOpenPractice: fn(),
 	},
+	argTypes: {
+		// A discriminated union renders as a free-text box, which cannot produce a valid value.
+		state: { control: false },
+	},
 	render: (args) => (
-		<DetailDrawerStack stack={[{ kind: "area", id: "review-ready-work" }]} onClose={() => {}}>
-			{() => <AreaAdoptionPanel {...args} />}
-		</DetailDrawerStack>
+		<Stateful initial={[{ kind: "area", id: preview.slug }]}>
+			{(stack, setStack) => (
+				<DetailDrawerStack stack={stack} onClose={(depth) => setStack(stack.slice(0, depth))}>
+					{(_entry, level) => <AreaAdoptionPanel {...args} nested={level.nested} />}
+				</DetailDrawerStack>
+			)}
+		</Stateful>
 	),
 	tags: ["autodocs"],
 } satisfies Meta<typeof AreaAdoptionPanel>;
@@ -96,24 +106,29 @@ export const MixedOutcomes: Story = {
 		await expect(screen.getByText("Adds")).toBeVisible();
 		await expect(screen.getByText("Already here")).toBeVisible();
 		await expect(screen.getByText("Blocked")).toBeVisible();
-		await userEvent.click(
-			screen.getByRole("button", { name: "Describe what changed and why, adds" }),
-		);
+		await userEvent.click(screen.getByRole("button", { name: /Describe what changed and why/ }));
 		await expect(args.onOpenPractice).toHaveBeenCalledWith("describe-what-and-why");
 	},
 };
 
+export const DismissReturnsToThePage: Story = {
+	play: async () => {
+		await expectSettledVisible(await screen.findByRole("button", { name: "Add 1 practice" }));
+		await userEvent.click(screen.getByRole("button", { name: "Close" }));
+		await expect(await screen.findByRole("heading", { name: "Practice setup" })).toBeVisible();
+	},
+};
+
 export const RestoreDeletedArea: Story = {
 	args: {
-		preview: {
-			...preview,
+		state: ready({
 			disposition: "REUSE_EXISTING_AREA",
 			actions: [
 				{ slug: "describe-what-and-why", action: "MOVE_TO_AREA" },
 				{ slug: "focused-changes", action: "MOVE_TO_AREA" },
 				{ slug: "clear-context", action: "KEEP" },
 			],
-		},
+		}),
 	},
 	play: async () => {
 		// Nothing is created, so the action is a restore rather than an add.
@@ -124,51 +139,59 @@ export const RestoreDeletedArea: Story = {
 
 export const NothingToChange: Story = {
 	args: {
-		preview: {
-			...preview,
+		state: ready({
 			actions: preview.actions.map(({ slug }) => ({ slug, action: "KEEP" as const })),
-		},
+		}),
 	},
 	play: async () => {
 		await expectGenuinelyDisabled(await screen.findByRole("button", { name: "Add 0 practices" }));
 	},
 };
 
 export const Loading: Story = {
-	args: { preview: undefined, isLoading: true },
+	args: { state: { status: "loading" } },
 	play: async () => {
 		await expectSettledVisible(await screen.findByText("Loading area preview"));
+		// The header cannot invent an area colour for a slug that has not loaded.
+		await expect(screen.getByRole("heading", { name: "Practice area" })).toBeVisible();
 	},
 };
 
 export const FailedToLoad: Story = {
-	args: { preview: undefined, isLoading: false, isError: true, error: new Error("offline") },
+	args: { state: { status: "error", error: new Error("offline"), onRetry: fn() } },
 	play: async ({ args }) => {
 		const retry = await screen.findByRole("button", { name: "Retry" });
 		await expectSettledVisible(retry);
 		await userEvent.click(retry);
-		await expect(args.onRetry).toHaveBeenCalledOnce();
+		await expect(
+			(args.state as Extract<AreaAdoptionState, { status: "error" }>).onRetry,
+		).toHaveBeenCalledOnce();
 	},
 };
 
 export const Adding: Story = {
-	args: { isPending: true },
+	args: { state: ready({}, true) },
 	play: async () => {
 		await expectGenuinelyDisabled(await screen.findByRole("button", { name: "Adding…" }));
 	},
 };
 
-export const LongContentInDarkMode: Story = {
+export const LongContent: Story = {
 	args: {
-		preview: {
-			...preview,
+		state: ready({
 			definition: {
 				name: "Decisions, documentation, and long-lived operational knowledge",
 				description:
 					"Practices covering how a team records the reasoning behind a change, keeps operational runbooks current, and makes the resulting knowledge findable long after the original authors have moved on.",
 			},
-		},
+		}),
 	},
-	globals: { theme: "dark" },
+};
+
+export const NarrowViewport: Story = {
 	parameters: { viewport: { defaultViewport: "reflow" }, chromatic: { viewports: [320] } },
 };
+
+export const DarkMode: Story = {
+	globals: { theme: "dark" },
+};