@lotics/ui 11.3.0 → 11.5.0

package/AGENTS.md

@@ -1,4 +1,4 @@
-# @lotics/ui — the UI reference
+# @lotics/ui — the UI reference index
 
 > **Upgrading to v11 from ≤10.x — the type scale was re-slotted.** The display sizes gained the
 > missing `##` step: `xl` is now 22/24 (section title), `xxl` is 28/32 (page/record title — the
@@ -8,1102 +8,43 @@
 > ALWAYS `##` (22/24), and disabled `Button`s fade their label to the zinc-400 disabled ink on
 > every variant.
 
-A React-Native-Web component kit (renders on web **and** native). This file is the design
-law + the "reach for what" guide. The **exact API** of any component is its source, which
-ships with the package: read `node_modules/@lotics/ui/src/<name>.tsx`. **Never guess a prop —
-open the file.** If the closest component lacks a capability, **extend it** (a platform change
-every app inherits), never inline a one-off `View`/`Text` rebuild — that forfeits the
-typeahead, async search, virtualization, and a11y the primitive already ships.
-
-- Import per module: `import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox"`.
-- Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `OptionList`) needs a
-  `PortalHost` at the app root.
-- RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
-  `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
-- Fonts: the app entry imports the Inter sheet ONCE — `import "@lotics/ui/fonts.css"` (400/500/600,
-  served by absolute URL so it resolves on every origin an app runs from) — or every `Text` falls
-  back to system fonts. File picking: `pickFiles` (`@lotics/ui/file_picker`) opens the browser
-  picker and resolves the chosen `File[]` — the imperative half behind every Add-file CTA.
-- i18n: most components are string-free. For the rest, set the language ONCE at the root with
-  **`LoticsLocaleProvider`** (`@lotics/ui/locale`, the sibling of `LoticsThemeProvider`) — wrap
-  `<LoticsLocaleProvider locale={vi}>` and every wired component picks up the pack, no per-instance
-  props. Shipped packs: `en` (default) and `vi` (one canonical Vietnamese translation, so apps don't
-  redefine — or drift on — strings). Resolution is **prop → provider locale → English default**, so a
-  per-instance `labels`/`clearLabel`/`selectAllLabel` still overrides for one-offs, and an un-wrapped
-  app stays English. Wired so far: `Pagination`, `SortHeader`/`Table.sortLabels`, `OptionList`
-  (+ `Select`/`Combobox` built on it), `FilterChip`, `Drawer`, `Confidence`, `RemainderMeter`,
-  `ChangeReview`/`ChangeReviewActions`, `DateRangeFilterField`/`DateFilter` (presets + footer +
-  time-segment a11y, one `dateRange` slice), `FormField` (the `optional` marker), and
-  `FileRows`/`FileGalleryModal`/`FilePreview` (one `gallery` slice: the ⋯ menu incl. remove+confirm,
-  the gallery chrome, and the preview captions). Adding a string to a wired component's `*Labels` forces
-  both packs in `locale.tsx` to fill it (compile error) — that's how the kit avoids a silent English
-  leak. Not yet on the provider (pass `labels` for now): calendar/gantt, the comment labels.
-
----
-
-## Reach by role — what exists
-
-Pick by capability, not by name. (→ the source file for the API.)
-
-- **Actions** — `Button` (labelled; `title` is MANDATORY; `color` = emphasis/risk),
-  `IconButton` (icon-ONLY — the circular affordance; an icon-only Button is a type error, so reach
-  here. `size` `lg` 40px / `md` 28px / `sm` 24px, the SAME `color` palette as Button, plus `loading`
-  and `elevated` (white fill + border + shadow, for a button sitting ON imagery — a tile's remove ✕,
-  an overlay's retry); needs `accessibilityLabel`/`tooltip`), `TextLink` (underlined text that's
-  OPTIONALLY an action (`onPress`) or a link (`href`) — or, with neither, plain underlined text you
-  drop in your own pressable like a table cell; colour via `color`; the go-to for Clear / Select all /
-  inline links), `Chip` (dismissible facet chip). A button is never a raw `Pressable`. For a link OUT
-  (a URL / record / document) use `Link` — fixed underline+blue + `role="link"`, the destination
-  signal; `TextLink` is the neutral, colour-configurable underlined link/action.
-- **Pick from a list** — `Picker` (native `<select>`, plain label-only single, native typeahead)
-  or `Select` (the rich one — custom-rendered options, single/multi, select-all). Search-as-you-type
-  / async / create-new → `Combobox`. A selectable card row → `CardSelectItem`. For a SELECT-FIELD
-  picker, render each option as its colored chip on `Select`
-  (`renderOptionContent={(o) => <OptionBadge value={o} />}`). `Select` opens the shared
-  `OptionList` body; `Combobox` is COMPOUND (`ComboboxInput` + `ComboboxContent`) over the same
-  `useOptionList` engine; `Picker` is the only one that's a native dropdown.
-- **Pick member(s)** — `MemberSelect` (a `Select` that renders each option as a `MemberChip`,
-  single or multi) — the ready member picker; pass it the roster (`members={useMembers().members}`).
-  Don't re-wire `Select` + `renderOptionContent` + a directory by hand. For an assignee FILTER that
-  also matches unassigned records, pass `unassignedLabel` → it prepends a muted "unassigned" option
-  (value `MEMBER_UNASSIGNED`), so you never hand-roll a mixed member+none `Select`. To edit a `select_member`
-  field IN PLACE (chip at rest → picker on click) use its inline-edit twin `InlineMemberSelect`.
-- **A person / member (display)** — `MemberChip` (avatar + name + optional secondary line) — the
-  ONE way to show a member inline: a picker option, an assignee, a `select_member` value. Pure:
-  resolve the member from your directory (`useMembers`) and pass `name` / `image`; never hand-roll
-  `Avatar` + `Text`. (The product's `MemberBadge` is just `memberId → MemberChip`; `MemberSelect`
-  renders these per option.)
-- **A select-field value** — `OptionBadge` (a stored `select` value as its CONFIGURED colored
-  badge) — never hand-map option-key → color. Feed it a resolved option (`useFieldOptions` for a
-  picker option, or `byKey(readSelect(cell)[0]?.key)` for a stored value); multi-select wraps to
-  one badge each; a missing/unknown color token degrades to neutral.
-- **Tags / multi-value chip box** — `Select multi` whose `renderSelected` returns a removable
-  `<Chip onDismiss={remove}>` (with `searchable` + `allowCustom`). The chip box is COMPOSED, not a
-  separate control — there's no `display` mode; `renderSelected` is the seam (see §Data entry).
-- **Text & form** — `TextInputField`, `NumberInput`, `SearchInput`; wrap with `FormField`;
-  `Checkbox`, `Switch`, `RadioPicker`; dates via `DatePicker` / `DateRangeFilterField`, times
-  via `TimePicker`.
-- **Edit a record's fields in place** — the `Inline*` family: `InlineTextInput` ·
-  `InlineNumberInput` · `InlineSelect` · `InlineMemberSelect` · `InlineDatePicker` ·
-  `InlineTimePicker`; a READ-ONLY field in that same column uses `InlineStatic` (matches the
-  editor box exactly, no input chrome, so it aligns pixel-for-pixel) (see §Data entry).
-- **Tasks / to-dos — pick by ALTITUDE.** A task-management PAGE (many tasks, grouping, filters,
-  expandable rows) is COMPOSITION — there is NO Task component (a Reminders row and a Linear
-  column-grid share almost nothing): `CheckCircle` + a struck `InlineTextInput` + your meta cells;
-  see `tpl_tasks` (quick list) and `tpl_task_board` (columns). A record's own small CHECKLIST
-  (the 5–8 tasks living in a drawer/section) is the `Checklist`/`ChecklistRow` compound +
-  `SuggestionChip` commons + `CaptureRow` — see `tpl_record`/`tpl_item_list`.
-- **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 + search, you don't
-    group. Worked example: `tpl_item_list`. Never an HTML `<table>` or a `.map` of rows.
-  - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view) — the
-    `DataGrid` primitive: a grouped, sortable grid whose cells are LIVE inline editors (ANY field — a
-    column is `{ key, label, width?, sortable?, cell: (item) => ReactNode }`, so `InlineMemberSelect` /
-    `InlineDatePicker` / `InlineNumberInput` / `InlineSelect` / a borderless `Select multi` for tags / colour-dot `OptionBadge`).
-    `DataGrid` owns the sortable header + collapsible grouped sections + aligned rows + an optional
-    per-row `leading` slot (a `CheckCircle`); YOU own the data, the sort/group/filter/collapse STATE
-    (`cycleSort` + `sortBy`, a `collapsed` Set), the toolbar (`SearchInput` + `FilterChip`s), and the
-    per-group add row (`renderGroupFooter`, aligned with the exported `gridRowStyle` + the column
-    widths). It renders ALL rows (no virtualization), so it's only for sets small enough to hold in
-    view — at 10k+ it lags, and grouping + pagination/infinite don't compose; use the register instead.
-    Worked example: `tpl_task_board` (a `CheckCircle` leading).
-- **Numbers & charts** — `KPIStrip` (the dashboard stat band) · `SummaryLine` (the light inline
-  register/list summary — below the toolbar, from the filtered rows) · `KPICard` / `Metric` (headline figures), `TrendChip`
-  (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG set — no
-  recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a plain sm
-  tabular count beside it — the cell/heading/peek-trigger meter; a caption floating above a
-  tiny bar reads misaligned) / `StackedProgressBar` / `StepProgress`, `Breakdown`
-  (a stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
-  "Show N more" toggle — `labels` to localize — so several facet cards align to one height in a row),
-  `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step conversion rate is the
-  HEADLINE (a bold aligned row across the top, the first stage = the 100% baseline), the count is the
-  supporting figure below — the Amplitude/Mixpanel convention, never pin the rate to the fill height.
-  `orientation` vertical columns | horizontal bars; pass `onSelect`+`selectedKey` to make the bars
-  press-to-drill (the selected stays solid, others dim — the caller renders the records). The
-  subset/drop-off sibling of `StackedProgressBar` — nested cohorts that shrink "calls → connected →
-  won", NOT a whole split across stages — that's `StackedProgressBar`),
-  `StatusGrid` + `StatusLegend`, `Heatmap` (density: colour-only, "where does it cluster"),
-  `Matrix` (the PIVOT cross-tab: the NUMBER in each cell — optionally a heat wash behind it — plus
-  row/column/grand totals; press a cell to drill).
-- **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
-  `CardFooter`), `Section` (the card-less twin of `Card`: bare gap-spaced region + `SectionHeading`/
-  `SectionHeadingTitle`/`SectionHeadingMeta`; no body component — children are the body;
-  ), `Subsection` (+ `SubsectionHeading`/
-  `SubsectionHeadingTitle` — the named group INSIDE a section, `###` lg-semibold title),
-  `SectionStack` (the flat page's content column — owns the fixed 56px beat + hairline between
-  top-level blocks), `SubsectionStack` (the same law one step tighter — fixed 24px beat +
-  hairline between a section's `Subsection` groups), `SectionCard`,
-  `PageHeader` /
-  `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`,
-  `DangerZone` (the destructive section — delete/archive — set apart at the bottom of a record/settings surface).
-- **Rows & registers** — `PressableRow` (THE register row; forwards its `ref`, so wrapping it in a `PopoverTrigger` anchors a row-triggered peek Popover — without the ref the trigger is unmeasurable and the popover renders off-screen), `ListItem`, `MenuButton`,
-  `MenuListItem`, `DetailRow` (label+value for drawers/peeks; optional `trailing` slot for a
-  right-side action/badge/unit), `ActionMenu` (⋯), `FloatingActionBar` (bulk-select bar).
-- **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`,
-  `Counter`), `Chip`.
-- **Overlays** — `Dialog` (centered card over a scrim), `Modal` (+ `ModalHeader`/`ModalBody`/
-  `ModalFooter` — a full-bleed, edge-to-edge takeover with NO scrim), `Drawer` (+ `DrawerFooter`),
-  `Popover`, `Tooltip`, `OptionList` (the searchable list body — host it in a `Popover`/`Dialog` for
-  a command palette), `Alert` (the blocking confirm).
-- **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
-  `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
-- **Files** — `FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below
-  it that swaps into a batch SELECT mode, full-screen preview, download/share, and Alert-confirmed
-  remove — the host only owns `files` + wires `onAdd`/`onRemove`; mirrors the frontend
-  `cell_files_editor`. Reach for this first for "manage a record's attachments"), `FileDropzone`,
-  `FileRows` (batteries-included file LIST: tap a row → built-in
-  full-screen gallery, with a per-row trailing ⋯ menu = Download · Open-external · Remove; the default "here are some files"
-  surface), `FileGrid` (the upload-aware grid: completed files + a live upload
-  queue in one surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own
-  the chrome), `FileThumbnail` / `FileThumbnailGrid`
-  (square tiles, display-only), `UploadingThumbnail` (the single in-flight tile FileGrid renders —
-  reach for it only when hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document
-  LINE — badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge / action
-  / remove; `onPress` makes the whole row a pressable door, `trailing` stays an independently-pressable
-  sibling; for checklists & readable lists), `FileBadge` (the two-tone type mark), `FilePreview` /
-  `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
-  `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
-- **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
-  sequence — done · current · upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow`
-  (allocation), `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
-  `Calendar`, `Gantt`, `comments_thread`.
-- **AI surfaces** — `Composer` (the adaptive command/chat composer — a compact pill when empty that
-  expands for long text + attachments; the surface that triggers agent work),
-  `AgentRun` (the live streaming work feed) + `AgentProgress` (its compact, floating, expandable
-  form — a composer's "working" state) + `Confidence`;
-  **`ChangeReview` — THE one review-before-apply surface, a COMPOUND family** (frame: `ChangeReview`
-  · `ChangeReviewHeader` · `ChangeReviewActions`; sections: `Change` · `ChangeLabel` ·
-  `ChangeSummary` · `ChangeReasoning`; the grammar: `ChangeFields` + `ChangeField` ·
-  `ChangeRecord` · `ChangeBand` + `ChangeValueInput`): adds, updates, removals, conflicts, whole
-  records, display-only findings are all compositions — see §AI workflows for the laws;
-  `Clarify` (the agent asks back — selectable `ChoiceList` options),
-  `Sources` (provenance chips for AI output — at review scale, `label={null}` slots the chips at a
-  section's bottom), `Finding` (one ranked insight from an AI check — localized severity word ·
-  title · detail · `Sources` chips · a `children` slot; **`FindingComparison`** is the
-  expected-vs-actual body: each disagreeing side a labeled row, the DELTA emphasized under a
-  hairline (localized "Difference") — quantities, totals, dates; a plain `metric` prop remains for
-  one-number findings. The children slot composes ANY visual result — a compact `Table` for
-  per-line detail (danger color on the offending cells), `ProgressBar` for
-  consumption-toward-a-cliff (free time, credit), dot `Badge`s for a present/missing checklist,
-  `Confidence` for judgment calls — the AI-page demos show each. Display-only — it informs the verdict the host records; `finding` slice).
-  See §AI workflows.
-
----
-
-## Data entry — which pattern for which job
-
-This is the most common thing to get right. Match the JOB to the pattern:
-
-| You're capturing… | Reach for | Why |
-|---|---|---|
-| an EXISTING record's fields | **Inline edit** (`Inline*`) | edit in place, no form mode |
-| a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
-| a RELATED record (pick or make) | **find-or-create** (`Combobox allowCustom`) | one control covers both |
-| REPEATING rows you build & revise | **line items** (create→preview→edit) | add / edit / remove, live totals |
-| CHARGES that bill onto documents | **billing** (`tpl_record` Billing section) | the invoice document is the unit |
-| a record's FEE/charge SUMMARY | **`Ledger`** (worked example: `tpl_item_list` drawer) | LedgerGroup (label + sum) → LedgerRow (label · meta · ONE right tabular money column; `peek` makes the row a door to its PARTICULARS in an anchored popover — references live inside the peek; `reference` = a trailing link on a non-peek row) → LedgerTotal (divider-set emphasized close, `zeroLabel` for the settled state). Pair with a Record-payment POPOVER that appends a receipt. No bars/charts |
-| a multi-value TAG field | **`Select multi`** (`renderSelected` → `Chip`) | chips composed, not a separate control |
-| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker`) | required single-select, one tap, every option visible |
-| a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
-| FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
-| a state TRANSITION mid-flow | **stage gate** (popover / dialog by weight) | right-sized friction |
-
-### Inline edit — the preferred way to edit an existing record
-When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
-form mode or a preview↔edit card — make each VALUE inline-editable: it reads as plain text,
-hover reveals its border (it's a field — no grey tint, no pencil that shifts), click swaps the input in **at the same height** (zero
-reflow, the whole point), and it commits on blur (Enter saves, Escape reverts) or via
-`controls="buttons"` (✓ primary / ✕). One per type — `InlineTextInput` · `InlineNumberInput`
-(`format` for currency/units) · `InlineSelect` (plain options OR `renderOptionContent`; floats an
-`OptionList` in a popover so the row never grows; the RESTING value renders like its option
-(`renderOptionContent` by default; `renderSelected` overrides) — a colored `OptionBadge`, not just a label) · `InlineMemberSelect` (a `MemberChip` at rest →
-member picker; the inline twin of `MemberSelect`; worked example: `tpl_record`'s "Sales owner" fact) · `InlineDatePicker` (`format="datetime"` for
-always-on time; `optionalTime` to let the user ADD/REMOVE a time — the value's own shape, date vs
-datetime, is the source of truth) · `InlineTimePicker` · `InlineTagSelect` (the MULTI member —
-a tag SET in the inline vocabulary: selected tags render as badges inside the standard chip,
-clicking floats a multi `OptionList` (checkbox rows), CLOSING commits the new set in one
-`onSave` — never a borderless `Select` posing as an inline field) — all
-on `useInlineEdit` + `InlineEditView` (custom inputs join via those). `onSave` is async: the
-saving spinner sits INSIDE the control (never a sibling — that reflows); an error shows inline
-without losing the edit. To let a value be UNSET (a diff-write CLEAR — unassign, remove a due
-date, drop a select), pass **`onClear`** to `InlineSelect` / `InlineMemberSelect` /
-`InlineDatePicker`. It surfaces through each popover's OWN clear affordance — `InlineSelect` renders
-a compact left-aligned "Clear" `Button` below the `OptionList` (only while a value is set);
-`InlineDatePicker` reuses the calendar's own footer "Clear" button. NOT a bolted-on sibling row: that
-can't reach the option list's active-highlight (so the last-hovered option stays lit) and would
-double the footer hairline;
-and never a persistent ✕ on the resting cell (noise on a dense board, and a pressable nested in the
-view's button trigger is invalid DOM). `onSave`'s `next` stays non-null so a caller opts in per field;
-the clear fires `onClear`, which writes `null` (the app workflow must ACCEPT null on that input — a
-`select`/`date`/`member` field clears on null). `InlineTagSelect` (multi) needs no `onClear` — an
-empty set is already a valid `onSave`. A STACK of rows lives in a `DetailTable` (label ·
-value · trailing laid out like a TABLE: `labelWidth` / `trailingWidth` /
-`minHeight` set ONCE on the parent, plus the 6px row gap the zinc-50 chips
-need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a
-trailing action/badge, so EVERY row reserves the column and one row's
-`Copy` button never makes its editor narrower than its neighbours'. An editor AT REST sits
-on a zinc-50 chip — THE editability affordance: users see what's editable without hovering; the
-picker-opening editors (`InlineSelect`/`InlineDatePicker`/`InlineTimePicker`) additionally carry a
-rest glyph (chevron / calendar / clock) marking them tappable pickers without hover — the
-touch-critical cue plain text/number fields don't get.
-`background="transparent"` opts a field out of the chip — for DENSE, uniformly-editable
-surfaces (a task list/board where EVERY cell edits: the chip repeated everywhere is noise and
-distinguishes nothing; hover/focus still reveal the input). Keep the chip wherever editable and
-static values MIX. A `disabled` editor rests FLAT automatically — the chip is the editability
-promise, and an inert field must not make it. A
-READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
-`InlineStatic`: it copies the editor box metrics exactly (height, padding, 1px transparent border)
-but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a glance
-and the static value never reads as a disabled input. To hang a right-side
-action/badge off a row, use `DetailRow`'s `trailing` slot (NOT for units — "kg"/"₫" belong IN the value via `InlineNumberInput format`) — see the "Details"
-`DetailTable` of `tpl_record`, which also reads top→bottom as a full record surface
-(header → fields → `DangerZone`). Not every field is a same-height swap — a tag field, a status, or an attachment grid
-edit in place too (below).
-
-### Fieldset form — fields lay out on a RESPONSIVE two-column grid
-Never hard-code columns, never 3-up. A fieldset is `flexDirection:row, flexWrap:wrap,
-columnGap:16`; each `FormField` declares an intrinsic width — `half` (`flexGrow:1,
-flexBasis:240`) or `full` (`flexGrow:1, flexBasis:"100%"`) — so two halves sit side-by-side on a
-wide card and stack on a narrow one with zero media queries. Pair short, related fields as halves
-(phone/email, qty/price); give long or singular values the full row (legal name, address, notes).
-Past two columns the label→field link breaks — MANY inputs means GROUPING into labeled fieldsets
-(each its own 2-up grid, `Divider` between), never a third column. `FormDatePicker`/`FormPicker`
-wrap their OWN `FormField` (and omit `style`) — for a grid cell use a bare `FormField style={half}`
-wrapping `DatePicker`/`Picker`.
-
-### Find-or-create — the `Combobox` family IS the control
-`Combobox` is COMPOUND: a root holds the DATA + behaviour (the shared `useOptionList` engine —
-`options`, `value`, `onValueChange`, `onSearchChange`, `allowCustom`, the per-row
-`getOptionDescription`/`renderOptionContent` so they're typed against the option `data`), and the
-parts render the CHROME, composed as children — never a render-prop pile:
-
-```tsx
-<Combobox options={hits} value={sel} onSearchChange={setQ} onValueChange={pick} allowCustom
-          customOptionLabel={(q) => `Create "${q}"`} getOptionDescription={(o) => o.data?.code}>
-  <ComboboxInput icon="search" clearable onClear={deselect} placeholder="Find or create…" />
-  <ComboboxContent recentsLabel="Recent">
-    <ComboboxEmpty>No match — type a name to create one</ComboboxEmpty>
-    <ComboboxFooter>{validity}</ComboboxFooter>
-  </ComboboxContent>
-</Combobox>
-```
-
-It's a SELECT by default (`ComboboxInput` with NO `icon` → a trailing chevron); opt INTO the
-search-box look with `ComboboxInput icon="search"` only when typing-to-search is primary (a
-large/remote set). For a select that the user can RESET, pass `clearable` + `onClear` (deselect):
-the chevron shows while the field is empty and a clear ✕ replaces it once there's a value/query;
-pressing ✕ clears the text and reopens the full-browse list, so `onClear` lands back on the whole
-set (on focus an empty field already browses everything — `recentOptions ?? all`). `allowCustom` appends a "Create …" row (`customOptionLabel`) when the query
-matches no option, emitting the typed text as the value — so a value not in the known set means
-CREATE. Wire that branch to a create overlay (an anchored popover for a 1–2 field gate, a modal
-`Dialog` for 3+) that builds the new record and attaches it; existing matches attach directly.
-A record-CREATION dialog stays a MINIMAL gate and really creates — the row lands and its own
-workspace opens for refinement (an EMPTY checklist, commons as ghosts). NEVER a creation
-wizard: create-then-refine puts complexity on the record surface, not in front of it. The create
-row sits BELOW matches by default (the keyboard highlight lands on the first MATCH, so Enter on a
-partial picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it above. Use
-`reflectSelection={false}` and render the attached record below as a card with a Change action.
-For input-level status that must stay visible while results scroll (validity feedback on the typed
-value, a result count, a secondary "create" affordance), drop a `ComboboxFooter` into the content —
-a pinned row below the listbox, OUTSIDE keyboard option-nav; call `useCombobox().close()` from a
-footer action that hands off elsewhere (so the popover dismisses cleanly instead of floating over
-what you navigated to). A `ComboboxEmpty` child gives the no-match state richer content than the
-`ComboboxContent emptyText` string.
-
-### Line items — create → preview → edit (a composition, not a primitive)
-For a list of records you build then revise (invoice rows, repair lines, config entries), each
-item is a `Card` toggling between a read-only PREVIEW (a stack of `DetailRow`s) and an EDIT form
-(the inputs), via a local `editing` flag + Edit/Save/Cancel in the `CardFooter`. A freshly-added
-item opens in edit; Save collapses it to the preview; Edit reopens it. **Edit is cancelable** —
-snapshot the item on Edit so Cancel reverts, or DISCARDS a freshly-added one. Duplicate sits left;
-the destructive **Delete is `danger-secondary`**; Cancel + the Save/Edit toggle sit right. Every
-screen composes its own (~15 lines) so the preview rows + form fit the data.
-
-### Handoff — a stage transition, never a message
-When work crosses departments (sales → operations → accounting), the HANDOFF is the RECORD
-changing desks — never an inbox, a notification, or a copied task. Two types:
-**(A) Same entity** → a STAGE field on the shared record: sections carry OWNER dot tags, and
-the handoff is MANAGED AS TASKS — each desk's checklist on the record (the task-row vocabulary:
-sibling `CheckCircle` + struck transparent `InlineTextInput` + per-task `InlineMemberSelect`
-assignees + the `CaptureRow` add-affordance — never a decorative progress strip). A NEW record
-starts with an EMPTY checklist — tasks truly vary. The commons split in two: MANDATORY tasks are
-seeded by the app (a workflow on create, per record type) — no human types them; common-but-
-OPTIONAL tasks appear as `SuggestionChip`s under the list — a PILL, never a row,
-so a suggestion can't be mistaken for a task (tap = materialize, ✕ = dismiss for this record;
-already-present labels filter out; suggestions never count in done/total and pause while a
-filter narrows the view) — the same suggestion grammar as the
-billing Standard pill. Real rows carry a ⋯ `menu` (an `ActionMenu`; Delete lives BEHIND it, danger-styled and last — never a bare ✕ a stray tap can hit), completing the checklist's CRUD. Open
-tasks INFORM
-the handoff, they NEVER block it: the CTA stays enabled, the count warns, and open tasks carry
-over. The handoff CTA opens a DIALOG for the receiving desk (assignee `MemberSelect` + an
-optional note; the open-task warning inside); confirming closes the drawer — the record left
-this register. Tasks PEEK from the register: the done/total column is a pressable
-compact-`ProgressBar` trigger whose popover holds the checklist on FIXED columns — every row
-ring · struck `InlineTextInput` title (flex) · quick-reassign `InlineMemberSelect` (140) — no
-expandable rows (tags/files depth is the Task list template's lesson, not the peek's); the
-popover body is `PopoverContent`'s own ScrollView (`disableBodyScroll` is ONLY for children
-that manage their own scroll, like `OptionList`). The DRAWER carries a real Tasks SECTION in
-the Record template's shape (heading + the compact meter + the same checklist) — one shared
-task state per record feeds the column, the peek, the section, and the handoff dialog;
-a section owned by a later desk sits visible but GATED ("Billing opens when the record reaches
-Accounting"). Registers scope by stage — the receiving department's register IS its inbox. The
-sender's sections stay editable after handoff (the gate transfers RESPONSIBILITY, not access —
-locking is app IAM, not template grammar). Worked example: `tpl_record`.
-**(B) Different entity** (a deal → a shipment) → SPAWN-AND-LINK: the upstream record's terminal
-gate CREATES the downstream record on the shared spine, linked both ways (a linked-record row
-each side); usually TWO apps — the upstream closes its own lifecycle, the downstream starts
-fresh in its department's app. Never merge the two lifecycles into one record.
-
-### Sequential phases on one record + the outline rail
-When a record's work happens in ORDERED PHASES (gate in → gate out; receive → dispatch), the
-phases are NOT tabs or a segmented control — hiding the other phase loses the context the
-current one needs and buries why its gate is blocked. Both phase sections sit on ONE page in
-chronological order; each phase owns ITS OWN fee rows + phase total (the invoice-band idea one
-level up — money never reads as one pot); each closes with a SEQUENTIAL confirm gate that names
-its blockers ("Confirm gate in first."). The header status chip carries the phase. A LONG record
-surface pairs with a LEFT OUTLINE RAIL — `MenuButton` items + `useSectionNav` (scroll-spy: jump
-to a section, the highlight follows the scroll); on narrow containers the rail becomes a
-PINNED bar naming the current section that opens a full-page section-picker `Modal`. A per-phase
-dot on a rail item carries its confirmed state. A direction that is a TYPE (one record per gate
-EVENT) is instead a discriminator chosen ONCE at creation — a `SegmentedControl` in the create
-step, never a toggle on the record.
-
-### Billing — the invoice DOCUMENT is the unit (`tpl_record` Billing section)
-When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
-split the screen into "enter fees here, issue there" — that smears one job across two places. Make
-**each invoice a FLAT hairline-set band that holds its own editable charge lines** (amount input +
-payment method), its **live total**, its **status badge** (nothing-to-bill · draft · issued + ref),
-and its **issue action** in its closing row — no card chrome; Data-capture templates are flat. A charge never lives apart from the document it bills on. Issuing is gated
-**inline, never a dead end**: when a prerequisite is missing (a bill-to tax ID, a method on a
-charged line) the issue button disables with one muted line saying what's needed; the payment-method
-picker turns required the instant a line carries an 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.
-
-### Tag / multi-value field — `Select multi`
-A tag field's resting state should be a tidy CHIP BOX — and that's just a multi `Select` whose
-`renderSelected` returns a removable `<Chip onDismiss={remove}>`. There's NO separate component and no
-`display` mode: `renderSelected(item, { remove })` composes the anchor — render a `Chip` with `remove`
-for the ✕, or a plain `OptionBadge`/`MemberChip`/custom pill that ignores it; `renderOptionContent`
-renders the menu rows. `searchable` adds the filter field, `allowCustom` the create row. Borderless for
-a grid cell? Pass a `style`, never a `variant`. `Combobox` is the SINGLE-value sibling — for a search
-that emits one pick at a time and renders the selection elsewhere, use `reflectSelection={false}`
-(see `tpl_*`).
-
-### Disposition — lifecycle status is ASYMMETRIC by phase
-When a status is an OPEN default plus terminal OUTCOMES the user decides (Lead → Closed/Lost, Draft
-→ Confirmed/Cancelled, Open → Approved/Rejected), a 3-way segmented/dropdown is wrong — it treats a
-lifecycle as flat peers and guides neither the decision nor the revision. Split by phase: while
-OPEN, surface the outcomes as ACTIONS with valence (`Mark closed` = `primary`, `Mark lost` =
-`danger-secondary`; the open state a quiet dot `Badge`). Coloring the buttons is right here — a
-SINGLE record-level decision is not the approvals-queue "wall of loud buttons." Once RESOLVED, show
-the colored STATE (`Badge variant="dot"` — emerald positive / red negative / blue open) with a
-quiet, REVERSIBLE **Change**: a popover STATE SWITCHER (each state a colored dot + label, current
-marked + disabled), not a generic text menu. A composition (Badge + Button + Popover/MenuButton).
-
-### Attachments — a full add / preview / DELETE field
-**Default: `<FilesEditor files onAdd onRemove>`** — it bundles the grid + a toolbar (Upload · Select ·
-Download all) + a batch SELECT mode + the gallery + confirmed-remove; the host only owns `files` and
-wires `onAdd` (picked → its upload) / `onRemove`. The destructive per-tile ✕ shows only in SELECT mode
-(the default view is a clean preview — no stray-tap deletes); pass `selectTileRemove={false}` to drop
-that ✕ entirely so select mode deletes ONLY via Select → Menu → Delete (the batch gating flow — how the
-cell popover's `cell_files_editor` does it). The built-in gallery is Download +
-inline preview (no "open in new tab" — it's redundant once everything previews inline). In a
-height-bounded container (a popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the toolbar
-pins below it; omit it in free-flow layouts (a form field) where the grid grows. Reach for the
-lower-level pieces below only when you need custom chrome:
-Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
-accent; click falls back to a picker); display what landed with **`<FileGrid files uploads>`** ABOVE
-the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add more"
-affordance — only the empty state leads with it). `FileGrid` is the upload-aware grid: `files` are
-the saved/completed `DisplayFile`s, `uploads` is the LIVE add-queue (`FileUpload[]`) — it interleaves
-both and renders each in-flight tile itself — a LABELED status overlay (uploading spinner · "Retrying"
-· "Paused" · "Upload failed" + a retry button · "Can't upload" for a dead/empty file) — so you never
-hand-map an upload to a `FileThumbnail`. Localize the labels with `labels.upload` (an
-`UploadStatusLabels`; the Lotics `@lotics/ui-internal` adapter already injects vi/en). Make it CRUDable
-by wiring its callbacks: `onFilePress`
-→ set a `number|null` index that drives `<FileGalleryModal files activeIndex onIndexChange>` — a
-FULL-SCREEN viewer with a toolbar (filename · counter · actions — download, optional
-`onOpenExternal`/`onRemove` · close-✕), prev/next, ESC, and rotate. The toolbar is RESPONSIVE: on a
-phone (`useScreenSize().small`) the actions collapse into a `⋯` `ActionMenu` so the close-✕ never
-overflows off-screen (its popover portals inside the modal's own `PortalHost` — a raw `<Modal>` lacks
-one, which is why an earlier inline-less popover rendered behind the overlay). The 90° rotate controls
-for images are NOT in the toolbar — they FLOAT as a pill overlaid on the image (every screen size).
-`onDisplayRemove`/`onUploadRemove`
-→ drop the file / cancel the upload (the grid renders a ✕ on each tile automatically); `onRetry` /
-`onRetryAll` for failed uploads. In a sandboxed custom-code app the toolbar's "open in new tab" can't
-pop a window — pass `onOpenExternal` wired to the SDK's `openExternal` (omit it elsewhere and the
-action hides). PDF/Word/Excel/CSV all render INLINE here (pdf.js / `@lotics/docx` / `@lotics/xlsx`,
-lazy) — no native `<iframe>` viewer, so they work inside the cross-origin app iframe. Keep
-label+grid+dropzone on a `gap` (a bare `CardBody` has none). By default `FileGrid` tiles FILL the
-container width — a uniform size (≥ `minItemWidth`, default 96) so full rows span the width and reflow
-as it changes; a short last row keeps that size and left-aligns (no stretched tiles, no empty cells).
-Pass `columns` for a fixed column count, or `itemSize` for exact fixed-size tiles. For a dense strip
-in a FIXED-width container that must NOT wrap, pass `singleRow` — it fits as many tiles as the width
-allows and collapses the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`,
-which the host wires — e.g. open the gallery at the first hidden file). This is the responsive overflow
-pattern (avatar stack / Finder); prefer it over a hardcoded `maxVisible`, which can't adapt to width.
-Under the hood it composes `FileThumbnail` (the completed tile — right surface per
-MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename · media
-card; also takes `isTemplate` to overlay a TMPL marker) and `UploadingThumbnail` (the in-flight tile);
-reach for either directly only when hand-rolling a NON-grid layout. **When the filename must be
-readable, use `FileRow`** — a horizontal LINE (`FileBadge` or a `placeholder` + the FULL name + a meta
-line + a composable `trailing` slot). `onPress` makes the whole row a pressable door (open the file);
-`trailing` (a status `Badge`, an action, a remove ✕) stays an independently-pressable sibling. For
-attachment lists / message files / document checklists where a square tile truncates the name. Never hand-build a drop well, a file grid, the upload tiles, or a preview
-modal. In a custom-code APP, don't hand-roll the upload+preview state either — `@lotics/app-sdk`
-`useAttachments()` gives the chat's instant-preview lifecycle (local object-URL now, `file_id` on
-complete); map each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file: {…} }`,
-else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `FileGrid`'s
-`uploads` — `onUploadRemove={remove}`.
-
-**Gated file CRUD is a PATTERN, composed locally — not a sealed kit component.** When a file field must
-GUARD deletion (operator-facing, accidental delete is a real risk), DON'T use `FileGrid` (its per-tile
-✕ is exactly the stray-tap risk you're guarding against) — compose it in the app from the kit pieces;
-don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
-`files_editor` and each app compose their own). The recipe: `FileDropzone` (add) + `FileThumbnailGrid
-files selectedIds onFilePress` (pass `selectedIds` ONLY in select mode) + `FileGalleryModal` (view +
-rotate + persist) + a `Dialog` confirm, all driven by **`useSelectionMode()`** — the reusable LOGIC. The
-gating rule: **NO per-thumbnail ✕** — delete is **Select → ⋯ menu → Delete → confirm**, so a stray tap
-never removes a file. Three reusable primitives back it (the logic is shared; the action bar + layout +
-copy stay local):
-- **`useSelectionMode()`** (`@lotics/ui/use_selection_mode`) — `{ active, selected, enter, exit, toggle,
-  toggleAll }`, an agnostic multi-select state machine (string ids; pairs with the grid's `selectedIds`).
-- **`shareOrDownloadFiles(files, { title, credentials })`** (`@lotics/ui/share_or_download`) — `navigator.share({ files })`
-  (mobile → Save to gallery / send to an app), else individual `downloadFileFromUrl` — **never a ZIP**.
-  It shares the BYTES (fetches each URL → `File`), so URL expiry afterward is moot; the share path needs the
-  host iframe to grant `allow="web-share"` (else it falls back to download). Best for FAST urls (presigned
-  R2). **For SLOW urls (auth-gated proxy with a server round-trip), split it:** `prepareShareFiles(files,
-  {credentials})` fetches the `File[]` BEFORE the gesture (on menu-open), then `shareFiles(File[])` runs
-  `navigator.share` synchronously on the tap — **iOS Safari rejects `share()` if a slow fetch burns the
-  tap's transient activation**, which silently lands in the download fallback. `prepareShareFiles` throws on
-  a fetch failure (log it, don't swallow); `shareFiles` returns `"shared"|"cancelled"|"unsupported"`.
-- **`rotateImageToBlob(url, degrees)`** (`@lotics/ui/rotate_image`) — canvas-bake a 90° rotation into a
-  NEW blob for re-upload (`useImageRotation` is view-only; this is how a rotation is persisted). Pair with
-  `FileGalleryModal`'s `onPersistRotation`/`persisting` (the ✓ shown on a rotated image).
-
-### Stage gates — tiered by weight
-A transition that needs NO input is one click. 1–3 quick fields → a POPOVER FORM anchored to its
-action button (title + one-line stake + `FormField`s; confirm in `PopoverFooter`). A
-destructive/exception path (anything touching money or locks) → a `Dialog` (consequence in prose,
-danger confirm + cancel in `DialogFooter`) or an `Alert.alert(title, message, [{cancel},
-{destructive}])` confirm. Never an inline expanding panel for a gate — it shifts layout and loses
-the "this is a gate" framing.
-
----
-
-## AI workflows — AI proposes, the human decides
-
-The AI surfaces share ONE law: the agent never commits — it **proposes**, the human
-accepts / edits / dismisses, the deterministic app applies. The agent owns judgment
-(recognition, estimation, intent→parameters); the app owns geometry, math, and the write.
-Compose the surfaces as a loop, and reach for the right one by job:
-
-**Which AI surface — decide by the OUTCOME's shape, not the task's topic.** Three shapes:
-
-1. **Field writes** (extract, match, rank, classify → the record changes) → **in-app agent**
-   (`useAgentRun`) + **`ChangeReview`**. The commits must obey the diff law (Keep/Drop per
-   change, app-workflow writes, bounded app authority), and the operator wants one button +
-   a review — never a prompt box.
-2. **Evidence for an in-app decision** (cross-check, audit, tie-out → nothing is written; the
-   operator acts on what was found) → **in-app agent** + **`Finding`**. Still bounded and
-   prompt-free (an optional instructions brief at most): the brief is fixed, the output is
-   structured display-only findings read IN the record's context, and there is no conversation
-   to have — the loop closes when the operator acts in the app. Chat would add prompting and
-   tear the findings away from the record they judge.
-3. **A file or an open-ended answer** (edit this document, draft from context, explain) →
-   **hand off to the chat agent** (`askAi` in `@lotics/app-sdk`). The loop is multi-turn with
-   no output schema, judged by looking — and the chat harness already owns it: preview beside
-   the thread, version chains, branching, session memory. An in-app "edit chat" would
-   re-implement all of that inside every app.
-
-The Document desk's Use-AI fork IS this table as UI: Extract data (1) · Cross-check (2) ·
-Edit with AI (3) — one entry point, three outcome shapes.
-
-- **Command / compose** — `Composer`, the adaptive command surface. Empty + minimal (no `footerRight`
-  model picker, no `pills`, no `files`), it's a COMPACT PILL: an optional `actionsButton` (attach) left,
-  the input, a send arrow right (Enter sends, Shift+Enter for a newline) — the same geometry
-  `AgentProgress` morphs into. Type past one line, or add files, and it EXPANDS: the input lifts onto
-  its own row, the `files` slot (`FileThumbnail`s, each `onRemove`-able) and `pills` stack above, and
-  the buttons drop to a footer row (the expansion latches until the text is cleared). For a run that
-  needs a FILE + a prompt together (attach a photo, review/remove it, add a note, THEN send), fill
-  `actionsButton` + the `files` slot and set `sendDisabled` so Send fires with an attachment and/or
-  text (`onSend(text)` — the host holds the uploaded file id). **Never auto-run an agent on attach** —
-  attaching HOLDS the file for review; the human presses Send. The canvas (`tpl_dieline`) uses it this
-  way; while running the host swaps `Composer` for `AgentProgress` (same pill geometry, so it reads as
-  a morph).
-- **Show the work** — `AgentRun`: a live feed of the agent's work as a TIMELINE. The prop is an
-  ORDERED `items` array — `{type:"text"}` prose (rendered as `Markdown`, a trailing ▍ while live),
-  `{type:"reasoning"}` thinking, and `{type:"step"}` tool/step calls, in the order they happened (a
-  real run is think → text → a burst of calls → more text, NOT all text on top of a flat step list).
-  **Progressive disclosure** — the feed shows the label + state; the detail is revealed on demand:
-  `reasoning` renders COLLAPSED (a muted "Thinking" row, press to reveal the Markdown), and a `step`'s
-  `input`/`output` are hidden in the row but open in a press-to-reveal **peek** (auto-built Input /
-  Output `JsonPanel`s; an `error` status + `errorText` paint the row red and show the reason there).
-  Pass an explicit `peek` node to render that reveal yourself (it overrides the auto panel); `detail`
-  is OPTIONAL — a short human summary (a count), never invented prose or raw I/O (that's `input`/`output`).
-  Consecutive `step` items fold into ONE activity group: while the agent is mid-tools the tail group is
-  a SINGLE pulsing row whose label swaps in place as each call fires (no growing stack of dots); once
-  prose resumes the group settles into a persistent "{final action} · {n} steps" HEADER (a `complete`
-  terminal dot — distinct from the filled `done` step dots) that STAYS PUT and rolls the calls out
-  BELOW it on press. The run ALWAYS ends on the agent's text (no global terminal node). A `step` with
-  `kind:"tool"` carries the RAW tool name, resolved via a built-in map + an optional `labelForTool`
-  override (localize THERE — the kit stays English); `stepsLabel` localizes the "{n} steps" suffix.
-  Fed natively by `@lotics/app-sdk` `useAgentRun().items` (reasoning + per-tool I/O + state come for
-  free — no hand-assembly). Transparent work, NEVER a bare spinner. On a canvas/composer app reach for
-  `AgentProgress` — `AgentRun` collapsed into a floating pill (avatar + current step) that EXPANDS on
-  press; the composer morphs into it while running, and reveals again when done.
-- **Review before apply — ONE surface, the compound `ChangeReview` family.** Every "the agent
-  proposes → the human accepts / edits / dismisses → nothing auto-applies" surface composes from
-  twelve pieces in three groups. **Frame**: `ChangeReview` (context provider + stack; hairline
-  dividers between `Change` sections — and `ChangeFields` rules between fields) ·
-  `ChangeReviewHeader` (the SECTION heading — md semibold; keep it lean: never repeat the record
-  the dialog is already about) · `ChangeReviewActions` (the commit bar — pin it in the
-  `DialogFooter`/`DrawerFooter`; **Keep all** bottom-left presses every pending decision — pass
-  `onAcceptAll` when field state lives in the host; the "N of M kept" counter reads HERE beside it,
-  never in the header; Apply disables at 0 kept or via `applyDisabled`). **Sections**: `Change`
-  (heading + free body + optional verbs + collapse — omit both callbacks for display-only) ·
-  `ChangeLabel` · `ChangeSummary` (the collapsed row's content) · `ChangeReasoning` (the agent's
-  quiet hairline aside — only when not self-explanatory). **The grammar**:
-  - **`ChangeFields` + `ChangeField`** — THE field unit. `ChangeFields` is the OPEN form (the
-    section IS the record — an extract dialog's one order: no card chrome). Each `ChangeField`:
-    label (sm, muted — the DetailRow convention) · the `−` band when replacing (`before`) · the value — `ChangeValueInput`
-    by default (the green `+` band; pressing it edits IN THE BAND — a borderless input with
-    identical type metrics, so nothing shifts; `unit="pcs"` fixes the suffix outside the editable
-    core — type the number, never the unit) or any input · conflict `candidates` as full-width decision rows + the localized
-    "Type another value" third option (`custom*` props; the outcome band is read-only via
-    `valueReadOnly` — the decision comes from picking, never from editing the band; gate with
-    `keepDisabled`) · row `reasoning` LAST · per-field **Keep/Drop** bottom-right
-    (`status`/`onKeep`/`onDrop`/`onUndo`). A pure REMOVAL is `before` with an empty value — the
-    `−` band alone. A decided field collapses to the compact one-row card (mark · label →
-    `summary` · Undo).
-  - **`ChangeRecord`** — THE item card for SETS of records (order lines): `id` (it registers in
-    the review context like a `Change`), `tone` add/edit/remove, the tinted header band with the
-    localized op word (Add/Edit/Delete · Thêm/Sửa/Xóa) + title, body = its `ChangeField`s, and
-    **the verb level follows the decision level**: add/remove carry ONE card Keep/Drop (fields
-    none — editable parts, one write); edit carries NO card verbs (only its changed fields, each
-    deciding for itself — dropping a field narrows the update diff). Collapses via `summary`.
-  - **`ChangeBand`** — the raw diff band (aligned `+`/`−` marker column, light emerald/red, dark
-    text) every piece builds from; reach for it directly for custom strokes.
-  **The scaling boundary (known, deliberate)**: `ChangeFields` + `ChangeRecord` cards cover one
-  record through ~10; a BULK review (30+ imported rows — a bank statement, an Excel import) needs a
-  dense form that does not exist yet — design it against the first real migration, not
-  speculatively.
-  **The laws**: ONE verb pair everywhere — Keep/Drop, localized; never rename per shape (Apply is
-  the only outcome-named button). Candidate rows carry the VALUE only; provenance = `Sources` at
-  the VERY bottom of the review (after every change; or omit it — lean beats decorated). The HOST owns every decision in plain `useState`; the family owns the
-  mechanics (collapse + Undo, the counter, Keep-all, apply gating). Never apply a field with no
-  value — gate unresolved conflicts. Editing IS the review.
-- **Ask back** — `Clarify`: when the agent is unsure, it asks a question with quick-reply options
-  and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run.
-- **Provenance** — `Sources`: openable chips saying where the output came FROM (records, a
-  document + page, a table), under any answer / summary / extracted value. Makes AI output
-  verifiable — show it on anything produced from data the agent read.
-- **Session, not chat** — the outputs accrue as a history the user can CLEAR ("New session"); the
-  APP owns the evolving state, each run is a discrete task. (The agent may re-read the session for
-  "make it a bit less", but it's a run LOG, not a conversation transcript — that's why it's not a
-  chat.)
-
-Ten shapes prove the range. The first four PRODUCE — pick by whether the work is a living artifact,
-a conversation, a single pass, or generated prose:
-- **Canvas** (`tpl_dieline`) — the page IS the design on a pannable/zoomable surface: it stays
-  CENTRED at every zoom (a floating zoom pill bottom-left), the FLOATING composer at the bottom (a
-  `Composer`: attach a photo → review/remove it → add a note → send, with `sendDisabled` allowing a
-  file-and/or-text submit — NOT auto-run on attach) morphs into `AgentProgress` while running, and a pinned PARAMS PANEL (a label/value field-card
-  in live-edit mode, carrying the single Download; minimizes to a pill) floats centre-right. Panel, zoom pill and composer
-  float ON TOP — they never shift the design. (Floating layers use a `pointerEvents:"none"` wrapper
-  with the interactive child set `"auto"`; RN-Web ignores `"box-none"` in style, so a full-width
-  wrapper would otherwise eat clicks on the canvas behind it.) Change the design by prompt ("5 mm
-  taller") OR by editing a param directly — either re-flows it in place. For a design/document the
-  user shapes over time.
-
-The next six output STRUCTURE the first four can't — when the answer is a panel of facts, a queue of
-decisions, or a ranked set, don't cram it into chat prose. Each pairs a template with a primitive:
-- **Answer desk** (`tpl_lookup`) — describe the goods on the LEFT → the agent RANKS the
-  matching codes (NEAREST MATCHES, the top one Recommended) → pick one and its STRUCTURED answer pins on
-  the RIGHT (a verdict header + an exact breakdown + the policies + sources). Input → matches → pick,
-  NOT a single confident verdict: classification is ambiguous, so the alternatives are first-class and
-  picking a different one changes the duty; refining the description re-ranks. For look-up-and-explain:
-  tariff/HS, fee lookup, policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
-
-- **Document desk** (`tpl_documents` — THE go-to for document-driven records) — the record's files
-  block feeds ONE "Use AI" entry that FORKS into the two document tasks, each a specialized run with
-  a task-pure result: **Extract** (files read → fields already matching fold into one quiet line →
-  every add / update / conflict a `ChangeField` (struck before · bordered input · candidate chips),
-  the record's current value a first-class choice — plus proposed new lines as record-body `Change`s
-  → one outcome-named `ChangeReviewActions` commit) and
-  **Cross-check** (documents compared against the record and each other → ranked `Finding`s —
-  severity · title · the prominent metric · sources — separated by hairlines; the findings ARE
-  the outcome the human acts on — no phantom "record verdict" write, a persisted check-status
-  goes stale on the next edit). The fork carries an OPTIONAL instructions field — the user steers what the agent
-  checks or extracts, so `Finding` serves ANY file-based AI request, not just the stock
-  cross-check. Every file list in the flow opens the full-page `FileGalleryModal`. Plus **Create documents**: a readiness checklist (unchecked by
-  default, missing inputs called out) → generate → the files land back on the record. Never merge the
-  two AI tasks into one mixed output — the fork is the design.
-- **Triage** — an inbox the agent classified + routed is a `ChangeReview` of `Change`s (body: the
-  item + the agent's call; verbs Accept / Dismiss; Accept-all covers the high-confidence sweep).
-- **Compare / ranked pick** — one `ChangeField` whose `candidates` carry the ranked options
-  (`description` = the score/reason, `source` where it came from); the human picks one. Quotes,
-  carriers, suppliers, plans.
-
-The AI vocabulary has **no purple accent and no gimmick glyphs** (no sparkles) — but it is NOT
-monochrome: **colour is used where it carries meaning, not for decoration.** What the violet sparkle
-used to carry now reads structurally — **provenance** is an uppercase microlabel naming the artifact
-(`PROPOSED` · `MATCH` · `MISMATCH` · `SUGGESTED EDIT` · `QUESTION`), and the agent's **reasoning** is
-a left-ruled margin note (a hairline rule + muted text), quoted apart from the facts and the human's
-controls — while **status/severity/diffs use functional colour** the way the rest of the kit does:
-- **Confidence** — a 3-tick meter + the full phrase ("High confidence" / "Medium" / "Low"), emerald /
-  amber / zinc by level; `labels` to translate (one phrase per level).
-- **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring** (white
-  centre), `done` a filled accent dot + **white check**, `upcoming` a faint **grey** ring, the terminal
-  `complete` a **blackish ring + black check**, `warning` **amber**. Default accent is neutral ink
-  (`color` themes it); `AgentRun` keeps the neutral default — an active group's tail pulses (`current`),
-  a settled group is a `done`/`warning` row, and there is no global terminal node (the run ends on text).
-- **ChangeBand** — the removed value on the light **red** band with the `−` marker, the incoming
-  value on the light **emerald** band with `+` (the GitHub-diff idiom, markers in one aligned
-  column); everything else in a review stays neutral — a decided row reads a single emerald check,
-  an add/remove record card wears the quiet tone wash (50 body · 100 header · 200 border). Colour
-  marks the change, never the chrome.
-
-Card chrome (borders, microlabels) stays neutral — colour marks the *state*, never the container.
-The **composer keeps its icons**: `Composer` compact is a single-row pill with an optional circular
-attach `actionsButton` + a circular send `Button`; expanded it adds a `FileThumbnail` attachment row
-(each `onRemove`-able) above the input; `AgentProgress` is the `WaveAvatar` pill. "No icons"
-was only ever about the review surfaces' sparkles/severity glyphs, not functional affordances.
-
----
-
-## Composition grammar
-
-- **Canvas**: full-bleed `colors.zinc[50]` ScrollView; content column `maxWidth` 880–1040,
-  centered, `padding: 28`. Cards float on the canvas — never white-on-white.
-- **Heading vocabulary — ONE construct per altitude, no drift.**
-  · **Page band**: one per screen — `Text size="xxl" weight="semibold"` title (`#`) + one `sm muted`
-    subtitle that says what the screen decides. Right side: the screen's ONE primary action and/or
-    a period filter — never a summary Badge (those belong to the KPI strip).
-  · **Card header** (a card's own title band, or separate banded cards): `CardHeader` +
-    `CardHeaderTitle` (`sm semibold`; `info` when the title alone doesn't define the numbers).
-  · **Section title** — ONE construct: `Section` > `SectionHeading` > `SectionHeadingTitle`
-    (lg semibold + optional muted `description`/`info`), everything left-aligned at the column
-    edge. The page column is a `SectionStack` — it owns the between-section law (`gap: 32` +
-    a bare hairline separating one section from the next); the `Divider` NEVER goes directly
-    under the heading, which orphans the title from its own content. Inside a DRAWER, a full
-    multi-section WORKSPACE uses the real
-    `SectionHeading` (lg) — its meta + CTA slots carry each section's count and action; a
-    `Text size="sm" weight="semibold"` stand-in is only for small sub-groups. Do NOT wrap each section in its own `CardHeader`, do NOT
-    hand-roll sm-semibold lead lines on a flat page. NEVER a bare eyebrow as a section title.
-  · **The heading ramp is FIXED — the markdown ladder, no size knobs.** `#` = xxl
-    (`RecordSummary` / `PageHeader` title) → `##` = xl (`SectionHeadingTitle`, always) →
-    `###` = lg (`SubsectionHeadingTitle`, always) → body sm. One outline on every surface;
-    never restyle a heading level per-page.
-  · **Subsection title** — the level BELOW a section on a long record surface: `Subsection` >
-    `SubsectionHeading` > `SubsectionHeadingTitle` (`###` lg semibold; siblings — a `Badge`, a
-    `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections
-    stack in a `SubsectionStack` (24 + hairline between groups — no margins, no hand-rolled
-    dividers); a headingless `Subsection` is the section's lead group. Group leads INSIDE a
-    subsection's rows are `md medium` at most. Do NOT hand-roll `Text weight="semibold"` group
-    leads inside a section, and never promote a subsection to its own section-level heading
-    just to separate it.
-  · **Eyebrow / label** (`<Text size="xs" color="muted" weight="medium">` — **sentence case, NEVER
-    `transform="uppercase"`**): a small quiet label above or beside content — an artifact tag
-    ("Proposed", "Question", "Suggested edit"), a field name, a metric caption, a minor one-line
-    label. **All-caps is banned — it reads as shouting and the redundant uppercasing of every little
-    label is the #1 thing that makes a surface feel templated.** Sentence case + medium weight, full
-    stop. (A COLORED status word — a verdict like "Mismatch" / "Resolved" — keeps the same xs/medium
-    shape with a status `color`, still not uppercase.) This applies to every hand-written label; don't
-    reach for a wrapper component either, just write the `Text`.
-  · **Gate header**: a `Dialog` uses `DialogHeaderTitle`; a popover form uses `Text size="sm"
-    weight="semibold"` + an optional `xs muted` subtitle.
-- **Time-constrained data gets a period filter** in the header band — `DateRangeFilterField`, never
-  a static period badge. Every period-dependent number MUST follow the selection. Pass `includeTime`
-  when the time-of-day matters: the trigger previews the chosen time (locale-aware 24h/12h) and the
-  hour/minute selects label themselves from the `labels` prop (`hour`/`minute`/`dayPeriod`).
-- **Keyboard & focus — use `tabIndex`, never `focusable`.** RN-Web's `Pressable` silently ignores
-  `focusable` (it writes its own `tabIndex`), so set a pressable control's tab-stop status with
-  `tabIndex={0 | -1}` (`focusable` only works on a plain `View`/`TextInput`). Roving widgets
-  (Tabs/SegmentedControl/RadioPicker) keep ONE stop at `0`, the rest `-1`. And NEVER let a FOCUSED
-  control unmount — a conditional pointer affordance that vanishes on use (e.g. an "apply suggested
-  value" pill shown only while a field is empty) must be `tabIndex={-1}`, or the browser drops focus
-  to `<body>` and the next Tab jumps to the page's first focusable. Full rules + the keyboard test:
-  `docs/accessibility.md` → Focus & tab order.
-- **Focus rings are per-component, never global.** There is NO global focus CSS — `index.css` only
-  resets the native outline. Every interactive control paints its OWN ring; nothing rings unless it
-  opts in. Three ways, pick by base:
-  - **`FocusRingPressable`** (`@lotics/ui/focus_ring_pressable`) — a `Pressable` that rings on keyboard
-    focus, WITHOUT the hover wash; the base for any control whose hover affordance is its BORDER not a wash
-    (inputs/selects, the inline editors, cells, tiles, nav buttons, menu options). Forwards all
-    `PressableProps`; its state-fn `style` exposes `hovered`/`focusVisible` so the control paints its own
-    border-hover. Reach for this before hand-rolling a Pressable + the hook.
-  - **`PressableHighlight`** — set the opt-in **`focusRing`** prop (or read `state.focusVisible` from
-    its style-fn / children for a bespoke treatment, e.g. `CardSelectItem` which rings on hover/press/focus).
-  - **`useFocusRing`** (`@lotics/ui/use_focus_ring`) — the underlying hook for inputs / custom surfaces.
-    Returns `{ focusVisible, focused, focusProps }`; spread `focusProps`, apply
-    `focusVisible && { boxShadow: FOCUS_RING }` (comma-join any existing box-shadow). `useFocusRing({ always: true })`
-    for text-like inputs/selects (ring on ANY focus, as browsers do for typing-capable fields); plain
-    controls omit it (keyboard-only).
-  The ring is the shared **`FOCUS_RING`** token (`@lotics/ui/control_surface`, `0 0 0 2px zinc-900`). A
-  mouse-opened popover trigger (Select/Combobox/InlineSelect/InlineDatePicker) wears the SAME token on
-  its open state so it reads identically to a keyboard-focused control. **Coverage is a contract:** EVERY
-  interactive control must ring (a focusable control with no focus treatment is a bug — the per-Pressable
-  audit is the gate); a surface that shouldn't ring is a non-control → `tabIndex={-1}`, not a missing ring.
-- **Hover intensifies a control's OWN resting signature — never a foreign affordance. Pick the base by WHAT THE SURFACE IS; never a raw `Pressable`.** The one rule behind every interactive control:
-  - **Fields** (type into / pick from) — `TextInputField`, `Picker`, `Select`, `Combobox`'s input,
-    `NumberInput`, `DateField`/`TimePicker`, `DateRangeFilterField`, the inline editors
-    (`InlineSelect`/`InlineDatePicker` via `InlineEditView`) — signature is a BORDER → hover DARKENS it to
-    `HOVER_BORDER` (a borderless in-cell field REVEALS one). Build on **`FocusRingPressable`** (ring + a11y
-    + a `state.hovered`/`focusVisible` style-fn, NO wash); layer the hover-border AFTER `style` so it wins
-    over the caller's resting edge; put the open ring (`FOCUS_RING`) on the open state. **A field NEVER
-    greys its content.**
-  - **Actions** — `Button`, `IconButton` — signature is a FILL → hover DARKENS the fill (own colour logic).
-    Never a border, never a wash.
-  - **Pills / toggles** — `Chip`/`ChipGroup`/`FilterChip` (via `chipSurfaceStyle`), `SegmentedControl`,
-    `Tabs`, `Switcher`, `RadioPicker` — signature is a pill SURFACE → hover WASHES it (white→zinc-100);
-    selected adds a ring/fill.
-  - **Surfaces** — `PressableRow`, `MenuButton`, list/menu items, `CardSelectItem`, `Card`, `Accordion` —
-    signature is a row/card SURFACE → hover WASHES it. Build on **`PressableHighlight`** — the grey wash IS
-    the affordance (its whole job; it's in the name).
-  - The bug this prevents: a FIELD built on `PressableHighlight` inherits the wash AND its own border →
-    it greys *and* animates its edge while its siblings only border-hover (`Select`/`DateRangeFilterField`/
-    the inline editors did exactly this pre-7.x). Reach for `PressableHighlight` on a bordered/input control
-    and you've made it.
-- **Cards are banded — and composable** (all from `@lotics/ui/card`):
-  ```tsx
-  <Card style={{ padding: 0 }}>
-    <CardHeader><CardHeaderTitle info="what this shows">Title</CardHeaderTitle><CardHeaderMeta>12</CardHeaderMeta></CardHeader>
-    <CardBody>…</CardBody>          {/* repeat with <Divider/> between */}
-    <CardFooter>hint(flex:1) + actions</CardFooter>
-  </Card>
-  ```
-  Never nest cards; never hand-compose a title or footer band. `info` is standard, not garnish.
-- **Flat work execution & data capture vs carded monitoring.** A `Card` is ALWAYS a bordered,
-  lifted container — there is no "flat card". MONITORING / dashboard screens group with cards (and
-  the `KPIStrip` band). WORK-EXECUTION screens — registers, lists, worklists — AND **data-capture /
-  record screens (forms, wizards, billing, settings, inline records) are FLAT**: content sits
-  DIRECTLY on the white canvas with no Card wrapper; separation comes from the row wash, gaps,
-  `SectionHeading` + `Divider` rhythm. Reach for a Card only
-  where a screen holds a DISTINCT region that must be told apart from another; a single register or
-  list filling the screen needs none. ONE carve-out inside a flat form: **repeating SUB-OBJECTS
-  (line items) are each their own small Card** (`padding: 16`), so discrete items
-  read as discrete objects; hairlines between them blur into one run-on list.
-- **Summaries — two altitudes, never mixed.** A DASHBOARD opens with the boxed stat band
-  `<KPIStrip items={[{label, value, trend?, caption?, tone?, info?}…]}>` (a `Card` of `KPICard`
-  columns). A REGISTER/LIST (work-execution) screen instead carries a LIGHT inline
-  `<SummaryLine items={[{label, value, tone?, info?}…]}>` BELOW its toolbar — a small `Metric` + a
-  muted label per item, recomputed from the FILTERED rows so it always describes WHAT'S SHOWN. Both
-  are INFORMATIONAL — they never filter or navigate (that's the tabs/chips' job); if there are no
-  cross-cutting numbers, drop them. Do NOT put a `KPIStrip` on a register page or a `SummaryLine` on
-  a dashboard. Card stat rails use `KPICard`.
-- **Numbers**: free-standing numerals `<Text tabular>`. Money: `formatMoney(n)` from
-  `@lotics/ui/format_money` (`compact` for strip captions; it emits a non-breaking space before `₫` —
-  normalize `\s` in test asserts). Dates: `formatDate(value, opts)` from
-  `@lotics/ui/format_date` — the date-VALUE formatter. `format` (date STYLE) ∈ `date` (22/05/2026) ·
-  `medium` (22 thg 5, 2026) · `long` (22 tháng 5, 2026) · `dayMonth` (22 thg 5) · `monthYear`
-  (Tháng 5 2026); **`time: true` is orthogonal** — prepends the 24h time to ANY style
-  (`14:30 22/05/2026`, `14:30 22 tháng 5, 2026`); `compact` drops the year on `date`. It's `Intl` +
-  the product's conventions (stable `/`, naive-ISO parse, 24h time-first, `emptyLabel`) — never
-  hand-roll a date via `Intl`/`padStart` for value display. An order the presets lack (e.g.
-  time-first `HH:mm dd/MM/yyyy` in a doc builder): `parseDate` + assemble the missing order —
-  never a regex re-implementation. (Exempt: a component's own internal
-  chrome — a calendar's header/weekday/a11y labels, a gantt axis — renders its own set.)
-- **Every number is a door** (except the KPI strip). A component that summarizes records leads to
-  the records behind it when pressed — switch to the filtered list, expand in place, or navigate.
-  Expansion happens IMMEDIATELY below the pressed element — the composable `Accordion` family
-  (`AccordionHeader`/`AccordionTitle`/`AccordionMeta`/`AccordionContent`); header-only = a plain row
-  of identical rhythm, so lists mix expandable + static rows. The body is **flush** with the
-  header's left edge (aligns with the title — like a `Section` body, no indent). `AccordionHeader`
-  is a layout slot: `AccordionTitle`/`AccordionMeta` is the compact list-row heading, but for a
-  **collapsible Section** (configurable font/level/description + count) compose the SAME
-  `SectionHeadingTitle`/`SectionHeadingMeta` inside it — one heading family across static + collapsible.
-- **No dead rows.** Every listed record is actionable. PRIMARY entity rows press-open the workspace
-  `Drawer` (sequenced); read-only drill-downs expand via `Accordion` or glance via `Peek`; every
-  other row gets an `ActionMenu` (⋯ → MenuButton items: destructive last + **confirmed** via
-  `Alert`). The whole surface is the door: register rows are `PressableRow` (full-bleed wash incl.
-  nested controls), Divider-separated:
-  · **Register (default, `variant="register"`)** — the rounded full-width hover/open/`marked` wash
-    spans the whole row (incl. nested controls); content sits on the 20px gutter so a `Table` header
-    + cells align. The Divider BETWEEN rows is the resting separation. The COLUMNAR register is
-    `Table`/`TableRow`/`TableCell` (columns once → header + widths can't drift; ONE hairline under the
-    header; the rows below it Divider-separated; a sortable column shows its `SortHeader` sort glyph
-    ALWAYS so it reads as sortable). A `TableRow` with no `onPress` renders a STATIC read-only row (no
-    hover wash / pointer cursor) so `Table` also serves read-only tabular data (a fee breakdown, a spec
-    sheet), not just interactive registers. A pressable `TableRow` REQUIRES `accessibilityLabel`
-    ("Open …") — its keyboard door is an empty overlay with no content to derive a name from. Make it SELECTABLE with the `Table` `leading` gutter + `selectAll`
-    slot — a `CheckboxInput` per `TableRow` (`leading`) + a select-all in the header band, the ticked
-    rows `marked`, paired with a `FloatingActionBar`; the selection state is the **`useSelection()`**
-    hook (`selected`/`count`/`toggle`/`setAll`/`allSelected`/`indeterminate`/`clear` — gating which
-    rows CAN be ticked stays with you: pass only the selectable ids to `setAll`/`allSelected`/
-    `indeterminate`). `tpl_item_list` is the reference. Paginate OUTSIDE (slice + `Pagination` in the
-    `CardFooter`).
-  · **`variant="bleed"`** (legacy) — px-20 square, `Divider`-separated; only for an edge-to-edge data
-    grid that genuinely wants hard rules.
-  · **`variant="inset"`** — grouped lists in a padded container (Accordion drill-downs).
-  Right-hand columns align only if every trailing element is FIXED-width (give each trailing action
-  a fixed `width`, so amount/status columns don't jitter).
-- **Row actions are ALWAYS-VISIBLE siblings, never hover-revealed, never nested.** A pressable row =
-  a role-less surface (the hover/press wash, via DOM `mouseenter` so it covers the whole row) + an
-  accessible "Open …" door (a button) + trailing actions (⋯, remove ✕, edit) as SIBLINGS of
-  the door — a button must not contain another button, so the action is independently pressable and
-  the ✕ isn't swallowed by the row press (`FileRow` and `PressableRow` are the references). The door
-  wraps the row body ONLY when that body is non-interactive by construction (`FileRow`'s name/meta);
-  where the body is arbitrary app content — `TableRow`'s cells, which legitimately carry a `Link` or
-  a popover trigger — the door is an EMPTY absolutely-positioned sibling under the cells (tab stop +
-  name + focus ring; mouse rides the surface), so a control in a cell never nests inside it. Actions
-  stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY exception
-  is a DENSE tree/register where a persistent per-row action would clutter (e.g. the DB sidebar):
-  reveal on hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its
-  opacity, so it's still keyboard-reachable. Do that locally — there is no shared hover-reveal
-  primitive (the old `HoverAction` made the keyboard-inaccessible anti-pattern easy and was removed).
-- **Master-detail = list + workspace `Drawer` with sequencing.** Pressing a PRIMARY entity row
-  opens the record workspace in a `Drawer` with `onPrev`/`onNext`/`position` ("3/24") over the
-  visible ordering (←/→ 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 `DrawerFooter`. The open row shows a selected
-  highlight (and `marked` — a resting blue tint — for a bulk-ticked row). `Peek` is ONLY for
-  secondary references, never the primary row press.
-- **Two work shapes, no side panels.** A work screen is ONE of two shapes — never a persistent
-  side-by-side split (it dies on a phone, and the "detail" of a list belongs in a `Drawer`/sheet,
-  not a second column). (1) **Work each** — a flat register/list; press a row → its workspace
-  `Drawer` (above). (2) **Act on many** — a flat list with a leading `CheckboxInput` per row + a
-  select-all `CardHeader` band, plus a bottom-pinned `<FloatingActionBar count label onClear>`
-  carrying the bulk action(s) while ≥1 row is ticked (`tpl_item_list`); a row
-  that can't take the action has NO checkbox. Bar weight gradient, left → right: the built-in
-  Clear is muted (the quietest act), destructive bulk = `danger-secondary` + icon, secondary
-  bulk = `secondary` + icon, ONE primary CTA last — never repeat the count in a CTA title; the bar's label already carries it. When a region genuinely must sit beside the list (a
-  source/remainder summary, a capacity picker) make it a TOP summary header or move it into a
-  Popover/sheet at the decision point — not a standing column.
-- **One control radius** — every interactive control (`Button`, the inputs/selects/pickers,
-  `SearchInput`, `MenuButton`, `Tabs`, the `SegmentedControl` track, `ChipGroup`/`FilterChip`/
-  `Chip`) wears `CONTROL_RADIUS` (10, from `control_surface.ts`) — never a literal. Containers
-  are deliberately larger (`Card` 16, the review card 12). An element NESTED inside a padded control
-  (a segmented thumb, a combobox chip, an ✕ on a chip) takes `CONTROL_RADIUS − padding` so its corner
-  stays CONCENTRIC with the parent — set it equal and the inner corner bulges past the outer curve.
-  Round-by-function controls (avatars, status dots, switches, sliders, progress bars, `IconButton`)
-  stay full (999); a small square toggle (`Checkbox`, 24px) keeps a proportional small radius (6 —
-  the same fraction of its box that 10 is of a 40px control), not the band radius. No capsules —
-  `Button` has no pill `shape`.
-- **One view-control vocabulary** (all 40px, `sm` labels, in one wrapping band):
-  · `SearchInput` is THE search box — a white `TextInputField` preset (the shared `CONTROL_RADIUS`
-    like every other input, a thin zinc-300 border, the leading search glyph + a clear ✕). It reads as search by its
-    ICON + white fill, not a distinct shape, so a toolbar of controls stays one consistent band.
-    Never a bare `TextInputField` + search icon.
-  · `ChipGroup` is THE one-of-N lens (≤ ~10 options the user flips between; include "All"; counts in
-    the label). Filters ONE list to a SUBSET — including by process stage / lifecycle state.
-  · `FilterChip` is THE secondary-dimension filter — a compact chip that opens a composed popover
-    editor (`OptionList multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
-    pick via the `{({close}) => …}` render prop.
-  · `ColumnFilter` is the TYPED column filter — give it a `FilterableColumn` (`text` / `number` /
-    `select`) + a controlled `ColumnFilterValue` and it renders the right editor (contains / range /
-    multi-select) inside a `FilterChip`, with `columnFilterToConditions` mapping the value to query
-    predicates. Reach for it — ONE compact chip per dimension — when a register filters on SEVERAL
-    columns (origin, destination, carrier, type…). Never hand-roll a row of bespoke chips/filters,
-    and never use a permanently-expanded `ChipGroup` for a secondary dimension.
-  · `Combobox` is the SEARCHABLE picker — reach
-    for it over `ColumnFilter` when the value is ONE of a large/growing set you type to narrow (a
-    port, a customer) rather than a short fixed list. Pass `recentOptions` (the same option list) so
-    a click opens the full list, then typing filters. The **From → To route picker** is two of them
-    (`icon="map-pin"`, `clearable`) with an `arrow-right` between — flight-search style.
-  · `Tabs` switch between VIEWS/sections (different content/layout) — never a subset of one list. A tab earns a `status` dot (optional `TabOption.status`) only when its area needs attention (a blocker / missing item) — the resting state has none.
-    `SegmentedControl` chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
-  · **Layout**: search + secondary filters LEFT, the primary CTA RIGHT, in ONE band. A `ChipGroup`
-    one-of-N lens is fine ONLY when the band has no `SearchInput`; once a search is present, the
-    status filter becomes a `Select`/`FilterChip` dropdown — never a row of pills competing with the
-    search.
-- **Footer actions align RIGHT.** `PopoverFooter`/`DialogFooter`/`DrawerFooter` default
-  `align="end"` — commit at the right edge, secondary to its left. Never left-flow a Save/Submit.
-- **Empty result**: `<EmptyState message hint? icon? action?>` — never a bare muted Text.
-- **Inline status**: `<Callout tone="info|success|warning|error|neutral">` — compound (like Card):
-  compose `CalloutTitle`/`CalloutText`/`CalloutActions` inside. `Callout` is INLINE; `Alert` is the
-  blocking modal; `Badge` is a one-word pill.
-- **One primary action per surface.** Everything else secondary/muted; destructive = `danger`
-  styling + explicit label. (A grouped BUILDER section — line items — MAY give its own Add 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` marks destructive — that's the whole axis. No "success"/green. Decision UIs put
-  positive/negative color on the STATUS (dot) and verdict (colored `Text`), not the buttons.
-- **Color discipline** — every status / data-viz / accent color comes from a NAMED helper, never a
-  hand-picked `colors.<family>[shade]`: `solid(name)` = the 500 (dots, series, meter accents);
-  `tint(name, α)` = a wash; `ramp(name, count)` = N shades of ONE family for a coherent dimension.
-  A status is ONE family NAME (`{ color: "emerald" }`) and every weight derives from it. One accent
-  per screen purpose (blue=pipeline, emerald=money, red=danger, amber=waiting). Direct `colors.*` is
-  reserved for NEUTRALS (`zinc`, `border`, `white`, the `*[50]` 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) — 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")`.
-- **Status indicators have a WEIGHT — match to prominence, never to a metric.** colored `Text` (a
-  verdict WORD in a header) < `Badge variant="dot"` (a categorical STATE in a scannable column /
-  legend) < `Badge` tonal pill (a record's PROMINENT status, a drawer/detail header). A register's
-  dense rows read lighter — the row's primary status is `variant="dot"`, its drawer twin tonal. A
-  `Badge` is never a metric value.
-- **Typography**: only the `Text` primitive (size/weight/color/transform). Uppercase tracking is
-  built in.
-- **Touch & whitespace**: anything pressable is ≥ 40px tall (8px min gap between pressables). 16px
-  between cards, 24–28 canvas padding, 16–20 inside bands, 10–12 between content lines. Density
-  comes from alignment + hierarchy, not cramming.
-
----
-
-## Worked examples (templates)
-
-Full worked-example screens ship in the package — **read the source at
-`node_modules/@lotics/ui/examples/<name>.tsx`** (pure `@lotics/ui` + mock data, each a usable
-recipe for a screen JOB; copy and adapt). Pick by the job:
-
-- **Analytics** — `tpl_dashboard` (KPIStrip + trends + attention list) · `tpl_stock`
-  (10k-record faceted funnel) · `tpl_tower` (live `StatusGrid` wallboard) · `tpl_pivot` (the
-  `Matrix` cross-tab desk: one dimension × another, number + heat per cell + row/col/grand totals,
-  press a cell to drill the list behind it) · `tpl_rollup` (hierarchical totals).
-- **Work** — every screen is FLAT (no Card) and ONE of two shapes: a register/list you
-  WORK EACH of (press a row → workspace `Drawer`) or a list you ACT ON MANY of (tick rows →
-  `FloatingActionBar`) — never a side-by-side panel. `tpl_item_list` (THE canonical register and the
-  consolidated work-list: search + a status `Select` + facet `FilterChip`s LEFT, the New CTA RIGHT in
-  one toolbar row, a `SummaryLine` below, then a sortable, Divider-separated `Table` where every row
-  carries a leading checkbox; a select-all band, footer `Pagination`, and a `FloatingActionBar` for
-  the bulk action over the ticked rows; a per-row PRINT button (the trailing action column) is the
-  row's primary action and the ⋯ its overflow; a row that can't take the bulk action gets a DISABLED
-  checkbox (here an "Awaiting docs" record — the same gating as a blocked run line) — a row press opens
-  the PRODUCTION workspace `Drawer`: a Details `DetailTable` showing every inline field type
-  (text · `InlineMemberSelect` · dates incl. optional-time · dot-select · money number · the
-  `InlineTagSelect` tag field · `InlineStatic` + System badge), a LINKED CASES section (the
-  customer's other records as `ListItem`s — the aligned row compound (title + description at
-  the column edge, its own 8px outdent; badge · fee · chevron right) — pressing one PUSHES an
-  EDITABLE workspace for that record inside the drawer via the hosted `ScreenRouter`; the
-  drawer HEADER swaps to back + the pushed id, back pops with scroll preserved), a Files section with its
-  OWN Add CTA (`FileRows` CRUD via `pickFiles` + an EXPECTED document as a ghost `FileRow
-  placeholder` with a Request action), the Payment `Ledger` (peekable fee rows + the Record-payment popover), an ACTIVITY section (the CRM touch-log shape: OUTCOME PILLS — `ChipGroup`, optional, 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), the PRIMARY Log saying WHY when disabled; below, a labelled "History" `Timeline` of outcome-typed items, newest first — an entry's attachments ride its expandable `details` as a thumbnail grid whose press opens the shared `FileGalleryModal`), and a closing `DangerZone`. Detail rows show trailing CTAs where earned (Phone → Call, Due → Today) — the case where `trailingWidth` IS set. This ONE template subsumes the old approvals / dispatch / batch / run
-  screens: register, per-row action, gated selection, and act-on-many in one) · `tpl_pick` (guided `ScanField` run — a single-focus task column with
-  the pick path collapsed into an `Accordion` below) · `tpl_allocate` (`RemainderMeter` split — a
-  source/remainder summary header over the invoice list + Apply) ·
-  `tpl_record` (THE record surface, create-then-refine: "New" = a small
-  dialog with the identity essentials + find-or-create → lands as a Draft; the surface IS the
-  editor — `RecordSummary` header over its key-fact `DetailTable` + a Details `DetailTable`
-  (one shared column grid, auto-stacking when narrow), a CUSTOMER section (TWO states, no
-  swap mode: attached = the read-only-first card — Edit/Done live in the SECTION HEADING and
-  swap the fields to inline chips, where a trailing Fetch fills contact + city from the
-  tax-ID registry, un-gating billing; Remove (danger) sits low and detaches the link → the
-  find-or-create search, whose custom row opens the create Dialog rendering the SAME
-  inline-chip table + Fetch), a FILES section (dropzone add, gallery preview, delete),
-  and a BILLING
-  section OWNED BY Accounting (gated until the record reaches that stage) in the INLINE vocabulary (each invoice a hairline-set band: charge amounts as chips
-  with the list price as ghost placeholder + a one-tap "Standard …" suggestion pill while
-  unset, "How paid…" select chips, NO per-band totals — the collect band owns the number; the
-  band's action row sits BOTTOM-RIGHT as hint → status dot → Issue, the hint naming exactly
-  what blocks (fees → method → the customer gate); an ISSUED invoice keeps its lines editable
-  and offers Re-issue — a new lookup code replaces the old, confirmed in the same Dialog;
-  validated receipt; separate refundable deposit) — and
-  the lifecycle is a HANDOFF CHAIN (Sales → Operations → Accounting → Closed): a TASKS section
-  speaking the FULL Task-list grammar — a clearable Group-by `FilterChip` (Desk/Assignee/Status)
-  + Assignee/Status filter chips derive the groups (empty groups drop; desk heads keep their
-  owner dots, assignee heads are `MemberChip`s), the add-a-task capture at the TOP landing on
-  the current desk, rows with per-task `InlineMemberSelect` assignees — EVERY desk's rows edit
-  (the stage gates the handoff and Billing, never task editing; planning ahead on a later desk
-  is normal work) — OWNER dot tags per section, per-stage handoff CTAs NEVER blocked (open
-  tasks warn + carry over); "New" is ONE CLICK → a fresh record at Sales; ALSO the settings shape: Preferences switch rows + `DangerZone`; a LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`)
-  jumps between the sections. Absorbed the
-  old order-form, inline-record, intake, settings, billing, and quick-capture templates) ·
-  `tpl_tasks` (the QUICK LIST — Apple-Reminders shape for personal lists: `CheckCircle` rows you tick +
-  expand in place to edit (`Inline*`, stable row — the meta summary never shifts on expand), colour-dot
-  tags, an attachments field (`FileThumbnailGrid` → tap a tile to the gallery for download + confirmed
-  remove + an `Add attachment` `pickFiles` button), search + a clearable group-by (✕ → ungrouped) + tag
-  filter chips, and a primary Draft-from-notes CTA `Composer → AgentRun → ChangeReview`) ·
-  `tpl_task_board` (the COLUMNS shape: a search · group-by · filter toolbar over a grouped, sortable
-  grid of inline-editable cells — assignee/due/status/tags set directly, a files cell (thumbnail glance →
-  popover grid → gallery), a **dynamic action column** (a per-row underlined action LINK driven by each
-  task's `action` descriptor — attach/approve/open, each wired in a real app to its OWN workflow: one
-  board, a different action per row; the link's pressable fills the cell to match the inline editors),
-  a trailing **`ActionMenu`** (the ⋯ overflow — a `danger` Remove + confirm; CUSTOM pressable
-  cells (files, the action link) hover with the control-surface BORDER reveal (`HOVER_BORDER`),
-  the same language as the inline-editor cells beside them — never their own background wash
-  today, more row actions later), per-group add rows that pre-set the group's field, and the same
-  Draft-from-notes CTA). Both `tpl_tasks` and `tpl_task_board`: filters/search left, primary CTA right, one
-  row; group-by holds only real dimensions, ✕ clears to ungrouped (no "Nothing" option). **`tpl_task_board` is the inline-managed
-  grouped table — MODERATE data you manage in view (group/sort/filter/edit-in-place, renders all
-  rows). For thousands+ you BROWSE, that's `tpl_item_list`'s paginated register, not this.** It builds
-  on the `DataGrid` primitive (the inline-managed grouped-table shape); it owns
-  only its data, toolbar, columns and per-group add. There is NO Task component — a task ROW varies
-  too much to bake into one, so rows compose `CheckCircle` + `InlineTextInput` + inline-editor cells
-  as **sibling** controls in a plain `View`. NEVER wrap the whole row in a `Pressable accessibilityRole="button"`
-  (for tap-to-expand) with those controls nested inside: RNW renders the row AND each control as a `<button>`,
-  so you get `<button>`s inside a `<button>` — invalid DOM + the inner controls drop out of the keyboard tab
-  order. Give "expand" its own affordance (a trailing `Pressable` over the meta/chevron), as `tpl_tasks` does.
-- **Finance** — `tpl_statements` (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, negatives in accounting parentheses, per-cell currency-free (the meta line says
-  VND once), no bars/charts. The three statements TIE — net income → retained earnings, closing
-  cash = the balance sheet's cash, the loan repayment moves the debt line — keep mock books
-  reconciled or the template teaches the wrong thing) · `tpl_report` (scope-first lookup report —
-  a header period + one-of-N dimension search drives KPIs → aligned facets w/ a `maxRows`
-  long-tail toggle → paginated register → export).
-- **Scheduling** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
-- **Agents** — *produce*: `tpl_dieline` (the design CANVAS: photo → stream → the dieline
-  reveals CENTRED on a pannable/zoomable surface, the floating composer morphing into `AgentProgress`,
-  a pinned live-edit params panel centre-right; prompt OR edit a param to iterate) ·
-  *Structure*: `tpl_lookup` (the ANSWER desk: converse left,
-  a pinned verdict panel right; a follow-up refines it) ·
-  `tpl_documents` (the DOCUMENT DESK — files on a record → the Use-AI fork: extract = the open
-  `ChangeFields` review (adds/updates/removal/conflict) + proposed order lines as `ChangeRecord`
-  cards, Keep-all + one outcome-named Apply; cross-check = display-only `Change` findings → a
-  recorded verdict; plus the Create-documents readiness checklist).
-
----
-
-## Full component inventory (import as `@lotics/ui/<module>`)
-
-text ·
-markdown (Markdown — the single canonical markdown renderer for chat, apps, and `AgentRun`; rich on web via react-markdown/remark-gfm with copyable tables, plain-text on native; takes a markdown `children` string; import `@lotics/ui/markdown.css` once for styling) ·
-card (Card · CardHeader · CardHeaderTitle · CardHeaderMeta · CardBody · CardFooter) ·
-section_heading (Section · SectionHeading · SectionHeadingTitle · SectionHeadingMeta · Subsection · SubsectionHeading · SubsectionHeadingTitle — the card-less twin of the Card family, compound, owns no margin; spacing via the Section gap (12, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold; `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title, same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3 title of a named group inside a section — heading-row siblings ride its right edge; the heading ramp is FIXED: # xxl / ## xl / ### lg, no size props) ·
-section_stack (SectionStack · SubsectionStack — divided stacks that own the between-block law: a fixed beat + hairline Divider BETWEEN blocks, skipping null children (56 for the flat page's Sections, 24 for a section's Subsections); stop hand-rolling gap + `<Divider />` pairs) · badge ·
-option_badge (OptionBadge — a select value as its configured colored badge) ·
-member_chip (MemberChip — avatar + name; the universal person render) ·
-member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
-status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · 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` ?? the `chip.remove` locale slice). Suggestion pills → `SuggestionChip`) · tabs (Tabs — switch between content sections; WAI-ARIA tablist + roving tabindex; each TabOption takes an optional `status` ColorName → a small attention dot before its label, for a tab whose area needs work) · segmented_control ·
-picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (COMPOUND single-select editable search: `Combobox` root + `ComboboxInput` + `ComboboxContent`, optional `ComboboxEmpty`/`ComboboxFooter`, `useCombobox()`; over the shared `useOptionList` engine; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
-text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
-radio_picker · counter · range_slider · date_picker · date_range_filter_field · date_calendar (Calendar — the bare month grid: `mode="single"` or `"range"` ({start,end} — two months side by side on desktop), month/year pickers + arrows, localized weekday/month names via BCP-47 `locale`, `firstDayOfWeek` (default Monday), `ref.navigateToMonth`. The engine DatePicker/DateFilter wrap in field chrome — reach for it bare only when the calendar lives permanently on the surface, not behind a field) · form_switch (FormSwitch — the FormField-labeled twin of `Switch`: toggle + clickable `label` (pressing it flips the value) + optional `description`/`error`; the settings-form boolean row. A bare toggle in a cell/toolbar → `Switch`; a full-row menu toggle → `SwitchButton`) · form_text_input (FormTextInput — `FormField` (label / description / error / optional) wrapping a `TextInputField`; the one-line labeled text field. Controls without a Form* twin just wrap in `FormField`) · switch_button (SwitchButton — the full-ROW toggle: a PressableHighlight row (optional icon + medium title left, `Switch` pinned right) where the whole row IS the switch (`accessibilityRole="switch"`, the inner Switch read-only). The settings-panel/menu row toggle; vs `Switch` (bare control) and `FormSwitch` (form stack)) · use_form (useForm — THE batch draft-form state hook: `values` = `initialValues` + an edits overlay (a revalidation refreshes untouched fields, no sync effect), `validate` (sync/async, gates submit, editing clears the field's error), `onSubmit(values, helpers)` with a re-entry-guarded `submitting`, and `changes`/`changed` — the touched-fields diff that feeds DIFF-writes (send only edited fields); `setFieldValue` (curried or direct) + `setValues`/`setFieldError`/`reset`. Pairs with the Form* family for dialog/settings forms — the draft-validate-COMMIT-together twin of the self-persisting Inline* editors) · time_picker ·
-inline_text_input · inline_number_input · inline_select · inline_member_select · inline_date_picker ·
-inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s `useInlineEdit` +
-`InlineEditView`; `InlineSelect`/`InlineMemberSelect` render the resting value like its option — `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not just text) ·
-inline_static (InlineStatic — a READ-ONLY value matching the Inline* box metrics EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column; non-interactive, NOT a disabled input; `muted`/`tabular`/`align="right"` for a number column, `weight="medium"` to emphasise a total among plain rows) ·
-record_summary (RecordSummary — the identity band of a record detail/drawer: ONE row — `title` xl semibold tabular · `subtitle` sm muted · `status` Badge slot · optional `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS never live in the header: compose them as `DetailTable`s in the sections below, the header's key facts as their own `DetailTable` right under the band on the same labelWidth/trailingWidth — `tpl_record` does this. Replaces hand-rolled record headers (mixed scales, several competing figures, color noise)) ·
-list · list_item · menu_button · menu_list_item · detail_row (DetailTable + DetailRow — the record field grid. DetailRow: label+value row for drawer/peek detail; in FORM mode (`labelWidth` set) the value column FILLS the row so a stack of inline editors all span the same width + none jumps wider on edit; optional `trailing` slot renders a right-side action/badge after the value (units belong IN the value via `InlineNumberInput format`). DetailTable: the compound parent of a row STACK — `labelWidth`/`trailingWidth`/`minHeight` (default 40, the inline-control grid) declared ONCE + the 6px row gap; with `trailingWidth` every row reserves the trailing column so value cells share one width and trailing items align at one x, like a table. RESPONSIVE with no prop: it measures its own container (onLayout, not the viewport — works inside a Drawer; the unmeasured first frame renders opacity-0 so the first PAINT is already in the right mode — no reshuffle as a drawer opens) and when the columns would crush the value cell it STACKS every row (the label above a full-width value row IN THE FORMFIELD LABEL GRAMMAR — medium, default ink — so narrow record surfaces and forms read as one vocabulary; trailing beside the value, gap 14. The components stay separate: FormField = draft controls validated + committed together; inline editors self-persist); raise `minValueWidth` (default 160) when a cell holds MORE than one editor (an amount+method pair) so the table stacks earlier. Two tables on one page share one grid by repeating the same labelWidth/trailingWidth. Worked example: `tpl_record`) · ledger (Ledger + LedgerGroup + LedgerRow + LedgerTotal — the record-level money list: charge/receipt GROUPS with sums in their headers, every figure on ONE right-aligned tabular column (all lines share the 8px inset), `peek` turns a row into a pressable door floating its particulars in an anchored popover (put links INSIDE the peek — never a button in a button; `reference` is the trailing-link alternative for static rows), LedgerTotal = the divider-set emphasized close with `zeroLabel` for settled. The financial-statement grammar at record density; worked example: `tpl_item_list` drawer) · danger_zone (DangerZone — the destructive section: a soft danger-tinted frame (`tint`/`solid`, never raw hex) + a danger heading + a description + a destructive action slot (children, e.g. a `danger` Button); sits APART at the bottom of a record/settings surface) · pressable_row ·
-check_circle (CheckCircle — the completion ring: an empty ring that springs to a filled check when done, distinct from the square checkbox; the task/to-do/checklist toggle) · checklist (Checklist + ChecklistRow — the record-scoped checklist COMPOUND: it owns GEOMETRY only (row minHeight 32, gap 12, ring/title alignment, ONE `trailingWidth` so assignee cells column-align) while content stays composed — `control` takes the CheckCircle (omit onChange = read-only ring), children the struck transparent InlineTextInput, `trailing` an InlineMemberSelect, `menu` the row's ⋯ options ({items: ActionMenuItem[], accessibilityLabel}) — Delete lives BEHIND the menu, danger-styled and last, never a bare ✕ (omit on read-only rows). NARROW surfaces (a drawer/peek checklist) put the editors on the `meta` line instead of `trailing` — the second line indents past the ring so the TITLE keeps the full width and stays readable; wide surfaces use `trailing`; never both. SUGGESTIONS are never rows: offer the commons as `SuggestionChip`s under the list (tap = materialize, ✕ = dismiss; a pill can't be mistaken for a task). Close the list with `CaptureRow`. There is deliberately NO monolithic Task component — richer task-management rows (tpl_tasks expand affordances, board cards) compose their own anatomy directly) · suggestion_chip (SuggestionChip — the dismissible SUGGESTION pill: an item the record could have but doesn't yet (a common task, an expected line) as a `Chip` whose press MATERIALIZES it (plus glyph + label, one tuned anatomy) and whose ✕ refuses it; filter out labels already present; suggestions never count in totals. Chrome via the `suggestionChip` locale slice) · capture_row (CaptureRow — the add-an-item row closing an editable list: dashed empty ring + borderless input on the item-title inset + a primary Save that appears on type; Enter commits too. Controlled: `value`/`onChangeText`/`onSubmit`. One shape wherever a list grows in place — task checklists, simple item lists) · action_menu ·
-floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
-columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
-sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Example: `tpl_task_board`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it 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 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, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover (Popover + PopoverTrigger + PopoverContent — **PopoverContent already insets its body 12px; put content directly in it, NEVER add your own padding View (that double-pads). Title/actions via PopoverHeader / PopoverFooter**) · 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), `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack` (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover (an avatar/settings menu drilling into a sub-panel); route PATTERNS, `params`, and stacked-alive screens are `screen_router`'s job. Distinct from `Popover`'s plain `PopoverHeader` children container) · tooltip ·
-alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
-CalloutText · CalloutActions) · kpi_card · kpi_strip · summary_line (SummaryLine — the light inline summary of a register/list's FILTERED view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band) · metric · trend_chip · sparkline ·
-bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
-funnel (Funnel — conversion funnel: narrowing bars + the step rate as a bold aligned headline row, count below; `orientation` vertical|horizontal, `onSelect`/`selectedKey` press-to-drill; the subset/drop-off sibling of stacked_progress_bar's whole-split) ·
-status_grid (StatusGrid + StatusLegend) · heatmap (density cross-tab — colour-only, no numbers) · matrix (Matrix — the PIVOT cross-tab: band-compound `Matrix` root + `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) + `Matrix.Legend`; the data layer `matrixTotals`/`MatrixAxisItem`/`MatrixCellRef` import from `@lotics/ui/matrix_totals`. Pick over `Heatmap` when the NUMBER and totals matter, not just where it clusters) · legend_item · remainder_meter · allocation_row ·
-scan_field · file_dropzone · files_editor (FilesEditor — THE all-in-one attachment field: FileGrid + a toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode (Select all · a Menu of Download/Share/Delete · Done; the per-tile ✕ is select-mode-only, never in the default view; `selectTileRemove={false}` drops even that so delete is menu-only) + built-in gallery (Download + inline preview; no "open in new tab") + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `selectTileRemove`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it scrolls and the toolbar pins, for a popover/drawer); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview (FilePreview — the universal inline preview: image/PDF/video/audio + Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js · `@lotics/docx` · `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that type is opened) and SHIP AS `@lotics/ui` deps (7.14.0+) — custom-code apps get PDF/Word/Excel preview with ZERO extra install. Renders to canvas/DOM, never a nested iframe — works in the sandboxed app iframe) ·
-app_icon (AppIcon — the app's launcher tile: a brand-gradient square from a `themeColor` palette token (unknown → neutral zinc) holding any Lucide icon by runtime name via DynamicIcon; `size` sm|md. One render wherever an app shows — launcher, list, picker, settings) · dynamic_icon (DynamicIcon — any Lucide icon by RUNTIME name (kebab-case string), for user/config-chosen icons a compile-time `IconName` can't express; web lazy-loads per icon, unknown name → blank. Decorative — the enclosing control carries the accessible name. A fixed, code-chosen glyph → `Icon`) · group_avatar (GroupAvatar — the first letter of `name` in a zinc rounded square (`size`, default 40); the avatar for image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`) · rotatable_image (RotatableImage — an image rotating in 90° steps that REFITS: at a quarter turn the box lays out in SWAPPED dimensions then rotates into place, so a rotated landscape fills the frame; the VIEW half of image rotation — `rotate_image` bakes the pixels for re-upload; FilePreview/ImageGallery compose it) · file_preview_types (PreviewLabels / FilePreviewProps / GalleryLabels — the shared label + prop contracts of the file-preview family; types only) · file_gallery_modal · image_gallery · use_selection (useSelection — always-on multi-select state for a register/list: the `selected` Set + `toggle`/`setAll`/`allSelected`/`indeterminate`/`count`/`clear`; selectability gating stays with the caller. The checkbox-always-visible counterpart to `use_selection_mode`) · use_selection_mode · use_section_nav (useSectionNav — scroll-spy for a LONG record surface with a left outline rail: keys in page order → {scrollRef, onScroll, register(key)→onLayout, jumpTo(key), activeKey}; rail items are `MenuButton`s (selected={activeKey===key}); section wrappers must be DIRECT children of the ScrollView content. On NARROW containers the rail becomes a PINNED bar naming the CURRENT section (the spy keeps it honest) that opens a full-page section-picker `Modal` (`MenuButton` list; Escape / the close control dismiss) — never a horizontal tab strip the thumb has to scroll. Worked example: `tpl_record`) · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
-spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
-comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
-expandable form — a composer's working state) · composer (Composer — the adaptive command/chat
-composer: a compact pill that expands for long text + attachments) · confidence (calibrated high/med/low) ·
-change_review (the COMPOUND review family — frame: ChangeReview provider/stack · ChangeReviewHeader
-(auto kept-counter over decidable entries) · ChangeReviewActions (the commit bar in the
-DialogFooter/DrawerFooter: Keep-all bottom-left (onAcceptAll for host-held field state) + Apply
-gating); sections: Change (host-owned status, labeled verbs, collapses to its ChangeSummary + Undo;
-no callbacks = display-only) · ChangeLabel · ChangeSummary · ChangeReasoning (the quiet why);
-grammar: ChangeFields (the open record form) + ChangeField (THE field: − band · value · candidates
-+ type-another-value · reasoning · per-field Keep/Drop · collapse) · ChangeRecord (THE item card:
-registers like a Change; tone wash + localized op word; verb level follows the decision level) ·
-ChangeBand (the raw ± band) · ChangeValueInput (the diff-at-rest editor); the `changeReview`
-locale slice) ·
-clarify (the agent asks back, via ChoiceList) · choice_list (ChoiceList — selectable answer options,
-the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · finding (Finding — one ranked AI-check insight: severity word · title · detail · Sources ·
-children slot — with FindingComparison, the expected-vs-actual body: labeled sides + emphasized
-delta; the `finding` locale slice) ·
-format_money · format_date · colors (solid · tint · ramp · ColorName ·
-isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback) ·
-auto_sizer (AutoSizer — measures its own box via onLayout and renders the render-prop child only once `{width,height}` exist; `autoSizeWidthOnly`/`autoSizeHeightOnly`, `onResize`. For content needing pixel dimensions before first paint — a canvas, a virtualized grid) · separator (Separator — a `Divider` pre-wrapped in vertical padding (`padding: SpacerSize`, default 8): the between-groups rule WITH breathing room — what `Stack useSeparator` inserts and what menus/popovers put between option groups; `Divider` is the bare hairline) · back_button (BackButton — the chevron-left `IconButton` (lg, secondary) heading a screen/panel: `onPress` + translated `accessibilityLabel` (default "Back"); the one go-back glyph — don't hand-roll it) · info_popover (InfoPopover — the ⓘ button opening a 280px popover of explanatory `text`; the middle ground between Tooltip (short hover label) and composing Popover (rich content) — it is what `SectionHeadingTitle.info`/`CardHeaderTitle.info` render) · shortcut_badge (ShortcutBadge — the keycap hint pill: a zinc-50 badge rendering a shortcut from a raw string or `ShortcutDescriptor` (⌘B on Mac, Ctrl+B elsewhere); null on small screens. `TextInputField shortcut` renders it built-in) · trend_footer (TrendFooter — the "Up X% vs last period" caption under a chart card: signed `value` (0 = flat), `periodLabel`, optional `detail`; `goodDirection="down"` flips green/red for metrics where down is good; SKIP it when there's no comparator. Direction words via the `trendFooter` locale slice; goes in `SectionCard footer`) · dots_indicator (DotsIndicator — three looping bouncing dots (`size`/`color`); the indeterminate "working/typing" pulse `Loading` composes; use bare beside a caption while an agent thinks. Determinate work → ProgressBar) · scroll_to_bottom (ScrollToBottom — the floating jump-to-latest circle button for a chat/feed; ONLY the affordance — the caller owns positioning, visibility, and the actual scroll) · animation_fade_in (AnimationFadeIn — the mount transition: children fade (+ optional `translateY` rise) into place on first render, once; the entrance polish Accordion/Timeline/Stepper/AgentRun rows use) · landmark (Landmark — the semantic region wrapper: `kind` banner|navigation|main|complementary|contentinfo|region maps to the matching HTML element on web for screen-reader landmark navigation, `accessibilityRole` on native; `accessibilityLabel` required for `region`) · skip_link (SkipLink — the a11y bypass link: parked off-screen until keyboard focus slides it in; `href="#targetId"` jumps past repeated nav into the main region. One per app shell, FIRST in the tree; web-only) · use_async_fn (useAsyncFn — wrap an async function into a manual-trigger mutation: `[run, {loading, data, error}]`, unmount-safe, the error lands in state AND rethrows; the pending-state engine for a submit/download/upload action) · use_hover (useHover — pointer-hover state `{hovered, hoverProps}` for raw inputs/DOM controls that lack a hovered style state; native stays false. Pressable-based controls use the built-in `hovered` state instead) · use_auto_grow_height (useAutoGrowHeight — the grows-with-content textarea engine ({minLines,maxLines} → container height + `scrollEnabled` at the cap); powers Composer and multiline TextInputField — reach for it only when hand-rolling a growing input) · overlay_scope (isOverlayScopeActive / 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 is open. Lives in the primitives — never call it from a screen) · route_matching (pure `:param` route-pattern utilities — routeMatches / parseRouteParams / findBestPattern (exact beats parameterized); the matching core under ScreenRouter/Dialog) · text_utils (text/typography plumbing: `getTextColor` (the TextColor→hex map incl. the AA-cleared valence set), the Inter `fontFamily*` stacks, and `getInputTextStyle`/`getInputLineHeight` — the 16px-mobile/14px-desktop input contract that stops Safari iOS auto-zoom; only for hand-rolled raw inputs) · use_focus_ring (useFocusRing — keyboard-aware focus state for painting a control's own ring; see Focus rings) ·
-focus_ring_pressable (FocusRingPressable — a Pressable that rings on keyboard focus; the raw-control default) ·
-control_surface (CONTROL_HEIGHT · CONTROL_RADIUS · FOCUS_RING · chipSurfaceStyle — the shared control-surface tokens).
+The component kit for Lotics custom-code apps and the product frontend: React-Native-Web
+primitives (renders on web **and** native), data-entry patterns, AI surfaces, a composition
+grammar, and worked-example screens. It pairs with **`@lotics/app-sdk`** (data + RPC — read
+`node_modules/@lotics/app-sdk/AGENTS.md`): the SDK fetches/mutates, this kit draws.
+
+This file is the index. The comprehensive references live in **`docs/`** — read the owning area
+doc before building any screen, **never from memory**. Exact props are the shipped sources
+(`src/<name>.tsx`); full worked screens are `examples/tpl_*.tsx`.
+
+## The area references
+
+| Doc | Read it for |
+|---|---|
+| [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. 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, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments, stage gates. |
+| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI proposes, the human decides — composer, live run feed (`AgentRun`), review-before-apply, findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
+| [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). |
+
+## Iron rules
+
+- **Reuse first; the catalog can lag `src/`.** Before hand-rolling ANY capability, `ls src/` and
+  grep for a match — a component in `src/` missing from the catalog is a doc bug to fix, not a
+  license to hand-roll.
+- **One canonical component per data role** (member → `MemberChip`, select → `OptionBadge`,
+  files → `FilePreview` family, …) — the catalog's Reach-by-role outranks neighboring code.
+- **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.
+- **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
+  callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
+- **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
+
+## Keeping this reference current
+
+These docs publish to npm and are read from `node_modules` by authors who cannot see this repo.
+**Codify every new component, pattern, or rule into its OWNING area doc + the index above in the
+same change, and bump the package version** — a `src/` export absent from
+[docs/catalog.md](./docs/catalog.md) WILL be hand-rolled by the next author. New shapes that prove
+themselves graduate into `src/` + an `examples/tpl_*` + a catalog entry, so every app inherits
+them. Each fact lives in exactly one doc — link, never duplicate.