@lotics/ui 3.6.0 → 4.1.0

package/AGENTS.md

@@ -0,0 +1,352 @@
+# @lotics/ui — the UI reference
+
+A React-Native-Web component kit (renders on web **and** native). This file is the design
+law + the "reach for what" guide. The **exact API** of any component is its source, which
+ships with the package: read `node_modules/@lotics/ui/src/<name>.tsx`. **Never guess a prop —
+open the file.** If the closest component lacks a capability, **extend it** (a platform change
+every app inherits), never inline a one-off `View`/`Text` rebuild — that forfeits the
+typeahead, async search, virtualization, and a11y the primitive already ships.
+
+- Import per module: `import { Combobox } from "@lotics/ui/combobox"`.
+- Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `CommandMenu`) needs a
+  `PortalHost` at the app root.
+- RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
+  `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
+- i18n: most components are string-free; the few that emit their own user-facing strings take
+  a `labels` prop (`DateRangeFilterField`, `Pagination`, `SortHeader`/`Table.sortLabels`) —
+  localize there.
+
+---
+
+## Reach by role — what exists
+
+Pick by capability, not by name. (→ the source file for the API.)
+
+- **Actions** — `Button` (labelled; `color` = emphasis/risk, `shape` pill|rounded),
+  `IconButton` (icon-only, needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
+  action — Clear / Select all), `PillButton` (dismissible facet chip). A button is never a raw
+  `Pressable`. For a link OUT (a URL / record / document) use `Link` — underline+blue, the
+  destination signal; the opposite of `LinkButton` (a quiet in-app action, never underlined).
+- **Pick from a list** — `Picker` (known options, native typeahead, single/multi/custom-render,
+  no search box). Search-as-you-type / async / create-new → `Combobox`. A selectable card row →
+  `CardSelectItem`.
+- **Tags / multi-select chip box** — `TagInput` (chips + an Add-popover checklist + create), NOT
+  `Combobox multi` (see §Data entry).
+- **Text & form** — `TextInputField`, `NumberInput`, `SearchInput`; wrap with `FormField`;
+  `Checkbox`, `Switch`, `RadioPicker`; dates via `DatePicker` / `DateRangeFilterField`, times
+  via `TimePicker`.
+- **Edit a record's fields in place** — the `Inline*` family: `InlineTextInput` ·
+  `InlineNumberInput` · `InlineSelect` · `InlineDatePicker` · `InlineTimePicker` (see §Data entry).
+- **Tabular data** — `Table` (columns defined once; sortable headers via `SortHeader`; paired
+  with `Pagination`). Never an HTML `<table>` or a `.map` of rows.
+- **Numbers & charts** — `KPIStrip` / `KPICard` / `Metric` (headline figures), `TrendChip`
+  (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG set — no
+  recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`,
+  `StatusGrid` + `StatusLegend`, `Heatmap`.
+- **Surfaces & layout** — `Card` (+ `CardHeader`/`CardHeaderTitle`/`CardHeaderMeta`/`CardBody`/
+  `CardFooter`), `SectionCard`, `SectionHeading` (+ `SectionHeadingTitle`), `PageHeader` /
+  `PageContent`, `Stack`, `Spacer`, `Divider`, `Accordion`, `Tabs`, `SegmentedControl`, `Stepper`.
+- **Rows & registers** — `PressableRow` (THE register row), `ListItem`, `MenuButton`,
+  `MenuListItem`, `DetailRow` (label+value for drawers/peeks), `ActionMenu` (⋯), `FloatingActionBar`
+  (bulk-select bar).
+- **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterPill` (+ `RangeSlider`,
+  `Counter`), `PillButton`.
+- **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `CommandMenu`,
+  `Alert` (the blocking confirm).
+- **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
+  `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
+- **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
+  `FileGalleryModal`, `ImageGallery` (see §Data entry → Attachments).
+- **Specialized work surfaces** — `ScanField` (scan/verify), `StepList` (guided run),
+  `RemainderMeter` + `AllocationRow` (allocation), `Timeline`, `Calendar`, `Gantt`,
+  `comments_thread`.
+
+---
+
+## Data entry — which pattern for which job
+
+This is the most common thing to get right. Match the JOB to the pattern:
+
+| You're capturing… | Reach for | Why |
+|---|---|---|
+| an EXISTING record's fields | **Inline edit** (`Inline*`) | edit in place, no form mode |
+| a brand-NEW record (a form) | **fieldset form** (`FormField` + the 2-col grid) | structured entry + a Save |
+| a RELATED record (pick or make) | **find-or-create** (`Combobox allowCustom`) | one control covers both |
+| REPEATING rows you build & revise | **line items** (create→preview→edit) | add / edit / remove, live totals |
+| CHARGES that bill onto documents | **billing** (`tpl_billing`) | the invoice document is the unit |
+| a multi-value TAG field | **`TagInput`** | a chip box, not a search input |
+| a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
+| FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
+| many entries FAST | **quick capture** (one row, Enter to add) | repeat-entry speed |
+| a state TRANSITION mid-flow | **stage gate** (popover / dialog by weight) | right-sized friction |
+
+### Inline edit — the preferred way to edit an existing record
+When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
+form mode or a preview↔edit card — make each VALUE inline-editable: it reads as plain text,
+hover tints it (no pencil — that shifts), click swaps the input in **at the same height** (zero
+reflow, the whole point), and it commits on blur (Enter saves, Escape reverts) or via
+`controls="buttons"` (✓ primary / ✕). One per type — `InlineTextInput` · `InlineNumberInput`
+(`format` for currency/units) · `InlineSelect` (plain options OR `renderOptionContent`; floats a
+`Picker` menu in a popover so the row never grows) · `InlineDatePicker` · `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).
+
+### Fieldset form — fields lay out on a RESPONSIVE two-column grid
+Never hard-code columns, never 3-up. A fieldset is `flexDirection:row, flexWrap:wrap,
+columnGap:16`; each `FormField` declares an intrinsic width — `half` (`flexGrow:1,
+flexBasis:240`) or `full` (`flexGrow:1, flexBasis:"100%"`) — so two halves sit side-by-side on a
+wide card and stack on a narrow one with zero media queries. Pair short, related fields as halves
+(phone/email, qty/price); give long or singular values the full row (legal name, address, notes).
+Past two columns the label→field link breaks — MANY inputs means GROUPING into labeled fieldsets
+(each its own 2-up grid, `Divider` between), never a third column. `FormDatePicker`/`FormPicker`
+wrap their OWN `FormField` (and omit `style`) — for a grid cell use a bare `FormField style={half}`
+wrapping `DatePicker`/`Picker`.
+
+### Find-or-create — `Combobox` IS the control
+`Combobox` is a SELECT by default (no leading icon, a trailing chevron); opt INTO the search-box
+look with `icon="search"` only when typing-to-search is primary (a large/remote set).
+`allowCustom` appends a "Create …" row (`customOptionLabel`) when the query matches no option,
+emitting the typed text as the value — so a value not in the known set means CREATE. Wire that
+branch to a create overlay (a modal `Dialog` for 4+ fields, an anchored popover for 1–3) that
+builds the new record and attaches it; existing matches attach directly. The create row sits
+BELOW matches by default (the keyboard highlight lands on the first MATCH, so Enter on a partial
+picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it above. Use
+`reflectSelection={false}` and render the attached record below as a card with a Change action.
+
+### Line items — create → preview → edit (a composition, not a primitive)
+For a list of records you build then revise (invoice rows, repair lines, config entries), each
+item is a `Card` toggling between a read-only PREVIEW (a stack of `DetailRow`s) and an EDIT form
+(the inputs), via a local `editing` flag + Edit/Save/Cancel in the `CardFooter`. A freshly-added
+item opens in edit; Save collapses it to the preview; Edit reopens it. **Edit is cancelable** —
+snapshot the item on Edit so Cancel reverts, or DISCARDS a freshly-added one. Duplicate sits left;
+the destructive **Delete is `danger-secondary`**; Cancel + the Save/Edit toggle sit right. Every
+screen composes its own (~15 lines) so the preview rows + form fit the data.
+
+### Billing & invoicing — the invoice DOCUMENT is the unit (`tpl_billing`)
+When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
+split the screen into "enter fees here, issue there" — that smears one job across two places. Make
+**each invoice a `Card` that holds its own editable charge lines** (amount input + payment method),
+its **live total**, its **status badge** (nothing-to-bill · draft · issued + ref), and its **issue
+action** in the footer. A charge never lives apart from the document it bills on. Issuing is gated
+**inline, never a dead end**: when a prerequisite is missing (a bill-to tax ID, a method on a
+charged line) the issue button disables with one muted line saying what's needed; the payment-method
+picker turns required the instant a line carries an amount. Issuing a real e-invoice is irreversible
+→ confirm in a `Dialog` (stage gate). A grand-total **receipt** validates first — surface the EXACT
+missing methods (`Alert.alert` listing each) rather than a vague "incomplete." A refundable
+**deposit** is its own card and its own receipt — never folded into the total due. Composition over
+`Card` + `NumberInput` + `Picker` + `Badge`; no new primitive.
+
+### Tag field — `TagInput`, NOT `Combobox multi`
+A tag field's resting state should be a tidy CHIP BOX: `TagInput` is a bordered box of removable
+chips + an Add affordance; searching/creating happens in a POPOVER (a searchable, checkable list +
+an optional `allowCreate` row), never an inline token input. `Combobox multi` squeezes a
+`TextInput` among the chips — right for a SEARCH field that accumulates picks, wrong for a chip box
+you occasionally add to. One owner per shape: chips-you-edit → `TagInput`; search-that-accumulates
+→ `Combobox multi`.
+
+### Disposition — lifecycle status is ASYMMETRIC by phase
+When a status is an OPEN default plus terminal OUTCOMES the user decides (Lead → Closed/Lost, Draft
+→ Confirmed/Cancelled, Open → Approved/Rejected), a 3-way segmented/dropdown is wrong — it treats a
+lifecycle as flat peers and guides neither the decision nor the revision. Split by phase: while
+OPEN, surface the outcomes as ACTIONS with valence (`Mark closed` = `primary`, `Mark lost` =
+`danger-secondary`; the open state a quiet dot `Badge`). Coloring the buttons is right here — a
+SINGLE record-level decision is not the approvals-queue "wall of loud buttons." Once RESOLVED, show
+the colored STATE (`Badge variant="dot"` — emerald positive / red negative / blue open) with a
+quiet, REVERSIBLE **Change**: a popover STATE SWITCHER (each state a colored dot + label, current
+marked + disabled), not a generic text menu. A composition (Badge + Button + Popover/MenuButton).
+
+### Attachments — a full add / preview / DELETE field
+Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
+accent; click falls back to a picker); display what landed with `<FileThumbnailGrid files>` ABOVE
+the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add more"
+affordance — only the empty state leads with it). Make it CRUDable by wiring the grid's two
+callbacks: `onFilePress` → set a `number|null` index that drives `<FileGalleryModal files
+activeIndex onIndexChange>` (built-in prev/next/ESC/rotate); `onRemove` → drop the file from state
+(the grid renders a ✕ on each thumbnail automatically). Keep label+grid+dropzone on a `gap` (a bare
+`CardBody` has none). `FileThumbnail` shows the right surface per MIME (image thumbnail · doc card ·
+media card). Never hand-build a drop well, a file row grid, or a preview modal.
+
+### Quick capture — the SPEED surface
+For fast repeat entry (logging activity, expenses), one compact capture row (a `SegmentedControl`
+mode, a `Combobox`-as-select, a `Counter`, an Enter-to-submit `TextInputField`); each entry commits
+on its own into an undoable log below, the field keeps focus and the prior choices carry over. No
+screen-wide Save.
+
+### Stage gates — tiered by weight
+A transition that needs NO input is one click. 1–3 quick fields → a POPOVER FORM anchored to its
+action button (title + one-line stake + `FormField`s; confirm in `PopoverFooter`). A
+destructive/exception path (anything touching money or locks) → a `Dialog` (consequence in prose,
+danger confirm + cancel in `DialogFooter`) or an `Alert.alert(title, message, [{cancel},
+{destructive}])` confirm. Never an inline expanding panel for a gate — it shifts layout and loses
+the "this is a gate" framing.
+
+---
+
+## Composition grammar
+
+- **Canvas**: full-bleed `colors.zinc[50]` ScrollView; content column `maxWidth` 880–1040,
+  centered, `padding: 28`. Cards float on the canvas — never white-on-white.
+- **Heading vocabulary — ONE construct per altitude, no drift.**
+  · **Page band**: one per screen — `Text size="xl" weight="semibold"` title + one `sm muted`
+    subtitle that says what the screen decides. Right side: the screen's ONE primary action and/or
+    a period filter — never a summary Badge (those belong to the KPI strip).
+  · **Card header** (a card's own title band, or separate banded cards): `CardHeader` +
+    `CardHeaderTitle` (`sm semibold`; `info` when the title alone doesn't define the numbers).
+  · **Section title** (a substantial titled block — a form, a timeline, a field group — INSIDE one
+    multi-section card or drawer): a `Text size="sm" weight="semibold"` at the TOP of the section's
+    content, sections separated by ONE `Divider`. Do NOT wrap each section in its own `CardHeader`
+    (its auto-divider double-stacks hairlines around every title). A card-less full page uses
+    `SectionHeading` + `SectionHeadingTitle`. NEVER a bare eyebrow standing in for a section title.
+  · **Eyebrow** (`<Text size="xs" color="muted" transform="uppercase">`, WEIGHTLESS): ONLY a
+    column header or a truly minor one-line label — not a section that owns real content. Don't add
+    `weight`. (A COLORED status word like "Blocked" — `weight="semibold"` + `color="danger"` — is a
+    different element, the verdict word, and keeps its weight.)
+  · **Gate header**: a `Dialog` uses `DialogHeaderTitle`; a popover form uses `Text size="sm"
+    weight="semibold"` + an optional `xs muted` subtitle.
+- **Time-constrained data gets a period filter** in the header band — `DateRangeFilterField`, never
+  a static period badge. Every period-dependent number MUST follow the selection.
+- **Keyboard & focus — use `tabIndex`, never `focusable`.** RN-Web's `Pressable` silently ignores
+  `focusable` (it writes its own `tabIndex`), so set a pressable control's tab-stop status with
+  `tabIndex={0 | -1}` (`focusable` only works on a plain `View`/`TextInput`). Roving widgets
+  (Tabs/SegmentedControl/RadioPicker) keep ONE stop at `0`, the rest `-1`. And NEVER let a FOCUSED
+  control unmount — a conditional pointer affordance that vanishes on use (e.g. an "apply suggested
+  value" pill shown only while a field is empty) must be `tabIndex={-1}`, or the browser drops focus
+  to `<body>` and the next Tab jumps to the page's first focusable. A mouse-opened popover trigger
+  (Picker/Combobox/InlineSelect/InlineDatePicker) gets no `:focus-visible` ring, so it wears
+  **`ACTIVE_RING`** (`control_surface.ts`, a `0 0 0 2px zinc-900` box-shadow mirroring the focus
+  outline) on its open state — reuse that token, don't hand-roll a thin 1px edge. Full rules + the
+  keyboard test: `docs/accessibility.md` → Focus & tab order.
+- **Cards are banded — and composable** (all from `@lotics/ui/card`):
+  ```tsx
+  <Card style={{ padding: 0 }}>
+    <CardHeader><CardHeaderTitle info="what this shows">Title</CardHeaderTitle><CardHeaderMeta>12</CardHeaderMeta></CardHeader>
+    <CardBody>…</CardBody>          {/* repeat with <Divider/> between */}
+    <CardFooter>hint(flex:1) + actions</CardFooter>
+  </Card>
+  ```
+  Never nest cards; never hand-compose a title or footer band. `info` is standard, not garnish.
+- **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`.
+- **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` (`format:"datetime"`, `compact` → dd/MM). Never hand-roll grouping/₫ or
+  dd/MM.
+- **Every number is a door** (except the KPI strip). A component that summarizes records leads to
+  the records behind it when pressed — switch to the filtered list, expand in place, or navigate.
+  Expansion happens IMMEDIATELY below the pressed element — the composable `Accordion` family
+  (`AccordionHeader`/`AccordionTitle`/`AccordionMeta`/`AccordionContent`); header-only = a plain row
+  of identical rhythm, so lists mix expandable + static rows.
+- **No dead rows.** Every listed record is actionable. PRIMARY entity rows press-open the workspace
+  `Drawer` (sequenced); read-only drill-downs expand via `Accordion` or glance via `Peek`; every
+  other row gets an `ActionMenu` (⋯ → MenuButton items: destructive last + **confirmed** via
+  `Alert`). The whole surface is the door: register rows are `PressableRow` (full-bleed wash incl.
+  nested controls). 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).
+  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).
+- **Master-detail = list + workspace `Drawer` with sequencing.** Pressing a PRIMARY entity row
+  opens the record workspace in a `Drawer` with `onPrev`/`onNext`/`position` ("3/24") over the
+  visible ordering (←/→ built in). Key the drawer body by record id so per-record state resets on
+  step. Facts are `DetailRow`s; the commit bar is a `DrawerFooter`. The open row shows a selected
+  highlight (and `marked` — a resting blue tint — for a bulk-ticked row). `Peek` is ONLY for
+  secondary references, never the primary row press.
+- **One view-control vocabulary** (all 40px, `sm` labels, in one wrapping band):
+  · `SearchInput` is THE search box — a rounded white pill with a thin zinc-300 border. Never a
+    bare `TextInputField` + search icon.
+  · `ChipGroup` is THE one-of-N lens (≤ ~10 options the user flips between; include "All"; counts in
+    the label). Filters ONE list to a SUBSET — including by process stage / lifecycle state.
+  · `FilterPill` is THE secondary-dimension filter — a compact pill that opens a composed popover
+    editor (`PickerMenu multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
+    pick via the `{({close}) => …}` render prop.
+  · `Tabs` switch between VIEWS/sections (different content/layout) — never a subset of one list.
+    `SegmentedControl` chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
+- **Footer actions align RIGHT.** `PopoverFooter`/`DialogFooter`/`DrawerFooter` default
+  `align="end"` — commit at the right edge, secondary to its left. Never left-flow a Save/Submit.
+- **Empty result**: `<EmptyState message hint? icon? action?>` — never a bare muted Text.
+- **Inline status**: `<Callout tone="info|success|warning|error|neutral">` — compound (like Card):
+  compose `CalloutTitle`/`CalloutText`/`CalloutActions` inside. `Callout` is INLINE; `Alert` is the
+  blocking modal; `Badge` is a one-word pill.
+- **One primary action per surface.** Everything else secondary/muted; destructive = `danger`
+  styling + explicit label. (A grouped BUILDER section — line items — MAY give its own Add action
+  `primary`; it sits at a different altitude than the form's one terminal commit.)
+- **Button labels carry no trailing ellipsis** ("Assign", not "Assign…"). **Button color is
+  VALENCE/RISK, never category**: the ladder `muted < secondary < primary` is the emphasis axis,
+  `danger` marks destructive — that's the whole axis. No "success"/green. Decision UIs put
+  positive/negative color on the STATUS (dot) and verdict (colored `Text`), not the buttons.
+- **Color discipline** — every status / data-viz / accent color comes from a NAMED helper, never a
+  hand-picked `colors.<family>[shade]`: `solid(name)` = the 500 (dots, series, meter accents);
+  `tint(name, α)` = a wash; `ramp(name, count)` = N shades of ONE family for a coherent dimension.
+  A status is ONE family NAME (`{ color: "emerald" }`) and every weight derives from it. One accent
+  per screen purpose (blue=pipeline, emerald=money, red=danger, amber=waiting). Direct `colors.*` is
+  reserved for NEUTRALS (`zinc`, `border`, `white`, the `*[50]` selection washes).
+- **Status indicators have a WEIGHT — match to prominence, never to a metric.** colored `Text` (a
+  verdict WORD in a header) < `Badge variant="dot"` (a categorical STATE in a scannable column /
+  legend) < `Badge` tonal pill (a record's PROMINENT status, a drawer/detail header). A register's
+  dense rows read lighter — the row's primary status is `variant="dot"`, its drawer twin tonal. A
+  `Badge` is never a metric value.
+- **Typography**: only the `Text` primitive (size/weight/color/transform). Uppercase tracking is
+  built in.
+- **Touch & whitespace**: anything pressable is ≥ 40px tall (8px min gap between pressables). 16px
+  between cards, 24–28 canvas padding, 16–20 inside bands, 10–12 between content lines. Density
+  comes from alignment + hierarchy, not cramming.
+
+---
+
+## Worked examples (templates)
+
+Full worked-example screens ship in the package — **read the source at
+`node_modules/@lotics/ui/examples/<name>.tsx`** (pure `@lotics/ui` + mock data, each a usable
+recipe for a screen JOB; copy and adapt). Pick by the job:
+
+- **Monitor & decide** — `tpl_dashboard` (KPIStrip + trends + attention list) · `tpl_stock`
+  (10k-record faceted funnel) · `tpl_tower` (live `StatusGrid` wallboard) · `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).
+- **Data capture** — `tpl_intake` (multi-fieldset form + attachments) · `tpl_order` (the
+  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
+  disposition + `TagInput` + Documents grid; `tpl_record_plain` = card-less).
+- **Records & lookup** — `tpl_detail` (full record + tabs) · `tpl_directory` (searchable register) ·
+  `tpl_timeline` (audit feed).
+- **Planning & time** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
+- **Administration** — `tpl_settings`.
+
+---
+
+## Full component inventory (import as `@lotics/ui/<module>`)
+
+text · card (Card · CardHeader · CardHeaderTitle · CardHeaderMeta · CardBody · CardFooter) ·
+section_heading (SectionHeading · SectionHeadingTitle — compound, owns no margin) · badge ·
+status_badge · button · icon_button · link · link_button · pill_button · tabs · segmented_control ·
+picker · combobox · tag_input (TagInput — chip box + Add-popover; for tags, not Combobox multi) ·
+text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
+radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·
+inline_text_input · inline_number_input · inline_select · inline_date_picker · inline_time_picker
+(the Inline* family — per-field editors on `inline_edit`'s `useInlineEdit` + `InlineEditView`) ·
+list · list_item · menu_button · menu_list_item · detail_row · pressable_row · action_menu ·
+floating_action_bar · filter_pill · sort_header · table · pagination · accordion · stepper ·
+step_progress · step_list · timeline · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
+command_menu · alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
+CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
+bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
+status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_meter · allocation_row ·
+scan_field · file_dropzone · file_thumbnail · file_thumbnail_grid · file_preview ·
+file_gallery_modal · image_gallery · avatar · skeleton · activity_indicator · loading · divider ·
+spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
+comments_thread · format_money · format_date · colors (solid · tint · ramp · ColorName).