@lotics/ui 46.2.0 → 46.8.0

package/AGENTS.md

@@ -18,7 +18,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [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; **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), and where a commit sits. |
-| [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. GATES that outrank every treatment question, then 11 probes each naming what to COLLECT and the SIGNATURE in the numbers. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [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 11 probes each naming what to COLLECT and the SIGNATURE in the numbers. 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. |
 
@@ -75,6 +75,30 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **The kit's fonts/colors/icons ARE the design system** — never a custom font, icon set, or
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
   → [composition.md §"Color discipline"](./docs/composition.md).
+- **An overlay paints in the order it was OPENED, and a scroller that swaps content opens the new
+  content at the top.** Compose overlays wherever you like — a `Dialog` written beside the
+  `Drawer` whose row opens it works, both ways round, and a `Dialog` opened from an open `Popover`
+  paints over its panel. An overlay of your OWN gets that for free by rendering its react-native
+  `Modal` **only while open** (`{open && <Modal visible …>}`); mounted while closed it takes its
+  body-level slot on the app's first paint and is then covered by anything opened later —
+  rendering and announcing perfectly, dead to every press. The z-index rungs beside the overlays
+  are published in `overlay_layer`, so never hand-pick a number to clear a Lotics overlay.
+  `DrawerScrollArea` / `DialogScrollArea` / `ModalBody` take a `scrollKey` and the routed
+  `Popover` takes the same seam off its route, so a swapped-in record opens at the top and the
+  reader returns to their place on the way back.
+  → [composition.md §"Canvas & content column"](./docs/composition.md)
+  → [catalog.md §"Overlays & navigation"](./docs/catalog.md)
+- **ONE VALUE, ONE RENDERING, inside one card — the chart draws the entity its table draws.**
+  A value's filter renders it the way its cell does, and the same rule reaches the chart beside
+  the table: `StackedBarRow` and `BarChartItem` take a `leading` slot for the entity's own mark.
+  A LEGEND row is the exception — its subject is a category, and the swatch is that identity.
+  → [composition.md §"A register that TRIAGES"](./docs/composition.md).
+- **A row says which side HOLDS; `numberOfLines` handles the side that gives way.** The clamp
+  brings its own `minWidth: 0` + `flexShrink: 1` (a clamp that cannot shrink cannot clamp), so
+  what a call site still has to state is `flexShrink: 0` on the figure or control that must stay
+  whole. Same law on a categorical axis: the LABELS thin to fit, the bars never do.
+  → [composition.md §"Typography"](./docs/composition.md),
+  [catalog.md §"Numbers & charts"](./docs/catalog.md).
 - **Hand-typed type is off-system — and it always lands too small.** Every run of language is
   `<Text size= weight= color=>` on the fixed rungs. **Grep the diff: `fontSize:` / `lineHeight:` /
   `letterSpacing:` outside `src/` is a bug.** → [composition.md §"Typography"](./docs/composition.md).
@@ -90,6 +114,19 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
   button. `Table`/`TableRow` already does this.
   → [composition.md §"Row actions are always-visible siblings"](./docs/composition.md).
+- **Piles you MOVE records between are a `Board`; bands of rows are not.** `Board` +
+  `BoardColumn` + `BoardCard` (`@lotics/ui/board`) — columns are one field's values, and a
+  card's `moves` drive a KEYBOARD menu first, with pointer drag layered on the same list.
+  `tpl_task_board` is a `DataGrid` of ROWS despite its name; a view built on it and labelled
+  Kanban is mislabelled.
+  → [catalog.md §"Records in PILES you move them between"](./docs/catalog.md),
+  [templates.md §"`Board` vs `tpl_task_board`"](./docs/templates.md).
+- **Money you are PRICING is `ChargeLines`; money you are READING is `Ledger`.** A charge is ONE
+  line — `quantity × unitPrice` reading across it and ENDING at the amount, never a derived figure
+  hung underneath — and the band's total lands on that same amount column. Below its fork width
+  the row takes two lines and the arithmetic RIGHT-ALIGNS to the band, so the amounts keep the
+  total's edge. → [catalog.md §"Money you are PRICING"](./docs/catalog.md),
+  [templates.md §"`tpl_money`"](./docs/templates.md).
 - **A fact every row needs is a COLUMN; a fact one row needs expands in place.** `TableRow`'s
   `detail` + `expanded` reveal the detail beneath the row; keep the drawer for a heavy form.
   → [composition.md §"No dead rows"](./docs/composition.md),

package/MIGRATION.md

@@ -4,6 +4,93 @@ 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.
 
+## 46.3.0
+
+**A `Text` with `numberOfLines` now declares `flexShrink: 1` + `minWidth: 0` for you.**
+A clamp that cannot shrink cannot clamp: on web a clamped `Text` is `white-space: nowrap`, so
+`min-width: auto` floors it at the WHOLE string; on native a `Text` is `flexShrink: 0`. Either way
+two clamped values on one row laid out at intrinsic width and ran off the frame. Both declarations
+now come with the clamp, and both are no-ops until a row actually overflows.
+
+Nothing's API changed, but **a layout default moved under every clamped `Text` in your app** — this
+is the one 46.3.0 change to re-check by looking. Two shapes are worth a pass:
+
+- A flex ROW where a clamped `Text` was the side that HELD and an unclamped sibling gave way. Both
+  can shrink now, so the wrong one may truncate.
+- A flex COLUMN with a bounded height (a fixed-height card, a `maxHeight` panel). `flexShrink` acts
+  on the MAIN axis, so a clamped `Text` that used to hold its height can now be compressed.
+
+The pair sits BEFORE your own `style`, so the site that must stay whole says so:
+
+```diff
+-<Text numberOfLines={1}>{amount}</Text>
++<Text numberOfLines={1} style={{ flexShrink: 0 }}>{amount}</Text>
+```
+
+That is how a figure keeps winning over its label. `minWidth` is overridden the same way
+(`style={{ minWidth: "auto" }}`) on the rare surface that wants the old min-content floor back.
+
+**An overlay of your OWN must render its react-native `Modal` only while it is OPEN.**
+`Dialog`, `Drawer`, `Modal` and `FileGalleryModal` now do — nothing in their API changed — and a
+hand-rolled overlay outside the kit has to do the same, or it loses to them:
+
+```diff
+-<Modal visible={open} onRequestClose={close} transparent>
+-  …
+-</Modal>
++{open && (
++  <Modal visible onRequestClose={close} transparent>
++    …
++  </Modal>
++)}
+```
+
+react-native-web appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders
+it, so an overlay mounted while closed takes its slot on the app's first paint and is then covered
+by any overlay opened later — while rendering, reading and announcing perfectly, with only its
+presses dead. Nothing is lost by the change: react-native-web renders a closed `Modal`'s children
+as `null` already, so only the empty portal div was being held. A takeover with
+`animationType="fade"` keeps its fade IN and now closes immediately, as `FileGalleryModal` always
+has; state that must survive a close belongs outside the `Modal` element either way.
+
+**The overlay z-index rungs are now published constants.** The numbers are unchanged for `Tooltip`
+and `Alert` (`10000`) and for a toast (`10001`); **the skip link moved `10001` → `10002`**, off the
+rung it was sharing with a toast. Read the rung instead of naming a number:
+
+```diff
+-import { View } from "react-native";
++import { NOTIFICATION_Z } from "@lotics/ui/overlay_layer";
+ …
+-  zIndex: 10001,
++  zIndex: NOTIFICATION_Z,
+```
+
+The full table is in `docs/catalog.md` § Overlays & navigation: `OVERLAY_Z` (every overlay, and
+`Popover`), `OVERLAY_Z_ABOVE` (tooltip/alert), `NOTIFICATION_Z` (a toast), `SKIP_LINK_Z`.
+
+**`PageContent`'s title band is now a `PageHeader`**, so the two stop drifting. `title`,
+`titleRight` and `description` are unchanged, and `PageHeader`'s `title` became optional — but the
+band's rhythm is now `PageHeader`'s everywhere: a description sits **8px** under the title (it was
+flush in `PageHeader`) and the band clears **16px** before the content (it was 24 in
+`PageContent`). Nothing to change; worth one look at a page shell you care about.
+
+**`useChangeSet`'s per-proposal default is a MAP, not a predicate.** `initial: "accepted"` /
+`"pending"` are unchanged.
+
+```diff
+-useChangeSet(ids, { initial: (id) => (overwrites.has(id) ? "rejected" : "accepted") })
++const initial = useMemo(
++  () => new Map(rows.filter((r) => r.overwrites).map((r) => [r.id, "rejected" as const])),
++  [rows],
++);
++useChangeSet(ids, { initial })
+```
+
+An id the map does not name arrives `accepted`, as before. A value rather than a function is what
+lets the default be an ordinary dependency: `status` and the group arrays derive from it together,
+so `status` changes identity whenever a decision does — which a screen that memoizes its rows on
+`review.status` needs, and which a predicate held out of the dependency lists could not give.
+
 ## 46.0.0
 
 **`AgentRun` / `AgentProgress` drop `stepsLabel`, and the `agentRun` locale slice drops `steps`.**

package/docs/ai_patterns.md

@@ -379,6 +379,17 @@ alignment and rhythm.
   `keptCount`/`total`/`settled`. `initial` defaults to **`accepted`** so an operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change
   genuinely deserves its own verdict, and gate the commit on `settled`.
+  - **A set that mixes KINDS defaults per kind: `initial` also takes a `Map<id, decision>`.** A
+    review usually holds both — filling a blank should arrive `accepted`, overwriting a value a
+    human already set should arrive `rejected`, so the destructive half is opt-in — and one
+    global default puts one of the two on the wrong footing. An id the map does not name arrives
+    `accepted`. Build it with a `useMemo` over the proposals your screen already holds, which is
+    what keeps the hook ignorant of what a proposal IS; a VALUE (rather than a predicate written
+    inline) is what lets `status` and the group arrays derive from it together, so `status`
+    changes identity the moment a decision moves and a screen memoizing its rows on it re-runs.
+    Deciding those rows by calling `reject()` from the result handler instead writes overrides
+    nobody made, and `undo` then hands the row back **accepted** — the destructive change
+    silently in, from the control that means "undo".
 
 ### The shapes, and what each one is
 

package/docs/catalog.md

@@ -151,8 +151,8 @@ reader must read WHOLE rather than recognise at a glance: a payment term, an add
 Above 1 the resting box RESERVES that many lines — the full editor height, not the height this
 particular value needs — so clicking in moves neither the field nor anything below it; Enter
 then inserts a newline and the value commits on blur.
-**`autoGrow`** makes that budget a MINIMUM and fits the value instead — see
-[data_entry.md §Open prose grows](./data_entry.md). **`link`** marks a URL value with
+**`autoGrow`** makes that budget a MINIMUM and fits the value instead, and a NOTE field always
+takes it — see [data_entry.md §Open prose grows](./data_entry.md). **`link`** marks a URL value with
 the navigation ink as a TREATMENT on the same single element — never a swapped-in
 `TextLink`, which would reintroduce the sub-pixel jump this field stays one
 `<input>` to avoid; pressing still edits, so pair it with an `Open` `InlineButton`
@@ -182,6 +182,33 @@ field rows lives in
 `DetailTable` + `DetailRow`; the record's identity band is `RecordSummary`; its money
 summary is `Ledger`.
 
+### Money you are PRICING — the charge band
+
+`ChargeLines` + `ChargeLine` (`@lotics/ui/charge_lines`) is the WRITE side of a record's money:
+what it charges, priced per line, closed by its own total. `Ledger` is the READ side of the same
+subject and the two are not interchangeable — a ledger has nothing to type into, and this has no
+notion of adjustments or of three sides.
+
+- **A charge is ONE line.** The arithmetic reads across it — `quantity × unitPrice`, ending at the
+  amount. Hanging the derived figure on a second line doubles every row's height and leaves the
+  answer in no column, so the total below closes nothing.
+- **One money column.** Quantity, unit price and amount all right-align and the total lands on the
+  amount column, so the band adds up by eye. The typed figures right-align through
+  `InlineNumberInput`'s `align`; without it a typed price and a derived one drift apart, which is
+  probe 6 in [reviewing.md](./reviewing.md).
+- **The total is the sum of what is on screen.** Never a figure computed off a different array: a
+  total that is not the sum of something visible is the one figure a reader cannot check.
+- **The row's verb sits in a fixed slot**, so the money column does not shift between a row that
+  can be removed and one that cannot. `locked` turns the editors into values for a settled charge.
+- **Below its fork width** the name takes its own line and the arithmetic sits under it — a
+  two-line row ON PURPOSE, measured on the band's own container because it lives in drawers as
+  often as on pages. The arithmetic RIGHT-ALIGNS to the band there: laid out from the left it
+  would land the amounts wherever the fixed slot widths happen to end, which coincides with the
+  closing total only when the container is exactly as wide as the row. The row's money verb moves
+  up to the name line in the fork, because the arithmetic line has no width to reserve for it.
+- **The field names are locale-wired** — `LoticsLocale.chargeLines` gives the quantity, unit-price
+  and amount editors their screen-reader names, each qualified by the charge it belongs to.
+
 ### Tasks, to-dos, phased work — ONE compound, two axes
 
 Anything a reader marks is `checklist` — `Checklist` + `ChecklistGroup` + `ChecklistItem`. Two
@@ -217,7 +244,9 @@ same record, so it follows automatically; for a surface whose SUBJECT is tasks s
 
 ### Tabular data — pick by SCALE + intent
 
-Two columnar shapes, and the choice is about data size:
+Two columnar shapes, and the choice is about data size. (A third shape divides the same records
+into **piles you move them between** — that is the board, below, and it is picked by INTENT, not
+by size.)
 
 - **High-volume register** (thousands+ you BROWSE) — `Table` (columns defined once; sortable
   headers via `SortHeader`; paired with `Pagination`) + rows that either open a `Drawer` to
@@ -253,6 +282,56 @@ Two columnar shapes, and the choice is about data size:
   grouping + pagination/infinite don't compose; use the register instead. Worked example:
   [`tpl_task_board`](../examples/tpl_task_board.tsx) (a `CheckCircle` leading).
 
+### Records in PILES you move them between — the column board
+
+`Board` + `BoardColumn` + `BoardCard` (`@lotics/ui/board`). Columns are the values of ONE
+field; cards are records; the act the shape exists for is sending a card to another column.
+Reach for it when the reader ADVANCES work and the pile sizes are themselves the report — not
+when they compare a row's measures (`DataGrid`) or browse thousands (`Table`).
+
+Worked example: [`tpl_board`](../examples/tpl_board.tsx).
+
+- **Order WITHIN a column is deliberately not offered.** The board moves a card BETWEEN piles;
+  it does not let you drag one above another in the same pile. Ordering that survives a reload
+  needs a persisted rank field on the record, and without one the reader arranges a pile, leaves,
+  and finds it rearranged — which is worse than never offering it. A pile is sorted by a column
+  the data already carries (a deadline, a priority), stated once. An earlier implementation shipped
+  an insert-at-index affordance with no rank behind it; it is gone.
+
+- **A column states its identity and its SIZE separately.** `heading` is a node — the component
+  the value's data role owns (`OptionBadge` for a select, `MemberChip` for a person) — and
+  `count` is a PROP. Formatted into the heading the number becomes part of the column's NAME.
+- **The move is keyboard-first.** A card's `moves` (`{ key, label }[]`) name its destinations,
+  and the card renders a focusable control whose menu items are those labels. Pointer drag is
+  layered on the SAME list: the grip drags, the drop resolves to the column under the pointer,
+  and a destination the menu would refuse is refused there too. Omit `moves` and the card
+  carries no move control — the honest rendering of a card that cannot go anywhere.
+- **The board owns its horizontal scroll**, so the page body never scrolls sideways and the
+  shape survives 375. **Columns grow and the page scrolls** — a bounded board height is a number
+  nobody can derive, which is how `height: 560` gets hand-picked into an app.
+- **A card's controls sit in the CARD's top-right corner, and they are always visible.** Pinned
+  to the card rather than carried by the title row, because a title that wraps to two lines
+  otherwise pushes them down and a control that moves with the length of the text beside it is one
+  the reader hunts for on every card. Always visible rather than revealed on hover: hover-reveal is
+  the exception a DENSE register earns, where forty controls at rest drown the rows — a board is
+  already sparse, and hiding the one act the shape exists for leaves a pointer user with a card
+  that looks inert. (Revealing on focus only is the same bug wearing a keyboard: the pointer, which
+  is how most people drive a board, never triggers it.)
+- **The card face states the record; the MOVE MENU states the destinations.** A badge on the card
+  repeating the column it already sits in prints one fact twice. The same badge in the menu is new
+  information — it names where the card would GO, in that column's own vocabulary — so the menu
+  takes each destination's heading node and cannot drift from the pile it points at.
+- **A card darkens under the pointer and its geometry does not move.** The wash is the card's own,
+  one neutral step; a border appearing on hover adds an edge to a surface already full of them.
+- **A drop must not open the record.** The browser ends a drag with a press on the row the grip
+  sits in, and that row is a door — so without a guard every drag dumps the reader into a detail
+  surface they never asked for. Suppress the press for the tick after a drop. The case that
+  reproduces it is a SHORT drag, where the release lands back inside the card it started in.
+- `BOARD_COLUMN_WIDTH` is the kit's column width. Do not re-pick it per app.
+- Not the same thing as [`tpl_task_board`](../examples/tpl_task_board.tsx), whose name says
+  columns and whose body is a `DataGrid` of ROWS — see
+  [templates.md §"`Board` vs `tpl_task_board`"](./templates.md).
+
 ### Numbers & charts
 
 `KPIStrip` (the dashboard stat band), `SummaryLine` (the light inline register/list summary
@@ -443,6 +522,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   numbers), `weight`, `color`, alignment, tabular numerals. **`leading="tight"`** sets the line
   box for a STACKED PAIR rather than for prose — a subject over its supporting line, a value over
   its annotation; see composition.md, which also covers the `gap` that goes with it.
+  **`numberOfLines`** clamps, and brings the `minWidth: 0` + `flexShrink: 1` that makes clamping
+  possible on a flex row — a clamp that cannot shrink cannot clamp. Both are no-ops until the row
+  overflows, and a `style` on the call site still wins, so a value that must never give way says
+  `flexShrink: 0` and keeps holding over its own label.
 - **`eyebrow`** — `Eyebrow`: the small quiet label above or beside a VALUE (`xs` muted medium) —
   a metric caption, a field name in a cell, an artifact tag. Takes `color` (for a VERDICT word
   like "Mismatch") and `align`, and deliberately takes no `size`, `weight` or `transform`:
@@ -702,16 +785,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band. `actions` puts page-level CTAs on
+- **`page_header`** — `PageHeader`: the page's title band, and the ONE place that band is
+  defined — `PageContent`'s `title`/`titleRight`/`description` render one of these rather than a
+  second copy of the row. `actions` puts page-level CTAs on
   the title row (right-aligned) and `trailing` puts a control immediately AFTER the title;
   `left`/`right` form a separate nav row above. Split `trailing` from `actions` by what the
   control acts on: `actions` do something to the page's CONTENT (create, sort, export),
   `trailing` changes what is AROUND it (a side-panel toggle, a view switch). A panel toggle
   filed under `actions` reads as a peer of "create one of these". Under a title too long for
   the row the TITLE gives way and wraps while `trailing`
-  and `actions` keep their width.
+  and `actions` keep their width. **The band owns the space under itself** — 16px, whether it
+  is rendered on a hand-rolled screen or by `PageContent`; a shell adds nothing after it, or
+  the same band closes on two different rhythms depending on which shell a screen picked.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
+  region — a centred column with optional `title`/`titleRight`/`description` (which render a
+  `PageHeader`, so the band's row law and rhythm have one home), `header`/`footer`
   slots and `fullscreen`. **Reach for it before hand-rolling a screen shell.** Its side
   padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
   genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
@@ -1145,7 +1233,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   a list too small for its own row.
   Pass `actions` UNCONDITIONALLY and `disabled` the verb when it has nothing to act on: a slot
   that appears once the value is non-empty resizes the field as the user types.
-- **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
+- **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units, `align="right"`
+  to put the RESTING figure on its slot's far edge so a typed money column shares one edge —
+  data_entry.md §Billing),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
   (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
   — locale field order, separator advances, Alt+ArrowDown floats the calendar; click still
@@ -1293,6 +1383,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   line box, so the band is the same height either way and a loading record's header does not
   move when the number lands. Still ONE number: a node is a stand-in for it, not a licence to
   put a control in the slot.
+- **`charge_lines`** — `ChargeLines` + `ChargeLine`: the editable money band — what a record
+  CHARGES, priced line by line, closed by its own total. The write side of `Ledger`'s subject,
+  and not interchangeable with it: a ledger has nothing to type into and this has no notion of
+  adjustments. A charge is ONE line — `quantity`/`unitPrice` derive the amount and the amount is
+  never typed; leave both out and the `amount` itself becomes the editor (`amountActions` puts a
+  list price one tap away, `unitPriceActions` a rate). Verbs sit BESIDE the field, never inside
+  it, and the row's own verb (`action`, usually removal) sits in a slot held open on every row —
+  both so the money column cannot move between rows. `extra` carries a second control belonging
+  to the charge (how it was paid); `warning` names a problem on the line that has it; `locked`
+  turns the editors into values for a settled band; `empty` speaks for a record nobody has priced
+  yet. `formatMoney` is the BAND's, so two lines cannot disagree about a currency, and the `total`
+  you pass must be the sum of the lines on screen. Below its fork width the row takes two lines
+  with the arithmetic right-aligned to the band — see § "Money you are PRICING" for the full
+  rules. Worked example: [`tpl_money`](../examples/tpl_money.tsx).
 - **`ledger`** — `Ledger` + `LedgerGroup` + `LedgerBasis` + `LedgerRow` + `LedgerTotal` — the
   record-level money list: every figure on ONE right-aligned tabular column, `peek` turns a row
   into a pressable door floating its particulars in an anchored popover (put links INSIDE the
@@ -1505,6 +1609,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`data_grid`** — `DataGrid` + `gridRowStyle`: the inline-managed grouped table (see
   [Tabular data](#tabular-data--pick-by-scale--intent)); `labels` localizes the sort-header
   a11y via `SortHeaderLabels`.
+- **`board`** — `Board` + `BoardColumn` + `BoardCard` + `BoardMove` + `BOARD_COLUMN_WIDTH`:
+  the column board — piles you MOVE records between (see
+  [Records in PILES](#records-in-piles-you-move-them-between--the-column-board)). The board
+  owns the horizontal scroll; a column takes a `heading` node, a `columnKey` and a `count`
+  prop; a card takes `moves` + `onMove`, which drive the keyboard menu AND the pointer drop.
+  Strings resolve through the `board` locale slice (`open` / `move` / `moveTo` / `empty`),
+  overridable per card with `openLabel` / `moveLabel` and per column with `emptyMessage`.
 - **`pagination`** — `Pagination` (+ `PaginationLabels`): the register's pager — a range and two
   arrows, no page index. ONE per register, ABOVE the rows on the `SummaryLine` row; its range is
   the register's count (pair with `Table` `counted`), and `onPageChange` owes a scroll reset the
@@ -1586,15 +1697,56 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Overlays & navigation
 
+**Every overlay paints in the order it was OPENED**, so mount them wherever composition wants — a
+`Dialog` written beside the `Drawer` whose row opens it is the ordinary shape and it works; a
+drawer opened from a dialog covers the dialog, which is the same rule the other way round. There
+is no layer prop and nothing at the call site has to know the tree order. It covers every
+body-level surface the kit has, `Popover` included: a `Dialog` or a file-preview `Modal` opened
+from an open popover paints OVER the panel that opened it. `Alert` and `Tooltip` stay above every
+overlay at any depth.
+
+**The one rule an overlay of your OWN has to follow: render the react-native `Modal` element only
+while it is open** (`{open && <Modal visible …>}`, or an early `return null`). react-native-web
+appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders it, so an overlay
+mounted while closed has already taken its slot before anything opened — and once two overlays tie
+at the same z-index, that slot is what decides. The symptom is nasty precisely because it is not
+visual: the covered surface renders, reads and announces perfectly, and only its presses do
+nothing. Nothing is lost by not mounting it — react-native-web renders a closed `Modal`'s children
+as `null` anyway, so only the empty portal div was ever being held, and anything that must survive
+a close (a router, a context, form state) belongs outside the `Modal` element regardless.
+
+**The rungs beside the overlays are a published contract** (`overlay_layer`), because a surface
+OUTSIDE the kit that has to clear a Lotics overlay cannot do it with a hand-picked literal:
+
+| z-index | what sits there |
+|---|---|
+| `9999` | every overlay, and `Popover` — `OVERLAY_Z` |
+| `10000` | `Tooltip`, `Alert` — `OVERLAY_Z_ABOVE` |
+| `10001` | a transient notification / toast — `NOTIFICATION_Z` |
+| `10002` | the skip link — `SKIP_LINK_Z` |
+
+Overlays all share one rung on purpose: DOM order settles the tie and DOM order is open order.
+`Popover` is on it too — it is no `Modal`, but it portals into the nearest `PortalHost`, so one
+opened inside an overlay is already inside that overlay's stacking context and a page-level one is
+a child of the app root, which every overlay's body-level box follows.
+
 - **`portal`** — `PortalHost` + `Portal`: the floating-content mount point; the app root
   needs ONE `PortalHost` or `Dialog`/`Popover`/`Tooltip`/`Alert`/`OptionList` cannot render.
 - **`dialog`** — `Dialog` (+ `DialogHeader`/`DialogHeaderTitle`/`DialogFooter`, `useDialog`,
   `useDialogNavigation`): the centered card over a scrim; BAKES a screen router in
-  (`<Dialog><Screen route="">…` — see `screen_router`).
+  (`<Dialog><Screen route="">…` — see `screen_router`). `DialogScrollArea` takes the same
+  **`scrollKey`** seam as `DrawerScrollArea` for a pane that swaps its body in place; a dialog
+  navigating between `Screen`s does not need it, because a stacked screen stays mounted and keeps
+  its own offset.
 - **`drawer`** — `Drawer` + `DrawerScrollArea` + `DrawerFooter`: the docked side panel with scrim; the
   register row's edit surface. ONE standard width (600px) — pass `width` only for a genuinely
   exceptional panel; full-width on small screens. `DrawerScrollArea` is the guttered content
-  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. It always
+  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. Give it a
+  **`scrollKey`** (the open content's identity — `scrollKey={openChild?.id}`, where the undefined
+  leg names the root content rather than opting out) on a drawer that SWAPS its body in place, so
+  the new content opens at the top and the previous one's offset returns on the way back — the seam
+  `DialogScrollArea` and `ModalBody` take too, and the one thing a React `key` on the scroller
+  cannot buy, since that resets the parent's place along with the child's. It always
   scrolls: a padded box around a `flex:1` scroller insets that scroller's viewport, ending the
   list short of the panel with the last row clipped. Two bodies skip it and take the `Drawer`'s
   bare slot: a FULL-BLEED one (a band spanning the panel, a record screen with its own gutters),
@@ -1605,7 +1757,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
   to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader
-  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned
+  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody (which takes the
+  **`scrollKey`** seam — a wizard stepping between steps swaps its body in place), a pinned
   ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a
   focused capture / multi-step wizard / a console the user steps INTO; pick Dialog when the
   surface is a card the user can see context around.
@@ -1631,11 +1784,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   The built-in scroller is **full-bleed horizontally** and re-insets its content by the same
   amount, so a scrolling body reaches the panel's real edges while the text stays on the
   same column the header and footer use. Nothing to opt into; `disableBodyScroll` consumers
-  (which own their scroll) are untouched.
+  (which own their scroll) are untouched. It also carries the **scroll seam** every scroller
+  that swaps its body in place takes — keyed on the routed popover's current route, with no prop
+  at call site, and inert in a popover that has no sub-screens.
 - **`popover_nav`** — `usePopoverNav` + `PopoverScreen` + `PopoverNavHeader` — the popover's
   built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes,
   `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the
-  root and screens render conditionally (unmounted when inactive — no scroll preservation),
+  root and screens render conditionally (unmounted when inactive, so a screen's own state does
+  not survive the round trip — the panel's SCROLL does: the screens share `PopoverContent`'s one
+  scroller, which takes the ROUTE as its seam key, so a sub-screen opens at the top with its
+  `PopoverNavHeader` in view and the root list's offset returns on the way back),
   `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack`
   (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover; route PATTERNS,
   `params`, and stacked-alive screens are `screen_router`'s job.
@@ -1661,6 +1819,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   content) — it is what `SectionHeadingTitle.info`/`CardHeaderTitle.info` render.
 - **`alert`** — `Alert` (+ `AlertButton`/`AlertOptions`): the blocking confirm —
   `Alert.alert(title, message, [{cancel}, {destructive}])`.
+- **`overlay_layer`** — `OVERLAY_Z` / `OVERLAY_Z_ABOVE` / `NOTIFICATION_Z` / `SKIP_LINK_Z`: the
+  ONE paint-order table for everything that reaches `document.body` (the rungs are in the table
+  above), and the file that states why open order works. Constants only — there is no layer to
+  render and nothing to claim; an overlay of your own gets its place by mounting its react-native
+  `Modal` only while it is open. Never write one of these numbers as a literal.
 - **`overlay_scope`** — `isOverlayScopeActive` / `pushOverlayScope` / `useOverlayScope`: the
   module-level open-overlay counter every overlay primitive reports into; the host's
   shortcut registry reads it synchronously to floor page-level shortcuts while any overlay
@@ -1715,11 +1878,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). `LineChart` prints as many x labels
-  as the track fits and thins the rest, anchored on the LAST point — the newest reading is the
-  one a reader looks up, and anchoring there is what keeps the spacing uniform. The first
-  point is labelled only when it clears the same distance, so a series whose length does not
-  divide evenly drops its opening label rather than crowding the one beside it.
+  `PieChart`: the canonical SVG chart set (no recharts). **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
+  spacing uniform; the first position is labelled only when it clears the same distance, so a
+  series whose length does not divide evenly drops its opening label rather than crowding the one
+  beside it. **The BARS never thin** — how many bars a card carries is a question about the data,
+  never about how wide a label happens to be, and an unlabelled bar keeps its slot so the row
+  above stays in line. **What thins is the whole annotation, label AND value together**, because a
+  bar's name and its figure are one reading: a number under an unnamed bar is a quantity of nothing
+  a reader can name, and the surviving annotation is widened across the room its dropped neighbours
+  vacated — room the figure needs as much as the name does. So a DENSE vertical `BarChart` (more
+  bars than `track ÷ 50px`: a 30-day daily series in a 600px card keeps roughly ten) shows the
+  figures only for the bars it labels. When every bar's number has to be readable, that is a
+  `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.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it.
 - **`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
@@ -1741,7 +1917,10 @@ component rather than showing it at zero.
   cost make-up per product line. `series` (key/label/colour, one hue family per dimension)
   drives a legend that is on by default; each `StackedBarRow` takes `label` + optional `meta`,
   a pre-formatted headline `value` with its `valueTone`, and a `caption` sentence, so colour is
-  never the only channel. Between `stacked_progress_bar` (one whole, own track) and `breakdown`
+  never the only channel. **`leading`** is the entity's own mark (`BrandMark`, `Avatar`, a status
+  dot), centred on the label's line box — a row's segment colours belong to the MEASURE, so unlike
+  a legend row this one carries no identity until you give it one, and a chart beside a table over
+  the same entities has to draw them the same way (composition.md § the register's own craft). Between `stacked_progress_bar` (one whole, own track) and `breakdown`
   (one whole + ranked share rows beneath it): reach here the moment there are SEVERAL wholes to
   compare.
 - **`waterfall_chart`** — `WaterfallChart`: the BRIDGE — an opening level, the signed steps
@@ -1780,9 +1959,15 @@ component rather than showing it at zero.
   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
   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. `MATRIX_COL_GAP` is
+  labels carry default ink, because a row's label is its identity, not chrome. **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.
+  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.
@@ -1993,6 +2178,10 @@ component rather than showing it at zero.
   NODE** as well as a string, because a second line can itself be carrying a change (a file
   being RECLASSIFIED is the same bytes filed differently — a `DiffValue` on the property); a
   node renders outside the muted single-line `Text`, which would clip it and fight its colour.
+  It also takes the **field annotations** (`description` / `warning` / `error`) — an expected
+  document is a value the reader supplies, so a row whose document FAILS says so on the row, in
+  the same block `DetailRow` renders; without it a fault could only be demoted into a callout
+  about the whole section, which says something different.
   Both `sm` variants share ONE beat (48px min + 6px vertical padding).
 - **`file_rows`** — `FileRows`: batteries-included file list — row press → built-in gallery
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
@@ -2205,7 +2394,14 @@ component rather than showing it at zero.
   `ids` is normally a memo over query rows — a new array every render, which is the
   `Maximum update depth exceeded` loop). `initial` defaults to `accepted` so the operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change deserves
-  its own verdict and gate the commit on `settled`.
+  its own verdict and gate the commit on `settled`. **`initial` also takes a
+  `ReadonlyMap<id, decision>`**, for a set that mixes kinds with different safe defaults —
+  filling a blank arrives `accepted`, overwriting a value a human already set arrives `rejected`,
+  so the destructive half is opt-in; an id the map does not name arrives `accepted`. Build it in a
+  `useMemo` over your own rows: it is a VALUE, so `status` and the groups derive from it together
+  and `status` changes identity whenever a decision does — which is what a screen memoizing its
+  rows on `status` needs. Do not reach for `reject()` in the result handler instead: that writes
+  overrides the operator never made, so `undo` hands the row back `accepted`.
 - **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
   (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
   the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires