@lotics/ui 23.1.1 → 24.0.0

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). 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, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (the `FilesEditor` COMPOUND — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer) |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows, master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [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). |
 
 ## Iron rules
@@ -39,6 +39,13 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   never a second chip. A chip beside a name reads as its PEER (a colored one reads louder),
   inverting the hierarchy the row is scanned by. →
   [composition.md §`Badge` is for STATUS only](./docs/composition.md).
+- **A countdown ANNOTATES its date field — never a trailing badge, and never hand-rolled.**
+  How far off a date is, what to call that number, and how loud it reads are three CONTRACTS:
+  invent them per screen and two registers disagree about when "urgent" starts and phrase "2
+  days late" four ways. Reach for `@lotics/ui/deadline` and spread `deadlineAnnotation` onto the
+  `DetailRow` — the three annotation slots carry the three urgency levels exactly. A binary
+  `error={overdue ? … }` is the tell: it makes a date due tomorrow read like one due in three
+  months. → [catalog.md §Dates & times](./docs/catalog.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.
 - **Hand-typed type is off-system — and it always lands too small.** Every run of language is
@@ -54,6 +61,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   (a CTA, ⋯, a checkbox, a `Link`) is a role-less `PressableRow` + a **`PressDoor`** sibling
   (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
   button. `Table`/`TableRow` already does this. → [composition.md](./docs/composition.md).
+- **A fact every row needs is a COLUMN; a fact one row needs expands in place.** Sending the
+  reader to a drawer for either loses the surrounding rows and charges a navigation to come
+  back — which is what makes scanning twenty records unaffordable. `TableRow`'s `detail` +
+  `expanded` reveal the detail beneath the row; keep the drawer for a heavy form.
+  → [catalog.md](./docs/catalog.md).
 - **A reference to another record is a FIELD** — it wears the inline editor's own resting
   surface, carries an **`InlineButton`** Open inside it, and PEEKS its facts on press (detach
   lives in the peek). Never its own Section, never a card, never the other record's fields as

package/MIGRATION.md

@@ -4,6 +4,43 @@ 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.
 
+## 24.0.0 — `TextLink` navigates, `TextButton` acts
+
+```tsx
+<TextLink onPress={selectAll}>Select all</TextLink>     // BEFORE
+<TextButton onPress={selectAll}>Select all</TextButton> // AFTER — same look, role=button
+```
+
+`TextLink` no longer takes `onPress`. It had three modes behind one name — `href` made it a link,
+`onPress` made it `role="button"`, neither made it plain underlined text — so one export was three
+components, and the button mode was nearly all of the use, including `OptionList` and `FilterChip`
+inside this kit.
+
+**Pick by what the press DOES, not by appearance.** Both are UNDERLINED — that is what marks a
+surface-less control interactive, and it is not optional (position is a learned convention, hover is
+absent on touch). What separates them is INK: blue means NAVIGATION, so `Link`/`TextLink` are blue
+and go somewhere while `TextButton` is zinc and acts. They differ in `role` too, which is what a
+screen reader announces and what keeps open-in-new-tab off a control that opens nothing.
+
+`TextButtonColor` is `default | danger` only — deliberately not `TextColor`. A `muted` text action
+would mute the one thing carrying the act's weight; use `Button color="muted"` when an act must be
+that quiet. `disabled` greys to zinc-400, drops the press and the hover wash, and announces
+`aria-disabled`. ONE size, no `icon`/`href`/`decoration`.
+
+Migration is mechanical: every `TextLink` with `onPress` becomes `TextButton`; every `TextLink` with
+`href` or with neither prop is unchanged. It is NOT visible — a migrated action keeps the same
+underlined neutral ink it had. Passing `size`, `icon`, or a `TextColor` other than `danger` is now a
+type error; drop them (`Text`'s default size is already `sm`, so the common `size="sm"` was
+redundant), and reach for `Button` when a verb needs a glyph or a real hit target.
+
+It also sharpens an existing rule: blue-600 means NAVIGATION specifically, not "interactive"
+generally — the underline carries interactive, so an ACTION stays zinc.
+
+A destructive text-weight act is `TextButton color="danger"`, which lands its ink on a text column
+by construction and keeps a 40px target via `hitSlop`. Do NOT reach for a fill-less `Button`
+(`danger-secondary`, `muted`) there: with no box, its optical edge is its ink, inset by its own
+padding, so it reads as indented against the labels it should line up with.
+
 ## 23.0.0 — the `Inline*` editors are WHITE, and `variant` is renamed
 
 ```tsx

package/docs/catalog.md

@@ -116,21 +116,26 @@ the `Task` compound owns the row — `TaskStatus` (a `CheckCircle`), `TaskTitle`
 `InlineTextInput`), `TaskActions`. **The row carries the TITLE; the fields a user can SET hang
 under it as `TaskSubRow`s** (`InlineDatePicker`/`InlineMemberSelect`/`InlineSelect`, each with
 its NAME beside it), never a `DetailTable` in a `TaskDetail`, which declares a grid of its own.
-The SAME composition serves a record's 5–8-task drawer checklist and a grouped desk board,
-because a sub-row reflows instead of being authored per surface; add `SuggestionChip` commons +
-`CaptureRow` for the checklist case. **A list you scan DOWN columns — the same four values
-compared across twenty rows — is a `Table`, not a `TaskList`.** And a record's own PROGRESS is
-not a checklist at all — that's `Pipeline` ([`tpl_record`](../examples/tpl_record.tsx) § Progress).
-See [`tpl_item_list`](../examples/tpl_item_list.tsx) for the checklist grammar, and
-[`tpl_task_board`](../examples/tpl_task_board.tsx) for columns.
+One composition serves a standalone task surface at any density — a flat list or a grouped desk
+board — because a sub-row reflows instead of being authored per surface; add `SuggestionChip`
+commons + `CaptureRow` for the capture case. **A list you scan DOWN columns — the same four values
+compared across twenty rows — is a `Table`, not a `TaskList`.**
+
+**A RECORD never carries a checklist.** Its work state is `Pipeline`
+([`tpl_record`](../examples/tpl_record.tsx) § Progress): a reached stage owns the facts it stamps,
+the LIVE stage alone carries its condition and the one act that leaves it. A per-desk checklist
+described the work but never said where the record SAT, and it put the CTA a section away from the
+state that gated it — so `tpl_record` replaced one with the pipeline, and a register's workspace
+drawer follows the same shape. `TaskList` is for a surface whose SUBJECT is tasks; see
+[`tpl_task_board`](../examples/tpl_task_board.tsx).
 
 ### Tabular data — pick by SCALE + intent
 
 Two columnar shapes, and the choice is about data size:
 
 - **High-volume register** (thousands+ you BROWSE) — `Table` (columns defined once; sortable
-  headers via `SortHeader`; paired with `Pagination`) + read-only rows that open a `Drawer`
-  to edit. It scales by PAGING — renders one page, never the whole set — so you FILTER +
+  headers via `SortHeader`; paired with `Pagination`) + rows that either open a `Drawer` to
+  edit or expand in place (`detail` + `expanded`) when the detail is read or light-edit. It scales by PAGING — renders one page, never the whole set — so you FILTER +
   search, you don't group. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx).
   Never an HTML `<table>` or a `.map` of rows. The register adapts to its container on its
   own — hides columns by `priority`, stacks rows below the two-column floor (see the `table`
@@ -456,7 +461,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Actions, links & menus
 
 - **`button`** — `Button`: the labelled action; `title` MANDATORY (it is the accessible
-  name), `color` = emphasis/risk.
+  name), `color` = emphasis/risk. A fill-less `Button` shows no box, so its optical
+  edge is its INK, inset by its padding — don't align one to a column of TEXT; that
+  is `TextButton`'s job.
 - **`icon_button`** — `IconButton`: the icon-only circular action (see
   [Actions](#actions)).
 - **`back_button`** — `BackButton`: the one go-back control — don't hand-roll it (an
@@ -468,10 +475,23 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   never an icon button beside unclickable prose.
 - **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
   `onPress` only (the consumer wires the opener).
-- **`text_link`** — `TextLink`: underlined text that's optionally an `onPress` action or an
-  `href` link (a real `<a>` on web — middle-click / open-in-new-tab work), or plain
-  underlined text to wrap in your own pressable; inherits every `Text` prop; the neutral
-  counterpart to the fixed-blue `Link`.
+- **`text_link`** — `TextLink`: underlined text that NAVIGATES — `href` renders a real
+  `<a>` on web (middle-click / open-in-new-tab work) and takes the blue navigation ink;
+  with no `href` it stays NEUTRAL: plain underlined text to wrap in your own pressable,
+  or a MARKER that a value leads somewhere (a record reference whose press opens a peek,
+  not a trip). `color` overrides either way; inherits every `Text` prop. It does NOT
+  act — that's `TextButton`.
+- **`text_button`** — `TextButton`: a low-chrome ACTION at text weight ("Select all",
+  "Clear", "Add stop") — the third rung of chrome after `Button` (40px surface) and
+  `InlineButton` (28px, filled, on a field's surface). **Underlined, in neutral ink**:
+  underline marks interactive, blue marks navigation — so `Link` goes somewhere and
+  this acts. Choose by what the press DOES. The underline is not optional (position is
+  a learned convention, hover is absent on touch). `TextButtonColor` is
+  `default | danger` only — `muted` would mute the thing carrying the act (use
+  `Button color="muted"`). `onPress` REQUIRED; `disabled` greys to zinc-400, drops the
+  press + wash, announces `aria-disabled`. Hover wash, focus ring and a 40px target
+  (32px box + `hitSlop`) come from `PressableHighlight` — a pressable `Text` has
+  none of them. ONE size, no icon (a verb needing a glyph is a `Button`).
 - **`chip`** — `Chip`: the generic pill — pressable when `onPress` (announces as a button;
   pass `accessibilityLabel` when children aren't self-describing text) + an
   absolutely-positioned dismiss ✕ sibling when `onDismiss` (its name = `dismissTooltip` ??
@@ -644,6 +664,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   **12- vs 24-hour derived from `locale`** — never from the browser, which is why this is not
   an `<input type="time">`. The value is always canonical 24-hour `"HH:mm"`; `locale` changes
   only what is displayed and typed.
+- **`deadline`** — the COUNTDOWN vocabulary, RN-free and pure: `daysUntil`, `countdownLabel`,
+  `deadlineTone` / `deadlineColor`, `deadlineAnnotation`, `nearestDeadline` (+ `DeadlineLabels`,
+  `DeadlineThresholds`, `Deadline`). Three contracts a screen must not invent for itself — how
+  far off a date is, what to CALL that number, and how loud it reads. `daysUntil` collapses both
+  ends to midnight because the vocabulary is day-granular: rounding the raw gap lands on the
+  wrong day whenever now and the deadline straddle noon (a 02:00 cut-off tomorrow reads "today";
+  one at 02:00 today reads "1 day overdue" 12 hours in). Wording comes from the `deadline` locale
+  slice; the 1-day/3-day tone lines are freight defaults and move per domain via
+  `DeadlineThresholds`. **`deadlineAnnotation` spreads onto the `DetailRow` holding the date** —
+  a deadline is a property OF that field, and the three annotation slots carry the three urgency
+  levels exactly (`error` / `warning` / `description`), so it never becomes a trailing badge
+  speaking a vocabulary the rest of the field grid does not. `nearestDeadline` returns an OVERDUE
+  milestone FIRST and expects the caller to pass only OPEN ones — done-ness is not knowable from
+  a date, and skipping past a missed cut-off is how a record silently stops reporting the failure.
+  Worked example: `tpl_record`'s Due rows.
 
 ### Inline editing & record surfaces
 
@@ -785,6 +820,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   divider-set emphasized close with `zeroLabel` for settled. The financial-statement grammar
   at record density; worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx)
   drawer.
+- **`reference_field`** — `ReferenceField`: a reference to ANOTHER RECORD, rendered as a
+  FIELD VALUE — the kit's inline-editor surface (so a pointer sits in the value column
+  like the editors above and below it), whose press opens a PEEK of that record's facts.
+  `name` + optional `code` + `facts` (label/value pairs) + `onOpen`/`openLabel` and an
+  optional `onRemove`. The verbs live INSIDE the peek, never on the field: `Open` goes to
+  the referenced record's own page, `Remove` detaches. The value is a `TextLink` marker
+  (underlined, neutral) because the press opens a summary rather than navigating. A
+  reference is a FIELD, not a section — one pointer to one other row never earns a heading
+  and a rail entry. Worked example: [`tpl_record`](../examples/tpl_record.tsx) § General
+  (customer) and its Transport parties.
 - **`peek`** — `Peek`: drill-down for inline references — press a name/id where it appears
   and get its details in an anchored popover, without leaving the screen; keep the content a
   summary with ONE action to the full record.
@@ -807,6 +852,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   On pressable rows dropped values stay one tap away — the row opens the record; a READ-ONLY
   register (rows without `onPress`) has no door, so give the columns it can't afford to lose
   a low `priority` (e.g. `priority: 1` — outlives its right-side neighbours).
+  **`detail` + `expanded` reveal a row's detail BENEATH it instead of navigating away.** A
+  register answers "which one"; the moment it cannot answer "and what about it" the reader is
+  sent to a drawer, loses the surrounding rows, and pays a navigation to come back — which is
+  what makes scanning twenty records unaffordable. Reach for it when the detail is read or
+  light-edit; a heavy form still deserves its own surface. `expanded` is CONTROLLED — how many
+  may be open at once is the caller's rule, so the component does not pick one. The detail
+  renders as a SIBLING of the press surface (a control inside it would otherwise be swallowed
+  by the row's own toggle), the row shows the open wash while it is out, and the door announces
+  `aria-expanded`. Prefer the columns first: a fact every row needs is a column, not a reason
+  to expand.
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
   `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
   `DataGrid` consumers drive.

package/docs/composition.md

@@ -335,7 +335,29 @@ record id so per-record state resets on step. Facts are `DetailRow`s; the commit
 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
 ONLY for secondary references — a glanceable summary popover on an inline reference (a customer
-name, a record id) with ONE action to the full record — never the primary row press.
+name, a record id) with ONE action to the full record — never the primary row press. That ONE
+action goes to the referenced record's own page; a local `Drawer` that re-shows the facts the peek
+just showed makes "Open" mean *read that again, wider*, and leaves the real record unreachable
+from the only control that promised it.
+
+**All of the above is the LIST SCREEN.** A CHILD COLLECTION inside a record page — fees, lines,
+stops, containers — does the opposite: the row **EXPANDS** (`TableRow` `detail` + `expanded`),
+never docks a drawer. A drawer's whole job is to supply a context the reader is missing, and on a
+record page they are already in it: docking one charges a navigation to see nine fields, takes the
+sibling rows away while they read, and charges again to come back. `expanded` is CONTROLLED, so
+pick the rule — for a ledger it is ONE at a time, because two open details push the next row off
+screen and a register that cannot be scanned has stopped being one. The boundary is the detail's
+weight, not its field count: read or light-edit (independent inline commits) expands, a real form
+with a submit and cross-field validation still earns its own surface.
+
+The expansion carries **EVERY** field, including the ones already in columns. Column cells are
+read-only, and `table_fit` tier 2 drops droppable columns on the explicit promise that a door
+reaches the dropped values — the expansion IS that door, so anything it omits is unreachable
+rather than merely inconvenient. `Table` does not expose its fit result, so this cannot be
+conditional. This is also the answer to "just add more columns": the fit budget is the MEASURED
+container, so past it the register drops columns silently instead of overflowing — widening does
+not reveal the extra fields, it hides them without saying so. And free text (a note) has no column
+width at any measure.
 
 ## Two work shapes, no side panels
 
@@ -422,7 +444,21 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   action `primary`; it sits at a different altitude than the form's one terminal commit.)
 - **Button labels carry no trailing ellipsis** ("Assign", not "Assign…"). **Button color is
   VALENCE/RISK, never category**: the ladder `muted < secondary < primary` is the emphasis axis;
-  `danger` (and its quieter `danger-secondary`) marks destructive — that's the whole axis. No
+  `danger` (and its quieter `danger-secondary`) marks destructive — that's the whole axis. A
+  fill-less `Button` (`danger-secondary`, `muted`, un-colored) shows no box, so its optical edge is
+  its INK, inset by its padding: **never align one to a column of TEXT** — it reads as indented
+  against every label starting on the true edge, and reaching for the filled tier to fix that buys
+  alignment with prominence, on what is usually the rarest act on the surface. A text-weight act is
+  `TextButton`, which lands its ink on the column by construction. Chrome has three rungs: `Button` (a 40px control with a
+  surface) → `InlineButton` (28px, filled, on a field's own surface) → `TextButton` (no surface,
+  sitting in a line of text). **UNDERLINE MARKS INTERACTIVE, BLUE MARKS NAVIGATION** — so
+  `Link`/`TextLink` are blue + underline and GO somewhere, `TextButton` is zinc + underline and
+  ACTS. Pick by what the press DOES. The underline is not optional on a surface-less control:
+  POSITION is a learned convention rather than an affordance (invisible to a first-time reader) and
+  hover is not one either (absent on touch, revealed only once you're already there). A tint is the
+  other way to say it — the Material/HIG answer — but blue is spoken for here and a second accent
+  for "actionable" would collide with one-accent-per-purpose. Never a `muted` text action: it mutes
+  the one thing carrying the act. No
   "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
   (colored `Text`), not the buttons.
 - **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". A create is `primary` and
@@ -493,6 +529,24 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   no rail entry — it is not a place you navigate to. Narrow, it collapses onto the same bar the
   sections use, on the RIGHT: sections are where you ARE, the discussion is what is being SAID,
   and the two poles keep the sides they hold on a wide screen.
+- **A record is ONE PAGE. A section is a place you SCROLL to, never a route you swap to.** The
+  rule above already assumes it — a section earns a POSITION in a top-to-bottom read, and the
+  discussion is docked precisely because a thing "parked at one position is unreachable from
+  every other". Routing the sections makes that true of every one of them. It is tempting on a
+  long record and it does not survive contact: each fix it needs rebuilds the whole-record view
+  in miniature — a dot to say which hidden section just changed, a page-band action to
+  re-surface an affordance some section had swallowed, an "everything" route that IS this page.
+  It also HIDES what it does not carry: a whole-record drop target advertised only inside the
+  files section does not exist from the eight destinations that are not it. And it charges
+  permanently — browser find reaches only the open section, two sections can never be read
+  together, and every cross-section check costs a click each way. A long record is a DENSITY
+  problem, and density is cuttable (a choice that took four rows, a group that restated the
+  title): **cut the sections, keep the page.** The rail stays — `useSectionNav` is a scroll-spy
+  and a jump, and it carries a `Badge variant="dot"` on any section holding a condition, which
+  is how the page says WHERE without a banner at the top saying it for one section at a time.
+  A cross-section TASK is not an argument for routing either: it belongs in an overlay that
+  spans the record (an extract review lists every proposed field, whatever section owns it),
+  which the rail then never has to serve.
 - **A VARIABLE-LENGTH, ORDERED fact is a `Sequence`, not a row of fields.** Before reaching for
   any layout lever, check the section is not carrying a MODELLING error: `Origin` /
   `Transfer point` / `Destination` looks like three fields and is actually one route — it cannot
@@ -618,7 +672,13 @@ selection washes).
 **TEXT never wears `solid()`** — the 500 is a FILL shade (dots, series). A status word/number uses
 `Text`'s valence tokens: `color="danger"` (red-900) / `"warning"` (amber-700) / `"success"`
 (emerald-700) — all AA on white. Map a dynamic `ColorName` to a token at the call site; hue nuance
-(rose vs orange) stays on `Badge`s. Links use `Link`/`TextLink` (blue-600), never `solid("blue")`.
+(rose vs orange) stays on `Badge`s.
+
+Links use `Link`/`TextLink` (blue-600), never `solid("blue")` — and blue-600 means NAVIGATION
+specifically, not "interactive" generally: the underline is what marks a surface-less control
+interactive (see the button ladder above), so a `TextButton` ACTS and stays zinc. `TextLink` takes
+the blue only when it has an `href`; as a passive marker on a value it stays neutral, because a
+press that opens a PEEK is not a trip.
 
 ## `Badge` is for STATUS only — everything else is text
 

package/docs/data_entry.md

@@ -191,6 +191,14 @@ A READ-ONLY value in the same column — a computed total, a system ID, a synced
 border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
 glance and the static value never reads as a disabled input.
 
+**Only in a grid that MIXES the two.** "Copies the editor box metrics" means it hard-sets
+`INLINE_CONTROL_HEIGHT` — worth paying to hold a column straight beside real editors, pure waste
+where there are none. In an ALL-static grid (a peek's facts, a summary popover) it reserves a 40px
+control band for a 20px value, and the row is the MAX of that box and the table's own band, so
+neither fix works alone: use plain `Text` for the value AND pass `DetailTable` a `minHeight` (28,
+`DetailRow`'s own default). Same test as `labelWidth` — a `DetailTable`'s defaults are the
+inline-control grid's; a grid that isn't one overrides both.
+
 ### Choosing a CHOICE control — by option count, not by taste
 
 A field whose value is one-of-N has three answers, and the wrong one is what makes a record
@@ -216,7 +224,17 @@ on a reference, `Call` on a phone): the act names the value, so it travels with
 instead of being paired back to a control at the page's right edge. Pass it UNCONDITIONALLY and
 `disabled` it when there is nothing to act on — a verb that appears once the value is non-empty
 resizes the field as the user types, which is the one thing an inline editor promises never to
-do. Anything that is not a verb — a status `Badge`, a unit ("kg"/"$", which belong IN the value
+do. **"About the value" is the whole test, and DEPARTURE fails it:** `Open`, on a field holding a
+reference to another record, is not an act on that value — it is leaving for a different record —
+and putting it on the surface hides two destinations behind one press area (the box opens a
+summary, the verb 8px away navigates). A reference's `Open` and `Remove` live inside its PEEK,
+which is what `LedgerRow` already enforces by IGNORING `reference` while `peek` is set. What marks
+the field as a reference instead of typed text is then the VALUE, not a verb: `TextLink` with
+neither `href` nor `onPress` — the kit's underline, non-interactive, so it sits inside the field's
+own press target without nesting a control. Not a `Badge` (STATUS only), and not `Link`'s fixed
+blue + `role="link"`, which promises navigation a peek does not perform.
+
+Anything that is not a verb — a status `Badge`, a unit ("kg"/"$", which belong IN the value
 via `InlineNumberInput format`) — composes into a row inside the VALUE cell, so it costs only the
 row that wants it. See the "General" section of `tpl_record`, which also reads top→bottom as a
 full record surface. Not every field is a same-height swap — a tag field, a status, or an

package/docs/templates.md

@@ -196,33 +196,27 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
   only](./composition.md)). A per-row action `Button` (here Print) is the row's primary action in
   the trailing column, `⋯` its overflow. A select-all band, footer totals + `Pagination`, and a
   `FloatingActionBar` carrying the bulk action while rows are ticked.
-- **A row press opens the PRODUCTION workspace `Drawer`**, which demonstrates the full
-  record-workspace anatomy section by section:
-  - **Details `DetailTable`** showing every inline field type — text, `InlineMemberSelect`,
-    dates incl. optional time, dot-select, money number, an `InlineSelect multi` tag field,
-    and `InlineStatic` + a System badge for read-only values. It is also the worked example of
-    where a VERB goes: Phone → Call and Due → Today are both `InlineButton`s in the field's
-    `actions` (on the surface, disabled while empty) — the date editor included, since a field
-    anchors its overlay to its own box; the System badge, not being a verb, sits beside its value.
-  - **Linked records** — the customer's other records as `ListItem`s (title + description at
-    the column edge, badge, amount, chevron); pressing one PUSHES an **editable** workspace
-    for that record inside the drawer via the hosted `ScreenRouter` — while `canGoBack` the
-    drawer header swaps to a back button + the pushed id and the ◀ ▶ sequencer hides; back
-    pops with scroll preserved.
-  - **Files** with its own Add CTA — `FileRows` CRUD via `pickFiles`, plus an EXPECTED
-    document as a ghost `FileRow placeholder` with a Request action. The section is wrapped in
-    a `<FileDropTarget … paste>`, so a drag anywhere onto it or a Ctrl/Cmd+V lands on the same
-    `addFiles` handler; a `SectionHeadingTitle description` names the three ways in.
-  - **Payment** — the `Ledger` (charge/received groups with sums, peekable fee rows,
-    `LedgerTotal`) + a Record-payment popover that appends a receipt.
-  - **Activity** — the CRM touch-log shape: optional outcome pills (`ChipGroup`,
-    tap-to-deselect) over a MULTILINE note (the note IS the record and the one requirement),
-    an always-visible optional follow-up `InlineDatePicker`, an "Attach files" secondary
-    (`pickFiles` → removable `FileThumbnailGrid` in the composer), and the primary Log button
-    saying WHY when disabled. Below, a labelled History `Timeline` of outcome-typed entries,
-    newest first — an entry's attachments ride its expandable details as a thumbnail grid
-    whose press opens the shared `FileGalleryModal`.
-  - A closing `DangerZone`.
+- **A row press opens the PRODUCTION workspace `Drawer`** — which RENDERS
+  [`tpl_record`](../examples/tpl_record.tsx) in `chrome="drawer"`, not a copy of it. Same
+  sections, same order, same rules, because it is the same component: `<TplRecord
+  chrome="drawer" code={row.id} />`. A hand-built second record surface is exactly how the two
+  drifted apart — a checklist on one side and a `Pipeline` on the other, a reference as a
+  section here and a field there — so the register owns the REGISTER and nothing else.
+  - What the chrome flag changes is only what a nested surface must not do: comments become the
+    LAST SECTION of the drawer's own scroller (a `Drawer` has no second gutter to dock them
+    into), and the back button is left to the Drawer's header. Everything else follows from
+    width — the layout measures its CONTAINER via `onLayout`, never the window, so the outline
+    rail, the docked discussion and the mirrored gutters collapse on their own, and the section
+    picker is a popover ANCHORED to its bar button rather than a full-page `Modal` that would
+    escape the drawer.
+  - **Linked records** still push an editable screen for that record inside the drawer via the
+    hosted `ScreenRouter` — while `canGoBack` the drawer header swaps to a back button + the
+    pushed id and the ◀ ▶ sequencer hides; back pops with scroll preserved.
+  - Two things this template no longer demonstrates, so look elsewhere: the drawer does NOT
+    write back to its row (settling a ledger used to flip the register's paid state live — the
+    drawer's money is the record's now), and the CRM call-log shape (outcome pills over a
+    multiline note, an outcome-typed history `Timeline`) went with the Activity section, which
+    the record surface has no counterpart for.
 - **The "Enter data" INTAKE FORK** (the New CTA) — AI FIRST, the form as fallback, one phased
   dialog. The whole register page is ALSO a `<FileDropTarget … paste>` (the whole-surface intake
   standard): a file dropped or Ctrl/Cmd+V pasted ANYWHERE on the register opens this same dialog
@@ -416,7 +410,9 @@ billing, and quick-capture templates. Top → bottom:
   map** (every section including Danger zone; subsections never join it) — headed by the
   bare circular `BackButton`; it scroll-spies the active section (`current={activeKey === key}`
   on each item — navigation, not selection), and on narrow containers becomes the pinned
-  current-section bar opening a section-picker `Modal` whose items carry the same `current`.
+  current-section bar opening a section-picker POPOVER, anchored to that bar's own button, whose
+  items carry the same `current`. Anchored, not a `Modal`: a modal escapes its container, so the
+  same surface hosted in a drawer would take the whole window over the register behind it.
 - **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and
   the rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
   `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead**