@lotics/ui 47.7.0 → 47.8.0

package/AGENTS.md

@@ -18,7 +18,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values; findings, provenance, confidence (`Finding` is filed here because AI produces most of them, NOT because it is AI-only — a rules-derived contradiction is as in scope as an extraction's); **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the first-line drift a column shows when its cell is sometimes one line and sometimes two, and the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the first-line drift a column shows when its cell is sometimes one line and sometimes two, the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame), and the semantic-section check (a danger or empty section drawn as an ordinary one, and the primitive nobody reached for). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 
@@ -35,6 +35,12 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   nearest `SizeBoundary`; wrap one around any region whose width stops tracking its parent's.
   `useScreenSize()` answers a question about the DEVICE.
   → [catalog.md §"Utility hooks & plumbing"](./docs/catalog.md).
+- **A view the reader ARRANGED survives the reload.** Filters, grouping, sort and folded bands go
+  through `usePersistedState(key, fallback, codec)` — browser storage, per app origin, so it is a
+  per-viewer convenience and never a shared or durable fact. Its `codec.read` is a required
+  ALLOWLIST: a stored option key whose option has since been retired must restore as "off", not
+  as an empty register.
+  → [catalog.md §"Utility hooks & plumbing"](./docs/catalog.md).
 - **No user-facing string is a literal in `src/` when a locale slice already names it.** Every
   string a component renders resolves prop → `useLoticsLocale()` slice → the English pack.
   → [composition.md §"Localization — a rendered string is WIRED"](./docs/composition.md).

package/docs/catalog.md

@@ -1049,7 +1049,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   entity/workspace switcher. A square `Avatar` appears on the trigger and every row as soon as
   ONE item carries `imageUri`, the rest falling back to initials, so an unpictured entry still
   lines up. `minItemsToRender` defaults to 2 (a single choice is clutter); lower it to 1 where
-  the switcher states a scope the reader has no other way to see.
+  the switcher states a scope the reader has no other way to see. It FILTERS past
+  `SWITCHER_SEARCH_FROM` (8) items, and the THRESHOLD is the point: `searchable` is a
+  default rather than an opt-in because the failure it prevents is silent — eight rows
+  is a list, forty is a scroll with no way to jump, and nothing about the second says a
+  prop was missed. Pass `false` on a list that is long but ORDERED (a year of months,
+  where scanning beats typing), `true` on a short one whose labels are hard to tell
+  apart. The query clears on close, so reopening never shows a list narrowed by
+  something typed earlier and no longer on screen.
 - **`count`** — `Count`: a 20px count disc that grows into a pill past one digit (`color` highlight|muted|red).
 - **`shortcut_badge`** — `ShortcutBadge`: the keycap hint pill — a zinc-50 badge rendering a
   shortcut from a raw string or `ShortcutDescriptor` (⌘B on Mac, Ctrl+B elsewhere); null on
@@ -1675,7 +1682,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   **The row OWNS its `title`/`description` pair, so do not hand-roll one beside it.** Both
   lines are `sm`, `leading="tight"`, no gap between them — the stacked-pair law in
   [composition.md](./composition.md), applied by the component rather than restated at each
-  call site. The row is 56.
+  call site. The row's floor is 64 — 12 a side around a tight pair and an `md` leading mark —
+  and it grows for a `description` node taller than a line.
   A `description` passed as a NODE keeps its own leading — the component only sets it on the
   string branch, because forcing a line box on somebody else's subtree re-spaces content that
   may not be a line of text at all.
@@ -1742,7 +1750,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `TabOption.status` (a `ColorName` dot). Pressing the tab IS the filter, so the count is also the
   reason to press it. → [composition.md](./composition.md) §"A partitioning control states its band's size".
 - **`table`** rhythm — rows are separated by their own height and the hover wash, never by a hairline; the register's one line is the band capping the columns. 72px rows, overridable per row with `TableRow`'s `minHeight` when a surface genuinely needs density. There is no `spacing` prop: a table of VALUES rather than of objects is a different component (`Matrix`, `DataGrid`). → [composition.md](./composition.md) §"The register's rhythm".
-- **`table` › `TableGroup`** — a titled BAND of rows inside a `Table` (`label`, `count?`, `color?` for a single valence dot). Turns a register that presents records into one that triages them: group by what implies a different ACTION, order the bands by what needs the reader now, and let air rather than a rule separate them. → [composition.md](./composition.md) §"A register that TRIAGES".
+- **`table` › `TableGroup`** — a titled BAND of rows inside a `Table` (`label`, `count?`, `color?` for a single valence dot, `collapsed?` + `onToggleCollapse?`, `footer?`). **Reach for this rather than `DataGrid` whenever the rows are pressable** — both group, but a `DataGrid` row is a plain view by design (its cells hold live editors), so banding a browse-and-drill register with it silently costs the row press and nothing says so until somebody clicks. **Collapse is CONTROLLED**: `collapsed` + `onToggleCollapse` live with the control that grouped the rows, and omitting `onToggleCollapse` leaves an inert band — one that cannot fold must not wear a chevron. A folded band is only safe while it still says how much it is holding, which is what `count` is for. **`footer` is the band's subtotal**, composed from `TableCell`s so its figures land under the columns they total, and rendered only while the band is open. The band spans the register, so it aligns to the register's left edge — never indented to the first column's text. Turns a register that presents records into one that triages them: group by what implies a different ACTION, order the bands by what needs the reader now, and let air rather than a rule separate them. → [composition.md](./composition.md) §"A register that TRIAGES".
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
   `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
   `DataGrid` consumers drive. `sortBy` copies rather than mutates, and compares strings with
@@ -2682,6 +2690,28 @@ component rather than showing it at zero.
   usually needs both (what is being typed vs. what the results answer). `.cancel()` is for when
   a trailing call has been overtaken — a picked option, a cleared box. `Combobox` searches
   through it.
+- **`use_persisted_state`** — `usePersistedState(key, fallback, codec)` + the codecs `asText`,
+  `oneOf`, `asStringSet`, `asSortState`: `useState` that survives a RELOAD, for the things a
+  reader arranged and would otherwise arrange again — which filters are on, how a register is
+  grouped, which bands are folded. Same signature as `useState`, functional updater included, so
+  a screen adopts it by swapping the call. Storage is the browser's, per origin — and every app
+  is served from its own origin, so what a screen stores is private to that app on that machine.
+  **That is also the whole limit: it never reaches another viewer, the same person's other
+  device, or the server.** A convenience belongs here; anything the work depends on belongs in a
+  record. Every access is wrapped, so a private window or a browser that blocks site data costs
+  the arrangement and nothing else.
+  **The `codec.read` is REQUIRED, and that is the point** — what comes back was written by an
+  earlier version of the page, so `JSON.parse` typed as `T` is a lie that surfaces later as a
+  filter set to a value nothing matches. Validate against an ALLOWLIST (`oneOf`, `asSortState`)
+  wherever the value is an option key or a column name, so a retired option restores as "off"
+  rather than as an empty register that reads like missing data. Never persist a value the
+  screen cannot show the reader: a filter whose chip is on screen is legible, a hidden one is a
+  bug report.
+- **`search_match`** — `normalizeForSearch(s)`: fold case + diacritics for substring matching, so
+  `cafe` finds `Café` and `da giac` finds `Đa Giác`. ONE definition, and every list that filters
+  uses it — two rules is not a style problem: a reader who found a row by typing unaccented text
+  in one list and finds nothing in the next reads the second as missing data. `OptionList`,
+  `Combobox` and `Switcher` all match through it.
 - **`use_async_fn`** — `useAsyncFn`: wrap an async function into a manual-trigger mutation —
   `[run, {loading, data, error}]`, unmount-safe, the error lands in state AND rethrows; the
   pending-state engine for a submit/download/upload action.

package/docs/composition.md

@@ -369,6 +369,14 @@ formatted into it, and that is the whole rule: `"Trên tàu (4)"` is a second co
 screen already computes, and it is the copy that goes stale — the band re-counts on every filter
 and the string does not.
 
+**A grouping control CLEARS — it never offers "no grouping" as a choice.** Flat is the
+register's resting state, not one option among N, so putting *None* / *Không nhóm* in the list
+prices the way back at the same click as a way in and leaves the control looking engaged while it
+is doing nothing. Give the chip a clear affordance (the ✕ every other filter already has) and let
+its summary state the dimension only while one is picked. Same reason a grouping chip sits FIRST
+in the band: it changes the register's shape, where the filters beside it only change its
+contents.
+
 It also decides where the count may live. A register whose bands already state their sizes must
 not carry a strip of chips above it repeating the same three numbers; that is one fact twice. And
 a count is a reason to PRESS — a control that states how many rows are behind it and does not
@@ -1567,6 +1575,18 @@ column is a sort wearing chrome: it spends a band per value to repeat the cell b
   that is not there.
 - **At most one band carries a dot.** A valence mark on every band is decoration; on the one band
   whose urgency comes from a CLOCK rather than from something someone wrote down, it is a signal.
+- **Grouping never costs the row press.** A register whose rows open something keeps `Table` +
+  `TableGroup`; reaching for `DataGrid` to get bands trades the press away, because its rows are
+  plain views by design. The tell is that the screen still looks right — bands, counts and columns
+  all render — and only a click reveals the rows are inert. Grouping is a presentation OF rows,
+  not a different kind of screen, so it must not decide which kind you get.
+- **The band aligns to the REGISTER, not to a column.** It spans every column, so its heading
+  starts on the same left edge the column headings do. Indented to where the first column's text
+  begins it reads as a value inside that column rather than a divider across all of them, and it
+  drifts the day that column's leading chrome changes size.
+- **The air between bands is a margin OUTSIDE the heading, and the heading's own padding is
+  symmetric.** Padding the top asymmetrically to make room bakes the gap into the pressable's box,
+  so its hover wash and focus ring hang below the words they belong to.
 - **Air separates bands, a hairline separates rows.** The band boundary is the largest break
   inside the register and the row rules are the smallest — drawing both as lines makes them
   compete and the grouping stops reading. No rule under a band heading either; that orphans the
@@ -1751,6 +1771,22 @@ The hit area is unchanged — it paints outside the box rather than growing it
 where it would if the control were not there. The same applies to any verb riding a value: a
 `CopyButton`, an `InlineButton`, a count chip.
 
+## "Who can reach this" is drawn as MARKS, on every surface that asks it
+
+Access is a set of people, so it renders as `AvatarGroup` — a register cell, a settings row, a
+detail header. A word in place of the marks (`Shared`, `2 people`) answers a smaller question than
+the faces do: it says THAT the thing is shared without saying WITH WHOM, which is the half the
+reader opened the screen for, and it puts one datum in two treatments the moment any other surface
+draws the marks.
+
+The one case marks cannot carry is the whole organization: "everyone" is not a set you can show
+three of, and the three that happen to sort first would say something false about who else is in
+there. That gets an icon and a word.
+
+Whether the OWNER is among the marks is the caller's decision, not a flag on the component — a
+register with its own owner column passes the shares alone, a list without one leads with the
+owner. Compose it; a boolean would make one component answer two questions.
+
 ## Identity marks — a mark that is the same on every row carries nothing
 
 `Avatar` derives its ground from the NAME (`avatar_tone`), and takes `shape="circle" | "square"`

package/docs/reviewing.md

@@ -232,6 +232,13 @@ reads as one cluster. One `gap` on a container makes every child a peer; wrap th
 space the groups. Worst where both items are small grey glyphs on one line, because nothing but
 spacing distinguishes them.
 
+**The inverted case is easiest to measure and easiest to miss: a control sitting directly on a
+list.** An action above a `List` with nothing between them measures 0, against the 1px divider
+INSIDE the list — so the boundary between two different things is smaller than the boundary
+between two rows of one thing, and the button reads as the list's first row. Measure the CTA's
+bottom against the first row's top on any panel built as *action, then list*; it is a per-screen
+defect, so finding it on one panel is a reason to sweep the siblings.
+
 → [composition.md](./composition.md) §"Touch & whitespace".
 
 ### 5. State diff
@@ -675,6 +682,27 @@ its whole subtree on each background refresh.
 
 → [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".
 
+### 9d. A SEMANTIC section drawn as an ordinary one — and the primitive nobody reached for
+Probes 1 and 2 group by shape and find each group internally consistent. The defect neither sees
+is a section whose MEANING is special — destructive, warning, empty, generated — rendered in the
+same heading treatment, on the same ground, as the ordinary sections beside it. Every measurement
+passes, and the meaning is carried by the heading's WORDS alone: delete the word "Danger" and
+nothing on screen still says it.
+
+**Collect**, per section on the surface: heading `rung / weight / ink`, the section's own
+background and border, and the treatment of the action inside it. **The signature** is a
+semantically-marked section byte-identical to its neighbours — and, downstream of that, its
+action reading as the FAINTEST control on a screen whose ordinary Save is solid (probe 2's
+singleton ground, arrived at from the other end).
+
+**The cheaper detection is structural: grep the kit for a component named after the meaning
+before composing one.** A section the kit already ships — `DangerZone`, `EmptyState` — hand-rolled
+out of a divider, a heading and a button loses more than its treatment: it loses the SLOTS the
+primitive requires, which is why hand-rolled destructive sections routinely carry no consequence
+line at all. If a screen's section has a name, that name is the thing to search for. And a
+component that exists and is used NOWHERE is the same finding seen from the kit's side — worth a
+sweep, not a second copy.
+
 ### 10. Microcopy
 - **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
   refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.7.0",
+  "version": "47.8.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -239,6 +239,7 @@
     "./screen_router": "./src/screen_router.tsx",
     "./scroll_to_bottom": "./src/scroll_to_bottom.tsx",
     "./search_input": "./src/search_input.tsx",
+    "./search_match": "./src/search_match.ts",
     "./section_card": "./src/section_card.tsx",
     "./section_heading": "./src/section_heading.tsx",
     "./section_stack": "./src/section_stack.tsx",
@@ -304,6 +305,7 @@
     "./use_gated_press": "./src/use_gated_press.ts",
     "./use_hover": "./src/use_hover.ts",
     "./use_image_rotation": "./src/use_image_rotation.ts",
+    "./use_persisted_state": "./src/use_persisted_state.ts",
     "./use_paste_files": {
       "react-native": "./src/use_paste_files.ts",
       "default": "./src/use_paste_files.web.ts"

package/src/list_item.tsx

@@ -171,18 +171,17 @@ function PressRow(props: {
 }
 
 const styles = StyleSheet.create({
-  // 56, not 64. The height was sized around a pair rendered as prose — two 24px
-  // boxes plus a 2px gap is 50, and 64 left 14px of slack the row did not ask
-  // for, which is what made a correctly-sized `md` mark (28px, the documented
-  // rung for a person in a list) look adrift in it. A tight pair is 40, so 56
-  // gives it the same 8-a-side the rest of the kit's rows carry. A title-only
-  // row keeps one 20px line centred in the same box, so the two shapes still
-  // share a beat.
+  // 64 around a tight pair of 40 and an `md` (28px) leading mark — 12 a side,
+  // which is what lets a settings list of identity rows read as a list rather
+  // than a table. A title-only row keeps one 20px line centred in the same box,
+  // so the two shapes share a beat. `minHeight`, not `height`: a `description`
+  // node the caller supplies (a chip row, two stacked facts) is taller than a
+  // line of text, and a fixed height clips it.
   container: {
     flexDirection: "row",
     alignItems: "center",
     gap: 8,
-    height: 56,
+    minHeight: 64,
     paddingHorizontal: 8,
     marginHorizontal: -8,
     borderRadius: 12,

package/src/search_match.ts

@@ -0,0 +1,18 @@
+/** Fold case + diacritics for matching, so search is forgiving: `cafe` matches
+ *  `Café`, `dieu` matches `Điều`, `da giac` matches `Đa Giác`. Still
+ *  substring-based (predictable — no subsequence/typo noise); the typed value
+ *  keeps its original accents.
+ *
+ *  ONE definition, because every list in the kit that filters must agree on what
+ *  a query matches. Two of them is not a style problem: a reader who found a row
+ *  by typing unaccented text in one list and finds nothing in the next reads the
+ *  second as missing data, and nothing on either screen says the rule differed.
+ *  `Đ`/`đ` needs the explicit fold — NFD leaves it a single codepoint with no
+ *  combining mark to strip, so it survives the diacritic pass unchanged. */
+export function normalizeForSearch(s: string): string {
+  return s
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .replaceAll(String.fromCharCode(0x111), "d");
+}

package/src/switcher.tsx

@@ -1,15 +1,23 @@
-import React, { useCallback, useState } from "react";
+import React, { useCallback, useMemo, useState } from "react";
 import { StyleSheet } from "react-native";
 import { Avatar } from "./avatar";
 import { Icon } from "./icon";
 import { MenuButton } from "./menu_button";
 import { PressableHighlight } from "./pressable_highlight";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { normalizeForSearch } from "./search_match";
+import { SearchInput } from "./search_input";
+import { useLoticsLocale } from "./locale";
 import { Stack } from "./stack";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 
+/** Where a popover list stops being scannable and starts being a scroll. Eight
+ *  rows is about one popover's height at the default row rhythm — past it the
+ *  reader is dragging rather than reading. */
+export const SWITCHER_SEARCH_FROM = 8;
+
 export interface SwitcherItem {
   id: string;
   label: string;
@@ -36,6 +44,16 @@ interface SwitcherProps {
   align?: "start" | "center" | "end";
   /** Trigger max width in pixels. Default 180. */
   maxTriggerWidth?: number;
+  /**
+   * Filter the list by typing. Defaults to ON past {@link SWITCHER_SEARCH_FROM}
+   * items — the threshold rather than a flat `false`, because the failure this
+   * prevents is SILENT: a switcher over eight things is a short list, a switcher
+   * over forty is a scroll with no way to jump, and nothing about the second
+   * announces that a prop was missed. Pass `false` to suppress it on a list that
+   * is long but ordered (a year of months), or `true` to force it on a short one
+   * whose labels are hard to scan.
+   */
+  searchable?: boolean;
 }
 
 /**
@@ -59,12 +77,23 @@ export function Switcher(props: SwitcherProps) {
     side = "bottom",
     align = "start",
     maxTriggerWidth = 180,
+    searchable,
   } = props;
   const [open, setOpen] = useState(false);
+  const [q, setQ] = useState("");
+  const locale = useLoticsLocale();
+
+  const showSearch = searchable ?? items.length >= SWITCHER_SEARCH_FROM;
+  const shown = useMemo(() => {
+    const needle = normalizeForSearch(q.trim());
+    if (!showSearch || !needle) return items;
+    return items.filter((i) => normalizeForSearch(i.label).includes(needle));
+  }, [items, q, showSearch]);
 
   const handleSelect = useCallback(
     (id: string) => {
       setOpen(false);
+      setQ("");
       if (id === currentId) return;
       onSelect(id);
     },
@@ -88,7 +117,9 @@ export function Switcher(props: SwitcherProps) {
     ) : undefined;
 
   return (
-    <Popover open={open} onOpenChange={setOpen} side={side} align={align}>
+    // The query resets on close, so reopening never shows a list narrowed by
+    // something typed a minute ago and no longer on screen.
+    <Popover open={open} onOpenChange={(o) => { setOpen(o); if (!o) setQ(""); }} side={side} align={align}>
       <PopoverTrigger>
         <PressableHighlight focusRing style={[styles.trigger, { maxWidth: maxTriggerWidth }]}>
           {mark(current)}
@@ -100,7 +131,20 @@ export function Switcher(props: SwitcherProps) {
       </PopoverTrigger>
       <PopoverContent>
         <Stack style={styles.popoverBody}>
-          {items.map((item) => (
+          {showSearch ? (
+            <SearchInput
+              value={q}
+              onChangeText={setQ}
+              placeholder={locale.optionList.searchPlaceholder}
+              autoFocus
+            />
+          ) : null}
+          {showSearch && shown.length === 0 ? (
+            <Text size="sm" color="muted" style={styles.noResults}>
+              {locale.optionList.noResults}
+            </Text>
+          ) : null}
+          {shown.map((item) => (
             <MenuButton
               key={item.id}
               icon={mark(item)}
@@ -131,4 +175,5 @@ const styles = StyleSheet.create({
   popoverBody: {
     minWidth: 220,
   },
+  noResults: { paddingHorizontal: 10, paddingVertical: 8 },
 });

package/src/table.tsx

@@ -13,6 +13,8 @@ import {
 import { Animated, StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors, solid, type ColorName } from "./colors";
+import { Icon } from "./icon";
+import { FocusRingPressable } from "./focus_ring_pressable";
 import { PressableRow } from "./pressable_row";
 import { CONTROL_HEIGHT } from "./control_surface";
 import { PressDoor } from "./press_door";
@@ -86,6 +88,9 @@ const TableContext = createContext<TableCtx | null>(null);
  */
 const ORDINAL_W = 28;
 
+/** The band's leading slot — sized to the chevron, the widest thing it holds. */
+const GROUP_MARK_W = 16;
+
 /**
  * The row's left chrome: its number, then whatever the caller put in `leading`.
  *
@@ -335,6 +340,17 @@ export interface TableGroupProps {
    *  label alone understates (a queue that is overdue). Omit for a neutral band —
    *  most bands are neutral, and a dot on every one is decoration. */
   color?: ColorName;
+  /** Folded away. Controlled: which bands are open is the register's own state,
+   *  and it belongs beside the control that grouped them. The COUNT is what makes
+   *  folding safe — a closed band still says how much it is holding. */
+  collapsed?: boolean;
+  /** Omit for an inert band — a heading with no chevron and no tab stop. A band
+   *  that cannot fold must not look like it can. */
+  onToggleCollapse?: () => void;
+  /** A subtotal row under the band's rows, composed from `TableCell`s so its
+   *  figures land under the columns they total. Rendered only while open: a
+   *  total under a folded band restates a number the band already carries. */
+  footer?: ReactNode;
   /** The `TableRow`s in this band. */
   children: ReactNode;
 }
@@ -363,36 +379,73 @@ export interface TableGroupProps {
  * "which of all".
  */
 export function TableGroup(props: TableGroupProps) {
-  const { label, count, color, children } = props;
+  const { label, count, color, collapsed = false, onToggleCollapse, footer, children } = props;
   const rows = Children.toArray(children).filter(isValidElement);
   // A band separates its OWN rows the same way the table does. This rendered
   // hairlines unconditionally, so an airy register lost its rules between bands
   // and kept them inside — the grouping made the register look half-converted,
   // and the rule that survived was the one with least reason to.
-  return (
-    <View>
-      <View style={styles.groupHeading}>
-        {/* Ô này giữ chỗ kể cả khi băng không có màu: bỏ hẳn nó đi thì nhãn của
-            băng trung tính bắt đầu sớm hơn nhãn băng có màu đúng một chấm cộng
-            khoảng cách, và hai băng nằm ngay cạnh nhau trong cùng một bảng. */}
-        <View
-          style={[styles.groupDot, color ? { backgroundColor: solid(color) } : { opacity: 0 }]}
-        />
-        <Text size="sm" weight="semibold">
-          {label}
-        </Text>
-        {count != null ? (
-          <Text size="sm" color="muted" tabular>
-            {count}
-          </Text>
+  // THE BAND SPANS THE WHOLE REGISTER, so it aligns to the register's own left
+  // edge — the same line the column headings start on — not to any one column's
+  // text. A heading indented to the subject column reads as a value inside that
+  // column rather than a divider across all of them, and it drifts the moment the
+  // first column's chrome changes.
+  const heading = (
+    <View style={styles.groupHeading}>
+      {/* ONE slot for the band's leading mark, whatever it holds — the chevron, the
+          valence dot, or nothing. Fixed width so the label starts at the same x on
+          every band in a register: a collapsible band beside an inert one, or a
+          coloured band beside a neutral one, would otherwise step their titles
+          apart by the width of a glyph. (The dot already carried this reasoning for
+          colour alone; the chevron made it a second axis of the same problem.) */}
+      <View style={styles.groupMark}>
+        {onToggleCollapse ? (
+          <Icon name={collapsed ? "chevron-right" : "chevron-down"} size={15} color={colors.zinc[400]} />
+        ) : color ? (
+          <View style={[styles.groupDot, { backgroundColor: solid(color) }]} />
         ) : null}
       </View>
-      <View style={styles.body}>
-        {/* The row's own key, for the reason given in the wide variant above. */}
-        {rows.map((row, i) => (
-          <View key={row.key ?? i}>{row}</View>
-        ))}
-      </View>
+      <Text size="sm" weight="semibold">
+        {label}
+      </Text>
+      {count != null ? (
+        <Text size="sm" color="muted" tabular>
+          {count}
+        </Text>
+      ) : null}
+    </View>
+  );
+
+  return (
+    <View style={styles.groupBand}>
+      {onToggleCollapse ? (
+        <FocusRingPressable
+          onPress={onToggleCollapse}
+          accessibilityRole="button"
+          // Raw, not `accessibilityState` — this RNW build drops that silently, and a
+          // band that folds without announcing it is a control a screen reader reads
+          // as a plain button.
+          aria-expanded={!collapsed}
+          accessibilityLabel={label}
+          style={({ hovered }: { hovered?: boolean }) => [
+            styles.groupPress,
+            hovered ? styles.groupPressHover : null,
+          ]}
+        >
+          {heading}
+        </FocusRingPressable>
+      ) : (
+        heading
+      )}
+      {collapsed ? null : (
+        <View style={styles.body}>
+          {/* The row's own key, for the reason given in the wide variant above. */}
+          {rows.map((row, i) => (
+            <View key={row.key ?? i}>{row}</View>
+          ))}
+          {footer}
+        </View>
+      )}
     </View>
   );
 }
@@ -774,10 +827,23 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
     gap: 8,
-    paddingTop: 26,
-    paddingBottom: 10,
+    // SYMMETRIC, so the hover wash and the focus ring sit centred on the label.
+    // The air that separates one band from the band above is `groupBand`'s margin,
+    // OUTSIDE the pressable — baked into this padding instead it made every band
+    // look bottom-heavy, because the wash is drawn on the padding box.
+    paddingVertical: 7,
     paddingHorizontal: ROW_GUTTER,
   },
+  /** The separation between groups. Outside the pressable — see `groupHeading`. */
+  groupBand: { marginTop: 18 },
+  groupPress: { borderRadius: 8 },
+  /** ONE slot for the band's leading mark, whatever it holds — the chevron, the
+   *  valence dot, or nothing. Fixed width so the label starts at the same x on
+   *  every band in a register: a collapsible band beside an inert one, or a
+   *  coloured band beside a neutral one, would otherwise step their titles apart
+   *  by the width of a glyph. */
+  groupMark: { width: GROUP_MARK_W, alignItems: "center", justifyContent: "center" },
+  groupPressHover: { backgroundColor: colors.zinc[50] },
   groupDot: {
     width: 6,
     height: 6,

package/src/use_option_list.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import type { ScrollView } from "react-native";
+import { normalizeForSearch } from "./search_match";
 import { useListKeyboardNav } from "./use_list_keyboard_nav";
 import type { PickerOption, PickerValue, PickerOnValueChange, PickerOnClose } from "./picker";
 
@@ -98,17 +99,6 @@ export interface UseOptionList<T extends string, D> {
 
 const defaultCustomLabel = (query: string) => `Add "${query}"`;
 
-/** Fold case + diacritics for matching, so option search is forgiving: `cafe`
- *  matches `Café`, `dieu` matches `Điều`. Still substring-based (predictable —
- *  no subsequence/typo noise); the typed value keeps its original accents. */
-function normalizeForSearch(s: string): string {
-  return s
-    .toLowerCase()
-    .normalize("NFD")
-    .replace(/\p{Diacritic}/gu, "")
-    .replaceAll(String.fromCharCode(0x111), "d");
-}
-
 /**
  * The headless core of the kit's option listbox — filtering, the custom/empty
  * rows, single/multi selection + select-all, and keyboard nav + typeahead — with

package/src/use_persisted_state.ts

@@ -0,0 +1,131 @@
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from "react";
+import type { SortState } from "./sort_header";
+
+/** How one value survives a reload. `read` is REQUIRED and not optional: what
+ *  comes back out of storage was written by some earlier version of this page,
+ *  in some browser, possibly by hand — `JSON.parse` typed as `T` is a lie, and
+ *  the lie surfaces later as a filter set to a value nothing matches. Validate
+ *  the shape and return `undefined` to fall back. `write` is only needed when
+ *  `T` is not something `JSON.stringify` round-trips (a `Set`, a `Map`, a
+ *  `Date`). */
+export interface PersistedCodec<T> {
+  read: (raw: unknown) => T | undefined;
+  write?: (value: T) => unknown;
+}
+
+/**
+ * `useState` that REMEMBERS — for the things a reader arranged and would have to
+ * arrange again: which filters are on, how the register is grouped, which bands
+ * are folded. Same signature as `useState` (the functional updater included), so
+ * a screen adopts it by swapping the call.
+ *
+ * Storage is per browser and per origin, and every app is served from its own
+ * origin, so what a screen stores is private to that app on that machine. It
+ * never reaches another viewer, the same person's other device, or the server —
+ * which is exactly why this is for CONVENIENCE and never for anything the work
+ * depends on. A shared or durable fact belongs in a record.
+ *
+ * Every access is wrapped: storage can be absent, full, or throw on the accessor
+ * itself (a private window, a browser set to block site data, a screenshot
+ * runner). The screen must render correctly with nothing stored, which is what
+ * `fallback` is for — so a failure here costs the arrangement and nothing else.
+ */
+export function usePersistedState<T>(
+  key: string,
+  fallback: T,
+  codec: PersistedCodec<T>,
+): [T, Dispatch<SetStateAction<T>>] {
+  // The codec is inevitably a fresh object literal on every render — reading it
+  // through a ref keeps it out of the write effect's dependencies, so the effect
+  // fires on a VALUE change rather than on every render.
+  const codecRef = useRef(codec);
+  codecRef.current = codec;
+
+  const [value, setValue] = useState<T>(() => {
+    const stored = readStored(key);
+    if (stored === undefined) return fallback;
+    // `undefined` is the ONLY rejection — never `??`. A codec may legitimately
+    // revive `null` (a sort the reader cleared), and `??` would quietly restore
+    // the default instead, so clearing would be the one arrangement that never
+    // survives a reload.
+    const revived = codec.read(stored);
+    return revived === undefined ? fallback : revived;
+  });
+
+  useEffect(() => {
+    const w = codecRef.current.write;
+    writeStored(key, w ? w(value) : value);
+  }, [key, value]);
+
+  // Stable, so a screen can pass it straight to a child without re-rendering it
+  // on every keystroke elsewhere.
+  const set = useCallback<Dispatch<SetStateAction<T>>>((next) => setValue(next), []);
+  return [value, set];
+}
+
+function store(): Storage | null {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  } catch {
+    // Accessing the accessor throws where site data is blocked outright.
+    return null;
+  }
+}
+
+function readStored(key: string): unknown {
+  try {
+    const raw = store()?.getItem(key);
+    return raw === null || raw === undefined ? undefined : JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function writeStored(key: string, value: unknown): void {
+  try {
+    store()?.setItem(key, JSON.stringify(value));
+  } catch {
+    // Full, or blocked. The screen already holds the value in state.
+  }
+}
+
+/** The codec for a plain string that must be one of a KNOWN set — a select
+ *  option key, a grouping dimension. An allowlist rather than a `typeof` check,
+ *  because a stored key whose option was deleted filters the register down to
+ *  nothing and looks like missing data. `""` is always allowed: it is how every
+ *  filter in the kit spells "off". */
+export function oneOf<T extends string>(allowed: readonly T[]): PersistedCodec<T | ""> {
+  return {
+    read: (raw) =>
+      raw === "" ? "" : typeof raw === "string" && (allowed as readonly string[]).includes(raw) ? (raw as T) : undefined,
+  };
+}
+
+/** The codec for free text a reader typed. */
+export const asText: PersistedCodec<string> = {
+  read: (raw) => (typeof raw === "string" ? raw : undefined),
+};
+
+/** The codec for a `Set` of strings — stored as an array, since `JSON` has no
+ *  set. Used for the folded bands of a grouped register. */
+export const asStringSet: PersistedCodec<Set<string>> = {
+  read: (raw) => (Array.isArray(raw) && raw.every((x) => typeof x === "string") ? new Set(raw) : undefined),
+  write: (v) => [...v],
+};
+
+/** The codec for a `Table`'s single-column sort. Takes the columns that are
+ *  actually sortable, so a stored key from a column since renamed or removed
+ *  falls back to the register's own order instead of sorting on a field the
+ *  screen no longer reads. */
+export function asSortState(keys: readonly string[]): PersistedCodec<SortState | null> {
+  return {
+    read: (raw) => {
+      if (raw === null) return null;
+      if (typeof raw !== "object") return undefined;
+      const { key, dir } = raw as { key?: unknown; dir?: unknown };
+      if (typeof key !== "string" || !keys.includes(key)) return undefined;
+      if (dir !== "asc" && dir !== "desc") return undefined;
+      return { key, dir };
+    },
+  };
+}