@lotics/ui 22.2.0 → 23.0.0

package/docs/composition.md

@@ -44,8 +44,9 @@ restyle a heading level per-page.
   numbers) + optional `CardHeaderMeta` (a count/unit/period, xs muted tabular).
 - **Section title** — ONE construct: `Section` › `SectionHeading` › `SectionHeadingTitle`
   (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
-  at the column edge; `SectionHeadingMeta` and actions ride the heading row's right edge (the
-  title's `flex: 1` pushes them). The page column is a **`SectionStack`** — it owns the
+  at the column edge; `SectionHeadingMeta` and any VIEW control ride the heading row's right edge
+  (the title's `flex: 1` pushes them) — but a verb that CHANGES the content does not: see the
+  action-placement law below. The page column is a **`SectionStack`** — it owns the
   between-section law (a fixed 56px beat + a bare hairline separating one section from the NEXT;
   null/false children are skipped so a conditional section never leaves a stray hairline). The
   `Divider` NEVER goes directly under a heading — that orphans the title from its own content.
@@ -317,7 +318,7 @@ card): `<PressableRow onPress>` + `<PressDoor onPress accessibilityLabel="Open
 content on `zIndex: 1` (the door hit-tests above in-flow siblings, so the content must lift back
 over it). `PressableHighlight` is the wrong base for such a row — it IS a button and wraps its
 children, so any nested control lands inside it; it stays for surfaces whose content is
-non-interactive by construction. `TableRow` and `LinkedRecordBox` already compose `PressDoor`.
+non-interactive by construction. `TableRow` already composes `PressDoor`.
 
 Actions stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY
 exception is a DENSE tree/register where a persistent per-row action would clutter: reveal on
@@ -424,11 +425,10 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   `danger` (and its quieter `danger-secondary`) marks destructive — that's the whole axis. No
   "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
   (colored `Text`), not the buttons.
-- **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". Section-heading creates are
-  `secondary` (one primary per scope, reserved for the scope's main verb); a create promotes to
-  `primary` only where creating IS the surface's job — the register page's New, an empty state's
-  action. (The icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps
-  its glyph.)
+- **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". A create is `primary` and
+  sits BELOW the list it extends, never in the section heading — see the verb-placement law for
+  why, and for the one-verb-one-weight rule that keeps it primary in the `EmptyState` too. (The
+  icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps its glyph.)
 
 ## The action-gating law — disabled + the reason as a co-located Callout
 
@@ -456,57 +456,148 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
 - **The field-annotation vocabulary** — THREE tones, same names + meanings on `FormField` and
   `DetailRow`, always EXPLICIT (never a hidden ⓘ on rows): **`description`** (info, muted) = a
   content/domain fact or persistent guidance, under the VALUE on a horizontal row — the label
-  column has no room for prose; stacked mode wears the form order label · description · control;
+  column has no room for prose; stacked mode wears the form order label, description, control;
   **`warning`** (amber) = a consequence the user should weigh before acting, announced on
   appearance; **`error`** (danger + alert semantics) = an invalid state under the value (the
   `Inline*` editors already render their own transient save errors); cross-field / record-level
   STATE = a co-located `Callout`. Every tone is USEFUL AND TERSE — a short clause stating the
   fact or consequence, never widget mechanics, never a second sentence; `warning` marks a
   consequence, not decoration. Rows share ONE
-  alignment law: the row top-aligns and label · control · trailing each center within the
+  alignment law: the row top-aligns and label, control, trailing each center within the
   first control line — a tall value block never drags the label, and a LABEL too long for its
   column WRAPS (never clipped, never abbreviated to fit) with its first line still level with
   the value. A FLAT value row
   (`InlineStatic`, plain `Text`) sets **`DetailRow flat`**: the annotation tucks up by the
   control band's slack so the perceived gap under the text equals the gap under a chip —
   the band's invisible bottom half must never read as a hole above the description.
-- **A LINKED record never renders as field rows** — another record's data must not read as
-  fields on THIS one. Use **`LinkedRecordBox`** (`tpl_record`'s Customer/sibling are the worked
-  examples): a BORDERED box (glyph anchor · identity · facts stacked vertically) whose verbs
-  ride its `actions` slot in a hairline-fenced footer INSIDE the box — destructive LEFT in
-  danger, go-to RIGHT. One verb set across every box of a group (a party wall's five links all read "Gỡ", not a mix of
-  "Đổi"/"Gỡ"): with a clearable link, changing = remove → the empty-state picker re-prompts, so
-  the destructive verb covers both required anchors and optional adds.
-  **`onOpen` decides whether the box is a DOOR, and the kit makes the two exclusive.** Pass it
-  (with `doorLabel`) when the linked record HAS a detail surface: the whole box presses open, its
-  facts are TEXT, and editing that record happens on ITS page, never here. OMIT it when the record
-  has NO page of its own — the box renders static (no tab stop, no pointer, nothing announced as a
-  button), the explicit `actions` verbs are its only affordances, and a `facts` value may then be a
-  NODE holding the inline editor, since there is no destination a press could steal. Never wire a
-  door "so the box presses": it sends the reader somewhere they did not ask to go and duplicates
-  whatever change verb the footer already shows.
+- **A verb about a VALUE goes ON the value — an `InlineButton` in the field's `actions`.** Copy
+  this reference, call this number, open this record: the act names the value, so it travels
+  with what it acts on, and a reader never has to pair a control sitting at the page's right
+  edge with the field it belongs to. `DetailRow` has NO trailing slot, because a reserved
+  column is paid by every row for the benefit of one — it was declared on the TABLE, so a
+  single `Copy` made every value cell stop short of an edge nothing occupied. EVERY `Inline*`
+  editor takes `actions`, popover-backed ones included — a field exposes its outer box
+  separately from the control inside it, so a select's list and a date's calendar still open at
+  the field's own width. Anything that is not a verb — a status `Badge`, a unit — composes into
+  the value cell instead.
+  `actions` renders in BOTH view and edit mode, and it must be passed UNCONDITIONALLY —
+  `disabled` the verb when it has nothing to act on. A slot that appears once the value is
+  non-empty changes the field's width as the user types, which is the one thing an inline
+  editor promises never to do.
+- **What is about the WHOLE record is a PANEL, not a section.** A section takes a position in a
+  top-to-bottom reading order, which is a claim that it belongs at that point in the read. A
+  record's DISCUSSION does not: a note is written about anything on the page and is wanted while
+  you work anywhere on it, so parked at one position it is unreachable from every other — exactly
+  when it matters. Dock it in the page's right gutter (the one the outline rail's balance already
+  reserved), pinned, scrolling inside itself so a long thread never lengthens the record. Give it
+  no rail entry — it is not a place you navigate to. Narrow, it collapses onto the same bar the
+  sections use, on the RIGHT: sections are where you ARE, the discussion is what is being SAID,
+  and the two poles keep the sides they hold on a wide screen.
+- **A VARIABLE-LENGTH, ORDERED fact is a `Sequence`, not a row of fields.** Before reaching for
+  any layout lever, check the section is not carrying a MODELLING error: `Origin` /
+  `Transfer point` / `Destination` looks like three fields and is actually one route — it cannot
+  hold a second transfer, and three identical rows say nothing about which comes first. The same
+  goes for an approval chain, a set of legs, a list of signatories. Rendered as a `Sequence` it
+  gains the one thing the grid could never give it — visible ORDER — and stops competing with the
+  fields around it, because it is no longer pretending to be one.
+  Nothing about spacing or disclosure fixes a section holding the wrong SHAPE, and a section that
+  looks "unattended" is usually this rather than a density problem.
+- **A VERB GOES WHERE ITS EFFECT LANDS.** One law places every action on a record surface, and
+  it is the same one that decides `InlineButton` vs a trailing column:
+
+  | the act changes… | it lives… |
+  |---|---|
+  | a VALUE (copy it, open what it points at) | ON the value — `InlineButton` in the editor's `actions` |
+  | a ROW (remove it, move it) | ON the row — an `ActionMenu`, or the row's own controls |
+  | the LIST (one more of them) | BELOW the list, left-aligned, `primary` |
+  | the RECORD (issue, print, hand off) | its own action row at the section's END |
+  | the record's EXISTENCE | the `DangerZone`, last on the page |
+
+  The heading row is therefore identity + meta + view controls, and holds no content verb. An
+  **Add in the heading sits above the thing it extends**, at a different altitude from the rows
+  it affects, competing with the title for the one line that names the section — while the row it
+  creates appears at the BOTTOM, nowhere near the button that made it. Put it under the last row,
+  on the list's own left edge, and the button is where its result will be.
+  **An add is `primary`, in the `EmptyState` too.** It is the act its section offers, so it
+  carries that section's weight; a lone `secondary` button reads as though the real action were
+  somewhere else. The rule that matters is that ONE VERB KEEPS ONE WEIGHT — the same add must
+  not be primary on an empty list and secondary on a full one.
+  A record surface therefore carries several primaries, one per section, and that is correct:
+  "one primary per SCREEN" governs the page BAND, not a stack of independent sections each with
+  its own single act. The cost is real and worth knowing — the more sections offer an act, the
+  less any one of them stands out — so the answer to a loud page is FEWER SECTIONS WITH ACTS,
+  never a quieter button.
+- **A DENSE section is compacted by a SUMMARY above it, by ROW HEIGHT, and by grouping fields
+  that are ONE ENTITY — never by a two-column layout.** The evidence is unusually clear here, so
+  do not re-derive it: Baymard finds an overall two-column form layout "generally problematic and
+  never recommended" (empty columns pull attention in several directions; fields get skipped), and
+  NN/g measures single-column completion materially faster. What IS sanctioned is 2–3 inputs on
+  ONE line **when they logically belong to a single coherent entity** — their examples are
+  day/month/year, first/middle/last name, city/state/ZIP. A route (origin, via, destination) is
+  that; two unrelated short fields sharing a line to save height is not.
+  **But that exception belongs to the LABEL-ABOVE form grammar, not to a `DetailTable`.** Every
+  example of it (day/month/year, city/state/ZIP) sits in a form where each input already owns a
+  label on its own line. A `DetailRow` puts the label in a LEFT COLUMN, so a grouped row can only
+  name its parts by adding a sub-label line no other row has — which drops its controls off the
+  baseline every other row shares — and naming them with placeholders loses the names the moment
+  the row is filled. In a label-left grid, ONE FIELD PER ROW is not a failure to compact; it is
+  the only shape that keeps the column a reader scans. Both attempts are recorded here so nobody
+  re-runs them.
+  The other caveat: that research studies COMPLETION forms, where the failure mode is a skipped
+  required field, while a record page is read-mostly.
+  A SUMMARY belongs to the RECORD, not to a section. The highlights-panel precedent (a strip of
+  key facts above the detail) is a PAGE-level device, where what it summarises is a scroll or a
+  tab away; repeated per section it sits inches above the very rows it repeats, so it reads as
+  duplication and adds a third block of chrome — section title, description, strip — before any
+  data. Put the few facts someone would ask for by phone in the record's own header, once.
+  A read-only view behind an Edit button is the last resort: it compacts by DROPPING empty
+  fields — and an empty row is information, the difference between "this record has no vehicle"
+  and "this section has no vehicle field" — and it costs a MODE, against the law that the surface
+  IS the editor.
+- **A REFERENCE to another record is a FIELD, not a section and not a card.** The kit already
+  draws every other reference as a token — a person is a `MemberChip`, a file a `FileBadge`, a
+  select option an `OptionBadge` — and a record is no different. It renders as a VALUE wearing
+  the **inline editor's own resting surface** (the 40px band, the white bordered chip, the radius), so
+  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.
+  **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
+  state, the create dialog is a modal, the validity problem is the row's `warning`.
+  **Never render the other record's fields as rows on this one** either — the reference carries
+  IDENTITY; any fact THIS record actually uses (a tax id that gates invoicing) is this record's
+  own field or the row's annotation, and everything else belongs on the record you open. When
+  the referenced record has NO surface of its own, it has no identity to reference: its values
+  simply ARE this record's fields — put them in a `Subsection`, with no box around them.
   **The empty / attach state is a find-or-create `Combobox`, never a bare picker** (`tpl_record`'s
   Customer is the worked example): rows are `renderOptionContent`-rich, NOT a wall of bare names —
-  the premium shape is a **glyph tile (28·radius 7·zinc-100) · the name over a muted metadata line**
-  that carries the type + identifying fact as TEXT (`type · code · city`), joined by "·" and free to
-  wrap the row taller. A type/attribute is **NOT a status, so it is text, never a `Badge`** (see
-  Badge discipline below). The row should read like the `LinkedRecordBox` it becomes — reuse the same
-  kind-glyph. (The kit suppresses `renderOptionContent` on the `allowCustom` "Create …" row so it keeps its plain + look.)
+  the premium shape is a **glyph tile (28, radius 7, zinc-100) beside the name, over a muted metadata
+  line** that carries the type + identifying fact as TEXT (`type, code, city`) — COMMA-joined, never
+  a middot (see Microcopy), and free to wrap the row taller. A type/attribute is **NOT a status, so it is text, never a `Badge`** (see
+  Badge discipline below). (The kit suppresses `renderOptionContent` on the `allowCustom` "Create …" row so it keeps its plain + look.)
   Plus `allowCustom` + `customOptionPlacement:"top"` + `customOptionLabel={q => 'Create "…"'}`. In
   `onValueChange`, an existing pick attaches; the custom row opens a create **`Dialog` prefilled with
   the typed query** (mint the record + link it) — so a party absent from the registry is created
   WITHOUT leaving the record. `customOptionPlacement:"top"` keeps the create row visible while the
   keyboard highlight stays on the first MATCH, so Enter on a partial never makes a duplicate. A
-  linked record seeded by a workflow (not user-attached) skips the picker — show the box or an
-  `EmptyState`, no create affordance. The component OWNS the door variant's press ANATOMY (the
-  error-prone part hand-rolling got wrong): the box is a `PressableRow` (role-less, non-focusable surface — hover wash spans
-  the nested verbs) with the keyboard DOOR — an EMPTY absolutely-positioned `role="button"`
-  sibling carrying the tab stop, the accessible name and the focus ring — beneath the content,
-  the interior verbs lifted above it via `zIndex: 1`. NEVER `role="button"` on a container with
-  interactive descendants: a button must not contain a button (invalid HTML, a hydration error,
-  and AT double-announcement). That fenced, lifted footer is the ONLY place a control may sit
-  inside a door box — a control in the facts column would compete with the press for the same
-  click, which is why a node fact typechecks only on the doorless variant.
+  linked record seeded by a workflow (not user-attached) skips the picker — show the chip or an
+  `EmptyState`, no create affordance.
+  **One verb set across every reference of a group** (a party wall's five links all read "Gỡ", not
+  a mix of "Đổi"/"Gỡ"): with a clearable link, changing = remove → the empty-state picker
+  re-prompts, so the destructive verb covers both required anchors and optional adds.
 
 ## Color discipline — solid / tint / ramp + ONE accent
 
@@ -652,7 +743,7 @@ that praises it is marketing.
 
 ### Error messages — what happened → what it means → what to do
 
-The consensus anatomy (GOV.UK · NN/g · Microsoft): state what happened, what it means for the
+The consensus anatomy (GOV.UK, NN/g, Microsoft): state what happened, what it means for the
 user's data, and the one next step. Field errors go INLINE (`FormField error=`); a page-level
 failure is a `Callout tone="error"` (title = what happened, text = what to do, an action when
 one exists).
@@ -663,7 +754,8 @@ one exists).
 - Empty required field → instruct ("Enter the hours you work a week"); constraint violation →
   describe the constraint ("First name must be 35 characters or less").
 - Apology is reserved for genuine system failure — never for validation.
-- BAD: `Error: invalid input (0x643).` · GOOD: `Không tải được chứng từ lên — tệp vẫn còn trên
+- BAD: `Error: invalid input (0x643).`
+  GOOD: `Không tải được chứng từ lên — tệp vẫn còn trên
   máy bạn. Thử lại; nếu vẫn lỗi, kiểm tra kết nối mạng.`
 
 ### Empty states — confirm, orient, one action

package/docs/data_entry.md

@@ -13,14 +13,14 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 | You're capturing… | Reach for | Why |
 |---|---|---|
 | an EXISTING record's fields | [**Inline edit**](#inline-edit--the-preferred-way-to-edit-an-existing-record) (`Inline*`) | edit in place, no form mode |
-| a value in a DENSE ROW / register `DataGrid` cell (a task's due · assignee · status) | the SAME `Inline*` editor in **`variant="cell"`** | transparent at rest + a background-tint wash on hover (not the form's chip + border), value-first (the date drops its calendar glyph) — one editor per value type, `variant` picks form vs grid; there is no separate `*Cell` family |
+| a value in a DENSE ROW / register `DataGrid` cell (a task's due, assignee, status) | the SAME `Inline*` editor in **`variant="bare"`** | one editor per value type; `bare` drops the resting frame (the grid already promises every cell edits) and fades the same border in on hover — there is no separate `*Cell` family |
 | a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
 | a RELATED record (pick or make) | [**find-or-create**](#find-or-create--the-combobox-family-is-the-control) (`Combobox allowCustom`) | one control covers both |
 | REPEATING rows you build & revise | [**line items**](#line-items--create--preview--edit-a-composition-not-a-primitive) (create→preview→edit) | add / edit / remove, live totals |
 | CHARGES that bill onto documents | [**billing**](#billing--the-invoice-document-is-the-unit) (`tpl_record` Billing section) | the invoice document is the unit |
 | a record's FEE/charge SUMMARY | [**`Ledger`**](#fee-summary--ledger) (worked example: `tpl_item_list` drawer) | grouped money lines, one emphasized total — no bars/charts |
 | a multi-value TAG field | [**`Select multi`**](#tag--multi-value-field--select-multi) (`renderSelected` → `Chip`) | chips composed, not a separate control |
-| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker` — a stacked column of full-width choices, right when options carry descriptions) | required single-select, one tap, every option visible |
+| ONE choice from a small visible set | [**`ChipGroup` pills**](#choosing-a-choice-control--by-option-count-not-by-taste) — more options or long labels take `InlineSelect`; `RadioPicker` only where the choice IS the task | one tap, every option visible, and the row stays ONE band |
 | ONE pick from a BIG registry (ports, projects…) | on a RECORD surface: **`InlineSelect searchable`** (search lives in the popover); on a form/attach surface: **`Combobox`** with `value` | an inline row stays an inline editor — a persistent search input breaks the surface's grammar |
 | a YES/NO on a record | **`CheckboxInput`** as the `DetailRow` value | a boolean needs no editor mode |
 | a STATUS with terminal outcomes | [**disposition**](#disposition--lifecycle-status-is-asymmetric-by-phase) (open → resolve → revise) | guides the decision |
@@ -154,13 +154,12 @@ null). `InlineSelect multi` needs no `onClear` — an empty set is already a val
 
 ### The row stack — `DetailTable` + `DetailRow`
 
-A STACK of rows lives in a `DetailTable` (label · value · trailing laid out like a TABLE:
-`labelWidth` / `trailingWidth` / `minHeight` set ONCE on the parent, plus the 8px row gap the
-zinc-50 chips need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a trailing
-action/badge, so EVERY row reserves the column and one row's `Copy` button never makes its editor
-narrower than its neighbours'. Rows share ONE alignment law: the row top-aligns and label ·
-control · trailing each center within the first control line — annotations (the three tones
-under the value: `description` muted · `warning` amber · `error` danger, each indented to the
+A STACK of rows lives in a `DetailTable` (label, value laid out like a TABLE: `labelWidth` /
+`minHeight` set ONCE on the parent, plus the `SPACE.md` row gap bordered fields need — a border
+is a harder edge than the old tint, so rows 8px apart fused) holding `DetailRow`s. There are TWO columns and no third: the value FILLS whatever the label leaves, so
+nothing one row does can narrow its neighbours' editors. Rows share ONE alignment law: the row
+top-aligns and label, control each center within the first control line — annotations (the three tones
+under the value: `description` muted, `warning` amber, `error` danger, each indented to the
 chip's 8px text inset) grow the row downward without dragging the label. The full annotation
 vocabulary lives in composition.md §Field annotations. A long LABEL wraps inside its column
 instead of clipping — never shorten a field name to fit the label width, and never reach for a
@@ -168,23 +167,60 @@ tooltip to recover the tail; the wrapped label's first line stays level with the
 
 ### The editability affordance
 
-A `variant="form"` editor (the default) AT REST sits on a zinc-50 chip — THE editability affordance:
-users see what's editable without hovering, and it hovers via a BORDER (an input's edge). Keep it
-wherever editable and static values MIX (a `DetailTable` / record field). `variant="cell"` opts out
-of the chip — transparent at rest + a background-tint WASH on hover — for DENSE, uniformly-editable
-surfaces (a register/`DataGrid` column, a task row where EVERY cell edits: the chip repeated
-everywhere is noise, and the wash matches the row/cell it sits in). A `disabled` editor rests FLAT
-automatically — the chip is the editability promise, and an inert field must not make it.
+An editor AT REST wears THE pill surface — WHITE with a 1px border, the same one `Chip`,
+`ChipGroup` and a secondary `Button` wear. That is THE editability affordance: a read-only
+`InlineStatic` stays flat and borderless, so users see what is editable without hovering, and a
+bordered box beside bare text is a plainer signal than a tint. Hover marks the field you are about to act
+on with a CHANGE you can see, which is why it differs by variant: a `framed` field deepens its
+border AND tints (border alone would be zinc-200 → zinc-400, a shade shift on a 1px line), while a
+`bare` field has the border ARRIVE out of nothing, which is loud enough by itself — and a tint
+there would make a hovered cell lighter than the row washing under it. Open adds the 2px ring. A `disabled` editor rests FLAT and borderless
+automatically — the surface is the editability promise, and an inert field must not make it.
+
+**`variant` decides how much of that frame shows AT REST — an axis of WEIGHT, not of use.**
+`"framed"` (default) keeps the surface visible: required wherever editable and static values MIX,
+because the frame is the only thing saying which values you can change. `"bare"` shows nothing at
+rest and fades the SAME border in on hover — for a surface where EVERY value is editable (a
+register/`DataGrid` column, a task row), where a per-field frame states what the whole surface
+already promises and, repeated down a column, draws the grid a second time. Both hover and open
+identically, so this changes what a field looks like RESTING, never what it does. A hand-rolled
+pressable cell should match `bare`: nothing at rest, the border on hover — never a background wash.
 
 A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
 **`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent
 border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
 glance and the static value never reads as a disabled input.
 
-To hang a right-side action/badge off a row, use `DetailRow`'s `trailing` slot (NOT for units —
-"kg"/"$" belong IN the value via `InlineNumberInput format`) — see the "General" section of
-`tpl_record`, which also reads top→bottom as a full record surface. Not every field is a
-same-height swap — a tag field, a status, or an attachment grid edit in place too (below).
+### Choosing a CHOICE control — by option count, not by taste
+
+A field whose value is one-of-N has three answers, and the wrong one is what makes a record
+surface look cluttered — not the number of rows. A row that is four rows TALL shouts over every
+neighbour, and variation in row WEIGHT reads as noise long before row COUNT does.
+
+| The choice | Reach for | Why |
+|---|---|---|
+| 2–3 SHORT labels, switched often | **`ChipGroup`** | every option visible, ONE press to switch; the pills size to their words and wrap, so the row stays one band |
+| More options, or long labels, or the value is set once and read after | **`InlineSelect`** | scales to any count; costs two presses (open, pick) and hides the alternatives until you do — put each option's gloss in `renderOptionContent`, where it is needed while CHOOSING rather than on every later read |
+| The choice IS the task — a wizard step, a short focused form | **`RadioPicker`** | full-width choices with their descriptions permanently visible. In a grid of many fields this is ~4 rows of height for one value; never use it as a row in a record's field table |
+
+**`SegmentedControl` is NOT a field control.** It belongs to the view-control vocabulary (a mode
+or parameter of the SAME view — see the composition grammar), and it fails as a value editor for
+two concrete reasons: it is a bounded TRACK, so in a value column that fills the row it either
+stretches absurdly wide for two options or needs a hand-picked width; and its track+thumb is a
+different visual species from the chip surface every other editor on the page wears. A `ChipGroup`
+is the same `chipSurfaceStyle` as the controls around it, sizes to its content, and grows by
+wrapping instead of squeezing.
+
+A VERB about the value rides the FIELD — an **`InlineButton`** in an editor's `actions` (`Copy`
+on a reference, `Call` on a phone): the act names the value, so it travels with what it acts on
+instead of being paired back to a control at the page's right edge. Pass it UNCONDITIONALLY and
+`disabled` it when there is nothing to act on — a verb that appears once the value is non-empty
+resizes the field as the user types, which is the one thing an inline editor promises never to
+do. Anything that is not a verb — a status `Badge`, a unit ("kg"/"$", which belong IN the value
+via `InlineNumberInput format`) — composes into a row inside the VALUE cell, so it costs only the
+row that wants it. See the "General" section of `tpl_record`, which also reads top→bottom as a
+full record surface. Not every field is a same-height swap — a tag field, a status, or an
+attachment grid edit in place too (below).
 
 ## Fieldset form — fields lay out on a RESPONSIVE two-column grid
 
@@ -280,7 +316,7 @@ changing desks — never an inbox, a notification, or a copied task. Two types:
 handoff is MANAGED AS TASKS — each desk's checklist on the record. The **`Task`** compound owns
 the list geometry (the control column, the indent, and `density` — 44px targets by default) —
 compose it, never hand-roll the row. A **`TaskItem`** carries a `TaskStatus` (a `CheckCircle` — a
-read-only ring when it has no `onChange`), a `TaskTitle` (a `variant="cell"` `InlineTextInput`,
+read-only ring when it has no `onChange`), a `TaskTitle` (an `InlineTextInput`,
 or the title TEXT as a string child — `<TaskTitle struck={done}>{label}</TaskTitle>` is the
 read-only form, and the compound owns its inset and band, so never hand-roll a `Text` title) and
 a `TaskActions` ⋯ menu — never a decorative progress strip. The fields the desk SETS (the
@@ -303,7 +339,7 @@ about one FIELD is not a caption either: it is that sub-row's own `description`
 
 **THE ROW CARRIES THE TITLE; THE FIELDS THE USER CAN SET ARE SUB-ROWS BENEATH IT.** A field
 belonging to ONE task — its due date, its assignee, a portal login, a reference number — hangs
-under it as a **`TaskSubRow`** (`label` · the control · `description` / `warning` / `error`),
+under it as a **`TaskSubRow`** (`label`, the control, `description` / `warning` / `error`),
 indented ONE step, with the NAME beside its VALUE so the eye pairs them. Belonging is expressed by
 that indentation, which is the same step a nested `TaskList` takes — one device, at every depth.
 
@@ -315,7 +351,7 @@ own words is not a column: it lined up the labels of a task whose names happened
 staggered every other one, and a vocabulary with longer field names than English staggered nearly
 all of them. Raise it once, on the list, for a vocabulary that genuinely needs more. The value
 takes the slack from a readable minimum, dropping onto its own line under the label on a surface
-too narrow to seat both. Use the form-variant `Inline*` editor (the default) — `variant="cell"`
+too narrow to seat both. Use the `Inline*` editor —
 belongs to a grid.
 
 **A TASK'S FIELD ANNOTATES EXACTLY LIKE A RECORD'S FIELD.** `TaskSubRow` carries the same
@@ -390,8 +426,8 @@ open tasks carry over. The handoff CTA opens a DIALOG for the receiving desk (as
 the record left this register.
 
 Tasks PEEK from the register: the done/total column is a pressable compact-`ProgressBar` trigger
-whose popover holds the same `Task` list — every `TaskItem`'s ring `TaskStatus` · struck
-`InlineTextInput` `TaskTitle` (flex) · a quick-reassign `InlineMemberSelect` in a `TaskSubRow`
+whose popover holds the same `Task` list — every `TaskItem`'s ring `TaskStatus`, struck
+`InlineTextInput` `TaskTitle` (flex), a quick-reassign `InlineMemberSelect` in a `TaskSubRow`
 under it — no expandable rows (tags/files depth is
 the Task list template's lesson, not the peek's); the popover body is `PopoverContent`'s own
 ScrollView (`disableBodyScroll` is ONLY for children that manage their own scroll, like
@@ -431,7 +467,7 @@ create step, never a toggle on the record.
 When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
 split the screen into "enter fees here, issue there" — that smears one job across two places.
 Make **each invoice a FLAT hairline-set band that holds its own editable charge lines** (amount
-input + payment method), its **live total**, its **status badge** (nothing-to-bill · draft ·
+input + payment method), its **live total**, its **status badge** (nothing-to-bill, draft,
 issued + ref), and its **issue action** in its closing row — no card chrome; data-capture
 templates are flat (see [the composition grammar](./composition.md)). A charge never lives apart
 from the document it bills on. Issuing is gated **inline, never a dead end**: when a prerequisite
@@ -446,7 +482,7 @@ receipt — never folded into the total due. Composition over `Card` + `NumberIn
 ## Fee summary — `Ledger`
 
 For a record's fee/charge SUMMARY (read-heavy, one payment action), reach for the `Ledger`
-compound: **`LedgerGroup`** (label + group sum) → **`LedgerRow`** (label · `meta` · ONE right
+compound: **`LedgerGroup`** (label + group sum) → **`LedgerRow`** (label, `meta`, ONE right
 tabular money column; `peek` makes the row a door to its PARTICULARS in an anchored popover —
 references live INSIDE the peek, since a row is never a button holding another button (`reference`
 is ignored while `peek` is set); `reference` = a trailing link on a non-peek row — an issued
@@ -597,8 +633,8 @@ more" affordance — only the empty state leads with it).
 
 `FileGrid` is the upload-aware grid: `files` are the saved/completed `DisplayFile`s, `uploads` is
 the LIVE add-queue (`FileUpload[]`) — it interleaves both and renders each in-flight tile itself —
-a LABELED status overlay (uploading spinner · "Retrying" · "Paused" · "Upload failed" + a retry
-button · "Can't upload" for a dead/empty file) — so you never hand-map an upload to a
+a LABELED status overlay (uploading spinner, "Retrying", "Paused", "Upload failed" + a retry
+button, "Can't upload" for a dead/empty file) — so you never hand-map an upload to a
 `FileThumbnail`. Those words resolve **prop → `LoticsLocale.fileUpload` → nothing** — set the
 pack once at the root and a stalled or dead upload speaks the app's language everywhere,
 including inside `FilesEditor`, which has no per-instance way to reach them. `labels.upload` /
@@ -606,7 +642,7 @@ including inside `FilesEditor`, which has no per-instance way to reach them. `la
 
 Make it CRUDable by wiring its callbacks: `onFilePress` → set a `number|null` index that drives
 `<FileGalleryModal files activeIndex onIndexChange>` — a FULL-SCREEN viewer with a toolbar
-(filename · counter · actions — download, optional `onOpenExternal`/`onRemove` · close-✕),
+(filename, counter, actions — download, optional `onOpenExternal`/`onRemove`, close-✕),
 prev/next, ESC, and rotate. The toolbar is RESPONSIVE: on a phone (`useScreenSize().small`) the
 actions collapse into a `⋯` `ActionMenu` so the close-✕ never overflows off-screen (its popover
 portals inside the modal's own `PortalHost` — a raw `<Modal>` lacks one, which is why an inline
@@ -631,7 +667,7 @@ gallery at the first hidden file). This is the responsive overflow pattern (avat
 file-manager); prefer it over a hardcoded `maxVisible`, which can't adapt to width.
 
 Under the hood it composes `FileThumbnail` (the completed tile — right surface per MIME: image
-thumbnail · a doc tile with the `FileBadge` centered + a single-line filename · media card; also
+thumbnail, a doc tile with the `FileBadge` centered + a single-line filename, media card; also
 takes `isTemplate` to overlay a TMPL marker) and `UploadingThumbnail` (the in-flight tile); reach
 for either directly only when hand-rolling a NON-grid layout. **When the filename must be
 readable, use `FileRow`** — a horizontal LINE (`FileBadge` or a `placeholder` + the FULL name + a