@lotics/ui 24.0.2 → 25.1.0

package/AGENTS.md

@@ -67,9 +67,16 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   `expanded` reveal the detail beneath the row; keep the drawer for a heavy form.
   → [catalog.md](./docs/catalog.md).
 - **A reference to another record is a FIELD** — it wears the inline editor's own resting
-  surface, carries an **`InlineButton`** Open inside it, and PEEKS its facts on press (detach
-  lives in the peek). Never its own Section, never a card, never the other record's fields as
-  rows on this one. → [composition.md](./docs/composition.md).
+  surface and PEEKS its facts on press; EVERY verb lives in the peek's footer as a `Button`,
+  none on the field — LEFT the link (Change and Clear, both standard), RIGHT the record (Edit's
+  draft, and the optional Open). Change is `secondary`, never `danger`: it is a correction. After
+  Change hand the picker focus, after Clear never. Never its own
+  Section, never a card, never the other record's fields as rows on this one. **A peek can
+  hold editors only as a DRAFT** — `Edit` → inputs → `Save` (which sends only what CHANGED),
+  with the open draft pinning the popover so a stray click cannot discard typing; a
+  self-persisting inline editor may never go in one, because there blur and dismiss are the
+  same gesture.
+  → [composition.md](./docs/composition.md), [catalog.md](./docs/catalog.md).
 - **A verb about a VALUE goes on the value** — an `InlineButton` in the field's `actions`
   (Copy, Open), never the row's `trailing`: a control at the page's right edge has to be paired
   back to the field it belongs to, and one row's action makes EVERY row reserve the column.

package/MIGRATION.md

@@ -4,6 +4,44 @@ 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.
 
+## 25.0.0 — `ReferenceField` edits in place; `onRemove` becomes `onClear`
+
+**`onRemove` is now `onClear` — a pure rename, identical behaviour.** The act was always
+"detach and leave it empty"; only the VERB was wrong. Named "Remove" and coloured `danger`, a
+recoverable unset wore the ink reserved for destruction. Rename the prop and nothing else
+changes — same write, same follow-through, nothing focused.
+
+```tsx
+<ReferenceField … onRemove={() => setNotify(null)} />  // BEFORE — "Remove", danger
+<ReferenceField … onClear={() => setNotify(null)} />   // AFTER  — "Clear", secondary
+```
+
+**`onChange` is NEW, and also required.** Same write, but it means "wrong record, I'm about to
+pick another", so the caller hands the picker focus afterwards. Every `ReferenceField` now takes
+BOTH — including one the record cannot do without, since withholding Clear there enforces nothing
+(Change, then decline to pick, lands on the same empty state) and only makes the footer's shape
+vary per call site.
+
+**Hand the picker focus after Change, and only after Change.** Both verbs unset the reference and
+land on your empty state, but they mean opposite things: Change said "wrong one" (open the picker
+focused — `Combobox`'s `autoFocus` both focuses and opens), Clear said "there is none" (focus
+nothing, or you argue with the press). Track it as state — "empty" and "empty because Change was
+just pressed" look identical otherwise, and a field that starts empty must not steal the caret.
+
+**`onOpen`/`openLabel` are now OPTIONAL.** A reference whose facts can be corrected in place has
+no errand to send the reader on. Existing call sites keep working; drop them where Open only
+re-showed what the peek already said.
+
+**New: `onSave`, and `facts` gained `name`/`multiline`.** A fact carrying a `name`
+is editable and saves under that key; `Edit` opens a DRAFT in the same grid and `Save` fires
+`onSave` with only what CHANGED. The peek pins itself open while a draft is live, so a stray
+click cannot bin the typing. `facts` stays backward-compatible — `{label, value}` alone is
+read-only, exactly as before.
+
+**All four verbs are `Button`s now** (`TextButton` is gone from this component): Change and Clear
+on the left act on the LINK, Edit and Open on the right act on the RECORD, Edit taking the one
+filled-dark rung and handing it to Save when the draft opens.
+
 ## 24.0.0 — `TextLink` navigates, `TextButton` acts
 
 ```tsx

package/docs/catalog.md

@@ -720,7 +720,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   just text. **`InlineSelect` is single OR multi** — pass `multi` for a tag SET (`value: T[]`,
   commits the new set on popover-CLOSE; selected tags render as badges via `renderSelected`),
   mirroring `Select`'s `multi` axis; there is NO separate tag component. Both modes take
-  `allowCustom` (a create-a-tag/option row) + `searchable`. **`InlineMemberSelect` takes `avatarOnly`**
+  `allowCustom` (a create-a-tag/option row) + `searchable`, plus **`autoFocus`** to open the list
+  on mount — for the picker a `ReferenceField`'s `Change` just dropped the reader into, so the
+  correction stays one gesture; leave it off for a field that is merely empty, since stealing the
+  list open on load is a different act. **`InlineMemberSelect` takes `avatarOnly`**
   — the resting display is the bare AVATAR (no name/chevron, a dashed "add" ghost when unset) for a
   DENSE row where the name won't fit (a task-row assignee); the dropdown rows still show avatar + name.
   `InlineDatePicker` takes a **`tone`**
@@ -748,7 +751,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed
   total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column;
   non-interactive, NOT a disabled input; `muted`/`tabular`/`align="right"` for a number
-  column, `weight="medium"` to emphasise a total among plain rows.
+  column, `weight="medium"` to emphasise a total among plain rows, `multiline` to WRAP rather
+  than truncate (single-line is the default, because a field column reads as a column only if
+  its rows are one height — pass it where the counterpart editor is itself `multiline`, or a
+  truncated value beside a wrapping input reintroduces the misalignment on the other axis).
+  **Reach for it over a bare `Text` in any grid that has editors in some state**: an input's
+  words start at `CONTROL_TEXT_INSET` (1px border + 8px padding) and a raw `Text` starts at 0,
+  so a read/edit toggle slides every value 9px sideways.
 - **`sequence`** — `Sequence` + `SequenceItem` (+ `SEQUENCE_INSET`): an ORDERED list whose ORDER
   IS THE DATA — a route's stops, an approval chain, a set of legs — drawn as a connected rail so
   the sequence reads without a label saying "first"/"then". Reach for it when a thing has a
@@ -823,11 +832,48 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`reference_field`** — `ReferenceField`: a reference to ANOTHER RECORD, rendered as a
   FIELD VALUE — the kit's inline-editor surface (so a pointer sits in the value column
   like the editors above and below it), whose press opens a PEEK of that record's facts.
-  `name` + optional `code` + `facts` (label/value pairs) + `onOpen`/`openLabel` and an
-  optional `onRemove`. The verbs live INSIDE the peek, never on the field: `Open` goes to
-  the referenced record's own page, `Remove` detaches — both come from the locale pack
-  (`referenceField.open` / `.remove`), while `openLabel` stays a prop because it names the
-  DESTINATION for a screen reader, which only the caller knows. The value is a `TextLink` marker
+  `name` + optional `code` + `facts`, plus the verb callbacks below. The verbs live INSIDE the
+  peek, never on the field, and they are ALL `Button`s at one altitude — a peek is
+  dialog-scale and a dialog's verbs are buttons, so mixing weights only made the reader rank
+  four acts that are four acts. The row splits by WHAT EACH TOUCHES, and the spacer is that
+  seam: **left, the LINK** — `Change` (`onChange`, `secondary`) points the field at a different
+  record, named for the intent and deliberately not `danger` since a recoverable correction must
+  not wear the colour reserved for destruction; `Clear` (`onClear`, NO fill — the least-reached
+  verb of the four) leaves it empty. **Both are REQUIRED**, so the footer has one shape
+  everywhere; a reference the record cannot do without gains nothing from hiding Clear, because
+  Change and then declining to pick reaches the same empty state. **Right, the RECORD it points at** — `Edit` (`primary`, the one filled-dark rung,
+  handed to `Save` when the draft opens) and `Open` (`secondary`, rightmost, OPTIONAL, the
+  departure — not prioritized, because on a peek whose facts are correctable in place leaving is
+  the rarest move). Every verb is optional and the footer renders only when it HAS one, so an
+  edit-only reference draws no rule under nothing.
+  **Both unset — they differ only in FOLLOW-THROUGH.** `Clear` is the plain detach (nothing
+  focused); `Change` is the same write plus the caller's focus handoff. They are separate verbs
+  because the follow-through is not inferable from the write: nothing downstream can tell "unset
+  it" from "unset it, I'm about to pick another". Whether empty is VALID is the row's business — its
+  `warning`, its validation — never the peek's.
+  **Hand the picker focus after `Change`, never after `Clear`.** Both land on your empty state.
+  Change said "wrong one", so open the picker focused (`Combobox`'s `autoFocus` both focuses AND
+  opens) and the correction stays one gesture instead of three; Clear said "there is none", so
+  focusing would argue with the press and leave a menu to dismiss. Track it as state — "empty"
+  and "empty because Change was just pressed" are indistinguishable otherwise, and a field that
+  starts empty must not steal the caret on load.
+  Labels come from the locale pack (`referenceField.open` / `.change` / `.clear` / `.edit` /
+  `.save` / `.saving` / `.cancel`), while `openLabel` stays a prop because it names the
+  DESTINATION for a screen reader, which only the caller knows. **EDIT IN THE PEEK** (`onSave`):
+  a fact carrying a `name` is editable and that key is what it saves under (omit `name` for a
+  derived value that rides along read-only); `multiline` for an address or an account block;
+  `type: "date"` swaps the draft's text input for a `DatePicker` and formats the read value —
+  the fact's `value` stays the canonical ISO string on both sides, so a date is never edited as
+  free text and the format ambiguity never reaches the record.
+  `Edit` swaps the SAME grid's value cells for inputs — a DRAFT, so nothing commits until `Save`,
+  which fires `onSave` with **only the facts that CHANGED** (never a snapshot, so a lock or
+  `before_update` sees the real edit). This is what lets a peek hold editors at all: a
+  self-persisting inline editor cannot, because there blur and dismiss are ONE gesture — an open
+  draft instead PINS the popover (outside-press and Escape stop dismissing), making
+  `Cancel`/`Save` the only exits, and the draft's footer REPLACES the peek's rather than joining
+  it (Change, Clear and Open are all moves away from unsaved typing). A failed save KEEPS the
+  draft. `Save` is disabled until something differs, since an empty write still fires the
+  record's hooks and bumps its modified stamp. The value is a `TextLink` marker
   (underlined, neutral) because the press opens a summary rather than navigating. A
   reference is a FIELD, not a section — one pointer to one other row never earns a heading
   and a rail entry. Worked example: [`tpl_record`](../examples/tpl_record.tsx) § General

package/docs/composition.md

@@ -615,18 +615,30 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   a pointer at another record sits in the value column exactly like the editors above and below
   it. Put BOTH the name and its code INSIDE it — one entity reads as one object, and a muted
   code beside a link reads as an orphan.
-  **THREE acts, placed by how often they happen and what they cost to undo**: pressing the
-  surface PEEKS the facts (free, so it gets the biggest target); an **`InlineButton`** Open sits
-  INSIDE on the right (the common act, so it stays in sight and stays labelled — a press target
-  you discover by hovering is not an affordance); and DETACH lives in the peek's footer
-  (destructive and rare, and it is the answer to the question the peek asks — "is this the right
-  one?" — so the check and the correction are one gesture). A detach link repeated down a column
-  of references is noise in the scan path for an act most readers never perform.
-  The interior verb REQUIRES the anatomy a container-with-controls always requires: a role-less,
-  non-focusable surface (a button must never contain a button), an empty `PressDoor` sibling
-  carrying the tab stop / name / focus ring, and the verb lifted above it on `zIndex`. Track
-  hover on the container itself, or react-native-web releases it to the innermost pressable and
-  the border flickers out as the pointer crosses the verb.
+  **ONE act on the surface, the rest one layer in.** Pressing the field PEEKS the facts — free,
+  so it takes the whole box as its target — and every verb lives INSIDE the peek, placed by
+  four `Button`s in the footer, split by what they touch: LEFT the link — Change (point it
+  elsewhere) and Clear (leave it empty), both always present — RIGHT the record it points at — Edit (the
+  draft) and the optional Open (depart to its page). A peek is dialog-scale and a dialog's verbs
+  are buttons, so they share one altitude; the spacer between the pairs IS the seam, not padding.
+  Change is `secondary` and NOT `danger` — a correction, not a destruction — Edit takes the one
+  filled-dark rung and hands it to Save, Open stays `secondary` and never prioritized. None of
+  them sits on the field. After Change, hand the picker focus; after Clear, never — the two
+  verbs land in the same place meaning opposite things. An interior verb was tried and removed: it put two destinations behind one object
+  (press the box → a summary; press 8px right → navigate), it demanded the whole
+  container-with-controls anatomy (a role-less surface, a `PressDoor` for the tab stop, the verb
+  lifted on `zIndex`, hover tracked on the container), and it was neither common nor an act
+  ABOUT the value — leaving is the rare move on a record page. Without it the field has its plain
+  anatomy back: the press target is the box, the focus ring rings the field.
+  Detach earns its depth twice — destructive and rare, and it ANSWERS the question the peek asks
+  ("is this the right one?"), so the check and the correction are one gesture. A detach link
+  repeated down a column of references is noise for an act most readers never perform.
+  **Open is OPTIONAL, and Edit is why.** A reference whose facts can be corrected in the peek has
+  no errand to send the reader on, and a verb wired to nothing is worse than an absent one. Edit
+  opens a DRAFT in the same grid — nothing commits until Save, which sends only what CHANGED —
+  and the open draft PINS the popover so outside-press and Escape cannot bin the typing. That
+  pinning is the whole licence: a peek may hold a draft, and may never hold a self-persisting
+  inline editor, because there blur and dismiss are one gesture.
   **Never promote it to a Section.** A section claims a distinct AREA of the record and buys an
   outline-rail entry; one pointer at one other row never earns that. What tempts the promotion is
   the machinery around it — and each piece is just part of the field: the search is its EMPTY

package/examples/tpl_record.tsx

@@ -124,16 +124,22 @@ interface Customer {
   taxId: string;
   contact: string;
   city: string;
+  /** Runs past one line at a peek's width — the case a fixture of short values
+   *  never exercises, and the one where a read value and its editor diverge. */
+  address: string;
+  /** ISO. A date fact, so the peek's draft has one non-text editor to render —
+   *  left as text it would take whatever shape the reader typed. */
+  since: string;
 }
 
 // Atlas ships WITHOUT a tax ID — attach it to see the billing gate + the
 // inline Tax ID fix-up in the Customer section.
 const KNOWN_CUSTOMERS: Customer[] = [
-  { id: "cus_01", name: "Northwind Traders", code: "KH-0148", taxId: "0312456780", contact: "Mara Lindqvist", city: "Gothenburg" },
-  { id: "cus_02", name: "Harbor Freight Lines", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam" },
-  { id: "cus_03", name: "Summit Packaging Co.", code: "KH-0231", taxId: "0301557742", contact: "Priya Nair", city: "Singapore" },
-  { id: "cus_04", name: "Atlas Distribution", code: "KH-0117", taxId: "", contact: "Tom Becker", city: "Hamburg" },
-  { id: "cus_05", name: "Bluewater Logistics", code: "KH-0294", taxId: "0312004455", contact: "Lena Fischer", city: "Antwerp" },
+  { id: "cus_01", name: "Northwind Traders", code: "KH-0148", taxId: "0312456780", contact: "Mara Lindqvist", city: "Gothenburg", address: "Ringvägen 118, 4 tr, 116 61 Stockholm, Sweden", since: "2019-03-14" },
+  { id: "cus_02", name: "Harbor Freight Lines", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam", address: "Waalhaven Oostzijde 81, 3087 BM Rotterdam, Netherlands", since: "2021-11-02" },
+  { id: "cus_03", name: "Summit Packaging Co.", code: "KH-0231", taxId: "0301557742", contact: "Priya Nair", city: "Singapore", address: "9 Tuas Bay Walk, #03-14, Singapore 637803", since: "2023-06-19" },
+  { id: "cus_04", name: "Atlas Distribution", code: "KH-0117", taxId: "", contact: "Tom Becker", city: "Hamburg", address: "Grosser Grasbrook 9, 20457 Hamburg, Germany", since: "2018-01-30" },
+  { id: "cus_05", name: "Bluewater Logistics", code: "KH-0294", taxId: "0312004455", contact: "Lena Fischer", city: "Antwerp", address: "Noorderlaan 127, 2030 Antwerpen, Belgium", since: "2022-09-08" },
 ];
 
 const TAX_ID_RE = /^\d{10}(\d{3})?$/;
@@ -704,15 +710,24 @@ function RouteStops({ stops, onChange }: { stops: Stop[]; onChange: (next: Stop[
 /** A party ROW — a reference when one is attached, the find-or-create picker when
  *  not. The two states share the row so the field never moves; the picker is the
  *  field's EMPTY state, not a different kind of surface. */
-function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onRemove }: {
+function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onUnset, onSaveFacts }: {
   role: string;
   rec: Customer | null;
   options: PickerOption<string, Customer>[];
   placeholder: string;
   onPick: (opt: PickerOption<string, Customer>) => void;
   onOpen: () => void;
-  onRemove: () => void;
+  onUnset: () => void;
+  onSaveFacts: (id: string, patch: Record<string, string>) => void;
 }) {
+  // THE FOCUS HANDOFF, and only for Change. Both verbs unset the reference, so
+  // both land on the picker below — but they arrive meaning opposite things.
+  // Change said "wrong one", and the next move is choosing the right one, so the
+  // picker opens focused and the correction stays ONE gesture instead of three
+  // (press, hunt for the input, click it). Clear said "there is none": opening a
+  // picker there would argue with the press, and leave a menu the reader has to
+  // dismiss to get the empty state they just asked for.
+  const [changing, setChanging] = useState(false);
   return (
     <DetailRow label={role}>
       {rec ? (
@@ -720,17 +735,26 @@ function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onRemove }:
           name={rec.name}
           code={rec.code}
           facts={[
-            { label: "Contact", value: rec.contact },
-            { label: "City", value: rec.city },
-            { label: "Tax ID", value: rec.taxId },
+            { label: "Contact", value: rec.contact, name: "contact" },
+            { label: "City", value: rec.city, name: "city" },
+            { label: "Tax ID", value: rec.taxId, name: "taxId" },
+            { label: "Address", value: rec.address, name: "address", multiline: true },
+            { label: "Customer since", value: rec.since, name: "since", type: "date" },
           ]}
           accessibilityLabel={`${rec.name} — details`}
           openLabel={`Open ${rec.name}`}
           onOpen={onOpen}
-          onRemove={onRemove}
+          onChange={() => { setChanging(true); onUnset(); }}
+          onClear={() => { setChanging(false); onUnset(); }}
+          onSave={(patch) => onSaveFacts(rec.id, patch)}
         />
       ) : (
-        <Combobox options={options} onValueChange={onPick} reflectSelection={false}>
+        <Combobox
+          options={options}
+          autoFocus={changing}
+          onValueChange={(o) => { setChanging(false); onPick(o); }}
+          reflectSelection={false}
+        >
           <ComboboxInput icon="search" placeholder={placeholder} accessibilityLabel={role} />
           <ComboboxContent emptyText="No match" />
         </Combobox>
@@ -818,6 +842,12 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   // the Customer section (that's what un-gates invoicing).
   const [customers, setCustomers] = useState<Customer[]>(KNOWN_CUSTOMERS);
   const [customerId, setCustomerId] = useState<string | null>("cus_02");
+  // Set by Change, consumed by the picker's `autoFocus`, cleared on pick. It has
+  // to be state rather than a derived value: "empty" and "empty BECAUSE the
+  // reader just pressed Change" look identical on the record, and only the
+  // second should steal focus — a field that starts empty must not grab the
+  // caret on load.
+  const [changingCustomer, setChangingCustomer] = useState(false);
   const customer = customers.find((c) => c.id === customerId) ?? null;
 
   // ── facts + details (all inline-persisted)
@@ -835,7 +865,11 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   // record arrives at, and the surface every compaction idea has to be judged
   // against — measure any change here, not on a four-field group.
   const [shipTo, setShipTo] = useState<string | null>("cus_03");
-  const [notify, setNotify] = useState<string | null>(null);
+  // Seeded so the ONE row carrying all four verbs is reachable at rest. Its own
+  // Clear returns it to the empty picker in a press, so the empty state this
+  // used to demonstrate at rest is still one gesture away — and now the full
+  // footer is too, which it never was.
+  const [notify, setNotify] = useState<string | null>("cus_01");
   const [carrier, setCarrier] = useState<string | null>("cus_05");
   const [docType, setDocType] = useState("original");
   const [waybill, setWaybill] = useState("WB-4471902");
@@ -856,6 +890,24 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   ]);
   const [dropPoint, setDropPoint] = useState("");
   const [scheduleNote, setScheduleNote] = useState("delayed");
+  // One writer for every party's facts — the peek's draft hands back only the
+  // keys that CHANGED, so each is applied over the record it names and the rest
+  // of that customer is left alone.
+  const saveCustomerFacts = (id: string, patch: Record<string, string>) =>
+    setCustomers((prev) =>
+      prev.map((c) =>
+        c.id === id
+          ? {
+              ...c,
+              contact: patch.contact ?? c.contact,
+              city: patch.city ?? c.city,
+              taxId: patch.taxId ?? c.taxId,
+              address: patch.address ?? c.address,
+              since: patch.since ?? c.since,
+            }
+          : c,
+      ),
+    );
   const shipToRec = customers.find((c) => c.id === shipTo) ?? null;
   const notifyRec = customers.find((c) => c.id === notify) ?? null;
   const carrierRec = customers.find((c) => c.id === carrier) ?? null;
@@ -1191,6 +1243,10 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
       taxId: custDraft.taxId.trim(),
       contact: custDraft.contact.trim(),
       city: custDraft.city.trim(),
+      // Not collected at create — a new party is attached from three fields and
+      // the rest is filled in later, which is what the peek's Edit is for.
+      address: "",
+      since: "",
     };
     setCustomers((prev) => [...prev, c]);
     setCustomerId(c.id);
@@ -1655,26 +1711,67 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                     <ReferenceField
                       name={customer.name}
                       code={customer.code}
+                      /* A fact carrying a `name` is EDITABLE — the key it saves
+                         under. The three here are the customer's own columns; a
+                         derived one (a balance, a rating) would omit `name` and
+                         ride along read-only. */
                       facts={[
-                        { label: "Tax ID", value: customer.taxId },
-                        { label: "Contact", value: customer.contact },
-                        { label: "City", value: customer.city },
+                        { label: "Tax ID", value: customer.taxId, name: "taxId" },
+                        { label: "Contact", value: customer.contact, name: "contact" },
+                        { label: "City", value: customer.city, name: "city" },
+                        { label: "Address", value: customer.address, name: "address", multiline: true },
+                        { label: "Customer since", value: customer.since, name: "since", type: "date" },
                       ]}
                       accessibilityLabel={`${customer.name} — details`}
-                      openLabel="Open customer"
+                      /* NO `onOpen`. The peek carries every fact this record
+                         holds about the customer AND can correct them, so
+                         "Open" resolved to "read that again, wider" — the exact
+                         thing the deleted customer drawer was doing. The party
+                         rows below still pass it: a carrier's page has related
+                         lists a peek can never hold, and that is a real errand.
+                         The prop is optional so each call site answers for
+                         itself instead of wiring a verb to nothing. */
+                      /* The warning on the row above is derived from this same
+                         tax ID, so correcting it in the peek clears the block
+                         without leaving the field — which is the case for
+                         editing here at all. Atlas Distribution ships with an
+                         empty tax ID to make that path reachable. */
+                      onSave={(patch) =>
+                        setCustomers((prev) =>
+                          prev.map((c) =>
+                            c.id === customerId
+                              ? {
+                                  ...c,
+                                  taxId: patch.taxId ?? c.taxId,
+                                  contact: patch.contact ?? c.contact,
+                                  city: patch.city ?? c.city,
+                                }
+                              : c,
+                          ),
+                        )
+                      }
                       /* A real app navigates to the customer's OWN record page —
                          same as Ship to / Notify / Carrier below. This used to
                          open a local drawer that re-showed the five facts the
                          peek had just shown, so "Open" resolved to "read that
                          again, wider" and the customer's record was unreachable
                          from the one control that promised it. */
-                      onOpen={() => {}}
-                      onRemove={() => setCustomerId(null)}
+                      /* Clear is offered even though an order needs a bill-to
+                         party: withholding it would enforce nothing, since
+                         Change and then declining to pick reaches the same empty
+                         state. The tax ID that gates invoicing is checked by the
+                         row's `warning` above, which is where validity belongs. */
+                      onChange={() => { setChangingCustomer(true); setCustomerId(null); }}
+                      onClear={() => { setChangingCustomer(false); setCustomerId(null); }}
                     />
                   ) : (
                     <Combobox
                       options={customerOptions}
-                      onValueChange={onPickCustomer}
+                      /* Pressing Change said "wrong customer" — so the picker it
+                         drops you into is already focused and open, and the
+                         correction stays one gesture. */
+                      autoFocus={changingCustomer}
+                      onValueChange={(o) => { setChangingCustomer(false); onPickCustomer(o); }}
                       renderOptionContent={(o) => (
                         <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
                           <View style={{ width: 28, height: 28, borderRadius: 7, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" }}>
@@ -2015,12 +2112,12 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                 <PartyRow
                   role="Ship to" rec={shipToRec} options={customerOptions}
                   placeholder="Find or create a consignee"
-                  onPick={(o) => setShipTo(o.value)} onOpen={() => {}} onRemove={() => setShipTo(null)}
+                  onPick={(o) => setShipTo(o.value)} onOpen={() => {}} onUnset={() => setShipTo(null)} onSaveFacts={saveCustomerFacts}
                 />
                 <PartyRow
                   role="Notify" rec={notifyRec} options={customerOptions}
                   placeholder="Find or create a notify party"
-                  onPick={(o) => setNotify(o.value)} onOpen={() => {}} onRemove={() => setNotify(null)}
+                  onPick={(o) => setNotify(o.value)} onOpen={() => {}} onUnset={() => setNotify(null)} onSaveFacts={saveCustomerFacts}
                 />
                 {/* A CHOICE IS ONE ROW, like every other field.
                     `RadioPicker` renders three full-width bordered choices with
@@ -2121,7 +2218,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                 <PartyRow
                   role="Carrier" rec={carrierRec} options={customerOptions}
                   placeholder="Find or create a carrier"
-                  onPick={(o) => setCarrier(o.value)} onOpen={() => {}} onRemove={() => setCarrier(null)}
+                  onPick={(o) => setCarrier(o.value)} onOpen={() => {}} onUnset={() => setCarrier(null)} onSaveFacts={saveCustomerFacts}
                 />
                 <DetailRow label="Booking no.">
                   <InlineTextInput value={booking} onSave={persist(setBooking)} placeholder="Add booking number…" accessibilityLabel="Booking number" />

package/package.json

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

package/src/inline_select.tsx

@@ -13,6 +13,16 @@ import { useLoticsLocale } from "./locale";
 
 interface InlineSelectBaseProps<T extends string, D = unknown> {
   options: PickerOption<T, D>[];
+  /**
+   * Open the list on mount.
+   *
+   * For a picker that REPLACED something the reader just dismissed — a
+   * `ReferenceField` whose `onChange` fired, which means "wrong one, I'm about
+   * to pick another". Landing them on a closed picker charges a second press to
+   * resume a correction they already started. Leave it off for a field that is
+   * merely empty: stealing the list open on load is not the same act.
+   */
+  autoFocus?: boolean;
   /** Custom option content in the dropdown (icon + label, two-line, a badge…).
    *  Omit for a plain label list — both render through the same `OptionList`. */
   renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
@@ -119,9 +129,9 @@ function InlineSelectShell(props: {
 }
 
 export function InlineSelect<T extends string, D = unknown>(props: InlineSelectProps<T, D>) {
-  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions } = props;
+  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions, autoFocus = false } = props;
   const labels = useLoticsLocale().inline;
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(autoFocus);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [draft, setDraft] = useState<T[]>(props.multi ? props.value : []);

package/src/inline_static.tsx

@@ -19,6 +19,15 @@ export interface InlineStaticProps {
   /** Value weight — `medium` to emphasise a total or headline figure among plain
    *  rows. Default `regular` (reads as an ordinary value, not a heading). */
   weight?: "regular" | "medium";
+  /**
+   * The value WRAPS instead of truncating — an address, a bank-account block.
+   *
+   * Single-line is the default because a record's field column reads as a column
+   * only if its rows are one height. Pass this where the counterpart editor is
+   * itself `multiline`: a truncated value beside a wrapping input is the same
+   * misalignment this component exists to prevent, just on the other axis.
+   */
+  multiline?: boolean;
 }
 
 /**
@@ -32,13 +41,13 @@ export interface InlineStaticProps {
  * slot, so the value takes the slack and the trailing pins right.
  */
 export function InlineStatic(props: InlineStaticProps) {
-  const { value, placeholder, muted, tabular, align = "left", weight } = props;
+  const { value, placeholder, muted, tabular, align = "left", weight, multiline } = props;
   const isEmpty = value.length === 0;
   const display = isEmpty ? (placeholder ?? "—") : value;
   return (
     <View style={styles.box}>
       <Text
-        numberOfLines={1}
+        numberOfLines={multiline ? undefined : 1}
         tabular={tabular}
         align={align}
         weight={weight}
@@ -61,6 +70,13 @@ const styles = StyleSheet.create({
     borderWidth: 1,
     borderColor: "transparent",
     paddingHorizontal: 8,
+    // The editors' vertical padding too, not just the horizontal. A single line
+    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
+    // sides land on 40 whether or not this exists — but an auto-growing input
+    // sizes itself to content PLUS its padding and border, so from the SECOND
+    // line on, a value without this sits ~14px shorter than the input that
+    // replaces it. Matching by coincidence at one line is not matching.
+    paddingVertical: 8,
     justifyContent: "center",
   },
   placeholder: { color: colors.zinc[400] },

package/src/locale.tsx

@@ -37,11 +37,12 @@ export interface LoticsLocale {
   pagination: Required<PaginationLabels>;
   /** `SortHeader` a11y prefix + asc/desc suffixes. */
   sortHeader: Required<SortHeaderLabels>;
-  /** `ReferenceField`'s peek footer — the go-to and detach verbs. `openLabel`
+  /** `ReferenceField`'s peek footer — the link verbs (change / clear), the draft
+   *  verbs (edit / save / saving / cancel) and the go-to. `openLabel`
    *  stays a per-instance PROP because it names the DESTINATION ("Open
    *  customer"), which is a11y text only a caller knows; these two are the
    *  VISIBLE chrome, which the pack owns. */
-  referenceField: { open: string; remove: string };
+  referenceField: { open: string; change: string; clear: string; edit: string; save: string; saving: string; cancel: string };
   /** `OptionList` (and everything built on it — `Select`, `Combobox`, the
    *  in-cell editors): the select-all/deselect-all links, the empty state, the
    *  internal search-field placeholder, and the `Combobox` recents header. */
@@ -220,7 +221,7 @@ export const en: LoticsLocale = {
     ascending: ", ascending",
     descending: ", descending",
   },
-  referenceField: { open: "Open", remove: "Remove" },
+  referenceField: { open: "Open", change: "Change", clear: "Clear", edit: "Edit", save: "Save", saving: "Saving…", cancel: "Cancel" },
   optionList: { selectAll: "Select all", deselectAll: "Deselect all", clear: "Clear", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
   datePicker: { today: "Today", now: "Now", clear: "Clear", done: "Done", openCalendar: "Open calendar", time: "Time", startTime: "Start time", endTime: "End time", startDate: "Start date", endDate: "End date", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM", invalidDate: "Enter a complete date", invalidTime: "Enter a complete time" },
   calendar: { previousMonth: "Previous month", nextMonth: "Next month" },
@@ -379,7 +380,7 @@ export const vi: LoticsLocale = {
     ascending: " (tăng dần)",
     descending: " (giảm dần)",
   },
-  referenceField: { open: "Mở", remove: "Gỡ" },
+  referenceField: { open: "Mở", change: "Đổi", clear: "Bỏ chọn", edit: "Sửa", save: "Lưu", saving: "Đang lưu…", cancel: "Huỷ" },
   optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", clear: "Xóa", noResults: "Không có kết quả", recent: "Gần đây", searchPlaceholder: "Tìm…" },
   datePicker: { today: "Hôm nay", now: "Bây giờ", clear: "Xóa", done: "Xong", openCalendar: "Mở lịch", time: "Giờ", startTime: "Giờ bắt đầu", endTime: "Giờ kết thúc", startDate: "Ngày bắt đầu", endDate: "Ngày kết thúc", addTime: "Thêm giờ", removeTime: "Bỏ giờ", year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH", invalidDate: "Nhập ngày đầy đủ", invalidTime: "Nhập giờ đầy đủ" },
   calendar: { previousMonth: "Tháng trước", nextMonth: "Tháng sau" },

package/src/reference_field.tsx

@@ -1,15 +1,18 @@
 import { useRef, useState } from "react";
 import { View } from "react-native";
 import { Button } from "./button";
+import { DatePicker } from "./date_picker";
 import { DetailRow, DetailTable } from "./detail_row";
+import { formatDate } from "./format_date";
 import { Divider } from "./divider";
 import { InlineEditView } from "./inline_edit";
+import { InlineStatic } from "./inline_static";
 import { Popover, PopoverContent } from "./popover";
 import { DialogSectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
-import { TextButton } from "./text_button";
+import { TextInputField } from "./text_input_field";
 import { TextLink } from "./text_link";
-import { useLoticsLocale } from "./locale";
+import { useLocaleTag, useLoticsLocale } from "./locale";
 
 /**
  * A REFERENCE to another record, rendered as a FIELD VALUE.
@@ -22,9 +25,10 @@ import { useLoticsLocale } from "./locale";
  * already mean by it — they open a popover too.)
  *
  * ONE act on the surface, the rest one layer in:
- *   press the value  → the facts, in a popover (free, so it's the whole surface)
- *   Open, in the peek → the referenced record's own page
- *   Remove, in the peek → detach (destructive and rare)
+ *   press the value → the facts, in a popover (free, so it's the whole surface)
+ *   Change / Clear  → the LINK: point it elsewhere, or leave it empty
+ *   Edit            → the RECORD's own facts, as a draft, committed by Save
+ *   Open            → the referenced record's page (optional; the departure)
  *
  * Open used to sit ON the field as an `InlineButton`, justified as "the common
  * act". It was neither common nor an act about the value. `actions` is for verbs
@@ -38,39 +42,175 @@ import { useLoticsLocale } from "./locale";
  * is the whole box again and the focus ring rings the field, not a narrower
  * region inside it.
  *
- * Remove earns its depth twice over. It is the answer to the question the PEEK
- * asks — "is this the right one?" — so the check and the correction are the same
- * gesture; and a detach link repeated down a column of references is noise in the
- * scan path for an act most readers never perform. Depth is not a hiding place
- * here: pressing a field-shaped value is the first thing anyone tries, and the
- * verb is plainly visible once open.
+ * The link verbs earn their depth twice over. They ANSWER the question the peek
+ * asks — "is this the right one?" — so the check and the correction are one
+ * gesture; and a detach control repeated down a column of references is noise in
+ * the scan path for an act most readers never perform. Depth is not a hiding
+ * place here: pressing a field-shaped value is the first thing anyone tries, and
+ * the verbs are plainly visible once open.
+ *
+ * Both link verbs are named for the INTENT, not the mechanism, and neither is
+ * `danger`: unsetting a reference is recoverable, and calling it "Remove" made it
+ * wear the colour reserved for destruction. `Clear` is the plain detach; `Change`
+ * is the same write followed by the picker, focused, because the press said
+ * "wrong one" and the correction should cost one gesture rather than three. Both
+ * are STANDARD — the footer has one shape everywhere, and a required reference
+ * gains nothing from hiding Clear, since Change-then-decline reaches the same
+ * empty state anyway.
  *
  * What it encodes is the PEEK CONTRACT — the marker, the popover's grammar, and
  * where each verb sits — not a layout convenience. It was a template composition
  * until a second surface needed it (a register's workspace drawer lists the same
  * references), which is the bar for lifting one here.
  */
+export interface ReferenceFact {
+  label: string;
+  value: string;
+  /**
+   * The key this fact SAVES under. Its presence is what makes the fact
+   * editable — a fact without one stays read-only in the draft, which is how a
+   * derived value (a total, a status, a formatted id) rides along in the peek
+   * without pretending to be typeable.
+   */
+  name?: string;
+  /** A value that runs past one line — an address, a bank account block. */
+  multiline?: boolean;
+  /**
+   * What the draft edits this fact WITH. `text` (default) is a text input;
+   * `date` is the kit's `DatePicker`, and the value is its ISO string.
+   *
+   * A date is not a short string that happens to look like one. Left as text it
+   * takes any shape the reader types, and the field it saves into accepts one —
+   * so the format ambiguity is only discovered by whatever reads the record
+   * next, which is exactly the kind of wrong a draft is supposed to catch at
+   * the input.
+   */
+  type?: "text" | "date";
+}
+
 export interface ReferenceFieldProps {
   name: string;
   code?: string;
-  facts: { label: string; value: string }[];
+  facts: ReferenceFact[];
   /** Announced name of the peek trigger, e.g. "Harbor Freight Lines — details". */
   accessibilityLabel: string;
-  onOpen: () => void;
-  openLabel: string;
-  /** Detach — omit where the link cannot be broken (a handoff's sibling record). */
-  onRemove?: () => void;
+  /**
+   * The referenced record's own page. OPTIONAL, because a reference that can be
+   * corrected in place has no errand to send the reader on — and a verb wired to
+   * nothing is worse than an absent one (it promises a destination, then spends
+   * the press on nothing). Omit it and the peek simply carries no Open.
+   */
+  onOpen?: () => void;
+  openLabel?: string;
+  /**
+   * Point this field at a DIFFERENT record. REQUIRED.
+   *
+   * Unsets the reference so the call site's picker returns, and the caller
+   * should hand that picker focus: the press said "wrong one", so the next move
+   * is choosing the right one and the correction should cost one gesture.
+   */
+  onChange: () => void;
+  /**
+   * Leave the reference EMPTY — the plain detach. REQUIRED.
+   *
+   * The SAME write as `onChange`; they differ only in FOLLOW-THROUGH, and
+   * nothing focuses after this one — auto-opening a picker would argue with the
+   * intent the press just stated. They are separate props because that
+   * follow-through is not inferable from the write: nothing downstream can tell
+   * "unset it" from "unset it, I'm about to pick another", and guessing wrong
+   * either steals the caret from someone who wanted an empty field or sends
+   * someone who wanted a swap hunting for the input.
+   *
+   * BOTH are required, including on a reference the record cannot do without.
+   * Hiding Clear there enforces nothing — Change, then decline to pick, lands on
+   * the same empty state — so it only removes the direct route to a place the
+   * reader can already reach, and makes the footer's shape vary for no gain.
+   * Whether empty is VALID is the row's business (its `warning`, its
+   * validation), never the peek's.
+   */
+  onClear: () => void;
+  /**
+   * Commit the draft. Receives ONLY the facts whose value CHANGED, keyed by
+   * `name` — never a full snapshot, so a lock or a `before_update` hook sees the
+   * edit the reader actually made. Present (with at least one named fact) is
+   * what gives the peek its Edit verb.
+   */
+  onSave?: (patch: Record<string, string>) => void | Promise<void>;
 }
 
 export function ReferenceField(props: ReferenceFieldProps) {
-  const { name, code, facts, accessibilityLabel, onOpen, openLabel, onRemove } = props;
-  // The peek's two verbs are the component's OWN chrome, so they come from the
+  const { name, code, facts, accessibilityLabel, onOpen, openLabel, onChange, onClear, onSave } = props;
+  // The peek's verbs are the component's OWN chrome, so they come from the
   // pack — hardcoding them shipped "Open"/"Remove" into every localized app.
   const t = useLoticsLocale().referenceField;
+  // The tag a date control renders in — `vi` yields dd/MM/yyyy with no per-
+  // instance prop, which is the same resolution `DatePicker` does internally.
+  const localeTag = useLocaleTag();
   const anchor = useRef<View>(null);
   const [peekOpen, setPeekOpen] = useState(false);
+  const [draft, setDraft] = useState<Record<string, string> | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const editing = draft !== null;
+  const editable = onSave != null && facts.some((f) => f.name != null);
+
+  const openDraft = () => {
+    const seed: Record<string, string> = {};
+    for (const f of facts) if (f.name != null) seed[f.name] = f.value;
+    setError(null);
+    setDraft(seed);
+  };
+  const closeDraft = () => {
+    setDraft(null);
+    setError(null);
+  };
+  // ONLY what changed. A full snapshot would clobber a concurrent edit to a
+  // fact this reader never touched, and would fire every `before_update` hook
+  // on the record rather than the ones the edit actually earned.
+  const changed = (d: Record<string, string>): Record<string, string> => {
+    const patch: Record<string, string> = {};
+    for (const f of facts) if (f.name != null && d[f.name] !== f.value) patch[f.name] = d[f.name] ?? "";
+    return patch;
+  };
+  const dirty = editing && Object.keys(changed(draft)).length > 0;
+
+  const save = async () => {
+    if (draft == null || onSave == null) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await onSave(changed(draft));
+      setDraft(null);
+    } catch (e) {
+      // The draft SURVIVES a failed save — discarding what someone just typed
+      // because the network refused it is the one unforgivable thing a form
+      // does. They retry, or they cancel; the component never decides.
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setSaving(false);
+    }
+  };
+
   return (
-    <Popover open={peekOpen} onOpenChange={setPeekOpen} triggerRef={anchor} side="bottom" align="start">
+    <Popover
+      open={peekOpen}
+      /* A DRAFT PINS THE POPOVER OPEN. Outside-press and Escape are this
+         surface's dismissal, and dismissal is silent — so while a draft is
+         open they would throw away typing with no undo and no trace. This is
+         the whole reason a peek could not hold self-persisting inline editors
+         (blur and dismiss are one gesture there); a draft with an explicit
+         Save has no such collision, PROVIDED the draft outranks the dismissal.
+         Cancel and Save are then the only ways out, which is what makes them
+         worth rendering. */
+      onOpenChange={(next) => {
+        if (!next && editing) return;
+        setPeekOpen(next);
+        if (!next) closeDraft();
+      }}
+      triggerRef={anchor}
+      side="bottom"
+      align="start"
+    >
       {/* THE KIT'S FIELD, not a lookalike. This was hand-rolled — a Pressable
           wearing copies of the field's border, radius, height and hover — and it
           promptly fell out of step the moment the kit's field changed: it kept a
@@ -120,57 +260,149 @@ export function ReferenceField(props: ReferenceFieldProps) {
       <PopoverContent style={{ width: 320 }} disableBodyScroll>
         <View style={{ gap: 12 }}>
           <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
-          {/* PLAIN `Text`, not `InlineStatic` — and `minHeight` 28, `DetailRow`'s
-              own default, instead of the `DetailTable`'s 40.
+          {/* ONE geometry for both modes — the table's own 40px band, which is
+              `CONTROL_HEIGHT` and exactly what `TextInputField` renders at. The
+              read row therefore RESERVES the space its editor will need, and
+              pressing Edit changes the value cell's species without moving a
+              single label.
 
-              Both come from one fact: this grid has NO editors. `InlineStatic`
-              exists to align pixel-for-pixel with the `Inline*` controls — it
-              hard-sets `INLINE_CONTROL_HEIGHT` so a computed total sits flush
-              beside editable rows in a record. Here there is nothing to sit flush
-              WITH, so it only reserved a 40px control band for a 20px value:
-              three facts, 60px of air, in a popover whose whole job is a glance.
-              `minHeight` alone does not fix it (the value's own box still forces
-              40) and `Text` alone does not either (the table's band re-imposes
-              it) — the row is the max of the two, so both have to go. */}
-          <DetailTable labelWidth={88} minHeight={28}>
-            {facts.map((f) => (
-              <DetailRow key={f.label} label={f.label} flat>
-                <Text size="sm">{f.value || "—"}</Text>
-              </DetailRow>
-            ))}
+              This read at 28 for a while, on the argument that the grid had no
+              editors and a glance surface should not buy a control band for a
+              20px value. That premise expired the moment the peek gained a
+              draft, and the constant outlived it: 28 → 40 grew every row by 12px
+              and re-centred every label by 6px inside it, so by the third fact
+              the reader's eye had moved 24px to follow text it was already
+              reading. A view↔edit toggle reserves the input's height; the 36px
+              of extra air across three facts is what that costs, and it is
+              cheaper than making someone re-find their place on every press. */}
+          <DetailTable labelWidth={88}>
+            {facts.map((f) =>
+              editing && f.name != null ? (
+                <DetailRow key={f.label} label={f.label}>
+                  {f.type === "date" ? (
+                    <DatePicker
+                      value={draft[f.name] || null}
+                      onValueChange={(v) => setDraft({ ...draft, [f.name as string]: v })}
+                      disabled={saving}
+                    />
+                  ) : (
+                    <TextInputField
+                      value={draft[f.name] ?? ""}
+                      onChangeText={(v) => setDraft({ ...draft, [f.name as string]: v })}
+                      multiline={f.multiline}
+                      autoGrow={f.multiline}
+                      disabled={saving}
+                      accessibilityLabel={f.label}
+                    />
+                  )}
+                </DetailRow>
+              ) : (
+                <DetailRow key={f.label} label={f.label}>
+                  {/* `InlineStatic`, NOT a bare `Text`. An input's words start at
+                      `CONTROL_TEXT_INSET` — 1px border plus 8px padding — and a
+                      raw Text starts at 0, so pressing Edit slid every value 9px
+                      right. This is the component built to sit flush beside
+                      editors, border and all, and reaching for it means the
+                      alignment survives the control geometry changing. Copying
+                      the box here instead would drift the first time it does. */}
+                  <InlineStatic
+                    /* A date's canonical value is its ISO string — that is what
+                       the picker reads and what Save sends — so the FORMATTING
+                       happens here, where the type is known. Handing the caller
+                       that job would make `value` mean two things (display in
+                       read, ISO in the draft) and the two would drift. */
+                    value={f.type === "date" ? formatDate(f.value, { locale: localeTag }) : f.value}
+                    multiline={f.multiline}
+                  />
+                </DetailRow>
+              ),
+            )}
           </DetailTable>
-          {/* THE FOOTER — destructive LEFT, go-to RIGHT, the kit's convention.
-              Open repeats the verb on the surface deliberately: the popover now
-              covers the button that opened it, and having read the facts, "take me
-              there" is the next move. That is the shape `Peek` prescribes — a
-              summary with one action to the full record. Remove closes the peek
-              first, because the surface it is anchored to is about to stop
-              existing. */}
+          {error ? <Text size="sm" color="danger">{error}</Text> : null}
+          {/* THE FOOTER — every verb is a `Button`, at ONE altitude. The peek is
+              dialog-scale (its title already takes the dialog rung), and a
+              dialog's verbs are buttons; mixing weights here made the reader
+              rank three acts that are simply three acts.
+
+              CHANGE, not Remove, and not `danger`. The mechanism is a detach,
+              but nobody arrives at it wanting an empty field — they arrive
+              having read the facts and decided this is the wrong record, and
+              what follows is the picker. Naming it for the mechanism made a
+              recoverable correction wear the colour reserved for destruction.
+              It is the answer to the question the peek asks — "is this the right
+              one?" — so it sits FIRST, at the left, where that answer belongs.
+
+              OPEN stays right and OPTIONAL: it is the departure, and on a peek
+              whose facts can be corrected in place, leaving is the rarest move.
+
+              The whole footer is conditional — with all three verbs optional, an
+              edit-only reference would otherwise draw a rule under the facts and
+              fence off an empty band, which is chrome asserting a structure that
+              is not there. */}
           <Divider />
+          {/* THE DRAFT'S FOOTER REPLACES the peek's, it does not join it. Change
+              and Open are moves AWAY from an unsaved draft — one detaches the
+              record being edited, one navigates off it — so offering either here
+              would be offering to lose the typing. Cancel and Save are the only
+              two exits, which is also what the pinned popover promised. */}
+          {editing ? (
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <View style={{ flex: 1 }} />
+              <Button title={t.cancel} color="secondary" disabled={saving} onPress={closeDraft} />
+              {/* Disabled until something DIFFERS: with nothing to send, a save
+                  is a write that fires the record's hooks and bumps its
+                  modified stamp to record that nobody changed anything. */}
+              <Button
+                title={saving ? t.saving : t.save}
+                color="primary"
+                disabled={!dirty || saving}
+                onPress={() => void save()}
+              />
+            </View>
+          ) : (
           <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-            {onRemove ? (
-              // `TextButton color="danger"` — this act wanted the component, not a
-              // Button wearing three corrections. It went `danger` (solid, too
-              // loud for the rarest verb here) → `danger-secondary` (a ghost, so
-              // its ink sat a padding's width inside the column every fact label
-              // starts on) → `+ flush` (that geometry, patched). A text-weight
-              // destructive act aligned to a column of text IS this component: red
-              // ink, no fill, its own bleed, and a hover wash and focus ring a bare
-              // pressable Text never had.
-              //
-              // Pairing a text action with the filled `secondary` "Open" is the
-              // standard footer shape, not a mismatch — Material and HIG both put
-              // the quiet/destructive verb at text weight beside a filled primary.
-              // No icon: an ✕ beside "Remove" says it twice, and the glyph alone
-              // made this read as the popover's dismiss rather than a decision.
-              <TextButton color="danger" onPress={() => { setPeekOpen(false); onRemove(); }}>{t.remove}</TextButton>
-            ) : null}
+            {/* LEFT PAIR acts on the LINK — which record this points at. Both
+                are unconditional: the peek always offers "point it elsewhere"
+                and "leave it empty", so its footer has ONE shape everywhere
+                instead of four depending on which callbacks a call site
+                remembered. */}
+            <Button
+              title={t.change}
+              color="secondary"
+              accessibilityLabel={`${t.change} — ${name}`}
+              onPress={() => { setPeekOpen(false); onChange(); }}
+            />
+            {/* No fill — Clear is the least-reached verb here, and the one whose
+                result the reader is least likely to want by accident, so it
+                carries the least weight of the four. */}
+            <Button
+              title={t.clear}
+              accessibilityLabel={`${t.clear} — ${name}`}
+              onPress={() => { setPeekOpen(false); onClear(); }}
+            />
+            {/* The spacer is the SEAM between what the two pairs touch: left the
+                link, right the record it points at. Without that split, Open's
+                position is just "pushed over". */}
             <View style={{ flex: 1 }} />
+            {/* RIGHT PAIR acts on the RECORD the link points at — correct its
+                data, or go to it. Edit takes the ONE filled-dark rung because it
+                is the only verb here that leads to a commit, and it hands that
+                rung straight to Save when the draft opens: one primary per mode,
+                never two. Every other verb stays `secondary` and FILLED — a
+                fill-less Button shows no box, so its ink sits a padding inside
+                its own edge, and one boxless label in a row of boxes reads as
+                indented (the geometry that made `TextButton` exist). */}
+            {editable ? (
+              <Button title={t.edit} color="primary" accessibilityLabel={`${t.edit} — ${name}`} onPress={openDraft} />
+            ) : null}
             {/* `openLabel` names the DESTINATION ("Open customer"): a page carries
                 four of these peeks, and four buttons announcing a bare "Open"
                 are four controls a screen reader cannot tell apart. */}
-            <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
+            {onOpen ? (
+              <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
+            ) : null}
           </View>
+          )}
         </View>
       </PopoverContent>
     </Popover>

package/src/text_input_field.tsx

@@ -52,6 +52,12 @@ interface TextInputFieldProps extends RNTextInputProps {
   "aria-autocomplete"?: "none" | "inline" | "list" | "both";
 }
 
+/** The input box's own vertical padding and border, named so the auto-grow math
+ *  and the stylesheet cannot drift apart — the height must cover content +
+ *  padding + border, because the box is `border-box`. */
+const INPUT_PADDING_Y = 8;
+const INPUT_BORDER_WIDTH = 1;
+
 export function TextInputField(props: TextInputFieldProps) {
   const locale = useLoticsLocale();
   const {
@@ -105,8 +111,15 @@ export function TextInputField(props: TextInputFieldProps) {
     minLines: numberOfLines ?? 1,
   });
 
+  // `containerHeight` is the CONTENT's height, and the box is `border-box`, so
+  // growing to fit it means adding the padding AND the border. Adding only the
+  // padding left an auto-grown field 2px short of its own text — with
+  // `overflow: hidden` on the non-scrolling path, the last line was silently
+  // clipped by exactly the border. The same trap `CONTROL_TEXT_INSET` documents
+  // on the horizontal axis: read the padding, forget the border, land 1px per
+  // side wrong.
   const height = autoGrow
-    ? Math.max(minHeight ?? 40, autoGrowResult.containerHeight + 16)
+    ? Math.max(minHeight ?? 40, autoGrowResult.containerHeight + INPUT_PADDING_Y * 2 + INPUT_BORDER_WIDTH * 2)
     : minHeight;
 
   const editable = !!(!disabled || inputProps.editable);
@@ -225,7 +238,7 @@ const SHORTCUT_INSET = 12;
 const styles = StyleSheet.create({
   input: {
     borderRadius: CONTROL_RADIUS,
-    borderWidth: 1,
+    borderWidth: INPUT_BORDER_WIDTH,
     borderColor: colors.border,
     // The input surface is WHITE on ANY background — an input is an open well
     // to type into, and on a tinted panel (an inset fill editor, a toned card)
@@ -234,7 +247,7 @@ const styles = StyleSheet.create({
     // overrides via `style` (it lands after this in the array).
     backgroundColor: colors.white,
     height: 40,
-    paddingVertical: 8,
+    paddingVertical: INPUT_PADDING_Y,
     paddingHorizontal: 8,
     fontFamily: fontFamilyRegular,
     letterSpacing: -0.4,