@lotics/ui 5.8.0 → 5.10.0

package/AGENTS.md

@@ -8,7 +8,7 @@ every app inherits), never inline a one-off `View`/`Text` rebuild — that forfe
 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
+- Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `OptionList`) needs a
   `PortalHost` at the app root.
 - RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
   `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
@@ -24,18 +24,21 @@ Pick by capability, not by name. (→ the source file for the API.)
 
 - **Actions** — `Button` (labelled; `title` is MANDATORY; `color` = emphasis/risk),
   `IconButton` (icon-ONLY — the circular affordance; an icon-only Button is a type error, so reach
-  here. `size` `lg` 40px / `md` 28px / `sm` 24px, the SAME `color` palette as Button, plus `loading`;
-  needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
+  here. `size` `lg` 40px / `md` 28px / `sm` 24px, the SAME `color` palette as Button, plus `loading`
+  and `elevated` (white fill + border + shadow, for a button sitting ON imagery — a tile's remove ✕,
+  an overlay's retry); needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
   action — Clear / Select all), `Chip` (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`. For a SELECT-FIELD picker, render each option as its colored chip
-  (`renderOptionContent={(o) => <OptionBadge value={o} />}`).
-- **Pick member(s)** — `MemberSelect` (a `Picker` that renders each option as a `MemberChip`,
+- **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`/`Combobox` all open
+  the one shared `OptionList` body; `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 `Picker` + `renderOptionContent` + a directory by hand. To edit a `select_member`
+  Don't re-wire `Select` + `renderOptionContent` + a directory by hand. 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:
@@ -46,16 +49,37 @@ Pick by capability, not by name. (→ the source file for the API.)
   badge) — never hand-map option-key → color. Feed it a resolved option (`useFieldOptions` for a
   picker option, or `byKey(readSelect(cell)[0]?.key)` for a stored value); multi-select wraps to
   one badge each; a missing/unknown color token degrades to neutral.
-- **Tags / multi-select chip box** — `TagInput` (chips + an Add-popover checklist + create), NOT
-  `Combobox multi` (see §Data entry).
+- **Tags / multi-value chip box** — `Select multi` whose `renderSelected` returns a removable
+  `<Chip onDismiss={remove}>` (with `searchable` + `allowCustom`). The chip box is COMPOSED, not a
+  separate control — there's no `display` mode; `renderSelected` is the seam (see §Data entry).
 - **Text & form** — `TextInputField`, `NumberInput`, `SearchInput`; wrap with `FormField`;
   `Checkbox`, `Switch`, `RadioPicker`; dates via `DatePicker` / `DateRangeFilterField`, times
   via `TimePicker`.
 - **Edit a record's fields in place** — the `Inline*` family: `InlineTextInput` ·
   `InlineNumberInput` · `InlineSelect` · `InlineMemberSelect` · `InlineDatePicker` ·
   `InlineTimePicker` (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.
+- **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
+  inline-editable title (`InlineTextInput` with `struck` for done) + whatever meta cells you add
+  (`OptionBadge` dot tags, `InlineDatePicker`, `InlineMemberSelect`). The one reusable primitive is
+  `CheckCircle`; the rest is composition — see `tpl_tasks` (quick list) and `tpl_task_board` (columns).
+- **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_dossier`. Never an HTML `<table>` or a `.map` of rows.
+  - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view) — the
+    `DataGrid` primitive: a grouped, sortable grid whose cells are LIVE inline editors (ANY field — a
+    column is `{ key, label, width?, sortable?, cell: (item) => ReactNode }`, so `InlineMemberSelect` /
+    `InlineDatePicker` / `InlineNumberInput` / `InlineSelect` / a borderless `Select multi` for tags / colour-dot `OptionBadge`).
+    `DataGrid` owns the sortable header + collapsible grouped sections + aligned rows + an optional
+    per-row `leading` slot (a `CheckCircle`); YOU own the data, the sort/group/filter/collapse STATE
+    (`cycleSort` + `sortBy`, a `collapsed` Set), the toolbar (`SearchInput` + `FilterChip`s), and the
+    per-group add row (`renderGroupFooter`, aligned with the exported `gridRowStyle` + the column
+    widths). It renders ALL rows (no virtualization), so it's only for sets small enough to hold in
+    view — at 10k+ it lags, and grouping + pagination/infinite don't compose; use the register instead.
+    Worked examples: `tpl_task_board` (with a `CheckCircle` leading), `tpl_pipeline` (no leading).
 - **Numbers & charts** — `KPIStrip` / `KPICard` / `Metric` (headline figures), `TrendChip`
   (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG set — no
   recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`
@@ -70,11 +94,25 @@ Pick by capability, not by name. (→ the source file for the API.)
   (bulk-select bar).
 - **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`,
   `Counter`), `Chip`.
-- **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `CommandMenu`,
+- **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `OptionList`
+  (the searchable list body — host it in a `Popover`/`Dialog` for a command palette),
   `Alert` (the blocking confirm).
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
-- **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
+- **Files** — `FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below
+  it that swaps into a batch SELECT mode, full-screen preview, download/share, and Alert-confirmed
+  remove — the host only owns `files` + wires `onAdd`/`onRemove`; mirrors the frontend
+  `cell_files_editor`. Reach for this first for "manage a record's attachments"), `FileDropzone`,
+  `FileRows` (batteries-included file LIST: tap a row → built-in
+  full-screen gallery, with a per-row trailing ⋯ menu = Download · Open-external · Remove; the default "here are some files"
+  surface), `FileGrid` (the upload-aware grid: completed files + a live upload
+  queue in one surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own
+  the chrome), `FileThumbnail` / `FileThumbnailGrid`
+  (square tiles, display-only), `UploadingThumbnail` (the single in-flight tile FileGrid renders —
+  reach for it only when hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document
+  LINE — badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge / action
+  / remove; `onPress` makes the whole row a pressable door, `trailing` stays an independently-pressable
+  sibling; for checklists & readable lists), `FileBadge` (the two-tone type mark), `FilePreview` /
   `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
   `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
 - **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
@@ -111,7 +149,7 @@ This is the most common thing to get right. Match the JOB to the pattern:
 | 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 multi-value TAG field | **`Select multi`** (`renderSelected` → `Chip`) | chips composed, not a separate control |
 | ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker`) | required single-select, one tap, every option visible |
 | a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
 | FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
@@ -124,10 +162,12 @@ form mode or a preview↔edit card — make each VALUE inline-editable: it reads
 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; `renderValue` renders the RESTING value as a
+(`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 →
-member picker; the inline twin of `MemberSelect`) · `InlineDatePicker` · `InlineTimePicker` — all
+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
@@ -178,13 +218,15 @@ missing methods (`Alert.alert` listing each) rather than a vague "incomplete." A
 **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`.
+### Tag / multi-value field — `Select multi`
+A tag field's resting state should be a tidy CHIP BOX — and that's just a multi `Select` whose
+`renderSelected` returns a removable `<Chip onDismiss={remove}>`. There's NO separate component and no
+`display` mode: `renderSelected(item, { remove })` composes the anchor — render a `Chip` with `remove`
+for the ✕, or a plain `OptionBadge`/`MemberChip`/custom pill that ignores it; `renderOptionContent`
+renders the menu rows. `searchable` adds the filter field, `allowCustom` the create row. Borderless for
+a grid cell? Pass a `style`, never a `variant`. `Combobox` is the SINGLE-value sibling — for a search
+that emits one pick at a time and renders the selection elsewhere, use `reflectSelection={false}`
+(see `tpl_*`).
 
 ### Disposition — lifecycle status is ASYMMETRIC by phase
 When a status is an OPEN default plus terminal OUTCOMES the user decides (Lead → Closed/Lost, Draft
@@ -198,24 +240,54 @@ quiet, REVERSIBLE **Change**: a popover STATE SWITCHER (each state a colored dot
 marked + disabled), not a generic text menu. A composition (Badge + Button + Popover/MenuButton).
 
 ### Attachments — a full add / preview / DELETE field
+**Default: `<FilesEditor files onAdd onRemove>`** — it bundles the grid + a toolbar (Upload · Select ·
+Download all) + a batch SELECT mode + the gallery + confirmed-remove; the host only owns `files` and
+wires `onAdd` (picked → its upload) / `onRemove`. Reach for the lower-level pieces below only when you
+need custom chrome:
 Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
-accent; click falls back to a picker); display what landed with `<FileThumbnailGrid files>` ABOVE
+accent; click falls back to a picker); display what landed with **`<FileGrid files uploads>`** ABOVE
 the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add more"
-affordance — only the empty state leads with it). 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), and takes `uploading` to dim it with a spinner while the bytes are still going up.
-Never hand-build a drop well, a file row grid, or a preview modal. In a custom-code APP, don't
-hand-roll the upload+preview state either — `@lotics/app-sdk` `useAttachments()` gives the chat's
-instant-preview lifecycle (local object-URL now, `file_id` on complete); map each `AttachedFile` to a
-`DisplayFile` (snake → camel: `preview_url`→`url`, `mime_type`→`mimeType`) for
-`<FileThumbnail file={…} uploading={f.status === "uploading"} />`.
+affordance — only the empty state leads with it). `FileGrid` is the upload-aware grid: `files` are
+the saved/completed `DisplayFile`s, `uploads` is the LIVE add-queue (`FileUpload[]`) — it interleaves
+both and renders each in-flight tile itself — a LABELED status overlay (uploading spinner · "Retrying"
+· "Paused" · "Upload failed" + a retry button · "Can't upload" for a dead/empty file) — so you never
+hand-map an upload to a `FileThumbnail`. Localize the labels with `labels.upload` (an
+`UploadStatusLabels`; the Lotics `@lotics/ui-internal` adapter already injects vi/en). Make it CRUDable
+by wiring its callbacks: `onFilePress`
+→ set a `number|null` index that drives `<FileGalleryModal files activeIndex onIndexChange>` — a
+FULL-SCREEN viewer with a toolbar (filename · counter · inline action buttons — download, optional
+`onOpenExternal`/`onRemove` · close-✕), prev/next, ESC, and rotate; `onDisplayRemove`/`onUploadRemove`
+→ drop the file / cancel the upload (the grid renders a ✕ on each tile automatically); `onRetry` /
+`onRetryAll` for failed uploads. In a sandboxed custom-code app the toolbar's "open in new tab" can't
+pop a window — pass `onOpenExternal` wired to the SDK's `openExternal` (omit it elsewhere and the
+action hides). PDF/Word/Excel/CSV all render INLINE here (pdf.js / `@lotics/docx` / `@lotics/xlsx`,
+lazy) — no native `<iframe>` viewer, so they work inside the cross-origin app iframe. Keep
+label+grid+dropzone on a `gap` (a bare `CardBody` has none). By default `FileGrid` tiles FILL the
+container width — a uniform size (≥ `minItemWidth`, default 96) so full rows span the width and reflow
+as it changes; a short last row keeps that size and left-aligns (no stretched tiles, no empty cells).
+Pass `columns` for a fixed column count, or `itemSize` for exact fixed-size tiles. For a dense strip
+in a FIXED-width container that must NOT wrap, pass `singleRow` — it fits as many tiles as the width
+allows and collapses the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`,
+which the host wires — e.g. open the gallery at the first hidden file). This is the responsive overflow
+pattern (avatar stack / Finder); prefer it over a hardcoded `maxVisible`, which can't adapt to width.
+Under the hood it composes `FileThumbnail` (the completed tile — right surface per
+MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename · media
+card; also takes `isTemplate` to overlay a TMPL marker) and `UploadingThumbnail` (the in-flight tile);
+reach for either directly only when hand-rolling a NON-grid layout. **When the filename must be
+readable, use `FileRow`** — a horizontal LINE (`FileBadge` or a `placeholder` + the FULL name + a meta
+line + a composable `trailing` slot). `onPress` makes the whole row a pressable door (open the file);
+`trailing` (a status `Badge`, an action, a remove ✕) stays an independently-pressable sibling. For
+attachment lists / message files / document checklists where a square tile truncates the name. Never hand-build a drop well, a file grid, the upload tiles, or a preview
+modal. In a custom-code APP, don't hand-roll the upload+preview state either — `@lotics/app-sdk`
+`useAttachments()` gives the chat's instant-preview lifecycle (local object-URL now, `file_id` on
+complete); map each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file: {…} }`,
+else `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `FileGrid`'s
+`uploads` — `onUploadRemove={remove}`.
 
 **Gated file CRUD is a PATTERN, composed locally — not a sealed kit component.** When a file field must
-GUARD deletion (operator-facing, accidental delete is a real risk), compose it in the app from the kit
-pieces; don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
+GUARD deletion (operator-facing, accidental delete is a real risk), DON'T use `FileGrid` (its per-tile
+✕ is exactly the stray-tap risk you're guarding against) — compose it in the app from the kit pieces;
+don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
 `files_editor` and each app compose their own). The recipe: `FileDropzone` (add) + `FileThumbnailGrid
 files selectedIds onFilePress` (pass `selectedIds` ONLY in select mode) + `FileGalleryModal` (view +
 rotate + persist) + a `Dialog` confirm, all driven by **`useSelectionMode()`** — the reusable LOGIC. The
@@ -379,7 +451,8 @@ used to carry now reads structurally — **provenance** is an uppercase microlab
 (`PROPOSED` · `MATCH` · `MISMATCH` · `SUGGESTED EDIT` · `QUESTION`), and the agent's **reasoning** is
 a left-ruled margin note (a hairline rule + muted text), quoted apart from the facts and the human's
 controls — while **status/severity/diffs use functional colour** the way the rest of the kit does:
-- **Confidence** — a 3-tick meter + word, emerald / amber / zinc by level.
+- **Confidence** — a 3-tick meter + the full phrase ("High confidence" / "Medium" / "Low"), emerald /
+  amber / zinc by level; `labels` to translate (one phrase per level).
 - **Finding severity** — a coloured dot `Badge` + metric: red critical, amber warning, blue note,
   emerald on-track (+ stacking order, most severe first).
 - **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring** (white
@@ -434,11 +507,35 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   (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.
+  to `<body>` and the next Tab jumps to the page's first focusable. Full rules + the keyboard test:
+  `docs/accessibility.md` → Focus & tab order.
+- **Focus rings are per-component, never global.** There is NO global focus CSS — `index.css` only
+  resets the native outline. Every interactive control paints its OWN ring; nothing rings unless it
+  opts in. Three ways, pick by base:
+  - **`FocusRingPressable`** (`@lotics/ui/focus_ring_pressable`) — a `Pressable` that rings on keyboard
+    focus; the default for a raw interactive element (cell, tile, nav button, menu option). Forwards
+    all `PressableProps` (onPress, accessibilityRole/Label/State, ref, style). Reach for this before
+    hand-rolling a Pressable + the hook.
+  - **`PressableHighlight`** — set the opt-in **`focusRing`** prop (or read `state.focusVisible` from
+    its style-fn / children for a bespoke treatment, e.g. `CardSelectItem` which rings on hover/press/focus).
+  - **`useFocusRing`** (`@lotics/ui/use_focus_ring`) — the underlying hook for inputs / custom surfaces.
+    Returns `{ focusVisible, focused, focusProps }`; spread `focusProps`, apply
+    `focusVisible && { boxShadow: FOCUS_RING }` (comma-join any existing box-shadow). `useFocusRing({ always: true })`
+    for text-like inputs/selects (ring on ANY focus, as browsers do for typing-capable fields); plain
+    controls omit it (keyboard-only).
+  The ring is the shared **`FOCUS_RING`** token (`@lotics/ui/control_surface`, `0 0 0 2px zinc-900`). A
+  mouse-opened popover trigger (Select/Combobox/InlineSelect/InlineDatePicker) wears the SAME token on
+  its open state so it reads identically to a keyboard-focused control. **Coverage is a contract:** EVERY
+  interactive control must ring (a focusable control with no focus treatment is a bug — the per-Pressable
+  audit is the gate); a surface that shouldn't ring is a non-control → `tabIndex={-1}`, not a missing ring.
+- **A trigger's hover/focus is a contract too — build it on `PressableHighlight`, never a raw `Pressable`.**
+  Every popover/menu/select anchor (`Select`, `FilterChip`, `Switcher`, the inline editors, a custom
+  `PopoverTrigger`) rides `PressableHighlight` (or `FocusRingPressable`): it paints the hover **wash** +
+  focus ring AROUND the caller's `style`, so a borderless in-cell override (`style={{ borderColor:
+  "transparent" }}` on a `Select`) keeps the wash and reads like its inline neighbours. A raw `Pressable`
+  that hand-rolls its own hover is the bug — a caller's `borderColor` then erases the affordance. Layer the
+  hover-border BEFORE `style` (a transparent edge suppresses it → wash only) and the open ring (`FOCUS_RING`)
+  on the open state.
 - **Cards are banded — and composable** (all from `@lotics/ui/card`):
   ```tsx
   <Card style={{ padding: 0 }}>
@@ -479,6 +576,16 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     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).
+- **Row actions are ALWAYS-VISIBLE siblings, never hover-revealed, never nested.** A pressable row =
+  a role-less surface (the hover/press wash, via DOM `mouseenter` so it covers the whole row) + an
+  accessible "Open …" door (the body, a button) + trailing actions (⋯, remove ✕, edit) as SIBLINGS of
+  the door — a button must not contain another button, so the action is independently pressable and
+  the ✕ isn't swallowed by the row press (`FileRow` and `PressableRow` are the references). Actions
+  stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY exception
+  is a DENSE tree/register where a persistent per-row action would clutter (e.g. the DB sidebar):
+  reveal on hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its
+  opacity, so it's still keyboard-reachable. Do that locally — there is no shared hover-reveal
+  primitive (the old `HoverAction` made the keyboard-inaccessible anti-pattern easy and was removed).
 - **Master-detail = list + workspace `Drawer` with sequencing.** Pressing a PRIMARY entity row
   opens the record workspace in a `Drawer` with `onPrev`/`onNext`/`position` ("3/24") over the
   visible ordering (←/→ built in). Key the drawer body by record id so per-record state resets on
@@ -503,7 +610,7 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   · `ChipGroup` is THE one-of-N lens (≤ ~10 options the user flips between; include "All"; counts in
     the label). Filters ONE list to a SUBSET — including by process stage / lifecycle state.
   · `FilterChip` is THE secondary-dimension filter — a compact chip that opens a composed popover
-    editor (`PickerMenu multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
+    editor (`OptionList multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
     pick via the `{({close}) => …}` render prop.
   · `ColumnFilter` is the TYPED column filter — give it a `FilterableColumn` (`text` / `number` /
     `select`) + a controlled `ColumnFilterValue` and it renders the right editor (contains / range /
@@ -566,13 +673,30 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   `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).
+  `ScanField` run) · `tpl_allocate` (`RemainderMeter` split) · `tpl_run` (preview → resolve → post) ·
+  `tpl_tasks` (the QUICK LIST — Apple-Reminders shape for personal lists: `CheckCircle` rows you tick +
+  expand in place to edit (`Inline*`, stable row — the meta summary never shifts on expand), colour-dot
+  tags, an attachments field (`FileThumbnailGrid` → tap a tile to the gallery for download + confirmed
+  remove + an `Add attachment` `pickFiles` button), search + a clearable group-by (✕ → ungrouped) + tag
+  filter chips, and a primary Draft-from-notes CTA `Composer → AgentRun → ChangeReview`) ·
+  `tpl_task_board` (the COLUMNS shape: a search · group-by · filter toolbar over a grouped, sortable
+  grid of inline-editable cells — assignee/due/status/tags set directly, a files cell (thumbnail glance →
+  popover grid → gallery), 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
+  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
+  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.
 - **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).
+  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).
 - **Planning & time** — `tpl_calendar` · `tpl_attendance` · `tpl_shifts`.
@@ -604,22 +728,23 @@ option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
 status_badge · button · icon_button · link · link_button · chip · tabs · segmented_control ·
-picker · combobox · tag_input (TagInput — chip box + Add-popover; for tags, not Combobox multi) ·
+picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (single-select editable search input; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · 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 `renderValue` for a chip/badge at rest) ·
-list · list_item · menu_button · menu_list_item · detail_row · pressable_row · action_menu ·
+`InlineEditView`; `InlineSelect`/`InlineMemberSelect` take `renderSelected` for a chip/badge at rest) ·
+list · list_item · menu_button · menu_list_item · detail_row · 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 · 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`; 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. 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`; 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 · popover · tooltip ·
-command_menu · alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
+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 ·
+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) + built-in gallery + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `labels`, `galleryLabels`); 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 ·
 file_gallery_modal · image_gallery · 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
@@ -633,4 +758,7 @@ finding (Finding — one ranked briefing/audit insight) · discrepancy (Discrepa
 disagrees across sources) · triage_row (TriageRow — an item the agent classified + routed) ·
 scored_option (ScoredOption — an AI-ranked candidate) ·
 format_money · format_date · colors (solid · tint · ramp · ColorName ·
-isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback).
+isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback) ·
+use_focus_ring (useFocusRing — keyboard-aware focus state for painting a control's own ring; see Focus rings) ·
+focus_ring_pressable (FocusRingPressable — a Pressable that rings on keyboard focus; the raw-control default) ·
+control_surface (CONTROL_HEIGHT · CONTROL_RADIUS · FOCUS_RING · chipSurfaceStyle — the shared control-surface tokens).

package/examples/tpl_approvals.tsx

@@ -17,7 +17,7 @@ import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { FormField } from "@lotics/ui/form_field";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
-import { PickerMenu } from "@lotics/ui/picker_menu";
+import { OptionList } from "@lotics/ui/option_list";
 import { Popover, PopoverContent, PopoverFooter, PopoverTrigger } from "@lotics/ui/popover";
 import { RangeSlider, rangeSummary } from "@lotics/ui/range_slider";
 import { PressableRow } from "@lotics/ui/pressable_row";
@@ -255,10 +255,10 @@ export function TplApprovals() {
               onValueChange={(t) => { setTab(t); setOpenId(null); }}
             />
             <FilterChip label="Requester" summary={reqSummary} onClear={() => setReqSel([])} clearLabel="Clear requester filter">
-              <PickerMenu multi enableSelectAll options={REQUESTERS} value={reqSel} onValueChange={setReqSel} />
+              <OptionList search={{ mode: "none" }} multi options={REQUESTERS} value={reqSel} onValueChange={setReqSel} />
             </FilterChip>
             <FilterChip label="Role" summary={roleSummary} onClear={() => setRoleSel([])} clearLabel="Clear role filter">
-              <PickerMenu multi options={ROLES} value={roleSel} onValueChange={setRoleSel} />
+              <OptionList search={{ mode: "none" }} multi options={ROLES} value={roleSel} onValueChange={setRoleSel} />
             </FilterChip>
             <FilterChip label="Amount" summary={amtSummary} onClear={() => setAmt([AMT_MIN, AMT_MAX])} clearLabel="Clear amount filter">
               <RangeSlider

package/examples/tpl_convert.tsx

@@ -8,7 +8,7 @@ import { Card } from "@lotics/ui/card";
 import { DetailRow } from "@lotics/ui/detail_row";
 import { Divider } from "@lotics/ui/divider";
 import { Drawer, DrawerFooter } from "@lotics/ui/drawer";
-import { FileBadge } from "@lotics/ui/file_badge";
+import { FileRow } from "@lotics/ui/file_row";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileThumbnailGrid } from "@lotics/ui/file_thumbnail_grid";
 import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
@@ -37,8 +37,8 @@ import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
 // required-document checklist with a free FILE DUMP for anything extra. The
 // drawer's ◀▶ keys walk the manager down the queue without closing it.
 //
-// Reference composition — Drawer (list nav) + Stepper + FileBadge (+ placeholder)
-// + Pagination + DetailRow.
+// Reference composition — Drawer (list nav) + Stepper + FileRow (badge + name +
+// meta + a trailing status/action slot) + Pagination + DetailRow.
 // ─────────────────────────────────────────────────────────────────────────────
 
 const CODES: Record<string, string> = {
@@ -141,21 +141,9 @@ function QueueRow({ app, active, onPress }: { app: Applicant; active: boolean; o
   );
 }
 
-// A document line — a FileBadge (or a same-footprint placeholder) + name + meta.
-function FileRow({ name, meta, mimeType, placeholder, tone, action }: {
-  name: string; meta?: string; mimeType?: string; placeholder?: boolean; tone?: "received" | "ready"; action?: ReactNode;
-}) {
-  return (
-    <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-      <FileBadge size={30} mimeType={mimeType} placeholder={placeholder} />
-      <View style={{ flex: 1 }}>
-        <Text size="sm" weight="medium">{name}</Text>
-        {meta ? <Text size="xs" color="muted">{meta}</Text> : null}
-      </View>
-      {action ?? (tone === "received" ? <Badge variant="dot" label="Received" color="emerald" /> : tone === "ready" ? <Badge variant="dot" label="Generated" color="blue" /> : null)}
-    </View>
-  );
-}
+// Document status chips — the `trailing` slot content for the kit's `FileRow`.
+const receivedBadge = <Badge variant="dot" label="Received" color="emerald" />;
+const generatedBadge = <Badge variant="dot" label="Generated" color="blue" />;
 
 // The extra-documents zone — the data-capture attachment field: a thumbnail grid
 // (click to preview in the gallery, ✕ to delete) above a dropzone. Read-only once
@@ -189,7 +177,7 @@ function UploadsField({ uploads, editable, onAdd, onRemove }: {
       ) : uploads.length === 0 ? (
         <Text size="sm" color="muted">No extra files.</Text>
       ) : null}
-      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} />
     </View>
   );
 }
@@ -217,7 +205,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
   if (status === "pending") {
     body = <Text size="sm" color="muted">{`Unlocks after ${STAGES[index - 1].label.toLowerCase()}.`}</Text>;
   } else if (index === 0) {
-    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" tone={status === "done" ? "ready" : undefined} />;
+    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" trailing={status === "done" ? generatedBadge : undefined} />;
   } else if (index === 1) {
     body = (
       <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
@@ -229,7 +217,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
     body = (
       <View style={{ gap: 10 }}>
         {GENERATED_DOCS.map((d) => (
-          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} tone={status === "done" ? "ready" : undefined} />
+          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} trailing={status === "done" ? generatedBadge : undefined} />
         ))}
       </View>
     );
@@ -245,9 +233,9 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
               meta={d.received ? `${d.file} · received` : "Awaiting upload"}
               mimeType={d.received ? "application/pdf" : undefined}
               placeholder={!d.received}
-              action={status === "current"
+              trailing={status === "current"
                 ? (d.received ? <Button title="Remove" color="muted" onPress={() => onMarkDoc(d.name, false)} /> : <Button title="Upload" color="secondary" onPress={() => onMarkDoc(d.name, true)} />)
-                : (d.received ? <Badge variant="dot" label="Received" color="emerald" /> : undefined)}
+                : (d.received ? receivedBadge : undefined)}
             />
           ))}
         </View>

package/examples/tpl_dossier.tsx

@@ -21,7 +21,7 @@ import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { SearchInput } from "@lotics/ui/search_input";
 import { ChipGroup } from "@lotics/ui/chip_group";
 import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
-import { PickerMenu } from "@lotics/ui/picker_menu";
+import { OptionList } from "@lotics/ui/option_list";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { Combobox } from "@lotics/ui/combobox";
 import type { PickerOption } from "@lotics/ui/picker";
@@ -356,9 +356,9 @@ export function TplDossier() {
             onClear={() => { setAssignee([]); setPage(0); }}
             clearLabel="Clear assignee filter"
           >
-            <PickerMenu
+            <OptionList
+              search={{ mode: "none" }}
               multi
-              enableSelectAll
               options={ASSIGNEES}
               value={assignee}
               onValueChange={(v) => { setAssignee(v); setPage(0); }}
@@ -373,7 +373,8 @@ export function TplDossier() {
             clearLabel="Clear fee filter"
           >
             {({ close }) => (
-              <PickerMenu
+              <OptionList
+                search={{ mode: "none" }}
                 options={[{ value: "paid", label: "Paid" }, { value: "unpaid", label: "Unpaid" }]}
                 value={feeStatus}
                 onValueChange={(v) => { setFeeStatus(v); setPage(0); }}

package/examples/tpl_order.tsx

@@ -477,7 +477,7 @@ export function TplOrder() {
         </Screen>
       </Dialog>
 
-      <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={files} activeIndex={activeFile} onIndexChange={setActiveFile} />
     </ScrollView>
   );
 }