@lotics/ui 22.3.0 → 23.1.0

package/docs/catalog.md

@@ -20,7 +20,7 @@ indexed in [AGENTS.md](../AGENTS.md).
 - **If the closest component lacks a capability, extend it** (a platform change every app
   inherits), never inline a one-off `View`/`Text` rebuild — that forfeits the typeahead,
   async search, virtualization, and a11y the primitive already ships.
-- Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `OptionList`) needs a
+- Floating content (`Dialog`, `Popover`, `Tooltip`, `Alert`, `OptionList`) needs a
   `PortalHost` (`@lotics/ui/portal`) at the app root.
 - Worked examples referenced below (`tpl_record`, `tpl_item_list`, …) ship in
   [`../examples/`](../examples/).
@@ -95,8 +95,15 @@ Batch draft-form state → `useForm`.
 
 ### Edit a record's fields in place
 
-The `Inline*` family: `InlineTextInput` · `InlineNumberInput` · `InlineSelect` (single or
-`multi`) · `InlineMemberSelect` · `InlineDatePicker` · `InlineTimePicker`; a
+The `Inline*` family: `InlineTextInput` (**`numberOfLines`** — the line budget for a value a
+reader must read WHOLE rather than recognise at a glance: a payment term, an address, a clause.
+Above 1 the resting box RESERVES that many lines — the full editor height, not the height this
+particular value needs — so clicking in moves neither the field nor anything below it; Enter
+then inserts a newline and the value commits on blur. Both halves matter: a field that only
+goes multiline once focused hides the text from the reader who never clicks, and one that
+reserves less than it opens to shoves the rest of the form down the page on every click),
+`InlineNumberInput`, `InlineSelect` (single or
+`multi`), `InlineMemberSelect`, `InlineDatePicker`, `InlineTimePicker`; a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
 input chrome, so it aligns pixel-for-pixel). A stack of labelled field rows lives in
 `DetailTable` + `DetailRow`; the record's identity band is `RecordSummary`; its money
@@ -151,13 +158,13 @@ Two columnar shapes, and the choice is about data size:
 
 ### Numbers & charts
 
-`KPIStrip` (the dashboard stat band) · `SummaryLine` (the light inline register/list summary
-— below the toolbar, from the filtered rows) · `KPICard` / `Metric` (headline figures),
+`KPIStrip` (the dashboard stat band), `SummaryLine` (the light inline register/list summary
+— below the toolbar, from the filtered rows), `KPICard` / `Metric` (headline figures),
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
 set — no recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a
 plain sm tabular count beside it — the cell/heading/peek-trigger meter; a caption floating
 above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
-its max it reads `2,100 / 2,000 · 105%`, because a meter that says "100%" when you are over
+its max it reads `2,100 / 2,000 (105%)`, because a meter that says "100%" when you are over
 tells the reader they are exactly at the limit. Numbers format in the reader's locale, so
 never hand-format the value you pass in — when display precision differs from the true value
 (whole credits off a fractional balance), `formatValue` reshapes the caption text and leaves
@@ -206,8 +213,8 @@ controls is `PressableRow` + **`PressDoor`** — never `PressableHighlight`, whi
 button and wraps its children (a button must not contain interactive descendants). The
 door is an empty absolutely-positioned SIBLING of the content carrying the tab stop,
 accessible name, and focus ring; lift the content above it with `zIndex: 1`. `Table`/
-`TableRow` and `LinkedRecordBox` do exactly this internally, so a columnar register needs
-no assembly — reach for `PressDoor` only outside them.
+`TableRow` does exactly this internally, so a columnar register needs no assembly —
+reach for `PressDoor` only outside it.
 
 ### Filters & view controls
 
@@ -246,7 +253,11 @@ scoped to that region's focus; the region-wrapper next to `FileDropzone`'s dedic
 "files land without hunting for a dropzone", `FileRow` (a horizontal file/document LINE —
 badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge /
 action / remove; `onPress` makes the whole row a pressable door, `trailing` stays an
-independently-pressable sibling; for checklists & readable lists), `FileBadge` (the two-tone
+independently-pressable sibling; for checklists & readable lists. **`size`** — `sm` (default)
+is the compact attachment line for many files scanned as a list; **`md` is the document-desk
+row** (taller badge, `ListItem` height) for the FEW rows that ARE the section's subject — an
+expected-document checklist, a slot a button fills. A two-row section at `sm` reads as an
+appendix to the page rather than its point), `FileBadge` (the two-tone
 type mark), `FilePreview` / `FileGalleryModal`, `ImageGallery`; picking is `pickFiles`
 (`@lotics/ui/file_picker` — opens the browser picker and resolves the chosen `File[]`, the
 imperative half behind every Add-file CTA); for gated CRUD compose locally with
@@ -255,7 +266,7 @@ patterns doc indexed in [AGENTS.md](../AGENTS.md)).
 
 ### Specialized work surfaces
 
-`ScanField` (scan/verify), `Stepper` (a guided run / progress sequence — done · current ·
+`ScanField` (scan/verify), `Stepper` (a guided run / progress sequence — done, current,
 upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocation),
 `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
 `Calendar` (the `calendar` module's views), `Gantt`, `comments_thread`.
@@ -266,15 +277,15 @@ upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocatio
 long text + attachments; the surface that triggers agent work), `AgentRun` (the live
 streaming work feed) + `AgentProgress` (its compact, floating, expandable form — a
 composer's "working" state) + `Confidence`; **`ChangeReview` — THE one review-before-apply
-surface, a COMPOUND family** (frame: `ChangeReview` · `ChangeReviewHeader` ·
-`ChangeReviewActions`; sections: `Change` · `ChangeLabel` · `ChangeSummary` ·
-`ChangeReasoning`; the grammar: `ChangeFields` + `ChangeField` · `ChangeRecord` ·
+surface, a COMPOUND family** (frame: `ChangeReview`, `ChangeReviewHeader`,
+`ChangeReviewActions`; sections: `Change`, `ChangeLabel`, `ChangeSummary`,
+`ChangeReasoning`; the grammar: `ChangeFields` + `ChangeField`, `ChangeRecord`,
 `ChangeBand` + `ChangeValueInput`): adds, updates, removals, conflicts, whole records,
 display-only findings are all compositions — see the AI-patterns doc indexed in
 [AGENTS.md](../AGENTS.md) for the laws; `Clarify` (the agent asks back — selectable
 `ChoiceList` options), `Sources` (provenance chips for AI output — at review scale,
 `label={null}` slots the chips at a section's bottom), `Finding` (one ranked insight from an
-AI check — localized severity word · title · detail · `Sources` chips · a `children` slot;
+AI check — localized severity word, title, detail, `Sources` chips, a `children` slot;
 **`FindingComparison`** is the expected-vs-actual body: each disagreeing side a labeled row,
 the DELTA emphasized under a hairline (localized "Difference") — quantities, totals, dates;
 a plain `metric` prop remains for one-number findings. The children slot composes ANY visual
@@ -336,18 +347,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   weekday/month names, and `formatDate` display all follow the provider with no per-instance
   `locale` prop — an explicit `locale` still overrides. **Limitation:** the calendar/gantt
   views and the comment labels are not yet provider-wired — pass their `labels` props directly.
-- **`colors`** — the palette + `withAlpha` · `solid` · `tint` · `ramp` · `ColorName` ·
-  `isColorName` · `asColorName` (coerce a stored option/status token to a `ColorName`,
+- **`colors`** — the palette + `withAlpha`, `solid`, `tint`, `ramp`, `ColorName`,
+  `isColorName`, `asColorName` (coerce a stored option/status token to a `ColorName`,
   neutral fallback).
 - **`tokens`** — design tokens: re-exports `colors` plus `space`/`type`/`weight`/`radius`
   scales and `getCssVariables()` — an OPT-IN serializer to `--lotics-*` CSS variables for
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
 - **`spacing`** — the `SPACE` scale + `SpaceToken`.
-- **`control_surface`** — `CONTROL_HEIGHT` (40) · `CONTROL_RADIUS` (10) · `CONTROL_TEXT_INSET`
+- **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
-  up with a control's WORDS rather than its box carries it, and `TASK_TEXT_INSET` IS it) ·
-  `FOCUS_RING` · `HOVER_BORDER` · `CONTROL_TRANSITION` · `chipSurfaceStyle` — the shared
+  up with a control's WORDS rather than its box carries it, and `TASK_TEXT_INSET` IS it),
+  `FOCUS_RING`, `HOVER_BORDER`, `CONTROL_TRANSITION`, `chipSurfaceStyle` — the shared
   control-surface tokens.
 - **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
   every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
@@ -380,15 +391,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Layout & surfaces
 
-- **`card`** — `Card` · `CardHeader` · `CardHeaderTitle` (+ `info` ⓘ popover) ·
-  `CardHeaderMeta` · `CardBody` · `CardFooter`.
-- **`inset`** — `Inset`: a tinted, recessed content surface (zinc-50 fill · 10 radius · 14
-  pad · 12 gap) — the "well" INSIDE a Card/Section for a grouped sub-form, an inline fill
+- **`card`** — `Card`, `CardHeader`, `CardHeaderTitle` (+ `info` ⓘ popover),
+  `CardHeaderMeta`, `CardBody`, `CardFooter`.
+- **`inset`** — `Inset`: a tinted, recessed content surface (zinc-50 fill, 10 radius, 14
+  pad, 12 gap) — the "well" INSIDE a Card/Section for a grouped sub-form, an inline fill
   editor, or a nested block. **NOT a `Callout`:** a Callout is a status BAND (and
   `warning`/`error` render as an ARIA `alert`) — wrapping form fields in an alert is wrong.
   The law: **content + fields → `Inset`; a message → `Callout`.**
-- **`section_heading`** — `Section` · `SectionHeading` · `SectionHeadingTitle` ·
-  `SectionHeadingMeta` · `Subsection` · `SubsectionHeading` · `SubsectionHeadingTitle` ·
+- **`section_heading`** — `Section`, `SectionHeading`, `SectionHeadingTitle`,
+  `SectionHeadingMeta`, `Subsection`, `SubsectionHeading`, `SubsectionHeadingTitle`,
   `DialogSectionHeadingTitle` — the
   card-less twin of the Card family, compound, owns no margin; spacing via the Section gap
   (16, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
@@ -399,7 +410,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   md-semibold rung with the SAME `icon`/`description`/`info` slots as the section title, so a
   dialog surface loses only the type size, never an affordance. The heading ramp is FIXED:
   `#` xxl / `##` xl / `###` lg / `####` md, no size props.
-- **`section_stack`** — `SectionStack` · `SubsectionStack` — stacks that own the
+- **`section_stack`** — `SectionStack`, `SubsectionStack` — stacks that own the
   between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline
   `Divider` between top-level blocks; `SubsectionStack` = a fixed 32px beat, space-only while
   the groups are SHORT (the titles carry the grouping, hairlines stay at the section level) and
@@ -467,7 +478,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the `chip.remove` locale slice). Suggestion pills → `SuggestionChip`.
 - **`action_menu`** — `ActionMenu`: the ⋯ overflow menu (`ActionMenuItem[]`; danger items
   last).
-- **`menu_button`** — `MenuButton`: the menu/rail row (icon · title · `right` slot;
+- **`menu_button`** — `MenuButton`: the menu/rail row (icon, title, `right` slot;
   `focused`/`danger`; `role` menuitem|button|option) — popover menus, outline rails, section
   pickers. Its resting highlight has TWO meanings and they are not interchangeable:
   **`selected`** is listbox SELECTION (emitted as `aria-selected`, and only under
@@ -490,27 +501,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   own controls. Pair it with `PressableRow` (surface takes the mouse + the wash, door takes
   the keyboard, nested controls keep their own presses); the parent owns the positioning
   context and the content lifts above the door with `zIndex: 1`. `radius` (default 10)
-  matches the surface it spans. `TableRow` / `LinkedRecordBox` are the in-kit consumers —
-  reach for it when designing a row those don't cover.
-- **`linked_record_box`** — `LinkedRecordBox`: a bordered box scoping ANOTHER record's data
-  (`icon` · `name` · `subtitle` · vertical `facts`); verbs ride an `actions` slot in a
-  hairline-fenced footer at the bottom (destructive LEFT, go-to RIGHT — the divider draws itself
-  when `actions` is present, so don't hand-add one). Use it wherever a record points at another (a
-  shipment's customer, an invoice's party, a case's sibling). **`onOpen` picks the variant, and
-  they are exclusive at the type level**: WITH it (+ the required `doorLabel`) the whole box is a
-  keyboard door into the record's detail and `facts` values are TEXT (`""` → "—"); WITHOUT it the
-  box is a STATIC card — no door, no tab stop, no pointer, nothing announced as a button — and a
-  `facts` value may be a NODE (an inline editor; a node prints as authored, no "—"). A node fact
-  gets the CONTROL BAND on both cells — its label centres on the control instead of printing at
-  the band's top — while a string fact keeps its bare text line, so a long value that wraps still
-  tops out level with its label. Reach for the
-  static one when the linked record has NO page of its own: nothing to open, so the box is where
-  its values are read and edited, and the only interactive parts are `actions` + the fact nodes.
-  Under a door, `actions` is the ONLY place a control may live (a fact editor there would compete
-  with the press). The door variant **enforces the a11y contract** copy-pasting got wrong: a
-  container with interactive descendants is never `role="button"` (invalid HTML) — an internal
-  empty door sibling carries the tab stop / name / focus ring, verbs lift above via `zIndex`.
-  The reassign picker / empty state that swaps in for the box is the consumer's.
+  matches the surface it spans. `TableRow` is the in-kit consumer — reach for it when
+  designing a pressable surface it doesn't cover.
 - **`pressable_highlight`** — `PressableHighlight`: the hover-wash + keyboard-focus-ring
   `Pressable` under `MenuButton`/`Switcher`/custom pressable surfaces; its style-fn/children
   receive `hovered` + `focusVisible`.
@@ -526,7 +518,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   shortcut from a raw string or `ShortcutDescriptor` (⌘B on Mac, Ctrl+B elsewhere); null on
   small screens. `TextInputField shortcut` renders it built-in, while the field is EMPTY —
   it hints at reaching the field, so a value replaces it (with the clear ✕, when `clearable`).
-- **`keyboard`** — `isMac` · `ShortcutDescriptor` · `formatShortcut` (platform-aware
+- **`keyboard`** — `isMac`, `ShortcutDescriptor`, `formatShortcut` (platform-aware
   shortcut formatting behind `ShortcutBadge`).
 
 ### Badges, status & feedback
@@ -538,7 +530,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (see composition.md "Badge is for status only"). A bare `<Badge>` is `dot`.
 - **`status_badge`** — `StatusBadge`: an enabled/disabled pulse badge (`enabled` + `label`).
 - **`option_badge`** — `OptionBadge`: a select value as its configured colored badge.
-- **`callout`** — `Callout` · `CalloutTitle` · `CalloutText` · `CalloutActions` (`tone`
+- **`callout`** — `Callout`, `CalloutTitle`, `CalloutText`, `CalloutActions` (`tone`
   info|success|warning|error|neutral): inline status band — a MESSAGE (`warning`/`error`
   are ARIA `alert`s). For a form / nested content surface use **`Inset`**, never a Callout.
 - **`empty_state`** — `EmptyState`: centered placeholder for an empty list/filter result —
@@ -664,17 +656,30 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   INSIDE the control and inline error, commit on blur (Enter saves, Escape reverts) or
   `controls="buttons"`; KEYBOARD focus on the closed view opens edit mode with the input
   focused (type → Tab → type — see the data-entry keyboard contract), pointer focus never
-  does; **`variant: "form" | "cell"`** is THE axis that separates a form field from a data-grid
-  cell (see below). Every commit registers in **`pending_commits`**, which
+  does; **`variant: "framed" | "bare"`** sets how much of the field's frame shows AT REST
+  (see below). Every commit registers in **`pending_commits`**, which
   `Button`/`IconButton` wait on via **`use_gated_press`** so an action pressed in the same
   gesture as the blur cannot read the record before the edit lands (data_entry.md § Inline
   edit) — automatic, nothing to pass.
+  **`actions` puts VERBS on the field's surface** (an `InlineButton` — Copy, Open, Today), and
+  EVERY `Inline*` editor takes it. `trailing` is decoration only (a chevron, a spinner): it
+  renders INSIDE the press target, so a button there would be a button in a button.
+  With `actions` the field renders through ONE shell that owns the surface in BOTH modes — so
+  the verbs never move when the editor swaps to its input, the control inside goes `seamless`
+  (drawing no second box), hover is tracked on the box (react-native-web hands a parent's hover
+  to the innermost pressable, so a control-tracked border drops out as the pointer crosses a
+  verb), and the focus ring paints on the whole FIELD via focus-within, not on the value region.
+  A popover-backed editor also anchors its overlay to the shell (`anchorRef`) rather than to the
+  control — with verbs the control is narrower than the field, and an inherited width would open
+  a list too small for its own row.
+  Pass `actions` UNCONDITIONALLY and `disabled` the verb when it has nothing to act on: a slot
+  that appears once the value is non-empty resizes the field as the user types.
 - **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
   (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
   — locale field order, separator advances, Alt+ArrowDown floats the calendar; click still
   opens the calendar popover), **`inline_time_picker`** — the inline field editors (a form field by
-  default, a grid cell with `variant="cell"` — see the split below);
+  the same editor everywhere, `variant="bare"` on a dense grid — see the surface note below);
   `InlineSelect`/`InlineMemberSelect` render the resting value like its option —
   `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not
   just text. **`InlineSelect` is single OR multi** — pass `multi` for a tag SET (`value: T[]`,
@@ -687,38 +692,64 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (`TextColor`) that colours the resting date by
   semantic state — overdue red, soon-due amber (the caller owns the rule, e.g. a task's `dueTone`);
   the value text IS the signal, no separate dot.
-  **The form/cell split — one `variant`, not a second family.** Every `Inline*` editor is BOTH a
-  form field and a data-grid cell; `variant` picks which:
-  - **`variant="form"`** (default) — a zinc-50 chip at rest + a hover-BORDER. THE editability
-    affordance on a surface that MIXES editable and static values (a `DetailTable` / record field).
-  - **`variant="cell"`** — transparent at rest + a background-tint WASH on hover (`zinc-100` /
-    `zinc-200` press — the same `PressableHighlight` language as the row/cell beside it), and it reads
-    VALUE-FIRST: the date drops its resting calendar glyph, a select drops its chevron (the column
-    header + the uniformly-editable grid are the affordance; the saving spinner still shows). For a
-    DENSE, uniformly-editable surface — a register/`DataGrid` column, a task row (worked example:
-    `tpl_task_board`'s columns, `tpl_item_list`'s rows).
-
-  There is NO separate `*Cell` component family — a data-grid cell is `<InlineSelect variant="cell" …/>`,
-  not a `SelectCell`. (Naming a component for a USE, and duplicating the picker stack to flip two
-  style properties, are both things the kit forbids.) A custom pressable cell you hand-roll should
-  match the `variant="cell"` language: the `PressableHighlight` wash, never a border.
+  **ONE surface, ONE hover language; `variant` sets its resting WEIGHT.** An editor wears THE pill
+  surface — white, 1px border, the same one `Chip`, `ChipGroup` and a secondary `Button` wear — so
+  every control a row can hold reads as one family. Open adds the 2px ring; disabled rests flat and
+  borderless, promising no press. HOVER differs by variant, because hover must be a visible CHANGE
+  rather than a deeper line: `framed` deepens its border AND tints (zinc-200 → zinc-400 alone is a
+  shade shift on 1px), `bare` has the border ARRIVE (loud by itself — and a tint there would make a
+  hovered cell lighter than the row washing beneath it).
+  - **`variant="framed"`** (default) — the frame is already showing. Required wherever editable and
+    static values MIX (a record's `DetailTable`): there it is the only thing saying what you can change.
+  - **`variant="bare"`** — nothing at rest, the SAME border on hover. For a surface where EVERY value
+    edits (a register/`DataGrid` column, a task row), where a per-field frame states what the whole
+    surface already promises and, down a column, draws the grid twice.
+
+  It is an axis of weight, not of use: both hover and open identically. There is no `*Cell` family —
+  a data-grid cell is `<InlineSelect variant="bare" …/>`, not a `SelectCell` (naming a component for a
+  USE, and duplicating the picker stack to flip two style properties, are both things the kit forbids).
+  Hand-roll a pressable cell to match `bare`, never a background wash.
 - **`inline_static`** — `InlineStatic`: a READ-ONLY value matching the Inline\* box metrics
   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.
+- **`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
+  VARIABLE number of positions: one field per position (`Origin` / `Transfer point` /
+  `Destination`) cannot hold a second middle entry and cannot say the entries are ordered.
+  `SequenceItem` takes the content, an optional `role` (DERIVE it from index — a stored role lies
+  the moment the list is reordered) and `onMoveUp`/`onMoveDown`/`onRemove`; the controls render
+  even where they cannot act so the right edge never shifts between items. Reorder is BUTTONS,
+  not a drag handle — dragging is invisible to the keyboard and fiddly on a phone, and a
+  three-to-six position list does not need it. Indent anything that follows the list (an "Add"
+  link) by `SEQUENCE_INSET` so it lands on the rail's column. Distinct from `Timeline` (an
+  activity FEED), `Stepper` (a wizard's fixed positions) and `Pipeline` (ONE record walking
+  stages that own their controls) — this is the list a user EDITS.
+- **`inline_button`** — `InlineButton`: a verb that sits INSIDE an inline field's surface
+  (the `Open` on a reference, a `Copy` on a value worth copying) rather than in the row's
+  trailing column — put it inside when the act is ABOUT THE VALUE, so it travels with what it
+  acts on and the trailing column stays free for row-level verbs. FILLED (`Button secondary`'s own
+  zinc-100) on the field's white surface — the contrast is a RELATIONSHIP, not a colour: invert it
+  if the resting field surface ever changes, or the verb dissolves into the value. 28px, radius 8,
+  no border (the field already has one) and no shadow (depth belongs to the primary action alone). **It stops propagation** — that is the contract: the
+  surface underneath is itself pressable, so without it one press fires both, silently. Always
+  a WORD, never icon-only.
 - **`detail_row`** — `DetailTable` + `DetailRow` — the record field grid. `DetailRow`:
   label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column
   FILLS the row so a stack of inline editors all span the same width + none jumps wider on
-  edit; optional `trailing` slot renders a right-side action/badge after the value (units
-  belong IN the value via `InlineNumberInput format`). The LABEL WRAPS inside its column and
+  edit. There is NO trailing slot: a verb about the VALUE goes on the field (`InlineButton` in
+  the editor's `actions`), and anything else that belongs beside the value — a status `Badge`, a
+  unit (though "kg"/"$" belong IN the value via `InlineNumberInput format`) — composes into a
+  row inside the value cell, costing only the row that wants it. The LABEL WRAPS inside its column and
   is never clipped — a fixed `labelWidth` would otherwise ellipsize every long field name
   ("Registered business address"), and a name the reader can't finish is worse than a taller
   row; a wrapped label's FIRST line stays level with the value's first control line while a
   one-line label still centers on it (both modes, no prop). The FIELD-ANNOTATION vocabulary (same
   names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
   **`description`** = a fact / persistent guidance (muted), under the VALUE (stacked mode
-  mirrors the form order label · description · control); **`warning`** = a consequence to weigh
+  mirrors the form order label, description, control); **`warning`** = a consequence to weigh
   before acting (amber, announced); **`error`** = field-level failure under the value, danger +
   alert semantics (the `Inline*` editors already render their own transient save errors — don't
   wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
@@ -729,19 +760,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   on two surfaces.
   `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default `DETAIL_LABEL_WIDTH`, 130 — THE kit's label column, and
-  a `TaskList`'s default too) / `trailingWidth` / `minHeight` (default 40, the
-  inline-control grid) declared ONCE + the 8px row gap; with `trailingWidth` every row
-  reserves the trailing column so value cells share one width and trailing items align at
-  one x, like a table. RESPONSIVE with no prop: it measures its own container (onLayout, not
+  a `TaskList`'s default too) / `minHeight` (default 40, the inline-control grid) declared
+  ONCE + the `SPACE.md` (16) row gap — 8 was right while a field was a tint, but a stack of
+  BORDERED rows that close together fuses into one block. TWO columns, no third: the value
+  FILLS what the label leaves, so nothing one row does can narrow its neighbours' editors. RESPONSIVE with no prop: it
+  measures its own container (onLayout, not
   the viewport — works inside a Drawer; the unmeasured first frame renders opacity-0 so the
   first PAINT is already in the right mode) and when the columns would crush the value cell
   it STACKS every row (the label above a full-width value row in the FormField label
-  grammar; trailing beside the value); raise `minValueWidth` (default 160) when a cell holds
+  grammar); raise `minValueWidth` (default 160) when a cell holds
   MORE than one editor so the table stacks earlier. Two tables on one page share one grid by
-  repeating the same labelWidth/trailingWidth. Worked example:
+  repeating the same labelWidth. Worked example:
   [`tpl_record`](../examples/tpl_record.tsx).
 - **`record_summary`** — `RecordSummary`: the identity band of a record detail/drawer — ONE
-  row: `title` xxl semibold tabular · `subtitle` sm muted · `status` Badge slot · optional
+  row: `title` xxl semibold tabular, `subtitle` sm muted, `status` Badge slot, optional
   `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS
   never live in the header: compose them as `DetailTable`s in the sections below. Replaces
   hand-rolled record headers (mixed scales, several competing figures, color noise).
@@ -819,7 +851,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
   `TaskStatus` takes the `CheckCircle` (omit `onChange` for a read-only ring; a PICKER list
   puts a `CheckboxInput` here and sets `controlWidth={24}`). `TaskTitle` takes the
-  `variant="cell"` `InlineTextInput` — or the title TEXT itself as a string child
+  `InlineTextInput variant="bare"` — or the title TEXT itself as a string child
   (`<TaskTitle struck={done}>{label}</TaskTitle>`), which is the READ-ONLY form: the compound
   applies the cell inset and the row's band, so a plain `<Text>` + a hand-rolled
   `TASK_TEXT_INSET` is never needed and a long title that wraps keeps its first line beside the
@@ -831,7 +863,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   gutter on the first line (Delete lives BEHIND it, danger-styled and last, never a bare ✕).
   `TaskDetail` is a FREE-FORM block under the row on the title's text edge — a chart, a table, a
   form with its own submit — rendered only while open. The module also exports
-  **`TASK_TEXT_INSET`** (9), the inset a `variant="cell"` control puts on its own text: every
+  **`TASK_TEXT_INSET`** (9), the inset an inline control puts on its own text: every
   slot above already applies it, so reach for it ONLY when a custom title NODE (not a cell
   control) has to land on the same text edge.
 
@@ -844,7 +876,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   step inward per level. Declare `actionWidth={0}` when NO row in the list carries actions.
 
   **THE ROW CARRIES THE TITLE; THE FIELDS THE USER CAN SET ARE SUB-ROWS BENEATH IT.** One task's
-  own fields hang under it as **`TaskSubRow`** (`label` · the control · `description` /
+  own fields hang under it as **`TaskSubRow`** (`label`, the control, `description` /
   `warning` / `error`), indented ONE step — the same step a nested `TaskList` takes, because
   belonging is expressed by indentation and there is only one device for it. Label and value sit
   ADJACENT so the eye pairs them. **The label column is the LIST's, not the row's** — one
@@ -855,7 +887,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   vocabulary with longer field names staggered nearly every row). The value takes the slack from
   a readable minimum — on a phone or in a narrow drawer it drops onto its own line under the
   label rather than ellipsizing beside it. Pass a form-variant `Inline*` editor (the default),
-  not `variant="cell"`: a cell variant belongs to a grid.
+  `variant="bare"`: a dense grid drops the resting frame.
 
   **A TASK'S FIELD ANNOTATES EXACTLY LIKE A RECORD'S FIELD.** `description` (persistent
   guidance), `warning` (a consequence to weigh — amber, announced) and `error` (field-level
@@ -1096,8 +1128,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `FileGrid`; the host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`,
   `selectTileRemove`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it
   scrolls and the bar pins, for a popover/drawer). **What you can DO to the files is composed
-  below it**, from `FilesEditorBar` + `FilesEditorUpload` · `FilesEditorSelect` ·
-  `FilesEditorSelectAll` · `FilesEditorDownload` · `FilesEditorRemove` (+
+  below it**, from `FilesEditorBar` + `FilesEditorUpload`, `FilesEditorSelect`,
+  `FilesEditorSelectAll`, `FilesEditorDownload`, `FilesEditorRemove` (+
   `FilesEditorBarSpacer` to push the rest right). Each renders nothing without the handler it
   needs, so withholding `onAdd`/`onRemove` IS the read-only shape — there is no `readOnly`
   mode. **A HOST verb is a plain `Button`** reading **`useFilesEditorSelection()`**
@@ -1124,8 +1156,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (`FileGrid` resolves them from `LoticsLocale.fileUpload` on your behalf).
 - **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
-  MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename
-  · media card; `isTemplate` overlays a TMPL marker. The tile's accessible name is the
+  MIME: image thumbnail, a doc tile with the `FileBadge` centered + a single-line filename
+ , media card; `isTemplate` overlays a TMPL marker. The tile's accessible name is the
   filename; pass `accessibilityLabel` to say what pressing it DOES instead. The per-surface
   pieces are exported for a hand-rolled layout: `DocumentBadge` (a bare pressable badge —
   its `size` is the square SLOT side, like every other tile here, and the badge is fitted to
@@ -1146,15 +1178,15 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the mark is TALLER than it is wide (26 × 32 by default), so a square slot takes the
   fitted width, not the slot side (that conversion is what `DocumentBadge` does).
 - **`file_preview`** — `FilePreview`: the universal inline preview — image/PDF/video/audio +
-  Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js ·
-  `@lotics/docx` · `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that
+  Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js,
+  `@lotics/docx`, `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that
   type is opened) and SHIP AS `@lotics/ui` deps — custom-code apps get PDF/Word/Excel
   preview with ZERO extra install. Renders to canvas/DOM, never a nested iframe — works in
   the sandboxed app iframe.
 - **`file_preview_types`** — `PreviewLabels` / `FilePreviewProps` / `GalleryLabels` — the
   shared label + prop contracts of the file-preview family; types only.
 - **`file_gallery_modal`** — `FileGalleryModal`: the FULL-SCREEN viewer — toolbar (filename
-  · counter · download, optional `onOpenExternal`/`onRemove` · close-✕), prev/next, ESC,
+ , counter, download, optional `onOpenExternal`/`onRemove`, close-✕), prev/next, ESC,
   rotate (the 90° controls FLOAT as a pill on the image); on a phone the actions collapse
   into a ⋯ `ActionMenu`. `onPersistRotation`/`persisting` wire a rotation save. Driven by
   `files` + `activeIndex` + `onIndexChange`.
@@ -1236,16 +1268,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   be rendered; where a compact meter used to decorate a ranked row or proposal card, rank /
   badges / severity carry the standing instead. Also: calibrated
   high/med/low; localized via the provider.
-- **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·
-  `ChangeReviewHeader` (auto kept-counter over decidable entries) · `ChangeReviewActions`
+- **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack,
+  `ChangeReviewHeader` (auto kept-counter over decidable entries), `ChangeReviewActions`
   (the commit bar in the DialogFooter/DrawerFooter: Keep-all bottom-left (`onAcceptAll` for
   host-held field state) + Apply gating); sections: `Change` (host-owned status, labeled
-  verbs, collapses to its `ChangeSummary` + Undo; no callbacks = display-only) ·
-  `ChangeLabel` · `ChangeSummary` · `ChangeReasoning` (the quiet why); grammar:
-  `ChangeFields` (the open record form) + `ChangeField` (THE field: − band · value ·
-  candidates + type-another-value · reasoning · per-field Keep/Drop · collapse) ·
+  verbs, collapses to its `ChangeSummary` + Undo; no callbacks = display-only),
+  `ChangeLabel`, `ChangeSummary`, `ChangeReasoning` (the quiet why); grammar:
+  `ChangeFields` (the open record form) + `ChangeField` (THE field: − band, value,
+  candidates + type-another-value, reasoning, per-field Keep/Drop, collapse),
   `ChangeRecord` (THE item card: registers like a Change; tone wash + localized op word;
-  verb level follows the decision level) · `ChangeBand` (the raw ± band) ·
+  verb level follows the decision level), `ChangeBand` (the raw ± band),
   `ChangeValueInput` (the diff-at-rest editor); the `changeReview` locale slice.
 - **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
   (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
@@ -1280,17 +1312,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`sources`** — `Sources` + `SourceRef`/`SourceKind` (record | document | table | web |
   knowledge): provenance chips, per-kind glyphs.
 - **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one
-  ranked AI-check insight — severity word · title · detail · `Sources` · children slot; the
+  ranked AI-check insight — severity word, title, detail, `Sources`, children slot; the
   expected-vs-actual body with the emphasized delta; the `finding` locale slice.
 - **`result_header`** — `ResultHeader` (+ `ResultTone`): the save-direct RECEIPT's outcome
   strip, on the page grid — tone mark (`ok`/`attention`/`error`/`skipped`) inline on the
-  title row · outcome-first title · right-slot `action` (the open-record jump / a retry) ·
+  title row, outcome-first title, right-slot `action` (the open-record jump / a retry),
   ONE line under (the honest `Confidence`, or the failure reason). The receipt composes:
   header → the receipt lines (a `DetailTable` of spread `DetailRow`s — label left, value at
   the right edge) → a `Confidence` callout naming the exact values that failed their
   deterministic checks (or stating what passed). NOTHING in a
   receipt edits — the RECORD is the edit surface, one press away. SEVERAL records → an
-  attention-first register of `ListItem` rows (tone mark · title · figures · needs-checking
+  attention-first register of `ListItem` rows (tone mark, title, figures, needs-checking
   count) pressing straight through to the records. See ai_patterns §the one law.
 - **`comments_thread`** — `CommentList` + the
   `ThreadComment`/`ThreadMember`/`ThreadFile` types: the record comments thread.