@lotics/ui 28.3.1 → 29.2.0

package/docs/templates.md

@@ -255,17 +255,28 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
   (`AgentRun` in a `FollowScroll`) reads them → `ClarifyWizard` asks the ambiguities the
   analysis surfaced (described options, one custom-answer slot; its Cancel/Back/Next/Submit
   live in the `DialogFooter` — `ClarifyWizardScope` wraps the Dialog, `ClarifyWizardActions`
-  rides the footer) → the IMPORT stream CREATES the records and the dialog ends on the RESULT
-  LIST — one hand-rolled result row per record (outcome mark, what landed, key figures —
-  the anatomy in ai_patterns §the one law; secondary "Done" to dismiss) — the one law's
-  creation branch
-  (ai_patterns.md): no review gate on a create, the register IS the review, correction uses
-  the record's ordinary verbs (no drawer on a bulk landing either). BELOW the
+  rides the footer) → the IMPORT stream DRAFTS the records → the PREVIEW lays every one of
+  them out in full, editable in place → ONE commit creates them → the dialog ends on the
+  RESULT LIST — one hand-rolled result row per record (outcome mark, what landed, key
+  figures — the anatomy in ai_patterns §the one law; secondary "Done" to dismiss).
+  Correction past the receipt uses the record's ordinary verbs (no drawer on a bulk landing
+  either). BELOW the
   dropzone, "or enter manually" → the record VARIANTS as `CardSelectItem`s, each opening the
   same THREE-field create-then-refine form (a single manual create still opens its drawer).
   The template mocks the clarify step as two app-orchestrated phases; a real app can do it in
   ONE run — every app agent carries `ask_user_choice`, so the run parks on the agent's own
   question and `useAgentRun().pendingChoice`/`answerChoice` drive the same `ClarifyWizard`.
+  - **The PREVIEW is the gate, and the fork is who supplied the values.** The import stream
+    DRAFTS; it does not write. Every drafted record then renders in full — all four fields as
+    they will be stored, each editable in place, a `DiffMark` per card, Keep/Drop via
+    `useChangeSet` (`initial: "accepted"` — the operator drops the exceptions rather than
+    approving six identical records) — and ONE commit named for its outcome creates them. The
+    manual form beside it skips all of that and saves direct: the operator typed those three
+    values and read them on the way in. Only the DOCUMENT path needs the gate, because a
+    receipt saying "Created 3 records" is the first moment a misread order reference could
+    have been caught, and by then it is in the data. The receipt still follows the write — it
+    states the outcome, ROUTES, and carries the deterministic checks (a checksum, a count
+    reconciliation) that a person cannot eyeball anyway.
 
 ### `tpl_pick` — the guided queue
 
@@ -676,12 +687,20 @@ menu holds only Rename/Download). Inside its dialog the run FORKS into three tas
 phase runs inside a `FollowScroll` (swapped back to `DialogScrollArea` on the phase flip,
 so review opens at the top):
 
-- **Extract** (read the documents, fill the record) — the open `ChangeFields` review: ONE
-  `Change` section per record whose body stacks 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 + a type-another-value third option. Proposed line items arrive as
-  `ChangeRecord` cards; Keep-all + one outcome-named Apply commit.
+- **Extract** (read the documents, fill the record) — a `DetailTable` of proposed values, each
+  row a label plus a `DiffValue` and its own Keep/Drop, with `useChangeSet` holding the
+  verdicts. **Editing IS the review**; the four shapes are ONE component — an add omits
+  `before`, a removal omits `after` (the struck value IS the change), an update passes both,
+  and a conflict is a `DiffValue` on its placeholder over `CardSelectItem` candidates plus a
+  type-another-value option, Keep gated until one is picked. Proposed line items arrive as a
+  `Table` with `DiffMark` leading each row — a set of lines reads like the ledger it is about.
+  The line table also works the ATTACHMENT case: a dropped invoice's proposal is WHICH LINE it
+  belongs to, so the Document column is a `DiffValue` whose sides are file chips, and a file
+  replacing one already filed shows both with the superseded one struck. Its untouched lines
+  are deliberate — a fixture where every row changed would prove nothing about the screen that
+  matters, and they are why an untouched row draws NO mark: the eye finds the filled discs
+  among the blanks without reading the column.
+  Keep-all + one outcome-named Apply commit.
 - **Cross-check** (compare the documents against the record and each other) — ranked,
   display-only `Finding`s the human acts on, closing in a recorded verdict.
 - **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the

package/examples/tpl_item_list.tsx

@@ -53,6 +53,8 @@ import type { DisplayFile } from "@lotics/ui/file_thumbnail";
 import { InlineSelect } from "@lotics/ui/inline_select";
 import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { useSelection } from "@lotics/ui/use_selection";
+import { DiffMark } from "@lotics/ui/diff_mark";
+import { useChangeSet } from "@lotics/ui/use_change_set";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template, Register — THE canonical register, and the ONE work-execution list
@@ -70,9 +72,17 @@ import { useSelection } from "@lotics/ui/use_selection";
 
 // The customer book the new-case form searches — find-or-create (pick an existing
 // customer or coin a new one) instead of typing a raw name that risks a duplicate.
+// The customer book. The import's preview asks it whether each drafted record's
+// customer already exists, so the two named in `PROPOSED_BY_CUSTOMER` that the
+// wizard's own question calls known ("Blue Harbor Foods isn't in the customer
+// book yet" — implying the other two are) have to actually BE here. They were
+// not, and the old receipt hid it by hardcoding the one new name instead of
+// asking the book; every drafted record now reads as a new customer the moment
+// anything checks. The fixture is the source, so the source has to agree.
 const CUSTOMER_OPTIONS: PickerOption[] = [
   "Northwind Packaging", "Crestline Foods", "Atlas Components", "Summit Logistics",
   "Michael Torres", "Anna Whitfield", "Robert Hayes", "Karen Mitchell",
+  "Meridian Trading Co.", "Northgate Textiles",
 ].map((name) => ({ value: name, label: name }));
 
 // The assignable roster — an app feeds `useMembers()` here.
@@ -385,13 +395,24 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 // ─── Enter data — the INTAKE fork ────────────────────────────────────────────
 // AI FIRST, form as fallback. The one "Enter data" CTA opens a phased dialog:
 // drop files (the hero) → a short ANALYZE stream reads them → the run asks the
-// genuine ambiguities the analysis surfaced → the IMPORT stream
-// CREATES the records and the dialog ends on the RESULT LIST — one row per
-// record with its key figures. This is the one law's creation branch: no
-// review gate on a create (nothing to diff — the register IS the review);
-// correction uses the record's ORDINARY verbs (open it, edit or delete);
-// `ChangeReview` belongs to the record page, where a SINGLE existing record
-// is being modified.
+// genuine ambiguities the analysis surfaced → the IMPORT stream DRAFTS the
+// records → the PREVIEW lays every drafted record out in full, every field
+// editable in place → one commit creates them → the RECEIPT states the outcome
+// and routes.
+//
+// The preview is the one law's DOCUMENT-create branch, and the fork is WHO
+// supplied the values, not whether a before-state exists. The manual form below
+// skips it and saves direct — the operator typed those three values and read
+// them on the way in. These came off a spreadsheet nobody has read, and a
+// receipt saying "Created 3 records" is the first moment a misread order
+// reference could have been caught, by which point it is in the data. So the
+// values are shown BEFORE the write, as they will be stored, editable where
+// they are wrong.
+//
+// It is deliberately not a diff. Nothing exists to compare against, so the
+// whole record is the review; `DiffMark` earns its place only for the one fact
+// that IS relational — whether each record's customer matched the book or is
+// being created alongside it.
 // Below the dropzone, the MANUAL variants (each flavors the same 3-field
 // create-then-refine gate). The mock plays the clarify step as two phases; a
 // real app can run it as ONE agent run — every app agent carries
@@ -400,11 +421,16 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 // shape: the mock below satisfies the same `AgentRunLike` the hook does.
 
 type Part = UIMessagePart<UIDataTypes, UITools>;
-type IntakePhase = "intake" | "analyze" | "clarify" | "running" | "done" | "form";
+type IntakePhase = "intake" | "analyze" | "clarify" | "running" | "preview" | "done" | "form";
 type ManualVariant = "export" | "import";
 
 type Proposal = { id: string; khach: string; dienThoai: string; phi: number; orders: string };
 
+/** The preview's editable copy of one drafted record — the run's output after
+ *  the operator has had it. Local state, seeded ONCE when the draft stream ends;
+ *  a real app seeds it from the run's structured output the same way. */
+type Draft = Proposal & { newCustomer: boolean };
+
 // What the (mock) import drafts, per the wizard's grouping answer. A real app
 // takes these from the import run's structured output.
 const PROPOSED_BY_CUSTOMER: Proposal[] = [
@@ -452,8 +478,10 @@ const importScript = (grouping: "customer" | "order"): Part[] => [
   { type: "reasoning", text: grouping === "customer" ? "Group the six orders under their three customers, one record each, fees summed per customer." : "One record per order — six records, fees split from the order totals." },
   doneTool("i1", "Extract order lines"),
   doneTool("i2", "Match customers"),
-  doneTool("i3", grouping === "customer" ? "Create 3 records" : "Create 6 records"),
-  { type: "text", text: `Created **${grouping === "customer" ? 3 : 6} records** — they are in the register.` },
+  doneTool("i3", grouping === "customer" ? "Draft 3 records" : "Draft 6 records"),
+  // DRAFTED, not created — the stream's closing line must not claim a write
+  // that has not happened. The operator sees them next, in full, and presses.
+  { type: "text", text: `Drafted **${grouping === "customer" ? 3 : 6} records** — check them below before they are created.` },
 ];
 
 /** The manual gate stays the THREE-field create-then-refine form — past the
@@ -481,12 +509,23 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   // on the created records (create + link, leave unlinked, or the user's own
   // instruction via the custom slot).
   const [customerPlan, setCustomerPlan] = useState("New customer created and linked");
+  // What the import DRAFTED — the preview's working copy, seeded once when the
+  // draft stream ends and edited in place from then on. It is not server data
+  // (nothing is stored yet), so it is the one thing here that legitimately
+  // lives in `useState`.
+  const [drafts, setDrafts] = useState<Draft[]>([]);
   // the RECEIPT — what the import CREATED. A real app READS BACK what the
   // save stored (values + record ids) and runs its DETERMINISTIC checks over
   // the stored values (a reference checksum, a count reconciliation). ONE
   // record renders its receipt directly; several render the attention-first
   // register whose rows press straight through to the records.
   const [landed, setLanded] = useState<{ id: string; title: string; detail: string; ref: string; refFlagged: boolean; fee: string }[]>([]);
+  // Keep/Drop over the drafted records. Everything is IN by default: the
+  // operator's job here is to catch the wrong one, not to approve six right
+  // ones — `initial: "pending"` would turn a review into a second round of
+  // data entry. Nothing is gated on `settled` for the same reason.
+  const kept = useChangeSet(drafts.map((d) => d.id));
+
   // form state (the manual gate)
   const [khach, setKhach] = useState("");
   const [dienThoai, setDienThoai] = useState("");
@@ -547,26 +586,19 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           // Auto-advance: analysis flows into the wizard.
           setTimeout(() => setPhase("clarify"), 500);
         } else {
-          // The import SAVES as it lands — the records are created here, and the
-          // dialog advances to the result list where each row carries Undo.
+          // The import DRAFTS — nothing is written here. The drafts go to the
+          // preview, which is the gate; the write happens on one press there.
           setTimeout(() => {
             const proposals = grouping === "customer" ? PROPOSED_BY_CUSTOMER : PROPOSED_BY_ORDER;
-            onCreateMany(proposals.map((p) => ({ khach: p.khach, dienThoai: p.dienThoai, phi: p.phi })));
-            const rows = proposals.map((p) => ({
-              id: p.id,
-              title: grouping === "customer" ? p.khach : `${p.orders} — ${p.khach}`,
-              // The wizard's answers are load-bearing: the unknown customer's row
-              // states how it landed (created + linked / left unassigned / the
-              // user's own instruction).
-              detail: [p.dienThoai, formatMoney(p.phi), p.khach === "Blue Harbor Foods" ? customerPlan : ""].filter(Boolean).join(", "),
-              ref: p.orders,
-              // The mock flags one record's reference (a failed checksum); a
-              // real app computes this over the STORED value.
-              refFlagged: p.khach === "Blue Harbor Foods",
-              fee: String(p.phi),
-            }));
-            setLanded(rows);
-            setPhase("done");
+            setDrafts(
+              proposals.map((p) => ({
+                ...p,
+                // The one relational fact in a screen full of new values, and
+                // the only thing here a `DiffMark` can honestly say.
+                newCustomer: !CUSTOMER_OPTIONS.some((o) => o.label === p.khach),
+              })),
+            );
+            setPhase("preview");
           }, 500);
         }
       }
@@ -584,6 +616,8 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   const reset = () => {
     setPhase("intake");
     setDocs([]);
+    setDrafts([]);
+    kept.reset();
     setLanded([]);
     setCustomerPlan("New customer created and linked");
     setKhach("");
@@ -592,6 +626,41 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   };
   const close = () => { onOpenChange(false); reset(); };
 
+  /**
+   * THE COMMIT. It writes what is on screen — the edited drafts, minus the
+   * dropped ones — and only then computes the receipt, over the values that
+   * were actually stored.
+   *
+   * The deterministic checks belong on THIS side of the write for the reason
+   * the one law gives: a person cannot eyeball-verify a checksum, so the
+   * preview is where human judgment applies (is this the right customer, is
+   * that fee plausible) and the receipt is where arithmetic does.
+   */
+  const commitDrafts = () => {
+    const writing = drafts.filter((d) => kept.status(d.id) !== "rejected");
+    if (writing.length === 0) return;
+    onCreateMany(writing.map((d) => ({ khach: d.khach, dienThoai: d.dienThoai, phi: d.phi })));
+    setLanded(
+      writing.map((d) => ({
+        id: d.id,
+        title: grouping === "customer" ? d.khach : `${d.orders} — ${d.khach}`,
+        // The wizard's answers are load-bearing: the unknown customer's row
+        // states how it landed (created + linked / left unassigned / the
+        // user's own instruction).
+        detail: [d.dienThoai, formatMoney(d.phi), d.newCustomer ? customerPlan : ""].filter(Boolean).join(", "),
+        ref: d.orders,
+        // The mock flags one record's reference (a failed checksum); a real app
+        // computes this over the STORED value.
+        refFlagged: d.orders.includes("PO-7313"),
+        fee: String(d.phi),
+      })),
+    );
+    setPhase("done");
+  };
+
+  const editDraft = (id: string, patch: Partial<Draft>) =>
+    setDrafts((prev) => prev.map((d) => (d.id === id ? { ...d, ...patch } : d)));
+
   const createManual = () => {
     if (khach.trim() === "") return;
     onCreate(khach.trim(), dienThoai.trim(), phi ?? 0);
@@ -601,6 +670,9 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   const title =
     phase === "form" ? (variant === "export" ? "New export case" : "New import case")
     : phase === "intake" ? "Enter data"
+    // Named for what the operator is about to DO, not for the machinery: they
+    // are checking records, and the count is the size of the job.
+    : phase === "preview" ? `Check ${drafts.length} drafted ${drafts.length === 1 ? "record" : "records"}`
     : phase === "done" ? "Saved"
     : "Import from files";
 
@@ -693,6 +765,89 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           <AgentRunPane run={run} onCancel={() => setPhase("intake")} />
         ) : null}
 
+        {phase === "preview" ? (
+          // THE GATE. Every drafted record, laid out as it will be STORED — all
+          // four fields, not a three-line summary — and every one of them
+          // editable where it sits. The law's reason for editing over
+          // accept/reject: a wrong proposal you can fix costs a keystroke, one
+          // you can only reject costs the whole re-entry.
+          <DialogScrollArea>
+            <View style={{ gap: 12 }}>
+              <Text size="xs" color="muted">
+                Nothing is saved yet. Correct anything that is wrong, drop what should not be created, then create the rest.
+              </Text>
+              {drafts.map((d) => {
+                const dropped = kept.status(d.id) === "rejected";
+                const title = grouping === "customer" ? d.khach : d.orders;
+                return (
+                  <View key={d.id} style={{ borderWidth: 1, borderColor: colors.zinc[200], borderRadius: 12, overflow: "hidden" }}>
+                    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, paddingVertical: 8, backgroundColor: colors.zinc[50] }}>
+                      {/* The mark says what will happen to this card. Emphasised
+                          because the preview is scanned, not read: a filled
+                          shape per card is found without reading the column. */}
+                      <DiffMark kind={dropped ? "removed" : "added"} />
+                      <Text size="sm" weight="semibold" style={{ flex: 1 }} numberOfLines={1}>{title}</Text>
+                      {dropped ? (
+                        <Link size="sm" onPress={() => kept.undo(d.id)} accessibilityLabel={`Keep ${title}`}>Keep</Link>
+                      ) : (
+                        <Link size="sm" onPress={() => kept.reject(d.id)} accessibilityLabel={`Do not create ${title}`}>Don&rsquo;t create</Link>
+                      )}
+                    </View>
+                    {/* A dropped card COLLAPSES rather than dimming in place:
+                        its fields are not going to be written, so leaving them
+                        legible-but-grey invites edits to a record that will not
+                        exist. The header keeps its identity and the Keep verb. */}
+                    {dropped ? null : (
+                      <View style={{ paddingHorizontal: 12 }}>
+                        <DetailTable>
+                          <DetailRow
+                            label="Customer"
+                            description={d.newCustomer ? customerPlan : undefined}
+                          >
+                            <InlineTextInput
+                              value={d.khach}
+                              onSave={(v) => editDraft(d.id, { khach: v })}
+                              accessibilityLabel={`Customer for ${title}`}
+                            />
+                          </DetailRow>
+                          <DetailRow label="Orders">
+                            <InlineTextInput
+                              value={d.orders}
+                              onSave={(v) => editDraft(d.id, { orders: v })}
+                              accessibilityLabel={`Orders for ${title}`}
+                            />
+                          </DetailRow>
+                          <DetailRow label="Phone">
+                            {/* The document carried no phone for one of these.
+                                An empty box would read as "blank" — a value
+                                somebody chose — so the placeholder NAMES the
+                                absence: unknown is not empty. */}
+                            <InlineTextInput
+                              value={d.dienThoai}
+                              placeholder="Not on the document"
+                              onSave={(v) => editDraft(d.id, { dienThoai: v })}
+                              accessibilityLabel={`Phone for ${title}`}
+                            />
+                          </DetailRow>
+                          <DetailRow label="Service fee">
+                            <InlineNumberInput
+                              value={d.phi}
+                              min={0}
+                              format={(v) => (v == null ? "" : formatMoney(v))}
+                              onSave={(v) => editDraft(d.id, { phi: v ?? 0 })}
+                              accessibilityLabel={`Service fee for ${title}`}
+                            />
+                          </DetailRow>
+                        </DetailTable>
+                      </View>
+                    )}
+                  </View>
+                );
+              })}
+            </View>
+          </DialogScrollArea>
+        ) : null}
+
         {phase === "done" ? (
           // The RECEIPT (ai_patterns §the one law): states the outcome and
           // routes — NOTHING here edits; the RECORD is the edit surface,
@@ -804,6 +959,24 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           <DialogFooter>
             <AgentRunActions run={run} />
           </DialogFooter>
+        ) : phase === "preview" ? (
+          <DialogFooter>
+            <Button
+              title="Back"
+              color="secondary"
+              onPress={() => { setDrafts([]); kept.reset(); setPhase("intake"); }}
+            />
+            {/* Named for its OUTCOME and carrying the count that will actually
+                be written — never "Apply", never the proposal count. Disabled
+                at zero kept, which is the only state where the press would do
+                nothing. */}
+            <Button
+              title={`Create ${kept.keptCount} ${kept.keptCount === 1 ? "record" : "records"}`}
+              color="primary"
+              disabled={kept.keptCount === 0}
+              onPress={commitDrafts}
+            />
+          </DialogFooter>
         ) : phase === "done" ? (
           <DialogFooter>
             {/* Dismissal, not an action — the records already landed. */}