@tangle-network/ui 11.12.0 → 11.13.1

package/src/primitives/input.test.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import { act, cleanup, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Input, Textarea } from "./input";
+import { Label } from "./label";
+
+afterEach(cleanup);
+
+describe.each([
+  ["Input", Input],
+  ["Textarea", Textarea],
+] as const)("%s relationships", (_name, Field) => {
+  it("gives repeated labels distinct, stable IDs and focuses the correct field", async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(<><Field label="Name" /><Field label="Name" /></>);
+    const fields = screen.getAllByRole("textbox");
+    const ids = fields.map((field) => field.id);
+    expect(ids.every(Boolean)).toBe(true);
+    expect(new Set(ids).size).toBe(2);
+    expect(screen.getAllByLabelText("Name")).toEqual(fields);
+    for (const [index, label] of screen.getAllByText("Name", { selector: "label" }).entries()) {
+      expect(label).toHaveAttribute("for", ids[index]);
+      await user.click(label);
+      expect(fields[index]).toHaveFocus();
+    }
+    rerender(<><Field label="Renamed" /><Field label="Renamed" /></>);
+    expect(screen.getAllByRole("textbox").map((field) => field.id)).toEqual(ids);
+  });
+
+  it("preserves an explicit ID and merges caller, hint and error descriptions without duplicates", () => {
+    render(<>
+      <p id="external">External instructions.</p>
+      <Field
+        id="profile"
+        label="Name"
+        hint="Use your full name."
+        error="Name is required."
+        aria-describedby={" external  external\tprofile-hint "}
+        aria-invalid={false}
+      />
+    </>);
+    const field = screen.getByRole("textbox", { name: "Name" });
+    expect(field).toHaveAttribute("id", "profile");
+    expect(field).toHaveAttribute("aria-describedby", "external profile-hint profile-error");
+    expect(screen.getByText("Use your full name.")).toHaveAttribute("id", "profile-hint");
+    expect(screen.getByText("Name is required.")).toHaveAttribute("id", "profile-error");
+    expect(field).toHaveAccessibleDescription("External instructions. Use your full name. Name is required.");
+    expect(field).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("associates descriptions without a convenience label and removes stale relationships", () => {
+    const { rerender } = render(<Field aria-label="Name" hint="A hint" error="An error" />);
+    const field = screen.getByRole("textbox", { name: "Name" });
+    const id = field.id;
+    expect(id).not.toBe("");
+    expect(field).toHaveAccessibleDescription("A hint An error");
+    rerender(<Field aria-label="Name" hint="A hint" />);
+    expect(field.id).toBe(id);
+    expect(field).toHaveAttribute("aria-describedby", `${id}-hint`);
+    expect(field).not.toHaveAttribute("aria-invalid");
+    expect(document.getElementById(`${id}-error`)).toBeNull();
+    rerender(<Field aria-label="Name" />);
+    const bareField = screen.getByRole("textbox", { name: "Name" });
+    expect(bareField.id).toBe(id);
+    expect(bareField).not.toHaveAttribute("aria-describedby");
+    expect(document.getElementById(`${id}-hint`)).toBeNull();
+  });
+
+  it("preserves the bare-element API and caller invalid states", () => {
+    const { container, rerender } = render(
+      <Field aria-label="Name" aria-describedby="external" aria-invalid="spelling" className="caller-class" />,
+    );
+    const field = screen.getByRole("textbox");
+    expect(container.firstElementChild).toBe(field);
+    expect(container.childElementCount).toBe(1);
+    expect(field).toHaveAttribute("aria-describedby", "external");
+    expect(field).toHaveAttribute("aria-invalid", "spelling");
+    expect(field).toHaveClass("caller-class");
+    rerender(<Field aria-label="Name" aria-invalid={false} />);
+    expect(field).toHaveAttribute("aria-invalid", "false");
+  });
+
+  it("uses the existing Label treatment", () => {
+    render(<><Label className="block">Reference</Label><Field label="Name" /></>);
+    expect(screen.getByText("Name", { selector: "label" }).className)
+      .toBe(screen.getByText("Reference").className);
+  });
+});
+
+it("keeps Input and Textarea IDs distinct even with the same label", () => {
+  render(<><Input label="Notes" /><Textarea label="Notes" /></>);
+  expect(new Set(screen.getAllByRole("textbox").map((field) => field.id)).size).toBe(2);
+});
+
+it("exposes Input's error variant without requiring error text", () => {
+  render(<Input aria-label="Name" variant="error" />);
+  expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+});
+
+it("forwards native field refs, values and change handlers", async () => {
+  const user = userEvent.setup();
+  const inputRef = React.createRef<HTMLInputElement>();
+  const textareaRef = React.createRef<HTMLTextAreaElement>();
+  const inputChange = vi.fn();
+  const textareaChange = vi.fn();
+  const { unmount } = render(<>
+    <Input ref={inputRef} label="Name" defaultValue="A" onChange={inputChange} />
+    <Textarea ref={textareaRef} label="Notes" defaultValue="B" onChange={textareaChange} />
+  </>);
+  expect(inputRef.current).toBe(screen.getByRole("textbox", { name: "Name" }));
+  expect(textareaRef.current).toBe(screen.getByRole("textbox", { name: "Notes" }));
+  await user.type(inputRef.current!, "lice");
+  await user.type(textareaRef.current!, "ody");
+  expect(inputRef.current).toHaveValue("Alice");
+  expect(textareaRef.current).toHaveValue("Body");
+  expect(inputChange).toHaveBeenCalled();
+  expect(textareaChange).toHaveBeenCalled();
+  unmount();
+  expect(inputRef.current).toBeNull();
+  expect(textareaRef.current).toBeNull();
+});
+
+it("hydrates SSR IDs and all description relationships without mismatch", async () => {
+  const ui = <React.StrictMode>
+    <p id="external">External instructions.</p>
+    <Input label="Name" hint="First hint" />
+    <Input label="Name" error="Required" />
+    <Textarea label="Name" hint="Notes hint" error="Too short" aria-describedby="external" />
+    <Input id="explicit" label="Explicit" hint="Explicit hint" />
+  </React.StrictMode>;
+  const container = document.createElement("div");
+  container.innerHTML = renderToString(ui, { identifierPrefix: "fields-" });
+  document.body.appendChild(container);
+  const serverHTML = container.innerHTML;
+  const serverIds = within(container).getAllByRole("textbox").map((field) => field.id);
+  const recoverableError = vi.fn();
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  let root: Root | undefined;
+  try {
+    await act(async () => {
+      root = hydrateRoot(container, ui, { identifierPrefix: "fields-", onRecoverableError: recoverableError });
+    });
+    expect(new Set(serverIds).size).toBe(4);
+    expect(within(container).getAllByRole("textbox").map((field) => field.id)).toEqual(serverIds);
+    expect(container.innerHTML).toBe(serverHTML);
+    for (const field of within(container).getAllByRole("textbox")) {
+      for (const id of field.getAttribute("aria-describedby")!.split(" ")) {
+        expect(document.getElementById(id)).not.toBeNull();
+      }
+    }
+    expect(recoverableError).not.toHaveBeenCalled();
+    expect(consoleError).not.toHaveBeenCalled();
+  } finally {
+    await act(async () => { root?.unmount(); });
+    consoleError.mockRestore();
+    container.remove();
+  }
+});

package/src/primitives/input.tsx

@@ -1,6 +1,9 @@
+"use client";
+
 import * as React from "react";
 import { focusField, focusFieldInvalid } from "../lib/focus";
 import { cn } from "../lib/utils";
+import { Label } from "./label";
 
 import { cva, type VariantProps } from "class-variance-authority";
 
@@ -30,6 +33,11 @@ const inputVariants = cva(
   }
 );
 
+// Only rendered descriptions are added; caller IDs and their order are retained.
+function descriptionIds(...ids: Array<string | undefined>) {
+  return [...new Set(ids.join(" ").split(/\s+/).filter(Boolean))].join(" ") || undefined;
+}
+
 export interface InputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">,
     VariantProps<typeof inputVariants> {
@@ -40,10 +48,16 @@ export interface InputProps
 
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
   (
-    { className, type, variant, size, label, error, hint, id, ...props },
+    {
+      className, type, variant, size, label, error, hint, id,
+      "aria-describedby": describedBy, "aria-invalid": invalid, ...props
+    },
     ref,
   ) => {
-    const inputId = id ?? label?.toLowerCase().replace(/\s+/g, "-");
+    const generatedId = React.useId();
+    const inputId = id ?? generatedId;
+    const hintId = hint ? `${inputId}-hint` : undefined;
+    const errorId = error ? `${inputId}-error` : undefined;
 
     const input = (
       <input
@@ -52,6 +66,8 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
         className={cn(inputVariants({ variant: error ? "error" : variant, size, className }))}
         ref={ref}
         {...props}
+        aria-describedby={descriptionIds(describedBy, hintId, errorId)}
+        aria-invalid={error || variant === "error" ? true : invalid}
       />
     );
 
@@ -59,19 +75,10 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
 
     return (
       <div className="w-full space-y-1.5">
-        {label && (
-          <label
-            htmlFor={inputId}
-            className="block font-medium text-foreground text-sm"
-          >
-            {label}
-          </label>
-        )}
+        {label && <Label htmlFor={inputId} className="block">{label}</Label>}
         {input}
-        {error && <p className="text-[var(--surface-danger-text)] text-sm font-medium">{error}</p>}
-        {hint && !error && (
-          <p className="text-[var(--text-dim)] text-sm">{hint}</p>
-        )}
+        {error && <p id={errorId} className="text-[var(--surface-danger-text)] text-sm font-medium">{error}</p>}
+        {hint && <p id={hintId} className="text-[var(--text-dim)] text-sm">{hint}</p>}
       </div>
     );
   },
@@ -90,10 +97,16 @@ export interface TextareaProps
 const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   (
     // `variant` is taken out so it never reaches the DOM element.
-    { className, variant: _variant, label, error, hint, id, ...props },
+    {
+      className, variant: _variant, label, error, hint, id,
+      "aria-describedby": describedBy, "aria-invalid": invalid, ...props
+    },
     ref,
   ) => {
-    const textareaId = id ?? label?.toLowerCase().replace(/\s+/g, "-");
+    const generatedId = React.useId();
+    const textareaId = id ?? generatedId;
+    const hintId = hint ? `${textareaId}-hint` : undefined;
+    const errorId = error ? `${textareaId}-error` : undefined;
 
     const textarea = (
       <textarea
@@ -108,6 +121,8 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         )}
         ref={ref}
         {...props}
+        aria-describedby={descriptionIds(describedBy, hintId, errorId)}
+        aria-invalid={error ? true : invalid}
       />
     );
 
@@ -115,19 +130,10 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
 
     return (
       <div className="w-full space-y-1.5">
-        {label && (
-          <label
-            htmlFor={textareaId}
-            className="block font-medium text-muted-foreground text-sm"
-          >
-            {label}
-          </label>
-        )}
+        {label && <Label htmlFor={textareaId} className="block">{label}</Label>}
         {textarea}
-        {error && <p className="text-[var(--surface-danger-text)] text-sm">{error}</p>}
-        {hint && !error && (
-          <p className="text-[var(--text-dim)] text-sm">{hint}</p>
-        )}
+        {error && <p id={errorId} className="text-[var(--surface-danger-text)] text-sm">{error}</p>}
+        {hint && <p id={hintId} className="text-[var(--text-dim)] text-sm">{hint}</p>}
       </div>
     );
   },

package/src/primitives/page-header.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { PageHeader } from "./page-header";
+import { StatusPill } from "./status-pill";
+
+const meta = {
+  title: "Primitives/PageHeader",
+  component: PageHeader,
+  parameters: { layout: "padded" },
+  args: {
+    title: "Activity",
+    description: "Inspect recent work and the scope of the results below.",
+    actions: <Button type="button">Export</Button>,
+    meta: <><span>12 results · Last 24 hours</span><StatusPill tone="success">Up to date</StatusPill></>,
+  },
+} satisfies Meta<typeof PageHeader>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+export const Nested: Story = { args: { level: 2 } };
+export const SandboxInputs: Story = {
+  args: { actions: undefined, action: <Button type="button">Create item</Button>, eyebrow: "Workspace", titleAs: "h2" },
+};
+export const NarrowLongContent: Story = {
+  render: () => <div data-narrow-header style={{ width: 320, maxWidth: "100%" }}>
+    <PageHeader
+      title="Production activity for workspace-with-a-very-long-unbroken-identifier-012345678901234567890123456789"
+      description="Inspect the selected activity without clipping the title or hiding action names."
+      eyebrow="Production workspace"
+      titleId="long-page-title"
+      actions={<>
+        <Button type="button" className="h-auto whitespace-normal">Export all selected activity for this workspace</Button>
+        <Button type="button" variant="outline" className="h-auto whitespace-normal">Create another activity item</Button>
+      </>}
+      meta={<><span>0 matching results</span><StatusPill tone="neutral">No filter matches</StatusPill></>}
+    />
+  </div>,
+  // Executes when this story is opened in a real browser. Building Storybook
+  // alone does not run this layout assertion.
+  play: async ({ canvasElement }) => {
+    await canvasElement.ownerDocument.fonts.ready;
+    const root = canvasElement.querySelector<HTMLElement>("[data-narrow-header]")!;
+    if (root.scrollWidth > root.clientWidth + 1) throw new Error("PageHeader overflows its narrow container");
+    for (const button of root.querySelectorAll("button")) {
+      if (button.scrollWidth > button.clientWidth + 1 || button.scrollHeight > button.clientHeight + 1) {
+        throw new Error("A long action label is clipped");
+      }
+    }
+  },
+};

package/src/primitives/page-header.test.tsx

@@ -1,3 +1,4 @@
+import { createRef } from "react";
 import { render, screen } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
 import { PageHeader } from "./page-header";
@@ -54,4 +55,51 @@ describe("PageHeader", () => {
     expect(container.querySelector("p")).toBeNull();
     expect(screen.queryByRole("button")).toBeNull();
   });
+
+  it("maps Sandbox inputs while keeping title, eyebrow and description separate", () => {
+    const { container } = render(<PageHeader title="Activity" titleAs="h3" eyebrow="Workspace" description="Recent events" action={<button type="button">Export</button>} />);
+    expect(screen.getByRole("heading", { level: 3 })).toHaveTextContent("Activity");
+    expect(screen.getAllByRole("heading")).toHaveLength(1);
+    expect(screen.getByText("Workspace").tagName).toBe("P");
+    expect(screen.getByRole("button", { name: "Export" })).toBeInTheDocument();
+    for (const attribute of ["action", "actions", "titleAs", "eyebrow", "level"]) {
+      expect(container.querySelector("header")).not.toHaveAttribute(attribute);
+    }
+  });
+
+  it("gives actions precedence without duplicating controls, including explicit null", () => {
+    const fallback = <button type="button">Legacy</button>;
+    const { rerender } = render(<PageHeader title="Activity" action={fallback} actions={<button type="button">Canonical</button>} />);
+    expect(screen.getByRole("button", { name: "Canonical" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Legacy" })).toBeNull();
+    rerender(<PageHeader title="Activity" action={fallback} actions={null} />);
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("lets titleAs override level's element but not its visual treatment", () => {
+    const { rerender } = render(<PageHeader title="Nested" level={2} />);
+    const classes = screen.getByRole("heading", { level: 2 }).className;
+    rerender(<PageHeader title="Nested" level={2} titleAs="h4" />);
+    expect(screen.getByRole("heading", { level: 4 }).className).toBe(classes);
+  });
+
+  it("preserves the header ref, native attributes and zero-valued metadata", () => {
+    const ref = createRef<HTMLElement>();
+    render(<PageHeader ref={ref} title="Activity" titleId="activity-title" id="masthead" aria-labelledby="activity-title" className="custom" meta={0} />);
+    expect(ref.current?.tagName).toBe("HEADER");
+    expect(ref.current).toHaveAttribute("id", "masthead");
+    expect(ref.current).toHaveAttribute("aria-labelledby", "activity-title");
+    expect(ref.current).toHaveClass("custom");
+    expect(screen.getByText("0")).toBeInTheDocument();
+  });
+
+  it("does not truncate long titles or put action labels inside the heading", () => {
+    const title = "A".repeat(180);
+    render(<PageHeader title={title} actions={<button type="button">Export the selected activity</button>} />);
+    const heading = screen.getByRole("heading", { name: title });
+    expect(heading).toHaveClass("[overflow-wrap:anywhere]");
+    expect(heading).not.toHaveClass("truncate");
+    expect(heading).not.toHaveTextContent("Export the selected activity");
+    expect(screen.getByRole("button").parentElement).toHaveClass("flex-wrap", "min-w-0", "max-w-full");
+  });
 });

package/src/primitives/page-header.tsx

@@ -1,39 +1,32 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
+import { Heading } from "./heading";
 
 /**
- * The one masthead every console page opens with.
- *
- * A page identifies itself in three separate registers, and each gets its own
- * slot here so they cannot compete for the same one:
- *
- *   - `title` — what the page IS. The `<h1>`, and the only `<h1>`.
- *   - `description` — one line on what it is for. Prose belongs here, never in
- *     the title slot: a paragraph rendered where a heading goes reads as body
- *     copy to a sighted reader and as nothing at all to a screen reader, which
- *     is how a page ends up with no accessible name.
- *   - `actions` — what the reader can DO from here, right-aligned and wrapping
- *     under the title on a narrow viewport rather than squeezing it.
- *
- * `meta` is the fourth register and the one most often missing: the small facts
- * that qualify everything below (a count, a scope, a window). They sit on their
- * own line under the title so a reader can tell the difference between "this
- * page has nothing in it" and "this filter matches nothing".
- *
- * `titleId` is exposed so a page can point `aria-labelledby` at the heading
- * from a region further down without minting a second copy of the string.
+ * A page masthead with separate title, prose, actions and qualifying metadata.
+ * Brand's existing props and header ref are preserved. Sandbox's existing
+ * action/eyebrow/titleAs inputs map into the same renderer, not a second header.
  */
 export interface PageHeaderProps
   extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
   title: React.ReactNode;
   description?: React.ReactNode;
+  /** Canonical action slot. If supplied (even null), takes precedence over action. */
   actions?: React.ReactNode;
   meta?: React.ReactNode;
   titleId?: string;
-  /** Renders the title one step down for a nested/tab surface. */
+  /** Existing nested-surface treatment: h2 and section typography. */
   level?: 1 | 2;
+  /** Existing Sandbox action slot; used only when actions is undefined. */
+  action?: React.ReactNode;
+  eyebrow?: React.ReactNode;
+  /** Existing Sandbox semantic override; takes precedence over level's tag only. */
+  titleAs?: React.ElementType;
 }
 
+// A numeric zero is useful metadata, not an absent slot.
+const hasContent = (node: React.ReactNode) => Boolean(node) || node === 0;
+
 const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
   (
     {
@@ -41,39 +34,46 @@ const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
       title,
       description,
       actions,
+      action,
+      eyebrow,
       meta,
       titleId,
+      titleAs,
       level = 1,
       ...props
     },
     ref,
   ) => {
-    const Heading = level === 1 ? "h1" : "h2";
+    const resolvedActions = actions === undefined ? action : actions;
     return (
-      <header ref={ref} className={cn("mb-6", className)} {...props}>
-        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-3">
-          <div className="min-w-0">
+      <header ref={ref} className={cn("mb-6 min-w-0", className)} {...props}>
+        <div className="flex min-w-0 flex-wrap items-start justify-between gap-x-6 gap-y-3">
+          <div className="min-w-0 flex-[1_1_16rem]">
+            {hasContent(eyebrow) && (
+              <Heading variant="eyebrow" className="mb-1.5">{eyebrow}</Heading>
+            )}
             <Heading
               id={titleId}
-              className={cn(
-                "text-balance font-semibold tracking-tight",
-                level === 1 ? "text-2xl" : "text-lg",
-              )}
+              variant={level === 1 ? "page" : "section"}
+              as={titleAs ?? (level === 1 ? "h1" : "h2")}
+              className="text-balance"
             >
               {title}
             </Heading>
-            {description && (
-              <p className="mt-1 max-w-prose text-muted-foreground text-sm">
+            {hasContent(description) && (
+              <p className="mt-1 max-w-prose text-muted-foreground text-sm [overflow-wrap:anywhere]">
                 {description}
               </p>
             )}
           </div>
-          {actions && (
-            <div className="flex flex-wrap items-center gap-2">{actions}</div>
+          {hasContent(resolvedActions) && (
+            <div className="flex min-w-0 max-w-full flex-wrap items-center gap-2 [overflow-wrap:anywhere] [&>*]:min-w-0 [&>*]:max-w-full">
+              {resolvedActions}
+            </div>
           )}
         </div>
-        {meta && (
-          <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs">
+        {hasContent(meta) && (
+          <div className="mt-3 flex min-w-0 flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs [overflow-wrap:anywhere]">
             {meta}
           </div>
         )}

package/src/primitives/page-shell.stories.tsx

@@ -0,0 +1,89 @@
+import { useId, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+import { Card, CardContent, CardFooter, CardHeader, CardTitle } from "./card";
+import { EmptyState } from "./empty-state";
+import { Input } from "./input";
+import { Metric, MetricStrip } from "./metric-strip";
+import { PageHeader } from "./page-header";
+import { PageShell } from "./page-shell";
+import { StatusPill } from "./status-pill";
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from "./table";
+import { Toolbar } from "./toolbar";
+
+type PageState = "empty" | "loading" | "error" | "populated";
+const items = [{ name: "Documentation build", status: "Complete" }, { name: "Package validation", status: "Complete" }];
+
+/** Local example data and real state transitions; no auth, routing or fetching in PageShell. */
+function ActivityPage({ state, fluid = false }: { state: PageState; fluid?: boolean }) {
+  const titleId = useId();
+  const searchId = useId();
+  const [recovered, setRecovered] = useState(false);
+  const [query, setQuery] = useState("");
+  const current = recovered ? "populated" : state;
+  const available = current === "populated" ? items : [];
+  const matching = available.filter((item) => item.name.toLowerCase().includes(query.toLowerCase()));
+  const known = current === "empty" || current === "populated";
+  const recover = () => { setQuery(""); setRecovered(true); };
+
+  return <main>
+    <PageShell className={fluid ? "mx-0 max-w-none" : undefined}>
+      <PageHeader
+        title="Workspace activity"
+        eyebrow="Example workspace"
+        description="Search the example activity or add example items. State is owned by this story, not the layout."
+        actions={<Button type="button" disabled={current === "loading"} onClick={recover}>Add example items</Button>}
+        meta={known ? <span>{matching.length} matching of {available.length} available items</span> : <span>Activity is not available yet</span>}
+      />
+      <MetricStrip>
+        <Metric label="Available" value={known ? available.length : "—"} />
+        <Metric label="Matching" value={known ? matching.length : "—"} />
+        <Metric label="Completed" value={known ? available.length : "—"} />
+        <Metric label="Failed" value={known ? 0 : "—"} />
+      </MetricStrip>
+      <section aria-labelledby={titleId}>
+        <Toolbar search={<Input id={searchId} label="Search activity" value={query} disabled={!known} onChange={(event) => setQuery(event.target.value)} placeholder="Search by name" />} />
+        <Card>
+          <CardHeader>
+            <CardTitle as="h2" id={titleId}>Activity items</CardTitle>
+          </CardHeader>
+          <CardContent aria-busy={current === "loading"}>
+            {current === "loading" ? <p role="status">Loading activity…</p> :
+              current === "error" ? <div className="space-y-3">
+                <p role="alert">Activity could not be loaded. The last request failed; retry to restore the example results.</p>
+                <Button type="button" onClick={recover}>Retry</Button>
+              </div> : matching.length === 0 ?
+                <EmptyState
+                  title={query ? "No matching activity" : "No activity yet"}
+                  description={query ? "Try a different search or clear the current filter." : "Add example items to see the populated table."}
+                  action={<Button type="button" onClick={query ? () => setQuery("") : recover}>{query ? "Clear search" : "Add example items"}</Button>}
+                /> :
+                <Table wrapper={false}>
+                  <TableCaption>Matching workspace activity</TableCaption>
+                  <TableHeader><TableRow><TableHead scope="col">Item</TableHead><TableHead scope="col">State</TableHead></TableRow></TableHeader>
+                  <TableBody>{matching.map((item) => <TableRow key={item.name}>
+                    <TableHead scope="row" className="[overflow-wrap:anywhere]">{item.name}</TableHead>
+                    <TableCell><StatusPill tone="success">{item.status}</StatusPill></TableCell>
+                  </TableRow>)}</TableBody>
+                </Table>}
+          </CardContent>
+          <CardFooter className="text-sm text-muted-foreground">{known ? "Example data. Use search to exercise the filtered empty state." : "Missing data is not reported as zero activity."}</CardFooter>
+        </Card>
+      </section>
+    </PageShell>
+  </main>;
+}
+
+const meta = {
+  title: "Primitives/PageShell",
+  component: PageShell,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof PageShell>;
+export default meta;
+type Story = StoryObj<typeof PageShell>;
+
+export const Populated: Story = { render: () => <ActivityPage state="populated" /> };
+export const Empty: Story = { render: () => <ActivityPage state="empty" /> };
+export const Loading: Story = { render: () => <ActivityPage state="loading" /> };
+export const Error: Story = { render: () => <ActivityPage state="error" /> };
+export const FluidWidth: Story = { render: () => <ActivityPage state="populated" fluid /> };

package/src/primitives/page-shell.test.tsx

@@ -0,0 +1,24 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { PageShell } from "./page-shell";
+
+describe("PageShell", () => {
+  it("ports Sandbox's width, gutters and rhythm without imposing a landmark or grid", () => {
+    const { container } = render(<PageShell><p>Content</p></PageShell>);
+    const shell = container.firstElementChild;
+    expect(shell?.tagName).toBe("DIV");
+    expect(shell).toHaveClass("mx-auto", "max-w-6xl", "space-y-8", "px-6", "py-8", "lg:px-8");
+    expect(shell).not.toHaveAttribute("role");
+    expect(shell).not.toHaveClass("grid");
+    expect(screen.queryByRole("main")).toBeNull();
+    expect(screen.getByText("Content")).toBeInTheDocument();
+  });
+
+  it("allows a caller-owned fluid layout without introducing shell behavior", () => {
+    const { container } = render(<main><PageShell className="mx-0 max-w-none px-0 lg:px-0"><p>Workbench</p></PageShell></main>);
+    const shell = container.querySelector("main > div");
+    expect(shell).toHaveClass("mx-0", "max-w-none", "px-0", "lg:px-0");
+    expect(shell).not.toHaveClass("mx-auto", "max-w-6xl", "px-6", "lg:px-8");
+    expect(screen.getAllByRole("main")).toHaveLength(1);
+  });
+});

package/src/primitives/page-shell.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/utils";
+
+export interface PageShellProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Ported from sandbox-ui/src/primitives/page-shell.tsx. An optional bounded
+ * width, gutter and vertical rhythm, not an application shell or a card grid.
+ * The caller owns landmarks, routing, auth, navigation and data state. Use
+ * className to override the bound/gutters, or omit it for a workbench layout.
+ */
+export function PageShell({ children, className }: PageShellProps) {
+  return (
+    <div
+      className={cn(
+        "mx-auto min-w-0 w-full max-w-6xl space-y-8 px-6 py-8 lg:px-8",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}