@lotics/ui 47.7.1 → 47.8.0

package/AGENTS.md

@@ -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
@@ -1743,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
@@ -2683,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.7.1",
+  "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/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 };
+    },
+  };
+}