@graph8/sdk 0.358.0 → 0.362.0

package/blocks/_foundation/README.md

@@ -16,6 +16,8 @@ Shared base every other block depends on. Install it first (the CLI does it for
 | `components/confirm-spend-dialog.tsx` | `ConfirmSpendDialog`: shows tier, estimated credits, recipients, before a billable/external/destructive call. |
 | `components/api-error.tsx` | `ApiError`: shows `detail`, 422 field errors, request id, retry. |
 | `components/empty-state.tsx` | `EmptyState`: empty list with a first step. |
+| `components/screen/*.tsx` | The **screen kit** (below): `ScreenLayout`, `StatStrip`, `SplitView`, `DetailPanel`, `Toolbar`, `StatusPill`, `EntityAvatar`, `SectionCard`, `FormSheet`, `KeyValueList`, `Sparkline`, `BarList`, `TimeSeriesChart`. Barrel: `@/g8/components/screen`. |
+| `hooks/use-url-state.ts` | `useUrlState(key, default = "")` -> `[value, set]`. One string in the URL query as state (replaceState + popstate, SSR-safe). |
 
 ## Flow of every call
 
@@ -67,6 +69,112 @@ redirects (an upstream 3xx becomes a 502); caps the request body at 5 MiB (413),
 an oversized upload is never held whole in memory; returns 500 with a clear message if `G8_API_KEY` is unset
 and a generic 502 if graph8 is unreachable. The key is never logged, echoed or included in any response.
 
+## Screen kit
+
+Finished screens (`<Name>Screen` in every block) are composed from these parts, so an Apollo clone and a
+HubSpot clone look like one product. Import each part from `@/g8/components/screen/<file>` (or everything
+from `@/g8/components/screen`). The look follows graph8's rules: ink on white, calm density, colour only
+for meaning, no entrance animations, light and dark through the tokens.
+
+| Part | File | Use it for |
+|---|---|---|
+| `ScreenLayout` | `screen-layout` | The frame: sticky header (icon, title, description, actions, underline `tabs`), `stats`, `toolbar`, content. One per route. |
+| `StatStrip` | `stat-strip` | KPI tiles. `StatItem = { label, value, delta?, hint?, tone?, sparkline?, footer?, onClick? }`. Numbers are ink; a delta takes colour only through `tone`. |
+| `SplitView` | `split-view` | `list` beside the selected record (`detail`), `detailWidth` md, lg, xl. Under 1024px the detail is a right sheet. `expanded` + `onExpandedChange` make it a full-page record screen with a Back affordance. |
+| `DetailPanel` | `detail-panel` | The record: sticky header (avatar, title, subtitle, badges, actions, close) + `tabs: { id, label, content, count? }[]` or children. `onExpand` shows "Open full page"; `onCollapse` shows "Back to split view". |
+| `Toolbar` | `toolbar` | Debounced `search` (Enter flushes, Escape clears), `filters`, right-aligned `actions`, `status` (polite result count), a chips row as children. |
+| `StatusPill` | `status-pill` | `tone`: neutral, info, positive, warning, negative. `toneForStatus(raw)` maps API states; unknown is warning, never positive. `humanizeStatus`. |
+| `EntityAvatar` | `entity-avatar` | `kind` person (circle, initials) or company (rounded square, letter); `size` sm, md, lg; `imageUrl`. |
+| `SectionCard` | `section-card` | A flat, hairlined section: title, description, actions, body (`flush` for tables), footer. |
+| `FormSheet` | `form-sheet` | Create/edit sheet: `title`, `description`, fields as children, `footer` (Cancel, then the primary), `onSubmit` wraps the body in a form. |
+| `KeyValueList` | `key-value-list` | Facts about a record, `columns` 1 or 2, `inline` for dense rows. A missing value is a faint dash. |
+| `Sparkline` | `sparkline` | Tiny SVG trend for tiles and cells. `data: number[]`, optional `tone`. |
+| `BarList` | `bar-list` | Ranked rows with a proportional ink bar; `href` makes a row a link. |
+| `TimeSeriesChart` | `time-series-chart` | `data`, `xKey`, `series: { key, label?, tone? }[]`, `kind` line, area, bar. Needs the `recharts` peer. `tone: "prior"` is the dashed comparison. |
+| `useUrlState` | `hooks/use-url-state` | `const [id, setId] = useUrlState("id")`; `setId(null)` removes it; `{ push: true }` adds a history entry. |
+
+A finished list screen, start to end:
+
+```tsx
+"use client";
+import { Users, Plus } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { StatusPill, toneForStatus, humanizeStatus } from "@/g8/components/screen/status-pill";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+
+export function ContactsScreen() {
+  const [q, setQ] = useUrlState("q");
+  const [id, setId] = useUrlState("id");
+  const [creating, setCreating] = useUrlState("new");
+  const [view, setView] = useUrlState("view"); // "full" = the record as a full page (?id=X&view=full)
+  const contacts = useContacts(q); // your block's hook; { data, loading, error, refetch }
+  const open = contacts.data?.find((c) => c.id === id);
+
+  return (
+    <ScreenLayout
+      title="Contacts"
+      description="Everyone your team is working"
+      icon={<Users />}
+      stats={[{ label: "Contacts", value: contacts.total ?? "-" }, { label: "Replied this week", value: 12, delta: 8, tone: "positive" }]}
+      actions={<Button onClick={() => setCreating("1")}><Plus />Add contact</Button>}
+      toolbar={<Toolbar search={{ value: q, onChange: setQ, placeholder: "Search contacts" }} status={contacts.total != null ? `${contacts.total} contacts` : undefined} />}
+      fill
+    >
+      <SplitView
+        detailOpen={!!open}
+        onCloseDetail={() => { setId(null); setView(null); }}
+        expanded={view === "full"}
+        onExpandedChange={(full) => setView(full ? "full" : null)}
+        list={<ContactTable rows={contacts.data} selectedId={id} onOpen={(c) => setId(c.id)} />}
+        detail={open ? (
+          <DetailPanel
+            title={open.name}
+            subtitle={open.title}
+            avatar={<EntityAvatar name={open.name} imageUrl={open.avatar_url} size="lg" />}
+            badges={<StatusPill tone={toneForStatus(open.status)} dot>{humanizeStatus(open.status)}</StatusPill>}
+            onClose={() => { setId(null); setView(null); }}
+            onExpand={view === "full" ? undefined : () => setView("full")}
+            onCollapse={view === "full" ? () => setView(null) : undefined}
+            tabs={[
+              { id: "overview", label: "Overview", content: (
+                <SectionCard title="Details">
+                  <KeyValueList columns={2} items={[{ label: "Email", value: open.email }, { label: "Phone", value: open.phone }]} />
+                </SectionCard>
+              ) },
+              { id: "activity", label: "Activity", content: <ActivityFeed contactId={open.id} /> },
+            ]}
+          />
+        ) : null}
+      />
+      <FormSheet open={!!creating} onOpenChange={(o) => setCreating(o ? "1" : null)} title="Add contact" onSubmit={submit}
+        footer={<><Button variant="outline" type="button" onClick={() => setCreating(null)}>Cancel</Button><Button type="submit">Add contact</Button></>}>
+        {/* fields */}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}
+```
+
+Rules the kit encodes, so screens stay consistent:
+
+- The URL owns the open record, the tab and the search (`useUrlState`): reload and Back work, links are shareable.
+- Every record has a full-page view, not only a side panel: `?id=X&view=full` opens it (SplitView `expanded`), and
+  the panel's "Open full page" button gets there. Back returns to the split view with the list.
+- One primary action per screen, last on the right. Bulk actions appear on selection. Edits autosave where possible.
+- Colour means good or bad for the user: `tone` on deltas, pills and series; everything else is ink.
+- An unknown status is a warning pill with the humanized value, never a green "Active".
+- A failed load is `ApiError` with Retry, never an empty list; an empty list is `EmptyState` with the first step.
+- Loading is visible and distinct from empty: `StatStrip loading`, `Skeleton` rows.
+- Dates show short text; the full timestamp is the `title` of a `<time dateTime>`.
+
 ## Prerequisites
 
 - `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.

package/blocks/_foundation/block.json

@@ -3,7 +3,12 @@
   "id": "foundation",
   "title": "Foundation",
   "summary": "Shared base for every block: browser client, data hooks, Next.js proxy route, confirm/error/empty components.",
-  "features": ["browser-safe API calls via a server proxy", "query, mutation, pagination and job-polling hooks", "spend/send/delete confirmation dialog"],
+  "features": [
+    "browser-safe API calls via a server proxy",
+    "query, mutation, pagination and job-polling hooks",
+    "spend/send/delete confirmation dialog",
+    "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts"
+  ],
   "dependsOn": [],
   "operations": [],
   "components": [
@@ -27,20 +32,147 @@
       "purpose": "Empty-list placeholder with a title, hint and an optional first-step action.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "ScreenLayout",
+      "file": "components/screen/screen-layout.tsx",
+      "purpose": "Frame of a finished screen: sticky header (icon, title, description, actions, underline tabs), StatStrip, toolbar, content.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "StatStrip",
+      "file": "components/screen/stat-strip.tsx",
+      "purpose": "Row of KPI tiles: label, value, delta (coloured only through tone), hint tooltip, sparkline, skeleton while loading.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SplitView",
+      "file": "components/screen/split-view.tsx",
+      "purpose": "List beside the selected record; the detail pane becomes a right Sheet under 1024px.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "DetailPanel",
+      "file": "components/screen/detail-panel.tsx",
+      "purpose": "The selected record: sticky header (avatar, title, subtitle, badges, actions, close) and underline tabs or plain children.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "Toolbar",
+      "file": "components/screen/toolbar.tsx",
+      "purpose": "The row above a list: debounced search (Enter flushes, Escape clears), filters, right-aligned actions, an optional chips row.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "StatusPill",
+      "file": "components/screen/status-pill.tsx",
+      "purpose": "State badge with a tone (neutral, info, positive, warning, negative); toneForStatus maps raw API states, unknown ones to warning.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "EntityAvatar",
+      "file": "components/screen/entity-avatar.tsx",
+      "purpose": "Person (circle, initials) or company (rounded square, first letter) avatar in three sizes, with an image when there is one.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SectionCard",
+      "file": "components/screen/section-card.tsx",
+      "purpose": "Flat hairlined section with a title row (title, description, actions) and a body; cards cast no shadow.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "FormSheet",
+      "file": "components/screen/form-sheet.tsx",
+      "purpose": "Create/edit side sheet: header, scrolling fields, sticky footer; optional onSubmit wraps the body in a form.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "KeyValueList",
+      "file": "components/screen/key-value-list.tsx",
+      "purpose": "Labelled facts about a record in one or two columns; a missing value is a faint dash.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "Sparkline",
+      "file": "components/screen/sparkline.tsx",
+      "purpose": "Tiny inline SVG trend (ink line, 6% area) for stat tiles and cells; no chart library.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "BarList",
+      "file": "components/screen/bar-list.tsx",
+      "purpose": "Ranked rows with a proportional ink bar and a right-aligned value; rows can be links.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TimeSeriesChart",
+      "file": "components/screen/time-series-chart.tsx",
+      "purpose": "Line, area or bar chart over time on recharts: ink series, tones only for meaning, dashed prior period, hairline grid.",
+      "operations": [],
+      "tiers": []
     }
   ],
   "hooks": [
-    { "name": "useG8Query", "file": "hooks/use-g8-query.ts", "purpose": "Load data with loading/error/data, an out-of-order guard and refetch." },
-    { "name": "useG8Mutation", "file": "hooks/use-g8-mutation.ts", "purpose": "Run a write with loading/error state and success/error callbacks." },
-    { "name": "usePaginated", "file": "hooks/use-paginated.ts", "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload." },
-    { "name": "useJobPoll", "file": "hooks/use-job-poll.ts", "purpose": "Poll a job-status fetcher with backoff until a terminal state (the API has no streams)." }
+    {
+      "name": "useG8Query",
+      "file": "hooks/use-g8-query.ts",
+      "purpose": "Load data with loading/error/data, an out-of-order guard and refetch."
+    },
+    {
+      "name": "useG8Mutation",
+      "file": "hooks/use-g8-mutation.ts",
+      "purpose": "Run a write with loading/error state and success/error callbacks."
+    },
+    {
+      "name": "usePaginated",
+      "file": "hooks/use-paginated.ts",
+      "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload."
+    },
+    {
+      "name": "useJobPoll",
+      "file": "hooks/use-job-poll.ts",
+      "purpose": "Poll a job-status fetcher with backoff until a terminal state (the API has no streams)."
+    },
+    {
+      "name": "useUrlState",
+      "file": "hooks/use-url-state.ts",
+      "purpose": "One string in the URL query as state (replaceState + popstate, SSR-safe, no next/navigation): the open record, tab or search survives reload and Back."
+    }
   ],
   "lib": [
-    { "file": "lib/g8-client.ts", "purpose": "Browser caller for the app's own /api/g8 proxy. Holds no key, returns the SDK envelope, throws G8Error." }
+    {
+      "file": "lib/g8-client.ts",
+      "purpose": "Browser caller for the app's own /api/g8 proxy. Holds no key, returns the SDK envelope, throws G8Error."
+    },
+    {
+      "file": "components/screen/index.ts",
+      "purpose": "Barrel for the screen kit: import every part from @/g8/components/screen."
+    }
   ],
   "server": [
-    { "file": "server/proxy.ts", "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.", "target": "g8/server/proxy.ts" },
-    { "file": "server/route.ts", "purpose": "The Next.js App Router catch-all route that mounts the proxy.", "target": "app/api/g8/[...path]/route.ts" }
+    {
+      "file": "server/proxy.ts",
+      "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.",
+      "target": "g8/server/proxy.ts"
+    },
+    {
+      "file": "server/route.ts",
+      "purpose": "The Next.js App Router catch-all route that mounts the proxy.",
+      "target": "app/api/g8/[...path]/route.ts"
+    }
   ],
   "recipes": [
     {
@@ -71,9 +203,25 @@
   ],
   "scopes": [],
   "defaults": [
-    { "decision": "Which API paths the browser may call through the proxy", "default": "Only the areas the installed blocks use (allowedPrefixes, required), not all of /api/v1", "askHuman": false },
-    { "decision": "How the proxy knows the caller is a signed-in user of the app", "default": "None: the route refuses every request until `authorize` is set", "askHuman": true },
-    { "decision": "Styling", "default": "Tailwind utility classes on plain elements; overlays (ConfirmSpendDialog) and later blocks use @graph8/sdk/ui, so import its CSS", "askHuman": false }
+    {
+      "decision": "Which API paths the browser may call through the proxy",
+      "default": "Only the areas the installed blocks use (allowedPrefixes, required), not all of /api/v1",
+      "askHuman": false
+    },
+    {
+      "decision": "How the proxy knows the caller is a signed-in user of the app",
+      "default": "None: the route refuses every request until `authorize` is set",
+      "askHuman": true
+    },
+    {
+      "decision": "Styling",
+      "default": "Tailwind utility classes on plain elements; overlays (ConfirmSpendDialog) and later blocks use @graph8/sdk/ui, so import its CSS",
+      "askHuman": false
+    }
   ],
-  "peerDependencies": { "react": ">=18" }
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0",
+    "recharts": "^2.15.0 || ^3.0.0"
+  }
 }

package/blocks/_foundation/components/api-error.tsx

@@ -1,6 +1,8 @@
 "use client";
 
 import { G8Error } from "@graph8/sdk";
+import { CircleAlert } from "lucide-react";
+import { Button, cn } from "@graph8/sdk/ui";
 
 export interface ApiErrorProps {
   error: unknown;
@@ -8,6 +10,11 @@ export interface ApiErrorProps {
   /** Shows a Retry button. */
   onRetry?: () => void;
   className?: string;
+  /** One line with the reason and Retry inline, for toolbars and cards. */
+  compact?: boolean;
+  retryLabel?: string;
+  /** Extra actions beside Retry (open settings, contact support). */
+  actions?: React.ReactNode;
 }
 
 interface FieldError {
@@ -36,27 +43,64 @@ function explain(error: G8Error): string {
   return error.message;
 }
 
-/** Inline error panel for a failed graph8 call. Always shows `detail`, not just `message`. */
-export function ApiError({ error, title = "Something went wrong", onRetry, className }: ApiErrorProps) {
+/**
+ * Inline error panel for a failed graph8 call. Always shows `detail`, not just `message`. A failed load
+ * is an error with Retry, never an empty list. Ember is reserved for this: errors and alerts.
+ */
+export function ApiError({ error, title = "Something went wrong", onRetry, className, compact, retryLabel = "Retry", actions }: ApiErrorProps) {
   if (error == null) return null;
   const info = describeError(error);
+
+  if (compact) {
+    return (
+      <div role="alert" data-testid="api-error" className={cn("flex flex-wrap items-center gap-x-3 gap-y-1 rounded-md border border-error-foreground/20 bg-error px-3 py-2 text-sm text-error-foreground", className)}>
+        <CircleAlert className="size-4 shrink-0" strokeWidth={1.5} aria-hidden />
+        <span className="min-w-0 flex-1 truncate">
+          <span className="font-medium">{title}.</span> {info.message}
+        </span>
+        {actions}
+        {onRetry ? (
+          <Button type="button" size="sm" variant="outline" onClick={onRetry} className="h-7 border-error-foreground/30 bg-background text-error-foreground hover:bg-background/70 hover:text-error-foreground">
+            {retryLabel}
+          </Button>
+        ) : null}
+      </div>
+    );
+  }
+
   return (
-    <div role="alert" className={`rounded border border-red-200 bg-red-50 p-4 text-sm ${className ?? ""}`}>
-      <p className="font-medium text-red-900">{title}</p>
-      <p className="mt-1 text-red-800">{info.message}</p>
-      {info.fields.length > 0 ? (
-        <ul className="mt-2 list-disc pl-5 text-red-800">
-          {info.fields.map((line) => (
-            <li key={line}>{line}</li>
-          ))}
-        </ul>
-      ) : null}
-      {info.requestId ? <p className="mt-2 text-xs text-red-700">Request id: {info.requestId}</p> : null}
-      {onRetry ? (
-        <button type="button" onClick={onRetry} className="mt-3 rounded border border-red-300 bg-white px-3 py-1 text-red-900">
-          Retry
-        </button>
-      ) : null}
+    <div role="alert" data-testid="api-error" className={cn("flex gap-3 rounded-lg border border-error-foreground/20 bg-error p-4 text-sm text-error-foreground", className)}>
+      <div aria-hidden className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border border-error-foreground/20 bg-background/60">
+        <CircleAlert className="size-4" strokeWidth={1.5} />
+      </div>
+      <div className="min-w-0 flex-1">
+        <p className="font-medium leading-5">{title}</p>
+        <p className="mt-1 leading-5 text-error-foreground/90">{info.message}</p>
+        {info.fields.length > 0 ? (
+          <ul className="mt-2 list-disc space-y-0.5 pl-5 text-error-foreground/90">
+            {info.fields.map((line) => (
+              <li key={line}>{line}</li>
+            ))}
+          </ul>
+        ) : null}
+        {info.status != null || info.requestId ? (
+          <p className="mt-2 text-xs text-error-foreground/70 tabular-nums">
+            {info.status != null ? <span>HTTP {info.status}</span> : null}
+            {info.status != null && info.requestId ? <span aria-hidden> · </span> : null}
+            {info.requestId ? <span>Request id: {info.requestId}</span> : null}
+          </p>
+        ) : null}
+        {onRetry || actions ? (
+          <div className="mt-3 flex flex-wrap items-center gap-2">
+            {onRetry ? (
+              <Button type="button" size="sm" variant="outline" onClick={onRetry} className="border-error-foreground/30 bg-background text-error-foreground hover:bg-background/70 hover:text-error-foreground">
+                {retryLabel}
+              </Button>
+            ) : null}
+            {actions}
+          </div>
+        ) : null}
+      </div>
     </div>
   );
 }

package/blocks/_foundation/components/empty-state.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
 
 export interface EmptyStateProps {
   title: string;
@@ -9,16 +10,47 @@ export interface EmptyStateProps {
   action?: ReactNode;
   icon?: ReactNode;
   className?: string;
+  /** A second, quieter action (import, learn more). */
+  secondaryAction?: ReactNode;
+  /** Less vertical space, for panels and cards. */
+  compact?: boolean;
+  /** Draw a dashed boundary, so the empty area reads as a place where rows will appear. */
+  bordered?: boolean;
 }
 
-/** Shown when a list is empty. Say what will appear here and offer the first step. */
-export function EmptyState({ title, description, action, icon, className }: EmptyStateProps) {
+/**
+ * Shown when a list is empty. Say what will appear here and offer the first step. First-run copy
+ * ("No contacts yet. Import a CSV or add one.") differs from filtered-empty copy ("No contacts match
+ * these filters.", with a Clear filters action). An ink icon in a quiet well, one sentence, one action.
+ */
+export function EmptyState({ title, description, action, icon, className, secondaryAction, compact, bordered }: EmptyStateProps) {
   return (
-    <div className={`flex flex-col items-center justify-center gap-2 px-6 py-12 text-center ${className ?? ""}`}>
-      {icon ? <div className="text-gray-400">{icon}</div> : null}
-      <h3 className="text-sm font-semibold text-gray-900">{title}</h3>
-      {description ? <p className="max-w-sm text-sm text-gray-500">{description}</p> : null}
-      {action ? <div className="mt-2">{action}</div> : null}
+    <div
+      role="status"
+      data-testid="empty-state"
+      className={cn(
+        "flex flex-col items-center justify-center gap-2 px-6 text-center",
+        compact ? "py-8" : "py-14",
+        bordered && "rounded-lg border border-dashed border-border",
+        className,
+      )}
+    >
+      {icon ? (
+        <div
+          aria-hidden
+          className="mb-1 flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground [&_svg]:size-5 [&_svg]:stroke-[1.5]"
+        >
+          {icon}
+        </div>
+      ) : null}
+      <h3 className="text-sm font-medium text-foreground">{title}</h3>
+      {description ? <p className="max-w-sm text-sm leading-5 text-text-color-muted">{description}</p> : null}
+      {action || secondaryAction ? (
+        <div className="mt-2 flex flex-wrap items-center justify-center gap-2">
+          {secondaryAction}
+          {action}
+        </div>
+      ) : null}
     </div>
   );
 }

package/blocks/_foundation/components/screen/bar-list.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+/**
+ * BarList: ranked rows (top sources, top campaigns, stages) with a proportional ink bar behind each
+ * label and the value right-aligned. Rows with `href` are links. The first row carries the story in
+ * ink; the rest are an ink tint.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { TONE_CLASSES, type Tone } from "./status-pill";
+
+export interface BarListItem {
+  label: ReactNode;
+  value: number;
+  href?: string;
+  onClick?: () => void;
+  /** Colours this row's bar; only when the row means good or bad. */
+  tone?: Tone;
+  /** Text shown instead of the raw number ("42%", "1.2k"). */
+  display?: string;
+}
+
+export interface BarListProps {
+  items: BarListItem[];
+  /** Highest value to scale against; defaults to the largest item. */
+  max?: number;
+  /** Format a value for display when `display` is absent. */
+  formatValue?: (value: number) => string;
+  /** Emphasise the first row in full ink. Default true. */
+  emphasizeFirst?: boolean;
+  className?: string;
+}
+
+const defaultFormat = (v: number) => v.toLocaleString();
+
+export function BarList({ items, max, formatValue = defaultFormat, emphasizeFirst = true, className }: BarListProps) {
+  const top = max ?? Math.max(0, ...items.map((i) => i.value));
+  return (
+    <ol className={cn("flex flex-col gap-1.5", className)} data-testid="bar-list">
+      {items.map((item, i) => {
+        const pct = top > 0 ? Math.max(0, Math.min(100, (item.value / top) * 100)) : 0;
+        const bar = item.tone ? TONE_CLASSES[item.tone].bar + " opacity-30" : emphasizeFirst && i === 0 ? "bg-foreground/15" : "bg-foreground/[0.07]";
+        const inner = (
+          <>
+            <span aria-hidden className={cn("absolute inset-y-0 left-0 rounded-sm transition-[width]", bar)} style={{ width: `${pct}%` }} />
+            <span className="relative min-w-0 flex-1 truncate text-sm text-foreground">{item.label}</span>
+            <span className="relative shrink-0 pl-3 text-sm tabular-nums text-foreground">{item.display ?? formatValue(item.value)}</span>
+          </>
+        );
+        const cls = "relative flex h-7 w-full items-center overflow-hidden rounded-sm px-2 text-left";
+        return (
+          <li key={i} className="min-w-0">
+            {item.href ? (
+              <a href={item.href} className={cn(cls, "hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring")}>
+                {inner}
+              </a>
+            ) : item.onClick ? (
+              <button type="button" onClick={item.onClick} className={cn(cls, "hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring")}>
+                {inner}
+              </button>
+            ) : (
+              <div className={cls}>{inner}</div>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}