@lotics/ui 27.13.1 → 27.13.3

package/MIGRATION.md

@@ -4,6 +4,25 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 27.13.3 — a stacked `Table` row's identity cell no longer renders its column label
+
+No API change, but the rendered output changed on NARROW containers only (below the
+two-column floor, where `Table` stacks). The identity cell — column 0 — used to render as a
+`DetailRow` spread like every other cell, so its column label appeared beside the value. It
+now heads the row bare. **A test or script that finds that label inside a stacked row must be
+updated**:
+
+```ts
+// a 375px-wide register whose first column is labelled "Customer"
+getByText("Customer")   // BEFORE — the identity cell's label, once per ROW
+                        // AFTER  — matches the column HEADER only (wide containers)
+```
+
+Field cells (index ≥ 1) keep their labels, and register mode is untouched — this is stacked
+mode only. The label restated the value it sat beside (`Customer` over `Northwind Packaging`),
+and it had nowhere to go: a label and a full-width identity on one line with nothing to give
+made the label collapse under a long value, which is what a narrow register used to render.
+
 ## 27.4.0 — a `Select` trigger announces as `combobox`, not `button`
 
 No API change, but the DOM and the accessibility tree changed, so **a test or script that

package/docs/catalog.md

@@ -973,9 +973,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
   the width can't fit every column it hides columns by `TableColumn.priority` (higher drops
   first; default = column order, rightmost first; column 0 — the identity — never drops), and
-  below the two-column floor every row STACKS: each cell renders as a `DetailRow`-spread
-  line (muted label left, value at the right edge — one vocabulary with the drawer's detail
-  rows), the lines sitting on the identity column's text edge, never under the checkbox;
+  below the two-column floor every row STACKS: the identity cell (column 0) HEADS the pile
+  unlabelled — its column name would only restate the value — and each REMAINING cell renders
+  as a `DetailRow`-spread line (muted label left, value at the right edge — one vocabulary with
+  the drawer's detail rows), the lines sitting on the identity column's text edge, never under the checkbox;
   the header band gives way, so sorting is a wide-container affordance. Rows carry TWO right-side slots: `action`
   (the primary CTA `Button` — register: in the trailing gutter; stacked: closes the content,
   right-aligned) and `trailing` (the ⋯ overflow — stays beside the identity on the top line).

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

@@ -342,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.1",
+  "version": "27.13.3",
   "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

package/src/table.tsx

@@ -229,7 +229,10 @@ export function TableRow(props: TableRowProps) {
     // A dropped column drops its cell (stacked shows everything). Cells beyond
     // the declared columns stay — same tolerance as the width mapping.
     .filter(({ column }) => ctx.stacked || column == null || ctx.visibleKeys.has(column.key))
-    .map(({ cell, column }) => cloneElement(cell, { _column: column, _stacked: ctx.stacked }));
+    // Index 0 is the identity cell — it HEADS the stacked pile rather than becoming
+    // one of its labelled field lines. (Safe to read post-filter: stacked mode drops
+    // no cell, and column 0 never drops in register mode either.)
+    .map(({ cell, column }, i) => cloneElement(cell, { _column: column, _stacked: ctx.stacked, _primary: i === 0 }));
 
   const body = ctx.stacked ? (
     <View style={styles.stackedBody}>
@@ -314,19 +317,31 @@ export interface TableCellProps {
   _column?: TableColumn;
   /** @internal — injected by `TableRow`; the Table is in stacked mode. */
   _stacked?: boolean;
+  /** @internal — injected by `TableRow`; this is the identity cell (column 0), which
+   *  in stacked mode leads the row instead of becoming one of its field lines. */
+  _primary?: boolean;
 }
 
 /** One cell — its width/align come from the column `TableRow` injects by position.
- *  In stacked mode it IS a `DetailRow` (spread: muted label left, value at the
- *  right edge) — the drawer's detail-row component, not a lookalike, so a
+ *  In stacked mode a FIELD cell is a `DetailRow` (spread: muted label left, value
+ *  at the right edge) — the drawer's detail-row component, not a lookalike, so a
  *  stacked register and the record workspace behind its door share one
  *  vocabulary by construction. `DetailRow` values are arbitrary nodes (the
  *  drawer renders badges, money stacks, editors, popover triggers in them), so
  *  register cell content needs no adaptation. A label-less control column has
- *  no line to spread — its content pins to the right edge. */
+ *  no line to spread — its content pins to the right edge.
+ *
+ *  The IDENTITY cell is not a field line and carries no label. It heads the row —
+ *  the thing you read to know WHICH record this is — so its column name ("Hợp đồng",
+ *  "Customer") only restates what the value already says, and it already sits on the
+ *  top line beside the selection checkbox and the ⋯ overflow, where a label has no
+ *  field grid to align to. */
 export function TableCell(props: TableCellProps) {
-  const { children, _column, _stacked } = props;
+  const { children, _column, _stacked, _primary } = props;
   if (_stacked) {
+    if (_primary) {
+      return <>{children}</>;
+    }
     if (!_column?.label) {
       return <View style={styles.stackedBareCell}>{children}</View>;
     }