@lotics/ui 46.2.0 → 46.8.0

package/docs/composition.md

@@ -8,6 +8,24 @@ full worked-example screens ship as source in `examples/tpl_*.tsx` (picked by jo
 [templates](./templates.md)). Every rule here is enforced by the primitives' defaults; fighting
 them produces off-system UI.
 
+**Arrived here because a screen LOOKS wrong?** The visual law sits in the last fifth of this file,
+behind the structural law — so the sections that answer that complaint are listed here rather than
+found by reading forward:
+
+| The report | The section |
+|---|---|
+| "it looks like a spreadsheet" | [The register's own craft](#the-registers-own-craft--what-it-looks-like-a-spreadsheet-actually-is) |
+| "it looks plain / flat / unfinished" | [Identity marks](#identity-marks--a-mark-that-is-the-same-on-every-row-carries-nothing) — a register whose rows open with text starts flat, and the symptom is reported as anything but the cause |
+| "it's bland" after every defect is fixed | [Character comes from the DATA](#character-comes-from-the-data--the-answer-when-a-screen-reads-bland) |
+| colour, accent, type, density | [Color discipline](#color-discipline--solid--tint--ramp--one-accent) · [Where the accent goes](#where-the-accent-goes--where-you-are-and-nothing-else) · [Typography](#typography) · [Touch & whitespace](#touch--whitespace) |
+
+Those are the reports these sections were written to answer, in their own words — not the whole
+visual law, which is the rest of the file.
+
+**Reading them is not the same as checking them.** [reviewing.md](./reviewing.md) is how you find
+out whether a screen you built actually holds these — render, look, measure — and it belongs
+before a deploy rather than after a complaint.
+
 ## The form comes before the treatment
 
 **If the domain already has a standard shape, that is the answer — build it.** A parcel's journey
@@ -69,6 +87,28 @@ the subject into rows.
   the same left edge as the title above it and the actions below it. Never hand-pad inside one,
   and never hand-roll one: the three surfaces disagree on the number (24 / responsive / 20) and
   only the surface knows which it is.
+  - **ANY scroller whose body is SWAPPED opens the new content at the top.** Stated as a rule and
+    not as a count of the surfaces that happen to have one today: `ModalBody`,
+    `DialogScrollArea` and `DrawerScrollArea` each take a `scrollKey` — the content's identity (a
+    record id, a step name) — and the kit's routed `Popover` takes the same seam with no prop at
+    all, because its ROUTE already is that identity. A scroller you add that swaps its body joins
+    the rule rather than being added to a list. `scrollKey={openChild?.id}` is the right shape:
+    an ABSENT key names the root content, not an opt-out, so the offset comes back when the child
+    closes. Opting out needs no signal — a surface whose key never changes never scrolls. Without it the container keeps the offset it
+    was holding for content that no longer exists, so a swapped-in record opens part-way down
+    itself with its heading off-screen above — invisible until the first list long enough to
+    scroll, which is the same list that made the swap worth having. The key opens unseen content
+    at the top and restores the offset when it comes BACK, which is what a React `key` on the
+    scroll area cannot do: that rebuilds the container, resetting the parent's place along with
+    the child's. Omit it where the body is one thing, and inside a `Screen`-routed dialog, where
+    a stacked screen stays mounted and already keeps its own offset.
+- **Overlays paint in the order they were OPENED, and no call site has to know it.** Mount them
+  wherever composition wants — a `Dialog` sitting always-mounted beside the `Drawer` whose row
+  opens it is the ordinary shape, and it is the one that used to fail: the dialog claimed its DOM
+  slot on the app's first paint, the drawer landed after it, and the dialog then rendered
+  perfectly and read correctly with every control under the panel DEAD. Whatever opens last is on
+  top, both ways round, so a drawer opened from a dialog covers it too. `Alert` and `Tooltip` sit
+  above every overlay at any depth — they are ABOUT the surface under them.
   - **The responsive one is READ, never re-derived — `useDialogGutter()`, no argument.** Inside
     a `Dialog` that is what the header, the scroll area, the footer and any pane a caller drops
     in all call. The `Dialog` resolves `small ? 16 : 24` ONCE, off the SCREEN, and publishes it.
@@ -819,6 +859,14 @@ surfaces consult `pressSelectedText()` instead, so a release that ENDED a select
 open the record and throw that selection away. Only a real, non-empty selection suppresses: a
 swallowed ordinary click would leave the row impossible to open.
 
+**Every gesture that ends on a row owes the same guard.** Selection is one source; a DRAG that
+ends inside the row it started in is another, and the next one will not be on this list. A row
+carrying both a door and a gesture must suppress the press for that gesture's release — and the
+release is what to watch, not the movement: a long drag ends far from where it began and never
+reaches the door, so the case that reproduces the bug is the SHORT one. Suppress on the specific
+gesture having just finished, never by disabling the press while a gesture is possible, which
+takes the door away from every reader who was only ever going to click.
+
 Selection covers every value at once, so reach for **`CopyButton`** only where one value is copied
 often enough to earn a control (a phone number a rep dials, a reference quoted into a message) —
 and put it ON that value inside its cell, never in the row's trailing column, which has nothing to
@@ -829,7 +877,11 @@ unconditionally and let an empty `value` disable it, rather than revealing it on
 
 Pressing a PRIMARY entity row opens the record workspace in a `Drawer` with `onPrev`/`onNext`/
 `position` ("3/24") over the visible ordering (←/→ arrow keys are built in). Key the drawer body by
-record id so per-record state resets on step. Facts are `DetailRow`s; the commit bar is a
+record id so per-record state resets on step. A drawer that instead REPLACES its body with a child
+record — the shape where a row inside the panel opens a second record rather than stacking a
+second drawer — passes that id as `DrawerScrollArea`'s `scrollKey` (`scrollKey={openChild?.id}` —
+the undefined leg is the list's own identity), so the child opens at the top and the list keeps its
+place on the way back. Facts are `DetailRow`s; the commit bar is a
 `DrawerFooter` (a hairline-topped band pinned to the panel bottom — render it as the LAST child,
 after the scroll body; actions sit right, a leading `<Text style={{ flex: 1 }}>` hint pushes them
 there). The open row shows a `selected` highlight (and `marked` for a bulk-ticked row). `Peek` is
@@ -1318,6 +1370,15 @@ colours, same shapes. Re-rendering it as plain text makes the reader translate b
 presentations of one field, and the two drift the first time either side gains a value. This holds
 for every custom-rendered value, not just status.
 
+**The same rule reaches the CHART beside the table.** One entity, one rendering, everywhere inside
+one card: if the table's first cell carries the entity's mark (`BrandMark`, `Avatar`, a status
+dot), the chart's rows carry it too — `StackedBarRow` and `BarChartItem` each take a `leading`
+slot for exactly that, laid out on the label's own line box. It is worst where the mark carries
+most (a channel, a platform, a person), and the two ways out that are not the slot are both
+losses: dropping the mark from the table to match makes *both* halves anonymous, and hand-drawing
+the chart to get one slot loses the component. A LEGEND row is the exception and needs no slot —
+its subject is a category, and the colour swatch already is that category's identity.
+
 **Group by what implies a different ACTION, never by a category the reader can already see.**
 Bands like *Waiting on you* / *Gone quiet* / *Open* / *Closed* each name a different response, so
 the grouping tells the reader something no column does. Grouping by a value that is already a
@@ -1780,13 +1841,20 @@ complaint it was meant to fix, because a reader who cannot read a label reports
 cluttered rather than as small. Recede with INK, at the same rung. `xs` is for genuine meta (a
 timestamp, a count), not for a label that a person actually has to read.
 
-**A LABEL sharing a row with a flexible VALUE must be told which one gives way.** Two items in one
+**A LABEL sharing a row with a flexible VALUE must be told which one HOLDS.** Two items in one
 flex row, and whichever cannot shrink forces the other to. It is invisible wherever the values
 happen to fit, which is usually the width it was built at, and it appears the first time a real
-record carries a long one. Decide deliberately: `flexShrink: 0` on the one that must stay
-whole (a fixed-length key, a label), `flexShrink: 1` + `numberOfLines` on the one that may clip,
-and pick by which is still USEFUL truncated — `RC-2026-0…` is unusable, `(555) 384-7…` is still
-recognisably a phone number.
+record carries a long one. Say which one stays whole — `flexShrink: 0` on a fixed-length key, on a
+figure, on a control — and pick by which is still USEFUL truncated: `RC-2026-0…` is unusable,
+`(555) 384-7…` is still recognisably a phone number.
+
+The clipping half needs only **`numberOfLines`**, which now brings its own `minWidth: 0` +
+`flexShrink: 1`: a clamp that cannot shrink cannot clamp, so the prop that says "cut this to fit"
+is what makes it possible. (Neither platform gave it for free — 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`. A row of two clamped values laid out at intrinsic width and ran off the frame.)
+Both are no-ops until a row actually overflows, and a `style` on the call site still wins — which
+is how a figure keeps holding over its own label.
 
 
 

package/docs/data_entry.md

@@ -300,6 +300,13 @@ The box is drawn at the budget and the value simply exceeds it: no ellipsis, no
 scrollbar, nothing to scroll. So the test is not "is this field long" but **"who decides the
 length"** — the field, or whoever is typing.
 
+**One field kind answers that question the same way every time: the NOTE.** A remark, a comment,
+a "ghi chú", an internal note — whatever a surface calls the box a person types free prose into,
+its length is the author's by definition, so it takes `autoGrow` without the test being re-run.
+It is named here because the abstract test kept being answered wrong for it: a note reads as
+short (most are one line), so it gets the default budget, and the one entry that actually
+mattered — the sentence explaining the exception — is the one silently cut.
+
 **And it gets worse as the surface narrows**: a budget is a count of LINES and the wrap point
 moves, so the narrower column wraps the same value into more hidden lines. A fixed reserve
 verified on a wide screen is not verified.
@@ -341,6 +348,17 @@ on top would make inline fields the one control in the kit with a second hover l
 reader crossing a record surface would meet both. Open adds the 2px ring. A `disabled` editor rests FLAT and borderless
 automatically — the surface is the editability promise, and an inert field must not make it.
 
+**The surface is not the only promise, and dropping it alone makes things worse.** A select's
+chevron and a date field's calendar glyph each say "something opens here"; once the frame and the
+hover are gone, that glyph is the ONLY mark left calling the row a control, so a value you cannot
+change reads as an editable one that ignores the click. A disabled field therefore renders no
+trailing affordance either — what is left is plain text, which is what a read-only value is.
+The same applies to the PLACEHOLDER: "Choose a…" on an inert field invites an act that cannot
+happen, so a disabled empty field says what is true ("None recorded") instead of what to do.
+Check it by disabling one field in a stack and looking down the column — every field that cannot
+be edited should be indistinguishable from a static value, and one that still carries a glyph or
+an inviting placeholder is the odd one out.
+
 **`variant` decides how much of that frame shows AT REST — an axis of WEIGHT, not of use.**
 `"framed"` (default) keeps the surface visible: required wherever editable and static values MIX,
 because the frame is the only thing saying which values you can change. `"bare"` shows nothing at
@@ -423,6 +441,26 @@ surface look cluttered — not the number of rows.
 | More options, or long labels, or the value is set once and read after | **`InlineSelect`** | scales to any count; costs two presses (open, pick) and hides the alternatives until you do — put each option's gloss in `renderOptionContent`, where it is needed while CHOOSING rather than on every later read |
 | The choice IS the task — a wizard step, a short focused form | **`RadioPicker`** | full-width choices with their descriptions permanently visible. In a grid of many fields this is ~4 rows of height for one value; never use it as a row in a record's field table |
 
+**A chip may carry an ICON, and it earns one only when the set differs in KIND.** Payment
+methods, channels, document types — a glyph plus `iconColor` separates *the money is here* from
+*it is not* before the labels are read. On a set that differs in DEGREE (Low / Medium / High) the
+same glyphs are decoration every chip pays width for. Never icon-only: the label stays, because a
+chip that is a bare glyph has a value nobody can read aloud.
+
+**Appending a line to a list is create-then-refine too, even when the new line must pick its
+KIND first.** A dialog that exists only to choose one of N and press Save is three presses for one
+act, and it leaves the reader looking at a form instead of the list they were reading. Put the
+choice ON the add control — a `Popover` of the kinds not already present — and let the chosen line
+land in the list with its defaults, refined in place like any other row.
+
+Where that control sits follows the list's own shape: **at the END of the rows when the list is
+read in order** (a `DetailTable` of lines, where the next line is what comes after the last one and
+the section heading carries the section's identity, not a per-list verb), and **on the section
+heading when the list is a `Table`** (which already owns a header row and a toolbar for acts that
+are about the whole set). One primary either way — if the section already has a committing act,
+the add is secondary, because appending a rare line must not outrank the act the section exists
+for.
+
 **A choice that GATES the form is a fourth answer, and the answer is usually "don't ask".** The
 table above is for a choice that IS a value. A choice about how to proceed — which sign-in method,
 which import format, which template — is not a field at all, and putting it on its own screen in
@@ -730,8 +768,24 @@ line saying what's needed; the payment-method picker turns required the instant
 amount. Issuing a real e-invoice is irreversible → confirm in a `Dialog` (stage gate). A
 grand-total **receipt** validates first — surface the EXACT missing methods (`Alert.alert` listing
 each) rather than a vague "incomplete." A refundable **deposit** is its own card and its own
-receipt — never folded into the total due. Composition over `Card` + `NumberInput` + `Picker` +
-`Badge`; no new primitive. Worked example: `tpl_record`'s Billing section.
+receipt — never folded into the total due. Where the band's lines are PRICED — a quantity against
+a rate — that band is `ChargeLines` + `ChargeLine` (`@lotics/ui/charge_lines`), which owns the
+one-line charge, the two money columns and the closing total; hand-rolling it is what produced the
+defects listed in [catalog.md §"Money you are PRICING"](./catalog.md). Worked examples:
+`tpl_money`, and `tpl_record`'s Billing section.
+
+**An EDITABLE amount still owes the reader a money column.** An `Inline*` editor fills the value
+slot and left-aligns its text, while the figures derived from it — a line's extended amount, the
+total — right-align like money always does. Left alone that is three ink positions for three
+numbers the reader is meant to add up, and no width fixes it because the two are aligned on
+opposite edges. Give the editor a FIXED width and `align="right"` — the `Inline*` prop that moves
+the RESTING value onto its slot's far edge, which is the half a width alone cannot buy: the
+amounts you type form one column, the amounts the system computes form the next, and both close on
+the same edge as the total beneath them. Measure it by collecting the right edge of every money
+string on the surface — a correct one shows two values, not one per row. A one-tap verb beside the
+figure (a standard rate, a list price) is a THIRD edge and not a defect; what it must never do is
+sit INSIDE the editor in a money column, where it eats the field's width and slides the figure off
+the column its neighbours are on. In a form row whose value column grows, on the field is fine.
 
 ## Fee summary — `Ledger`
 

package/docs/reviewing.md

@@ -225,6 +225,17 @@ spacing distinguishes them.
   fixed neighbouring shade under the pointer. Watch for an opaque overlay hiding a themed ground.
 - **A prop's EFFECT must match its claim** — render each value and diff what actually moved
   against what the prop says it changes. The fix is in the component, never the caller.
+- **A prop with NO effect is invisible to that diff**, because every value renders the same
+  screen. It typechecks, it lints, the caller reads correctly, the docs describe it — and it does
+  nothing, sometimes for releases. Read it off the SOURCE instead of the screen: a name that
+  appears in the props interface and in the destructure and **nowhere else in the render** is
+  dead. Wire it, then cover it with a test that goes red when the render line is deleted — a
+  component test asserting the passed node reaches the output, since nothing about the type system
+  will ever notice. **Three shapes look dead and are not**, so check them before reporting: a rest
+  spread (`const { a, ...inline } = props`) forwards a prop without ever naming it; a renamed
+  destructure (`slices: chartData`) uses it under the new name; and a platform fallback file
+  deliberately ignores a prop its `.web` twin honours. Sweep a component's WHOLE prop list at
+  once — a verb prop that shipped dead usually has a twin on the sibling field, dead the same way.
 - **Measure a component against ITSELF under each optional prop** that should not change size — a
   file row measured 37px static and 49px with an `onPress`, because only the pressable variant
   carried the padding its wash needed. Same for a slot that may be empty.
@@ -240,6 +251,29 @@ spacing distinguishes them.
   become double-corrections the moment the row is right. Two exceptions are legitimate: a
   self-contained overlay has nothing to align with, and an indent something VISIBLE occupies (a
   checkbox, an ordinal, a mark) is explained.
+- **A number you can EDIT and a number you can only READ drift apart on a money column.** An
+  inline editor fills its slot and left-aligns; the figures derived from it right-align. Collect
+  the right edge of every money string on the surface — a sound one lands on TWO values (the typed
+  column, the computed one), a broken one lands on as many values as there are rows, and the
+  reader can no longer add the column up by eye. The band's TOTAL is part of the computed column
+  and must be counted; a one-tap verb beside a field (a standard rate) is a third edge and is not a
+  defect. **Re-run the probe at a width where the row FORKS to two lines** — a forked row is laid
+  out by different rules and can land its amounts on an edge the total is not on, which is the one
+  failure the wide measurement cannot see. Rule: data_entry.md §Billing.
+- **A derived result must END the expression it derives from.** Where a row spells out a
+  calculation — a quantity, an operator, a rate — collect the right edge of the RESULT and of the
+  last operand. Equal is sound; anything else makes the eye read the expression left-to-right and
+  then jump backwards to find its answer, and putting the result in a label/description slot is
+  the worst version (it lands at the START of the line). The near-miss has one cause worth naming:
+  the result was positioned by a HAND-ADDED width, and one term of the sum — usually the operator
+  glyph, whose width the font decides — was guessed. Give that glyph an explicit width and build
+  both offsets from the same named constants, or the two edges agree only at the font size you
+  happened to screenshot.
+- **A DISABLED control that still wears its affordance.** Query every field for
+  `aria-disabled="true"`, then ask what separates it from an editable neighbour. Frame gone but
+  chevron/calendar glyph still drawn, or an inviting placeholder ("Choose a…") on an inert field,
+  is a value that reads as editable and ignores the click — the complaint arrives as "I can't edit
+  this and I don't know why". Rule: data_entry.md §The editability affordance.
 - **A CENTRED child hides its own drift.** Centring puts a child's top at `(container − child)/2`,
   so a child whose size varies with DATA moves its own first line between instances while the
   container measures identical every time. It takes a container with SLACK to bite. Wherever a

package/docs/templates.md

@@ -40,10 +40,11 @@ composition grammar](./composition.md); the package index is [../AGENTS.md](../A
 | A guided sequence of physical tasks (scan, confirm, next) | `tpl_pick` |
 | Splitting one source amount across many targets | `tpl_allocate` |
 | A record's create/edit surface — also the settings shape | `tpl_record` |
-| A surface whose SUBJECT is tasks (the canonical task-list grammar) | `tpl_task_board` |
+| A surface whose SUBJECT is tasks, managed in a grid of live cells | `tpl_task_board` |
+| Advancing records between STAGES | `tpl_board` |
+| Records as CARDS in columns, moved between them — the column board | `Board` (`@lotics/ui/board`) |
 | One record HANDED between desks — stages that each own their controls | `tpl_record` (its Progress section) |
-| Financial statements | `tpl_statements` |
-| A scoped lookup report with export | `tpl_report` |
+| ONE record's money — what it charges, costs, bills and collects | `tpl_money` |
 | A week calendar + agenda | `tpl_calendar` |
 | An attendance desk | `tpl_attendance` |
 | Shift signup + staffing | `tpl_shifts` |
@@ -387,6 +388,13 @@ The corollaries, each of which a register is routinely missing:
 
 - **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
   RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows.
+  **Search is ALWAYS the leftmost control**, and the order after it is stated rather than left to
+  the author: search, then the scope the rest of the row filters WITHIN (a site, an account, a
+  period), then the facets. Search is the one control every register carries and the one a reader
+  reaches for without looking, so it holds the same spot on every screen in the product; a scope
+  `Select` placed before it moves the anchor per screen and costs the reader a scan each time.
+  This is the register's counterpart to the add-placement law — the position is the affordance,
+  and an author choosing it per screen is the defect.
 - **A sortable `Table`** — rows separated by their own height and the hover wash, with the one
   hairline under the column band. It sets no row height: the register's rhythm is the kit's. →
   [composition.md](./composition.md) §"The register's rhythm". The record's SUBJECT is the first
@@ -450,7 +458,9 @@ The corollaries, each of which a register is routinely missing:
     DRAFTS; it does not write. Every drafted record then renders in full — all four fields as
     they will be stored, each editable in place, a `DiffMark` per card, Keep/Drop via
     `useChangeSet` (`initial: "accepted"` — the operator drops the exceptions rather than
-    approving six identical records) — and ONE commit named for its outcome creates them. The
+    approving six identical records; a set that also OVERWRITES values a human set passes a
+    `Map<id, decision>` instead, so that half arrives dropped) — and ONE commit named for its outcome
+    creates them. The
     manual form beside it skips all of that and saves direct. Only the DOCUMENT path needs the
     gate. The receipt still follows the write — it states the outcome, ROUTES, and carries the
     deterministic checks (a checksum, a count reconciliation).
@@ -890,7 +900,32 @@ a REGISTER (`tpl_item_list`) with a derived stage column — the same ladder mod
 so a row's badge and its filter bucket can never disagree. Rows that are structurally identical
 and tickable in any order are a `tpl_task_board`, not a pipeline.
 
-### `tpl_task_board` — the columns shape
+### `tpl_board` — the column board
+
+Columns are the STAGES of a pipeline, cards are records, and the only act is sending a card
+onward. Reach for it when the question is *"what is stuck, and what moves next?"* — the pile sizes
+are themselves the report, which is the thing a register at equal weight cannot say.
+
+- **The move is KEYBOARD-first.** Each card carries a control whose items name their destinations;
+  pointer drag is layered on that same declared list, so the two paths cannot disagree about what
+  is legal. An act reachable only by drag is unreachable for a keyboard user and untestable by a
+  driver.
+- **A column states its size as a PROP**, never formatted into its heading.
+- **The BOARD owns the horizontal scroll.** The page never does.
+- **A card is a DOOR** into the same record surface a register opens — the board is another way in,
+  never a second detail view.
+
+**Not [`tpl_task_board`](../examples/tpl_task_board.tsx)**, which is a `DataGrid` of ROWS with an
+inline editor in every cell: you ADVANCE work here and COMPARE-and-correct it there. The name is
+the trap — read the source.
+
+### `tpl_task_board` — the inline-managed task grid
+
+**It is not a column board, and the name is the trap.** This template is a `DataGrid`:
+collapsible BANDS OF ROWS with inline-editable cells. Nothing is arranged in columns of cards
+and nothing is dragged between them. A view built on it and labelled *Kanban* is mislabelled —
+for the column shape reach for **`Board`** (`@lotics/ui/board`), and read
+§"`Board` vs `tpl_task_board`" below before choosing.
 
 The manager's board: a search, group-by, filter toolbar over a grouped, sortable grid of
 LIVE editable cells — assignee/due/status/tags ALL via `Inline*` editors in **`variant="bare"`**
@@ -921,31 +956,59 @@ only real dimensions, ✕ clears to ungrouped (no "Nothing" option).
 manage in view (group/sort/filter/edit-in-place; it renders ALL rows). For thousands+ you
 BROWSE — that's `tpl_item_list`'s paginated register, not this.
 
-## Finance
-
-### `tpl_statements` — the statement grammar
-
-The income statement, balance sheet, and cash flow statement in ONE statement grammar:
-right-aligned column captions over fixed money columns, items indented under group headers, a
-hairline rule above every subtotal, the grand total DOUBLE-RULED (the accounting convention),
-negatives in accounting parentheses, per-cell currency-free (the meta line names the currency
-once), no bars, no charts — the numbers are the interface. Composed from `Text` + `Divider`
-alone: it teaches a grammar, not a component. The three statements TIE — net income flows
-into retained earnings, closing cash IS the balance sheet's cash, the loan repayment moves
-the debt line. Keep your books reconciled when adapting the data, or the screen teaches the
-wrong thing.
-
-### `tpl_report` — the scope-first lookup report
-
-Answer a question by SCOPING a dataset, not by browsing it. The scope bar leads: a header
-period (`DateRangeFilterField`) + ONE search key chosen from several mutually-exclusive
-dimensions (`SegmentedControl` swaps the matching picker; switching the key resets the
-value). That scope drives everything below — KPI totals → a row of pressable `Breakdown`
-facets (the long-tail one folds behind `maxRows`) → the paginated register of matching lines
-→ an Export button. Leave the search empty and the period alone gives the whole-period
-report. The fee / transaction / usage lookup desk.
-
-## Scheduling
+### `Board` vs `tpl_task_board` — the same data, two different jobs
+
+Both divide one field's values into piles. They are not variants of each other, and the
+discriminator is what the reader came to DO.
+
+- **`Board`** (`@lotics/ui/board`) when the job is to ADVANCE work — the pile sizes are the
+  report, and moving a card from one pile to the next is the act the screen exists for. Columns
+  are the field's values, cards are records, and each card carries a `moves` list naming its
+  destinations. That list is the keyboard path (a menu) AND the pointer path (a drag drops onto
+  the column under the pointer and is refused unless the destination is in the same list), so the
+  two can never offer different answers. Compare across cards is what it is BAD at: only what
+  fits on a card is visible, and nothing lines up.
+- **`tpl_task_board`** when the job is to COMPARE and EDIT — assignee against due date against
+  priority, twenty rows at a time, each cell an inline editor. Bands, not columns; the field is
+  changed in its own cell rather than by moving the row.
+
+Grouped rows answer "what is in each pile" and stop there. **A view labelled Kanban over bands
+of rows is the wrong FORM, not a smaller version of the right one** — the move is the whole
+shape, and a grid hands it back as a cell edit two screens from the pile it belongs to.
+
+## Money
+
+### `tpl_money` — THE money surface for one record
+
+Everything one record's money does, on one page, in the four shapes it takes — and the split that
+governs it: **`ChargeLines` is what you are PRICING and `Ledger` is what you are READING**, a band
+you type into versus a statement you check.
+
+- **Fees** — the DETAILED view, both directions (charge / cost), each fee carrying its party, due
+  date, supplier original and paid state. A register whose every row EXPANDS in place to its full
+  nine-field detail, one at a time: a child collection inside a record never docks a drawer,
+  because the page already IS the context the drawer would recreate. The section's Add rides the
+  heading row, where it does not move with the row count.
+- **Billing** — the invoice DOCUMENTS. Each invoice costs ONE line of chrome (its name, its
+  total, its reference once issued — the reference in a HELD-OPEN slot, or it drags the totals off
+  the column the statement below closes) over its own charge rows, with the issue act at the end
+  of what it commits. A problem rides the CHARGE ROW that has it, never a callout counting
+  offenders. The section closes on a three-sided `Ledger` — billed, less credited, less received —
+  and the refundable deposit, which is deliberately outside the total to collect.
+- **The charge bands** — `ChargeLines` in every shape: priced lines (`quantity × unitPrice`, the
+  amount never typed), flat amounts (the amount IS the editor, with the payment method riding the
+  charge's own line via `extra`), mixed kinds landing on one column, `locked` once collected, the
+  empty band, and the narrow fork — the SAME band rendered in a 360 box, because the fork is
+  measured on the band's container and not on the window.
+
+**The law the page is checked against:** every band lands on TWO money edges — the typed column
+and the amount column, with the band's total in the amount column. A one-tap verb (a standard
+rate) is not a column figure and may sit elsewhere. Verify by measuring: collect the right edge of
+every money string per band at a wide and a narrow width (→
+[reviewing.md](./reviewing.md), and [data_entry.md §Billing](./data_entry.md)).
+
+Its Fees and Billing sections are the same two sections `tpl_record` carries — read them there
+when you want them in the context of a whole record surface, and here when money is the subject.
 
 ### `tpl_calendar` — the week desk
 

package/docs/testing.md

@@ -46,6 +46,12 @@ Assert two things, not one: that the content appeared, and that it **dismisses**
 backdrop, so clicking the trigger a second time is often intercepted; click the
 backdrop or press `Escape`.
 
+Two overlays open at once stack by the order they were OPENED, so the newest one
+takes the press. If a driver reports `subtree intercepts pointer events` on a
+control of the overlay you just opened, that is a real defect and not this
+anatomy: check with `document.elementFromPoint` at the control's centre, which
+names whatever is actually on top.
+
 ## Custom pointer drag is not `dragTo`
 
 The calendar and gantt drags are built on `use_pointer_drag`, which listens for