@lotics/ui 7.8.0 → 7.10.0

package/AGENTS.md

@@ -69,7 +69,8 @@ Pick by capability, not by name. (→ the source file for the API.)
   via `TimePicker`.
 - **Edit a record's fields in place** — the `Inline*` family: `InlineTextInput` ·
   `InlineNumberInput` · `InlineSelect` · `InlineMemberSelect` · `InlineDatePicker` ·
-  `InlineTimePicker` (see §Data entry).
+  `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** — there is NO Task component (a task row varies too much app-to-app to abstract
   well — a Reminders row and a Linear column-grid share almost nothing). Compose the row directly:
   `CheckCircle` (the completion ring — fills with a spring, distinct from the square `Checkbox`) + an
@@ -80,7 +81,7 @@ Pick by capability, not by name. (→ the source file for the API.)
   - **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_dossier`. Never an HTML `<table>` or a `.map` of rows.
+    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` /
@@ -91,8 +92,9 @@ Pick by capability, not by name. (→ the source file for the API.)
     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 examples: `tpl_task_board` (with a `CheckCircle` leading), `tpl_pipeline` (no leading).
-- **Numbers & charts** — `KPIStrip` / `KPICard` / `Metric` (headline figures), `TrendChip`
+    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` / `StackedProgressBar` / `StepProgress`, `Breakdown`
   (a stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
@@ -111,10 +113,11 @@ Pick by capability, not by name. (→ the source file for the API.)
   `CardFooter`), `Section` (the card-less twin of `Card`: bare gap-spaced region + `SectionHeading`/
   `SectionHeadingTitle`/`SectionHeadingMeta`; no body component — children are the body), `SectionCard`,
   `PageHeader` /
-  `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`.
+  `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), `ListItem`, `MenuButton`,
-  `MenuListItem`, `DetailRow` (label+value for drawers/peeks), `ActionMenu` (⋯), `FloatingActionBar`
-  (bulk-select bar).
+  `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`/
@@ -187,15 +190,22 @@ hover reveals its border (it's a field — no grey tint, no pencil that shifts),
 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; `renderSelected` renders the RESTING value as a
-node — a colored `OptionBadge`, not just a label) · `InlineMemberSelect` (a `MemberChip` at rest →
+`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`) · `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` — 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. Pair with `DetailRow` (label left, inline value right). Not every field
-is a same-height swap — a tag field, a status, or an attachment grid edit in place too (below).
+without losing the edit. Pair with `DetailRow` (label left, inline value right). 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 exactly (height, padding, 1px transparent border) but is non-interactive, so
+it sits FLUSH with the editors instead of reading as a disabled input. To hang a right-side
+action/badge/unit off a row, use `DetailRow`'s `trailing` slot (wrap the editor in a `flex:1` View
+so it takes the slack and the trailing pins right) — see the "Row anatomy" section of
+`tpl_record_plain`, which also reads top→bottom as a full drawer record (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,
@@ -489,9 +499,9 @@ decisions, or a ranked set, don't cram it into chat prose. Each pairs a template
 - **Match** (`tpl_match`, body-first `ReviewCard` + `MatchSides`) — the agent proposes PAIRINGS with
   its reasoning; each is a `ReviewCard` (no title, so body-first) whose body is a two-sided `MatchSides`
   pairing (source → proposed counterpart), with the confidence + reason beneath, accept / reassign /
-  reject, high-confidence batch-accept. The AI reconciliation / dedup / correlation queue. (The
-  deterministic cousin
-  `tpl_reconcile` has no agent reasoning — that's the tell for which to reach for.)
+  reject, high-confidence batch-accept. The AI reconciliation / dedup / correlation queue. (Strip the agent's
+  reasoning and it would be a plain deterministic match register — the reasoning is the tell for when
+  you need this.)
 - **Briefing** (`tpl_briefing`, `Finding`) — a generated narrative over the data + a RANKED list of
   what needs attention, each finding carrying a severity, a metric, its sources, and one action. The
   leadership digest / anomaly scan — the agent's COMMENTARY, not a raw dashboard.
@@ -616,10 +626,21 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   </Card>
   ```
   Never nest cards; never hand-compose a title or footer band. `info` is standard, not garnish.
-- **The stat band**: `<KPIStrip items={[{label, value, trend?, caption?, tone?, info?}…]}>` is the
-  ONE way to open a screen with numbers. KPI strips are INFORMATIONAL — they never filter or
-  navigate (that's the tabs/chips' job), and they carry cross-cutting health numbers the tabs
-  can't show; if there are none, drop the strip. Card stat rails use `KPICard`.
+- **Flat work execution 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, the worklists an operator acts on — are FLAT:
+  the register/list sits DIRECTLY on the white canvas with no Card wrapper; separation comes from
+  the row wash, gaps, and `Divider`/`CardHeader`/`CardFooter` bands used BARE. 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.
+- **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). Dates: `formatDate(value, opts)` from
   `@lotics/ui/format_date` — the date-VALUE formatter. `format` (date STYLE) ∈ `date` (22/05/2026) ·
@@ -642,13 +663,22 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   `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). Two row patterns, never un-separated:
-  · **Register (default)** — px-20 square rows, wash to the card edges, separated by full-bleed
-    `Divider`s (`{i > 0 ? <Divider/> : null}`), NO wrapping padding. A COLUMNAR register is
-    `Table`/`TableRow`/`TableCell` (columns defined once → header + widths can't drift); paginate
-    OUTSIDE (slice + `Pagination` in the `CardFooter`).
-  · **Inset contained list** — grouped/gap-separated lists: `PressableRow variant="inset"` in a
-    padded container, NO `Divider`s (the gap + rounded hover separate them).
+  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). 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 =
@@ -667,6 +697,15 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   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. 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
@@ -700,6 +739,10 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     (`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.
@@ -744,12 +787,19 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   paginated register → export) · `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 execution** — `app_orders` (stage-gated work queue) · `tpl_crm_desk` (assign & work +
-  `FloatingActionBar`) · `tpl_callsheet` (call console) · `tpl_convert` (staged conversion) ·
-  `tpl_inventory` (threshold actions) · `tpl_dossier` (high-volume paginated register) ·
-  `tpl_approvals` (verdicts: bulk + over-policy `Dialog`) · `tpl_reconcile` (pair matching) ·
-  `tpl_dispatch` (capacity allocation) · `tpl_batch` (compose from parts) · `tpl_pick` (guided
-  `ScanField` run) · `tpl_allocate` (`RemainderMeter` split) · `tpl_run` (preview → resolve → post) ·
+- **Work execution** — 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" case — the same gating as a blocked run line) — a row press opens
+  the workspace `Drawer`. 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_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
@@ -762,13 +812,11 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   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
   today, more row actions later), per-group add rows that pre-set the group's field, and the same
-  Draft-from-notes CTA) · `tpl_pipeline` (the SAME inline-managed grouped-table shape, a second domain — deals grouped by
-  stage with a money-value cell + owner + close-date edited inline, its own Draft-from-notes CTA drafting
-  deals; proof the shape generalizes beyond tasks). All three: filters/search left, primary CTA right, one
-  row; group-by holds only real dimensions, ✕ clears to ungrouped (no "Nothing" option). **`tpl_task_board` + `tpl_pipeline` are the inline-managed
+  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_dossier`'s paginated register, not this.** Both build
-  on the `DataGrid` primitive (the grid shape, extracted once these two uses confirmed it); each owns
+  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"`
@@ -779,7 +827,7 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   transactional form: find-or-create + line items + attachment CRUD + 2-col grid) · `tpl_billing`
   (charges→invoice→collect: the invoice DOCUMENT is the unit — editable charge lines + method,
   live total, status, inline-gated issue; validated receipt; separate deposit) · `tpl_quick`
-  (quick-capture log) · `tpl_wizard` (`Stepper` form + review) · `tpl_record` (inline edit + Stage
+  (quick-capture log) · `tpl_wizard` (`Stepper` form + review) · `tpl_record_plain` (inline edit + Stage
   disposition + `Select` tags + Documents grid; `tpl_record_plain` = card-less).
 - **Records & lookup** — `tpl_detail` (full record + tabs) · `tpl_directory` (searchable register) ·
   `tpl_timeline` (audit feed).
@@ -817,20 +865,21 @@ text_input_field · number_input · search_input · form_field · checkbox · ch
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · 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` take `renderSelected` for a chip/badge at rest) ·
-list · list_item · menu_button · menu_list_item · detail_row · pressable_row ·
+`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) ·
+list · list_item · menu_button · menu_list_item · detail_row (DetailRow — label+value row for drawer/peek detail; optional `trailing` slot renders a right-side action/badge/unit after the value) · 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. Compose task rows directly, no Task component) · 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. Examples: `tpl_task_board`, `tpl_pipeline`) · 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) ·
+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) · popover · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
-CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
+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) + built-in gallery (Download + inline preview; no "open in new tab") + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `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 are LAZY (dynamic-imported, ~free until a doc of that type is opened) so custom-code APPS can use it too — they just add `@lotics/docx` + `@lotics/xlsx` to their deps. Renders to canvas/DOM, never a nested iframe — works in the sandboxed app iframe) ·
-file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
+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 · 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

package/examples/tpl_allocate.tsx

@@ -5,7 +5,7 @@ import { colors } from "@lotics/ui/colors";
 import { AllocationRow } from "@lotics/ui/allocation_row";
 import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
-import { Card, CardFooter } from "@lotics/ui/card";
+import { CardFooter } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
 import { RemainderMeter } from "@lotics/ui/remainder_meter";
 import { formatMoney } from "@lotics/ui/format_money";
@@ -63,7 +63,7 @@ export function TplAllocate() {
       : "Payment fully applied across the selected invoices";
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 1000, alignSelf: "center", gap: 16 }}>
         {/* header */}
         <View style={{ gap: 2 }}>
@@ -72,7 +72,7 @@ export function TplAllocate() {
         </View>
 
         {/* the source — the payment, and the remainder as you place it */}
-        <Card style={{ padding: 0 }}>
+        <View>
           <View style={{ padding: 20, flexDirection: "row", alignItems: "flex-start", gap: 24, flexWrap: "wrap" }}>
             <View style={{ gap: 2, flexGrow: 1, flexBasis: 220 }}>
               <Text size="xs" color="muted" transform="uppercase">Payment received</Text>
@@ -87,10 +87,10 @@ export function TplAllocate() {
               </View>
             </View>
           </View>
-        </Card>
+        </View>
 
         {/* the targets — the open invoices, each absorbing part of the payment */}
-        <Card style={{ padding: 0 }}>
+        <View>
           <View style={{ paddingHorizontal: 20, paddingVertical: 12 }}>
             <Text size="xs" color="muted" transform="uppercase">{`Open invoices · ${INVOICES.length}`}</Text>
           </View>
@@ -113,7 +113,7 @@ export function TplAllocate() {
             <Text size="xs" color={over ? "danger" : "muted"} style={{ flex: 1 }}>{status}</Text>
             <Button title="Apply payment" color="primary" disabled={over || allocated === 0} onPress={() => {}} />
           </CardFooter>
-        </Card>
+        </View>
       </View>
     </ScrollView>
   );

package/examples/tpl_assistant.tsx

@@ -84,7 +84,7 @@ export function TplAssistant() {
   };
 
   return (
-    <View style={{ flex: 1, backgroundColor: colors.zinc[50] }}>
+    <View style={{ flex: 1, backgroundColor: colors.white }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12, borderBottomWidth: 1, borderBottomColor: colors.zinc[200], backgroundColor: colors.background }}>
         <View style={{ width: 24, height: 24, borderRadius: 7, alignItems: "center", justifyContent: "center", backgroundColor: colors.zinc[100] }}>
           <View style={{ width: 4, height: 4, borderRadius: 2, backgroundColor: colors.zinc[900] }} />

package/examples/tpl_attendance.tsx

@@ -269,7 +269,7 @@ export function TplAttendance() {
   const seqIndex = openNv ? sorted.findIndex((nv) => nv.id === openNv.id) : -1;
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 920, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>

package/examples/tpl_billing.tsx

@@ -233,7 +233,7 @@ export function TplBilling() {
   };
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 640, alignSelf: "center", gap: 16 }}>
         <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
           <Text size="xl" weight="semibold">Billing</Text>
@@ -299,7 +299,7 @@ export function TplBilling() {
 
           {/* deposit band — tinted + labelled separate, never part of the total */}
           <Divider />
-          <CardBody style={{ backgroundColor: colors.zinc[50], gap: 8 }}>
+          <CardBody style={{ backgroundColor: colors.white, gap: 8 }}>
             <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
               <Text weight="semibold">Deposit</Text>
               <Badge label="Collected separately" color="zinc" />

package/examples/tpl_briefing.tsx

@@ -54,7 +54,7 @@ export function TplBriefing() {
   const attention = findings.filter((f) => f.severity === "critical" || f.severity === "warning").length;
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 860, alignSelf: "center", gap: 16 }}>
         <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 16 }}>
           <View style={{ flex: 1, gap: 2 }}>

package/examples/tpl_calendar.tsx

@@ -204,7 +204,7 @@ export function TplCalendar() {
 
   return (
     <View style={{ flex: 1 }}>
-      <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
         <View style={{ width: "100%", maxWidth: 1040, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>

package/examples/tpl_compare.tsx

@@ -90,7 +90,7 @@ export function TplCompare() {
   const pick = OPTIONS.find((o) => o.id === chosen) ?? null;
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 720, alignSelf: "center", gap: 16 }}>
         <View style={{ gap: 2 }}>
           <Text size="xl" weight="semibold">Freight options</Text>

package/examples/tpl_crosscheck.tsx

@@ -72,7 +72,7 @@ export function TplCrosscheck() {
   const openCount = SEED.length - resolvedCount;
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 760, alignSelf: "center", gap: 16 }}>
         <View style={{ gap: 2 }}>
           <Text size="xl" weight="semibold">Document cross-check</Text>

package/examples/tpl_dashboard.tsx

@@ -306,7 +306,7 @@ export function TplDashboard() {
   const ky = (key ? KY_DU_LIEU[key] : undefined) ?? KY_DU_LIEU[KY_CUOI];
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 960, alignSelf: "center", gap: 16 }}>
         {/* header band — the period filter lives here: presets + custom
             range in the popover (and time, via includeTime, where a

package/examples/tpl_detail.tsx

@@ -191,7 +191,7 @@ export function TplDetail() {
   const [tab, setTab] = useState<string>("tongquan");
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 880, alignSelf: "center", gap: 16 }}>
         {/* breadcrumb line */}
         <Text size="xs" color="muted">Orders / SO-2026-0042</Text>

package/examples/tpl_dieline.tsx

@@ -164,7 +164,7 @@ export function TplDieline() {
   };
 
   return (
-    <View style={{ flex: 1, backgroundColor: colors.zinc[50] }}>
+    <View style={{ flex: 1, backgroundColor: colors.white }}>
       {/* slim top bar */}
       <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12, borderBottomWidth: 1, borderBottomColor: colors.zinc[200], backgroundColor: colors.background }}>
         <Text size="sm" weight="semibold" style={{ flex: 1 }}>Carton design</Text>
@@ -341,7 +341,7 @@ function EmptyFrame() {
 
 function BuildingFrame() {
   return (
-    <View style={[frame.box, { backgroundColor: colors.zinc[50] }]}>
+    <View style={[frame.box, { backgroundColor: colors.white }]}>
       <DotsIndicator size={9} color={colors.zinc[900]} />
       <Text size="sm" color="muted">Designing your dieline…</Text>
     </View>

package/examples/tpl_directory.tsx

@@ -170,7 +170,7 @@ export function TplDirectory() {
   const seqIndex = openPartner ? matches.findIndex((p) => p.id === openPartner.id) : -1;
 
   return (
-    <View style={{ flex: 1, backgroundColor: colors.zinc[50] }}>
+    <View style={{ flex: 1, backgroundColor: colors.white }}>
       <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 28 }}>
         <View style={{ width: "100%", maxWidth: 880, alignSelf: "center", gap: 16 }}>
           {/* header band */}
@@ -225,7 +225,7 @@ export function TplDirectory() {
             </FilterChip>
           </View>
 
-          {/* the register: one card, hairline-separated rows */}
+          {/* the register: one card, gap-separated rounded `register` rows (no per-row Divider) */}
           <Card style={{ padding: 0 }}>
             {matches.length === 0 ? (
               <EmptyState
@@ -233,12 +233,9 @@ export function TplDirectory() {
                 hint="Try another keyword or switch the type filter"
               />
             ) : (
-              <View style={{ paddingVertical: 6 }}>
-                {matches.map((p, i) => (
-                  <View key={p.id}>
-                    {i > 0 ? <Divider /> : null}
-                    <PartnerRow p={p} selected={p.id === openId} onPress={() => setOpenId(p.id)} />
-                  </View>
+              <View style={{ paddingVertical: 6, gap: 2 }}>
+                {matches.map((p) => (
+                  <PartnerRow key={p.id} p={p} selected={p.id === openId} onPress={() => setOpenId(p.id)} />
                 ))}
               </View>
             )}

package/examples/tpl_draft.tsx

@@ -73,7 +73,7 @@ export function TplDraft() {
   const streamed = phase === "drafting" ? target.split(" ").slice(0, revealed).join(" ") : "";
 
   return (
-    <ScrollView style={{ backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28, paddingBottom: 80 }}>
+    <ScrollView style={{ backgroundColor: colors.white }} contentContainerStyle={{ padding: 28, paddingBottom: 80 }}>
       <View style={{ maxWidth: 720, width: "100%", alignSelf: "center", gap: 16 }}>
         <View style={{ gap: 2 }}>
           <Text size="xl" weight="semibold">Reply to inquiry</Text>
@@ -134,7 +134,7 @@ export function TplDraft() {
               ) : null}
 
               {phase === "drafting" ? (
-                <View style={{ borderWidth: 1, borderColor: colors.zinc[200], borderRadius: 10, padding: 14, gap: 10, backgroundColor: colors.zinc[50] }}>
+                <View style={{ borderWidth: 1, borderColor: colors.zinc[200], borderRadius: 10, padding: 14, gap: 10, backgroundColor: colors.white }}>
                   <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
                     <Text size="xs" color="muted" weight="medium" style={{ flex: 1 }}>Drafting</Text>
                     <DotsIndicator size={5} color={colors.zinc[900]} />

package/examples/tpl_extract.tsx

@@ -113,7 +113,7 @@ export function TplExtract() {
   const confirmedCount = RECORDS.filter((r) => statuses[r.id] === "confirmed").length;
 
   return (
-    <ScrollView style={{ backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28, paddingBottom: 120 }}>
+    <ScrollView style={{ backgroundColor: colors.white }} contentContainerStyle={{ padding: 28, paddingBottom: 120 }}>
       <View style={{ maxWidth: 720, width: "100%", alignSelf: "center", gap: 16 }}>
         <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 16 }}>
           <View style={{ flex: 1, gap: 2 }}>

package/examples/tpl_intake.tsx

@@ -70,7 +70,7 @@ export function TplIntake() {
       : undefined;
 
   return (
-    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+    <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 880, alignSelf: "center", gap: 16 }}>
         {/* header band */}
         <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 12 }}>