@lotics/ui 22.3.0 → 23.0.0

package/AGENTS.md

@@ -53,8 +53,15 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **A button never contains a control** — a row that presses open AND carries its own controls
   (a CTA, ⋯, a checkbox, a `Link`) is a role-less `PressableRow` + a **`PressDoor`** sibling
   (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
-  button. `Table`/`TableRow` and `LinkedRecordBox` already do this. →
-  [composition.md](./docs/composition.md).
+  button. `Table`/`TableRow` already does this. → [composition.md](./docs/composition.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).
+- **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.
+  → [composition.md](./docs/composition.md).
 - **Files land THREE ways on any surface that holds them** — the section's Add CTA
   (`pickFiles`), and a drag OR paste, both from ONE **`<FileDropTarget … paste>`** wrapping the
   region — a Files section, OR a WHOLE surface (a record's section stack, a register page), so a

package/MIGRATION.md

@@ -4,6 +4,146 @@ 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.
 
+## 23.0.0 — the `Inline*` editors are WHITE, and `variant` is renamed
+
+```tsx
+<InlineSelect variant="cell" … />   // BEFORE
+<InlineSelect variant="bare" … />   // AFTER — same axis, named for the LOOK not the use
+```
+
+An inline editor now rests on THE pill surface — **white with a 1px border**, the same one `Chip`,
+`ChipGroup` and a secondary `Button` wear — hovering by darkening that border and adding the 2px
+ring when open. The zinc-50 chip is gone.
+
+`InlineEditVariant` survives but is renamed for what it IS rather than where it was used:
+**`"framed"`** (was `"form"`, still the default) keeps that frame visible; **`"bare"`** (was
+`"cell"`) shows nothing at rest and fades the SAME border in on hover. `"cell"` named a use — a
+grid cell — which is why nobody reached for it on the other dense surfaces it suits.
+
+The tint existed as the editability affordance (a read-only `InlineStatic` stays flat, so you could
+see what was editable without hovering). That still holds, and reads more plainly: a bordered box
+beside bare text is a stronger signal than a tint. What it also fixes is a fork in the vocabulary —
+a `ChipGroup` sitting in a field row was white-and-bordered next to zinc-50 editors, two species of
+control on one line.
+
+- **Rename every `variant="cell"` → `variant="bare"`.** The old literal is a type error, not a
+  silent no-op.
+- **`bare` hovers with the BORDER now, not a background wash.** One hover language across the
+  kit; the ROW under it still washes as a row, so a task/register row is unaffected.
+- **A `cell` used to read VALUE-FIRST** — the date dropped its resting calendar glyph and the
+  select its chevron, on the theory that a column header plus a uniformly-editable grid were
+  affordance enough. Both now show on every surface: one control, one promise.
+- **`disabled` still rests FLAT and borderless**, so an inert field never makes the promise.
+- **`InlineButton` inverted with it** — it is `Button secondary`'s zinc-100 fill now, not white,
+  and has no border. Its affordance was always CONTRAST with the field beneath it, not a colour;
+  a white verb on a white field dissolves.
+
+Row hover on a dense surface is unaffected: a `TaskItem`/`PressableRow` still washes as the ROW.
+What changed is only what the editor inside it looks like at rest.
+
+## 23.0.0 — `DetailRow.trailing` and `DetailTable.trailingWidth` are DELETED
+
+A row's third column is gone; a `DetailTable` is label + value, and the value fills what the
+label leaves. `InlineButton` (`@lotics/ui/inline_button`) is the replacement for the case that
+mattered.
+
+```tsx
+// BEFORE — the verb in a column the whole table pays for
+<DetailTable labelWidth={150} trailingWidth={88}>
+  <DetailRow label="Reference" trailing={<Button title="Copy" color="secondary" onPress={copy} />}>
+    <InlineTextInput value={ref} onSave={save} />
+  </DetailRow>
+  <DetailRow label="Priority"><InlineSelect … /></DetailRow>   {/* pays 88px, uses none */}
+</DetailTable>
+
+// AFTER — the verb on the field it acts on
+<DetailTable labelWidth={150}>
+  <DetailRow label="Reference">
+    <InlineTextInput value={ref} onSave={save}
+      actions={<InlineButton title="Copy" disabled={!ref} onPress={copy} />} />
+  </DetailRow>
+  <DetailRow label="Priority"><InlineSelect … /></DetailRow>
+</DetailTable>
+```
+
+`trailingWidth` was declared on the TABLE, so one row's action made EVERY row reserve the
+width — a stack of fields whose values all stopped short of an edge nothing occupied. And the
+control it held was usually about the VALUE, which meant reading a field on the left and
+pairing it with its verb at the page's right edge.
+
+Porting, by what the slot held:
+
+- **A verb about the value** (Copy, Call, Open) → **`InlineButton`** in the editor's `actions`.
+  Pass it UNCONDITIONALLY and `disabled` it when there is nothing to act on: a slot that
+  appears once the value is non-empty resizes the field as the user types. `actions` is on
+  `InlineTextInput` and on the `InlineEditView` / `InlineEditFrame` engine that custom editors
+  build on.
+- **A verb the editor can't host** — the select/date editors pass their ref to a `Popover` as
+  its anchor — → compose it into the VALUE cell: a `flexDirection: "row"` with the editor on
+  `flex: 1` and the verb beside it. One row deep, no column.
+- **A verb about the FORM, not the value** (a "Fetch" that fills three other fields) → the same
+  value-cell composition, or the surface's own footer. It was never a field's verb.
+- **A `Badge` or other qualifier** → beside the value in the value cell. It was never a column.
+- **Units** — already excluded before this release: `InlineNumberInput format`.
+
+`DetailRow` keeps `labelWidth`, `labelSize`, `minHeight`, `flat`, and the annotation trio
+(`description` / `warning` / `error`).
+
+## 23.0.0 — `LinkedRecordBox` is DELETED; a reference is a field
+
+```tsx
+// BEFORE — a bordered card, its own section, three surfaces for one name
+<LinkedRecordBox
+  icon="building-2" name={c.name} subtitle={c.code}
+  facts={[{ label: "Tax ID", value: c.taxId }, { label: "Contact", value: c.contact }]}
+  doorLabel={`${c.name} — details`} onOpen={open}
+  actions={<><Button title="Remove" color="danger" onPress={detach} /><View style={{ flex: 1 }} /><Button title="Open record" color="secondary" onPress={open} /></>}
+/>
+
+// AFTER — a value in a row, in whatever section the reference belongs to.
+// It wears the field surface, carries its go-to verb INSIDE, and peeks its
+// facts on press; detach lives in the peek. `tpl_record`'s `ReferenceValue`
+// is the worked composition.
+<DetailRow label="Customer">
+  <ReferenceValue name={c.name} code={c.code} facts={…} onOpen={open} onRemove={detach} />
+</DetailRow>
+```
+
+There is no replacement component, because the kit already had the answer and this was the
+exception to it: a person renders as a `MemberChip`, a file as a `FileBadge`, a select option
+as an `OptionBadge`, and a picked value in a field as a `<Chip onDismiss>` (the tags pattern).
+A record was the one reference drawn as a card — an icon tile, a facts grid and an action
+footer for a single name — which made a pointer to another row outweigh the fields it sat
+among and pushed hosts into giving it a whole Section.
+
+Porting, piece by piece:
+
+- **`icon`** — drop it. The label already names what the reference is; a glyph at value
+  altitude is decoration. (Keep one only where the *kind* varies row to row.)
+- **`name` + `subtitle`** — both go INSIDE the pill, name in default ink, subtitle muted. A
+  code sitting outside the chip reads as an orphan next to a link.
+- **`facts`** — they were the other record's fields, which never belonged on this one. A fact
+  THIS record actually uses (a tax id that gates invoicing) becomes this record's own
+  `DetailRow`, or the reference row's `warning` when it is a problem; the rest lives on the
+  record `Open` goes to.
+- **`onOpen` / `doorLabel`** — an **`InlineButton`** ("Open") INSIDE the value's surface. The
+  whole-box door is gone, but the a11y contract it owned is not: a container with its own
+  controls is still a role-less surface + a `PressDoor` sibling, which is what makes pressing
+  the value (to peek) and pressing Open two separate acts.
+- **`actions`** — the destructive verb moves into the PEEK's footer (destructive left, go-to
+  right), where it answers the question the peek asks. A detach link repeated down a column of
+  references is noise for an act most readers never perform.
+- **The STATIC variant** (no `onOpen`, fact values as nodes with inline editors) has no
+  successor by design. A record with no surface of its own has no identity to reference — its
+  values simply ARE this record's fields, so render them as a `Subsection` of `DetailRow`s with
+  no box around them.
+- **A whole Section built around one reference** collapses into the row. Its find-or-create
+  `Combobox` is the field's EMPTY state (same value slot), its create `Dialog` stays a dialog,
+  and its validity `Callout` becomes `DetailRow warning`. Remove the section's outline-rail
+  entry with it.
+
+`tpl_record`'s Customer and Handoff sections are the worked examples.
+
 ## 22.0.0 — `RangeSlider` is `Slider`, and single-value is a mode on it
 
 ```ts
@@ -53,7 +193,7 @@ values it was missing.
 
 ## v21 from 20.x
 
-**`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload · Select · Download all,
+**`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload, Select, Download all,
 swapping into a select-mode row whose actions hid behind a generic "Menu" — and that shape cost
 two things in real screens. A HOST verb had nowhere to go, so a surface that needed one (an AI
 read over the picked papers, "send these to the broker") hand-rolled the whole grid and lost the
@@ -90,7 +230,7 @@ the files is now composed below it.
 | `onDownloadZipSelected` | the same |
 | `readOnly` | withhold `onAdd`/`onRemove`; the pieces render nothing without a handler, so the composition IS the read-only shape and there is no second mode to keep in sync |
 | the "Menu" popover | the bar. Actions are visible controls, in the order the surface wants them |
-| `labels.menu` · `labels.share` · `labels.downloadZip` | deleted with the acts they named |
+| `labels.menu`, `labels.share`, `labels.downloadZip` | deleted with the acts they named |
 
 **No children means no bar** — a grid that previews and nothing else. That is the one rendering
 path; there is no default toolbar to fall back to.

package/docs/ai_patterns.md

@@ -21,15 +21,15 @@ the human stays in charge follows the stakes — split by whether a before-state
   is nothing to diff → **apply directly, then end on the RECEIPT**
   (`@lotics/ui/result_header`) — the receipt states the outcome and ROUTES; it is never a
   record editor. Run DETERMINISTIC checks over what the save STORED (a checksum, a count
-  reconciliation — binary math, never a fabricated score). ONE record: `ResultHeader` (tone ·
-  outcome title) → the RECEIPT LINES — a `DetailTable` of spread `DetailRow`s (who · how
-  much · how many · the schedule) — → **`Confidence`**: the level WITH its basis as
+  reconciliation — binary math, never a fabricated score). ONE record: `ResultHeader` (tone,
+  outcome title) → the RECEIPT LINES — a `DetailTable` of spread `DetailRow`s (who, how
+  much, how many, the schedule) — → **`Confidence`**: the level WITH its basis as
   one block, always (the happy path says what was checked; the flagged path NAMES the exact
   failing values — the user knows what to verify BEFORE opening). Confidence never floats
   alone as a bare meter on a result surface. NOTHING in the receipt edits: the RECORD is the edit surface (its
   flagged cells carry the same amber marks), one press away — correction uses the record's
   ordinary verbs. SEVERAL records: a compact attention-first RESULT REGISTER (`ListItem` per
-  record — tone mark · outcome title · key figures · the needs-checking count) whose rows
+  record — tone mark, outcome title, key figures, the needs-checking count) whose rows
   press STRAIGHT THROUGH to the record — no intermediate screen. Never tabs (they cap out),
   never stacked collapsed cards, never a field wall duplicating the record page. A
   flagged value names its exact verdict in amber (a reason line under the value, or a check
@@ -69,7 +69,7 @@ Three shapes:
    the thread, version chains, branching, session memory. An in-app "edit chat" would
    re-implement all of that inside every app.
 
-The Document desk's Use-AI fork IS this table as UI: Extract data (1) · Cross-check (2) ·
+The Document desk's Use-AI fork IS this table as UI: Extract data (1), Cross-check (2),
 Edit with AI (3) — one entry point, three outcome shapes
 ([`tpl_record`](../examples/tpl_record.tsx)'s Documents section).
 
@@ -151,7 +151,7 @@ Output panel; `undefined` keeps it. Input + error rendering are untouched.
 **Activity grouping.** Consecutive tool parts fold into ONE group. While the agent is mid-tools
 the tail group is a SINGLE pulsing row whose label swaps in place as each call fires (no growing
 stack of dots); once prose resumes the group settles: a single call becomes one done row, and a
-multi-call group becomes a persistent "{final action} · {n} steps" HEADER (a `complete` terminal
+multi-call group becomes a persistent "{final action} ({n} steps)" HEADER (a `complete` terminal
 dot — distinct from the filled `done` step dots; amber `warning` if any call errored) that STAYS
 PUT and rolls the calls out BELOW it on press. The run ALWAYS ends on the agent's text — there is
 no global terminal node.
@@ -292,22 +292,22 @@ composes from twelve pieces in three groups (all in `@lotics/ui/change_review`;
 - **`ChangeFields` + `ChangeField`** — THE field unit. `ChangeFields` is the OPEN form (the
   section IS the record — an extract dialog's one order: no card chrome), stacking `ChangeField`s
   with hairline rules. A diff-form `ChangeField` renders, top to bottom: the label (sm medium,
-  **full colour** — it names the subject of a decision, never `DetailRow`'s muted ink) · the
-  field's `reasoning` directly under the label · the `−` band when replacing (`before`) · the
+  **full colour** — it names the subject of a decision, never `DetailRow`'s muted ink), the
+  field's `reasoning` directly under the label, the `−` band when replacing (`before`), the
   value — `ChangeValueInput` when `onChangeText` is given (the green `+` band; pressing it edits
   IN THE BAND — a borderless input with identical type metrics, so nothing shifts), the read-only
   `+` band when `valueReadOnly` or no `onChangeText` (muted `placeholder` while empty), or any
   input via `children` — compose `<ChangeValueInput unit="pcs" …>` there yourself for a unit
   suffix (`unit` fixes the suffix outside the editable core — type the number, never the unit;
-  the built-in default doesn't take it) · conflict `candidates` as full-width decision rows
+  the built-in default doesn't take it), conflict `candidates` as full-width decision rows
   (picked via `onPickCandidate`) + the localized "Type another value" third option
   (`customValue`/`customSelected`/`onCustomValue`/`onCustomSelect`; the outcome band is read-only
   via `valueReadOnly` — the decision comes from picking, never from editing the band; gate with
-  `keepDisabled`) · per-field **Keep/Drop** bottom-right
+  `keepDisabled`), per-field **Keep/Drop** bottom-right
   (`status: "pending" | "kept" | "dropped"`, `onKeep`/`onDrop`/`onUndo`). A pure REMOVAL is
   `before` with no value — the `−` band alone. A decided field collapses to the compact one-row
-  card (mark · label → `summary` · Undo). A field with no diff and no decision is the plain
-  inline label · value row — this form borrows `DetailRow`'s *metrics* (130px label column /
+  card (mark, label → `summary`, Undo). A field with no diff and no decision is the plain
+  inline label, value row — this form borrows `DetailRow`'s *metrics* (130px label column /
   40px row) — press-to-edit when `onChangeText` is given.
 
   **Limitation:** `ChangeFieldCandidate.source` and `.description` are accepted by the type but
@@ -432,8 +432,8 @@ meter + level phrase head the block, and the REQUIRED `children` carry the basis
 checked and what came of it ("all 7 references pass their checksum" / "2 of 7 fail (X, Y) —
 verify against the source"). The box stays white with a hairline border at EVERY level — the
 meter is the only colored element (the level already lives in the meter and the phrase; a
-tinted fill would say it a third time). Pass `level` or a 0–1 `score` (≥0.8 high ·
-≥0.5 medium · else low; `levelFromScore` exported). There is NO standalone meter: a level
+tinted fill would say it a third time). Pass `level` or a 0–1 `score` (≥0.8 high,
+≥0.5 medium, else low; `levelFromScore` exported). There is NO standalone meter: a level
 without its reasons cannot be acted on, so it cannot be rendered — and where a compact meter
 used to decorate a ranked row or a proposal card, remove it (rank, badges, and severity
 already convey standing). Derive levels HONESTLY (deterministic checks: all pass → high, any
@@ -442,16 +442,16 @@ fail → low) — never render a fabricated score.
 ## Findings — evidence, not writes
 
 `Finding` (`@lotics/ui/finding`) is one ranked insight from an AI check — a cross-check
-discrepancy, an audit observation, a briefing item: severity dot-badge + localized word ·
-`title` · `detail` · the PROMINENT `metric` (lg semibold, never a side note) + `metricCaption` ·
+discrepancy, an audit observation, a briefing item: severity dot-badge + localized word,
+`title`, `detail`, the PROMINENT `metric` (lg semibold, never a side note) + `metricCaption`,
 `Sources` chips at the bottom (`sources`/`onOpenSource`), with a `children` slot between body and
-sources. Severity → colour: `critical` red · `warning` amber · `info` zinc ("Note") · `positive`
+sources. Severity → colour: `critical` red, `warning` amber, `info` zinc ("Note"), `positive`
 emerald ("On track"); words come from the `finding` locale slice. **Display-only**: a finding
 informs the action the human takes in the app; it decides nothing itself — no phantom "record
 verdict" write (a persisted check-status goes stale on the next edit). Stack several most-severe
 first — inside a `ChangeReview` wrap each in a display-only `Change` (the family's dividers
 apply). `FindingComparison` is the expected-vs-actual body: each disagreeing side a labeled row
-(source · value), a hairline, then the DELTA emphasized — compose it as the finding's children
+(source, value), a hairline, then the DELTA emphasized — compose it as the finding's children
 for any one-value-disagrees insight (quantities, totals, dates).
 
 ## Session, not chat
@@ -496,10 +496,10 @@ ranked set, don't cram it into chat prose:
   document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
   the two document tasks, each a specialized run with a task-pure result: **Extract** (files
   read → fields already matching fold into one quiet line → every add / update / conflict a
-  `ChangeField` (the `−` band · the editable value · candidate rows), the record's current value
+  `ChangeField` (the `−` band, the editable value, candidate rows), the record's current value
   a first-class choice — plus proposed new lines as record-body `Change`s → one outcome-named
   `ChangeReviewActions` commit) and **Cross-check** (documents compared against the record and
-  each other → ranked `Finding`s — severity · title · the prominent metric · sources — separated
+  each other → ranked `Finding`s — severity, title, the prominent metric, sources — separated
   by hairlines; the findings ARE the outcome the human acts on). The fork carries an OPTIONAL
   instructions field — the user steers what the agent checks or extracts, so `Finding` serves ANY
   file-based AI request, not just the stock cross-check. Every file list in the flow opens the
@@ -530,7 +530,7 @@ ranked set, don't cram it into chat prose:
 The AI vocabulary has **no purple accent and no gimmick glyphs** (no sparkles) — but it is NOT
 monochrome: **colour is used where it carries meaning, not for decoration.** What the violet
 sparkle used to carry now reads structurally — **provenance** is a quiet sentence-case microlabel
-naming the artifact ("Proposed" · "Match" · "Mismatch" · "Suggested edit" · "Question" — xs,
+naming the artifact ("Proposed", "Match", "Mismatch", "Suggested edit", "Question" — xs,
 muted, medium; all-caps is banned kit-wide), and the agent's **reasoning** is a left-ruled margin
 note (a hairline rule + muted text — `ChangeReasoning`), quoted apart from the facts and the
 human's controls — while **status/severity/diffs use functional colour** the way the rest of the
@@ -546,7 +546,7 @@ kit does:
 - **ChangeBand** — the removed value on the light **red** band with the `−` marker, the incoming
   value on the light **emerald** band with `+` (the GitHub-diff idiom, markers in one aligned
   column); everything else in a review stays neutral — a decided row reads a single emerald
-  check, an add/remove record card wears the quiet tone wash (50 body · 100 header · 200 border).
+  check, an add/remove record card wears the quiet tone wash (50 body, 100 header, 200 border).
   Colour marks the change, never the chrome.
 - **Finding severity** — the coloured dot badge (red / amber / zinc / emerald), most severe
   first.