@lotics/ui 45.10.0 → 45.10.1

package/docs/data_entry.md

@@ -34,9 +34,7 @@ text box — and on a record surface radio/checkbox render as PERSISTENT control
 is the best display of the value; prose-shaped values and registry picks stay inline
 editors). **A MARKDOWN-typed field takes `InlineMarkdown`**, never `InlineTextInput`: the
 plain input prints the syntax it stores, so a reader sees `**` where every other surface
-showing that value renders it. It hides in the gap between two states of one field — the
-value is formatted wherever it is read-only and raw only where it is EDITABLE, which is one
-row, and looks like a quirk of that row rather than the wrong control. Rich `InlineSelect` options carry a description line (`renderOptionContent` — it
+showing that value renders it. Rich `InlineSelect` options carry a description line (`renderOptionContent` — it
 shows in the resting row too; the `data` generic types option payloads). A DEPENDENT field
 renders only while its parent value makes it real — never a disabled ghost row. Worked rows:
 `tpl_record`'s Classification group.
@@ -57,28 +55,25 @@ definitionally the second** — its Save/Create is the commit — so build it fr
 `FormTextInput` with controlled `value` + `onChangeText`, even when the record surface behind it
 is a grid of inline editors.
 
-This is **not** a safety rule, and it does not soften the press-gate law below ("Commit-on-blur
-would race the press that caused it"): inline editors in a dialog lose nothing, because `Button`
-already holds its press until the blur's commit settles. The gate makes the press SAFE. What it cannot do is make the dialog HONEST
-while the field still has focus — it only acts at press time, and everything **derived** from the
-draft trails the typing until then: a validity `error`, a Save gated on that validity, a computed
-total. Type a valid value and the form still says invalid, and its Save still sits disabled, until
-focus leaves. That is the dialog arguing with the box the reader is looking at, and no amount of
-press-gating answers it, because the reader is not pressing anything yet.
+Inline editors in a dialog lose nothing, because `Button`
+already holds its press until the blur's commit settles. The gate makes the press SAFE. What it
+cannot do is make the dialog HONEST while the field still has focus — everything **derived** from
+the draft trails the typing until then: a validity `error`, a Save gated on that validity, a
+computed total. Type a valid value and the form still says invalid, and its Save still sits
+disabled, until focus leaves.
 
-Controlled inputs make derived state track what is on screen, and read shorter than the editors
-they replace — four `DetailRow` + `Inline*` pairs whose `onSave` exists only to `setState` collapse
-to four fields. Worked example: `tpl_record`'s New-customer dialog.
+Controlled inputs make derived state track what is on screen. Worked example: `tpl_record`'s
+New-customer dialog.
 
 **The discriminator, since the kit's own `tpl_item_list` fills preview cards with `Inline*`
 editors:** what decides is whether anything on the surface READS the draft before the commit. A
 dialog whose Save is gated on the values being typed, or whose visible totals derive from them,
 takes controlled `FormField`s — that is this rule. A REVIEW surface whose gate is decided by
-something else (which cards are kept, which candidate is picked) may keep inline editors, because
-nothing is arguing with the box under the cursor. Neither shape is a create form's stand-in.
+something else (which cards are kept, which candidate is picked) may keep inline editors. Neither
+shape is a create form's stand-in.
 
-**But do not then derive the ERROR per keystroke** — the mistake controlled inputs invite, and the
-opposite failure to the one above. Validity and the error MESSAGE are different questions. Validity
+**But do not then derive the ERROR per keystroke** — the mistake controlled inputs invite.
+Validity and the error MESSAGE are different questions. Validity
 gates the commit and is checked continuously; the message claims the reader did something wrong, so
 it may only be made once they are DONE. Every prefix of a correct fixed-length value is invalid, so
 a per-keystroke message turns the first digit of a right answer into a red complaint. Gate the
@@ -88,28 +83,28 @@ already has: errors arrive from a validate pass, and editing a field clears that
 
 ## A picker over a select FIELD keeps the field's colours — `optionPicker`
 
-    <InlineSelect {...optionPicker(fields.status?.options ?? [])}
+    <InlineSelect {...optionPicker(fields.city?.options ?? [])}                    // a category
+                  value={cityKey} onSave={(v) => save({ city: v })} />
+    <InlineSelect {...optionPicker(fields.status?.options ?? [], { badge: "dot" })} // a status
                   value={statusKey} onSave={(v) => save({ status: v })} />
 
-Spread it into `InlineSelect`, `Select`, `OptionList` or `Combobox` — it supplies both the
-`options` and the `renderOptionContent` that paints each one.
+Spread it into `InlineSelect`, `Select`, `OptionList` or `Combobox` — it supplies the `options`
+(each carrying the field's own option as `data`) and, when you ask for a badge, the
+`renderOptionContent` that paints each one.
 
 **The obvious call site throws the colour away, silently.** A picker takes `{ value, label }`, so
 every app writes `options.map((o) => ({ value: o.key, label: o.label }))` — and `color` is not in
 that shape, so it never arrives. Nothing errors and nothing looks broken; the value simply renders
 as a coloured chip in the register and as bare grey text the moment someone goes to CHANGE it,
-which is backwards. Recognition matters most in the list you are choosing from, and a filter
-popover of identical grey rows makes the reader match text where they could have matched a colour.
-It is worth grepping for: the mapping is boilerplate, it looks correct, and one CRM had thirteen
-of them.
+which is backwards. It is worth grepping for: the mapping is boilerplate and it looks correct.
 
-The mapping and the renderer ship together deliberately. Returning only the options would leave
-each caller to write the `renderOptionContent` that reads `data`, and an app that mapped correctly
-but forgot the renderer lands back on grey text with nothing to indicate why.
-
-Default `dot`: a picker row is a place to READ a set of choices, and a stack of filled pills is
-heavier than the list describing them. Pass `{ variant: "tonal" }` where the selected value is the
-surface's one prominent status.
+**The badge is OPT-IN — `{ badge: "tonal" | "dot" }` — and that is the design.** Omit it and
+`renderOptionContent` comes back `undefined`, so the picker falls back to its own label rendering
+and the options read as plain text: correct for a type, a category or an attribute (an industry, a
+source, a department, a city), where badging every value spends the vocabulary that made a coloured
+pill mean something. A field carrying a `color` is not consent to paint it. Pass it where the value
+is a STATUS — `dot` by default, `{ badge: "tonal" }` where the selected value is the surface's one
+prominent status.
 
 ## Inline edit — the preferred way to edit an existing record
 
@@ -129,44 +124,38 @@ resting value is the RAW string (`InlineTextInput`) is ONE `<input>` in both sta
 swaps elements, and `editing` is a style state driven by focus. Two elements cannot be made to
 draw the same string identically: matching the padding, the border and the ink still leaves an
 `<input>` centring by FONT METRICS where a `<div>` positions by LINE BOX, a quarter-CSS-pixel
-residual that no property closes, is invisible to `getBoundingClientRect` (it reports the rounded
-box), and lands on a real device pixel at fractional scaling. Where the resting display is
+residual that no property closes, that is invisible to `getBoundingClientRect` (it reports the
+rounded box, and both paths compute the same text top), and that still lands on a real device
+pixel. Where the resting display is
 FORMATTED and the editor shows something else (`1,250 kg` → `1250`, `31/07/2026` → a segmented
 field), the string changes anyway, so those editors do swap and should. **The rule for a new
 editor: same string in both states ⇒ one element; different string ⇒ swap.**
 
 Two worked cases sit on either side of it, and they look alike until you apply the rule.
-**`InlineMarkdown` does NOT swap, and the reason it tried to is the lesson.** Its editor is the
+**`InlineMarkdown` does NOT swap.** Its editor is the
 WYSIWYG `MarkdownEditor`, so both states show rendered prose — the rule's first limb, one element.
-It was nonetheless built as a swap on a COST argument (a ProseMirror view per field is not free the
-way an `<input>` is), and every defect that followed came from that one decision: the box changed
-height on open, a toolbar rolled in and pushed the form down, and the resting state was a `Pressable`
-— so it wore the pointer cursor and `userSelect: none` denied a reader the ability to select a
-sentence out of their own note.
-
-None of those are fixable while two elements draw one value; a measured height floor only papers
-over the first. **When "the layout must not move" is a requirement rather than a preference, one
+A ProseMirror view per field is not free the way an `<input>` is.
+
+**When "the layout must not move" is a requirement rather than a preference, one
 element is the only thing that delivers it** — a swap can be made to look stable, never to be it. So
 the editor is mounted at rest and gains a draft on focus, and the per-field cost is paid on purpose.
 If a screen ever holds dozens of these, the answer is fewer markdown fields on it, not a swap.
 
 **`variant` has to reach whatever actually DRAWS the box.** `InlineEditFrame` paints no surface on
 the path this field takes — it has no `actions` — so the editor's own frame is the field's frame,
-and a `variant` that stops at the wrapper stops at nothing: `bare` bought no change at all, and
-every markdown field wore the document sheet whatever the caller asked for. So `MarkdownEditor`
+and a `variant` that stops at the wrapper stops at nothing. So `MarkdownEditor`
 takes the same `"framed" | "bare"` axis as `TextInputField`, and `InlineMarkdown` passes it through.
 
 **The half that is easy to miss is the INSET, not the border.** A document sheet insets its prose
 further than a control does (13px against `CONTROL_TEXT_INSET`'s 9), so an editor serving as a
 field lands 4px right of the plain-text field stacked directly above it — a ragged left edge inside
-one card, with nothing on screen naming the cause. A field variant is therefore what makes the
+one card. A field variant is therefore what makes the
 editor a FIELD: it takes the control's corner (`CONTROL_RADIUS`) and the control's inset with it.
 The third value, `"document"`, is the default and every standalone surface in the product — and it
 is a NAMED value rather than an absence, because an optional prop whose omission is a distinct
 third mode reads backwards to anyone who knows `TextInputField.variant`, where omitting it gives
-you `"framed"`. `seamless` is the different case and not this one: that surrenders the surface to a
-host that draws it, and here there is no host — `InlineEditFrame` paints one only when it also owns
-the verbs, so with none the CHILD owns the surface.
+you `"framed"`. `seamless` is the different case: that surrenders the surface to a
+host that draws it, and here there is no host.
 **A LINK does not swap**: marking a URL changes its ink, not its characters, so `InlineTextInput`
 takes a **`link`** treatment on its single `<input>` rather than swapping in a `TextLink`. Pressing
 the field still edits — an `Open` `InlineButton` in `actions` is how you reach the destination,
@@ -203,14 +192,14 @@ Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a
 SWAP editor — `InlineNumberInput`, `InlineDatePicker` — opens edit mode
 immediately with the input focused; commit-on-blur then makes Tab itself the commit, so the chain
 is type → Tab → type with the next editor already open. Pointer focus never auto-opens (mousedown
-records "pointer" modality before focus fires — `interaction_modality.ts`), so the click path is
-exactly what it always was. `InlineTextInput` needs none of this — its input is always mounted, so
+records "pointer" modality before focus fires — `interaction_modality.ts`). `InlineTextInput`
+needs none of this — its input is always mounted, so
 focus IS the edit by either route. When a **keyboard** close (Enter/Escape) leaves focus on
 `<body>`, a swap editor returns focus to its resting view so the next Tab continues from the
 field (the always-mounted one never loses focus, so there is nothing to restore). A **pointer**
-close (click ✓/✕, or click away onto non-focusable space) does NOT restore — a mouse user has no
-next Tab to preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
-restore is gated on modality via `shouldRestoreFocusOnClose`).
+close (click ✓/✕, or click away onto non-focusable space) does NOT restore — a bare `.focus()`
+would scroll the target into view, jerking the page (the restore is gated on modality via
+`shouldRestoreFocusOnClose`).
 
 **Typed dates.** `InlineDatePicker`'s keyboard mode is an internal segmented date field
 (`DateField` — not exported; reached only through `InlineDatePicker`): type
@@ -218,8 +207,8 @@ the date in the locale's own field order — dd/MM/yyyy under the `vi` provider,
 under `en`, derived from the active `LoticsLocaleProvider` (an explicit `locale` prop still
 overrides) — digits auto-advance, and a typed separator (`/` `.` `-`) advances a single-digit
 day/month; Enter or blur commits, Escape reverts, Alt+ArrowDown floats the calendar. The
-calendar popover stays the pointer path (click the resting value, as ever) — it is no longer
-the only path. A PARTIAL entry never commits and never clears the stored value: the field
+calendar popover stays the pointer path (click the resting value). A PARTIAL entry never commits
+and never clears the stored value: the field
 stays in edit mode showing the `datePicker.invalidDate` inline error until fixed or Escaped.
 
 The POPOVER editors (`InlineSelect` / `InlineMemberSelect`) deliberately
@@ -236,9 +225,9 @@ One per type:
   default; `renderSelected` overrides) — a colored `OptionBadge`, not just a label.
   An option ROW may be taller than one line — a rich row (custom `renderOptionContent`, or a
   label over a `getOptionDescription` line) renders as `MenuListItem`, the listbox row that
-  GROWS with its content; only a plain label row is the fixed-height `MenuButton`. So a short
-  code + the full official name underneath is a supported option shape, not a hack. Reach for it
-  whenever the real name is too long to READ in a list but must stay exact somewhere.
+  GROWS with its content; only a plain label row is the fixed-height `MenuButton`. So a short code
+  with the full official name underneath is a supported option shape — reach for it whenever the
+  real name is too long to READ in a list but must stay exact somewhere.
   **The popover is the FIELD's width** (floored at `MIN_CONTROL_WIDTH` so a dense grid cell still
   opens something readable) — shared by `Select` and `Combobox`, every popover anchored to a
   field. So option text longer than the field WRAPS; it never widens the panel, and a paragraph-
@@ -295,19 +284,17 @@ something belongs elsewhere.
 
 It is wrong wherever the length is the AUTHOR's choice, and it fails in the worst available way.
 The box is drawn at the budget and the value simply exceeds it: no ellipsis, no clamp, no
-scrollbar, nothing to scroll — a truncation mark would have been kinder; this is silent. So the test is not "is this field long" but **"who decides the
+scrollbar, nothing to scroll. So the test is not "is this field long" but **"who decides the
 length"** — the field, or whoever is typing.
 
 **And it gets worse as the surface narrows**: a budget is a count of LINES and the wrap point
 moves, so the narrower column wraps the same value into more hidden lines. A fixed reserve
 verified on a wide screen is not verified.
 
-`autoGrow` makes the budget a minimum and fits the value. It costs nothing the fixed reserve was
-protecting, and the reason is worth stating because it is easy to assume otherwise: an
-`InlineTextInput` is ONE input in both states, never a resting view swapped for an editor, so a
-grown box is the same height focused as at rest. The reserve was guarding against a jump the
-one-element design had already made impossible. Growing on a control that DOES swap (number, date, time — their resting display is
-formatted) would reintroduce it, which is why the prop lives here and not on those.
+`autoGrow` makes the budget a minimum and fits the value. An `InlineTextInput` is ONE input in
+both states, so a grown box is the same height focused as at rest. Growing on a control that DOES
+swap (number, date, time — their resting display is formatted) would reintroduce the jump, which
+is why the prop lives here and not on those.
 
 Two places to keep the reserve anyway: a value that can be **arbitrarily long** (growth has no
 ceiling — 406 characters is already 238px, so a field that might hold a document wants the budget,
@@ -319,8 +306,8 @@ on a record surface; reserve in a table. Worked both ways in `dev/pages/inline_e
 ### The row stack — `DetailTable` + `DetailRow`
 
 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
+`minHeight` set ONCE on the parent, plus the `SPACE.md` row gap bordered fields need) 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
@@ -333,29 +320,26 @@ tooltip to recover the tail; the wrapped label's first line stays level with the
 
 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
+`InlineStatic` stays flat and borderless, so users see what is editable without hovering. Hover
+marks the field you are about to act on with a CHANGE you can see, and it is ONE signal in both
+variants: the border darkens to `HOVER_BORDER` (zinc-500) — a `framed` field deepens the border it
+already has, a `bare` field has that border ARRIVE out of nothing. **Nothing tints.** A hover wash
+on top would make inline fields the one control in the kit with a second hover language, and a
+reader crossing a record surface would meet both. 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
+register/`DataGrid` column, a task row). 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 `bare` field aligns its TEXT, not its box.** Because it looks like text at rest, it sits on the
 column like text: the frame's 8px inset is pulled back out with a negative LEFT margin, so the glyphs
 land on the container's edge. Without that, every bare value rendered 8px right of the header naming
-it. The bleed is one-sided on purpose — a matching right bleed aligns nothing on left-aligned text and
-only pushes the frame past the edge its neighbours stop at, which shows the moment the border paints.
-Two consequences for callers: a `bare` field needs ~8px of slack on its LEFT to hover into (in a
+it. The bleed is one-sided on purpose. Two consequences for callers: a `bare` field needs ~8px of slack on its LEFT to hover into (in a
 zero-gap column the borders of adjacent cells will touch), and it is the wrong variant for a surface
 where it must stay strictly inside its box — that is `framed`. A DISABLED `framed` field keeps the
 box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
@@ -364,16 +348,12 @@ fields beside it.
 **`bare` puts its whole affordance in the hover edge, so nothing may outrank that edge.** Pass the
 variant as a PROP; never express it as a resting `borderColor: "transparent"` in `style`, which is
 applied after the hover rule and erases the edge one line after it is computed. The failure is
-silent in every direction that usually catches things — the field keeps its role, its label, its
-focus ring, its metrics and its save — and what breaks is only that nobody presses it, because a
-control drawing nothing at rest and nothing on hover is text. The kit's own `TextInputField` had
-it, so a `bare` inline editor in a register column went un-pressed rather than mis-styled.
+silent — the field keeps its role, its label, its focus ring, its metrics and its save — and what
+breaks is only that nobody presses it, because a control drawing nothing at rest and nothing on
+hover is text.
 
 **The cursor is the other half of that promise, and it belongs to the CONTROL, not to the page.**
-An inline editor takes the pointer like every other control. It once forced the arrow back, on the
-reasoning that an editor is an input rather than a button — right that it is not a button, wrong
-about the replacement: the arrow is what inert prose gets, so the one value on the row that was
-the reader's to change was the one that looked least touchable. The I-beam is not the alternative
+An inline editor takes the pointer like every other control. The I-beam is not the alternative
 either; a resting editor sets `userSelect: "none"` so a drag edits rather than selects, and an
 I-beam would promise a caret that is not there. A field is disabled is the only case that reverts
 to the arrow, for the same reason it rests bare: an inert value must promise nothing.
@@ -385,8 +365,7 @@ glance and the static value never reads as a disabled input.
 
 **In a grid that MIXES the two, or one that ANNOTATES.** "Copies the editor box metrics" means it
 hard-sets `INLINE_CONTROL_HEIGHT` — worth paying to hold a column straight, waste where there is
-no column to hold. Two different things can make the column, and missing the second is what put
-three left edges on a review dialog:
+no column to hold. Two different things can make the column:
 
 - **An editor beside it.** The obvious case: a static value rendered raw beside a real editor
   starts at the cell edge, 20px tall, at the top, while the editor's text starts 9px in and
@@ -401,8 +380,7 @@ values genuinely are short.
 
 **A `description` / `warning` / `error` under it.** `FieldAnnotations` insets its stack by
   `CONTROL_TEXT_INSET` so it lines up with a CONTROL's words — so an annotated row whose value is
-  raw puts the value at the cell edge and its own description 9px inside it. Nothing else on the
-  screen is wrong, the drift is small enough to read as sloppiness rather than structure, and it
+  raw puts the value at the cell edge and its own description 9px inside it — and it
   appears only on the rows that happen to carry a description, so a column slides in and out of
   alignment down its own length.
 
@@ -424,8 +402,7 @@ exists to remove and pulls the description 4px too tight.
 ### 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.
+surface look cluttered — not the number of rows.
 
 | The choice | Reach for | Why |
 |---|---|---|
@@ -442,15 +419,13 @@ subject reached two ways (a password vs a mailed link — one account, one desti
 first earns a chooser. For the second, render the path most readers take and offer the other as a
 secondary action beside that form's submit, where it is visible without being in the way.
 
-The tell is that people press the chooser far more than once each — a real decision is made once
-and remembered, so repeat presses mean they are bouncing between doors rather than choosing. The
+The tell is that people press the chooser far more than once each. The
 measurement is in [reviewing.md](./reviewing.md) probe 8b.
 
 And when you do offer the alternative beside the submit, **give it its own treatment**: an
-alternative WAY IN and a recovery link ("forgot your password") are different roles, and a reader
-parses shape before meaning, so two identical full-width buttons read as two equal ways to proceed
-however different their consequences. One primary, one secondary, and anything remedial drops to a
-quiet text link.
+alternative WAY IN and a recovery link ("forgot your password") are different roles, and two
+identical full-width buttons read as two equal ways to proceed however different their
+consequences. One primary, one secondary, and anything remedial drops to a quiet text link.
 
 **"No selection" is the PLACEHOLDER, never an option whose value is the empty string.** A picker
 reads `""` as *nothing chosen* — it is what its own clear affordance emits back through
@@ -458,8 +433,7 @@ reads `""` as *nothing chosen* — it is what its own clear affordance emits bac
 ABSENT value (`value={x ?? undefined}` + `placeholder`), and map an incoming `""` back to that
 absence at the call site. An `{ value: "", label: "All types" }` option instead leaves the control
 with no selection AND no placeholder, so the trigger renders down to its chevron — a filter that
-still works, sized at a few pixels, which reviews as a rendering glitch rather than a modelling
-error.
+still works, sized at a few pixels.
 
 **`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
@@ -492,24 +466,20 @@ attachment grid edit in place too (below).
 
 ## A value rendered TWICE is the bug — not the resident editor
 
-The section above is the default and holds everywhere. There is one thing that appears to
-contradict it, and the contradiction is worth naming because the wrong resolution is the
-tempting one: **a value that already appears elsewhere on the same surface.**
+The section above is the default and holds everywhere. One thing appears to
+contradict it: **a value that already appears elsewhere on the same surface.**
 
-A feed used to be the example. Its row LABEL was the gist, the body opened underneath, and a
-resident editor rendered the same sentence twice — stacked and identical, which reads as a
-mistake at any weight, so quieting the frame does not help. The fix looked like demoting the
-editor to a mode behind an **Edit** verb, and that is a workaround: it keeps the duplication and
-buys silence by hiding one copy behind a click. What it costs shows up immediately after —
+A resident editor rendering the same sentence twice — stacked and identical — reads as a
+mistake at any weight, so quieting the frame does not help. Demoting the
+editor to a mode behind an **Edit** verb is a workaround: it keeps the duplication and
+buys silence by hiding one copy behind a click, and
 the verb has to live somewhere (a button nested in the row's own button, or a footer a scroll
-away from the sentence it edits), and every repair from there is a repair to the arrangement,
-not to the surface.
+away from the sentence it edits).
 
 **Render it once, and the question dissolves.** Text inside a press target cannot be edited where
 it sits, so a value a person WROTE does not belong in a row's label: the label is for derived,
 read-only text ("Stage changed to Won"). Move the prose out and it is an ordinary resident field
-with no mode, no verb, and one copy — `tpl_record`'s activity feed is the worked example, and the
-byline above it carries the derived facts that used to fight it for the row.
+with no mode, no verb, and one copy — `tpl_record`'s activity feed is the worked example.
 
 So: if a resident editor would duplicate a value, **delete the duplicate**. Make the editor a mode
 only when the second appearance is genuinely load-bearing and cannot move.
@@ -522,9 +492,8 @@ Two things follow that are easy to get wrong in the other direction:
   verb, name it for the words rather than the row: "Edit", not "Edit entry", which claims the
   whole entry is yours to rewrite.
 - **An EMPTY value still shows its field, and shows it FRAMED.** A surface fed by automations
-  receives entries with no words in them routinely — a recording lands and nobody has written it
-  up — so withholding the field lets a feed RECEIVE an entry it gives the reader no way to
-  finish. Empty is also the state where `bare` fails: grey placeholder text on an invisible box
+  receives entries with no words in them routinely, so withholding the field lets a feed RECEIVE
+  an entry it gives the reader no way to finish. Empty is also the state where `bare` fails: grey placeholder text on an invisible box
   does not read as somewhere you can type. Follow the value — `variant={value ? "bare" : "framed"}`
   — so a written-up entry reads as prose and an empty one is recognisable as an input from across
   the page. A button that reveals a field is the wrong trade: `InlineTextInput` has no
@@ -555,8 +524,8 @@ personal detail: `ComboboxInput`, `SearchInput`, `ScanField`, `ColumnFilter`, an
 `OptionList` search. Nothing to pass.
 
 It deliberately does NOT do this on `FormTextInput`, the inline editors, or the comment composer.
-A contact form SHOULD autofill a name, an email and a phone number — suppressing it there is a real
-usability loss, and which fields those are is the app author's call, not the kit's. Pass
+A contact form SHOULD autofill a name, an email and a phone number, and which fields those are is
+the app author's call, not the kit's. Pass
 `autoComplete` yourself on a form field (`"name"`, `"tel"`, `"email"`, `"off"`); it forwards to the
 DOM input.
 
@@ -633,8 +602,7 @@ line asserts sequence, which is what a desk handoff IS. OFF for N items ticked i
 a line claims an order the work does not have. It is the same compound either way.
 
 **A GROUP is a name and nothing else.** No control: a phase owns no completion of its own, so a
-ring there reports without responding — and one identical to the pressable rings beneath it
-invites the press it refuses, which is worse than showing nothing. No BODY: a condition or an act
+ring there reports without responding. No BODY: a condition or an act
 hung off a heading leaves the reader working out which of the rows below it they were about. The
 row that OWES the work carries all of it — its wait (`meta`), its condition (`ChecklistNote`) and
 the act that leaves it (`ChecklistActions`).
@@ -643,15 +611,13 @@ the act that leaves it (`ChecklistActions`).
 on a dated ladder, today's date onto milestones that happened on days nobody recorded. Where the
 run is a SEQUENCE, derive position from the highest stamp instead — one click then marks
 everything below it, and a rung the record passed without a recorded day shows a BLANK date, which
-is the honest answer to "when" and stays one click from being filled. That is the whole of the
-bulk gesture, and it invents nothing.
+is the honest answer to "when" and stays one click from being filled.
 
 **A CHECKLIST REPORTS; IT DOES NOT COLLECT, AND IT DOES NOT PREVIEW.** A field some section owns —
 an assignee, an address, a tax ID — is NAMED as a gap by a **`ChecklistNote`** whose `action` jumps
-to that section. Never an editor in the row: two edit surfaces for one fact, and every row becomes
-two things at once (a status and a form) with nothing to say which one the reader is in. Never a
+to that section. Never an editor in the row: two edit surfaces for one fact. Never a
 rendered value either — an avatar or a badge is a COPY that has to be kept in step with the
-field's real home, and readers start treating the list as the place the value lives. Two
+field's real home. Two
 exceptions, both narrow: **`ChecklistItem.trailing`** for the row's OWN stamp (a tick writes today,
 so a run filled in after the fact needs the correction in reach), and **`ChecklistField`** for a
 value with NO other home — a portal login created at that step, unreachable otherwise.
@@ -662,9 +628,7 @@ is a `ChecklistNote`, because a sentence on the title's line wraps into the titl
 scanning. Neither takes a LABEL: a field is a named value the reader sets, and labelling prose
 makes it read as a field nobody can edit.
 
-**Anything that needs SCANNABLE COLUMNS is a `Table`.** The compound once carried a declared VALUE
-column so cells lined up down the list; it aligned, and it read worse — each name ended a quarter
-of the surface from its control, sized for the widest value on the page. Comparing the same four
+**Anything that needs SCANNABLE COLUMNS is a `Table`.** Comparing the same four
 values across twenty rows is a table's job.
 
 **State flows from the LEAVES.** Where a row's position is computable from what it owns, DERIVE it
@@ -683,10 +647,9 @@ same empty list, so a badge asserting the first states something no one establis
 at both ends, and separate "is it under way" (which drives the ring) from "has it anything to
 say" (which drives the caption) — fusing them forces every pending state to invent a label.
 
-`CheckCircle` has THREE positions (`state="none" | "partial" | "done"`), and `partial` is not
-optional dressing: a step whose vocabulary reads "No portal account → Account created → Filed
-online" is neither finished nor untouched in the middle, and a binary ring calls it untouched — in
-the gutter column, which is the fastest scan on the surface. Its CLICK stays binary (finish /
+`CheckCircle` has THREE positions (`state="none" | "partial" | "done"`): a step whose vocabulary
+reads "No portal account → Account created → Filed
+online" is neither finished nor untouched in the middle, and a binary ring calls it untouched, in the gutter column. Its CLICK stays binary (finish /
 reopen) so the ring means one thing everywhere; `partial` is reached through whatever NAMES it —
 an `InlineSelect` status cell in that step's own words, or children ticking off — never by cycling
 the ring. Keep the ring MONOCHROME and let colour live in the status cell, or the row double-codes
@@ -707,7 +670,7 @@ 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 `Checklist` — every `ChecklistItem`'s ring and title, and nothing a
 section already owns (a reassign belongs to the record, not to a peek over fifty rows) — no
-expandable rows (tags/files depth is the task board's lesson, not the peek's); the popover body is `PopoverContent`'s own
+expandable rows; the popover body is `PopoverContent`'s own
 ScrollView (`disableBodyScroll` is ONLY for children that manage their own scroll, like
 `OptionList`). The DRAWER carries a real Tasks SECTION in the Record template's shape (heading +
 the compact meter + the same checklist) — one shared task state per record feeds the column, the
@@ -783,7 +746,7 @@ create row. Borderless for a grid cell? Pass a `style`, never a `variant`.
 editors, so the tag field wears the same frame and hover as the row it sits in; reach for `Select`
 inside a form or dialog. The ✕ detaches its tag whether the list is open or shut and never opens
 the list. Two densities, one seam: a record field earns the removable `Chip`, a narrow register
-column keeps the plain badge, where the ✕ costs more width than the reopen it saves. `Combobox` is the
+column keeps the plain badge. `Combobox` is the
 SINGLE-value sibling — for a search that emits one pick at a time and renders the selection
 elsewhere, use `reflectSelection={false}` (see the [templates](./templates.md)).
 
@@ -815,14 +778,13 @@ sitting on the inline-control grid via `InlineSlot`.
 
 "Add another" is not an act a single-file field can perform, and offering it produces a field
 holding two of something the schema says there is one of. The component gets the affordance
-right; it cannot enforce the persistence, because it does not own the data — so the difference
-lives at the call site, `onAdd={([f]) => setFile(f)}` against
+right; it cannot enforce the persistence — so the difference lives at the call site, `onAdd={([f]) => setFile(f)}` against
 `onAdd={(fs) => setFiles([...files, ...fs])}`, where it is decided.
 
 **Nothing to attach TO yet is a real state.** Pass `blockedReason` and the CTA is replaced by a
 sentence naming the act that unblocks it ("attach the invoice number first"). Never a disabled
 button: disabled says you may not and leaves the reader to work out why and what would change
-it — same pixels, one of them useful.
+it.
 
 **A LIST, and not switchable.** Documents are identified by NAME; a PDF/Word/Excel thumbnail is
 a grey page identical to every other grey page, so a grid of them is a wall of one tile under a
@@ -866,10 +828,10 @@ intake paths, all wired to ONE handler:
 **What `accept` is matched against, and the one thing a paste cannot do.** A pattern is an
 extension (`.pdf`), a wildcard type (`image/*`) or an exact MIME. A file is matched on
 `resolveMimeType(file.type, file.name)` — its own declared type when that type says something,
-and what its EXTENSION says when it doesn't. That fallback is not a nicety: a file copied in
+and what its EXTENSION says when it doesn't. A file copied in
 Finder/Explorer and pasted arrives with real bytes and a real filename but an uninformative
-type — `""`, or just as often `application/octet-stream`, the same non-answer wearing the shape
-of one. Judging it on that reads silence as "not a PDF", the file is discarded, and since an
+type — `""`, or just as often `application/octet-stream`. Judging it on that reads silence as
+"not a PDF", the file is discarded, and since an
 unacceptable paste is deliberately left alone, the user sees nothing happen at all. Matching on
 the resolved type also means the surface agrees with what the server will store. The kit's
 extension table covers documents, images and A/V; the server reads a far larger one, so an
@@ -885,8 +847,8 @@ the paste goes to the TOP-MOST one whose `region` contains focus (`document.acti
 so two peer file sections each win while the user is working in them, never "last-mounted
 silently grabs everything." With none focused it falls back to the top of the stack (the
 last-mounted surface — the right default for a dialog stacked over a screen). A `usePasteFiles`
-with no `region` is a pure stack participant, so a single existing consumer is byte-for-byte
-unchanged. `FileDropTarget paste` passes its own region, so you get focus routing for free.
+with no `region` is a pure stack participant. `FileDropTarget paste` passes its own region, so
+you get focus routing for free.
 
 Both drop and paste are web behaviors with native no-op siblings — wrap/call them
 unconditionally on a shared screen. The two templates are the worked examples of the
@@ -925,21 +887,13 @@ own order, under their own names.
 ```
 
 **A HOST verb is a plain `Button`** that reads `useFilesEditorSelection()` →
-`{selected, selectedIds, files, selectMode, clear, exit}`. This is the whole reason the bar is
-composed: an act the kit has never heard of — read these with AI, send them to the broker, ZIP
-them — has a home, instead of forcing the screen to hand-roll the grid and lose the gallery and
-the upload queue with it.
-
-```tsx
-function ReadWithAi() {
-  const { selected, exit } = useFilesEditorSelection();
-  return <Button title="Read with AI" disabled={selected.length === 0}
-                 onPress={() => { run(selected); exit(); }} />;
-}
-```
+`{selected, selectedIds, files, selectMode, clear, exit}` — `disabled` while `selected` is empty,
+and it calls `exit()` when the act is done (`clear` drops the selection but stays in select mode).
+This is the whole reason the bar is composed: an act the kit has never heard of — read these with
+AI, send them to the broker, ZIP them — has a home.
 
 **Each piece renders nothing without the handler it needs**, so composition expresses the
-variants that used to be flags: withhold `onAdd` and there is no Upload; withhold `onRemove` and
+variants: withhold `onAdd` and there is no Upload; withhold `onRemove` and
 there is no Remove and no per-tile ✕ — that IS read-only, with no second mode to keep in sync.
 **No children means no bar**: a grid that previews and nothing else.