@graph8/sdk 0.361.0 → 0.370.0

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

@@ -1,6 +1,9 @@
 "use client";
 
-import { G8Error } from "@graph8/sdk";
+import { G8Error } from "@graph8/sdk/errors";
+import { CircleAlert } from "lucide-react";
+import { Button, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, useBrand } from "../hooks/use-brand";
 
 export interface ApiErrorProps {
   error: unknown;
@@ -8,6 +11,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 {
@@ -16,47 +24,85 @@ interface FieldError {
 }
 
 /** A readable one-line reason for any thrown value. 422 field errors are listed. */
-export function describeError(error: unknown): { message: string; fields: string[]; status?: number; requestId?: string } {
+export function describeError(error: unknown, platform: string = DEFAULT_BRAND.linkLabel): { message: string; fields: string[]; status?: number; requestId?: string } {
   if (error instanceof G8Error) {
     const fields = Array.isArray(error.detail)
       ? (error.detail as FieldError[]).map((f) => `${(f.loc ?? []).filter((p) => p !== "body").join(".")}: ${f.msg ?? ""}`.trim())
       : [];
     const message =
-      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error);
+      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error, platform);
     return { message, fields, status: error.status, requestId: error.requestId };
   }
   return { message: error instanceof Error ? error.message : "Something went wrong.", fields: [] };
 }
 
-function explain(error: G8Error): string {
-  if (error.status === 401) return "Your session with graph8 is not valid. Check the server API key.";
+function explain(error: G8Error, platform: string): string {
+  if (error.status === 401) return `Your session with ${platform} is not valid. Check the server API key.`;
   if (error.status === 403) return "This API key is not allowed to do that (missing scope, or the proxy blocked the path).";
-  if (error.status === 429) return "graph8 is rate limiting requests. Wait a moment and retry.";
+  if (error.status === 429) return `${platform} is rate limiting requests. Wait a moment and retry.`;
   if (error.status === 0) return "Could not reach the server. Check your connection.";
   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) {
+  const brand = useBrand();
   if (error == null) return null;
-  const info = describeError(error);
+  const info = describeError(error, brand.linkLabel);
+
+  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/brand-provider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Wraps the app so every block shows YOUR brand: the platform's name in copy and link-outs, and where those links
+ * go. A created app renders it in components/app-shell.tsx from `g8.config.ts`:
+ *
+ *   <BrandProvider brand={brand}>{children}</BrandProvider>
+ *
+ * Fields left out keep graph8's defaults (see hooks/use-brand.ts). No API calls.
+ */
+
+import { useMemo, type ReactNode } from "react";
+import { BrandContext, resolveBrand, type BrandConfig } from "../hooks/use-brand";
+
+export interface BrandProviderProps {
+  brand?: Partial<BrandConfig> | null;
+  children: ReactNode;
+}
+
+export function BrandProvider({ brand, children }: BrandProviderProps) {
+  const value = useMemo(() => resolveBrand(brand), [brand?.name, brand?.appUrl, brand?.linkLabel, brand?.logo]); // eslint-disable-line react-hooks/exhaustive-deps
+  return <BrandContext.Provider value={value}>{children}</BrandContext.Provider>;
+}

package/blocks/_foundation/components/confirmed-action.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * useConfirmAction + AskButton (foundation, shared by every block's record detail): the pattern detail screens use for every write. A button calls `ask(config)`; the screen
+ * renders ONE `<ConfirmSpendDialog {...dialog} />` (so the confirmation is visible in the screen's own source), the person confirms,
+ * then `config.run()` executes and the failure, if any, is shown in `failure`.
+ *
+ * SDK operations: none of its own; `run` is whatever the caller passes. `tolerateStatus` lists HTTP statuses that count as done
+ * (a delete answering 404); `mapError` can turn a thrown error into a clearer one (return null to treat it as done).
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+
+export interface ConfirmActionConfig {
+  tier: ConfirmTier;
+  title: string;
+  description?: ReactNode;
+  confirmLabel?: string;
+  estimatedCredits?: number;
+  recipients?: number;
+  affected?: number;
+  tolerateStatus?: number[];
+  mapError?: (error: unknown) => unknown;
+  run: () => Promise<unknown>;
+  onDone?: () => void;
+}
+
+export interface AskButtonProps extends ConfirmActionConfig {
+  ask: (config: ConfirmActionConfig) => void;
+  label: string;
+  variant?: "default" | "outline" | "ghost";
+  disabled?: boolean;
+}
+
+export function useConfirmAction() {
+  const [cfg, setCfg] = useState<ConfirmActionConfig | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<unknown>(null);
+
+  const go = async () => {
+    if (!cfg) return;
+    setBusy(true);
+    setFailure(null);
+    try {
+      await cfg.run();
+      cfg.onDone?.();
+    } catch (err) {
+      const status = (err as { status?: number })?.status;
+      if (status != null && cfg.tolerateStatus?.includes(status)) cfg.onDone?.();
+      else {
+        const shown = cfg.mapError ? cfg.mapError(err) : err;
+        if (shown == null) cfg.onDone?.();
+        else setFailure(shown);
+      }
+    } finally {
+      setBusy(false);
+      setCfg(null);
+    }
+  };
+
+  return {
+    ask: (config: ConfirmActionConfig) => setCfg(config),
+    busy,
+    failure,
+    dialog: {
+      open: cfg != null,
+      tier: cfg?.tier ?? ("external" as ConfirmTier),
+      title: cfg?.title ?? "",
+      description: cfg?.description,
+      estimatedCredits: cfg?.estimatedCredits,
+      recipients: cfg?.recipients,
+      affected: cfg?.affected,
+      confirmLabel: cfg?.confirmLabel,
+      confirming: busy,
+      onConfirm: () => void go(),
+      // While the write is running, Cancel does nothing: closing then would hide a write that still lands.
+      onCancel: () => { if (!busy) setCfg(null); },
+    },
+  };
+}
+
+export function AskButton({ ask, label, variant = "outline", disabled, ...config }: AskButtonProps) {
+  return (
+    <Button size="sm" variant={variant} disabled={disabled} onClick={() => ask({ confirmLabel: label, ...config })}>
+      {label}
+    </Button>
+  );
+}

package/blocks/_foundation/components/connect-graph8.tsx

@@ -0,0 +1,280 @@
+"use client";
+
+/**
+ * Connect graph8 (local preview only): the first-run screen of a created app when the server has no graph8 API
+ * key yet, and the place to replace or remove the key later.
+ *
+ * Calls this app's own `/api/g8-connect` route (g8/server/connect.ts), never graph8 directly:
+ *   GET    status: is a key configured, where from (server environment or the pasted file), whose is it
+ *   POST   { key }: the server checks the key with a free read (GET /me), then stores it in .g8/local-key
+ *   DELETE remove the stored key
+ * No billable, external or destructive graph8 operation (removing the local file only forgets the key here).
+ * The key goes from the input to the server once and is never kept in browser state after submit, storage or URL.
+ *
+ * Exports:
+ *   - ConnectGraph8Panel: the full-page panel (no required props).
+ *   - G8ConnectGate: wraps the app; in `next dev` it shows the screen until a key is connected, plus a small
+ *     "Local preview" button to manage the key. In a production build it renders its children and nothing else.
+ */
+
+import { useCallback, useEffect, useId, useState, type FormEvent, type ReactNode } from "react";
+import { CheckCircle2, ExternalLink, KeyRound, Loader2, X } from "lucide-react";
+import { Button, Input, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, brandUrl, useBrand } from "../hooks/use-brand";
+
+export const CONNECT_PATH = "/api/g8-connect";
+/** Where API keys are managed, on the platform's web app (white-label: see hooks/use-brand). */
+const KEYS_PATH = "/studio/settings?tab=api";
+
+export interface ConnectStatus {
+  localPreview: boolean;
+  connected: boolean;
+  source: "env" | "file" | null;
+  keyHint?: string;
+  keyFile?: string;
+  account?: { name?: string; workspace?: string; scopes?: string[] };
+  problem?: string;
+}
+
+async function readJson(res: Response): Promise<Record<string, unknown>> {
+  return (await res.json().catch(() => ({}))) as Record<string, unknown>;
+}
+
+/** GET the status. Null when the route does not exist or refuses (production, not this machine). */
+export async function fetchConnectStatus(): Promise<ConnectStatus | null> {
+  try {
+    const res = await fetch(CONNECT_PATH, { headers: { accept: "application/json" }, cache: "no-store" });
+    if (!res.ok) return null;
+    const body = await readJson(res);
+    return body.localPreview === true ? (body as unknown as ConnectStatus) : null;
+  } catch {
+    return null;
+  }
+}
+
+function accountLine(s: ConnectStatus, platform = DEFAULT_BRAND.linkLabel): string {
+  const a = s.account ?? {};
+  return [a.name, a.workspace].filter(Boolean).join(" at ") || `a ${platform} key`;
+}
+
+export interface ConnectGraph8PanelProps {
+  /** Status from a previous GET (the gate passes it); fetched on mount when absent. */
+  status?: ConnectStatus | null;
+  /** Called after a key is stored or removed, with the new status. */
+  onChange?: (status: ConnectStatus) => void;
+  className?: string;
+}
+
+/** Paste, check and store the server's graph8 API key; replace or remove it. */
+export function ConnectGraph8Panel({ status: initial, onChange, className }: ConnectGraph8PanelProps) {
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(initial);
+  const [key, setKey] = useState("");
+  const [busy, setBusy] = useState<"save" | "remove" | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [replacing, setReplacing] = useState(false);
+  const inputId = useId();
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (initial === undefined) void fetchConnectStatus().then(setStatus);
+  }, [initial]);
+
+  const apply = (next: ConnectStatus) => {
+    setStatus(next);
+    setReplacing(false);
+    onChange?.(next);
+  };
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!key.trim() || busy) return;
+    setBusy("save");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ key: key.trim() }) });
+      const body = await readJson(res);
+      setKey("");
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not save the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const remove = async () => {
+    setBusy("remove");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "DELETE" });
+      const body = await readJson(res);
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not remove the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const connected = Boolean(status?.connected);
+  const fromEnv = status?.source === "env";
+  const showForm = !fromEnv && (!status?.source || replacing);
+
+  return (
+    <section aria-labelledby={`${inputId}-title`} className={cn("mx-auto flex w-full max-w-md flex-col gap-5 px-4 py-14", className)}>
+      <div className="flex flex-col gap-2">
+        <div aria-hidden className="flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground">
+          <KeyRound className="size-5" strokeWidth={1.5} />
+        </div>
+        <h1 id={`${inputId}-title`} className="text-lg font-medium text-foreground">
+          {connected ? `Connected to ${brand.linkLabel}` : `Connect ${brand.linkLabel}`}
+        </h1>
+        <p className="text-sm leading-5 text-text-color-muted">
+          This app reads and writes your {brand.linkLabel} data through its own server. Paste an API key once: the server checks
+          it and keeps it in <code className="text-xs">{status?.keyFile ?? ".g8/local-key"}</code> on this computer. The
+          browser never stores it.
+        </p>
+      </div>
+
+      {status?.source ? (
+        <div className="flex items-start gap-3 rounded-lg border border-border p-3 text-sm">
+          {connected ? (
+            <CheckCircle2 aria-hidden className="mt-0.5 size-4 shrink-0 text-positive-foreground" strokeWidth={1.5} />
+          ) : (
+            <X aria-hidden className="mt-0.5 size-4 shrink-0 text-error-foreground" strokeWidth={1.5} />
+          )}
+          <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+            <span className="text-foreground">{connected ? accountLine(status, brand.linkLabel) : "The key no longer works"}</span>
+            <span className="text-xs text-text-color-muted">
+              Key {status.keyHint ?? ""} from {fromEnv ? "the server environment (.env.local)" : status.keyFile ?? ".g8/local-key"}
+              {status.problem ? `. ${status.problem}` : ""}
+            </span>
+            {fromEnv ? <span className="text-xs text-text-color-muted">To change it, edit .env.local and restart the dev server.</span> : null}
+          </div>
+        </div>
+      ) : null}
+
+      {showForm ? (
+        <form onSubmit={submit} className="flex flex-col gap-2">
+          <label htmlFor={inputId} className="text-sm font-medium text-foreground">
+            {brand.linkLabel} API key
+          </label>
+          <Input
+            id={inputId}
+            type="password"
+            autoComplete="off"
+            spellCheck={false}
+            value={key}
+            onChange={(e) => setKey(e.target.value)}
+            placeholder="Paste the key"
+            aria-invalid={error ? true : undefined}
+            aria-describedby={error ? `${inputId}-error` : undefined}
+          />
+          {error ? (
+            <p id={`${inputId}-error`} role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+          <div className="flex items-center gap-2 pt-1">
+            <Button type="submit" disabled={!key.trim() || busy !== null}>
+              {busy === "save" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              {busy === "save" ? "Checking" : "Connect"}
+            </Button>
+            {replacing ? (
+              <Button type="button" variant="ghost" onClick={() => setReplacing(false)}>
+                Cancel
+              </Button>
+            ) : null}
+          </div>
+        </form>
+      ) : status?.source === "file" ? (
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="outline" onClick={() => setReplacing(true)} disabled={busy !== null}>
+              Replace key
+            </Button>
+            <Button type="button" variant="ghost" onClick={() => void remove()} disabled={busy !== null}>
+              {busy === "remove" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              Remove key
+            </Button>
+          </div>
+          {error ? (
+            <p role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
+      <a href={brandUrl(brand, KEYS_PATH)} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 text-sm text-foreground underline-offset-4 hover:underline">
+        Get a key in {brand.linkLabel} (Settings, API)
+        <ExternalLink aria-hidden className="size-3.5" strokeWidth={1.5} />
+      </a>
+      <p className="text-xs leading-5 text-text-color-muted">
+        Local preview: this screen and the data routes only answer requests from this computer while you run the dev
+        server. Before you deploy, set <code>authorize</code> in app/api/g8/[...path]/route.ts and the key in your host&apos;s
+        environment; <code>npx @graph8/sdk doctor --production</code> checks both.
+      </p>
+    </section>
+  );
+}
+
+export interface G8ConnectGateProps {
+  children: ReactNode;
+  /** Hide the small "Local preview" button once connected. Default false. */
+  hideManageButton?: boolean;
+}
+
+/**
+ * In `next dev`: shows ConnectGraph8Panel instead of the app until a key is connected, and a small button to
+ * manage the key afterwards. In a production build (and when /api/g8-connect is missing or refuses) it is
+ * exactly its children: no request, no extra markup.
+ */
+export function G8ConnectGate({ children, hideManageButton = false }: G8ConnectGateProps) {
+  const dev = process.env.NODE_ENV !== "production";
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(dev ? undefined : null);
+  const [managing, setManaging] = useState(false);
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (dev) void fetchConnectStatus().then(setStatus);
+  }, [dev]);
+
+  const changed = useCallback((next: ConnectStatus) => {
+    setStatus(next);
+    // Every screen loaded its data with the old (or no) key: start them again.
+    if (next.connected) window.location.reload();
+  }, []);
+
+  if (!status) return <>{children}</>;
+  if (!status.connected || managing) {
+    return (
+      <div className="relative">
+        {managing && status.connected ? (
+          <Button type="button" variant="ghost" size="sm" className="absolute right-4 top-4" onClick={() => setManaging(false)}>
+            Back to the app
+          </Button>
+        ) : null}
+        <ConnectGraph8Panel status={status} onChange={changed} />
+      </div>
+    );
+  }
+  return (
+    <>
+      {children}
+      {hideManageButton ? null : (
+        <button
+          type="button"
+          onClick={() => setManaging(true)}
+          title={`Local preview, connected as ${accountLine(status, brand.linkLabel)}. Manage the ${brand.linkLabel} key.`}
+          className="fixed bottom-3 right-3 z-40 inline-flex h-7 items-center gap-1.5 rounded-md border border-border bg-background px-2 text-xs text-text-color-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <KeyRound aria-hidden className="size-3.5" strokeWidth={1.5} />
+          Local preview
+        </button>
+      )}
+    </>
+  );
+}

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>
+  );
+}