@lotics/ui 27.13.0 → 27.13.2

package/docs/composition.md

@@ -494,7 +494,7 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   (colored `Text`), not the buttons.
 - **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". A create is `primary` and
   rides its section's HEADING row at the right edge — see § The add-placement law for why, and
-  for the one-verb-one-weight rule that keeps it primary in the `EmptyState` too. (The
+  for the one-verb-one-weight rule that keeps it `primary` wherever it renders. (The
   icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps its glyph.)
 
 ## The action-gating law — disabled + the reason as a co-located Callout
@@ -600,11 +600,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
 
   The ADD is the one verb this law does NOT place next to its effect, and the add-placement law
   says why: a position that never moves beats a position that is adjacent, because "below the
-  last row" is a different place on every list and no place at all on an empty one.
-  **An add is `primary`, in the `EmptyState` too.** It is the act its section offers, so it
-  carries that section's weight; a lone `secondary` button reads as though the real action were
-  somewhere else. The rule that matters is that ONE VERB KEEPS ONE WEIGHT — the same add must
-  not be primary on an empty list and secondary on a full one.
+  last row" is a different place on every list and no place at all on an empty one. The heading
+  row therefore carries identity + meta + view controls + the section's ADD, and no other content
+  verb. **An add is `primary` wherever it renders** — on that heading row, or inside an
+  `EmptyState` in the one case § Empty states allows, where there is no heading to carry it. It
+  is the act its section offers, so it carries that section's weight; a lone `secondary` button
+  reads as though the real action were somewhere else. The rule that matters is that ONE VERB
+  KEEPS ONE WEIGHT — the same add must not be primary on an empty list and secondary on a full one.
   A record surface therefore carries several primaries, one per section, and that is correct:
   "one primary per SCREEN" governs the page BAND, not a stack of independent sections each with
   its own single act. The cost is real and worth knowing — the more sections offer an act, the

package/docs/data_entry.md

@@ -13,6 +13,7 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 | You're capturing… | Reach for | Why |
 |---|---|---|
 | an EXISTING record's fields | [**Inline edit**](#inline-edit--the-preferred-way-to-edit-an-existing-record) (`Inline*`) | edit in place, no form mode |
+| a DRAFT inside a `Dialog` (create / edit-then-save) | [**`FormField` / `FormTextInput`**](#a-dialog-is-a-draft--use-formfield-never-an-inline-editor), controlled | the dialog's action IS the commit; inline editors make everything derived from the draft lag by one blur |
 | a value in a DENSE ROW / register `DataGrid` cell (a task's due, assignee, status) | the SAME `Inline*` editor in **`variant="bare"`** | one editor per value type; `bare` drops the resting frame (the grid already promises every cell edits) and fades the same border in on hover — there is no separate `*Cell` family |
 | a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
 | a RELATED record (pick or make) | [**find-or-create**](#find-or-create--the-combobox-family-is-the-control) (`Combobox allowCustom`) | one control covers both |
@@ -41,6 +42,36 @@ the CONTROL COLUMN, the same left edge the user just filled, and inherits stacke
 narrow containers. A right-floated button aligns to nothing; only OVERLAY footers
 (`DialogFooter`/`DrawerFooter`) right-align. Worked: `tpl_record`'s Delivery receipt.
 
+### A dialog is a draft — use `FormField`, never an `Inline*` editor
+
+An inline editor SELF-PERSISTS: it holds a local draft and reports it on blur (or Enter). A
+`FormField` wraps a draft **validated and committed together**. A create/edit **`Dialog` is
+definitionally the second** — its Save/Create is the commit — so build it from `FormField` /
+`FormTextInput` with controlled `value` + `onChangeText`, even when the record surface behind it
+is a grid of inline editors.
+
+This is **not** a safety rule, and it does not soften the press-gate law below ("Commit-on-blur
+would race the press that caused it"): inline editors in a dialog lose nothing, because `Button`
+already holds its press until the blur's commit settles. The gate makes the press SAFE. What it cannot do is make the dialog HONEST
+while the field still has focus — it only acts at press time, and everything **derived** from the
+draft trails the typing until then: a validity `error`, a Save gated on that validity, a computed
+total. Type a valid value and the form still says invalid, and its Save still sits disabled, until
+focus leaves. That is the dialog arguing with the box the reader is looking at, and no amount of
+press-gating answers it, because the reader is not pressing anything yet.
+
+Controlled inputs make derived state track what is on screen, and read shorter than the editors
+they replace — four `DetailRow` + `Inline*` pairs whose `onSave` exists only to `setState` collapse
+to four fields. Worked example: `tpl_record`'s New-customer dialog.
+
+**But do not then derive the ERROR per keystroke** — the mistake controlled inputs invite, and the
+opposite failure to the one above. Validity and the error MESSAGE are different questions. Validity
+gates the commit and is checked continuously; the message claims the reader did something wrong, so
+it may only be made once they are DONE. Every prefix of a correct fixed-length value is invalid, so
+a per-keystroke message turns the first digit of a right answer into a red complaint. Gate the
+message on a `touched` flag set `onBlur`, keep the commit gated on the real validity, and let a
+showing error clear live as the value becomes valid — the shape [`useForm`](../src/use_form.ts)
+already has: errors arrive from a validate pass, and editing a field clears that field's error.
+
 ## Inline edit — the preferred way to edit an existing record
 
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a

package/docs/templates.md

@@ -53,6 +53,22 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | AI ranks answers — look-up-and-explain | `tpl_lookup` |
 | AI over a record's documents (extract / cross-check / generate) | `tpl_record` — its Documents + Document set sections |
 
+### Register + drawer, or a navigated page?
+
+The register is the DEFAULT, and its row press opens the workspace `Drawer`. A record earns
+its own navigated route only when one of these holds:
+
+- **It is a destination.** Someone arrives cold from outside the register — a link in an
+  email, a notification, a handoff from another desk — and must land on the record without
+  the list to open it from.
+- **The work needs the canvas.** A docked comments gutter, a document read beside the fields,
+  an outline rail worth navigating — width the drawer's single column cannot give.
+
+The volume of DATA is not the test. A record with forty fields still closes in the drawer if
+the operator opens it from the list, works it, and goes back to the list. What an app without
+a destination skips is the ROUTE, never the template: the drawer renders `tpl_record` either
+way, so "no record page" must never become a hand-built detail surface.
+
 ## Composition rules — how a record surface is assembled
 
 Laws for any screen where a record's data is edited and a primary action produces its output
@@ -268,7 +284,10 @@ billing, and quick-capture templates. Top → bottom:
   ATTENTION state as a co-located `Callout` (e.g. overdue — record-scoped state reads here;
   field-scoped state stays on its field), then a quiet `SummaryLine` (desk, documents
  , to collect).
-- **GENERAL — the MAIN details, FIRST in the rail**; every later section is supplementary.
+- **GENERAL — the MAIN details, first in THIS record's rail** because its work starts at the
+  details; rule 1 orders sections by work flow, so a surface whose work starts at a DOCUMENT
+  (an invoice desk, a claims desk) leads with Documents and General follows. Every later
+  section is supplementary.
   A `SubsectionStack` (space-only beat) of a headingless LEAD group (the key facts) plus
   named groups (e.g. Order / Fulfilment / System — system identifiers get a HOME, not a
   per-row badge). Every group's `DetailTable` repeats the same `labelWidth` so the grid
@@ -323,7 +342,9 @@ billing, and quick-capture templates. Top → bottom:
   a floating `Callout`. Transport's three party rows are the same shape repeated, which is where
   it earns itself: N references as field rows scan as one list, where N cards would be a wall.
   Empty state = the find-or-create `Combobox` in the same value slot, custom row → the create
-  `Dialog` (tax ID + Fetch; its field errors ride `DetailRow error`, not a loose line).
+  `Dialog` (tax ID + Fetch). That dialog is built from **`FormField` / `FormTextInput`, never the
+  record surface's `Inline*` editors** — see [data_entry.md](./data_entry.md) §"A dialog is a
+  draft".
   **Reference (the buyer's own) is the `actions` worked example**: its `Copy` is an
   `InlineButton` ON the field, passed unconditionally and `disabled` while empty — not in the
   row's `trailing`, and not conditional, which would resize the field as you type.

package/examples/tpl_record.tsx

@@ -1036,7 +1036,9 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   // — and the draft names its destination as DATA instead of the dialog holding a
   // callback, so what is in flight stays inspectable and the commit stays one
   // function.
-  const [custDraft, setCustDraft] = useState<{ target: PartyTarget; name: string; taxId: string; contact: string; city: string } | null>(null);
+  // `taxIdTouched` is what decides whether the tax ID's format error may SHOW —
+  // see `taxIdError` for why a controlled field must not simply derive it.
+  const [custDraft, setCustDraft] = useState<{ target: PartyTarget; name: string; taxId: string; contact: string; city: string; taxIdTouched: boolean } | null>(null);
   // The Fetch button's in-flight state (the registry lookup).
   const [fetching, setFetching] = useState(false);
 
@@ -1369,11 +1371,22 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
       attachParty[target](opt.value);
       return;
     }
-    setCustDraft({ target, name: opt.value, taxId: "", contact: "", city: "" });
+    setCustDraft({ target, name: opt.value, taxId: "", contact: "", city: "", taxIdTouched: false });
   };
 
-  const taxIdError =
-    custDraft && custDraft.taxId && !TAX_ID_RE.test(custDraft.taxId.trim()) ? "Tax ID is 10 or 13 digits" : undefined;
+  // Two different questions, and conflating them is the trap a controlled field
+  // walks into. VALIDITY gates the commit and is checked continuously. The
+  // ERROR MESSAGE is a claim that the reader did something wrong, and it may
+  // only be made once they are DONE — every prefix of a correct 10-digit id is
+  // invalid, so deriving the message per keystroke turns "1" into a red
+  // complaint and shouts at someone typing the right answer.
+  //
+  // Blur is "done", which is why `taxIdTouched` gates only the message. Once it
+  // is showing, it clears the moment the value becomes valid — the same shape
+  // `useForm` has: errors arrive from a validate pass, and editing a field
+  // clears that field's error.
+  const taxIdInvalid = !!custDraft && custDraft.taxId.trim() !== "" && !TAX_ID_RE.test(custDraft.taxId.trim());
+  const taxIdError = taxIdInvalid && custDraft?.taxIdTouched ? "Tax ID is 10 or 13 digits" : undefined;
 
   const createAndAttach = () => {
     if (!custDraft) return;
@@ -3217,46 +3230,53 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
 
       {/* find-or-create's CREATE branch — a focused Dialog (4 fields is
           dialog-weight; an inline swap shifts the page). Essentials only: the
-          dialog's Fetch fills contact + city off the tax ID. */}
+          dialog's Fetch fills contact + city off the tax ID.
+
+          FORM controls, not the record surface's inline editors, and that is the
+          whole point of the dialog: an inline editor SELF-PERSISTS on blur, a
+          `FormField` wraps a draft validated and committed TOGETHER. This dialog
+          is definitionally the second, so it is built from the second.
+
+          It was built from the first, and NOTHING WAS LOST BY THAT — the kit
+          gates the press (`pending_commits`), so `Create & attach` waited for the
+          blur's commit and a typed tax ID always survived. This is not a bug fix;
+          the safety was never in question.
+
+          What the gate cannot do is make the dialog honest BEFORE the press. It
+          acts at press time, so until then everything derived from the draft
+          trails the typing: with a valid id on screen the field still read
+          invalid and the button still sat disabled, until focus left. The reader
+          is not pressing anything yet, so no press-gating answers it.
+
+          Controlled inputs make derived state track what is on screen — and cost
+          less to read than the editors they replace. */}
       <Dialog width={520} open={custDraft !== null} onOpenChange={(o) => { if (!o) setCustDraft(null); }}>
         <DialogHeader>
           <DialogHeaderTitle>New customer</DialogHeaderTitle>
         </DialogHeader>
-        {/* the same inline-chip table vocabulary as the record's field grids —
-            only the commit differs (Create & attach) */}
-        <View style={{ paddingHorizontal: 24, paddingBottom: 12, gap: 8 }}>
-          <DetailTable labelWidth={150}>
-            <DetailRow label="Customer name">
-              <InlineTextInput
-                value={custDraft?.name ?? ""}
-                onSave={(v) => {
-                  setCustDraft((d) => (d ? { ...d, name: v } : d));
-                  return Promise.resolve();
-                }}
-                placeholder="Add legal name…"
-                accessibilityLabel="Customer name"
-              />
-            </DetailRow>
-            {/* the field-level failure rides the ROW (`DetailRow error` —
-                FormField's alert semantics), not a loose line below the table */}
-            <DetailRow label="Tax ID" error={taxIdError}>
-              {/* Fetch is NOT a verb about this value — it reads the tax ID and
-                  fills the contact and city BELOW it, so it belongs to the form,
-                  not to the field (which is why it isn't an `InlineButton` in
-                  `actions`). It composes into a row inside this value cell, so
-                  it costs the one row that wants it instead of a column every
-                  row would reserve. */}
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flex: 1 }}>
+        <View style={{ paddingHorizontal: 24, paddingBottom: 12, gap: 16 }}>
+          <FormTextInput
+            label="Customer name"
+            value={custDraft?.name ?? ""}
+            onChangeText={(v) => setCustDraft((d) => (d ? { ...d, name: v } : d))}
+            placeholder="Add legal name…"
+          />
+          {/* Fetch is NOT a verb about this value — it reads the tax ID and
+              fills the contact and city BELOW it, so it belongs to the form, not
+              to the field. It composes into a row inside this field, so it costs
+              the one field that wants it instead of a column every field would
+              reserve. `FormField` + a bare input (rather than `FormTextInput`)
+              is what lets the button share the line while the label, error and
+              a11y wiring still belong to the input. */}
+          <FormField label="Tax ID" error={taxIdError}>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
               <View style={{ flex: 1, minWidth: 0 }}>
-              <InlineTextInput
-                value={custDraft?.taxId ?? ""}
-                onSave={(v) => {
-                  setCustDraft((d) => (d ? { ...d, taxId: v } : d));
-                  return Promise.resolve();
-                }}
-                placeholder="Add tax ID…"
-                accessibilityLabel="Tax ID"
-              />
+                <TextInputField
+                  value={custDraft?.taxId ?? ""}
+                  onChangeText={(v) => setCustDraft((d) => (d ? { ...d, taxId: v } : d))}
+                  onBlur={() => setCustDraft((d) => (d ? { ...d, taxIdTouched: true } : d))}
+                  placeholder="Add tax ID…"
+                />
               </View>
               <Button
                 title="Fetch"
@@ -3265,35 +3285,28 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                 disabled={!TAX_ID_RE.test((custDraft?.taxId ?? "").trim())}
                 onPress={fetchIntoDraft}
               />
-              </View>
-            </DetailRow>
-            <DetailRow label="Contact">
-              <InlineTextInput
-                value={custDraft?.contact ?? ""}
-                onSave={(v) => {
-                  setCustDraft((d) => (d ? { ...d, contact: v } : d));
-                  return Promise.resolve();
-                }}
-                placeholder="Add contact…"
-                accessibilityLabel="Contact"
-              />
-            </DetailRow>
-            <DetailRow label="City">
-              <InlineTextInput
-                value={custDraft?.city ?? ""}
-                onSave={(v) => {
-                  setCustDraft((d) => (d ? { ...d, city: v } : d));
-                  return Promise.resolve();
-                }}
-                placeholder="Add city…"
-                accessibilityLabel="City"
-              />
-            </DetailRow>
-          </DetailTable>
+            </View>
+          </FormField>
+          <FormTextInput
+            label="Contact"
+            value={custDraft?.contact ?? ""}
+            onChangeText={(v) => setCustDraft((d) => (d ? { ...d, contact: v } : d))}
+            placeholder="Add contact…"
+          />
+          <FormTextInput
+            label="City"
+            value={custDraft?.city ?? ""}
+            onChangeText={(v) => setCustDraft((d) => (d ? { ...d, city: v } : d))}
+            placeholder="Add city…"
+          />
         </View>
         <DialogFooter>
           <Button title="Cancel" color="secondary" onPress={() => setCustDraft(null)} />
-          <Button title="Create & attach" color="primary" disabled={(custDraft?.name.trim() ?? "") === "" || !!taxIdError} onPress={createAndAttach} />
+          {/* Gated on the VALIDITY, never on the visible message: an invalid id
+              must not commit just because the reader has not blurred out of the
+              field yet. Pressing here blurs first, so the explanation appears in
+              the same gesture that finds the button disabled. */}
+          <Button title="Create & attach" color="primary" disabled={(custDraft?.name.trim() ?? "") === "" || taxIdInvalid} onPress={createAndAttach} />
         </DialogFooter>
       </Dialog>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "27.13.0",
+  "version": "27.13.2",
   "type": "module",
   "exports": {
     "./vite": {

package/src/detail_row.tsx

@@ -204,7 +204,7 @@ export function DetailRow(props: DetailRowProps) {
           {flatTuck !== 0 ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
         </View>
       ) : (
-        <View style={annotated ? styles.valueStack : undefined}>
+        <View style={[styles.spreadValue, annotated && styles.valueStack]}>
           <View style={[styles.controlLine, { minHeight }]}>{children}</View>
           {flatTuck !== 0 ? <View style={{ marginTop: flatTuck }}>{annotations}</View> : annotations}
         </View>
@@ -239,7 +239,20 @@ const styles = StyleSheet.create({
     alignItems: "flex-start",
     gap: 12,
   },
-  flexLabel: { flex: 1 },
+  // Spread mode's label column. `flexGrow` is what pushes the value to the right
+  // edge; the BASIS is what stops the push from eating the label. It was
+  // `flex: 1` — grow 1, shrink 1, basis **0** — so the label entered the layout
+  // claiming no size at all, and a value too wide for the row (a company name in
+  // a stacked register) took the whole row while the label absorbed the entire
+  // deficit: measured at 0px wide and 140px tall, "Hợp đồng" set one character
+  // per line down the page.
+  //
+  // With `basis: auto` the label enters at its TEXT width, so a deficit is split
+  // between the two in proportion to what each actually asked for — a long value
+  // is the one that gives way, because it is the one that is long. Both stay
+  // shrinkable on purpose: a long LABEL against a short value has to wrap too,
+  // and pinning the label unshrinkable would just overflow the row the other way.
+  flexLabel: { flexGrow: 1, flexShrink: 1, flexBasis: "auto" },
   // `center` is what makes a WRAPPED label align sanely, and it does both jobs
   // with no measurement: a one-line label is shorter than the control band, so
   // it centers on the control line (the alignment law); a wrapped label is as
@@ -255,6 +268,12 @@ const styles = StyleSheet.create({
   // The 2px between the control line and the annotation block beneath it — the
   // same rhythm `FieldAnnotations` puts between its own lines.
   valueStack: { gap: 2 },
+  // Spread mode's value. A React Native `View` does NOT shrink by default
+  // (`flexShrink: 0`, unlike the web), so without this a wide value simply keeps
+  // its intrinsic width — overflowing the row and pushing the whole deficit onto
+  // the label. `minWidth: 0` is the half that lets a text value actually wrap
+  // rather than stopping at its longest word.
+  spreadValue: { flexShrink: 1, minWidth: 0 },
   // Form mode (labelWidth set): the value column FILLS the row so every inline
   // editor spans the SAME width — and none jumps wider when it swaps to the
   // (flex:1) edit control. A stretch column, so an InlineEditView / InlineStatic