@lotics/ui 5.9.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.
@@ -30,13 +30,15 @@ Pick by capability, not by name. (→ the source file for the API.)
   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:
@@ -47,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`
@@ -71,14 +94,20 @@ 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`, `FileRows` (batteries-included file LIST: tap a row → built-in
-  full-screen gallery, ⋯ menu = Download · Open-external · Remove; the default "here are some files"
+- **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 — use this for any add-files screen), `FileThumbnail` / `FileThumbnailGrid`
+  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
@@ -120,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 |
@@ -133,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
@@ -187,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
@@ -207,6 +240,10 @@ 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 **`<FileGrid files uploads>`** ABOVE
 the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add more"
@@ -218,8 +255,8 @@ hand-map an upload to a `FileThumbnail`. Localize the labels with `labels.upload
 `UploadStatusLabels`; the Lotics `@lotics/ui-internal` adapter already injects vi/en). Make it CRUDable
 by wiring its callbacks: `onFilePress`
 → set a `number|null` index that drives `<FileGalleryModal files activeIndex onIndexChange>` — a
-FULL-SCREEN viewer with a toolbar (filename · counter · ⋯actions (download, optional
-`onOpenExternal`/`onRemove`) · close-✕), prev/next, ESC, and rotate; `onDisplayRemove`/`onUploadRemove`
+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
@@ -414,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
@@ -469,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 }}>
@@ -548,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 /
@@ -611,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`.
@@ -649,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_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 ·
+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
@@ -678,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_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); }}