@lotics/ui 44.7.1 → 44.8.0

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it, because "it looks fine" is the same claim as "it should work" made with the same evidence. Measure, never eyeball: render it, extract computed values, let the table show the defect. Two GATES that outrank every treatment question (**SUBTRACT** — what question does this element answer, and count FACTS not elements; **RIGHT CONTROL** — name the species before treating it), then 10 probes each naming what to COLLECT and the SIGNATURE in the numbers: type inventory (range, singletons, the label/value shrink war), ground+border+radius across siblings, what each RULE separates, gap RATIOS, the state diff (paint may change, geometry may not), alignment drift (incl. a centred child that moves while its container measures identical), the surface walk (open it, press it, read the settled string), the DATA probe (what is really in the table — incl. grepping rendered text for internal ids), the ABSENCE pass that catches "bland", and microcopy. Plus the extraction snippets, what measurement cannot see, and how to act on a finding (fix the CLASS, and never resolve one with "the docs say X"). |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
@@ -42,6 +42,16 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   panel a few hundred pixels wide lays its contents out for the whole display. (A component that
   needs a number rather than a bucket — how many columns fit — measures its own box; `Table`
   does exactly that.) → [catalog.md §Utility hooks](./docs/catalog.md).
+- **No user-facing string is a literal in `src/` when a locale slice already names it.** Every
+  string a component renders resolves prop → `useLoticsLocale()` slice → the pack's English
+  default. Write it as an allowlist, not a hunt: a literal typechecks, renders, and passes a
+  render test in the language it happens to be written in — the kit shipped a Vietnamese ⓘ label
+  to every tenant that way, invisible to a whole suite of vi-pack assertions. Assert a wired
+  string under the OTHER language. → [composition.md §Microcopy](./docs/composition.md).
+- **Annotate every droppable table column, or none.** A partial `priority` is the trap: an
+  unannotated column sorts above the whole hand-written range, so one annotation makes every
+  other column drop first, and one unannotated column among annotated ones goes first however
+  important it is. → [composition.md §The register's own craft](./docs/composition.md).
 - **A section's ADD rides its heading row, right edge** — Add files, Add fee, New line: a
   `primary` `Button` beside `SectionHeadingTitle`, rendered empty or full. Under the rows it
   extends, the verb MOVES with the row count and vanishes off-screen on a long list; a heading is

package/MIGRATION.md

@@ -4,6 +4,112 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 44.8.0 — a value column gets its own floor, and eight defaults stop fighting their own docs
+
+No API is removed. Three of these change what an existing screen renders, so read them even
+though nothing will fail to compile.
+
+**`StepProgress`'s built-in caption is locale-wired, and `LoticsLocale` gains a `stepProgress`
+slice.** A hand-built pack must supply it (both shipped packs already do):
+
+```ts
+stepProgress: {
+  complete: (total) => `Hoàn tất (${total}/${total})`,
+  stage:    (name, index, total) => `${name} (${index}/${total})`,
+  none:     (total) => `0/${total}`,
+  position: (index, total) => `${index} trên ${total}`,
+},
+```
+
+The caption over named stages was built as `Complete (7/7)` / `0/7` in the component, and the
+screen-reader fallback as `4 of 7` — hardcoded English inside a component the kit requires to
+resolve prop → pack → English default. A Vietnamese board read `Complete (7/7)` in its own
+register. Same defect class as the `fileRow`/`sources`/`counter` leak below, and it hid the same
+way: every state renders correctly under `en`, because English is what the bug produces.
+
+Each entry is a FUNCTION rather than a word to concatenate, for the reason the earlier entry
+gives — where the number sits in the sentence is a property of the language, and `position`
+is `4 of 7` against `4 trên 7`. Passing `label` still overrides the caption entirely; nothing
+that already passed one changes.
+
+**`Finding` stacks its `readings` one per line and drops the ` · ` between them.** No prop
+changes; a two-reading finding is now two lines instead of one.
+
+The separator failed twice over. `docs/reviewing.md` bans ` · ` outright — it claims a
+relationship while refusing to name it, and it is the loudest templated-metadata tell there is —
+so an app reaching for the kit's own ranked-insight component failed the kit's own microcopy
+probe with nothing it could do about that. And a middot is the one mark a screen reader drops,
+so the character carrying "these two disagree" never survived being read aloud: exactly the
+defect `CommentsButton` was fixed for. It wrapped badly too — inline + `flexWrap` could start a
+phone-width line WITH the separator, or split a source from its value across lines.
+
+Stacked, each `source value` pair is a row at every width and needs no separator to relate them.
+Pass `readings` shorter values, or move a long one to `detail`, if the extra line costs you
+somewhere tight.
+
+**A `SequenceItem` with no handlers renders no control column.** Reorder/remove controls still
+render disabled where they cannot act — first item, last item, a row that can be removed but not
+moved — because that is what holds the right edge steady between items that are editable. What
+changed is the item that declares NO editing at all: it used to get three permanently dead
+buttons, which is a dead affordance by `reviewing.md`'s own gates, and a read-only sequence (legs
+already run, a route as recorded) is a common shape rather than an edge case. A list where some
+rows are fully locked and others are editable will now step in the right margin; give the locked
+rows a handler if that matters more than the dead controls did.
+
+**`DateStamp` takes `compact`.** Additive, default `false`. It forwards the option `formatDate`
+already had, dropping the year (`08/09`) so the stamp can agree with a neighbouring column the
+caller formats itself. The format stays in `formatDate` — this is a passthrough, not a second
+implementation.
+
+**A `DetailTable` stacks earlier, because a value column's floor is no longer a control's.**
+`minValueWidth` defaulted to `MIN_CONTROL_WIDTH` (160) — the width below which a CONTROL stops
+being operable, which is a different question from the width below which a VALUE stops being
+readable. A value column holds company names and addresses. At 150/160 the stack threshold was
+334, so a 375px screen kept two columns and handed the value ~170px: a name needing 221 got 104.
+The new `MIN_VALUE_WIDTH` (200) is the default; pass `minValueWidth` explicitly to pin the old
+behaviour on a table whose values really are short.
+
+**An unannotated table column's drop priority is `columns.length + index`, not `index`.** An
+unannotated register still sheds right-to-left — that is unchanged and covered by a test — but a
+MIXED table now behaves the way its author meant. Annotating your most important column
+`priority: 1` used to TIE it with the unannotated column at index 1, and the right-to-left
+tie-break then dropped yours first: the amount column, the fact the register exists for,
+disappearing at narrow widths on a screen that reviewed as correctly annotated. **Annotate every
+droppable column or none** — a partial annotation is what the old default punished.
+
+**A selected `CardSelectItem` carries a GROUND**, not the same ring as hover. It was
+`selected || hovered || pressed || focusVisible` → one style, so the card you had CHOSEN was
+pixel-identical to the card under the pointer. Selection is now `accent_wash` + an accent edge,
+the same "you are here" a selected table row and an active chip carry. This is the fix 43.5.0
+made for `Table`'s selected row, one release late.
+
+**`DataGrid`'s flexible column has a floor** (`FLEX_MIN_WIDTH`, 120) instead of `minWidth: 0`.
+This grid sheds no columns by design — every column is a measure you came to compare — so the
+fixed columns held their widths and the flexible identity column absorbed the whole squeeze,
+all the way to zero: a narrow container rendered rows of unlabelled money, silently. Past the
+floor the grid now overflows, and a narrow container needs to scroll it.
+
+**`AgentRunLike.error` is OPTIONAL.** It was declared required while its own docblock promised
+it accepted an SDK run's optional `error` — and an optional property is not assignable to a
+required one however wide the required one's type, so the three-line usage printed in
+`ai_patterns.md` did not compile. **If you worked around it** with a `useMemo` reshape or a cast
+(`{ ...run, error: run.error ?? null }`), delete that: hand the SDK's run straight over.
+
+**`Select` takes the `D` data generic** its siblings already had, so `optionPicker(...)` spreads
+into it without a cast. Additive.
+
+Also additive, nothing to change: `MIN_VALUE_WIDTH` and `FLEX_MIN_WIDTH` are exported (the
+latter via a new `./table_fit` entry point, which also exports `ROW_HEIGHT` and `COLUMN_GAP` so
+a skeleton can be built from the register's own constants); `formatMoney` takes
+`maxFractionDigits` for a genuine per-unit price (`Intl`'s currency style floors at the
+currency's minor unit, so an LCL rate of 0,019 US$/kg printed as `0,02`); `InlineSelect`
+forwards `getOptionDescription` to the two-line option row `OptionList` already renders;
+`NumberInput` takes a `placeholder`; `EmptyState` and `ErrorState` centre their TEXT and not
+only their box (they swap into one another as a read settles, so only one of the two centred
+would have shown up as the copy jumping alignment at the moment a region fails); a
+heading row WRAPS rather than crushing its title; `Accordion`'s meta yields before its title;
+`CardHeaderTitle` reads the ⓘ's name from the locale pack; and `ReferenceField`'s peek footer
+gives its clear the same resting surface as the verb beside it.
 ## 44.5.0 — `Pagination` drops the page index
 
 The pager rendered a range AND a page index — `16–30 of 45` beside `Page 2 of 3`. Both answer
@@ -94,11 +200,10 @@ No API is removed and nothing throws, but four DEFAULTS moved, so every register
 in your app renders differently on upgrade. Each is reversible at the call site if you need the
 old look while you catch up.
 
-**Table column headers are sentence case, not all-caps** — and one ink step lighter
-(`zinc-500`). `Table` and `SortHeader` were uppercasing every column label, which the heading ramp
-bans and names the #1 templated tell. The ink step is not cosmetic and cannot be skipped: at
-`muted` the header matched a row's supporting line in size, weight AND colour, so dropping the
-case alone leaves it reading as a stray label rather than as the band naming the columns.
+**Table column headers are sentence case, not all-caps.** `Table` and `SortHeader` were
+uppercasing every column label, which the heading ramp bans and names the #1 templated tell. What
+keeps the band from reading as a stray label once the case is gone is WEIGHT: the header is
+`sm muted medium`, and a row's supporting line is `sm muted` regular, so the two never collide.
 
 **Row separators are lighter than the header rule.** The band capping a table keeps
 `colors.border`; the hairlines between rows are `zinc-100`. Every rule used to be `border`, which

package/docs/catalog.md

@@ -222,6 +222,13 @@ Two columnar shapes, and the choice is about data size:
   heading, so digits line up under their label; **`DataGridColumn.footer` gives that column its
   cell in the group's footer row** (a subtotal, a resolved measure) — the grid lays it out in
   the column's own box, so a total can never drift from what it sums and no consumer rebuilds
+  **`DataGrid` SHEDS NOTHING at narrow widths, and that is deliberate** — every column is a
+  measure you came to compare, unlike `Table`'s register of objects where the row is an index
+  and the record holds the rest. So it has no `priority` and no stacked mode: fixed columns keep
+  their widths, the flexible column holds a `FLEX_MIN_WIDTH` floor, and past that the grid
+  OVERFLOWS. A narrow container must scroll it horizontally; the floor exists because without
+  one the flexible identity column absorbed the entire squeeze down to zero and the grid
+  rendered rows of unlabelled numbers, silently. If you want columns to drop, you want `Table`.
   the row. `renderGroupFooter` remains for content that does NOT sit in a column (a per-group
   add row). The grid takes exactly its container's width — no outdent to fight, so it needs no
   scroller unless YOU add one. It renders ALL rows (no
@@ -376,7 +383,9 @@ your screen. See the AI-patterns doc indexed in [AGENTS.md](../AGENTS.md) for th
 `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, laid out HORIZONTALLY: a severity dot, the title, and the `delta` right-aligned on
-that same line, over one dim line of `readings` — `source value · source value`, both kept on
+that same line, over the `readings` stacked ONE PER LINE — each `source value`, no separator
+joining them (a middot claims a relation it will not name, and is the one mark a screen reader
+drops), both kept on
 screen with NEITHER marked as the wrong one, since a finding reports that two sources disagree
 and which is right is the reader's call. `detail` is the optional consequence. A reader scanning
 a stack gets severity down the left edge and magnitude down the right. The readings ARE the
@@ -542,6 +551,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   one interaction it signals; the padding still comes off the 8-grid, the ring is only
   the floor), `HOVER_BORDER`, `CONTROL_TRANSITION`, `chipSurfaceStyle` — the shared
   control-surface tokens.
+- **`table_fit`** — the register's shared geometry, importable so a skeleton or a
+  hand-built band derives from the same numbers `Table` lays out with: `ROW_HEIGHT` (72),
+  `COLUMN_GAP`, `ROW_GUTTER`, `FLEX_MIN_WIDTH` (120 — what a flexible column needs to stay
+  usable), plus `computeTableFit` itself. `MIN_VALUE_WIDTH` (200 — a record VALUE column's
+  floor, deliberately above a control's `MIN_CONTROL_WIDTH`) lives in `control_surface`.
 - **`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
   to system fonts.
@@ -1150,7 +1164,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `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,
+  even where they cannot act so the right edge never shifts between items — but an item passing
+  NO handler at all renders no control column, so a read-only sequence (legs already run, a route
+  as recorded) is a first-class shape rather than three dead buttons per row. 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
@@ -1182,8 +1198,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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`**
-  on a flat-text value row (`InlineStatic`, plain `Text`) tucks the annotation up by the
-  control band's slack so its gap matches a chip row's.
+  on a value sitting OFF the inline-control grid (a raw node — NOT `InlineStatic` / `InlineSlot`,
+  which are on it) aligns the annotation to it on both axes: drops the control text inset and
+  tucks up by the band's slack.
   The three annotations are ONE anatomy shared with a checklist row's `ChecklistNote` — same
   order, same alert semantics — because a record's field and a task's field are the same thing
   on two surfaces.
@@ -1257,7 +1274,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   panel narrower than the control that opened it reads as belonging to something else. So the
   field truncates its name to one line and the peek's header WRAPS the whole of it: the column
   stays scannable, the full value is one press away. Between the floor and `labelWidth +
-  MIN_CONTROL_WIDTH + 24` a `DetailTable` stacks, which is the right grammar at that width.
+  MIN_VALUE_WIDTH + 24` a `DetailTable` stacks, which is the right grammar at that width — the
+  VALUE floor (200), not the control floor, because that column holds names as well as editors.
   The verbs live INSIDE the
   peek, never on the field, and they are ALL `Button`s at one altitude — a peek is
   dialog-scale and a dialog's verbs are buttons, so mixing weights only made the reader rank
@@ -1374,6 +1392,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   position (a group band, a totals line) and the gutter stays blank so the cells beside it stay
   in line. A position is NEVER an identity: sort or filter and row 12 is a different record —
   a stable handle is a column, and it leads the cells. Worked screen: `tpl_item_list`.
+- **`tabs`** — a tab may state its band's size with `TabOption.count`, and needs attention with
+  `TabOption.status` (a `ColorName` dot). Pressing the tab IS the filter, so the count is also the
+  reason to press it. → [composition.md](./composition.md) §"A partitioning control states its band's size".
 - **`table`** rhythm — rows are separated by their own height and the hover wash, never by a hairline; the register's one line is the band capping the columns. 72px rows, overridable per row with `TableRow`'s `minHeight` when a surface genuinely needs density. There is no `spacing` prop: a table of VALUES rather than of objects is a different component (`Matrix`, `DataGrid`). → [composition.md](./composition.md) §"The register's rhythm".
 - **`table` › `TableGroup`** — a titled BAND of rows inside a `Table` (`label`, `count?`, `color?` for a single valence dot). Turns a register that presents records into one that triages them: group by what implies a different ACTION, order the bands by what needs the reader now, and let air rather than a rule separate them. → [composition.md](./composition.md) §"A register that TRIAGES".
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
@@ -1435,6 +1456,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   empty — and a ladder of fields is a form with invisible borders. Reach for `InlineDatePicker`
   when a person is expected to ENTER the date, and this when the system already knows it.
   Empty renders a thin rule, not a placeholder; read-only (omit `onChange`) renders text alone.
+  `compact` drops the year (`08/09`) — the stamp shares a row with dates the caller formats, and
+  the option goes straight through to `formatDate`, which stays the one place deciding what a
+  date looks like.
   `onChange` fires on CLOSE, not on each pick — one commit per visit, and a dismissed panel
   still writes whatever was picked in it, which is what makes a single tap enough.
   Worked screen: `examples/tpl_record.tsx` § Progress.
@@ -1606,7 +1630,9 @@ component rather than showing it at zero.
   status mix on one bar).
 - **`step_progress`** — `StepProgress`: N-of-M dots/segments progress. A real `progressbar`
   (valuenow/min/max) because its segments are decoration over ONE quantity — the opposite
-  case from `stepper`, whose steps carry content a `progressbar` would hide.
+  case from `stepper`, whose steps carry content a `progressbar` would hide. Pass the stage
+  NAMES and it captions itself from the `stepProgress` locale slice ("Hạ bãi (2/4)"); `label`
+  overrides, `captionTone="danger"` is the documented stalled-stage slot.
 - **`breakdown`** — `Breakdown`: a stacked bar + ranked share rows, pressable to drill;
   `maxRows` folds the long tail behind a localized "Show N more" toggle
   (`BreakdownLabels`).
@@ -2019,7 +2045,9 @@ component rather than showing it at zero.
   column quietly acquires TWO left edges and two baselines, and `DetailRow`'s label (which pads
   down to meet a control) agrees with one kind of row and not the other. `InlineStatic` is the
   STRING case and composes it; reach for the slot when the value is a node, which a review
-  surface always is. NOT for a table cell — a `Table` sets its own row rhythm.
+  surface always is. An ANNOTATED row needs the grid even with no editor in sight, because the
+  annotation stack is inset to a control's words — data_entry.md §The editability affordance
+  has the per-table test. NOT for a table cell — a `Table` sets its own row rhythm.
 - **`use_change_set`** — **`useChangeSet(ids, { initial })`**: the accept/reject/undo
   bookkeeping as a HOOK, zero layout — `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`,
   `accepted`/`rejected`/`pending`, `keptCount`/`total`/`settled`. Decisions are stored as

package/docs/composition.md

@@ -8,6 +8,23 @@ full worked-example screens ship as source in `examples/tpl_*.tsx` (picked by jo
 [templates](./templates.md)). Every rule here is enforced by the primitives' defaults; fighting
 them produces off-system UI.
 
+## The form comes before the treatment
+
+**Name what the subject IS, then reach for parts.** A set of records is a register; a thing moving
+through ordered places is a rail; work assigned to finite resources over time is a board; a
+sequence of events is a timeline; a population whose point is its deviant minority is a queue
+sorted by deviation. Getting this wrong cannot be recovered later — a register of objects that
+should have been a rail is well-typed, well-spaced, correctly aligned and still says nothing about
+order or progress, because a status column reports one word and leaves the reader to know which
+word comes after which.
+
+The pull toward a register is structural, not a lapse in taste: `Table`, `DetailRow`,
+`SummaryLine` and `Badge` are the most reachable things here, and they compose into something
+defensible for almost any data. That is exactly why the question has to be asked out loud. **Reuse
+first is about not duplicating primitives** — a one-off composition needs no new component, so the
+kit lacking a device is a reason to compose one from what it has, not a reason to flatten the
+subject into rows.
+
 ## Canvas & content column
 
 - **Canvas**: a full-bleed `colors.white` ScrollView with `padding: 28`. Cards separate from the
@@ -183,6 +200,14 @@ without scanning. The heading row is the section's control line — it already c
 and the view controls — so the add belongs on it, in the same spot whether the section holds
 nought or forty.
 
+**When the row runs out of width, the VERB wraps — the title never gives way.** The title names
+the section; the verb is the thing that can move. Getting this backwards is easy to ship because
+RN-Web resolves `flex: 1` to `flex-basis: 0%` with `min-width: 0`, so a title beside a button that
+holds its intrinsic width is the half that collapses — measured at 375 as a heading broken one
+word per line beside an untouched button. `SectionHeading` and `SubsectionHeading` wrap and floor
+their title column for this; do not add a second `flex: 1` spacer beside a title that already has
+one, which halves its share again and is how a badge came to land on top of a section title.
+
 **Where there IS no heading row, the add has nowhere else to be, so it rides the surface's own
 bar** — an attachment popover, a dialog body, any self-contained widget. That is not an exception
 to the law so much as the same reasoning: the rule exists so the verb sits in ONE place a reader
@@ -217,6 +242,18 @@ no path actually closes.
 - **Only the ADD.** A verb that acts on a SELECTION (delete, export, run) belongs to the
   selection — `FloatingActionBar` — and a verb about ONE row stays on the row.
 
+## A partitioning control states its band's size as a PROP
+
+`TableGroup` takes `count`; `Tabs` takes it per option. Neither takes a label with the number
+formatted into it, and that is the whole rule: `"Trên tàu (4)"` is a second copy of a figure the
+screen already computes, and it is the copy that goes stale — the band re-counts on every filter
+and the string does not.
+
+It also decides where the count may live. A register whose bands already state their sizes must
+not carry a strip of chips above it repeating the same three numbers; that is one fact twice, and
+the reader learns to skip the strip. And a count is a reason to PRESS — a control that states how
+many rows are behind it and does not filter to them is stating a fact it refuses to act on.
+
 ## Period filters for time-constrained data
 
 Time-constrained data gets a **`DateRangeFilterField`** in the header band — never a static period
@@ -312,7 +349,11 @@ compete instead of reading as different things. Selection changes what the box I
 hover changes how intensely it says it.
 
 For fields: layer the hover-border AFTER `style` so it wins over the caller's resting edge, put the
-open ring (`FOCUS_RING`) on the open state, and **a field NEVER greys its content**. The bug this
+open ring (`FOCUS_RING`) on the open state, and **a field NEVER greys its content**. That ordering
+is load-bearing rather than tidy: a caller's resting `borderColor` is exactly how a frameless
+variant gets expressed, and layered the other way it erases the hover edge that is such a field's
+ONLY affordance — a control that then draws nothing in either state and is simply never pressed.
+Give the field a variant PROP for its resting frame instead of taking one through `style`. The bug this
 grammar prevents: a FIELD built on `PressableHighlight` inherits the wash AND its own border — it
 greys *and* animates its edge while its siblings only border-hover. Reach for `PressableHighlight`
 on a bordered/input control and you've made it.
@@ -416,6 +457,12 @@ a dashboard. Card stat rails use `KPICard`.
   form round-trip never expands them to a fabricated `"2026-05-01"`. Comparisons and sorting treat
   a partial as its period start (`"2026" < "2026-05" < "2026-05-01"`).
 
+**A per-unit price is not a total, and the currency's minor unit is the wrong floor for it.**
+`Intl`'s currency style rounds to two decimals for USD, so a rate of 0,019 per kg prints as
+`0,02` — a 5% error rendered as fact, with nothing on the screen saying it was rounded. Pass
+`maxFractionDigits` on a UNIT price; leave it off for a total, where two decimals is the contract.
+Never hand-roll the grouping or the symbol to get the digits back.
+
 ## Every number is a door
 
 Except the KPI strip: a component that summarizes records leads to the records behind it when
@@ -712,6 +759,21 @@ action goes to the referenced record's own page; a local `Drawer` that re-shows
 just showed makes "Open" mean *read that again, wider*, and leaves the real record unreachable
 from the only control that promised it.
 
+**A record surface answers *which record is this* first — and the block that does it is SHORT.**
+Identity is the handful of facts someone would say aloud to name this record (its number and its
+counterparty, usually two); everything else is an ATTRIBUTE and belongs below the answer the
+reader opened the record for. Get the size wrong and the position becomes unwinnable: eight
+labelled header fields push the ledger under the fold, and moving the block to the bottom to fix
+that leaves a reader who cannot tell whose record they are in. Both orders measure perfectly, so
+neither is caught by any check that reads the rendered screen. **When a leading block buries the
+answer, shrink it — do not move it**; frequency of EDIT is not the axis, because a rarely-edited
+fact can still be the one that names the thing.
+
+"The chrome already carries identity, so the body need not lead with it" is a real argument and a
+falsifiable one — verify it FACT BY FACT before relying on it. A summary strip showing the record
+number and its totals carries half an identity; the counterparty is missing, and half is what
+makes the claim feel true while the reader still cannot name what they are looking at.
+
 **All of the above is the LIST SCREEN.** A CHILD COLLECTION inside a record page — fees, lines,
 stops, containers — does the opposite: the row **EXPANDS** (`TableRow` `detail` + `expanded`),
 never docks a drawer. A drawer's whole job is to supply a context the reader is missing, and on a
@@ -928,10 +990,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   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.
+  the value. A value that sits OFF the
+  inline-control grid — a raw node, not an `InlineStatic` / `InlineSlot` — sets **`DetailRow
+  flat`**, which aligns its annotations on both axes: they drop the control's text inset so the
+  description starts on the value's own left edge, and tuck up by the band's slack so the gap
+  under the text matches the gap under a chip. Miss it and the row has three left edges and a
+  hole; pass it on a value that IS on the grid and you create both. Which one a static value
+  should be is decided per table — see data_entry.md §The editability affordance.
 - **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
@@ -1243,6 +1308,15 @@ which is the loudest possible version of the thing the rule exists to stop. Remo
 without replacing the separation is what left the header looking adrift — the ink step above is
 the replacement, and the two changes only work together.
 
+**Annotate every droppable column, or none.** `priority` decides what a narrow container sheds
+(lowest number is last to go, and column 0 — the identity — never drops). A PARTIAL annotation is
+the trap: an unannotated column defaults above the whole hand-written range, so one annotated
+column silently makes every other column drop before it, and one unannotated column among
+annotated ones is the first to go however important it is. Both read as correct in review. The
+question to answer per register is "what is the last column standing", and the answer is almost
+always the figure the register exists to compare — so give that one the lowest number and work
+outwards.
+
 **A row's SUBJECT is `medium`, never semibold.** Semibold is the heading ladder's weight — `#`,
 `##`, `###` are all semibold — so a register whose row subjects are semibold renders its content
 at heading weight once per row, in the same font CUT as the page title (`Inter_600SemiBold` is a
@@ -1495,6 +1569,12 @@ disclosure exception). `TextLink` takes the blue only when it has an `href`; as
 a value, or as a muted in-place disclosure, it stays neutral — because a press that opens a PEEK,
 or unfolds a transcript, is not a trip.
 
+**Selection is a GROUND, and hover is a ring — at every altitude.** A row, a card, a chip, a
+tile: the thing you have CHOSEN carries the accent wash, and the thing under the pointer carries
+the ring. Collapsing them into one "active" style makes the selected item pixel-identical to the
+hovered one, so "which did I pick" is answerable only by moving the mouse away. The tell in code
+is a single boolean OR-ing selection together with hover, press and focus.
+
 ## `Badge` is for STATUS only — everything else is text
 
 A `Badge` means STATE that must read at a GLANCE — a lifecycle status, a risk level, a quality
@@ -1610,6 +1690,12 @@ Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px b
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
 
+**A control's height comes from `CONTROL_HEIGHT`, never from padding tuned against a leading.**
+Padding that happens to sum to the band height is a second owner of that number, and it drifts the
+moment the type ramp moves — which the ramp is allowed to do. The signature is one control
+standing a few pixels proud of every sibling in a filter bar, correct on the day it was written
+and wrong after a release that touched no control at all.
+
 **The trim test — does this element RESTATE something already on the screen?** Run it over every
 screen before shipping: a per-row proportion bar when the percentage is already on the row; the
 percentage itself when the column holds four values and a total; a state line that only says

package/docs/data_entry.md

@@ -66,6 +66,13 @@ Controlled inputs make derived state track what is on screen, and read shorter t
 they replace — four `DetailRow` + `Inline*` pairs whose `onSave` exists only to `setState` collapse
 to four fields. 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.
+
 **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
 gates the commit and is checked continuously; the message claims the reader did something wrong, so
@@ -313,19 +320,66 @@ where it must stay strictly inside its box — that is `framed`. A DISABLED `fra
 box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
 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.
+
+**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
+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.
+
 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.
 
-**Only in a grid that MIXES the two.** "Copies the editor box metrics" means it hard-sets
-`INLINE_CONTROL_HEIGHT` — worth paying to hold a column straight beside real editors, pure waste
-where there are none. In an ALL-static grid (a peek's facts, a summary popover) it reserves a 40px
-control band for a 20px value, and the row is the MAX of that box and the table's own band, so
-neither fix works alone: use plain `Text` for the value AND pass `DetailTable` a `minHeight` (28,
-`DetailRow`'s own default). Same test as `labelWidth` — a `DetailTable`'s defaults are the
+**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:
+
+- **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
+  centres in a 40px band.
+- **A value column's floor is not a control's floor.** `minValueWidth` decides when the table
+gives up two columns and stacks, and it defaults to `MIN_VALUE_WIDTH` (200) rather than a
+control's `MIN_CONTROL_WIDTH` (160), because the column holds company names and addresses, not
+only editors. The narrow-width failure is silent in both halves: the table technically fits, so
+it does not stack, and every value is then truncated past half while the label beside it measures
+perfectly. Raise it further where a cell holds MORE than one editor; lower it only where the
+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
+  appears only on the rows that happen to carry a description, so a column slides in and out of
+  alignment down its own length.
+
+Decide it per TABLE, never per row: one annotated static row puts every static value in that table
+on the grid, or the table keeps two row heights for no reason a reader can see.
+
+In an all-static, un-annotated grid (a peek's facts, a summary popover) the grid buys nothing and
+costs 40px of band for a 20px value — and the row is the MAX of that box and the table's own band,
+so neither fix works alone: use plain `Text` for the value AND pass `DetailTable` a `minHeight`
+(28, `DetailRow`'s own default). Same test as `labelWidth` — a `DetailTable`'s defaults are the
 inline-control grid's; a grid that isn't one overrides both.
 
+`DetailRow flat` is the ESCAPE from the grid, not a synonym for read-only: it says "this value is
+a raw node sitting off the control band", and it corrects the annotations on both axes for it —
+dropping the text inset and tucking the block up by the band's slack. Never pass it with
+`InlineStatic` or `InlineSlot`, which are ON the grid: there it re-introduces the 9px drift it
+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

package/docs/reviewing.md

@@ -45,10 +45,35 @@ the same direction. The kit measures the CONTAINER, not the screen — see AGENT
 
 ---
 
-## Two gates, before any probe
+## Three gates, before any probe
 
-A perfectly-treated element that should not exist still measures clean, and a wrong control cannot
-be treated into a right one. Both of these are cheap and both outrank everything below.
+A screen in the wrong FORM measures clean in every direction, a perfectly-treated element that
+should not exist still measures clean, and a wrong control cannot be treated into a right one.
+All three are cheap and all three outrank everything below.
+
+### 0. RIGHT FORM
+
+**Name what the subject IS before composing anything.** A set of records is a register. A thing
+moving through ordered places is a rail. Work assigned to finite resources over time is a board.
+A sequence of events is a timeline. A population whose point is its deviant minority is a queue
+sorted by deviation. A quantity across two dimensions is a matrix.
+
+This gate exists because **every probe below reads a screen that is already a register of fields**
+and measures its TREATMENT. So a screen that should have been a board or a rail passes the type
+inventory, the ground tally, the gaps, the rules and the alignment — all of them — and still reads
+as templated. No amount of treatment fixes it, and nothing else here can see it.
+
+*The tell that it was skipped:* every screen in the product is a register with a summary line over
+it. That is what reuse-first produces when nothing asks the question — the catalog's most reachable
+parts are `Table`, `DetailRow`, `SummaryLine` and `Badge`, so a subject whose natural shape is not
+a table gets flattened into one and no probe fires. **Reuse-first is about not duplicating
+PRIMITIVES, not about the shape of a screen**: a one-off composition needs no new component, so
+"the catalog has no journey rail" is an argument for composing one out of `Stepper`, not for
+rendering a status column and moving on.
+
+*And check the form against what the data can FILL.* A rail with no stamped stops, a calendar with
+no durations, a map with no coordinates — each renders an empty device that measures perfectly.
+→ probe 8.
 
 ### 1. SUBTRACT
 
@@ -244,6 +269,14 @@ A resting register is the cheapest thing to screenshot and the least likely to h
 
 - **Open what the row opens** and measure where the actionable field LANDS. An UNBOUNDED section
   (a feed, a thread) above a bounded one buries it, and the burial deepens with use.
+- **Name the record before you read it.** Collect the y of each fact that IDENTIFIES what is open
+  (its number, its counterparty) and compare against the viewport; any of them first answered
+  below the fold is the finding. Then measure the other direction — the top of the block answering
+  what the reader OPENED this for, and what sits above it. A leading block that pushes that answer
+  under the fold is too LONG, not mis-positioned: moving it down trades a buried ledger for a
+  reader who cannot tell whose record they are in, and both orders measure clean on their own, so
+  nothing that reads a resting screen catches either. Re-measure at 375, where a block that cleared
+  the fold at 1280 buries the answer. → [composition.md](./composition.md) §"Master-detail".
 - **Press every control** and look at the state you land in. Commonest miss: a value rendering as
   a coloured chip in a register and as bare grey text in its own EDITOR.
 - **TAB through it, then diff what a keyboard reaches against what LOOKS pressable.** A pointer