@lotics/ui 47.7.1 → 47.9.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

@@ -526,7 +526,9 @@ patterns doc indexed in [AGENTS.md](../AGENTS.md)).
 upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocation),
 `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
 `CalendarView` (the `calendar` module — days are the axis), `GanttView` (RESOURCES are the
-axis: a channel, an owner, a vehicle), `comments_thread`.
+axis: a channel, an owner, a vehicle), `comments_thread`, `SocialPostPreview` (a post as ONE
+network's feed shows it, with the count against that network's limit and every rule its API
+would refuse — the publish gate reads the same `socialPostIssues` the preview draws).
 
 ### AI surfaces
 
@@ -606,7 +608,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `SubsectionHeading` instead. Pick between this and `Eyebrow` by what is LABELLED — a block or a
   value; composition.md § Eyebrow vs group lead has the table.
 - **`brand_mark`** — `BrandMark`: an OUTSIDE brand's mark, naming the channel a touchpoint
-  happened on — `facebook`, `zalo`, `linkedin`, `x`, `google-meet`. Solid single-colour silhouettes
+  happened on — `facebook`, `instagram`, `threads`, `zalo`, `linkedin`, `x`, `google-meet`. Solid single-colour silhouettes
   in each brand's own hex, drawn from CC0 geometry. `size` (default 16) and `muted` (draw in the
   text colour). The name list is an ALLOWLIST — `BRAND_NAMES` is the array and `BrandName` derives
   from it, so a channel with no mark will not typecheck and the call site falls back to a generic
@@ -800,6 +802,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the product can name); `joined` comes in as an ISO DATE and the card formats it to month + year;
   `groups` distinguishes absent (no row) from `[]` ("None"). `inactive` draws the departed state as
   a `Badge` — a lifecycle state, not another muted line.
+- **`social_post_preview`** — `SocialPostPreview`: a draft post as one network's feed would show
+  it — author line with the network's mark, text folded where THAT feed folds it (or the tail
+  past the limit in the danger ink, unfolded, so the characters to cut are the ones on screen),
+  media as a carousel strip (Instagram, Threads) or a tiled grid with overflow (Facebook, X,
+  LinkedIn) — a lone video plays inline, as every feed plays it — a link as the card or the
+  inert text it becomes, and a footer with `count / limit`
+  plus each refusal in words. `SOCIAL_NETWORK_RULES` is the one table both the drawing and
+  `socialPostIssues(network, draft)` read — both in `social_post_rules`, RN-free, so a gate reads
+  them without rendering — so a button gated on the issues refuses exactly what
+  the preview shows; `socialPostIssueText` renders one in the pack's words. Never writes, never
+  publishes. Counts in code points, which is a guide on X (it weights URLs and CJK), exact
+  elsewhere.
 - **`member_peek`** — `MemberPeek`: `MemberChip` + `Peek` + the card above, with the trigger's
   announced name taken from the locale. Off picker options and off rows that already press —
   see the person-display section for why.
@@ -1049,7 +1063,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 +1764,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 +2704,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.9.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",
@@ -249,6 +250,8 @@
     "./share_or_download": "./src/share_or_download.ts",
     "./shortcut_badge": "./src/shortcut_badge.tsx",
     "./size_boundary": "./src/size_boundary.tsx",
+    "./social_post_preview": "./src/social_post_preview.tsx",
+    "./social_post_rules": "./src/social_post_rules.ts",
     "./skeleton": "./src/skeleton.tsx",
     "./skip_link": "./src/skip_link.tsx",
     "./slider": "./src/slider.tsx",
@@ -304,6 +307,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/brand_mark.tsx

@@ -18,7 +18,7 @@ import { Svg, Path } from "react-native-svg";
  * plausible and slightly wrong, which is the one defect a reader spots instantly
  * and a test suite never does.
  */
-export const BRAND_NAMES = ["facebook", "meta", "tiktok", "google-ads", "zalo", "linkedin", "x", "google-meet"] as const;
+export const BRAND_NAMES = ["facebook", "instagram", "threads", "meta", "tiktok", "google-ads", "zalo", "linkedin", "x", "google-meet"] as const;
 
 export type BrandName = (typeof BRAND_NAMES)[number];
 
@@ -73,6 +73,16 @@ const MARKS: Record<BrandName, Mark> = {
     color: "#0866FF",
     path: "M9.101 23.691v-7.98H6.627v-3.667h2.474v-1.58c0-4.085 1.848-5.978 5.858-5.978.401 0 .955.042 1.468.103a8.68 8.68 0 0 1 1.141.195v3.325a8.623 8.623 0 0 0-.653-.036 26.805 26.805 0 0 0-.733-.009c-.707 0-1.259.096-1.675.309a1.686 1.686 0 0 0-.679.622c-.258.42-.374.995-.374 1.752v1.297h3.919l-.386 2.103-.287 1.564h-3.246v8.245C19.396 23.238 24 18.179 24 12.044c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.628 3.874 10.35 9.101 11.647Z",
   },
+  /** The two Meta surfaces a post goes to under a PERSON's name rather than a
+   *  Page's. Threads' mark is black, like X's — the same `muted` escape applies. */
+  instagram: {
+    color: "#FF0069",
+    path: "M7.0301.084c-1.2768.0602-2.1487.264-2.911.5634-.7888.3075-1.4575.72-2.1228 1.3877-.6652.6677-1.075 1.3368-1.3802 2.127-.2954.7638-.4956 1.6365-.552 2.914-.0564 1.2775-.0689 1.6882-.0626 4.947.0062 3.2586.0206 3.6671.0825 4.9473.061 1.2765.264 2.1482.5635 2.9107.308.7889.72 1.4573 1.388 2.1228.6679.6655 1.3365 1.0743 2.1285 1.38.7632.295 1.6361.4961 2.9134.552 1.2773.056 1.6884.069 4.9462.0627 3.2578-.0062 3.668-.0207 4.9478-.0814 1.28-.0607 2.147-.2652 2.9098-.5633.7889-.3086 1.4578-.72 2.1228-1.3881.665-.6682 1.0745-1.3378 1.3795-2.1284.2957-.7632.4966-1.636.552-2.9124.056-1.2809.0692-1.6898.063-4.948-.0063-3.2583-.021-3.6668-.0817-4.9465-.0607-1.2797-.264-2.1487-.5633-2.9117-.3084-.7889-.72-1.4568-1.3876-2.1228C21.2982 1.33 20.628.9208 19.8378.6165 19.074.321 18.2017.1197 16.9244.0645 15.6471.0093 15.236-.005 11.977.0014 8.718.0076 8.31.0215 7.0301.0839m.1402 21.6932c-1.17-.0509-1.8053-.2453-2.2287-.408-.5606-.216-.96-.4771-1.3819-.895-.422-.4178-.6811-.8186-.9-1.378-.1644-.4234-.3624-1.058-.4171-2.228-.0595-1.2645-.072-1.6442-.079-4.848-.007-3.2037.0053-3.583.0607-4.848.05-1.169.2456-1.805.408-2.2282.216-.5613.4762-.96.895-1.3816.4188-.4217.8184-.6814 1.3783-.9003.423-.1651 1.0575-.3614 2.227-.4171 1.2655-.06 1.6447-.072 4.848-.079 3.2033-.007 3.5835.005 4.8495.0608 1.169.0508 1.8053.2445 2.228.408.5608.216.96.4754 1.3816.895.4217.4194.6816.8176.9005 1.3787.1653.4217.3617 1.056.4169 2.2263.0602 1.2655.0739 1.645.0796 4.848.0058 3.203-.0055 3.5834-.061 4.848-.051 1.17-.245 1.8055-.408 2.2294-.216.5604-.4763.96-.8954 1.3814-.419.4215-.8181.6811-1.3783.9-.4224.1649-1.0577.3617-2.2262.4174-1.2656.0595-1.6448.072-4.8493.079-3.2045.007-3.5825-.006-4.848-.0608M16.953 5.5864A1.44 1.44 0 1 0 18.39 4.144a1.44 1.44 0 0 0-1.437 1.4424M5.8385 12.012c.0067 3.4032 2.7706 6.1557 6.173 6.1493 3.4026-.0065 6.157-2.7701 6.1506-6.1733-.0065-3.4032-2.771-6.1565-6.174-6.1498-3.403.0067-6.156 2.771-6.1496 6.1738M8 12.0077a4 4 0 1 1 4.008 3.9921A3.9996 3.9996 0 0 1 8 12.0077",
+  },
+  threads: {
+    color: "#000000",
+    path: "M18.263 11.097c-.03-3.486-1.92-5.586-5.111-5.586-2.13 0-3.922.963-4.863 2.499l2.062 1.438c.535-.843 1.272-1.543 2.628-1.543 1.528 0 2.318.85 2.544 2.431a15 15 0 0 0-2.236-.173c-4.125 0-6.068 1.867-6.068 4.336s1.943 3.99 4.804 3.99c3.139 0 5.013-2.115 5.781-4.735.798.361 1.348 1.204 1.348 2.47 0 3.387-3.907 5.232-7.22 5.232-4.885 0-8.077-3.207-8.077-8.424 0-6.392 4.223-10.487 9.9-10.487 3.808 0 5.69 1.671 6.97 3.914l2.108-1.475C21.44 2.078 18.331 0 13.663 0 6.227 0 1.168 5.277 1.168 12.934c0 7 4.953 11.066 10.856 11.066 4.878 0 9.809-2.846 9.809-7.716 0-2.545-1.46-4.231-3.569-5.187m-6.33 4.855c-1.077 0-2.026-.512-2.026-1.453 0-1.483 1.822-1.934 3.606-1.934.678 0 1.34.045 1.927.173-.422 1.927-1.671 3.215-3.508 3.214Z",
+  },
   zalo: {
     color: "#0068FF",
     path: "M12.49 10.2722v-.4496h1.3467v6.3218h-.7704a.576.576 0 01-.5763-.5729l-.0006.0005a3.273 3.273 0 01-1.9372.6321c-1.8138 0-3.2844-1.4697-3.2844-3.2823 0-1.8125 1.4706-3.2822 3.2844-3.2822a3.273 3.273 0 011.9372.6321l.0006.0005zM6.9188 7.7896v.205c0 .3823-.051.6944-.2995 1.0605l-.03.0343c-.0542.0615-.1815.206-.2421.2843L2.024 14.8h4.8948v.7682a.5764.5764 0 01-.5767.5761H0v-.3622c0-.4436.1102-.6414.2495-.8476L4.8582 9.23H.1922V7.7896h6.7266zm8.5513 8.3548a.4805.4805 0 01-.4803-.4798v-7.875h1.4416v8.3548H15.47zM20.6934 9.6C22.52 9.6 24 11.0807 24 12.9044c0 1.8252-1.4801 3.306-3.3066 3.306-1.8264 0-3.3066-1.4808-3.3066-3.306 0-1.8237 1.4802-3.3044 3.3066-3.3044zm-10.1412 5.253c1.0675 0 1.9324-.8645 1.9324-1.9312 0-1.065-.865-1.9295-1.9324-1.9295s-1.9324.8644-1.9324 1.9295c0 1.0667.865 1.9312 1.9324 1.9312zm10.1412-.0033c1.0737 0 1.945-.8707 1.945-1.9453 0-1.073-.8713-1.9436-1.945-1.9436-1.0753 0-1.945.8706-1.945 1.9436 0 1.0746.8697 1.9453 1.945 1.9453z",

package/src/locale.tsx

@@ -3,6 +3,7 @@ import { type DatePickerLabels } from "./date_picker";
 import { type CalendarLabels } from "./date_calendar";
 import { type CalendarViewLabels } from "./calendar/types";
 import { type GanttLabels } from "./gantt/types";
+import { type SocialPostPreviewLabels } from "./social_post_rules";
 import { type PaginationLabels } from "./pagination";
 import { type SortHeaderLabels } from "./sort_header";
 import { type ConfidenceLabels } from "./confidence";
@@ -65,6 +66,9 @@ export interface LoticsLocale {
   /** `GanttView` — the zoom switch, the frozen column header, dependency
    *  announcements and the empty state. */
   gantt: GanttLabels;
+  /** `SocialPostPreview`: the fold's "more", the not-yet-published timestamp,
+   *  and the refusals each network's API would answer with. */
+  socialPostPreview: SocialPostPreviewLabels;
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
    *  a call site doesn't pass a dimension-specific `clearLabel`. */
   filterChip: { clear: string };
@@ -348,6 +352,13 @@ export const en: LoticsLocale = {
     day: "Day", week: "Week", month: "Month", task: "Task",
     empty: "Nothing scheduled",
   },
+  socialPostPreview: {
+    more: "more", justNow: "Just now",
+    overLimit: (over) => `${over} over the limit`,
+    needsMedia: "Needs a photo or video", tooManyImages: (max) => `Up to ${max} images`,
+    videoAlone: "A video goes on its own", gifAlone: "A GIF goes on its own",
+    linkOrMedia: "A link or media, not both",
+  },
   filterChip: { clear: "Clear" },
   filterBand: { filters: "Filters", clearAll: "Clear all", done: "Done" },
   floatingActionBar: { clear: "Clear" },
@@ -568,6 +579,13 @@ export const vi: LoticsLocale = {
     day: "Ngày", week: "Tuần", month: "Tháng", task: "Công việc",
     empty: "Chưa có việc nào",
   },
+  socialPostPreview: {
+    more: "xem thêm", justNow: "Vừa xong",
+    overLimit: (over) => `Quá ${over} ký tự`,
+    needsMedia: "Cần ảnh hoặc video", tooManyImages: (max) => `Tối đa ${max} ảnh`,
+    videoAlone: "Video phải đăng riêng", gifAlone: "GIF phải đăng riêng",
+    linkOrMedia: "Liên kết hoặc ảnh/video, không cả hai",
+  },
   filterChip: { clear: "Xóa" },
   filterBand: { filters: "Bộ lọc", clearAll: "Xoá lọc", done: "Xong" },
   floatingActionBar: { clear: "Bỏ chọn" },

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/social_post_preview.tsx

@@ -0,0 +1,187 @@
+import React from "react";
+import { StyleSheet, View } from "react-native";
+import { Avatar } from "./avatar";
+import { BrandMark, type BrandName } from "./brand_mark";
+import { Card } from "./card";
+import { colors } from "./colors";
+import { type DisplayFile } from "./file_thumbnail";
+import { FileThumbnailGrid } from "./file_thumbnail_grid";
+import { MediaPlayer } from "./media_player";
+import { isVideoMimeType } from "./mime";
+import { useLoticsLocale } from "./locale";
+import {
+  SOCIAL_NETWORK_RULES,
+  countSocialChars,
+  socialPostIssueText,
+  socialPostIssues,
+  type SocialNetwork,
+  type SocialNetworkRules,
+  type SocialPostDraft,
+  type SocialPostLink,
+} from "./social_post_rules";
+import { Text } from "./text";
+
+const NETWORK_MARK: Record<SocialNetwork, BrandName> = {
+  facebook: "facebook",
+  instagram: "instagram",
+  threads: "threads",
+  x: "x",
+  linkedin: "linkedin",
+};
+
+export interface SocialPostPreviewProps extends SocialPostDraft {
+  network: SocialNetwork;
+  /** Who the post goes out as — the name and handle the feed prints. */
+  author: { name: string; handle?: string; avatarUrl?: string };
+  /** The timestamp line. Defaults to the locale's "just now", which is what a
+   *  post that has not gone out yet would read. */
+  when?: string;
+  onFilePress?: (file: DisplayFile) => void;
+  testID?: string;
+}
+
+/**
+ * A post as one network's feed would show it — the author line, the text
+ * folded where that feed folds it, the media in the shape that feed lays it out,
+ * the link as the card or the plain text it becomes — with the count against
+ * the limit and every rule the API would refuse, in words, under it.
+ *
+ * It is a PREVIEW, so it never writes and never publishes: the app owns the
+ * draft and the button. What it owns is the knowledge of what each network
+ * does with the same three inputs, which is exactly the thing a person cannot
+ * see from an editor and finds out from a refused request otherwise. That
+ * knowledge is `social_post_rules`, which the publish gate reads too, so the
+ * button refuses exactly what the preview shows.
+ */
+export function SocialPostPreview(props: SocialPostPreviewProps) {
+  const { network, author, text, media = [], link, when, onFilePress, testID } = props;
+  const labels = useLoticsLocale().socialPostPreview;
+  const rules = SOCIAL_NETWORK_RULES[network];
+  const issues = socialPostIssues(network, { text, media, link });
+  const count = countSocialChars(text);
+  const over = count > rules.maxChars;
+  // A carousel network shows one frame at a time, so a strip that scrolls says
+  // "swipe" honestly; a feed that tiles shows the tiles and hides the rest
+  // behind a count, which is what the grid's overflow draws.
+  const carousel = rules.video === "mixed";
+
+  return (
+    <Card style={styles.card} testID={testID}>
+      <View style={styles.header}>
+        <Avatar name={author.name} size="md" source={author.avatarUrl ? { uri: author.avatarUrl } : undefined} />
+        <View style={styles.identity}>
+          <Text size="sm" weight="semibold" numberOfLines={1}>{author.name}</Text>
+          <Text size="xs" color="muted" numberOfLines={1}>
+            {[author.handle, when ?? labels.justNow].filter(Boolean).join(" · ")}
+          </Text>
+        </View>
+        <BrandMark name={NETWORK_MARK[network]} size={18} />
+      </View>
+
+      <View style={styles.body}>
+        {text.length > 0 ? <PostText text={text} rules={rules} more={labels.more} /> : null}
+
+        {media.length === 1 && isVideoMimeType(media[0].mimeType) ? (
+          // A lone video PLAYS in every feed — a tile with a play glyph is what a
+          // file list shows, not what the post will look like.
+          <View style={styles.video}>
+            <MediaPlayer src={media[0].url} kind="video" accessibilityLabel={media[0].filename} />
+          </View>
+        ) : media.length > 0 ? (
+          <FileThumbnailGrid
+            files={[...media]}
+            columns={carousel ? undefined : Math.min(media.length, 2)}
+            itemSize={carousel ? 144 : undefined}
+            singleRow={carousel}
+            maxVisible={carousel ? undefined : 4}
+            onFilePress={onFilePress}
+            disablePress={onFilePress === undefined}
+          />
+        ) : null}
+
+        {link && rules.link === "card" && (media.length === 0 || rules.linkBesideMedia) ? (
+          <LinkCard link={link} />
+        ) : null}
+      </View>
+
+      <View style={styles.footer}>
+        <Text size="xs" color={over ? "danger" : "muted"} tabular>
+          {count} / {rules.maxChars}
+        </Text>
+        {issues.map((issue) => (
+          <Text key={issue.kind} size="xs" color="danger">
+            {socialPostIssueText(issue, labels)}
+          </Text>
+        ))}
+      </View>
+    </Card>
+  );
+}
+
+/**
+ * The text as the feed shows it: folded at the network's fold with the "more"
+ * the reader would tap, and — when it is over the limit — the tail the network
+ * would refuse drawn in the danger ink, unfolded, because a fold would hide the
+ * very characters the person has to cut.
+ */
+function PostText({ text, rules, more }: { text: string; rules: SocialNetworkRules; more: string }) {
+  const chars = Array.from(text);
+  if (chars.length > rules.maxChars) {
+    return (
+      <Text size="sm">
+        {chars.slice(0, rules.maxChars).join("")}
+        <Text size="sm" color="danger">{chars.slice(rules.maxChars).join("")}</Text>
+      </Text>
+    );
+  }
+  if (rules.foldChars !== null && chars.length > rules.foldChars) {
+    return (
+      <Text size="sm">
+        {chars.slice(0, rules.foldChars).join("")}…{" "}
+        <Text size="sm" color="muted">{more}</Text>
+      </Text>
+    );
+  }
+  return <Text size="sm">{text}</Text>;
+}
+
+function domainOf(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return url;
+  }
+}
+
+function LinkCard({ link }: { link: SocialPostLink }) {
+  return (
+    <View style={styles.linkCard}>
+      <Text size="xs" color="muted" numberOfLines={1}>{domainOf(link.url)}</Text>
+      <Text size="sm" weight="semibold" numberOfLines={2}>{link.title ?? link.url}</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: { padding: 0, maxWidth: 520, width: "100%" },
+  header: { flexDirection: "row", alignItems: "center", gap: 10, paddingHorizontal: 16, paddingTop: 14 },
+  identity: { flex: 1, minWidth: 0 },
+  body: { paddingHorizontal: 16, paddingVertical: 12, gap: 12 },
+  video: { width: "100%", aspectRatio: 16 / 9, borderRadius: 8, overflow: "hidden", backgroundColor: colors.zinc["900"] },
+  linkCard: {
+    borderWidth: 1,
+    borderColor: colors.zinc["200"],
+    borderRadius: 8,
+    backgroundColor: colors.zinc["50"],
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    gap: 2,
+  },
+  footer: {
+    borderTopWidth: 1,
+    borderTopColor: colors.zinc["200"],
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    gap: 2,
+  },
+});

package/src/social_post_rules.ts

@@ -0,0 +1,192 @@
+import type { DisplayFile } from "./file_thumbnail";
+
+/**
+ * The networks a post can be previewed FOR — the ones whose feed shape and
+ * publishing rules this module knows. A surface with no API (a personal Facebook
+ * profile, a group, a Zalo OA) has no entry: what it accepts is decided by a
+ * person pasting, not by a request the platform can refuse.
+ *
+ * RN-free on purpose: the publish gate in an app reads this without rendering
+ * anything, and the locale packs type their labels off it.
+ */
+export const SOCIAL_NETWORKS = ["facebook", "instagram", "threads", "x", "linkedin"] as const;
+
+export type SocialNetwork = (typeof SOCIAL_NETWORKS)[number];
+
+/**
+ * What one network's feed does with a post, and what its API refuses.
+ *
+ * Two kinds of fact, deliberately in one place: the FOLD (where the feed hides
+ * the rest behind "more") is a display fact, the rest are publishing rules the
+ * API enforces after the bytes have travelled. Both are what a person needs to
+ * see BEFORE pressing publish, so the preview and the gate read one table.
+ */
+export interface SocialNetworkRules {
+  /** The characters the API accepts. Counted in code points — X weights URLs
+   *  and CJK differently, so the count is a guide there, not the network's own. */
+  maxChars: number;
+  /** Where the feed folds the text behind "more", or null when it never does. */
+  foldChars: number | null;
+  /** The most images one post carries, or null when the API sets no count. */
+  maxImages: number | null;
+  /** Whether a video has to be the only attachment. */
+  video: "alone" | "mixed";
+  /** Whether a GIF is its own kind that goes alone (X) or just an image. */
+  gif: "alone" | "image";
+  /** What a link becomes: a card, or plain text the feed does not open. */
+  link: "card" | "text";
+  /** Whether the API takes a link beside media, or refuses the pair. */
+  linkBesideMedia: boolean;
+  /** Whether a post with no media is refused. */
+  requiresMedia: boolean;
+}
+
+export const SOCIAL_NETWORK_RULES: Record<SocialNetwork, SocialNetworkRules> = {
+  facebook: {
+    maxChars: 63206,
+    foldChars: 477,
+    maxImages: null,
+    video: "alone",
+    gif: "image",
+    link: "card",
+    linkBesideMedia: false,
+    requiresMedia: false,
+  },
+  instagram: {
+    maxChars: 2200,
+    foldChars: 125,
+    maxImages: 10,
+    video: "mixed",
+    gif: "image",
+    // A URL in a caption is inert text. Drawn as no card, not as a refusal:
+    // the API takes it, the reader just cannot tap it.
+    link: "text",
+    linkBesideMedia: true,
+    requiresMedia: true,
+  },
+  threads: {
+    maxChars: 500,
+    foldChars: null,
+    maxImages: 20,
+    video: "mixed",
+    gif: "image",
+    link: "card",
+    linkBesideMedia: false,
+    requiresMedia: false,
+  },
+  x: {
+    maxChars: 280,
+    foldChars: null,
+    maxImages: 4,
+    video: "alone",
+    gif: "alone",
+    link: "card",
+    linkBesideMedia: true,
+    requiresMedia: false,
+  },
+  linkedin: {
+    maxChars: 3000,
+    foldChars: 210,
+    maxImages: 20,
+    video: "alone",
+    gif: "image",
+    link: "card",
+    linkBesideMedia: false,
+    requiresMedia: false,
+  },
+};
+
+/** The network's own name. Proper nouns, so not in the locale packs. */
+export const SOCIAL_NETWORK_LABELS: Record<SocialNetwork, string> = {
+  facebook: "Facebook",
+  instagram: "Instagram",
+  threads: "Threads",
+  x: "X",
+  linkedin: "LinkedIn",
+};
+
+export interface SocialPostLink {
+  url: string;
+  title?: string;
+}
+
+/** What a post IS before it goes out — the three things every network takes. */
+export interface SocialPostDraft {
+  text: string;
+  media?: readonly DisplayFile[];
+  link?: SocialPostLink | null;
+}
+
+export type SocialPostIssue =
+  | { kind: "over_limit"; over: number; max: number }
+  | { kind: "needs_media" }
+  | { kind: "too_many_images"; max: number }
+  | { kind: "video_alone" }
+  | { kind: "gif_alone" }
+  | { kind: "link_or_media" };
+
+/** Code points, so a Vietnamese vowel with its tone is one character. */
+export function countSocialChars(text: string): number {
+  return Array.from(text).length;
+}
+
+function mediaKind(file: DisplayFile): "video" | "gif" | "image" {
+  if (file.mimeType.startsWith("video/")) return "video";
+  if (file.mimeType === "image/gif") return "gif";
+  return "image";
+}
+
+/**
+ * Everything the network would refuse, from the draft alone — so the gate can
+ * close before the bytes travel, and say why in the same words the preview does.
+ * An empty list is not a promise the post lands (a token can have expired, a
+ * container can fail to process); it is the promise the REQUEST is well-formed.
+ */
+export function socialPostIssues(network: SocialNetwork, draft: SocialPostDraft): SocialPostIssue[] {
+  const rules = SOCIAL_NETWORK_RULES[network];
+  const media = draft.media ?? [];
+  const kinds = media.map(mediaKind);
+  const videos = kinds.filter((k) => k === "video").length;
+  const gifs = kinds.filter((k) => k === "gif").length;
+  const images = media.length - videos - (rules.gif === "alone" ? gifs : 0);
+  const issues: SocialPostIssue[] = [];
+
+  const count = countSocialChars(draft.text);
+  if (count > rules.maxChars) issues.push({ kind: "over_limit", over: count - rules.maxChars, max: rules.maxChars });
+  if (rules.requiresMedia && media.length === 0) issues.push({ kind: "needs_media" });
+  if (rules.maxImages !== null && images > rules.maxImages) issues.push({ kind: "too_many_images", max: rules.maxImages });
+  if (rules.video === "alone" && videos > 0 && media.length > 1) issues.push({ kind: "video_alone" });
+  if (rules.gif === "alone" && gifs > 0 && media.length > 1) issues.push({ kind: "gif_alone" });
+  if (draft.link && media.length > 0 && !rules.linkBesideMedia) issues.push({ kind: "link_or_media" });
+  return issues;
+}
+
+export interface SocialPostPreviewLabels {
+  more: string;
+  justNow: string;
+  overLimit: (over: number) => string;
+  needsMedia: string;
+  tooManyImages: (max: number) => string;
+  videoAlone: string;
+  gifAlone: string;
+  linkOrMedia: string;
+}
+
+/** One issue, in the pack's words — the same sentence beside the preview and on
+ *  the gate that reads the same list. */
+export function socialPostIssueText(issue: SocialPostIssue, labels: SocialPostPreviewLabels): string {
+  switch (issue.kind) {
+    case "over_limit":
+      return labels.overLimit(issue.over);
+    case "needs_media":
+      return labels.needsMedia;
+    case "too_many_images":
+      return labels.tooManyImages(issue.max);
+    case "video_alone":
+      return labels.videoAlone;
+    case "gif_alone":
+      return labels.gifAlone;
+    case "link_or_media":
+      return labels.linkOrMedia;
+  }
+}

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 };
+    },
+  };
+}