@calliopelabs/ui 0.7.0 → 0.12.0

package/dist/theme/css-layer.js

@@ -0,0 +1,171 @@
+import { BOOT_SOURCE, bootConfig } from "../appearance/boot.js";
+import { astroliftBrand, chatStudioBrand, cykickBrand, loadrBrand, workbenchBrand, zentinelleBrand, } from "../appearance/brands.js";
+import { CORNERS, defineProduct } from "../appearance/product.js";
+import { accentDeclarations, block, renderThemeCss } from "./css.js";
+/**
+ * The CSS layer: the same tokens and the same boot script, for pages that
+ * cannot render React (Django, Jinja, HTMX, Rails, Laravel, Phoenix). Both
+ * files are generated here from the token table and the boot source by
+ * `npm run theme`, and shipped as `@calliopelabs/ui/css/*`.
+ */
+/** The products the CSS layer knows by name (`data-product`): the family's brands. */
+export const CSS_LAYER_PRODUCTS = [
+    astroliftBrand,
+    zentinelleBrand,
+    workbenchBrand,
+    chatStudioBrand,
+    loadrBrand,
+    cykickBrand,
+].map((config) => defineProduct(config));
+const TOKENS_HEADER = `/*
+ * @calliopelabs/ui CSS layer: tokens.
+ * Generated by \`npm run theme\` from src/theme/tokens.ts and the product
+ * brands. Do not edit by hand.
+ *
+ * The same values as the Tailwind preset (theme.css plus each product's brand
+ * tokens), for pages without React or Tailwind. Every axis is an attribute,
+ * on <html> or on any subtree:
+ *   data-product  the brand: its sidebar and its own accent
+ *   data-mode     dark | light (follows the ground)
+ *   data-ground   the surface ramp
+ *   data-accent   a family accent or the product's own; "custom" with an inline --brand-primary
+ *   data-density  compact | cards
+ *   data-corners  0 | 2 | 4 | 10 (appearance.js sets --radius inline instead)
+ * appearance.js stamps all of them before first paint, or a server that
+ * keeps the preference renders them itself.
+ */`;
+/** The whole of css/tokens.css. */
+export function renderTokensCss() {
+    const theme = renderThemeCss().replace(/^\/\*[\s\S]*?\*\/\n\n/, "");
+    const blocks = [TOKENS_HEADER, theme.trimEnd()];
+    for (const corners of CORNERS) {
+        blocks.push(block(`[data-corners="${corners}"]`, [["--radius", `${corners}px`]], `Corners: ${corners}px`));
+    }
+    for (const product of CSS_LAYER_PRODUCTS) {
+        blocks.push(block(`[data-product="${product.id}"]`, [["--brand-sidebar", product.sidebar]], `Product: ${product.name}`));
+        const accent = product.brandAccent;
+        if (!accent)
+            continue;
+        for (const mode of ["dark", "light"]) {
+            blocks.push(block(`[data-mode="${mode}"][data-accent="${accent.key}"]`, accentDeclarations(mode, accent), `Accent: ${accent.label} (${product.name}, ${mode})`));
+        }
+    }
+    return `${blocks.join("\n\n")}\n`;
+}
+/** JSON that is still safe when the file is pasted into an inline <script>. */
+function scriptJson(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+/**
+ * The whole of css/appearance.js: the boot script AppearanceScript renders
+ * (the same source text), the boot configs of the built-in products, and a
+ * small API over them. `set` stores the merged preference and runs the boot
+ * script again, so first paint and every later change resolve through one
+ * code path. Plain ES5, like the boot script.
+ */
+export function renderAppearanceJs() {
+    const products = Object.fromEntries(CSS_LAYER_PRODUCTS.map((p) => [p.id, bootConfig(p)]));
+    return `/*
+ * @calliopelabs/ui CSS layer: appearance.
+ * Generated by \`npm run theme\` from src/appearance/boot.ts. Do not edit by hand.
+ *
+ * Load it in <head>, before the stylesheets, as a plain script element
+ * (no async, no defer) with the product on it, so it runs before first
+ * paint: src=".../appearance.js" data-product="astrolift".
+ *
+ * It stamps the person's ground, accent, density and corners on <html> from
+ * localStorage, exactly as AppearanceScript does, and leaves an API on
+ * window.CalliopeAppearance:
+ *   get()            the appearance on <html> now
+ *   set(partial)     store and apply { ground, accent, density, corners }
+ *   reset()          forget the choice; the product's defaults apply
+ *   boot(config)     use another product's boot config
+ *   config           the active product's grounds, accents and corners
+ *   products         the built-in products' boot configs, by id
+ * Every change dispatches "calliope:appearance" on document.
+ */
+(function () {
+  var boot = ${BOOT_SOURCE};
+  var products = ${scriptJson(products)};
+  var d = document.documentElement;
+  var hex = /^#[0-9a-f]{6}$/;
+  var has = function (o, k) {
+    return typeof k === "string" && Object.prototype.hasOwnProperty.call(o, k);
+  };
+  var stored = function (c) {
+    try {
+      var parsed = JSON.parse(window.localStorage.getItem(c.key) || "null");
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch (e) {
+      return {};
+    }
+  };
+  /* normalizePartial: only the axes that are valid for this product. A locked accent (22:1) takes no custom colour. */
+  var valid = function (c, v) {
+    var out = {};
+    if (has(c.grounds, v.ground)) out.ground = v.ground;
+    if (c.accents.indexOf(v.accent) > -1 || (hex.test(v.accent) && c.minContrast <= 21))
+      out.accent = v.accent;
+    if (v.density === "compact" || v.density === "cards") out.density = v.density;
+    if (c.corners.indexOf(v.corners) > -1) out.corners = v.corners;
+    return out;
+  };
+  var api = {
+    products: products,
+    config: null,
+    get: function () {
+      var custom = d.getAttribute("data-accent") === "custom";
+      return {
+        ground: d.getAttribute("data-ground"),
+        mode: d.getAttribute("data-mode"),
+        accent: custom ? d.style.getPropertyValue("--brand-primary") : d.getAttribute("data-accent"),
+        density: d.getAttribute("data-density"),
+        corners: parseInt(d.style.getPropertyValue("--radius"), 10)
+      };
+    },
+    set: function (next) {
+      var c = api.config;
+      if (!c || !next) return;
+      var merged = stored(c);
+      for (var k in next) if (has(next, k)) merged[k] = next[k];
+      if (typeof merged.accent === "string") merged.accent = merged.accent.toLowerCase();
+      try {
+        window.localStorage.setItem(c.key, JSON.stringify(valid(c, merged)));
+      } catch (e) {}
+      apply();
+    },
+    reset: function () {
+      if (!api.config) return;
+      try {
+        window.localStorage.removeItem(api.config.key);
+      } catch (e) {}
+      apply();
+    },
+    boot: function (config) {
+      api.config = config;
+      apply();
+    }
+  };
+  var apply = function () {
+    /* A custom accent is inline; a family accent comes from the stylesheet. */
+    d.style.removeProperty("--brand-primary");
+    d.style.removeProperty("--brand-on-primary");
+    try {
+      boot(api.config);
+    } catch (e) {}
+    var event;
+    try {
+      event = new CustomEvent("calliope:appearance", { detail: api.get() });
+    } catch (e) {
+      event = document.createEvent("CustomEvent");
+      event.initCustomEvent("calliope:appearance", false, false, api.get());
+    }
+    document.dispatchEvent(event);
+  };
+  window.CalliopeAppearance = api;
+  var me = document.currentScript;
+  var id = me && me.getAttribute("data-product");
+  if (has(products, id)) api.boot(products[id]);
+})();
+`;
+}

package/dist/theme/css.d.ts

@@ -1,5 +1,6 @@
 import { type Mode } from "./tokens.js";
 type Declarations = readonly (readonly [property: string, value: string])[];
+export declare function block(selector: string, declarations: Declarations, comment?: string): string;
 /** The accent tokens one accent paints in one mode. */
 export declare function accentDeclarations(mode: Mode, accent: {
     dark: string;

package/dist/theme/css.js

@@ -1,11 +1,51 @@
 import { ACCENTS, ACCENT_KEYS, BASE_SURFACES, DEFAULT_ACCENT, DENSITIES, GROUNDS, GROUND_KEYS, MODE_TOKENS, STATIC_TOKENS, SURFACES, } from "./tokens.js";
 const STATUS_NAMES = ["success", "warning", "info", "danger"];
-function block(selector, declarations, comment) {
+export function block(selector, declarations, comment) {
     const head = comment ? `/* ${comment} */\n` : "";
     const body = declarations.map(([property, value]) => `  ${property}: ${value};`).join("\n");
     return `${head}${selector} {\n${body}\n}`;
 }
-function surfaceDeclarations(s) {
+/**
+ * The sidebar of one ground. A runtime brand (`brandStyles`) reaches it only
+ * through `--brand-sidebar-*` variables, each with the ground's own value as
+ * the fallback, so a page without a brand paints exactly the token table:
+ *   dark brand grounds   --brand-sidebar, its foreground, secondary text and marker
+ *   light grounds        --brand-sidebar-light (opt-in), with its foreground,
+ *                        secondary text, marker, hover tint and hairline
+ *   graphite             neutral whatever the brand (Astrolift #2286)
+ */
+function sidebarDeclarations(s, mode) {
+    const foreground = MODE_TOKENS[mode].sidebarForeground;
+    if (s.sidebar === "brand") {
+        return [
+            ["--sidebar", `var(--brand-sidebar, ${s.card})`],
+            ["--sidebar-foreground", `var(--brand-sidebar-foreground, ${foreground})`],
+            ["--sidebar-primary", "var(--brand-sidebar-primary, var(--brand-primary))"],
+            ["--sidebar-muted-foreground", `var(--brand-sidebar-muted-foreground, ${s.mutedForeground})`],
+            ["--sidebar-accent", s.sidebarAccent],
+            ["--sidebar-border", s.sidebarBorder],
+        ];
+    }
+    if (mode === "light") {
+        return [
+            ["--sidebar", `var(--brand-sidebar-light, ${s.sidebar})`],
+            ["--sidebar-foreground", `var(--brand-sidebar-foreground, ${foreground})`],
+            ["--sidebar-primary", "var(--brand-sidebar-primary, var(--brand-primary))"],
+            ["--sidebar-muted-foreground", `var(--brand-sidebar-muted-foreground, ${s.mutedForeground})`],
+            ["--sidebar-accent", `var(--brand-sidebar-accent, ${s.sidebarAccent})`],
+            ["--sidebar-border", `var(--brand-sidebar-border, ${s.sidebarBorder})`],
+        ];
+    }
+    return [
+        ["--sidebar", s.sidebar],
+        ["--sidebar-foreground", foreground],
+        ["--sidebar-primary", "var(--brand-primary)"],
+        ["--sidebar-muted-foreground", s.mutedForeground],
+        ["--sidebar-accent", s.sidebarAccent],
+        ["--sidebar-border", s.sidebarBorder],
+    ];
+}
+function surfaceDeclarations(s, mode) {
     return [
         ["--background", s.background],
         ["--card", s.card],
@@ -16,9 +56,7 @@ function surfaceDeclarations(s) {
         ["--muted-foreground", s.mutedForeground],
         ["--border", s.border],
         ["--input", s.input],
-        ["--sidebar", s.sidebar === "brand" ? `var(--brand-sidebar, ${s.card})` : s.sidebar],
-        ["--sidebar-accent", s.sidebarAccent],
-        ["--sidebar-border", s.sidebarBorder],
+        ...sidebarDeclarations(s, mode),
     ];
 }
 function modeDeclarations(mode) {
@@ -26,7 +64,7 @@ function modeDeclarations(mode) {
     const accent = ACCENTS[DEFAULT_ACCENT];
     return [
         ["color-scheme", mode],
-        ...surfaceDeclarations(BASE_SURFACES[mode]),
+        ...surfaceDeclarations(BASE_SURFACES[mode], mode),
         ["--foreground", m.foreground],
         ["--card-foreground", m.foreground],
         ["--popover-foreground", m.foreground],
@@ -40,8 +78,6 @@ function modeDeclarations(mode) {
         ["--ring", "var(--brand-primary)"],
         ["--chart-1", "var(--brand-primary)"],
         ...Object.entries(m.chart).map(([key, value]) => [`--${key}`, value]),
-        ["--sidebar-foreground", m.sidebarForeground],
-        ["--sidebar-primary", "var(--brand-primary)"],
         ["--sidebar-primary-foreground", "var(--brand-on-primary)"],
         ["--sidebar-accent-foreground", m.foreground],
         ["--sidebar-ring", "var(--brand-primary)"],
@@ -89,7 +125,7 @@ export function renderThemeCss() {
     blocks.push(block('[data-mode="light"]', modeDeclarations("light"), "Light: neutral ground, green accent"));
     for (const ground of GROUND_KEYS) {
         const { mode, label } = GROUNDS[ground];
-        blocks.push(block(`[data-mode="${mode}"][data-ground="${ground}"]`, surfaceDeclarations(SURFACES[ground]), `Ground: ${label} (${mode})`));
+        blocks.push(block(`[data-mode="${mode}"][data-ground="${ground}"]`, surfaceDeclarations(SURFACES[ground], mode), `Ground: ${label} (${mode})`));
     }
     for (const key of ACCENT_KEYS) {
         const accent = ACCENTS[key];

package/dist/workflow/ArtifactCard.d.ts

@@ -0,0 +1,47 @@
+import * as React from "react";
+import { type Artifact } from "./run.js";
+export interface ArtifactCardProps {
+    artifact: Artifact;
+    /**
+     * The host's view of the artifact: a thumbnail, a player, or one of the
+     * module review viewers. Rendered as given, so it can be interactive.
+     */
+    preview?: React.ReactNode;
+    /** Opens the artifact: the name becomes a link through the app's link component. */
+    href?: string;
+    /** Opens or selects the artifact without a route: the name becomes a button. Ignored with `href`. */
+    onOpen?: () => void;
+    /** Marks the artifact the host is showing beside the list. */
+    selected?: boolean;
+    /** The host's own controls (download, compare). */
+    actions?: React.ReactNode;
+    headingLevel?: "h2" | "h3" | "h4";
+    className?: string;
+}
+/**
+ * One typed output of a run: its type, name, status, size, version and the
+ * stage that made it, with a slot for the host's preview or a module viewer.
+ * Knows nothing of any module; the host decides what a kind looks like.
+ */
+export declare function ArtifactCard({ artifact, preview, href, onOpen, selected, actions, headingLevel, className, }: ArtifactCardProps): React.JSX.Element;
+export interface ArtifactListProps {
+    artifacts: readonly Artifact[];
+    /** Names the list. Defaults to "Artifacts". */
+    label?: string;
+    /** The preview or viewer for each artifact. */
+    renderPreview?: (artifact: Artifact) => React.ReactNode;
+    /** How each artifact opens: a route, a handler, the host's controls. */
+    actionsFor?: (artifact: Artifact) => Pick<ArtifactCardProps, "href" | "onOpen" | "actions">;
+    selectedId?: string;
+    /** One column, for a side panel; the default flows into columns as the width allows. */
+    columns?: "auto" | "one";
+    loading?: boolean;
+    error?: {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    headingLevel?: ArtifactCardProps["headingLevel"];
+    className?: string;
+}
+/** A run's artifacts as cards, with loading, error and empty states. */
+export declare function ArtifactList({ artifacts, label, renderPreview, actionsFor, selectedId, columns, loading, error, onRetry, headingLevel, className, }: ArtifactListProps): React.JSX.Element;

package/dist/workflow/ArtifactCard.js

@@ -0,0 +1,45 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { ErrorState } from "../states/ErrorState.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+import { ARTIFACT_TONE } from "./run.js";
+import { WorkflowCardSkeleton } from "./WorkflowCard.js";
+/**
+ * One typed output of a run: its type, name, status, size, version and the
+ * stage that made it, with a slot for the host's preview or a module viewer.
+ * Knows nothing of any module; the host decides what a kind looks like.
+ */
+export function ArtifactCard({ artifact, preview, href, onOpen, selected = false, actions, headingLevel = "h3", className, }) {
+    const { Link, messages } = useUI();
+    const t = messages.run;
+    const titleId = React.useId();
+    const Heading = headingLevel;
+    const meta = [
+        artifact.size,
+        artifact.version && t.version(artifact.version),
+        artifact.producedBy && t.producedBy(artifact.producedBy),
+    ].filter(Boolean);
+    const nameClass = "rounded-sm text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring";
+    return (_jsxs("article", { "aria-labelledby": titleId, "data-slot": "artifact-card", "data-kind": artifact.kind, "data-selected": selected || undefined, className: cn("flex min-w-0 flex-col overflow-hidden rounded-lg border bg-card text-card-foreground", selected && "border-primary ring-1 ring-primary", className), children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-1.5 p-(--panel-pad)", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx("span", { className: "min-w-0 truncate font-mono text-xs text-muted-foreground", children: artifact.kindLabel }), artifact.status && (_jsx(StatusBadge, { tone: ARTIFACT_TONE[artifact.status], struck: artifact.status === "superseded", children: t.artifactStatus(artifact.status) })), actions && _jsx("span", { className: "ml-auto flex items-center gap-1", children: actions })] }), _jsx(Heading, { id: titleId, className: "text-sm font-medium [overflow-wrap:anywhere]", children: href ? (_jsx(Link, { href: href, "aria-current": selected || undefined, className: nameClass, children: artifact.name })) : onOpen ? (_jsx("button", { type: "button", onClick: onOpen, "aria-pressed": selected, className: nameClass, children: artifact.name })) : (artifact.name) }), artifact.summary && (_jsx("p", { className: "line-clamp-3 text-sm [overflow-wrap:anywhere] text-muted-foreground", children: artifact.summary })), meta.length > 0 && (_jsx("p", { className: "flex min-w-0 flex-wrap gap-x-3 font-mono text-xs text-muted-foreground", children: meta.map((item, i) => (_jsx("span", { className: "min-w-0 [overflow-wrap:anywhere]", children: item }, i))) }))] }), preview != null && (_jsx("div", { "data-slot": "artifact-preview", className: "mt-auto min-w-0 border-t", children: preview }))] }));
+}
+/** A run's artifacts as cards, with loading, error and empty states. */
+export function ArtifactList({ artifacts, label, renderPreview, actionsFor, selectedId, columns = "auto", loading = false, error, onRetry, headingLevel, className, }) {
+    const { messages } = useUI();
+    const t = messages.run;
+    const name = label ?? t.artifacts;
+    const grid = cn("grid min-w-0 gap-3", columns === "auto" && "grid-cols-[repeat(auto-fill,minmax(min(100%,18rem),1fr))]", className);
+    if (error) {
+        return (_jsx(ErrorState, { title: t.loadFailed(name), error: error, onRetry: onRetry, className: className }));
+    }
+    if (loading) {
+        return (_jsxs("div", { "aria-busy": true, className: grid, children: [_jsx("p", { role: "status", className: "sr-only", children: messages.states.loading }), Array.from({ length: 3 }, (_, i) => (_jsx(WorkflowCardSkeleton, {}, i)))] }));
+    }
+    if (artifacts.length === 0) {
+        return (_jsx(EmptyState, { title: t.noArtifacts, description: t.noArtifactsDescription, className: className }));
+    }
+    return (_jsx("ul", { "aria-label": name, "data-slot": "artifact-list", className: grid, children: artifacts.map((artifact) => (_jsx("li", { className: "flex min-w-0", children: _jsx(ArtifactCard, { artifact: artifact, preview: renderPreview?.(artifact), selected: artifact.id === selectedId, headingLevel: headingLevel, className: "flex-1", ...actionsFor?.(artifact) }) }, artifact.id))) }));
+}

package/dist/workflow/DocumentReview.d.ts

@@ -0,0 +1,74 @@
+import * as React from "react";
+/** A run of text: plain, inserted or deleted (a redline). */
+export interface DocumentSegment {
+    text: string;
+    mark?: "insert" | "delete";
+}
+/** A paragraph or clause. */
+export interface DocumentBlock {
+    id: string;
+    /** The clause reference ("4.2", "Schedule 1, 3"), when the block is a clause. */
+    clause?: string;
+    heading?: string;
+    segments: readonly DocumentSegment[];
+}
+export interface DocumentPage {
+    /** From 1. */
+    number: number;
+    blocks: readonly DocumentBlock[];
+}
+/** A comment or note pinned to a block. */
+export interface DocumentAnnotation {
+    id: string;
+    blockId: string;
+    author: string;
+    body: string;
+    resolved?: boolean;
+}
+export type SignOffStatus = "pending" | "signed" | "declined";
+export interface DocumentSignOff {
+    id: string;
+    /** The role that signs ("Counsel", "Policy owner"). */
+    role: string;
+    name?: string;
+    status: SignOffStatus;
+    /** Formatted by the host. */
+    at?: string;
+}
+export interface DocumentReviewProps {
+    /** Names the document. */
+    title: string;
+    pages: readonly DocumentPage[];
+    /** The page shown, from 1. Uncontrolled without it. */
+    page?: number;
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    annotations?: readonly DocumentAnnotation[];
+    activeAnnotationId?: string;
+    /** An annotation was chosen in the margin: the host shows it (in ReviewPanel, say). */
+    onAnnotationSelect?: (annotation: DocumentAnnotation) => void;
+    /**
+     * The person chose a block to comment on. `label` is the anchor in words
+     * ("p. 3, 4.2"), ready for ReviewPanel's `commentAnchor`.
+     */
+    onAnchor?: (anchor: {
+        blockId: string;
+        page: number;
+        clause?: string;
+        label: string;
+    }) => void;
+    signOffs?: readonly DocumentSignOff[];
+    /** Signs off, after the confirm step. Shown when given and the person's sign-off is pending. */
+    onSignOff?: () => Promise<unknown> | unknown;
+    /** The role the person signs as, for the confirm step. */
+    signOffRole?: string;
+    className?: string;
+}
+/**
+ * Document review for legal and document modules: paged text with redline
+ * insertions and deletions, clause references, annotations in the margin and
+ * sign-off. Choosing a clause hands the host an anchor for its comment;
+ * choosing an annotation tells the host which one to show. The host supplies
+ * the text already segmented; the viewer renders, it does not diff.
+ */
+export declare function DocumentReview({ title, pages, page: pageProp, defaultPage, onPageChange, annotations, activeAnnotationId, onAnnotationSelect, onAnchor, signOffs, onSignOff, signOffRole, className, }: DocumentReviewProps): React.JSX.Element;

package/dist/workflow/DocumentReview.js

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftIcon, ChevronRightIcon, MessageSquareIcon, SignatureIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { ConfirmDialog } from "../overlays/ConfirmDialog.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+const SIGN_OFF_TONE = {
+    pending: "muted",
+    signed: "ok",
+    declined: "error",
+};
+/**
+ * Document review for legal and document modules: paged text with redline
+ * insertions and deletions, clause references, annotations in the margin and
+ * sign-off. Choosing a clause hands the host an anchor for its comment;
+ * choosing an annotation tells the host which one to show. The host supplies
+ * the text already segmented; the viewer renders, it does not diff.
+ */
+export function DocumentReview({ title, pages, page: pageProp, defaultPage = 1, onPageChange, annotations = [], activeAnnotationId, onAnnotationSelect, onAnchor, signOffs = [], onSignOff, signOffRole, className, }) {
+    const { messages } = useUI();
+    const t = messages.document;
+    const [ownPage, setOwnPage] = React.useState(defaultPage);
+    const [confirming, setConfirming] = React.useState(false);
+    const total = pages.length;
+    const current = Math.min(Math.max(pageProp ?? ownPage, 1), Math.max(total, 1));
+    const shown = pages.find((p) => p.number === current) ?? pages[current - 1];
+    const go = (next) => {
+        setOwnPage(next);
+        onPageChange?.(next);
+    };
+    const byBlock = new Map();
+    for (const a of annotations)
+        byBlock.set(a.blockId, [...(byBlock.get(a.blockId) ?? []), a]);
+    const canSign = Boolean(onSignOff) && signOffs.some((s) => s.status === "pending");
+    const changes = pages
+        .flatMap((p) => p.blocks)
+        .flatMap((b) => b.segments)
+        .filter((s) => s.mark).length;
+    return (_jsxs("section", { "aria-label": title, "data-slot": "document-review", className: cn("flex min-w-0 flex-col gap-3", className), children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center justify-between gap-2", children: [_jsxs("p", { className: "flex min-w-0 flex-wrap gap-x-3 font-mono text-xs text-muted-foreground", children: [_jsx("span", { children: t.changes(changes) }), _jsx("span", { children: t.annotations(annotations.length) })] }), total > 1 && (_jsxs("nav", { "aria-label": t.pages, className: "flex items-center gap-1", children: [_jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": t.previousPage, disabled: current <= 1, onClick: () => go(current - 1), children: _jsx(ChevronLeftIcon, { "aria-hidden": true }) }), _jsx("span", { "aria-live": "polite", className: "font-mono text-xs tabular-nums", children: t.pageOf(current, total) }), _jsx(Button, { size: "icon-sm", variant: "ghost", "aria-label": t.nextPage, disabled: current >= total, onClick: () => go(current + 1), children: _jsx(ChevronRightIcon, { "aria-hidden": true }) })] }))] }), _jsx("div", { className: "min-w-0 rounded-lg border bg-card p-(--panel-pad) text-card-foreground", children: shown ? (_jsx("ol", { "aria-label": t.pageOf(current, total), className: "flex min-w-0 flex-col gap-3", children: shown.blocks.map((block) => {
+                        const notes = byBlock.get(block.id) ?? [];
+                        const active = notes.some((n) => n.id === activeAnnotationId);
+                        const label = t.anchor(current, block.clause);
+                        return (_jsxs("li", { className: cn("grid min-w-0 grid-cols-[minmax(0,1fr)_auto] gap-x-3 gap-y-1 rounded-md border-l-2 border-transparent pl-2", notes.length > 0 && "border-warning", active && "border-primary bg-primary/5"), children: [_jsxs("div", { className: "min-w-0", children: [(block.clause || block.heading) && (_jsxs("p", { className: "mb-0.5 flex min-w-0 flex-wrap items-baseline gap-2 text-sm font-medium", children: [block.clause &&
+                                                    (onAnchor ? (_jsx("button", { type: "button", onClick: () => onAnchor({
+                                                            blockId: block.id,
+                                                            page: current,
+                                                            clause: block.clause,
+                                                            label,
+                                                        }), "aria-label": t.commentOnClause(block.clause), className: "rounded-sm font-mono text-xs text-primary underline-offset-2 outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring", children: block.clause })) : (_jsx("span", { className: "font-mono text-xs text-muted-foreground", children: block.clause }))), block.heading && _jsx("span", { children: block.heading })] })), _jsx("p", { className: "text-sm leading-relaxed [overflow-wrap:anywhere]", children: block.segments.map((segment, i) => segment.mark === "insert" ? (_jsxs("ins", { className: "rounded-sm bg-success/15 text-success-fg underline decoration-success", children: [_jsx("span", { className: "sr-only", children: t.inserted(segment.text) }), _jsx("span", { "aria-hidden": true, children: segment.text })] }, i)) : segment.mark === "delete" ? (_jsxs("del", { className: "rounded-sm bg-danger/15 text-danger-fg line-through", children: [_jsx("span", { className: "sr-only", children: t.deleted(segment.text) }), _jsx("span", { "aria-hidden": true, children: segment.text })] }, i)) : (_jsx(React.Fragment, { children: segment.text }, i))) })] }), _jsxs("div", { className: "flex flex-col items-end gap-1", children: [notes.map((note) => (_jsx("button", { type: "button", onClick: () => onAnnotationSelect?.(note), disabled: !onAnnotationSelect, "aria-current": note.id === activeAnnotationId || undefined, "aria-label": t.annotationBy(note.author, label), title: note.body, className: cn("inline-flex size-6 items-center justify-center rounded-md border text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default", note.id === activeAnnotationId && "border-primary text-primary", note.resolved && "opacity-60"), children: _jsx(MessageSquareIcon, { "aria-hidden": true, className: "size-3.5" }) }, note.id))), onAnchor && !block.clause && (_jsx(Button, { size: "icon-xs", variant: "ghost", "aria-label": t.commentOnBlock(label), onClick: () => onAnchor({ blockId: block.id, page: current, label }), children: _jsx(MessageSquareIcon, { "aria-hidden": true }) }))] })] }, block.id));
+                    }) })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: t.empty })) }), signOffs.length > 0 && (_jsxs("div", { className: "flex min-w-0 flex-col gap-2 rounded-lg border p-3", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center justify-between gap-2", children: [_jsx("h3", { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: t.signOff }), canSign && (_jsxs(Button, { size: "sm", onClick: () => setConfirming(true), children: [_jsx(SignatureIcon, { "aria-hidden": true }), t.signOffAction] }))] }), _jsx("ul", { className: "flex min-w-0 flex-col gap-1.5", children: signOffs.map((s) => (_jsxs("li", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-sm", children: [_jsx("span", { className: "font-medium", children: s.role }), s.name && _jsx("span", { className: "text-muted-foreground", children: s.name }), _jsx(StatusBadge, { tone: SIGN_OFF_TONE[s.status], children: t.signOffStatus(s.status) }), s.at && _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: s.at })] }, s.id))) })] })), _jsx(ConfirmDialog, { open: confirming, onOpenChange: setConfirming, title: t.signOffTitle(title), description: t.signOffDescription(signOffRole), confirmLabel: t.signOffAction, onConfirm: () => onSignOff?.() })] }));
+}

package/dist/workflow/FormReview.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+/** A field's place on its source page, as fractions of the page's width and height (0 to 1). */
+export interface FormFieldBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type FormFieldStatus = "pending" | "accepted" | "corrected";
+/** One value extracted from a form. */
+export interface FormField {
+    id: string;
+    label: string;
+    /** What extraction read. */
+    value: string;
+    /** Extraction's confidence, 0 to 1. */
+    confidence: number;
+    /** The source page it came from, from 1. */
+    page?: number;
+    box?: FormFieldBox;
+    status?: FormFieldStatus;
+    /** The person's correction, when `status` is corrected. */
+    corrected?: string;
+}
+/** A scanned or rendered source page. */
+export interface FormSourcePage {
+    number: number;
+    src: string;
+    alt: string;
+}
+export interface FormReviewProps {
+    /** Names the form. */
+    title: string;
+    pages: readonly FormSourcePage[];
+    fields: readonly FormField[];
+    /** Below this confidence a field is flagged. Defaults to 0.85. */
+    threshold?: number;
+    activeFieldId?: string;
+    onFieldSelect?: (field: FormField) => void;
+    /** Accepts the extracted value. Without it and `onCorrect` the review is read-only. */
+    onAccept?: (field: FormField) => Promise<unknown> | unknown;
+    /** Saves a correction. A rejection keeps the editor open with the error. */
+    onCorrect?: (field: FormField, value: string) => Promise<unknown> | unknown;
+    className?: string;
+}
+/**
+ * Form review for the paperwork module: the extracted fields beside the
+ * source page, each with its confidence (flagged below the threshold), and
+ * accept or correct per field. Choosing a field shows its page and boxes its
+ * place; the boxes on the page choose fields too. The host extracts, stores
+ * and decides; the viewer reports intent.
+ */
+export declare function FormReview({ title, pages, fields, threshold, activeFieldId, onFieldSelect, onAccept, onCorrect, className, }: FormReviewProps): React.JSX.Element;

package/dist/workflow/FormReview.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { CheckIcon, PencilIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { Input } from "../primitives/Input.js";
+import { Segmented } from "../primitives/Segmented.js";
+import { useUI } from "../provider/UIProvider.js";
+import { StatusBadge } from "../status/StatusBadge.js";
+/**
+ * Form review for the paperwork module: the extracted fields beside the
+ * source page, each with its confidence (flagged below the threshold), and
+ * accept or correct per field. Choosing a field shows its page and boxes its
+ * place; the boxes on the page choose fields too. The host extracts, stores
+ * and decides; the viewer reports intent.
+ */
+export function FormReview({ title, pages, fields, threshold = 0.85, activeFieldId, onFieldSelect, onAccept, onCorrect, className, }) {
+    const { messages } = useUI();
+    const t = messages.form;
+    const active = fields.find((f) => f.id === activeFieldId);
+    const [ownPage, setOwnPage] = React.useState(pages[0]?.number ?? 1);
+    const [lastActive, setLastActive] = React.useState(activeFieldId);
+    // Follow the chosen field to its page, until the person turns the page.
+    if (activeFieldId !== lastActive) {
+        setLastActive(activeFieldId);
+        if (active?.page)
+            setOwnPage(active.page);
+    }
+    const page = pages.find((p) => p.number === ownPage) ?? pages[0];
+    const onPage = fields.filter((f) => f.box && (f.page ?? 1) === page?.number);
+    const done = fields.filter((f) => f.status === "accepted" || f.status === "corrected").length;
+    const flagged = fields.filter((f) => f.confidence < threshold && f.status !== "accepted" && f.status !== "corrected").length;
+    return (_jsxs("section", { "aria-label": title, "data-slot": "form-review", className: cn("grid min-w-0 gap-4 md:grid-cols-2", className), children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center justify-between gap-2", children: [_jsx("h3", { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: t.source }), pages.length > 1 && (_jsx(Segmented, { label: t.sourcePage, size: "sm", value: String(page?.number), onValueChange: (v) => setOwnPage(Number(v)), options: pages.map((p) => ({ value: String(p.number), label: t.page(p.number) })) }))] }), page && (_jsxs("div", { className: "relative min-w-0 overflow-hidden rounded-lg border bg-muted/40", children: [_jsx("img", { src: page.src, alt: page.alt, className: "block h-auto w-full" }), onPage.map((f) => (_jsx("button", { type: "button", onClick: () => onFieldSelect?.(f), disabled: !onFieldSelect, "aria-label": t.fieldOnSource(f.label), "aria-current": f.id === activeFieldId || undefined, style: {
+                                    left: `${f.box.x * 100}%`,
+                                    top: `${f.box.y * 100}%`,
+                                    width: `${f.box.width * 100}%`,
+                                    height: `${f.box.height * 100}%`,
+                                }, className: cn("absolute rounded-sm border-2 outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-default", f.confidence < threshold && (f.status ?? "pending") === "pending"
+                                    ? "border-warning"
+                                    : "border-info/60", f.id === activeFieldId && "border-primary bg-primary/10") }, f.id)))] }))] }), _jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center justify-between gap-2", children: [_jsx("h3", { className: "font-mono text-2xs font-medium tracking-wider text-muted-foreground uppercase", children: t.fields }), _jsx("p", { role: "status", className: "font-mono text-xs text-muted-foreground", children: t.progress(done, fields.length, flagged) })] }), _jsx("ul", { className: "flex min-w-0 flex-col gap-2", children: fields.map((field) => (_jsx(FieldRow, { field: field, low: field.confidence < threshold, active: field.id === activeFieldId, onSelect: onFieldSelect, onAccept: onAccept, onCorrect: onCorrect }, field.id))) })] })] }));
+}
+function FieldRow({ field, low, active, onSelect, onAccept, onCorrect, }) {
+    const { messages } = useUI();
+    const t = messages.form;
+    const id = React.useId();
+    const [editing, setEditing] = React.useState(false);
+    const [draft, setDraft] = React.useState("");
+    const [pending, setPending] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const input = React.useRef(null);
+    React.useEffect(() => {
+        if (editing)
+            input.current?.focus();
+    }, [editing]);
+    const status = field.status ?? "pending";
+    const shown = status === "corrected" && field.corrected != null ? field.corrected : field.value;
+    async function run(action, after) {
+        setPending(true);
+        setError(null);
+        try {
+            const result = await action();
+            if (result !== false)
+                after?.();
+        }
+        catch (err) {
+            setError(err instanceof Error && err.message ? err.message : messages.confirm.failed);
+        }
+        finally {
+            setPending(false);
+        }
+    }
+    return (_jsxs("li", { "aria-current": active || undefined, className: cn("flex min-w-0 flex-col gap-1.5 rounded-lg border bg-card p-2.5 text-card-foreground", active && "border-primary"), children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx("span", { className: "min-w-0 text-xs font-medium [overflow-wrap:anywhere]", children: onSelect ? (_jsx("button", { type: "button", onClick: () => onSelect(field), className: "rounded-sm text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring", children: field.label })) : (field.label) }), _jsx(StatusBadge, { tone: low ? "warn" : "muted", children: t.confidence(field.confidence) }), status !== "pending" && (_jsx(StatusBadge, { tone: status === "accepted" ? "ok" : "info", children: t.status(status) }))] }), editing ? (_jsxs("form", { className: "flex min-w-0 flex-col gap-1.5", onSubmit: (event) => {
+                    event.preventDefault();
+                    void run(() => onCorrect?.(field, draft.trim()), () => setEditing(false));
+                }, children: [_jsx("label", { htmlFor: `${id}-input`, className: "sr-only", children: t.correctLabel(field.label) }), _jsx(Input, { id: `${id}-input`, value: draft, disabled: pending, ref: input, "aria-invalid": error != null || undefined, "aria-describedby": `${id}-extracted${error ? ` ${id}-error` : ""}`, onChange: (event) => setDraft(event.target.value) }), _jsx("p", { id: `${id}-extracted`, className: "text-xs [overflow-wrap:anywhere] text-muted-foreground", children: t.extracted(field.value) }), error && (_jsx("p", { id: `${id}-error`, role: "alert", className: "text-xs text-danger-fg", children: error })), _jsxs("div", { className: "flex flex-wrap gap-1.5", children: [_jsx(Button, { type: "submit", size: "xs", disabled: pending || !draft.trim(), children: pending ? messages.confirm.working : t.save }), _jsx(Button, { type: "button", size: "xs", variant: "ghost", disabled: pending, onClick: () => {
+                                    setEditing(false);
+                                    setError(null);
+                                }, children: t.cancel })] })] })) : (_jsxs(_Fragment, { children: [_jsxs("p", { className: "font-mono text-sm [overflow-wrap:anywhere]", children: [shown || _jsx("span", { className: "text-muted-foreground", children: t.empty }), status === "corrected" && field.corrected != null && (_jsxs(_Fragment, { children: [" ", _jsxs("del", { className: "text-xs text-muted-foreground", children: [_jsx("span", { className: "sr-only", children: t.extracted(field.value) }), _jsx("span", { "aria-hidden": true, children: field.value })] })] }))] }), (onAccept || onCorrect) && (_jsxs("div", { className: "flex flex-wrap gap-1.5", children: [onAccept && status === "pending" && (_jsxs(Button, { size: "xs", variant: "outline", disabled: pending, "aria-label": t.actionName(t.accept, field.label), onClick: () => void run(() => onAccept(field)), children: [_jsx(CheckIcon, { "aria-hidden": true }), t.accept] })), onCorrect && (_jsxs(Button, { size: "xs", variant: "ghost", disabled: pending, "aria-label": t.actionName(t.correct, field.label), onClick: () => {
+                                    setDraft(shown);
+                                    setEditing(true);
+                                }, children: [_jsx(PencilIcon, { "aria-hidden": true }), t.correct] }))] })), error && (_jsx("p", { role: "alert", className: "text-xs text-danger-fg", children: error }))] }))] }));
+}