@lotics/ui 47.13.1 → 47.15.0

package/AGENTS.md

@@ -17,8 +17,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — incl. `just_arrived` (`useJustArrived` + `TableRow`'s `justArrived`: the one-shot wash a row wears when it LANDS, so a realtime push is visible rather than one row of two hundred silently changing) and `SplitRow`/`SplitPane` (the responsive pane row — a weight that survives into a stacked column divides HEIGHT and clips a pane) — 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) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [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; findings, provenance, confidence (`Finding` is filed here because AI produces most of them, NOT because it is AI-only — a rules-derived contradiction is as in scope as an extraction's); **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), **a surface keyed by a whole MONTH takes a `MonthStepper`, never a range field** (its `max` bound is the contract), **a subject-by-date sheet of STATES is a `StateMatrix`** (a glyph per cell, the legend derived from the same list; not a `Matrix`, where a blank means zero), **a report's comparator is DERIVED from the selected range with `previousPeriod`, never a second control** (show it on the figure — `KPIStripItem.trend`/`caption`, `Metric previousValue`, a second `LineChart` series; a grain `SegmentedControl` beside the date field re-adds the mode the field removed), and where a commit sits. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the opinions-the-reader-cannot-operate pair (bands nobody asked for, pills crowding a search) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [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. |
 
@@ -87,7 +87,9 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   identity. And a radius is a PROPORTION of the box (`proportionalRadius`), because a component
   sized by data renders as a pill at one height and barely a corner at another.
   → [composition.md §"A body, not an edge"](./docs/composition.md).
-- **A subject over one qualifying line is `CellStack`, never two `Text`s in a `View`.** It owns
+- **A subject over one qualifying line is `CellStack`, never two `Text`s in a `View`.** Pass a
+  whitespace `caption` to RESERVE the line on a row with nothing to say — it is normalised to a
+  non-breaking space, so the column keeps one first-line height. It owns
   the whole stacked-pair rule — which rung the caption takes (from what ELSE separates the pair),
   which lines are tightened, and the zero gap. A hand-rolled pair gets one of the three wrong
   silently: the excess comes from the LINE BOX, so no margin and no gap exists to explain it and
@@ -107,6 +109,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **A countdown ANNOTATES its date field — never a trailing badge, and never hand-rolled.**
   Reach for `@lotics/ui/deadline` and spread `deadlineAnnotation` onto the
   `DetailRow`. → [catalog.md §"Dates & times"](./docs/catalog.md).
+- **A record surface's outline is `SectionNav` + `useSectionNav`, never hand-rolled rows.** The
+  hook spies the scroll, the component draws the rail AND the narrow bar that replaces it, and
+  the item's `issue` dot is what makes the outline say where the problem is. A hand-rolled rail
+  loses the live re-measure, the last-section rule and the narrow form.
+  → [catalog.md §"Overlays & navigation"](./docs/catalog.md).
 - **A third-party channel takes `BrandMark`, our own glyphs take `Icon`.** The names are an
   allowlist, so a channel with no mark (a phone call, an event, a website) fails to typecheck
   and falls back to `Icon` instead of borrowing another company's logo.
@@ -146,6 +153,13 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   gets `<GroupLead>` (`sm` medium, page ink). Neither takes `size`/`weight`/`transform` — the
   omitted props are the rule. →
   [composition.md §"The heading ramp"](./docs/composition.md).
+- **N booleans across FIXED positions are a `ToggleStrip`, never a row of hand-rolled cells.**
+  A week's running days, a gate's open hours, a notice's channels: a compact strip at
+  `CONTROL_CONTENT_HEIGHT`, each cell a `checkbox`, `minOne` where the empty set is a different
+  reading rather than a neutral one, and `toggleStripWidth(n)` for the column that seats it.
+  Selected wears `chipSurfaceStyle`'s doubled dark edge — a brand ground on a selection is the
+  decision the kit already reversed once.
+  → [catalog.md §"Pickers & selection controls"](./docs/catalog.md).
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
 - **A button never contains a control** — a row that presses open AND carries its own controls

package/docs/catalog.md

@@ -387,7 +387,9 @@ Worked example: [`tpl_board`](../examples/tpl_board.tsx).
 `KPIStrip` (the dashboard stat band), `SummaryLine` (the light inline register/list summary
 — below the toolbar, from the filtered rows), `KPICard` / `Metric` (headline figures),
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
-set — no recharts), `ProgressRing`, `ProgressBar` (its `compact` prop = ONE row, track + a
+set — no recharts; `LineChart` takes `points` for one line or `series` for several on one
+shared scale, which is where a "this period vs last" comparison goes), `ProgressRing`,
+`ProgressBar` (its `compact` prop = ONE row, track + a
 plain sm tabular count beside it — the cell/heading/peek-trigger meter. **The track clamps at
 100%, the caption does not** — over its max it reads `2,100 / 2,000 (105%)`. **`max: null` is an
 unbounded meter** — the caption states the value and the caller's `unboundedLabel`
@@ -413,7 +415,9 @@ stays solid, others dim — the caller renders the records). The subset/drop-off
 split across stages), `StatusGrid` + `StatusLegend`, `Heatmap`
 (density: colour-only, "where does it cluster"), `Matrix` (the PIVOT cross-tab: the NUMBER
 in each cell — optionally a heat wash behind it — plus row/column/grand totals; press a cell
-to drill).
+to drill), `StateMatrix` (the CATEGORICAL cross-tab: subjects down the side, dated positions
+across the top, a STATE glyph in every cell — an attendance sheet, a fleet's month; a blank
+cell means "nothing was due", never zero).
 
 ### Surfaces & layout
 
@@ -533,7 +537,8 @@ patterns doc indexed in [AGENTS.md](../AGENTS.md)).
 upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocation),
 `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
 `CalendarView` (the `calendar` module — days are the axis), `GanttView` (RESOURCES are the
-axis: a channel, an owner, a vehicle), `comments_thread`, `SocialPostPreview` (a post as ONE
+axis: a channel, an owner, a vehicle), `Timetable` (a repeating PATTERN with no dates — time ×
+weekday, a slot per row, today a tinted column), `comments_thread`, `SocialPostPreview` (a post as ONE
 network's feed shows it, with the count against that network's limit and every rule its API
 would refuse — the publish gate reads the same `socialPostIssues` the preview draws).
 
@@ -641,7 +646,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `react-markdown` instance the kit's renderer cannot serve. Never `remark-gfm`: it ships a
   regex-lookbehind literal, which WebKit older than Safari 16.4 rejects while parsing the bundle.
 - **`markdown.css`** — import once for the web markdown styling.
-- **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle`.
+- **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle` (incl.
+  `monthYear` and `quarterYear`, the two period labels).
 - **`format_money`** — `formatMoney` / `formatCompactNumber`.
 - **`text_utils`** — text/typography plumbing: `getTextColor` (the TextColor→hex map incl.
   the AA-cleared valence set), the Inter `fontFamily*` stacks, and `getInputTextStyle` /
@@ -690,8 +696,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `vi`→`vi-VN`); date/time controls read it via **`useLocaleTag`** (`resolveLocaleTag` is its
   pure core) so the segmented field's part ORDER (dd/MM vs MM/dd), the picker calendar's
   weekday/month names, and `formatDate` display all follow the provider with no per-instance
-  `locale` prop — an explicit `locale` still overrides. **Limitation:** the calendar/gantt
-  views and the comment labels do not read the provider — pass their `labels` props directly.
+  `locale` prop — an explicit `locale` still overrides. `CalendarView` and `GanttView` are
+  wired the same way, chrome and tick names both. **Limitation:** `CommentList` carries its
+  own English defaults — pass its `labels` prop directly.
 - **`colors`** — the palette + `withAlpha`, `solid`, `tint`, `ramp`, `ColorName`,
   `isColorName`, `asColorName` (coerce a stored option/status token to a `ColorName`,
   neutral fallback).
@@ -770,6 +777,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`group_avatar`** — `GroupAvatar`: a name's initials in a zinc rounded square (`size` — the
   same rung scale AND the same initials rule as `Avatar`, default `md`); the avatar for
   image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`.
+- **`organization_name`** — `stripLegalForm(name)`: an organization's name without the legal
+  form it opens or closes with ("Công ty TNHH", "HTX", "Hộ kinh doanh", "Ltd.", "LLC"…). The
+  name a mark derives its initials from AND the title a register row shows — composition.md
+  §Identity marks says why: the form puts the same first letters on every row and spends the
+  first 60px of the column on words that tell no two rows apart. The legal name belongs on the
+  record the row opens. A name that is nothing but a form comes back unchanged.
 - **`thumbnail_stack`** — `ThumbnailStack`: the same capped stack over THINGS rather than
   parties — a set of product, document or unit pictures answering "an order of what?" in one
   register cell. Takes `{ id, label, image? }`, shows `max` (default 3) and makes the rest the
@@ -952,6 +965,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   destructive action slot (children, e.g. a `danger` Button); sits APART at the bottom of a
   record/settings surface. The heading defaults to the locale's `dangerZone.title`
   ("Danger zone" / "Vùng nguy hiểm") — pass `title` only to override.
+  ONE LEFT EDGE, and it is `Callout`'s anatomy that gets it: the hazard mark sits in an outer
+  ROW beside a column holding title, consequence and actions, so all three derive from the same
+  edge. Put the mark INSIDE the heading row instead — the obvious way to write it, and how this
+  shipped — and only the TITLE moves right, so the loudest line in the block sits 22px past the
+  sentence explaining it and the button under both starts somewhere else again. Three edges
+  inside one 16px-padded box, on the primitive that exists so a hazard is not hand-rolled. Any
+  block with this anatomy (mark, title, body, actions) is laid out the same way.
 - **`landmark`** — `Landmark`: the semantic region wrapper — `kind`
   banner|navigation|main|complementary|contentinfo|region maps to the matching HTML element
   on web for screen-reader landmark navigation, `accessibilityRole` on native;
@@ -1208,7 +1228,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   choice. → `data_entry.md` §"Choosing a CHOICE control" — and check the states really ARE
   exclusive: independent capabilities that happen to be exclusive today bake today's
   combinations into the type.
-- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set. The row wraps by
+- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set. The ACTIVE chip
+  steps up in INK, never into a heavier weight: both states are `medium`, and what says "this
+  one is on" is the doubled zinc-900 edge plus default ink. Semibold is a separate, genuinely
+  heavier font FILE and the heading ramp is semibold at every rung, so an active chip in
+  semibold rendered a filter value at heading weight — and made itself a singleton treatment on
+  every screen carrying one, while `Tabs`, which answers the same question, steps
+  regular → medium. The row wraps by
   default; `overflow="scroll"` keeps it to ONE row for a register FILTER, where six options
   carrying counts wrap to three rows — 136px on a phone, more than the search band and the view
   switcher combined. Deliberately NOT a screen-width branch: width is not the question, the job
@@ -1216,6 +1242,35 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   chips are worth more than a `Picker` there only because every option is visible, and a swipe
   is exactly what takes that away. → `data_entry.md` §"Choosing a CHOICE control" for which
   control the count and the job call for.
+- **`toggle_strip`** — `ToggleStrip` (+ `toggleStripWidth`): N INDEPENDENT booleans across FIXED
+  positions, drawn as one compact strip — which days a departure runs, which hours a gate is
+  open, which channels a notice goes out on. Sits inside a register row or a field at
+  `CONTROL_CONTENT_HEIGHT`, not on a control band.
+  Not `ChipGroup` (one choice, and chips WRAP — which destroys the reading this exists for:
+  a column of strips lets the eye run down position 3 and see the shape of the week), and not
+  `SegmentedControl` (an exclusive choice, a radiogroup — each cell here is a `checkbox`).
+  `minOne` refuses to turn the LAST cell off, for a set where empty is a DIFFERENT reading
+  rather than a neutral one. Each option carries a `label` (the one or two characters shown)
+  AND a `name` (what a screen reader says) — a two-letter cell announces as nonsense, and seven
+  of them in a register are told apart only by voice. Budget the table column with
+  `toggleStripWidth(n)`, never a guess: a guessed column is one the fit sheds for the wrong
+  reason. Selected wears `chipSurfaceStyle`'s doubled dark EDGE, never a brand ground — a ground
+  is the row's language and this is a control, and seven filled cells per row made the screen's
+  one primary button the twenty-third copy of its own ground.
+  **`variant="mark"`** drops the letters for a bare square (filled = on) — for a COLUMN of strips
+  whose positions a header names once, which is what `Timetable` does; `current` tints the cell
+  of the position the reader stands in (today). `TOGGLE_STRIP_CELL_WIDTH` / `_GAP` are the
+  geometry a header lays its labels on.
+- **`timetable`** — `Timetable`: slots down the side, a FIXED repeating axis across the top, a
+  mark wherever a slot is on — a departure board (time × weekday), a shift roster, a lane's
+  opening hours. `slots` are the positions (`label` shown once in the header, `name` for the
+  cells' announcement), `current` is today's column (tinted, `aria-current="date"`), `rows` carry
+  a `time`, the `active` positions, a `subject` node (put the identity mark here), and optionally
+  `status`, `trailing` (an `ActionMenu`), and `detail` + `expanded` + `onPress` — the row's time and
+  subject are TEXT and edit in the expansion, since a timetable is read daily and changed a few
+  times a month; the pattern is the one thing edited in place. Not `CalendarView`: nothing has a
+  DATE, so there is no week to page to and no duration to draw. Not a `Table` of `ToggleStrip`s
+  with letters in every cell — that names the axis on every row.
 - **`checkbox`** — `Checkbox`: the bare square check control. Bare means UNLABELLED — reach for
   `CheckboxInput` unless something else already names it (a table's select-all, a row's
   leading slot). A square means CHOSEN; a ring means DONE, and spending the wrong one teaches a
@@ -1309,6 +1364,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the next click produces; hovering backwards from the start previews just as well.
 - **`date_filter`** — `DateFilter`: the date+time period filter panel — presets
   (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
+  The presets run day → week → month → quarter → year (`today`, `yesterday`, `tomorrow`,
+  `this_week`, `this_month`, `last_month`, `this_quarter`, `last_quarter`, `this_year`,
+  `last_year`), shortest grain first, so a reader scans past the days to the grain they mean.
   **Every preset SETS a range** — the list holds no mode and no null case, so a hand-picked
   range selects nothing. The
   presets are a `listbox` of `MenuButton` options: selection is the kit's `zinc.100` row
@@ -1321,7 +1379,38 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   renders it as a single date). Both bounds always show, so a half-picked range names the
   end that is still open.
 - **`date_range_filter_field`** — `DateRangeFilterField`: the register's period filter field
-  (presets + footer + time-segment a11y; localized via the `dateRange` locale slice).
+  (presets + footer + time-segment a11y; localized via the `dateRange` locale slice). **A range
+  that IS a whole period reads as that period** on the trigger — a whole month "Tháng 9 năm
+  2026", a whole quarter "Quý 3 năm 2026", a whole year "2026", one day one date; only a range
+  that is no period falls back to a date pair. That is what lets one field serve a dashboard
+  that lives in period rhythm, so never put a grain `SegmentedControl` beside it. For a
+  surface keyed by a whole MONTH — a plan, a roster — reach for `month_stepper` instead: a
+  month-keyed record cannot take "the 3rd to the 19th", so a range field offers moves that do
+  not exist.
+- **`date_filter_presets`** — `PRESET_IDS` / `getPresetValue(id, now)` / **`previousPeriod(value)`** /
+  **`periodToDate(value, now)`**;
+  the panel's range math, React-free and computed off an INJECTED `now` so a host can resolve or
+  compare a period without rendering anything. `previousPeriod` is the comparator a report means
+  by "so với kỳ trước": a whole calendar month, quarter or year steps back one WHOLE period
+  (February against March is 28 days against 31 — sliding a 31-day window back would compare
+  March against three days of January), any other complete range steps back by its own length
+  ending the day before it starts, and an open range returns `null` because it names no period.
+  Bounds come back day-aligned and untimed, like a preset's. Feed the result to the same query
+  the selected range feeds and show the delta ON the figure — never as a second control beside
+  the field. `periodToDate` is what a report keyed by a period actually reads: while the period
+  is still RUNNING it cuts both sides to the days elapsed — the selection ending today, the
+  comparator cut to the same count from its own first day and clamped to that period's end — and
+  reports `running` / `elapsedDays` / `totalDays` for the caption. Reach for it over a bare
+  `previousPeriod` on any figure the reader may open mid-period, or six days of this month get
+  compared against a whole month and the headline states a collapse that never happened.
+  → [composition.md §"Period filters for time-constrained data"](./composition.md).
+- **`month_stepper`** — `MonthStepper`: ‹ Tháng 9 năm 2026 › — `value` (any day of the month, as
+  `yyyy-MM-dd`), `onChange` (always the month's first day), `max` / `min` (the last / first
+  month that may be stepped INTO — pass this month on a surface about what has happened, or
+  the reader walks into a month nobody has planned), `labels` (the two arrows' names; the
+  `monthStepper` locale slice). The month name comes from `formatDate`'s `monthYear`.
+- **`month_math`** — `monthStart` / `shiftMonth`: the stepper's arithmetic on `yyyy-MM-dd`
+  strings, React-free, for a host that keys its own state by month.
 - **`time_picker`** — `TimePicker`: the time-of-day FIELD. The value on a pressable
   control (the bordered surface a `Select` uses, so it reads as pickable by the same
   shape as every other field that opens something), and `TimeColumns` behind it.
@@ -1513,8 +1602,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   control line while a
   one-line label still centers on it (both modes, no prop). The FIELD-ANNOTATION vocabulary (same
   names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
-  **`description`** = a fact / persistent guidance (muted), under the VALUE (stacked mode
-  mirrors the form order label, description, control); **`warning`** = a consequence to weigh
+  **`description`** = a fact / persistent guidance (muted), under the VALUE at BOTH widths —
+  stacked mode wears the form LOOK (a `FormField`-weight label) but keeps the RECORD's reading
+  order, label then value then annotation. Not the form ORDER: a form's description is guidance
+  you need BEFORE typing, a record's qualifies a value that already exists, so ahead of it the
+  reader gets "còn 116 ngày" before any date. Both modes render the shared `FieldAnnotations`
+  anatomy, so a fault says itself one way at both widths; **`warning`** = a consequence to weigh
   before acting (amber, announced); **`error`** = field-level failure under the value, danger +
   alert semantics (the `Inline*` editors already render their own transient save errors — don't
   wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
@@ -1582,7 +1675,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   rows), `LedgerTotal` = the divider-set emphasized close with `zeroLabel` for settled. **`meta` is a
   neutral QUALIFIER** (a date, a method) at caption weight — never a problem or a state: a
   caption is the wrong weight for something wanting action. A problem goes on the row
-  that can FIX it.
+  that can FIX it. **The label outranks the caption when the row runs out of width**: the
+  caption is sized off what the label and the figure leave, so it clips and is down to
+  nothing before the label gives up a word — and under a 320px ledger the row drops it
+  outright, since a caption clipped to two syllables is worth less than the space.
   **Pick the shape by what the statement IS**, because there are two and they read differently:
   - **`charges → total`** — `LedgerGroup`s, each **closed by its own sum** ("Charges" vs
     "Received"), giving three ascending rungs: row `sm/regular`, subtotal `sm/medium`, total
@@ -1732,10 +1828,28 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   A `description` passed as a NODE keeps its own leading — the component only sets it on the
   string branch, because forcing a line box on somebody else's subtree re-spaces content that
   may not be a line of text at all.
+  **`selected` outranks hover, and the two never paint the same grey.** The ladder is
+  `PressableRow`'s, verbatim — zinc-50 hovered, zinc-100 selected, zinc-200 pressed, one
+  neutral step apart with HOVER LIGHTER — so pointing at a neighbour cannot erase which row is
+  open. The two used to share `zinc-100`, which is invisible to every probe that reads a
+  RESTING screen and fails hardest on a navigation pane, where the selection is the only thing
+  tying a chooser to the detail it opened.
 - **`cell_stack`** — `CellStack`: a SUBJECT over one qualifying line, as a value primitive —
   the commonest cell in any register, and the shape most often hand-rolled wrong. `title` +
   `caption`, plus `weight` / `marked` / `size` / `color` / `tabular` / `align` /
-  `numberOfLines`.
+  `numberOfLines`. `leading` draws the identity mark (an `Avatar`, a `FileBadge`) before the
+  pair and owns the mark-to-text gap — the subject cell of a register is `CellStack leading`,
+  never a hand-rolled row of mark + stack; the column still budgets the mark's width. That gap
+  is exported as `LEADING_GAP`, the ONE number for mark-to-label anywhere the kit draws the pair
+  (`Matrix` and `StateMatrix` rows read it too) — a caller drawing its own pair reads it rather
+  than picking a number.
+  To RESERVE the caption line on a row that has nothing to say — which is how a column whose
+  cells are sometimes two lines keeps ONE first-line height down the page — pass a whitespace
+  string. `" "` is what everybody writes and the web renderer collapses it, so `CellStack`
+  normalises whitespace to a non-breaking space itself: without that the cell drops to one line
+  and its first line rides half a line above the rows that DID grow a caption, while the ROW
+  height, set by whichever sibling is two lines tall, never moves — so no spacing probe sees it.
+  (One app wrote the bare space twelve times.)
   It OWNS the three-part stacked-pair rule that [composition.md](./composition.md) §Typography
   states, so a call site never re-derives it: the caption's rung follows **what else already
   separates the pair** (a `medium` subject or a leading identity mark ⇒ the caption keeps body
@@ -1750,15 +1864,22 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   from the LINE BOX, so no margin and no gap appears anywhere to explain it and no spacing
   probe can see it — it is reported as "too far apart", never as its cause.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
-  (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
+  (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based). A column
+  whose header is a set of POSITIONS rather than a word passes `header` (a node) beside its
+  `label` — `Timetable`'s seven weekdays — never as a way to restyle a label.
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
   the width can't fit every column it hides columns by `TableColumn.priority` (**`1` = highest,
   as in P1/P2/P3** — the smallest number is the last to go; default = column order, rightmost
   first; column 0 — the identity — never drops), and
   below the two-column floor every row STACKS: the identity cell (column 0) HEADS the pile
   unlabelled — its column name would only restate the value — and each REMAINING cell renders
-  as a `DetailRow`-spread line (muted label left, value at the right edge — one vocabulary with
-  the drawer's detail rows), the lines sitting on the identity column's text edge, never under the checkbox;
+  as a `DetailRow` inside a `DetailTable`, so the field lines wear the FORM grammar: one fixed
+  label column, every value on ONE left edge, one vocabulary with the drawer's detail rows. The
+  lines sit on the identity column's text edge, never under the checkbox.
+  **A SPREAD row is right for one detail value and wrong for a register of them** — that is
+  what the narrow fork used to render, and repeated down twenty-one rows the same label string
+  measured seven distinct widths while its value started at a different x on every row, so the
+  fork had no value column at all. Invisible at desk width, where the fork never runs;
   the header band gives way, so sorting is a wide-container affordance. Rows carry TWO right-side slots: `action`
   (the primary CTA `Button` — register: in the trailing gutter; stacked: closes the content,
   right-aligned) and `trailing` (the ⋯ overflow — stays beside the identity on the top line).
@@ -1965,6 +2086,13 @@ a child of the app root, which every overlay's body-level box follows.
   and a PINNED one (a heading or summary above a scrolling list), which puts the exported
   `DRAWER_GUTTER` on the pinned part and on the scroller's `contentContainerStyle` rather than
   copying `20`.
+  **`position` + `onPrev`/`onNext` make it a RECORD navigator, and below the split width that
+  navigation drops to its own line** so the title keeps the full bar. The title names the record
+  — whose file is open — and it is the only element on that bar that CAN give way, since the
+  pager and the three icon buttons are all fixed widths; sharing one line at 375 cut a record's
+  own name at 206 of the 261px it needed while the chrome beside it sat whole. Pass a NODE title
+  (name over a qualifying line) and give its first line `lg` — that is the rung a string title
+  already takes, and at `md` a record reads as a peer of the section headings inside it.
 - **`modal`** — `Modal` + `ModalHeader` + `ModalBody` + `ModalFooter` — the full-bleed,
   edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog
   (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it
@@ -2053,10 +2181,19 @@ a child of the app root, which every overlay's body-level box follows.
   jump both re-measure the live DOM on web, so content loading in above a section never
   strands them. Reaching the END of the scroll activates the LAST key regardless of offsets —
   a final section shorter than the viewport never scrolls its top past the trigger line.
-  On NARROW containers
-  the rail becomes a PINNED bar naming the CURRENT section that opens a full-page
-  section-picker `Modal` — never a horizontal tab strip. Worked example:
+  Pair it with `SectionNav`, which draws both forms. Worked example:
   [`tpl_record`](../examples/tpl_record.tsx).
+- **`section_nav`** — `SectionNav`: the CHROME half of the outline, in its two forms — a RAIL
+  in a gutter, or a pinned bar naming the CURRENT section that opens the same list as a picker,
+  never a horizontal tab strip. `wide` picks the form and the CALLER measures its own container
+  for it (a window read gives a drawer the page's answer); `items` carry an `issue` dot, which is
+  what makes the outline answer "where is the problem" and not merely "where am I" and which is
+  ANNOUNCED as well as coloured, since it is the only thing marking the section; `back` leads
+  both forms, omitted where the container already has an exit. The active entry is `current`
+  (→ `aria-current`), never `selected` — a rail item is navigation, not listbox selection. The
+  picker anchors to the bar's own button, so it stays inside whatever container that bar sits in.
+  It owns neither the gutter the rail floats in, nor the width threshold, nor which sections are
+  in trouble.
 - **`scroll_to_bottom`** — `ScrollToBottom`: the floating jump-to-latest circle button for a
   chat/feed; ONLY the affordance — the caller owns positioning, visibility, and the actual
   scroll.
@@ -2095,7 +2232,24 @@ component rather than showing it at zero.
   it carries SHAPE (rising, spiky, flat) and no readable values, which is exactly what a
   register wants. Reach for a real chart the moment someone needs to read a value off it.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
-  `PieChart`: the canonical SVG chart set (no recharts). **A categorical axis prints as many
+  `PieChart`: the canonical SVG chart set (no recharts). `LineChart` takes EITHER `points`
+  (one line, its own `lineColor`) OR **`series: { key, label, color?, points }[]`** — never
+  both; the union makes passing two, or neither, a compile error. **Several series share ONE
+  y-scale**, which is the whole reason they are one chart: per-series scales would draw two
+  different quantities at the same height and the picture would state nothing. So a
+  COMPARISON — this period against last, this depot against that one — is two series on one
+  chart, never two charts side by side and never a control that swaps one for the other. The
+  x axis is shared too: position `i` is position `i` for every series, and the label comes
+  from whichever series reaches it, so a shorter series just ends early. **`legend` is on by
+  default once there is more than one series** (several unnamed lines are a picture nobody can
+  read) and off for a single one, which the card around it already names; the anatomy is the
+  same `LegendItem` every other chart annotates itself with. A series that names no `color`
+  takes the next one off the chart's own order, so four series are four distinguishable lines
+  with nothing to pass. Each named series is a `role="img"` carrying its label — a line
+  announces as nothing otherwise. The area wash and the per-reading markers are SINGLE-line
+  devices: stacked washes muddy into a colour belonging to no series, and four lines' markers
+  read as a field of dots, so several series draw bare with only their latest reading marked.
+  **A categorical axis prints as many
   labels as the track fits and thins the rest** — `LineChart` and `BarChart`'s vertical
   orientation both, because it is the axis's rule and not one chart's. It is anchored on the LAST
   position: the newest reading is the one a reader looks up, and anchoring there is what keeps the
@@ -2112,7 +2266,18 @@ component rather than showing it at zero.
   `Table` or the horizontal orientation, which gives each entity its own row and its own value
   column. `BarChart`'s horizontal orientation is one row per entity: **`labelWidth`**
   sizes the fixed label column (default 80, which fits a date and not a company name), and each
-  item's **`leading`** slot carries that entity's own mark ahead of its name.
+  item's **`leading`** slot carries that entity's own mark ahead of its name. **The value axis
+  reads the VALUES, not just their maximum, so an axis over whole things never prints a half** —
+  a series of counts gets whole-number gridlines however small its maximum, and only genuinely
+  fractional data gets fractional ones. Nothing to pass; it follows the data. **That axis thins
+  its labels too**, by the same rule the categorical one runs: its ticks are positioned by
+  fraction, so a narrow track does not crowd them, it STACKS them into an unreadable smudge, and
+  the tick marks stay because a 1px line collides with nothing. And **`labelWidth` is a REQUEST,
+  not a reservation**: the label and value columns are fixed, so in a narrow pane they would take
+  the whole width and leave every bar on its 2px floor — a row of identical stubs claiming every
+  entity is equal — so the label column gives way first and the plot keeps a readable minimum. A
+  trimmed name beside a real bar says more than a full name beside a stub; ask for the width the
+  names want and let the chart settle it.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it; `max: null` + `unboundedLabel` = the same meter with no bound.
 - **`progress_ring`** — `ProgressRing`: the same meter in a circle, and the ONLY circular one. Same API shape as the bar — a real `value`/`max` rather than a
@@ -2168,26 +2333,56 @@ component rather than showing it at zero.
   `onSelect`/`selectedKey` press-to-drill; the subset/drop-off sibling of
   `stacked_progress_bar`'s whole-split.
 - **`status_grid`** — `StatusGrid` + `StatusLegend`: the per-slot state grid (occupancy,
-  availability) and its legend.
+  availability) and its legend. A PILE of units with no axes — when the reader compares a
+  subject against a date, that is `state_matrix`.
+- **`state_matrix`** — `StateMatrix`: the CATEGORICAL cross-tab — `rows` (a subject each:
+  `label`, an identity `leading`, a pinned `total`, one cell per column), `columns` (dated
+  positions named ONCE in the header, `caption` for a second line, `current` for the one the
+  reader stands in — tinted down the grid, `aria-current`), `states` (key, label, palette
+  `color`, `shape` filled | hollow | dot | none — the legend derives from this list, so it can
+  never name a glyph the cells do not draw). A cell carries a `name` (a glyph announces as
+  nothing) and is a `button` only when `pressable` — `onPressCell(rowKey, colKey)` opens what
+  it has to say. The label block is PINNED outside the grid's own horizontal scroll. Not
+  `Matrix` (nothing here is a number; blank is "not due", never zero), not `Timetable` (a
+  timetable's positions are a dateless pattern and every mark is its own editor). Worked
+  example: `examples/tpl_attendance.tsx` §This week.
 - **`heatmap`** — `Heatmap`: density cross-tab — colour-only, no numbers; "where does it
   cluster".
 - **`matrix`** — `Matrix`: the PIVOT cross-tab — band-compound `Matrix` root +
   `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the
   cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) +
-  `Matrix.Legend`. Pick over `Heatmap` when the NUMBER and totals matter. Figures are
+  `Matrix.Legend`. Pick over `Heatmap` when the NUMBER and totals matter. **The heat is a RANK
+  scale behind numbers** (`heatScale`, default `rank` for `display="both"`, `linear` for a pure
+  heatmap): a linear map of value ÷ largest-cell spends the whole band on the one outlier every
+  real sheet has and leaves the rest inside a step the eye cannot resolve — a white grid with one
+  dark square. Pass `heatScale="linear"` only where the wash is the sole statement of MAGNITUDE.
+  `Matrix.Legend` samples the swatches out of that same scale rather than listing its own alphas,
+  so it cannot advertise a shade no cell can wear, and it renders nothing when no cell is painted.
+  **An empty interior cell says ZERO, not "no data"** — the grid has no third state, so a column
+  the source has not reached yet is the caller's to leave out. Figures are
   RIGHT-aligned — they are `tabular`, and centring them defeats the aligned column — and row
-  labels carry default ink, because a row's label is its identity, not chrome. **The totals column
+  labels carry default ink, because a row's label is its identity, not chrome. **A ROW may carry
+  a `leading` identity mark** (an `Avatar`, a status dot), drawn inside `rowLabelWidth` so it eats
+  the label's width rather than widening the column — which is how a matrix shows the same mark
+  the chart beside it shows. Rows only: a column is a period or a category and has no identity, so
+  `Matrix.Header` ignores `leading`, and the totals band carries no mark either. **The totals column
   takes one flex share like a data column**, because a total is the longest figure in its row: on a
   fixed width it is the FIRST thing to clip, and a clamped figure is whole in the DOM, so nothing
-  but a rendered screen sees it. `MATRIX_COL_GAP` is
-  exported for a caller budgeting
-  its own column widths. **A money matrix states its unit once** — in the card's
+  but a rendered screen sees it. **The grid owns its own horizontal scroll**: past the width where
+  every cell still meets its floor it scrolls rather than compressing, so a matrix with many columns
+  keeps its row labels and its totals column instead of squeezing the label to one glyph and pushing
+  the totals off the edge. That is the component's answer to a wide column axis — never the page
+  body, and never a caller's own wrapper. A date axis is still the caller's to BOUND: a sheet that
+  reaches past the last day with data buys empty columns that the ones with numbers then pay for.
+  `MATRIX_COL_GAP` is exported for a caller budgeting its own column widths. **A money matrix states its unit once** — in the card's
   `CardHeaderMeta`, cells bare (`formatCompactNumber`, not `formatMoney`), per
   [composition.md](./composition.md) §"A column states its unit ONCE": one currency glyph per cell
   is the same word fifty times and it is what pushes the totals column past its share.
 - **`matrix_totals`** — the data layer for `Matrix`: `matrixTotals` (the cross-tab
-  aggregation) + `MatrixAxisItem` / `MatrixCellRef` / `MatrixTotalsResult`; React-free, so a
-  KPI can be driven off the same numbers the grid shows.
+  aggregation) + `matrixHeatScale` (value → alpha, and the legend sampled from that same
+  function) + `MatrixAxisItem` (`key`, `label`, and a rows-only `leading` mark — a TYPE-only
+  node, so nothing here runs) / `MatrixCellRef` / `MatrixTotalsResult` / `MatrixHeatScale`;
+  React-free, so a KPI can be driven off the same numbers the grid shows.
 - **`highlight_segments`** — `splitHighlightSegments`: cuts a string into plain and
   highlighted runs for `Composer`'s `highlightRanges`. React-free: it feeds a mirror sitting
   behind a real text field, so a boundary off by one paints the tint adrift while everything
@@ -2764,7 +2959,11 @@ component rather than showing it at zero.
   `cafe` finds `Café` and `da giac` finds `Đa Giác`. ONE definition, and every list that filters
   uses it — two rules is not a style problem: a reader who found a row by typing unaccented text
   in one list and finds nothing in the next reads the second as missing data. `OptionList`,
-  `Combobox` and `Switcher` all match through it.
+  `Combobox` and `Switcher` all match through it. `codeKey(s)` / `codeMatches(query, ...fields)`:
+  the same fold for a CODE — a plate, a container number, a voucher number — dropping every
+  separator on both sides, so `14b031` and `031.02` both find `14B-031.02`; still a substring
+  test, never a subsequence one. A register searched by an identifier matches through this,
+  never through its own regex.
 - **`use_async_fn`** — `useAsyncFn`: wrap an async function into a manual-trigger mutation —
   `[run, {loading, data, error}]`, unmount-safe, the error lands in state AND rethrows; the
   pending-state engine for a submit/download/upload action.