@lotics/ui 11.4.0 → 11.6.0

package/docs/catalog.md

@@ -0,0 +1,920 @@
+# @lotics/ui — component catalog
+
+The complete inventory of the kit, in two passes: **Reach by role** maps each data role /
+job (actions, members, selects, dates, files, money, status, …) to the ONE canonical
+component, and the **Full import inventory** lists every `@lotics/ui/<module>` entry point
+with its purpose. Read this before building any screen — reuse first; a component absent
+from this catalog does not exist, and one present here must never be hand-rolled. The
+composition patterns (data entry, AI review, templates) live in the sibling area docs
+indexed in [AGENTS.md](../AGENTS.md).
+
+## How to read a component's API
+
+- **Compose with React Native primitives**: `View` / `ScrollView` from `react-native` (never
+  `div`/`span`), style with RN style objects (not CSS), and render every string through the `Text`
+  primitive — the kit renders on web **and** native.
+- **Import per module**: `import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox"`.
+  There is no barrel — every module below is its own entry point.
+- **The exact API is the source, which ships with the package**: read
+  `node_modules/@lotics/ui/src/<module>.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.
+- Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `OptionList`) needs a
+  `PortalHost` (`@lotics/ui/portal`) at the app root.
+- Worked examples referenced below (`tpl_record`, `tpl_item_list`, …) ship in
+  [`../examples/`](../examples/).
+
+---
+
+## Reach by role — what exists
+
+Pick by capability, not by name. (→ the source file for the API.)
+
+### Actions
+
+`Button` (labelled; `title` is MANDATORY — the type blocks a title-less Button; `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 — md/sm keep a 40px touch
+target via hitSlop — 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` — a real web anchor) — 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 (`onPress` only — the consumer wires
+the opener, e.g. the app SDK's `openExternal`); `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 option-list 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 and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`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; 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 the data-entry patterns doc indexed in
+[AGENTS.md](../AGENTS.md)).
+
+### Text & form
+
+`TextInputField`, `NumberInput`, `SearchInput`; wrap with `FormField`; `Checkbox`, `Switch`,
+`RadioPicker`; dates via `DatePicker` / `DateRangeFilterField`, times via `TimePicker`.
+Batch draft-form state → `useForm`.
+
+### Edit a record's fields in place
+
+The `Inline*` family: `InlineTextInput` · `InlineNumberInput` · `InlineSelect` ·
+`InlineMemberSelect` · `InlineTagSelect` · `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). A stack of labelled field rows lives in
+`DetailTable` + `DetailRow`; the record's identity band is `RecordSummary`; its money
+summary is `Ledger`.
+
+### 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`](../examples/tpl_tasks.tsx) (quick list) and
+[`tpl_task_board`](../examples/tpl_task_board.tsx) (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`](../examples/tpl_record.tsx) /
+[`tpl_item_list`](../examples/tpl_item_list.tsx).
+
+### Tabular data — pick by SCALE + intent
+
+Two columnar shapes, and the choice is about data size:
+
+- **High-volume register** (thousands+ you BROWSE) — `Table` (columns defined once; sortable
+  headers via `SortHeader`; paired with `Pagination`) + read-only rows that open a `Drawer`
+  to edit. It scales by PAGING — renders one page, never the whole set — so you FILTER +
+  search, you don't group. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx).
+  Never an HTML `<table>` or a `.map` of rows. The register adapts to its container on its
+  own — hides columns by `priority`, stacks rows below the two-column floor (see the `table`
+  inventory entry) — so a narrow screen or panel needs NO branching; compose a hand-designed
+  card pile (`PressableRow` + your own hierarchy) over `useScreenSize` only when a screen
+  deserves a better mobile shape than the automatic stack.
+- **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` from `@lotics/ui/sort_header`, 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`](../examples/tpl_task_board.tsx) (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` (from `@lotics/ui/section_heading` — 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`,
+`ColumnFilter` (the typed per-column filter pill + `columnFilterToConditions`).
+
+### 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), `Peek` (drill-down popover on an inline
+reference), `InfoPopover` (the ⓘ explainer).
+
+### 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`. 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`; picking is `pickFiles`
+(`@lotics/ui/file_picker` — opens the browser picker and resolves the chosen `File[]`, the
+imperative half behind every Add-file CTA); for gated CRUD compose locally with
+`useSelectionMode` + `shareOrDownloadFiles` + `rotateImageToBlob` (see the data-entry
+patterns doc indexed in [AGENTS.md](../AGENTS.md)).
+
+### 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` (the `calendar` module's views), `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 the AI-patterns doc indexed in
+[AGENTS.md](../AGENTS.md) 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. Display-only — it informs the
+verdict the host records; `finding` locale slice).
+
+---
+
+## Full import inventory
+
+Every published entry point, grouped by area. Import as `@lotics/ui/<module>`; the module's
+source (`src/<module>.tsx`/`.ts`) is the API reference.
+
+### Text & formatting
+
+- **`text`** — the `Text` primitive (never raw `div`/`span`/`fontSize`): `size` `xs`–`xxxl`
+  (the heading ramp: `xl` = `##` section title, `xxl` = `#` page/record title, `xxxl` = hero
+  numbers), `weight`, `color`, alignment, tabular numerals.
+- **`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.
+- **`markdown.css`** — import once for the web markdown styling.
+- **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle`.
+- **`format_money`** — `formatMoney` / `formatCompactNumber`.
+- **`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.
+
+### Theming, locale & tokens
+
+- **`theme`** — `LoticsThemeProvider` / `useLoticsTheme` + `DEFAULT_ACCENT`: the single
+  brand accent (OKLCH blue by default) that chart fills, hero CTAs, and focus rings read.
+- **`locale`** — `LoticsLocaleProvider` / `useLoticsLocale` + the shipped `en` (default) and
+  `vi` packs. Set the language ONCE at the root; wired components resolve **prop → provider
+  locale → English default**. **Limitation:** the calendar/gantt views and the comment
+  labels are not yet provider-wired — pass their `labels` props directly.
+- **`colors`** — the palette + `withAlpha` · `solid` · `tint` · `ramp` · `ColorName` ·
+  `isColorName` · `asColorName` (coerce a stored option/status token to a `ColorName`,
+  neutral fallback).
+- **`tokens`** — design tokens: re-exports `colors` plus `space`/`type`/`weight`/`radius`
+  scales and `getCssVariables()` — an OPT-IN serializer to `--lotics-*` CSS variables for
+  hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
+  don't need them).
+- **`spacing`** — the `SPACE` scale + `SpaceToken`.
+- **`control_surface`** — `CONTROL_HEIGHT` (40) · `CONTROL_RADIUS` (10) · `FOCUS_RING` ·
+  `HOVER_BORDER` · `CONTROL_TRANSITION` · `chipSurfaceStyle` — the shared control-surface
+  tokens.
+- **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
+  every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
+  to system fonts.
+- **`index.css`** — CSS custom properties (`--font-size-*`, `--input-font-size`, …) for
+  hand-rolled DOM surfaces; components don't require it.
+
+### Icons & identity
+
+- **`icon`** — `Icon` + `IconName`: the curated lucide set for a fixed, code-chosen glyph.
+  The set is deliberately partial — a missing glyph is added to the kit (deep import + map
+  entry), never assumed to exist.
+- **`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`.
+- **`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.
+- **`avatar`** — `Avatar`: image-or-initial person avatar (`source`/`name`/`size`;
+  `announce` when standalone — decorative by default because the name text usually sits
+  beside it).
+- **`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`.
+- **`wave_avatar`** — `WaveAvatar`: decorative animated waveform avatar (voice/audit
+  history); animates on web, renders a static fallback on native.
+- **`member_chip`** — `MemberChip`: avatar + name; the universal person render.
+
+### Layout & surfaces
+
+- **`card`** — `Card` · `CardHeader` · `CardHeaderTitle` (+ `info` ⓘ popover) ·
+  `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`** — a SECOND, standalone `Section`: a self-contained titled block
+  (`title`/`description`/`collapsible`/`icon`/`titleRight`, imperative
+  `SectionHandlers.expand/collapse`). **Warning:** two modules export a `Section` — the
+  layout grammar's card-less region is the one in `section_heading`; import from
+  `@lotics/ui/section` only when you specifically want this collapsible titled block.
+- **`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.
+- **`section_card`** — `SectionCard`: a titled card with a one-line description and an
+  optional hairline-set `footer` (where `TrendFooter` and source notes go).
+- **`stack`** — `Stack`: gap-spaced row/column; `useSeparator` inserts `Separator`s between
+  children.
+- **`spacer`** — `Spacer` + `SpacerSize` (the fixed size scale).
+- **`divider`** — `Divider`: the bare hairline.
+- **`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.
+- **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
+  `CONTAINER_SIZES`).
+- **`page_header`** — `PageHeader`: the page's title band.
+- **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
+  region.
+- **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
+  expandable section rows.
+- **`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`** — `SegmentedControl`: the exclusive small-set switch.
+- **`danger_zone`** — `DangerZone`: the destructive section — a soft danger-tinted frame
+  (the kit's `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.
+- **`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.
+- **`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.
+
+### Actions, links & menus
+
+- **`button`** — `Button`: the labelled action; `title` MANDATORY (it is the accessible
+  name), `color` = emphasis/risk.
+- **`icon_button`** — `IconButton`: the icon-only circular action (see
+  [Actions](#actions)).
+- **`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.
+- **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
+  `onPress` only (the consumer wires the opener).
+- **`text_link`** — `TextLink`: underlined text that's optionally an `onPress` action or an
+  `href` link (a real `<a>` on web — middle-click / open-in-new-tab work), or plain
+  underlined text to wrap in your own pressable; inherits every `Text` prop; the neutral
+  counterpart to the fixed-blue `Link`.
+- **`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`.
+- **`action_menu`** — `ActionMenu`: the ⋯ overflow menu (`ActionMenuItem[]`; danger items
+  last).
+- **`menu_button`** — `MenuButton`: the menu/rail row (icon · title · `right` slot;
+  `selected`/`focused`/`danger`; `role` menuitem|button|option) — popover menus, outline
+  rails, section pickers.
+- **`menu_list_item`** — `MenuListItem`: the richer listbox/menu row (title + description +
+  `right`; `selected` vs roving `focused` via `aria-activedescendant`).
+- **`floating_action_bar`** — `FloatingActionBar`: the floating bulk-select action bar.
+- **`pressable_row`** — `PressableRow`: THE register row — full-width hover/open wash,
+  `selected` (the open record) vs `marked` (ticked in bulk-select), forwards `ref` for
+  popover anchoring.
+- **`pressable_highlight`** — `PressableHighlight`: the hover-wash + keyboard-focus-ring
+  `Pressable` under `MenuButton`/`Switcher`/custom pressable surfaces; its style-fn/children
+  receive `hovered` + `focusVisible`.
+- **`focus_ring_pressable`** — `FocusRingPressable`: a Pressable that rings on keyboard
+  focus; the raw-control default.
+- **`card_select_item`** — `CardSelectItem`: a bordered, card-shaped button; `selected` =
+  persistent ring (reads as `aria-pressed`) — the org-picker / entity-switcher item.
+- **`switcher`** — `Switcher`: current-item trigger opening a popover of `MenuButton` items
+  (`SwitcherItem { id, label }`, `currentId`, `onSelect`) — the compact entity/workspace
+  switcher.
+- **`count`** — `Count`: a small circular count bubble (`color` highlight|muted|red).
+- **`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.
+- **`keyboard`** — `isMac` · `ShortcutDescriptor` · `formatShortcut` (platform-aware
+  shortcut formatting behind `ShortcutBadge`).
+
+### Badges, status & feedback
+
+- **`badge`** — `Badge`: the tonal pill; `variant="dot"` = pill-less colored dot + label,
+  the LIGHT state indicator.
+- **`status_badge`** — `StatusBadge`: an enabled/disabled pulse badge (`enabled` + `label`).
+- **`option_badge`** — `OptionBadge`: a select value as its configured colored badge.
+- **`callout`** — `Callout` · `CalloutTitle` · `CalloutText` · `CalloutActions` (`tone`
+  info|success|warning|error|neutral): inline status band.
+- **`empty_state`** — `EmptyState`: centered placeholder for an empty list/filter result —
+  `message` + `hint`, optional `icon` anchor and `action` CTA.
+- **`completion_state`** — `CompletionState`: the "all done" terminal state.
+- **`skeleton`** — `Skeleton`: loading placeholder blocks.
+- **`loading`** — `Loading`: the centered indeterminate loading state (composes
+  `DotsIndicator`).
+- **`activity_indicator`** — `ActivityIndicator`: the bare spinner.
+- **`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`.
+- **`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.
+
+### Pickers & selection controls
+
+- **`picker`** — `Picker`: native `<select>`, plain label-only single, native typeahead;
+  also home of the shared `PickerOption` type.
+- **`select`** — `Select`: rich/custom-rendered, single/multi, select-all, chips via
+  `renderSelected(item, { remove })` + `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 option-list engine; browses on focus; no `multi` —
+  multi-value chips → `Select multi`.
+- **`member_select`** — `MemberSelect` + `MEMBER_UNASSIGNED`: the member picker (a `Select`
+  of `MemberChip` options; `unassignedLabel` prepends the unassigned option).
+- **`radio_picker`** — `RadioPicker`: labelled radio group for a small visible single
+  choice.
+- **`chip_group`** — `ChipGroup`: pill single-select over a small visible set.
+- **`checkbox`** — `Checkbox`: the bare square check control.
+- **`checkbox_input`** — `CheckboxInput`: checkbox + label as one labelled control.
+- **`switch`** — `Switch`: the bare toggle (a cell/toolbar boolean).
+- **`counter`** — `Counter`: increment/decrement numeric stepper (filter facet).
+- **`range_slider`** — `RangeSlider` + `rangeSummary`: min–max range control (filter facet).
+
+### Form & text inputs
+
+- **`text_input_field`** — `TextInputField`: the standard text input (multiline grows via
+  the auto-grow engine; `shortcut` renders a `ShortcutBadge`).
+- **`number_input`** — `NumberInput`: numeric input; `format` for currency/units.
+- **`search_input`** — `SearchInput`: the search box for toolbars/filters.
+- **`form_field`** — `FormField` + `useFormField`: label / description / error / `optional`
+  marker wrapper; the fieldset grid cell (`half`/`full` widths — see the data-entry patterns
+  doc indexed in [AGENTS.md](../AGENTS.md)).
+- **`form_text_input`** — `FormTextInput`: `FormField` wrapping a `TextInputField`; the
+  one-line labeled text field. Controls without a Form\* twin just wrap in `FormField`.
+- **`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_picker`** — `FormPicker`: `FormField` wrapping a `Picker` — one labeled native
+  select.
+- **`form_date_picker`** — `FormDatePicker`: `FormField` wrapping a `DatePicker` — one
+  labeled date field. (Omits `style`; for a grid cell use a bare `FormField style={half}`
+  around `DatePicker`.)
+- **`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.
+- **`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.
+- **`scan_field`** — `ScanField`: the scan/verify input (`ScanStatus` idle|match|mismatch).
+
+### Dates & times
+
+- **`date_picker`** — `DatePicker` (+ `DatePickerPanel`, `DatePickerLabels`): the field-form
+  date (and datetime) picker.
+- **`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.
+- **`date_filter`** — `DateFilter`: the single/range date+time filter panel — presets
+  (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
+- **`date_range_filter_field`** — `DateRangeFilterField`: the register's period filter field
+  (presets + footer + time-segment a11y; localized via the `dateRange` locale slice).
+- **`time_picker`** — `TimePicker`: the time-of-day input.
+
+### Inline editing & record surfaces
+
+- **`inline_edit`** — `useInlineEdit` + `InlineEditView` / `InlineEditFrame` +
+  `INLINE_CONTROL_HEIGHT` (40) + `inlineValueTextStyle`: the engine custom inline editors
+  join through — a view ⇄ edit toggle, a draft buffer, async `onSave` with the spinner
+  INSIDE the control and inline error, commit on blur (Enter saves, Escape reverts) or
+  `controls="buttons"`; `background="tint" | "transparent"` (the zinc-50 editability chip vs
+  flat for dense uniformly-editable surfaces).
+- **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
+  **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
+  (`format="datetime"`, `optionalTime`), **`inline_time_picker`** — the Inline\* per-field
+  editors; `InlineSelect`/`InlineMemberSelect` render the resting value like its option —
+  `renderOptionContent` by default, `renderSelected` to override — a chip/badge at rest, not
+  just text.
+- **`inline_tag_select`** — `InlineTagSelect`: the MULTI inline editor — a tag SET in the
+  inline vocabulary: selected tags render as badges inside the standard chip (`renderTag`),
+  clicking floats a multi `OptionList` (checkbox rows), CLOSING commits the new set in one
+  `onSave` — never a borderless `Select` posing as an inline field.
+- **`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.
+- **`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` (default 130) / `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) 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; trailing beside the value); raise `minValueWidth` (default 160) when a cell holds
+  MORE than one editor so the table stacks earlier. Two tables on one page share one grid by
+  repeating the same labelWidth/trailingWidth. Worked example:
+  [`tpl_record`](../examples/tpl_record.tsx).
+- **`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. Replaces
+  hand-rolled record headers (mixed scales, several competing figures, color noise).
+- **`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, `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`](../examples/tpl_item_list.tsx)
+  drawer.
+- **`peek`** — `Peek`: drill-down for inline references — press a name/id where it appears
+  and get its details in an anchored popover, without leaving the screen; keep the content a
+  summary with ONE action to the full record.
+
+### Lists, tables & registers
+
+- **`list`** — `List`: children separated by hairline `Divider`s.
+- **`list_item`** — `ListItem`: the plain list row.
+- **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
+  (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
+  CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
+  the width can't fit every column it hides columns by `TableColumn.priority` (higher drops
+  first; default = column order, rightmost first; column 0 — the identity — never drops), and
+  below the two-column floor every row STACKS: each cell renders as a `DetailRow`-spread
+  line (muted label left, value at the right edge — one vocabulary with the drawer's detail
+  rows), the lines sitting on the identity column's text edge, never under the checkbox;
+  the header band gives way, so sorting is a wide-container affordance. Rows carry TWO right-side slots: `action`
+  (the primary CTA `Button` — register: in the trailing gutter; stacked: closes the content,
+  right-aligned) and `trailing` (the ⋯ overflow — stays beside the identity on the top line).
+  On pressable rows dropped values stay one tap away — the row opens the record; a READ-ONLY
+  register (rows without `onPress`) has no door, so give the columns it can't afford to lose
+  a low `priority` (e.g. `priority: 1` — outlives its right-side neighbours).
+- **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
+  `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
+  `DataGrid` consumers drive.
+- **`data_grid`** — `DataGrid` + `gridRowStyle`: the inline-managed grouped table (see
+  [Tabular data](#tabular-data--pick-by-scale--intent)); `labels` localizes the sort-header
+  a11y via `SortHeaderLabels`.
+- **`pagination`** — `Pagination` (+ `PaginationLabels`): the register's pager.
+- **`column_filter`** — `ColumnFilter` + `columnFilterToConditions` +
+  `isColumnFilterActive` + `columnFilterSummary`: the typed per-column filter pill; for a
+  register filtering on several columns.
+- **`filter_chip`** — `FilterChip` + `selectSummary`: the toolbar filter pill hosting a
+  facet (options, a `RangeSlider`, a `Counter`).
+- **`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.
+- **`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`** — `useSelectionMode`: `{ active, selected, enter, exit, toggle,
+  toggleAll }` — an agnostic enter/exit multi-select state machine (string ids; pairs with
+  `FileThumbnailGrid selectedIds` and gated-CRUD flows).
+
+### Tasks & checklists
+
+- **`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; wide surfaces use
+  `trailing`; never both. SUGGESTIONS are never rows: offer the commons as `SuggestionChip`s
+  under the list. Close the list with `CaptureRow`. There is deliberately NO monolithic Task
+  component — richer task-management rows 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.
+
+### Overlays & navigation
+
+- **`portal`** — `PortalHost` + `Portal`: the floating-content mount point; the app root
+  needs ONE `PortalHost` or `Dialog`/`Popover`/`Tooltip`/`Alert`/`OptionList` cannot render.
+- **`dialog`** — `Dialog` (+ `DialogHeader`/`DialogHeaderTitle`/`DialogFooter`, `useDialog`,
+  `useDialogNavigation`): the centered card over a scrim; BAKES a screen router in
+  (`<Dialog><Screen route="">…` — see `screen_router`).
+- **`drawer`** — `Drawer` + `DrawerFooter`: the docked side panel with scrim; the register
+  row's edit surface.
+- **`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; pick Dialog when the
+  surface is a card the user can see context around.
+- **`popover`** — `Popover` + `PopoverTrigger` + `PopoverContent` (+ `PopoverHeader`,
+  `PopoverFooter`; `side`/`align`; `disableBodyScroll` ONLY for children that manage their
+  own scroll, like `OptionList`): the anchored floating surface. **NON-MODAL**: the anchored
+  popover has NO blocking overlay — the rest of the page stays interactive, and clicking another
+  control both dismisses this popover AND activates that control in one click; clicking outside,
+  scrolling an ancestor, or Escape dismisses. Only the `small` (bottom-sheet) presentation is
+  modal (scrim). `PopoverContent` already insets its body 12px — put content directly in it,
+  NEVER add your own padding `View` (that double-pads); title/actions go in `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; route PATTERNS,
+  `params`, and stacked-alive screens are `screen_router`'s job.
+- **`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; 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`
+  while `canGoBack`). Key the router by record id so stepping between records resets the
+  stack. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx) drawer.
+- **`route_matching`** — pure `:param` route-pattern utilities — `routeMatches` /
+  `parseRouteParams` / `findBestPattern` (exact beats parameterized) / `shouldRouteMatch`;
+  the matching core under `ScreenRouter`/`Dialog`.
+- **`tooltip`** — `Tooltip` (+ `TooltipTrigger`, `TooltipProvider`, `useTooltip`): the short
+  hover label.
+- **`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.
+- **`alert`** — `Alert` (+ `AlertButton`/`AlertOptions`): the blocking confirm —
+  `Alert.alert(title, message, [{cancel}, {destructive}])`.
+- **`overlay_scope`** — `isOverlayScopeActive` / `pushOverlayScope` / `useOverlayScope`: the
+  module-level open-overlay counter every overlay primitive reports into; the host's
+  shortcut registry reads it synchronously to floor page-level shortcuts while any overlay
+  is open. Lives in the primitives — never call it from a screen.
+- **`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 that opens a full-page
+  section-picker `Modal` — never a horizontal tab strip. Worked example:
+  [`tpl_record`](../examples/tpl_record.tsx).
+- **`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.
+
+### Numbers & charts
+
+- **`kpi_card`** — `KPICard`: one headline metric in a card (trend chip slot, sub-caption,
+  ⓘ definition).
+- **`kpi_strip`** — `KPIStrip`: the boxed dashboard stat band.
+- **`metric`** — `Metric`: a bare headline figure (`format`
+  currency|number|percentage|none, `tone`, `size` sm|md|lg|hero).
+- **`trend_chip`** — `TrendChip`: the signed ±% delta chip.
+- **`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`.
+- **`sparkline`** — `Sparkline`: the inline mini trend line.
+- **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
+  `PieChart`: the canonical SVG chart set (no recharts).
+- **`ring_gauge`** — `RingGauge`: single-fraction circular gauge.
+- **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
+  plain sm tabular count beside it.
+- **`stacked_progress_bar`** — `StackedProgressBar`: one whole split across segments (a
+  status mix on one bar).
+- **`step_progress`** — `StepProgress`: N-of-M dots/segments progress.
+- **`breakdown`** — `Breakdown`: a stacked bar + ranked share rows, pressable to drill;
+  `maxRows` folds the long tail behind a localized "Show N more" toggle
+  (`BreakdownLabels`).
+- **`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`: the per-slot state grid (occupancy,
+  availability) and its legend.
+- **`heatmap`** — `Heatmap`: density cross-tab — colour-only, no numbers; "where does it
+  cluster".
+- **`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`. Pick over `Heatmap` when the NUMBER and totals matter.
+- **`matrix_totals`** — the data layer for `Matrix`: `matrixTotals` (the cross-tab
+  aggregation) + `MatrixAxisItem` / `MatrixCellRef` / `MatrixTotalsResult`; React-free, so a
+  KPI can be driven off the same numbers the grid shows.
+- **`legend_item`** — `LegendItem`: one swatch + label of a chart legend.
+- **`remainder_meter`** — `RemainderMeter`: allocated-vs-remaining meter
+  (`RemainderMeterLabels` localized via the provider).
+- **`allocation_row`** — `AllocationRow`: one target's row in an allocation surface (pairs
+  with `RemainderMeter`).
+
+### Scheduling & time
+
+- **`calendar`** — the calendar views: `CalendarView` (the composed month/week surface),
+  `TimeGridView`, `MonthView`, plus the layout/date helpers (`layoutDayColumns`,
+  `packEventLanes`, `addDays`, `startOfWeek`, …) and `CalendarEvent`/`CalendarLabels` types.
+  **Limitation:** labels are not provider-wired — pass `labels`
+  (`DEFAULT_CALENDAR_LABELS` is English).
+- **`gantt`** — `GanttView` + scale helpers (`barGeometry`, `axisRange`, `buildTicks`,
+  `pxPerDay`) + `GanttTask`/`GanttLabels` types. **Limitation:** labels are not
+  provider-wired — pass `labels` (`DEFAULT_GANTT_LABELS` is English).
+- **`timeline`** — `Timeline`: a heterogeneous event LOG — per-row icon + expandable
+  details; models the past, NOT progress.
+- **`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.
+
+### Files
+
+- **`mime`** — pure MIME predicates: `isImageMimeType` / `isVideoMimeType` /
+  `isAudioMimeType` / `isPdfMimeType` / `isExcelMimeType` / `isCsvMimeType` /
+  `isDocxMimeType` / `isPreviewableMimeType`.
+- **`download`** — `downloadFileFromUrl(url, filename, { credentials? })`: fetch+blob+anchor
+  download that works inside sandboxed iframes (where `window.open` is silently dropped);
+  `credentials` defaults to `same-origin` — pass `"include"` only for auth-gated same-site
+  proxy URLs, never for presigned URLs.
+- **`file_picker`** — `pickFiles({ accept?, multiple? }) → Promise<File[]>`: opens the
+  browser file dialog imperatively — the trigger half behind every Add-file CTA; cancel
+  resolves `[]` on modern engines.
+- **`file_dropzone`** — `FileDropzone`: the drag-drop capture well (`onFiles`, `accept`,
+  `label`/`hint`/`dropLabel`, `height`); click falls back to a picker.
+- **`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). Use `FileGrid`/`FileRows` bare only when you own the chrome.
+- **`file_grid`** — `FileGrid` + the `FileUpload`/`PendingUpload` types: the upload-aware
+  grid — `files` are the saved/completed `DisplayFile`s, `uploads` is the LIVE add-queue; it
+  interleaves both and renders each in-flight tile itself with a labeled status overlay.
+  Tiles FILL the container width at a uniform size (≥ `minItemWidth`, default 96); pass
+  `columns` for a fixed count, `itemSize` for exact tiles, or `singleRow` to fit one row and
+  collapse the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`).
+  CRUD via `onFilePress` / `onDisplayRemove` / `onUploadRemove` / `onRetry` / `onRetryAll`;
+  localize with `labels.upload` (an `UploadStatusLabels`).
+- **`uploading_thumbnail`** — `UploadingThumbnail` + `UploadStatus`/`UploadStatusLabels`:
+  the single in-flight upload tile `FileGrid` renders; reach for it only when hand-rolling a
+  non-grid upload layout.
+- **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
+  `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
+  MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename
+  · media card; `isTemplate` overlays a TMPL marker.
+- **`file_thumbnail_grid`** — `FileThumbnailGrid` (+ the generic `ThumbnailGrid`):
+  display-only square-tile grid; `selectedIds` + `onFilePress` pair with
+  `useSelectionMode()` for gated select-mode CRUD.
+- **`file_row`** — `FileRow`: a horizontal file/document LINE — `FileBadge` or a
+  `placeholder` + the FULL name + a meta line + a composable `trailing` slot; `onPress`
+  makes the whole row a pressable door, `trailing` stays an independently-pressable sibling;
+  for attachment lists / message files / document checklists where a square tile truncates
+  the name.
+- **`file_rows`** — `FileRows`: batteries-included file list — row press → built-in gallery
+  + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
+  `FileGalleryModal`; localized via the `gallery` locale slice.
+- **`file_badge`** — `FileBadge`: the two-tone file-type mark (PDF / XLSX / DOCX / video /
+  audio …) driven by MIME.
+- **`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 — 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.
+- **`file_preview_types`** — `PreviewLabels` / `FilePreviewProps` / `GalleryLabels` — the
+  shared label + prop contracts of the file-preview family; types only.
+- **`file_gallery_modal`** — `FileGalleryModal`: the FULL-SCREEN viewer — toolbar (filename
+  · counter · download, optional `onOpenExternal`/`onRemove` · close-✕), prev/next, ESC,
+  rotate (the 90° controls FLOAT as a pill on the image); on a phone the actions collapse
+  into a ⋯ `ActionMenu`. `onPersistRotation`/`persisting` wire a rotation save. Driven by
+  `files` + `activeIndex` + `onIndexChange`.
+- **`image_gallery`** — `ImageGallery`: main image + thumbnail strip (`thumbnailPosition`
+  bottom|right, `mainAspectRatio`, `rotatable`) with a built-in zoom modal.
+- **`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
+  (`FilePreview`/`ImageGallery` compose it).
+- **`rotate_image`** — `rotateImageToBlob(url, degrees)`: 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`.
+- **`use_image_rotation`** — `useImageRotation`: per-file VIEW rotation state (degrees keyed
+  by file id, in memory) shared between an inline gallery and its fullscreen modal;
+  view-only — a render transform, never a mutation of the stored file.
+- **`share_or_download`** — `shareOrDownloadFiles(files, { title, credentials })`:
+  `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).
+  **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"`.
+
+### AI & collaboration
+
+- **`composer`** — `Composer`: the adaptive command/chat composer — a compact pill that
+  expands for long text + attachments (`pills` + attachment slots, controlled or
+  uncontrolled `value`, `onSend`/`onStop`, `sendDisabled` override).
+- **`agent_run`** — `AgentRun` + `AgentRunStep`/`AgentRunItem` + `resolveToolMeta`: the live
+  streaming work feed.
+- **`agent_progress`** — `AgentProgress`: its compact, floating, expandable form — a
+  composer's working state.
+- **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
+  high/med/low; localized via the provider.
+- **`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`** — `Clarify`: the agent asks back, via `ChoiceList`.
+- **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options, the agent's
+  quick-reply surface.
+- **`sources`** — `Sources` + `SourceRef`/`SourceKind` (record | document | table | web |
+  knowledge): provenance chips, per-kind glyphs.
+- **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one
+  ranked AI-check insight — severity word · title · detail · `Sources` · children slot; the
+  expected-vs-actual body with the emphasized delta; the `finding` locale slice.
+- **`comments_thread`** — `CommentList` + `CommentComposer` + the
+  `ThreadComment`/`ThreadMember`/`ThreadFile` types: the record comments thread.
+  **Limitation:** labels are not provider-wired — pass `CommentListLabels`.
+
+### Utility hooks & plumbing
+
+- **`use_screen_size`** — `useScreenSize` / `getScreenSize` / `calculateScreenSize`:
+  `{ small, medium, large }` width-breakpoint booleans (small < 768 ≤ medium < 1728 ≤
+  large); tracks width changes only, so the mobile soft keyboard (a height-only change)
+  never re-renders.
+- **`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.
+- **`use_focus_ring`** — `useFocusRing`: keyboard-aware focus state for painting a control's
+  own ring.
+- **`json_panel`** — `JsonPanel` (`{title, value}`) + `stringifyData`: a labeled monospace
+  panel for raw/JSON payloads (debug & developer surfaces).