@lotics/ui 7.19.2 → 8.0.0

package/examples/tpl_documents.tsx

@@ -0,0 +1,790 @@
+import { Fragment, useEffect, useState } from "react";
+import { ScrollView, View } from "react-native";
+import { colors } from "@lotics/ui/colors";
+import { Text } from "@lotics/ui/text";
+import { Icon } from "@lotics/ui/icon";
+import { Button } from "@lotics/ui/button";
+import { Divider } from "@lotics/ui/divider";
+import { Section, SectionHeading, SectionHeadingTitle } from "@lotics/ui/section_heading";
+import { FileRow } from "@lotics/ui/file_row";
+import { pickFiles } from "@lotics/ui/file_picker";
+import { Alert } from "@lotics/ui/alert";
+import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
+import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
+import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
+import { FileBadge } from "@lotics/ui/file_badge";
+import { Finding, FindingComparison } from "@lotics/ui/finding";
+import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
+import { type DisplayFile } from "@lotics/ui/file_thumbnail";
+import { FormTextInput } from "@lotics/ui/form_text_input";
+import { CheckboxInput } from "@lotics/ui/checkbox_input";
+import { SearchInput } from "@lotics/ui/search_input";
+import { useSelection } from "@lotics/ui/use_selection";
+import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
+import { Dialog, DialogHeader, DialogHeaderTitle, DialogScrollArea, DialogFooter } from "@lotics/ui/dialog";
+import { CardSelectItem } from "@lotics/ui/card_select_item";
+import { AgentRun, type AgentRunItem, type AgentRunStep } from "@lotics/ui/agent_run";
+import { type SourceRef } from "@lotics/ui/sources";
+import { ChangeValueInput, Change, ChangeField, ChangeFields, ChangeReasoning, ChangeRecord, ChangeReview, ChangeReviewActions, ChangeReviewHeader, type ChangeStatus } from "@lotics/ui/change_review";
+
+import { CompletionState } from "@lotics/ui/completion_state";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Document desk — THE worked example for everything document-driven
+// on a record. A dossier's files block feeds ONE "Use AI" entry that FORKS into
+// the two document tasks: EXTRACT (read the documents and fill the record —
+// ONE `Change` section per RECORD whose body is `ChangeFields` stacking a
+// `ChangeField` per proposed value: label · the − band when replacing · the
+// editable + value. Editing IS the review; an add has no `before`, a removal
+// is the − band alone, and a conflict shows the read-only outcome band over
+// candidate rows + the type-another-value third option) and CROSS-CHECK
+// (compare the documents against the record and each other — ranked
+// display-only findings the human acts on), and EDIT WITH AI (the askAi handoff —
+// dialogue-shaped file iteration happens in the Lotics chat; the fork is the ONE
+// AI entry point, never per-row AI buttons). Plus CREATE DOCUMENTS: a
+// readiness checklist → generate → the files land back on the record. All
+// mock, useState + the timer that streams the AgentRun.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type ScriptStep = Omit<AgentRunStep, "status">;
+type Task = "extract" | "check";
+type Phase = "fork" | "running" | "review" | "done";
+
+interface Doc { id: string; name: string; mimeType: string; kind: string; sizeKB: number; added: string; addedAt: number }
+
+// Display derives from the canonical numeric — strings would sort "8.4 MB" < "96 KB".
+function fmtSize(kb: number): string {
+  if (kb <= 0) return "—";
+  return kb < 1024 ? `${kb} KB` : `${(kb / 1024).toFixed(1)} MB`;
+}
+const DOCS: Doc[] = [
+  { id: "f1", name: "invoice.pdf", mimeType: "application/pdf", kind: "PDF", sizeKB: 214, added: "26 Jun", addedAt: 626 },
+  { id: "f2", name: "packing-list.pdf", mimeType: "application/pdf", kind: "PDF", sizeKB: 96, added: "26 Jun", addedAt: 626 },
+  { id: "f3", name: "booking-confirmation.pdf", mimeType: "application/pdf", kind: "PDF", sizeKB: 182, added: "28 Jun", addedAt: 628 },
+  { id: "f4", name: "photos.zip", mimeType: "application/zip", kind: "ZIP", sizeKB: 8602, added: "30 Jun", addedAt: 630 },
+];
+
+const EXTRACT_STEPS: ScriptStep[] = [
+  { id: "e1", label: "Reading the selected documents", detail: "Page by page, tables included" },
+  { id: "e2", label: "get_record", kind: "tool" },
+  { id: "e3", label: "Extracting field values", detail: "9 fields · 2 order lines" },
+  { id: "e4", label: "Comparing against the record", detail: "3 match · 1 new · 1 change · 1 conflict" },
+];
+const CHECK_STEPS: ScriptStep[] = [
+  { id: "c1", label: "Reading the selected documents", detail: "Quantities, parties, dates and terms" },
+  { id: "c2", label: "get_record", kind: "tool" },
+  { id: "c3", label: "Cross-checking documents and record", detail: "18 fields compared across the sources" },
+];
+
+// The shapes of an extract decision — an ADD, an UPDATE, a REMOVAL, a source
+// CONFLICT — are the SAME `ChangeField` row: an add has no `before`, an update
+// bands it, a removal is the − band alone, and a conflict's outcome is the
+// read-only + band over the candidate rows.
+const MBL_PROPOSED = "MAEU129394855";
+const VESSEL_CURRENT = "MSC AURA";
+const VESSEL_PROPOSED = "MAERSK SALINA";
+const CONSIGNEE_CURRENT = "Nordic Furniture AB";
+const NOTIFY_CURRENT = "Euro Textile Trading GmbH, Frankfurt";
+const EXTRACT_REASONING = "The booking confirmation names the substitute vessel for this sailing week; the invoice and the packing list disagree on the consignee.";
+const CONSIGNEE_OPTIONS = [
+  { value: "Nordic Furniture AB, Jönköping DC", source: "invoice.pdf", recommended: true },
+  { value: "NF Distribution ApS, Kolding", source: "packing-list.pdf" },
+];
+const EXTRACT_FIELD_IDS = ["mbl", "vessel", "consignee", "gross", "notify"] as const;
+
+// Cross-check findings — severity reads through ONE colored dot badge (red /
+// amber / zinc), the rest stays calm text.
+type Severity = "critical" | "warning" | "info";
+interface Check { id: string; severity: Severity; title: string; detail?: string; comparison?: { values: { label: string; value: string }[]; delta?: string }; sources?: string[] }
+const FINDINGS: Check[] = [
+  {
+    id: "q1", severity: "critical", title: "Quantity disagrees between the invoice and the packing list",
+    detail: "Short-shipping against the invoice risks a customs query and a client claim.",
+    comparison: { values: [{ label: "invoice.pdf", value: "480 pcs" }, { label: "packing-list.pdf", value: "440 pcs" }], delta: "−40 pcs" },
+    sources: ["invoice.pdf", "packing-list.pdf"],
+  },
+  {
+    id: "q2", severity: "warning", title: "Consignee differs between the invoice and the booking",
+    detail: "The invoice names the buyer's own warehouse; the booking routes delivery through a distribution partner. One of them files wrong.",
+    sources: ["invoice.pdf", "booking-confirmation.pdf"],
+  },
+  {
+    id: "q4", severity: "warning", title: "No certificate of origin among the documents",
+    detail: "Destination customs requires a C/O for this HS chapter — request it before the vessel cut-off.",
+  },
+  {
+    id: "q3", severity: "info", title: "Booking cut-off is earlier than the invoiced ship week",
+    detail: "Documents close 14 Jul on the booking; the invoice quotes shipment in the week of 18 Jul. No conflict if the cargo is ready.",
+    sources: ["booking-confirmation.pdf"],
+  },
+];
+
+// A tiny REAL pdf (data URI) so the gallery preview genuinely renders.
+const MOCK_PDF_URL = "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgNjEyIDc5Ml0vQ29udGVudHMgNCAwIFIvUmVzb3VyY2VzPDwvRm9udDw8L0YxIDUgMCBSPj4+Pj4+ZW5kb2JqCjQgMCBvYmo8PC9MZW5ndGggNjM+PnN0cmVhbQpCVCAvRjEgMTggVGYgNzIgNzIwIFRkIChOb3JkaWMgRnVybml0dXJlIC0gbW9jayBkb2N1bWVudCkgVGogRVQKZW5kc3RyZWFtIGVuZG9iago1IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvQmFzZUZvbnQvSGVsdmV0aWNhPj5lbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTIgMDAwMDAgbiAKMDAwMDAwMDEwMSAwMDAwMCBuIAowMDAwMDAwMjExIDAwMDAwIG4gCjAwMDAwMDAzMjAgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNi9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjM4MQolJUVPRg==";
+const toDisplay = (d: Doc): DisplayFile => ({ id: d.id, filename: d.name, mimeType: d.mimeType, url: MOCK_PDF_URL });
+
+// The documents register — columns ONCE (the Table renders the header band
+// and every cell width from these; facts get dedicated scannable columns
+// instead of a crammed meta string). Same grammar as the case register
+// (tpl_item_list): leading checkbox + select-all, trailing ⋯ gutter.
+const DOC_COLUMNS: TableColumn[] = [
+  { key: "doc", label: "Document", flex: 1, sortable: true },
+  { key: "size", label: "Size", width: 90, align: "right", sortable: true },
+  { key: "added", label: "Added", width: 96, sortable: true },
+];
+
+interface Producible { id: string; label: string; file: string; sizeKB: number; needs?: { key: string; label: string }[] }
+const PRODUCIBLE: Producible[] = [
+  { id: "g1", label: "Shipping instruction", file: "shipping-instruction.pdf", sizeKB: 84 },
+  { id: "g2", label: "Certificate of origin", file: "certificate-of-origin.pdf", sizeKB: 61 },
+  { id: "g3", label: "Delivery note", file: "delivery-note.pdf", sizeKB: 72, needs: [{ key: "delivery_address", label: "Delivery address" }, { key: "hs_code", label: "HS code" }] },
+  { id: "g4", label: "Customs declaration draft", file: "customs-declaration-draft.pdf", sizeKB: 118 },
+];
+
+export function TplDocuments() {
+  const [files, setFiles] = useState<Doc[]>(DOCS);
+  const sel = useSelection();
+
+  // Use AI — one entry off the selection, forking into the two document tasks.
+  const [aiOpen, setAiOpen] = useState(false);
+  const [picked, setPicked] = useState<Doc[]>([]);
+  const [brief, setBrief] = useState("");
+  // The fork SELECTS a task; the footer CTA runs it (select → confirm, never
+  // act-on-press for an analysis that costs a run).
+  const [taskChoice, setTaskChoice] = useState<Task | "edit" | null>(null);
+  // True when the dialog opened from a fresh upload — the fork then offers
+  // keeping the files without running anything.
+  const [uploadFlow, setUploadFlow] = useState(false);
+  // Full-page preview over whichever list the user was looking at.
+  const [preview, setPreview] = useState<{ files: DisplayFile[]; index: number } | null>(null);
+  const openPreview = (docs: Doc[], index: number) => setPreview({ files: docs.map(toDisplay), index });
+  const [task, setTask] = useState<Task | null>(null);
+  const [phase, setPhase] = useState<Phase>("fork");
+  const [revealed, setRevealed] = useState(0);
+  // The HOST owns the review: one editable proposal per field (editing IS the
+  // review), a tri-state decision per field (dropped rows collapse struck,
+  // out of the apply), and the conflict's pick (empty until the user chooses).
+  const [mbl, setMbl] = useState(MBL_PROPOSED);
+  const [vessel, setVessel] = useState(VESSEL_PROPOSED);
+  const [consignee, setConsignee] = useState<string | null>(null);
+  const [grossWeight, setGrossWeight] = useState("1,540");
+  // Order lines proposed from the packing list — RECORD ops (ChangeRecord).
+  const [lineAdd, setLineAdd] = useState<ChangeStatus>("pending");
+  const [lineEdit, setLineEdit] = useState<Record<string, "kept" | "dropped">>({});
+  const [newItem, setNewItem] = useState("Corner protectors, foam");
+  const [newQty, setNewQty] = useState("400");
+  const [editedQty, setEditedQty] = useState("1,450");
+  const lineEditRow = (id: string) => ({
+    status: lineEdit[id] ?? ("pending" as const),
+    onKeep: () => setLineEdit((m) => ({ ...m, [id]: "kept" as const })),
+    onDrop: () => setLineEdit((m) => ({ ...m, [id]: "dropped" as const })),
+    onUndo: () => setLineEdit((m) => { const n = { ...m }; delete n[id]; return n; }),
+  });
+  const [consigneePick, setConsigneePick] = useState<number | "custom" | null>(null);
+  const [customConsignee, setCustomConsignee] = useState("");
+  const [fieldDecisions, setFieldDecisions] = useState<Record<string, "kept" | "dropped">>({});
+
+  const openAi = () => { setPicked(files.filter((f) => sel.has(f.id))); setUploadFlow(false); setAiOpen(true); };
+  // The upload path's save: pending picked files land on the record only here.
+  const commitUpload = () => setFiles((fs) => [...fs, ...picked.filter((p2) => !fs.some((f) => f.id === p2.id))]);
+  const closeAi = () => {
+    setAiOpen(false); setTask(null); setPhase("fork"); setRevealed(0); setUploadFlow(false); setBrief(""); setTaskChoice(null);
+    setMbl(MBL_PROPOSED); setVessel(VESSEL_PROPOSED); setConsignee(null); setConsigneePick(null); setCustomConsignee(""); setGrossWeight("1,540"); setLineAdd("pending"); setLineEdit({}); setNewItem("Corner protectors, foam"); setNewQty("400"); setEditedQty("1,450"); setFieldDecisions({});
+  };
+  const startTask = (t: Task) => { setTask(t); setRevealed(0); setPhase("running"); };
+  // ⋯ menu per document row. "Edit with AI" is the app→chat handoff for
+  // dialogue-shaped work on THIS document — a real app calls the SDK:
+  //   void askAi({ file_ids: [f.id], record_ids: [orderRecordId], prompt: `Update ${f.name} — ` });
+  // and the Lotics messenger opens a fresh chat with the file attached AND
+  // previewed beside it; the prompt is prefilled, editable, never auto-sent.
+  // Structured judgment that commits back into fields stays on the Use-AI
+  // review flow. Rename works for real; Download is host-served in an app
+  // (openExternal(file.url)).
+  // One sort at a time; the third toggle on a column clears it (register law).
+  const [docSort, setDocSort] = useState<SortState | null>(null);
+  const [docSearch, setDocSearch] = useState("");
+  const docQuery = docSearch.trim().toLowerCase();
+  const visibleFiles = sortBy(
+    docQuery ? files.filter((f) => f.name.toLowerCase().includes(docQuery)) : files,
+    docSort,
+    (f, key) => (key === "doc" ? f.name.toLowerCase() : key === "size" ? f.sizeKB : f.addedAt),
+  );
+
+  const [renameTarget, setRenameTarget] = useState<Doc | null>(null);
+  const [renameDraft, setRenameDraft] = useState("");
+  const openRename = (f: Doc) => { setRenameTarget(f); setRenameDraft(f.name); };
+  const saveRename = () => {
+    const name = renameDraft.trim();
+    if (renameTarget && name) setFiles((fs) => fs.map((x) => (x.id === renameTarget.id ? { ...x, name } : x)));
+    setRenameTarget(null);
+  };
+  const editWithAi = (docs: Doc[]) => {
+    const names = docs.map((d) => d.name).join(", ");
+    Alert.alert(
+      "Edit with AI",
+      `Opens the Lotics chat on a fresh thread with ${names} attached${docs.length === 1 ? " and previewed side by side" : ""} — describe the change and the agent edits as new versions.`,
+      [{ text: "OK" }],
+    );
+  };
+  const fileMenuFor = (f: Doc): ActionMenuItem[] => [
+    { key: "rename", label: "Rename", icon: "pencil", onPress: () => openRename(f) },
+    { key: "download", label: "Download", icon: "download", onPress: () => { /* a real app: openExternal(f.url) */ } },
+  ];
+
+  const removeSelected = () => {
+    Alert.alert(
+      `Remove ${sel.count} ${sel.count === 1 ? "file" : "files"}?`,
+      "They come off the order's documents — the originals stay wherever they came from.",
+      [
+        { text: "Keep files", style: "cancel" },
+        { text: "Remove", style: "destructive", onPress: () => { setFiles((fs) => fs.filter((f) => !sel.has(f.id))); sel.clear(); } },
+      ],
+    );
+  };
+  const decideField = (id: string, d: "kept" | "dropped" | undefined) =>
+    setFieldDecisions((m) => {
+      const n = { ...m };
+      if (d) n[id] = d;
+      else delete n[id];
+      return n;
+    });
+  const fieldRow = (id: string) => ({
+    status: fieldDecisions[id] ?? ("pending" as const),
+    onKeep: () => decideField(id, "kept"),
+    onDrop: () => decideField(id, "dropped"),
+    onUndo: () => decideField(id, undefined),
+  });
+
+  // The streaming timer idiom — reveal one script step at a time, then settle.
+  const script = task === "check" ? CHECK_STEPS : EXTRACT_STEPS;
+  useEffect(() => {
+    if (phase !== "running") return;
+    if (revealed >= script.length) {
+      const t = setTimeout(() => setPhase("review"), 850);
+      return () => clearTimeout(t);
+    }
+    const t = setTimeout(() => setRevealed((r) => r + 1), revealed === 0 ? 280 : 680);
+    return () => clearTimeout(t);
+  }, [phase, revealed, script.length]);
+
+  const runItems: AgentRunItem[] = [
+    { type: "text", id: "in", text: (task === "check" ? "Comparing the documents against the record and each other." + (brief.trim() ? ` Also: ${brief.trim()}` : "") : "Reading the documents and comparing them with the record.") },
+    ...script.slice(0, Math.min(revealed + 1, script.length)).map((s, i): AgentRunItem => ({
+      type: "step", ...s, detail: i < revealed ? s.detail : undefined, status: i < revealed ? "done" : "running",
+    })),
+  ];
+  if (revealed >= script.length) {
+    runItems.push({ type: "text", id: "out", text: task === "check" ? "Checked 18 fields — 2 disagree, 1 worth noting. The findings are below." : "3 fields already match; 3 need a decision, and the invoice carries 2 lines the order doesn't have yet." });
+  }
+
+  // Apply counts what actually commits: the kept fields.
+  const applyCount = Object.values(fieldDecisions).filter((d) => d === "kept").length + Object.values(lineEdit).filter((d) => d === "kept").length + (lineAdd === "accepted" ? 1 : 0);
+  // Keep-all lives with the HOST (field decisions the registry can't see):
+  // keep every still-pending field; the unresolved conflict stays pending.
+  const keepAll = () => {
+    setLineAdd((st) => (st === "pending" ? "accepted" : st));
+    setLineEdit((m) => ({ qty: m.qty ?? "kept", ...m }));
+    setFieldDecisions((m) => {
+    const n = { ...m };
+    for (const f of EXTRACT_FIELD_IDS) {
+      if (f === "consignee" && consignee == null) continue;
+      if (n[f] == null) n[f] = "kept";
+    }
+    return n;
+  });
+  };
+
+  // Create documents — a readiness checklist; generated files land on the record.
+  const gen = useSelection();
+  const [genOpen, setGenOpen] = useState(false);
+  // Required inputs some documents still miss — filled in the dialog's own
+  // fill screen, saved onto the record, readiness recomputes.
+  const [docFieldValues, setDocFieldValues] = useState<Record<string, string>>({});
+  const [fillTarget, setFillTarget] = useState<Producible | null>(null);
+  const [fillDraft, setFillDraft] = useState<Record<string, string>>({});
+  const missingOf = (p: Producible) => (p.needs ?? []).filter((n) => !docFieldValues[n.key]?.trim());
+  const openFill = (p: Producible) => {
+    setFillTarget(p);
+    setFillDraft(Object.fromEntries((p.needs ?? []).map((n) => [n.key, docFieldValues[n.key] ?? ""])));
+  };
+  const saveFill = () => {
+    setDocFieldValues((v) => ({ ...v, ...fillDraft }));
+    setFillTarget(null);
+  };
+  const [genDone, setGenDone] = useState(false);
+  // Generated documents stay PENDING until the user commits them — adding to
+  // the record is a decision (the same law as the upload flow), and the files
+  // are previewable while deciding.
+  const [genPending, setGenPending] = useState<Doc[]>([]);
+  // Generation is real work in a live app (template fill + render per
+  // document) — it runs as a visible scripted AgentRun, never a teleport.
+  const [genRunning, setGenRunning] = useState(false);
+  const [genRevealed, setGenRevealed] = useState(0);
+  const [genSteps, setGenSteps] = useState<{ id: string; label: string }[]>([]);
+  const generate = () => {
+    const chosen = PRODUCIBLE.filter((p) => gen.has(p.id));
+    setGenSteps([
+      { id: "read", label: "Reading the order's data" },
+      ...chosen.map((p) => ({ id: p.id, label: `Filling ${p.label}` })),
+    ]);
+    setGenPending(chosen.map((p) => ({ id: `gen-${p.id}`, name: p.file, mimeType: "application/pdf", kind: "PDF", sizeKB: p.sizeKB, added: "", addedAt: 0 })));
+    setGenRevealed(0);
+    setGenRunning(true);
+  };
+  useEffect(() => {
+    if (!genRunning) return;
+    if (genRevealed >= genSteps.length) {
+      const t = setTimeout(() => { setGenRunning(false); setGenDone(true); }, 600);
+      return () => clearTimeout(t);
+    }
+    const t = setTimeout(() => setGenRevealed((r) => r + 1), genRevealed === 0 ? 260 : 620);
+    return () => clearTimeout(t);
+  }, [genRunning, genRevealed, genSteps.length]);
+  const addGeneratedToRecord = () => {
+    setFiles((fs) => [...fs, ...genPending.map((g) => ({ ...g, added: "just now", addedAt: 999 }))]);
+    closeGen();
+  };
+  const closeGen = () => { setGenOpen(false); setGenDone(false); setGenRunning(false); setGenRevealed(0); setFillTarget(null); setGenPending([]); gen.clear(); };
+
+  return (
+    <>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28, paddingBottom: 120 }}>
+      <View style={{ maxWidth: 720, width: "100%", alignSelf: "center", gap: 24 }}>
+        <View style={{ gap: 2 }}>
+          <Text size="xl" weight="semibold">PO-2481 — Nordic Furniture AB</Text>
+          <Text size="sm" color="muted">Sea freight · Gothenburg → Ho Chi Minh City · FOB · ETD 18 Jul 2026</Text>
+        </View>
+
+        <Section>
+          <SectionHeading>
+            <SectionHeadingTitle>Documents</SectionHeadingTitle>
+          </SectionHeading>
+          {/* toolbar — search LEFT, the CTAs RIGHT, one row (the register band). */}
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+            <View style={{ flexGrow: 1, flexBasis: 220, minWidth: 200, maxWidth: 340 }}>
+              <SearchInput
+                placeholder="Search documents…"
+                value={docSearch}
+                onChangeText={setDocSearch}
+                accessibilityLabel="Search documents"
+              />
+            </View>
+            <View style={{ flex: 1 }} />
+            <Button title="Create documents" color="muted" onPress={() => setGenOpen(true)} />
+            <Button
+              title="Add files"
+              color="secondary"
+              onPress={() => {
+                void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then((chosen) => {
+                  if (chosen.length === 0) return;
+                  const added = chosen.map((f, i) => ({ id: `added-${f.name}-${i}`, name: f.name, mimeType: f.type || "application/pdf", kind: (f.type || "application/pdf").split("/")[1]?.toUpperCase().slice(0, 4) ?? "FILE", sizeKB: Math.round(f.size / 1024), added: "just now", addedAt: 999 }));
+                  // PENDING until the user chooses: saving is a decision the
+                  // dialog asks for (save only / run a task), never a side
+                  // effect of picking — closing the dialog discards.
+                  setPicked(added);
+                  setUploadFlow(true);
+                  setAiOpen(true);
+                });
+              }}
+            />
+          </View>
+          <Table
+            columns={DOC_COLUMNS}
+            leading={24}
+            trailing={44}
+            sort={docSort}
+            onSort={(key) => setDocSort(cycleSort(docSort, key))}
+            selectAll={
+              <CheckboxInput
+                accessibilityLabel="Select all documents"
+                checked={sel.allSelected(visibleFiles.map((f) => f.id))}
+                indeterminate={sel.indeterminate(visibleFiles.map((f) => f.id))}
+                onChange={(on) => sel.setAll(visibleFiles.map((f) => f.id), on)}
+              />
+            }
+          >
+            {visibleFiles.map((f, fi) => (
+              <TableRow
+                key={f.id}
+                onPress={() => openPreview(visibleFiles, fi)}
+                marked={sel.has(f.id)}
+                accessibilityLabel={`Open ${f.name}`}
+                leading={<CheckboxInput accessibilityLabel={`Select ${f.name}`} checked={sel.has(f.id)} onChange={(on) => sel.toggle(f.id, on)} />}
+                trailing={<ActionMenu items={fileMenuFor(f)} accessibilityLabel={`Actions for ${f.name}`} />}
+              >
+                <TableCell>
+                  <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+                    <FileBadge mimeType={f.mimeType} />
+                    <Text size="sm" weight="medium" numberOfLines={1} style={{ flexShrink: 1 }}>{f.name}</Text>
+                  </View>
+                </TableCell>
+                <TableCell>
+                  <Text size="sm" tabular>{fmtSize(f.sizeKB)}</Text>
+                </TableCell>
+                <TableCell>
+                  <Text size="sm" tabular>{f.added}</Text>
+                </TableCell>
+              </TableRow>
+            ))}
+          </Table>
+        </Section>
+      </View>
+    </ScrollView>
+
+    <FloatingActionBar count={sel.count} label={sel.count === 1 ? "file selected" : "files selected"} onClear={sel.clear}>
+      <Button title="Remove" color="danger-secondary" icon="trash" onPress={removeSelected} />
+      <Button title="Download" color="secondary" icon="download" onPress={() => { /* a real app zips or opens each selected file (openExternal) */ }} />
+      <Button title="Use AI" color="primary" onPress={openAi} />
+    </FloatingActionBar>
+
+    {/* Use AI — fork → running → review → done, all inside one dialog. The review
+        provider wraps the WHOLE dialog so the `Change`s (scroll area) and the
+        commit bar (`DialogFooter`) share one review context. */}
+    <ChangeReview>
+    <Dialog open={aiOpen} onOpenChange={(o) => { if (!o) closeAi(); }} maxWidth={620}>
+      <DialogHeader>
+        <DialogHeaderTitle>{task === "extract" ? "Extract data" : task === "check" ? "Cross-check" : `Use AI · ${picked.length} ${picked.length === 1 ? "file" : "files"}`}</DialogHeaderTitle>
+      </DialogHeader>
+      <DialogScrollArea>
+        {phase === "fork" ? (
+          <View style={{ gap: 16 }}>
+            <View style={{ gap: 8 }}>{picked.map((f, fi) => <FileRow key={f.id} name={f.name} mimeType={f.mimeType} onPress={() => openPreview(picked, fi)} />)}</View>
+            <View style={{ gap: 8 }}>
+              <CardSelectItem accessibilityLabel="Extract data — read the documents and fill the record" onPress={() => setTaskChoice("extract")} selected={taskChoice === "extract"} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                <Icon name="scan" size={18} color={colors.zinc[700]} />
+                <View style={{ flex: 1, gap: 2 }}>
+                  <Text size="sm" weight="semibold">Extract data</Text>
+                  <Text size="xs" color="muted">Read the documents and fill the record — what's new, what changes, what conflicts.</Text>
+                </View>
+              </CardSelectItem>
+              <CardSelectItem accessibilityLabel="Cross-check — compare the documents against the record" onPress={() => setTaskChoice("check")} selected={taskChoice === "check"} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                <Icon name="list-checks" size={18} color={colors.zinc[700]} />
+                <View style={{ flex: 1, gap: 2 }}>
+                  <Text size="sm" weight="semibold">Cross-check</Text>
+                  <Text size="xs" color="muted">Compare the documents against the record and each other — what disagrees and why.</Text>
+                </View>
+              </CardSelectItem>
+              <CardSelectItem accessibilityLabel="Edit with AI — open the chat agent with these documents" onPress={() => setTaskChoice("edit")} selected={taskChoice === "edit"} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                <Icon name="square-pen" size={18} color={colors.zinc[700]} />
+                <View style={{ flex: 1, gap: 2 }}>
+                  <Text size="sm" weight="semibold">Edit with AI</Text>
+                  <Text size="xs" color="muted">Open the chat with the documents attached — describe the change, the agent edits them as new versions.</Text>
+                </View>
+              </CardSelectItem>
+            </View>
+            {/* Optional steering for the CHECK — findings serve ANY file-based
+                request the user briefs, not just the stock cross-check. */}
+            {taskChoice === "check" ? (
+              <FormTextInput
+                label="Instructions (optional)"
+                placeholder="Anything specific to check — e.g. verify the HS codes against the order"
+                value={brief}
+                onChangeText={setBrief}
+                multiline
+                accessibilityLabel="Instructions for the agent"
+              />
+            ) : null}
+          </View>
+        ) : null}
+
+        {phase === "running" ? <AgentRun items={runItems} state={revealed >= script.length ? "done" : "streaming"} /> : null}
+
+        {phase === "review" && task === "extract" ? (
+          <View style={{ gap: 16 }}>
+            <View style={{ gap: 8 }}>
+              <Text size="md" weight="semibold">Files read</Text>
+              <View style={{ gap: 8 }}>{picked.map((f, fi) => <FileRow key={f.id} name={f.name} mimeType={f.mimeType} onPress={() => openPreview(picked, fi)} />)}</View>
+            </View>
+            <View style={{ gap: 8 }}>
+              <ChangeReviewHeader />
+              {/* ONE section for the RECORD — ChangeFields stacks a ChangeField
+                  per proposed value: label · the − band when replacing · the
+                  editable + value. Editing IS the review; each field decides
+                  for ITSELF (Keep/Drop), and Apply commits the kept rows. */}
+              <Change id="order">
+                <ChangeReasoning>{EXTRACT_REASONING}</ChangeReasoning>
+                <ChangeFields>
+                  {/* An ADD — the record holds nothing yet, so no `before`. */}
+                  <ChangeField label="MBL number" value={mbl} summary={mbl} {...fieldRow("mbl")}>
+                    <ChangeValueInput value={mbl} onChangeText={setMbl} accessibilityLabel="MBL number" />
+                  </ChangeField>
+                  {/* An UPDATE — the current value banded above the editor. */}
+                  <ChangeField label="Vessel" value={vessel} summary={vessel} before={VESSEL_CURRENT} {...fieldRow("vessel")}>
+                    <ChangeValueInput value={vessel} onChangeText={setVessel} accessibilityLabel="Vessel" />
+                  </ChangeField>
+                  {/* A CONFLICT — the sources disagree: the read-only outcome
+                      band stays on its placeholder until the user picks a
+                      candidate below or types a third value — never a
+                      pre-selection; Keep is gated until resolved. */}
+                  <ChangeField
+                    label="Consignee"
+                    value={consignee ?? ""}
+                    summary={consignee ?? undefined}
+                    before={CONSIGNEE_CURRENT}
+                    valueReadOnly
+                    placeholder="Pick a candidate below"
+                    reasoning="The invoice and the packing list disagree — pick a candidate or type your own."
+                    candidates={CONSIGNEE_OPTIONS.map((c, i2) => ({ value: c.value, source: c.source, selected: consigneePick === i2 }))}
+                    onPickCandidate={(c) => { const i2 = CONSIGNEE_OPTIONS.findIndex((x) => x.value === c.value); setConsigneePick(i2); setConsignee(c.value); }}
+                    customValue={customConsignee}
+                    customSelected={consigneePick === "custom"}
+                    onCustomSelect={() => { setConsigneePick("custom"); setConsignee(customConsignee || null); }}
+                    onCustomValue={(v) => { setCustomConsignee(v); setConsignee(v || null); }}
+                    keepDisabled={consignee == null}
+                    {...fieldRow("consignee")}
+                  />
+                  {/* An ADD-only field — new information the documents carry:
+                      the + band alone, same grammar as every diff. */}
+                  <ChangeField label="Gross weight" value={grossWeight} summary={grossWeight} {...fieldRow("gross")}>
+                    <ChangeValueInput value={grossWeight} onChangeText={setGrossWeight} unit="kg" accessibilityLabel="Gross weight" />
+                  </ChangeField>
+                  {/* A REMOVAL — the − band alone (empty value, no editor): the
+                      documents show this value no longer applies. */}
+                  <ChangeField
+                    label="Notify party"
+                    before={NOTIFY_CURRENT}
+                    reasoning="No notify party appears on any document — the consignee is notified directly."
+                    {...fieldRow("notify")}
+                  />
+                </ChangeFields>
+              </Change>
+              {/* RECORD ops — the packing list also proposes ORDER LINES:
+                  a ChangeRecord card per item (add = one card decision;
+                  edit = its changed fields decide themselves). A divider +
+                  breathing room set the sub-section off from the fields. */}
+              <View style={{ paddingTop: 10 }}>
+                <Divider />
+              </View>
+              <ChangeReviewHeader title="Order lines" />
+              <ChangeRecord
+                id="line-add"
+                tone="add"
+                title="New line"
+                status={lineAdd}
+                onAccept={() => setLineAdd("accepted")}
+                onReject={() => setLineAdd("rejected")}
+                onUndo={() => setLineAdd("pending")}
+                summary={`${newItem} (${newQty} pcs)`}
+              >
+                <ChangeField label="Item" value={newItem} summary={newItem}>
+                  <ChangeValueInput value={newItem} onChangeText={setNewItem} accessibilityLabel="Item" />
+                </ChangeField>
+                <ChangeField label="Quantity" value={newQty} summary={`${newQty} pcs`}>
+                  <ChangeValueInput value={newQty} onChangeText={setNewQty} unit="pcs" accessibilityLabel="Quantity" />
+                </ChangeField>
+              </ChangeRecord>
+              <ChangeRecord id="line-edit" tone="edit" title="Flat-pack cartons — existing line" summary={`Flat-pack cartons — ${editedQty} pcs`}>
+                <ChangeField label="Quantity" before="1,200 pcs" value={editedQty} summary={`${editedQty} pcs`} {...lineEditRow("qty")}>
+                  <ChangeValueInput value={editedQty} onChangeText={setEditedQty} unit="pcs" accessibilityLabel="Line quantity" />
+                </ChangeField>
+              </ChangeRecord>
+            </View>
+          </View>
+        ) : null}
+
+        {phase === "review" && task === "check" ? (
+          <View style={{ gap: 16 }}>
+            <View style={{ gap: 8 }}>
+              <Text size="md" weight="semibold">Documents checked</Text>
+              <View style={{ gap: 8 }}>{picked.map((f, fi) => <FileRow key={f.id} name={f.name} mimeType={f.mimeType} onPress={() => openPreview(picked, fi)} />)}</View>
+            </View>
+            <View style={{ gap: 14 }}>
+              <ChangeReviewHeader title="Findings" />
+              {/* Display-only: findings inform the verdict the footer records.
+                  The kit `Finding` owns severity word · title · detail · the
+                  PROMINENT metric · Sources; hairlines separate them. */}
+              {FINDINGS.map((c, i) => (
+                <Fragment key={c.id}>
+                  {i > 0 ? <Divider /> : null}
+                  <Finding
+                    severity={c.severity}
+                    title={c.title}
+                    detail={c.detail}
+                    sources={(c.sources ?? []).map((name): SourceRef => ({ id: name, label: name, kind: "document" }))}
+                    onOpenSource={() => { /* preview stub */ }}
+                  >
+                    {c.comparison ? <FindingComparison values={c.comparison.values} delta={c.comparison.delta} /> : null}
+                  </Finding>
+                </Fragment>
+              ))}
+            </View>
+          </View>
+        ) : null}
+
+        {phase === "done" ? (
+          <CompletionState title={`${applyCount} ${applyCount === 1 ? "change" : "changes"} applied to PO-2481`} summary="The files stay on the record — each updated field keeps its source document." />
+        ) : null}
+      </DialogScrollArea>
+      {phase === "fork" ? (
+        <DialogFooter>
+          {uploadFlow ? <Button title="Save files only" color="muted" onPress={() => { commitUpload(); closeAi(); }} /> : <Button title="Cancel" color="muted" onPress={closeAi} />}
+          <Button
+            title={taskChoice === "extract" ? "Extract data" : taskChoice === "check" ? "Run cross-check" : taskChoice === "edit" ? "Open chat" : "Run"}
+            color="primary"
+            disabled={taskChoice == null}
+            onPress={() => {
+              if (!taskChoice) return;
+              if (uploadFlow) commitUpload();
+              if (taskChoice === "edit") {
+                // The app→chat handoff — a real app calls the SDK and closes:
+                //   void askAi({
+                //     file_ids: picked.map((f) => f.id),
+                //     record_ids: [orderRecordId],
+                //     prompt: "Update these documents — ",
+                //   });
+                // The messenger opens a fresh chat with the files attached (a
+                // single file also opens previewed beside it); the prompt is
+                // prefilled, editable, never auto-sent.
+                editWithAi(picked);
+                closeAi();
+                return;
+              }
+              startTask(taskChoice);
+            }}
+          />
+        </DialogFooter>
+      ) : phase === "review" && task === "extract" ? (
+        <DialogFooter>
+          {/* N = the kept fields; the minKept swap disables Apply exactly at
+              N = 0 (the registry can't see field-level decisions, so the host
+              gates — and hands Keep-all its own handler). */}
+          <ChangeReviewActions onAcceptAll={keepAll} onDiscard={closeAi} discardLabel="Cancel" onApply={() => setPhase("done")} applyLabel={`Update record (${applyCount})`} minKept={0} applyDisabled={applyCount === 0} />
+        </DialogFooter>
+      ) : phase === "review" && task === "check" ? (
+        <DialogFooter>
+          {/* The findings ARE the outcome — the human reads them and goes to
+              act (Extract, a manual fix). No phantom "record verdict" write:
+              a persisted check-status would go stale on the next edit. */}
+          <Button title="Done" color="primary" onPress={() => { sel.clear(); closeAi(); }} />
+        </DialogFooter>
+      ) : phase === "done" ? (
+        <DialogFooter>
+          <Button title="Done" color="primary" onPress={() => { sel.clear(); closeAi(); }} />
+        </DialogFooter>
+      ) : null}
+    </Dialog>
+    </ChangeReview>
+
+    {/* Create documents — pick from the readiness checklist, generate, land back on the record. */}
+    <Dialog open={genOpen} onOpenChange={(o) => { if (!o) closeGen(); }} maxWidth={560}>
+      <DialogHeader><DialogHeaderTitle>{fillTarget ? `${fillTarget.label} — missing fields` : "Create documents"}</DialogHeaderTitle></DialogHeader>
+      <DialogScrollArea>
+        {fillTarget ? (
+          <View style={{ gap: 14 }}>
+            <Text size="sm" color="muted">These values save onto the order and unlock the document.</Text>
+            {(fillTarget.needs ?? []).map((n) => (
+              <FormTextInput
+                key={n.key}
+                label={n.label}
+                value={fillDraft[n.key] ?? ""}
+                onChangeText={(t) => setFillDraft((d) => ({ ...d, [n.key]: t }))}
+                accessibilityLabel={n.label}
+              />
+            ))}
+          </View>
+        ) : genRunning ? (
+          <AgentRun
+            items={genSteps.slice(0, Math.min(genRevealed + 1, genSteps.length)).map((st, i) => ({
+              type: "step", id: st.id, label: st.label, status: i < genRevealed ? "done" : "running",
+            }))}
+            state={genRevealed >= genSteps.length ? "done" : "streaming"}
+          />
+        ) : !genDone ? (
+          <View>
+            {PRODUCIBLE.map((p, i) => (
+              <Fragment key={p.id}>
+                {i > 0 ? <Divider /> : null}
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 10, minHeight: 44 }}>
+                  <CheckboxInput accessibilityLabel={`Create ${p.label}`} checked={gen.has(p.id)} onChange={(on) => gen.toggle(p.id, on)} />
+                  <View style={{ flex: 1, gap: 1 }}>
+                    <Text size="sm" weight="medium">{p.label}</Text>
+                    {missingOf(p).length > 0 ? (
+                      <Text size="xs" color="warning">{`Missing: ${missingOf(p).map((n) => n.label).join(", ")}`}</Text>
+                    ) : (
+                      <Text size="xs" color="muted">All fields available</Text>
+                    )}
+                  </View>
+                  {missingOf(p).length > 0 ? <Button title="Add missing fields" color="muted" onPress={() => openFill(p)} /> : null}
+                </View>
+              </Fragment>
+            ))}
+          </View>
+        ) : (
+          /* Review-before-commit, not a celebration: the files ARE the
+             message (no count headline), the footer carries the mechanics
+             (no instructional filler), and the one fact the rows can't show
+             is provenance — the single line this screen keeps. */
+          <View style={{ gap: 12 }}>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Icon name="circle-check" size={16} color={colors.emerald[600]} />
+              <Text size="sm" weight="medium">Created from the order's data</Text>
+            </View>
+            <View style={{ gap: 4 }}>
+              {genPending.map((g, gi) => (
+                <FileRow
+                  key={g.id}
+                  name={g.name}
+                  meta={`${g.kind} · ${fmtSize(g.sizeKB)}`}
+                  mimeType={g.mimeType}
+                  onPress={() => openPreview(genPending, gi)}
+                  trailing={
+                    <Button
+                      title="Download"
+                      color="secondary"
+                      icon="download"
+                      accessibilityLabel={`Download ${g.name}`}
+                      onPress={() => { /* a real app: openExternal(g.url) */ }}
+                    />
+                  }
+                />
+              ))}
+            </View>
+          </View>
+        )}
+      </DialogScrollArea>
+      <DialogFooter>
+        {fillTarget ? (
+          <>
+            <Button title="Back" color="muted" onPress={() => setFillTarget(null)} />
+            <Button
+              title="Save fields"
+              color="primary"
+              disabled={(fillTarget.needs ?? []).some((n) => !fillDraft[n.key]?.trim())}
+              onPress={saveFill}
+            />
+          </>
+        ) : genRunning ? null : !genDone ? (
+          <>
+            <Button title="Cancel" color="muted" onPress={closeGen} />
+            <Button title={`Generate ${gen.count} ${gen.count === 1 ? "document" : "documents"}`} color="primary" disabled={gen.count === 0} onPress={generate} />
+          </>
+        ) : (
+          <>
+            <Button title="Discard" color="muted" onPress={closeGen} />
+            <Button title={`Add to record (${genPending.length})`} color="primary" onPress={addGeneratedToRecord} />
+          </>
+        )}
+      </DialogFooter>
+    </Dialog>
+    {/* Rename — small focused dialog; Save disabled while empty. */}
+    <Dialog open={renameTarget != null} onOpenChange={(o) => { if (!o) setRenameTarget(null); }} maxWidth={420}>
+      <DialogHeader><DialogHeaderTitle>Rename file</DialogHeaderTitle></DialogHeader>
+      <DialogScrollArea>
+        <FormTextInput label="Filename" value={renameDraft} onChangeText={setRenameDraft} accessibilityLabel="Filename" />
+      </DialogScrollArea>
+      <DialogFooter>
+        <Button title="Cancel" color="muted" onPress={() => setRenameTarget(null)} />
+        <Button title="Save" color="primary" disabled={renameDraft.trim() === ""} onPress={saveRename} />
+      </DialogFooter>
+    </Dialog>
+    {/* Mounted only while open — its per-file hooks want a stable list. */}
+    {preview ? (
+      <FileGalleryModal
+        files={preview.files}
+        activeIndex={preview.index}
+        onIndexChange={(i) => setPreview((p2) => (i == null || !p2 ? null : { ...p2, index: i }))}
+      />
+    ) : null}
+    </>
+  );
+}