From 3ae68022a2705b42bc6e06332838068271247599 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 18:12:20 -0700
Subject: [PATCH 01/27] =?UTF-8?q?docs:=20spec=20for=20components=20SP2=20?=
 =?UTF-8?q?=E2=80=94=20Listbox,=20and=20PretableSelect?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A select-only combobox on the SP1 contract, built on a Listbox primitive
extracted from the enum cell editor so the grid has one list implementation;
the four native selects migrate, and their test drivers with them.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 ...2026-09-05-components-sp2-select-design.md | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-05-components-sp2-select-design.md

diff --git a/docs/superpowers/specs/2026-09-05-components-sp2-select-design.md b/docs/superpowers/specs/2026-09-05-components-sp2-select-design.md
new file mode 100644
index 00000000..65134fec
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-05-components-sp2-select-design.md
@@ -0,0 +1,242 @@
+# Components SP2: Listbox, and PretableSelect
+
+Date: 2026-09-05
+Status: approved, ready for planning
+
+## Purpose
+
+The second sub-project of the component kit (program and contract:
+`2026-09-04-components-sp1-button-design.md`). Four native `<select>`s remain
+in the grid — the filter dialog's operator picker, the tool panel's column and
+operator pickers, and the grouping section's aggregate picker — and each wears
+the operating system's chrome inside an otherwise designed surface, with a
+popup no theme can reach. This spec replaces them with `PretableSelect`, a
+select-only combobox on the SP1 contract, built on a `Listbox` primitive
+extracted from the enum cell editor so the grid has one list implementation.
+
+## Decisions (each confirmed with the user)
+
+1. **Custom select-only combobox**, not a styled native `<select>` and not a
+   pointer-type hybrid: a kit-styled `button[role="combobox"]` trigger and a
+   portalled `role="listbox"` popover — the WAI-ARIA select-only pattern, and
+   the shape the enum cell editor already uses. Both halves are styleable; the
+   grid owns the keyboard and ARIA contract; existing test drivers migrate.
+2. **Extract a shared `Listbox` from the enum cell editor; migrate the four
+   selects only.** The editor keeps its filtering `<input>` trigger and renders
+   the same list. The group panel's chip listbox is out of scope.
+3. **Data-driven options**: `options: readonly { value: string; label:
+ReactNode; disabled?: boolean }[]`, `value: string`, `onChange(value)`. No
+   children API, no generic value type, no `renderOption` until a site needs it.
+4. **Primitive shape**: a rendered `Listbox` component (the portalled list
+   both consumers render identically) plus a `useListboxKeys` hook (the
+   keyboard both triggers need). Not hook-only (two copies of the ARIA markup),
+   not a component that also owns the trigger (the two triggers differ).
+
+Inherited from SP1 without re-deciding: placement in
+`packages/react/src/components/`; one `components` slot per type; the
+placement prop is `site`; attributes + tokens + `className`/`style` passthrough
+as the styling channel; kit base rules first in `grid.css` and state rules
+last; every migrated site keeps its original `data-pretable-*` attribute; the
+pixel must not move.
+
+## The primitive
+
+### `Listbox` (internal, `packages/react/src/components/listbox.tsx`)
+
+One responsibility: render a portalled list of options from data the trigger
+owns.
+
+```ts
+export interface ListboxOption {
+  readonly value: string;
+  readonly label: ReactNode;
+  readonly disabled?: boolean;
+}
+
+interface ListboxProps {
+  /** The trigger's `aria-controls` target; option ids are `${id}-${index}`. */
+  id: string;
+  options: readonly ListboxOption[];
+  /** `aria-selected` — the committed value, or null. */
+  value: string | null;
+  /** The roving highlight; -1 for none. Owned by the trigger via the hook. */
+  activeIndex: number;
+  /** The trigger's rect; placed by `menuPopoverStyle`. */
+  anchor: DOMRect;
+  "aria-label"?: string;
+  onSelect: (value: string) => void;
+  /** Outside pointerdown. No focus return: the click chose a new target. */
+  onClose: () => void;
+}
+```
+
+- Renders `<ul role="listbox" data-pretable-listbox>` inside `OverlayPortal`,
+  styled by `menuPopoverStyle(anchor)`, with `<li role="option"
+id={`${id}-${i}`} aria-selected aria-disabled data-pretable-option
+data-value>` per option.
+- Keeps the active option scrolled into view when `activeIndex` changes.
+- Renders nothing when `options` is empty (the enum editor's rule: no bare
+  box).
+- Closes on outside pointerdown, without focus return — `useMenuKeyboard`'s
+  contract, and the portal's standing reason.
+- A disabled option is skipped by keyboard navigation and inert to click.
+
+The enum editor's `[data-pretable-enum-listbox]` / `[data-pretable-enum-option]`
+rules move to `[data-pretable-listbox]` / `[data-pretable-option]`; the editor
+keeps passing its own attribute through, as the buttons did.
+
+### `useListboxKeys` (same file)
+
+Owns `activeIndex` and returns `{ activeIndex, setActiveIndex, onKeyDown }`
+for a trigger:
+
+- ArrowDown / ArrowUp move the highlight, wrapping, skipping `disabled`;
+  Home / End jump.
+- **Typeahead**: printable characters accumulate into a buffer that resets
+  after 500 ms and matches an option label's prefix (case-insensitive) — the
+  native `<select>` behaviour a keyboard user expects.
+- Enter and Space commit the active option; Escape closes with focus return
+  to the trigger; Tab closes without consuming the move.
+- On a closed trigger, ArrowDown / ArrowUp / Enter / Space open it.
+
+The enum editor adopts the hook's navigation and keeps its own filtering.
+
+## `PretableSelect`
+
+`packages/react/src/components/select.tsx`.
+
+```ts
+export type PretableSelectOption = ListboxOption;
+
+export interface PretableSelectProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "value" | "onChange" | "aria-label"
+> {
+  options: readonly PretableSelectOption[];
+  value: string;
+  onChange: (value: string) => void;
+  /** REQUIRED. The picker's accessible name; a select with none is the
+   *  IconButton problem again. An empty string warns in development. */
+  "aria-label": string;
+  /** Where in the grid this picker is; lands as `data-pretable-site`. */
+  site?: PretableButtonSite;
+}
+```
+
+Renders `<button type="button" role="combobox" aria-haspopup="listbox"
+aria-expanded aria-controls={listId} aria-activedescendant
+data-pretable-select data-pretable-site data-pretable-value={value}>`
+containing the selected option's label and a `ChevronDownIcon`; opens the
+`Listbox` anchored to its own rect on click or through the hook; commits on
+option click or Enter / Space and closes; `disabled` takes the standard
+treatment. `forwardRef` to the button — the filter dialog focuses its operator
+picker on open through a ref.
+
+A `value` absent from `options` renders the value string itself as the label
+rather than a wrong option — the pruned-operator case both filter pickers
+already guard.
+
+`data-pretable-value` is the test-visible truth that replaces a native
+`.value`.
+
+`PretableButtonSite` gains four built-in names: `filter-operator`,
+`filter-row-column`, `filter-row-operator`, `aggregate`. (The type keeps its
+name; it is the kit's site vocabulary, not the button's.)
+
+## The override slot
+
+`PretableComponents` gains `Select?: PretableSelectComponent`
+(`ComponentType<PretableSelectProps & RefAttributes<HTMLButtonElement>>`).
+`useResolvedComponents` resolves it like the other two — the memo's
+comparison, defaults object and dependency array each gain the slot, and the
+changed-slot test is extended to it, because that four-part edit is exactly
+what the SP1 review flagged as easy to get wrong. A replacement receives the
+options array, `value`, `onChange`, the name and `site`, and owes a forwarded
+`ref`.
+
+## Migration
+
+| site                   | today                                                                                 | becomes                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| filter dialog operator | `<select ref={selectRef} data-pretable-filter-operator aria-label="Filter operator">` | `<Select site="filter-operator" ref={selectRef} …>`; the open-focus keeps working through the ref            |
+| builder column picker  | `<select data-pretable-filter-row-column aria-label={…hidden/groupedAway…}>`          | `<Select site="filter-row-column" …>`; the state-in-the-name label unchanged                                 |
+| builder operator       | `<select data-pretable-filter-row-operator>`                                          | `<Select site="filter-row-operator" …>`                                                                      |
+| aggregate picker       | `<select aria-label={…}>` with DEFAULT / NONE / built-ins / `custom`                  | `<Select site="aggregate" …>`; `custom` is `disabled: true`; the closed-vocabulary check stays in `onChange` |
+
+Every site keeps its `data-pretable-*` attribute (the aggregate picker gains
+`data-pretable-aggregate` so it has one). `OPERATOR_LABELS` stays the one
+un-localised string set, as the docs record.
+
+**Test drivers migrate with the sites, once.** The jsdom helpers that
+`fireEvent.change` a native select become one shared `chooseOption(trigger,
+value)` — click the trigger, click `[data-pretable-option][data-value]` in
+`document.body` — and `.value` assertions become
+`toHaveAttribute("data-pretable-value", …)`. The e2e `toHaveValue` checks in
+`tool-panel.spec.ts` become the same attribute assertion, with picker
+interactions through a `chooseOption` in `e2e/helpers.ts`. No test loses a
+claim; each is re-expressed against the DOM the component renders.
+
+## CSS
+
+- Trigger, in the kit section after the button rules: the shared box on
+  `[data-pretable-select]` — `inline-flex`, `justify-content: space-between`,
+  `gap`, `border: 1px solid var(--pretable-rule)`, `border-radius:
+var(--pretable-radius-control)`, `background: var(--pretable-bg-grid)`,
+  `color: var(--pretable-text-cell)`, `font: inherit`, `padding-inline`,
+  `cursor: pointer`; the caret in `--pretable-text-dim`. Ring and disabled in
+  the state section.
+- Sites keep only their size: the builder's pickers and the aggregate picker
+  `block-size: 24px`; the dialog's `28px`.
+- List: `[data-pretable-listbox]` / `[data-pretable-option]` take the enum
+  rules verbatim (`max-height: 220px`, `--pretable-bg-grid` surface,
+  `--pretable-rule-strong` border, `--pretable-shadow-overlay`, the portaled
+  font trio plus `line-height`, hover and selected tints, `:empty` hidden).
+- Guards: the site guard's `OWN` table gains the four select sites; the kit
+  guard asserts the trigger declarations; the bracket guard already covers
+  ordering. Forced colours: `[data-pretable-option][aria-selected="true"]`
+  takes `Highlight` / `HighlightText` with `forced-color-adjust: none`, the
+  same answer as cell selection. Reduced motion: nothing animates.
+
+## Measurement
+
+The measurement script gains four entries — the trigger boxes at rest and on
+focus — recorded before any code changes. The native popup was never
+measurable, so the list has no baseline; its look is the enum editor's, which
+is unchanged by the extraction. Definition of done: no trigger pixel moves.
+
+## Testing
+
+- **Primitive** (jsdom): `useListboxKeys` — every key, wrapping, disabled
+  skipping, typeahead accumulate and reset, open-on-key; `Listbox` — markup
+  and ARIA per option, active scroll-into-view, empty renders nothing,
+  outside click closes. Each negative claim with its positive twin;
+  mutation-checked.
+- **Select**: opens on click / ArrowDown / Enter / Space; commits on option
+  click / Enter; Escape closes and refocuses; Tab closes;
+  `aria-activedescendant` tracks; an absent `value` renders as its own label;
+  `data-pretable-value` is written; the name is a type error to omit (type
+  test) and warns when empty.
+- **Enum editor**: its existing suite passes unchanged after the extraction.
+- **Override**: `components.Select` replaces all four sites, including the one
+  in the portalled dialog; a stable map does not remount; all four sites
+  pinned to the kit component and site name.
+- **Browser** (`/fixtures/components` gains the pickers): keyboard-only
+  selection in webkit including typeahead; the dialog's operator picker
+  focused on open; a replaced Select receives that open-focus through its
+  ref. `bench:e2e` and the website suites the migration touches.
+
+## Docs
+
+The Components page gains a Select section (props table registered with the
+api-surface guard). Three sentences stop saying "select": `filtering.mdx`'s
+"an operator select", `tool-panel.mdx`'s "one `<select>` per aggregate row",
+and its note that the add-group menu shares the pickers' keyboard — now
+literally true. Changeset: minor `@pretable/react`, patch `@pretable/ui`, with
+the note that consumers who located these pickers as `select` elements now
+find a `button[role="combobox"]` carrying `data-pretable-value`.
+
+## Out of scope
+
+Rich option rendering, multi-select, a search input inside the Select (the
+enum editor's job), the group panel's chip listbox, a native-`<select>`
+fallback for coarse pointers, and every input control (SP3).

From 3cabff549e89e469275c8102a9c010dfed187cbd Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 18:22:07 -0700
Subject: [PATCH 02/27] docs: components SP2 implementation plan

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../plans/2026-09-05-components-sp2-select.md | 1535 +++++++++++++++++
 1 file changed, 1535 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-09-05-components-sp2-select.md

diff --git a/docs/superpowers/plans/2026-09-05-components-sp2-select.md b/docs/superpowers/plans/2026-09-05-components-sp2-select.md
new file mode 100644
index 00000000..d21340f6
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-05-components-sp2-select.md
@@ -0,0 +1,1535 @@
+# Components SP2: Listbox and PretableSelect Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the grid's four native `<select>`s with `PretableSelect`, a select-only combobox on the SP1 contract, built on a `Listbox` primitive extracted from the enum cell editor — with no trigger pixel moving and no test losing a claim.
+
+**Architecture:** `components/listbox.tsx` holds the shared list (`Listbox`: portalled `ul[role=listbox]` placed by `menuPopoverStyle`, active-option scroll, outside-click close) and the shared keyboard (`useListboxKeys`: arrows/Home/End with wrap and disabled-skip, 500 ms typeahead, Enter/Space commit, Escape/Tab close, open-on-key). `EnumCellEditor` renders `Listbox` and keeps its filtering `<input>`. `components/select.tsx` is `PretableSelect`: a `button[role=combobox]` trigger carrying `data-pretable-select` / `-site` / `-value`. `PretableComponents` gains a `Select` slot. The four sites migrate keeping their `data-pretable-*` attributes; their CSS rules, which today select by element type (`… select`), are rewritten onto those attributes; test drivers move from native-select semantics (`fireEvent.change`, `.value`, `toHaveValue`, `selectOption`) to one `chooseOption` helper per layer and `data-pretable-value` assertions.
+
+**Tech Stack:** React 18/19 (`forwardRef`), TypeScript, vitest + testing-library (jsdom), Playwright (website e2e + bench), api-extractor, changesets. Vanilla CSS in `packages/*`.
+
+**Spec:** `docs/superpowers/specs/2026-09-05-components-sp2-select-design.md`. SP1's contract and traps: `docs/superpowers/specs/2026-09-04-components-sp1-button-design.md` and the memory note `project-components-kit-sp1`.
+
+**Repo rules that bite here:**
+
+- Run every verification from the **repo root**. `pnpm bench:e2e` is a separate Playwright project — run it. `pnpm build` before `pnpm api`. Only ONE agent may build at a time (concurrent builds produce phantom `Cannot find module` / missing-`dist` failures).
+- Mutation-check every guard, and record it in the commit message. Revert a probe by re-editing, never `git checkout -- file` (it wipes all uncommitted work in that file).
+- The build uses the classic JSX runtime: keep the `createElement` import in every `.tsx`.
+- `usePretableComponents()` is the FIRST statement of a component body. Imports go in each file's sorted relative-import position.
+- Never `git stash`; never touch `~/repos/pretable`.
+- Commit attribution: `Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>`.
+
+---
+
+## File structure
+
+**Create**
+
+| file | responsibility |
+| --- | --- |
+| `packages/react/src/components/listbox.tsx` | `ListboxOption`, `Listbox` (the rendered portalled list), `useListboxKeys` (the trigger keyboard) — internal |
+| `packages/react/src/components/select.tsx` | `PretableSelect`, `PretableSelectProps`, `PretableSelectOption` — public |
+| `packages/react/src/__tests__/components-listbox.test.tsx` | the primitive's behaviour |
+| `packages/react/src/__tests__/components-select.test.tsx` | the Select's behaviour |
+| `packages/react/src/__tests__/select-helpers.ts` | `chooseOption`, `readOptions` for jsdom tests (not a test file) |
+| `type-tests/react/components-select.types.tsx` | the compile-time contract |
+
+**Modify**
+
+| file | change |
+| --- | --- |
+| `packages/react/src/editors/EnumCellEditor.tsx` | render `Listbox`; navigation through `useListboxKeys`; filtering kept |
+| `packages/react/src/components/button.tsx` | `PretableBuiltInButtonSite` gains four select sites |
+| `packages/react/src/components/context.ts` | `Select` slot; resolution; `PretableSelectComponent` |
+| `packages/react/src/filter-menu/FilterMenu.tsx` | operator `<select>` → `Select` (ref kept) |
+| `packages/react/src/tool-panel/filters/FilterRow.tsx` | column + operator `<select>` → `Select` |
+| `packages/react/src/tool-panel/grouping/GroupingSection.tsx` | aggregate `<select>` → `Select`, gains `data-pretable-aggregate` |
+| `packages/react/src/__tests__/{filter-builder,filter-menu,filter-menu-surface,tool-panel-aggregates-picker,components-override,components-button}.test.tsx` | drivers → helpers; slot tests |
+| `packages/ui/grid.css` | trigger rules; list rules renamed; site rules rewritten onto attributes; forced colours |
+| `packages/ui/src/__tests__/css-cascade.test.ts` | select sites in the constants/OWN; kit-trigger guard; listbox guard |
+| `packages/react/src/public_api.ts`, `packages/react/react.api.md` | exports |
+| `apps/website/e2e/helpers.ts`, `apps/website/e2e/tool-panel.spec.ts`, `apps/website/e2e/components.spec.ts`, `apps/website/app/fixtures/components/page.tsx` | e2e helper; driver migration; Select proof |
+| `apps/website/content/docs/grid/components.mdx`, `filtering.mdx`, `tool-panel.mdx`, `apps/website/lib/docs/__tests__/docs-api-surface.test.ts` | Select section; three sentences; registrations |
+| `.changeset/components-sp2-select.md` | minor react, patch ui |
+
+---
+
+### Task 1: Record the four trigger boxes before anything moves
+
+**Files:**
+- Create (scratch, not committed): `<scratchpad>/measure-selects.mjs`
+- Output: `<scratchpad>/selects-before.json`
+
+- [ ] **Step 1: Build and serve**
+
+```bash
+pnpm build && (cd apps/website && pnpm exec next start -p 3117 > /tmp/pt-server.log 2>&1 &) && sleep 6 && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3117/
+```
+Expected: last line `200`.
+
+- [ ] **Step 2: Write the script**
+
+```js
+// <scratchpad>/measure-selects.mjs — run from apps/website
+import { chromium } from "@playwright/test";
+import fs from "node:fs";
+
+const OUT = process.argv[2];
+const PROPS = [
+  "display", "alignItems", "justifyContent", "width", "height",
+  "paddingTop", "paddingRight", "paddingBottom", "paddingLeft",
+  "borderTopWidth", "borderTopColor", "borderRadius", "backgroundColor",
+  "color", "fontSize", "fontFamily", "lineHeight", "cursor", "flex",
+  "minWidth", "boxSizing",
+];
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+const read = (selector) =>
+  page.evaluate(({ selector, PROPS }) => {
+    const el = document.querySelector(selector);
+    if (!el) return null;
+    const at = (s) => Object.fromEntries(PROPS.map((p) => [p, s[p]]));
+    const rest = at(getComputedStyle(el));
+    el.focus();
+    const f = getComputedStyle(el);
+    const focus = { outline: f.outline, outlineOffset: f.outlineOffset };
+    el.blur();
+    const r = el.getBoundingClientRect();
+    return { rest, focus, box: { w: Math.round(r.width), h: Math.round(r.height) } };
+  }, { selector, PROPS });
+
+const result = {};
+await page.goto("http://localhost:3117/", { waitUntil: "networkidle" });
+await page.waitForSelector('[data-pretable-hydrated="true"]');
+const calm = page.getByRole("button", { name: /calm/i });
+if (await calm.count()) await calm.first().click();
+await page.hover("[data-pretable-header-row]");
+await page.locator("[data-pretable-filter-funnel]").first().click();
+result["filter-operator"] = await read("[data-pretable-filter-operator]");
+await page.keyboard.press("Escape");
+await page.locator("[data-pretable-tool-tab]").nth(1).click();
+await page.locator("[data-pretable-filter-add]").first().click();
+result["filter-row-column"] = await read("[data-pretable-filter-row-column]");
+result["filter-row-operator"] = await read("[data-pretable-filter-row-operator]");
+
+await page.goto("http://localhost:3117/fixtures/grouping", { waitUntil: "networkidle" });
+await page.waitForSelector('[data-pretable-hydrated="true"]');
+await page.locator("[data-pretable-tool-tab]").nth(2).click();
+result["aggregate"] = await read("[data-pretable-aggregate-row] select");
+
+fs.writeFileSync(OUT, JSON.stringify(result, null, 1));
+const missing = Object.entries(result).filter(([, v]) => v === null).map(([k]) => k);
+console.log(missing.length ? `MISSING: ${missing.join(", ")}` : "all 4 pickers measured");
+await browser.close();
+```
+
+Note for Task 12: after migration the aggregate picker is no longer a `select` element; the re-measure run substitutes `[data-pretable-aggregate-row] [data-pretable-aggregate]` for that one selector (the script accepts an `AFTER=1` env: `process.env.AFTER ? "[data-pretable-aggregate]" : "[data-pretable-aggregate-row] select"`). Add that ternary now so the script is otherwise identical in both runs.
+
+- [ ] **Step 3: Baseline**
+
+```bash
+cp <scratchpad>/measure-selects.mjs apps/website/measure.tmp.mjs && (cd apps/website && node measure.tmp.mjs <scratchpad>/selects-before.json); rm -f apps/website/measure.tmp.mjs
+```
+Expected: `all 4 pickers measured`. Fix a missing site's navigation before continuing; a baseline with a hole proves nothing.
+
+- [ ] **Step 4: Stop the server**
+
+```bash
+pkill -f "next start -p 3117"
+```
+No commit.
+
+---
+
+### Task 2: The `Listbox` primitive and `useListboxKeys`
+
+**Files:**
+- Create: `packages/react/src/components/listbox.tsx`
+- Test: `packages/react/src/__tests__/components-listbox.test.tsx`
+
+- [ ] **Step 1: Write the failing tests**
+
+```tsx
+// packages/react/src/__tests__/components-listbox.test.tsx
+import "@testing-library/jest-dom/vitest";
+import { act, cleanup, fireEvent, render, renderHook } from "@testing-library/react";
+import { createElement, useState } from "react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import {
+  Listbox,
+  useListboxKeys,
+  type ListboxOption,
+} from "../components/listbox";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+const OPTIONS: readonly ListboxOption[] = [
+  { value: "contains", label: "contains" },
+  { value: "equals", label: "equals" },
+  { value: "custom", label: "Custom", disabled: true },
+  { value: "endsWith", label: "ends with" },
+];
+const RECT = { top: 10, left: 20, bottom: 30, right: 120, width: 100, height: 20, x: 20, y: 10, toJSON: () => ({}) } as DOMRect;
+
+describe("Listbox", () => {
+  test("renders the ARIA list from data, portalled to body, placed at the anchor", () => {
+    const onSelect = vi.fn();
+    render(
+      <Listbox id="lb" options={OPTIONS} value="equals" activeIndex={0} anchor={RECT} onSelect={onSelect} onClose={() => {}} />,
+    );
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(list.parentElement).toBe(document.body);
+    expect(list).toHaveAttribute("role", "listbox");
+    expect(list).toHaveAttribute("id", "lb");
+    expect((list as HTMLElement).style.position).toBe("fixed");
+    const options = list.querySelectorAll("[data-pretable-option]");
+    expect(options).toHaveLength(4);
+    expect(options[0]).toHaveAttribute("id", "lb-0");
+    expect(options[0]).toHaveAttribute("role", "option");
+    expect(options[0]).toHaveAttribute("data-value", "contains");
+    // aria-selected is the COMMITTED value, not the highlight.
+    expect(options[1]).toHaveAttribute("aria-selected", "true");
+    expect(options[0]).toHaveAttribute("aria-selected", "false");
+    expect(options[2]).toHaveAttribute("aria-disabled", "true");
+  });
+
+  test("clicking an option selects it; a disabled option is inert", () => {
+    const onSelect = vi.fn();
+    render(<Listbox id="lb" options={OPTIONS} value={null} activeIndex={-1} anchor={RECT} onSelect={onSelect} onClose={() => {}} />);
+    fireEvent.click(document.querySelector('[data-pretable-option][data-value="endsWith"]')!);
+    expect(onSelect).toHaveBeenCalledWith("endsWith");
+    fireEvent.click(document.querySelector('[data-pretable-option][data-value="custom"]')!);
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  test("renders nothing for an empty list, not a bare box", () => {
+    render(<Listbox id="lb" options={[]} value={null} activeIndex={-1} anchor={RECT} onSelect={() => {}} onClose={() => {}} />);
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("an outside pointerdown closes; one inside does not", () => {
+    const onClose = vi.fn();
+    render(<Listbox id="lb" options={OPTIONS} value={null} activeIndex={0} anchor={RECT} onSelect={() => {}} onClose={onClose} />);
+    fireEvent.pointerDown(document.querySelector("[data-pretable-option]")!);
+    expect(onClose).not.toHaveBeenCalled();
+    fireEvent.pointerDown(document.body);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  test("the active option is scrolled into view when the index changes", () => {
+    const scrolled: string[] = [];
+    Element.prototype.scrollIntoView = function () {
+      scrolled.push((this as HTMLElement).id);
+    };
+    function Host() {
+      const [i, setI] = useState(0);
+      return (
+        <>
+          <button onClick={() => setI(3)}>go</button>
+          <Listbox id="lb" options={OPTIONS} value={null} activeIndex={i} anchor={RECT} onSelect={() => {}} onClose={() => {}} />
+        </>
+      );
+    }
+    const view = render(<Host />);
+    fireEvent.click(view.getByText("go"));
+    expect(scrolled.at(-1)).toBe("lb-3");
+  });
+});
+
+describe("useListboxKeys", () => {
+  const key = (k: string) => ({ key: k, preventDefault: vi.fn(), stopPropagation: vi.fn() }) as unknown as React.KeyboardEvent;
+
+  function setup(open = true) {
+    const onOpen = vi.fn();
+    const onCommit = vi.fn();
+    const onClose = vi.fn();
+    const hook = renderHook(() =>
+      useListboxKeys({ options: OPTIONS, open, initialIndex: 0, onOpen, onCommit, onClose }),
+    );
+    return { hook, onOpen, onCommit, onClose };
+  }
+
+  test("ArrowDown/ArrowUp move with wrap and skip a disabled option", () => {
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(1);
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(3); // skipped "custom"
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(0); // wrapped
+    act(() => hook.result.current.onKeyDown(key("ArrowUp")));
+    expect(hook.result.current.activeIndex).toBe(3);
+  });
+
+  test("Home and End jump to the first and last enabled option", () => {
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("End")));
+    expect(hook.result.current.activeIndex).toBe(3);
+    act(() => hook.result.current.onKeyDown(key("Home")));
+    expect(hook.result.current.activeIndex).toBe(0);
+  });
+
+  test("typeahead matches a label prefix and resets after 500ms", () => {
+    vi.useFakeTimers();
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("e")));
+    expect(hook.result.current.activeIndex).toBe(1); // "equals"
+    act(() => hook.result.current.onKeyDown(key("n")));
+    expect(hook.result.current.activeIndex).toBe(3); // "en…" → "ends with"
+    act(() => vi.advanceTimersByTime(600));
+    act(() => hook.result.current.onKeyDown(key("c")));
+    expect(hook.result.current.activeIndex).toBe(0); // buffer reset: "c" → "contains" (Custom is disabled)
+  });
+
+  test("Enter and Space commit the active option; Escape and Tab close", () => {
+    const { hook, onCommit, onClose } = setup();
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    const enter = key("Enter");
+    act(() => hook.result.current.onKeyDown(enter));
+    expect(onCommit).toHaveBeenCalledWith("equals");
+    expect(enter.preventDefault).toHaveBeenCalled();
+    act(() => hook.result.current.onKeyDown(key(" ")));
+    expect(onCommit).toHaveBeenCalledTimes(2);
+    act(() => hook.result.current.onKeyDown(key("Escape")));
+    expect(onClose).toHaveBeenCalledWith({ restoreFocus: true });
+    const tab = key("Tab");
+    act(() => hook.result.current.onKeyDown(tab));
+    expect(onClose).toHaveBeenCalledWith({ restoreFocus: false });
+    expect(tab.preventDefault).not.toHaveBeenCalled(); // Tab still moves
+  });
+
+  test("on a closed trigger, the navigation keys open rather than move", () => {
+    const { hook, onOpen } = setup(false);
+    for (const k of ["ArrowDown", "ArrowUp", "Enter", " "]) {
+      act(() => hook.result.current.onKeyDown(key(k)));
+    }
+    expect(onOpen).toHaveBeenCalledTimes(4);
+    expect(hook.result.current.activeIndex).toBe(0);
+  });
+});
+```
+
+- [ ] **Step 2: Run to see them fail**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-listbox.test.tsx; cd ../..
+```
+Expected: FAIL — `Cannot find module '../components/listbox'`.
+
+- [ ] **Step 3: Write the primitive**
+
+```tsx
+// packages/react/src/components/listbox.tsx
+/**
+ * The kit's one list: what a select-only combobox and the enum cell editor
+ * both pop open. Two pieces with two responsibilities, so each trigger keeps
+ * its own shape:
+ *
+ * - `Listbox` RENDERS the portalled `role="listbox"` from data the trigger
+ *   owns — the ARIA markup lives here and nowhere else.
+ * - `useListboxKeys` is the trigger's KEYBOARD: arrows/Home/End with wrap and
+ *   disabled-skip, typeahead, Enter/Space to commit, Escape/Tab to close, and
+ *   the navigation keys opening a closed trigger — the native <select>
+ *   contract a keyboard user expects.
+ *
+ * Portalled for the standing reason: the grid viewport's `contain: content`
+ * would clip a fixed popover. Placed by `menuPopoverStyle`, so a list clamps
+ * against the viewport exactly as the menus do.
+ */
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { menuPopoverStyle } from "../overlay/popover-position";
+import { OverlayPortal } from "../overlay/OverlayPortal";
+
+/** One entry in a list. `disabled` is skipped by the keyboard and inert to click. */
+export interface ListboxOption {
+  readonly value: string;
+  readonly label: ReactNode;
+  readonly disabled?: boolean;
+}
+
+/** How long two keystrokes stay one typeahead query. The native control's feel. */
+const TYPEAHEAD_RESET_MS = 500;
+
+/** Text for typeahead: a string label as is, a node by its rendered text. */
+function labelText(label: ReactNode): string {
+  if (typeof label === "string") return label;
+  if (typeof label === "number") return String(label);
+  return "";
+}
+
+export interface ListboxProps {
+  /** The trigger's `aria-controls` target; option ids are `${id}-${index}`. */
+  id: string;
+  options: readonly ListboxOption[];
+  /** The committed value — `aria-selected` — or null. */
+  value: string | null;
+  /** The roving highlight; -1 for none. Owned by the trigger via the hook. */
+  activeIndex: number;
+  /** The trigger's rect; the list is placed against it. */
+  anchor: DOMRect;
+  "aria-label"?: string;
+  onSelect: (value: string) => void;
+  /** Outside pointerdown. No focus return: the press chose a new target. */
+  onClose: () => void;
+  /** Extra attributes for the `<ul>` — a site's own `data-pretable-*`. */
+  listProps?: Record<`data-${string}`, string>;
+}
+
+export function Listbox({
+  id,
+  options,
+  value,
+  activeIndex,
+  anchor,
+  "aria-label": ariaLabel,
+  onSelect,
+  onClose,
+  listProps,
+}: ListboxProps): ReactElement | null {
+  const rootRef = useRef<HTMLUListElement>(null);
+
+  useEffect(() => {
+    const onPointerDown = (e: PointerEvent) => {
+      const root = rootRef.current;
+      if (root && e.target instanceof Node && !root.contains(e.target)) onClose();
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [onClose]);
+
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    rootRef.current
+      ?.querySelector<HTMLElement>(`[id="${id}-${activeIndex}"]`)
+      ?.scrollIntoView({ block: "nearest" });
+  }, [id, activeIndex]);
+
+  // An empty list is not a list: no bare box (the enum editor's rule).
+  if (options.length === 0) return null;
+
+  return (
+    <OverlayPortal>
+      <ul
+        {...listProps}
+        ref={rootRef}
+        id={id}
+        role="listbox"
+        aria-label={ariaLabel}
+        data-pretable-listbox=""
+        style={menuPopoverStyle(anchor)}
+        // Keep focus on the trigger: a blur before the click lands would
+        // close (or, in the editor, commit) under the pointer.
+        onMouseDown={(e) => e.preventDefault()}
+      >
+        {options.map((option, i) => (
+          <li
+            key={option.value}
+            id={`${id}-${i}`}
+            role="option"
+            aria-selected={option.value === value}
+            aria-disabled={option.disabled ? true : undefined}
+            data-pretable-option=""
+            data-value={option.value}
+            data-active={i === activeIndex ? "" : undefined}
+            onClick={() => {
+              if (!option.disabled) onSelect(option.value);
+            }}
+          >
+            {option.label}
+          </li>
+        ))}
+      </ul>
+    </OverlayPortal>
+  );
+}
+
+export interface UseListboxKeysInput {
+  options: readonly ListboxOption[];
+  /** Whether the list is showing. Closed, the navigation keys OPEN. */
+  open: boolean;
+  /** Where the highlight starts when the list opens (the current value). */
+  initialIndex: number;
+  onOpen: () => void;
+  onCommit: (value: string) => void;
+  onClose: (why: { restoreFocus: boolean }) => void;
+}
+
+export interface UseListboxKeysResult {
+  activeIndex: number;
+  setActiveIndex: (index: number) => void;
+  onKeyDown: (event: KeyboardEvent) => void;
+}
+
+/** The next enabled index from `from` in `dir`, wrapping; `from` if none. */
+function step(options: readonly ListboxOption[], from: number, dir: 1 | -1): number {
+  const n = options.length;
+  for (let k = 1; k <= n; k++) {
+    const i = (from + dir * k + n) % n;
+    if (!options[i]?.disabled) return i;
+  }
+  return from;
+}
+
+function edge(options: readonly ListboxOption[], dir: 1 | -1): number {
+  const n = options.length;
+  for (let k = 0; k < n; k++) {
+    const i = dir === 1 ? k : n - 1 - k;
+    if (!options[i]?.disabled) return i;
+  }
+  return -1;
+}
+
+export function useListboxKeys({
+  options,
+  open,
+  initialIndex,
+  onOpen,
+  onCommit,
+  onClose,
+}: UseListboxKeysInput): UseListboxKeysResult {
+  const [activeIndex, setActiveIndex] = useState(initialIndex);
+  const buffer = useRef("");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Re-seed the highlight from the value each time the list opens.
+  useEffect(() => {
+    if (open) setActiveIndex(initialIndex);
+  }, [open, initialIndex]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      const { key } = e;
+      if (!open) {
+        if (key === "ArrowDown" || key === "ArrowUp" || key === "Enter" || key === " ") {
+          e.preventDefault();
+          onOpen();
+        }
+        return;
+      }
+      if (key === "ArrowDown" || key === "ArrowUp") {
+        e.preventDefault();
+        e.stopPropagation();
+        setActiveIndex((i) => step(options, i < 0 ? -1 : i, key === "ArrowDown" ? 1 : -1));
+        return;
+      }
+      if (key === "Home" || key === "End") {
+        e.preventDefault();
+        setActiveIndex(edge(options, key === "Home" ? 1 : -1));
+        return;
+      }
+      if (key === "Enter" || key === " ") {
+        e.preventDefault();
+        e.stopPropagation();
+        const option = options[activeIndex];
+        if (option && !option.disabled) onCommit(option.value);
+        return;
+      }
+      if (key === "Escape" || key === "Esc") {
+        e.preventDefault();
+        e.stopPropagation();
+        onClose({ restoreFocus: true });
+        return;
+      }
+      if (key === "Tab") {
+        onClose({ restoreFocus: false });
+        return;
+      }
+      // Typeahead: one printable character at a time, accumulated for
+      // TYPEAHEAD_RESET_MS, matched against the labels' prefixes from the top.
+      if (key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        buffer.current += key.toLowerCase();
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+          buffer.current = "";
+        }, TYPEAHEAD_RESET_MS);
+        const query = buffer.current;
+        const hit = options.findIndex(
+          (o) => !o.disabled && labelText(o.label).toLowerCase().startsWith(query),
+        );
+        if (hit >= 0) setActiveIndex(hit);
+      }
+    },
+    [open, options, activeIndex, onOpen, onCommit, onClose],
+  );
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  return { activeIndex, setActiveIndex, onKeyDown };
+}
+```
+
+- [ ] **Step 4: Run the tests to see them pass**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-listbox.test.tsx; cd ../..
+```
+Expected: `Tests  10 passed (10)`. If the typeahead test's second press matches "equals" rather than "ends with", the buffer is not accumulating — the findIndex must run against the whole buffer, not the last key.
+
+- [ ] **Step 5: Mutation-check two guards, then commit**
+
+Temporarily make `step` ignore `disabled` → "skip a disabled option" must fail; revert by re-editing. Temporarily drop `e.stopPropagation()` from the Enter branch → no test fails (it is there for the grid's own key handling, covered in Task 5). Record the first in the message.
+
+```bash
+npx prettier --write packages/react/src/components/listbox.tsx packages/react/src/__tests__/components-listbox.test.tsx
+git add packages/react/src/components/listbox.tsx packages/react/src/__tests__/components-listbox.test.tsx
+git commit -m "feat(react): the Listbox primitive and its trigger keyboard
+
+The kit's one list — the portalled role=listbox markup in one place — and
+the keyboard both triggers need: arrows with wrap and disabled-skip,
+Home/End, 500ms typeahead, Enter/Space, Escape/Tab, and open-on-key for a
+closed trigger. Mutation-checked: ignoring disabled in the step fails the
+skip test.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: The enum editor renders the primitive
+
+**Files:**
+- Modify: `packages/react/src/editors/EnumCellEditor.tsx`
+- Modify: `packages/ui/grid.css` (`[data-pretable-enum-listbox]`/`[data-pretable-enum-option]` rules → `[data-pretable-listbox]`/`[data-pretable-option]`)
+- Test: `packages/react/src/__tests__/enum-cell-editor.test.tsx` must pass **unchanged** (that is the proof)
+
+- [ ] **Step 1: Check what references the two enum attributes**
+
+```bash
+grep -rn "data-pretable-enum-listbox\|data-pretable-enum-option" packages apps --include="*.ts" --include="*.tsx" --include="*.css" --include="*.mdx" | grep -v node_modules | grep -v "/dist/"
+```
+Anything outside `EnumCellEditor.tsx` and `grid.css` (a test, an e2e locator, a docs sentence) keeps working through the passthrough below; list what you found in the commit message.
+
+- [ ] **Step 2: Rewrite the editor's list and keyboard**
+
+Replace the `<OverlayPortal>…</OverlayPortal>` block with:
+
+```tsx
+      <Listbox
+        id={listId}
+        options={visible.map((o) => ({ value: o.value, label: optionLabel(o) }))}
+        value={active ? active.value : null}
+        activeIndex={index}
+        anchor={rect ?? EMPTY_RECT}
+        onSelect={(value) => choose(visible.find((o) => o.value === value))}
+        onClose={() => {
+          // Outside press: the strict combobox reverts unmatched text, as
+          // its onBlur does — the blur will fire on its own.
+        }}
+        listProps={{ "data-pretable-enum-listbox": "" }}
+      />
+```
+with `const EMPTY_RECT = new DOMRect(0, 0, 0, 0);` at module scope guarded for SSR (`typeof DOMRect === "undefined" ? ({ top: 0, left: 0, bottom: 0, right: 0, width: 0, height: 0, x: 0, y: 0, toJSON: () => ({}) } as DOMRect) : new DOMRect(0, 0, 0, 0)`). Before the first measure the list is still rendered (as today) — the `rect ? popoverStyle(rect) : undefined` gap is closed by placing at the empty rect for one frame; keep `useLayoutEffect` measuring as is.
+
+`aria-selected` semantics: today the editor marks the HIGHLIGHT selected (`aria-selected={i === index}`); the primitive marks the committed `value`. Pass `value={active ? active.value : null}` so the rendered `aria-selected` is exactly what it was (the editor has no separate committed value while editing) — the enum test suite asserts on it and must not change. The highlight is `data-active`.
+
+Replace the ArrowDown/ArrowUp branch of the input's `onKeyDown` with the hook: above the return,
+
+```tsx
+  const keys = useListboxKeys({
+    options: visible.map((o) => ({ value: o.value, label: optionLabel(o) })),
+    open: true,
+    initialIndex: index,
+    onOpen: () => {},
+    onCommit: (value) => choose(visible.find((o) => o.value === value), "down"),
+    onClose: () => {},
+  });
+```
+and in `onKeyDown`: `if (e.key === "ArrowDown" || e.key === "ArrowUp" || e.key === "Home" || e.key === "End") { keys.onKeyDown(e); return; }` — then keep the editor's own Enter/Tab branch (it commits with a DIRECTION, which the hook does not know) and its fallthrough to `fieldProps.onKeyDown`. Replace `highlight`/`setHighlight` with `keys.activeIndex`/`keys.setActiveIndex` (the `onChange` handler's `setHighlight(0)` becomes `keys.setActiveIndex(0)`), keeping the clamp `const index = keys.activeIndex < visible.length ? keys.activeIndex : 0;`. Do NOT route the editor's typeahead through the hook — the editor filters by typing; typeahead would fight it. To make that explicit, the hook's printable-character branch must only run when the trigger delegates it; since the editor only forwards the four navigation keys, nothing else reaches the hook.
+
+- [ ] **Step 3: Move the CSS**
+
+In `grid.css`, rename the four enum-list rules' selectors: `[data-pretable-enum-listbox]` → `[data-pretable-listbox]`, `[data-pretable-enum-listbox]:empty` → `[data-pretable-listbox]:empty`, `[data-pretable-enum-option]` → `[data-pretable-option]` (three rules: base, `:hover`, `[aria-selected="true"]`). Add to the list's base rule `line-height: 1.5;` (the portaled-trio-plus-one rule from #580; the guard in Task 7 requires it). Update the comment above them: "the kit's list — the enum editor and PretableSelect both render it". Move this block so it sits in the kit section (after the button rules, before `Multi-sort priority badge`): it is a kit rule now. Then update the `portaled popovers declare the whole inherited trio themselves` guard in `css-cascade.test.ts`: its block regex for `[data-pretable-enum-listbox]` becomes `[data-pretable-listbox]`, and the listbox joins the two blocks that must declare `line-height`.
+
+- [ ] **Step 4: Run — the enum suite unchanged, plus the cascade guards**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/enum-cell-editor.test.tsx src/__tests__/components-listbox.test.tsx; cd ../..
+cd packages/ui && pnpm exec vitest run; cd ../..
+pnpm typecheck; echo exit:$?
+```
+Expected: all pass, `enum-cell-editor.test.tsx` **without any edit** (`git diff --stat -- packages/react/src/__tests__/enum-cell-editor.test.tsx` is empty). If an enum test fails, the extraction changed behaviour — fix the editor/primitive, never the test.
+
+- [ ] **Step 5: Commit**
+
+```bash
+npx prettier --write packages/react/src/editors/EnumCellEditor.tsx packages/ui/grid.css packages/ui/src/__tests__/css-cascade.test.ts
+git add packages/react/src/editors/EnumCellEditor.tsx packages/ui/grid.css packages/ui/src/__tests__/css-cascade.test.ts
+git commit -m "refactor(react,ui): the enum editor renders the kit Listbox
+
+Its list and its arrow keys come from the primitive; its filtering input,
+its direction-aware commit and its strict blur stay its own. The enum
+editor suite passes unchanged, which is the proof. The list rules move to
+[data-pretable-listbox] / [data-pretable-option] in the kit section; the
+editor passes its own attribute through.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: `PretableSelect`
+
+**Files:**
+- Create: `packages/react/src/components/select.tsx`
+- Modify: `packages/react/src/components/button.tsx` (`PretableBuiltInButtonSite` gains `"filter-operator" | "filter-row-column" | "filter-row-operator" | "aggregate"`)
+- Test: `packages/react/src/__tests__/components-select.test.tsx`
+- Create: `packages/react/src/__tests__/select-helpers.ts`
+
+- [ ] **Step 1: The jsdom helpers every later test uses**
+
+```ts
+// packages/react/src/__tests__/select-helpers.ts
+import { fireEvent } from "@testing-library/react";
+
+/**
+ * Drive a PretableSelect the way a pointer does: open it, click the option.
+ * Replaces `fireEvent.change(select, { target: { value } })`, which a
+ * button[role=combobox] cannot honour. The list is portalled to body.
+ */
+export function chooseOption(trigger: HTMLElement, value: string): void {
+  fireEvent.click(trigger);
+  const option = document.querySelector<HTMLElement>(
+    `[data-pretable-listbox] [data-pretable-option][data-value="${value}"]`,
+  );
+  if (!option) {
+    throw new Error(`chooseOption: no option "${value}" in the open list`);
+  }
+  fireEvent.click(option);
+}
+
+/** The option values and labels a PretableSelect offers, read by opening it. */
+export function readOptions(trigger: HTMLElement): { values: string[]; labels: string[] } {
+  fireEvent.click(trigger);
+  const items = Array.from(
+    document.querySelectorAll<HTMLElement>("[data-pretable-listbox] [data-pretable-option]"),
+  );
+  const result = {
+    values: items.map((el) => el.getAttribute("data-value") ?? ""),
+    labels: items.map((el) => el.textContent ?? ""),
+  };
+  fireEvent.keyDown(trigger, { key: "Escape" });
+  return result;
+}
+
+/** The committed value, from the attribute the component writes for exactly this. */
+export function selectValue(trigger: HTMLElement): string | null {
+  return trigger.getAttribute("data-pretable-value");
+}
+```
+
+- [ ] **Step 2: Write the failing tests**
+
+```tsx
+// packages/react/src/__tests__/components-select.test.tsx
+import "@testing-library/jest-dom/vitest";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+import { createRef } from "react";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { PretableSelect } from "../components/select";
+import { resetDevWarnings } from "../dev-warn";
+import { chooseOption, readOptions, selectValue } from "./select-helpers";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+beforeEach(() => {
+  resetDevWarnings();
+});
+
+const OPTIONS = [
+  { value: "contains", label: "contains" },
+  { value: "equals", label: "equals" },
+  { value: "custom", label: "Custom", disabled: true },
+];
+
+function renderSelect(props: Partial<React.ComponentProps<typeof PretableSelect>> = {}) {
+  const onChange = vi.fn();
+  const view = render(
+    <PretableSelect aria-label="Operator" options={OPTIONS} value="contains" onChange={onChange} site="filter-operator" data-pretable-filter-operator="" {...props} />,
+  );
+  const trigger = view.getByRole("combobox", { name: props["aria-label"] ?? "Operator" });
+  return { view, trigger, onChange };
+}
+
+describe("PretableSelect", () => {
+  test("is a select-only combobox carrying the kit attributes and the value", () => {
+    const { trigger } = renderSelect();
+    expect(trigger.tagName).toBe("BUTTON");
+    expect(trigger).toHaveAttribute("type", "button");
+    expect(trigger).toHaveAttribute("aria-haspopup", "listbox");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveAttribute("data-pretable-select", "");
+    expect(trigger).toHaveAttribute("data-pretable-site", "filter-operator");
+    expect(trigger).toHaveAttribute("data-pretable-filter-operator", "");
+    expect(selectValue(trigger)).toBe("contains");
+    expect(trigger).toHaveTextContent("contains");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("opens on click with the current value highlighted, and commits a clicked option", () => {
+    const { trigger, onChange } = renderSelect();
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(trigger).toHaveAttribute("aria-controls", list.id);
+    expect(trigger).toHaveAttribute("aria-activedescendant", `${list.id}-0`);
+    fireEvent.click(list.querySelector('[data-value="equals"]')!);
+    expect(onChange).toHaveBeenCalledWith("equals");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
+  test("the keyboard opens, moves, commits and closes", () => {
+    const { trigger, onChange } = renderSelect();
+    trigger.focus();
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(trigger).toHaveAttribute("aria-activedescendant", expect.stringMatching(/-1$/));
+    fireEvent.keyDown(trigger, { key: "Enter" });
+    expect(onChange).toHaveBeenCalledWith("equals");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    fireEvent.keyDown(trigger, { key: " " });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.keyDown(trigger, { key: "Escape" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveFocus();
+  });
+
+  test("Tab closes without trapping, and an outside press closes", () => {
+    const { trigger } = renderSelect();
+    fireEvent.click(trigger);
+    fireEvent.keyDown(trigger, { key: "Tab" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    fireEvent.click(trigger);
+    fireEvent.pointerDown(document.body);
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  test("a value absent from the options renders as its own label, not a wrong option", () => {
+    // The pruned-operator case: the applied operator is not in the permitted
+    // list; a native <select> would silently display its first option.
+    const { trigger } = renderSelect({ value: "endsWith" });
+    expect(trigger).toHaveTextContent("endsWith");
+    expect(selectValue(trigger)).toBe("endsWith");
+  });
+
+  test("the helpers drive it: chooseOption commits, readOptions lists", () => {
+    const { trigger, onChange } = renderSelect();
+    expect(readOptions(trigger)).toEqual({ values: ["contains", "equals", "custom"], labels: ["contains", "equals", "Custom"] });
+    chooseOption(trigger, "equals");
+    expect(onChange).toHaveBeenCalledWith("equals");
+  });
+
+  test("disabled takes the standard treatment and does not open", () => {
+    const { trigger } = renderSelect({ disabled: true });
+    expect(trigger).toBeDisabled();
+    fireEvent.click(trigger);
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("forwards its ref; className and style pass through", () => {
+    const ref = createRef<HTMLButtonElement>();
+    const { trigger } = renderSelect({ ref, className: "mine", style: { width: 120 } } as never);
+    expect(ref.current).toBe(trigger);
+    expect(trigger).toHaveClass("mine");
+    expect(trigger.style.width).toBe("120px");
+  });
+
+  test("warns in development on an empty accessible name", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(<PretableSelect aria-label="  " options={OPTIONS} value="contains" onChange={() => {}} />);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toMatch(/PretableSelect/);
+  });
+});
+```
+
+- [ ] **Step 3: Run to see them fail**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-select.test.tsx; cd ../..
+```
+Expected: FAIL — `Cannot find module '../components/select'`.
+
+- [ ] **Step 4: Extend the site union and write the component**
+
+In `button.tsx`, add to `PretableBuiltInButtonSite`: `| "filter-operator" | "filter-row-column" | "filter-row-operator" | "aggregate"` with a comment: "the select sites — one vocabulary for every kit control's placement, not a per-component union".
+
+```tsx
+// packages/react/src/components/select.tsx
+/**
+ * A select-only combobox: the kit's answer to the native <select>, whose open
+ * list no theme can reach. The trigger is a button carrying
+ * role="combobox"; the list is the kit's `Listbox`, portalled and placed
+ * against the trigger. Both halves are styled by grid.css through
+ * `data-pretable-select` (trigger) and `data-pretable-listbox` /
+ * `data-pretable-option` (list), and a site's own attribute still arrives on
+ * the trigger through the spread.
+ *
+ * `data-pretable-value` is written for one reason: a button has no `.value`,
+ * and every test that used to read one reads this instead.
+ */
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type ReactElement,
+} from "react";
+
+import { warnOnce } from "../dev-warn";
+import { ChevronDownIcon } from "../icons";
+import type { PretableButtonSite } from "./button";
+import { Listbox, useListboxKeys, type ListboxOption } from "./listbox";
+
+/**
+ * One entry in a {@link PretableSelect}. A `disabled` option is shown, skipped
+ * by the keyboard, and inert to click — how the aggregate picker shows a
+ * consumer-written custom aggregate it must never write back.
+ *
+ * @public
+ */
+export type PretableSelectOption = ListboxOption;
+
+/**
+ * Props for {@link PretableSelect}.
+ *
+ * @public
+ */
+export interface PretableSelectProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "value" | "onChange" | "aria-label"
+> {
+  options: readonly PretableSelectOption[];
+  /** The committed value. Absent from `options`, it renders as its own label. */
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Required. A picker with no accessible name is the icon-button problem
+   * again. An empty string warns in development.
+   */
+  "aria-label": string;
+  /** Where in the grid this picker is; lands as `data-pretable-site`. */
+  site?: PretableButtonSite;
+}
+
+const EMPTY_RECT: DOMRect =
+  typeof DOMRect === "undefined"
+    ? ({ top: 0, left: 0, bottom: 0, right: 0, width: 0, height: 0, x: 0, y: 0, toJSON: () => ({}) } as DOMRect)
+    : new DOMRect(0, 0, 0, 0);
+
+/**
+ * A select-only combobox in the grid's own chrome.
+ *
+ * ```tsx
+ * <PretableSelect
+ *   aria-label="Filter operator"
+ *   options={operators.map((op) => ({ value: op, label: OPERATOR_LABELS[op] }))}
+ *   value={draft.operator}
+ *   onChange={(op) => setOperator(op as FilterOperator)}
+ * />
+ * ```
+ *
+ * @public
+ */
+export const PretableSelect = forwardRef<HTMLButtonElement, PretableSelectProps>(
+  function PretableSelect(
+    { options, value, onChange, "aria-label": ariaLabel, site, disabled, onClick, ...buttonProps },
+    ref,
+  ): ReactElement {
+    if ((ariaLabel ?? "").trim() === "") {
+      warnOnce(
+        "select-empty-name",
+        "[pretable] <PretableSelect> rendered with an empty aria-label. A picker with no accessible name reads as an unnamed button to a screen reader. Name what it chooses, e.g. `Filter operator`.",
+      );
+    }
+    const listId = useId();
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    useImperativeHandle(ref, () => triggerRef.current as HTMLButtonElement);
+    const [open, setOpen] = useState(false);
+    const [rect, setRect] = useState<DOMRect>(EMPTY_RECT);
+
+    const selectedIndex = options.findIndex((o) => o.value === value);
+    const selected = options[selectedIndex];
+
+    const close = useCallback((why: { restoreFocus: boolean }) => {
+      setOpen(false);
+      if (why.restoreFocus) triggerRef.current?.focus({ preventScroll: true });
+    }, []);
+    const commit = useCallback(
+      (next: string) => {
+        if (next !== value) onChange(next);
+        close({ restoreFocus: true });
+      },
+      [value, onChange, close],
+    );
+    const openList = useCallback(() => {
+      if (disabled) return;
+      if (triggerRef.current) setRect(triggerRef.current.getBoundingClientRect());
+      setOpen(true);
+    }, [disabled]);
+
+    const keys = useListboxKeys({
+      options,
+      open,
+      initialIndex: selectedIndex >= 0 ? selectedIndex : 0,
+      onOpen: openList,
+      onCommit: commit,
+      onClose: close,
+    });
+
+    // The list is `position: fixed` in a portal: re-anchor when anything
+    // scrolls or resizes while it is open (capture catches the grid's own
+    // scrollers, which do not bubble).
+    useLayoutEffect(() => {
+      if (!open) return;
+      const measure = () => {
+        if (triggerRef.current) setRect(triggerRef.current.getBoundingClientRect());
+      };
+      window.addEventListener("scroll", measure, true);
+      window.addEventListener("resize", measure);
+      return () => {
+        window.removeEventListener("scroll", measure, true);
+        window.removeEventListener("resize", measure);
+      };
+    }, [open]);
+
+    return (
+      <>
+        <button
+          {...buttonProps}
+          ref={triggerRef}
+          type="button"
+          role="combobox"
+          aria-label={ariaLabel}
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-controls={open ? listId : undefined}
+          aria-activedescendant={open && keys.activeIndex >= 0 ? `${listId}-${keys.activeIndex}` : undefined}
+          disabled={disabled}
+          data-pretable-select=""
+          data-pretable-site={site}
+          data-pretable-value={value}
+          onClick={(e) => {
+            onClick?.(e);
+            if (e.defaultPrevented) return;
+            if (open) close({ restoreFocus: true });
+            else openList();
+          }}
+          onKeyDown={(e) => {
+            buttonProps.onKeyDown?.(e);
+            if (e.defaultPrevented) return;
+            keys.onKeyDown(e);
+          }}
+        >
+          <span data-pretable-select-label="">{selected ? selected.label : value}</span>
+          <ChevronDownIcon />
+        </button>
+        {open ? (
+          <Listbox
+            id={listId}
+            options={options}
+            value={value}
+            activeIndex={keys.activeIndex}
+            anchor={rect}
+            onSelect={commit}
+            onClose={() => close({ restoreFocus: false })}
+          />
+        ) : null}
+      </>
+    );
+  },
+);
+```
+
+Note: `onKeyDown` is in `buttonProps` (not destructured) — the component reads `buttonProps.onKeyDown` then spreads it too; to avoid attaching it twice, destructure `onKeyDown` alongside `onClick`. Do that.
+
+- [ ] **Step 5: Run the tests to see them pass**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-select.test.tsx; cd ../..
+pnpm typecheck; echo exit:$?
+```
+Expected: `Tests  9 passed (9)`, typecheck 0. If `toHaveFocus()` fails after a click-commit in jsdom, `focus({ preventScroll })` is fine in jsdom; check that `close` runs after `onChange` (it does) and that the trigger is still mounted.
+
+- [ ] **Step 6: Commit**
+
+```bash
+npx prettier --write packages/react/src/components/select.tsx packages/react/src/components/button.tsx packages/react/src/__tests__/components-select.test.tsx packages/react/src/__tests__/select-helpers.ts
+git add packages/react/src/components/select.tsx packages/react/src/components/button.tsx packages/react/src/__tests__/components-select.test.tsx packages/react/src/__tests__/select-helpers.ts
+git commit -m "feat(react): PretableSelect, a select-only combobox on the kit Listbox
+
+A button[role=combobox] trigger carrying data-pretable-select / -site /
+-value and the kit list beneath it; opens on click and on the navigation
+keys, commits on option click or Enter/Space, closes on Escape (focus
+returned), Tab and outside press. A value absent from the options renders
+as its own label — the pruned-operator case. jsdom helpers replace the
+native-select drivers every later test used.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: The type contract
+
+**Files:**
+- Create: `type-tests/react/components-select.types.tsx` (imports from the SOURCE path until Task 9 switches it, with the same `TEMPORARY` marker SP1 used)
+
+- [ ] **Step 1: Write it**
+
+```tsx
+// type-tests/react/components-select.types.tsx
+// TEMPORARY: imported from source because `@pretable/react` does not export
+// these yet. Task 9 of the SP2 plan switches this to the package.
+import {
+  PretableSelect,
+  type PretableSelectOption,
+  type PretableSelectProps,
+} from "../../packages/react/src/components/select";
+import type { PretableButtonSite } from "../../packages/react/src/components/button";
+import type { Equal, Expect } from "../shared/assert";
+
+const options: readonly PretableSelectOption[] = [{ value: "a", label: "A" }, { value: "b", label: "B", disabled: true }];
+
+// The name is required.
+// @ts-expect-error — aria-label is required
+<PretableSelect options={options} value="a" onChange={() => {}} />;
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}} />;
+
+// The value is a string, and onChange hands one back.
+// @ts-expect-error — value is a string
+<PretableSelect aria-label="Pick" options={options} value={1} onChange={() => {}} />;
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={(v) => { const s: string = v; void s; }} />;
+
+// No `type`, no native `onChange`/`value` shapes leak through.
+// @ts-expect-error — the element is always type="button"
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}} type="submit" />;
+
+// The four select sites are in the kit's vocabulary, and it stays open.
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}} site="filter-operator" />;
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}} site="my-app-picker" />;
+export type SelectSitesAreBuiltIn = Expect<
+  Equal<Extract<PretableButtonSite, "aggregate" | "filter-row-column">, "aggregate" | "filter-row-column">
+>;
+
+// Refs and native attributes flow through.
+const ref = { current: null as HTMLButtonElement | null };
+<PretableSelect ref={ref} aria-label="Pick" options={options} value="a" onChange={() => {}} disabled className="x" />;
+
+export type NameIsRequired = Expect<Equal<PretableSelectProps["aria-label"], string>>;
+```
+
+- [ ] **Step 2: Run, then mutation-check one directive**
+
+```bash
+pnpm exec tsc -p type-tests/tsconfig.react.json --noEmit; echo exit:$?
+```
+Expected exit 0. Comment out the `value={1}` directive → tsc must fail (`TS2322`); restore.
+
+- [ ] **Step 3: Commit**
+
+```bash
+npx prettier --write type-tests/react/components-select.types.tsx
+git add type-tests/react/components-select.types.tsx
+git commit -m "test(react): pin the PretableSelect type contract
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: The `Select` slot
+
+**Files:**
+- Modify: `packages/react/src/components/context.ts`
+- Test: append to `packages/react/src/__tests__/components-button.test.tsx`'s `components context` block
+
+- [ ] **Step 1: Write the failing tests** (append inside `describe("components context")`)
+
+```tsx
+  test("the Select slot resolves like the other two, and its own change is its own", () => {
+    const MySelect = forwardRef<HTMLButtonElement, ComponentProps<typeof PretableSelect>>(
+      (props, ref) => <button {...(props as object)} ref={ref} data-mine="" />,
+    );
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: {} as { Select?: typeof MySelect } } },
+    );
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    expect(result.current.Select).toBe(PretableSelect);
+    rerender({ components: { Select: MySelect } });
+    expect(result.current.Select).toBe(MySelect);
+    expect(result.current.Button).toBe(PretableButton);
+    const withSelect = result.current;
+    rerender({ components: { Select: MySelect } });
+    expect(result.current).toBe(withSelect);
+    // The four-part edit the SP1 review flagged: the slot must be in the
+    // comparison, the defaults, the literal AND the deps. A slot left out of
+    // the deps would make this rerender a stale hit.
+    rerender({ components: {} });
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+  });
+```
+Add `PretableSelect` to the file's imports (from `../components/select`).
+
+- [ ] **Step 2: Run to see it fail**, then **Step 3: add the slot**
+
+In `context.ts`: import `PretableSelect, type PretableSelectProps` from `./select`; add
+
+```ts
+/**
+ * The component a `components.Select` replacement must be: it receives
+ * {@link PretableSelectProps} and forwards its `ref` to the trigger node —
+ * the filter dialog focuses its operator picker on open through that ref.
+ *
+ * @public
+ */
+export type PretableSelectComponent = ComponentType<
+  PretableSelectProps & RefAttributes<HTMLButtonElement>
+>;
+```
+`PretableComponents` gains `/** Every select-only picker the grid draws; receives {@link PretableSelectProps}. */ readonly Select?: PretableSelectComponent;`; `ResolvedPretableComponents` gains `readonly Select: PretableSelectComponent;`; `DEFAULT_COMPONENTS` gains `Select: PretableSelect`; `useResolvedComponents` reads `const Select = components?.Select ?? DEFAULT_COMPONENTS.Select;`, the identity test adds `&& Select === DEFAULT_COMPONENTS.Select`, the literal becomes `Object.freeze({ Button, IconButton, Select })`, the deps `[Button, IconButton, Select]`.
+
+- [ ] **Step 4: Run, mutation-check the deps, commit**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/components-button.test.tsx; cd ../..
+```
+Temporarily drop `Select` from the deps array → the new test must fail on the final `toBe(DEFAULT_COMPONENTS)` or the `MySelect` step; restore by re-editing.
+
+```bash
+npx prettier --write packages/react/src/components/context.ts packages/react/src/__tests__/components-button.test.tsx
+git add packages/react/src/components/context.ts packages/react/src/__tests__/components-button.test.tsx
+git commit -m "feat(react): the Select slot
+
+Comparison, defaults, literal and deps all gain it — the four-part edit —
+and the changed-slot test now covers it; mutation-checked by dropping the
+dep.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 7: The trigger and list CSS, and the guards
+
+**Files:**
+- Modify: `packages/ui/grid.css`
+- Modify: `packages/ui/src/__tests__/css-cascade.test.ts`
+
+- [ ] **Step 1: Write the failing guards**
+
+Add after the kit-button guard:
+
+```ts
+  test("the kit select trigger carries the field box, and the list its surface", () => {
+    const css = strippedCss();
+    const trigger = rulesSelecting(css, (s) => s.includes("data-pretable-select]") && !s.includes("::") && !s.includes(":hover") && !s.includes(":focus") && !s.includes(":disabled"));
+    expect(trigger.length, "no kit select rule").toBeGreaterThan(0);
+    const body = trigger.map((m) => m[2]).join("");
+    for (const decl of [
+      /display:\s*inline-flex/, /align-items:\s*center/, /justify-content:\s*space-between/,
+      /box-sizing:\s*border-box/, /border:\s*1px solid var\(--pretable-rule\)/,
+      /border-radius:\s*var\(--pretable-radius-control\)/, /background:\s*var\(--pretable-bg-grid\)/,
+      /color:\s*var\(--pretable-text-cell\)/, /font:\s*inherit/, /cursor:\s*pointer/, /text-align:\s*start/,
+    ]) expect(body).toMatch(decl);
+    // Ring and disabled ink in the state section, like the buttons.
+    const state = rulesSelecting(css, (s) => s.includes("data-pretable-select]:focus-visible") || s.includes("data-pretable-select]:disabled")).map((m) => m[2]).join("");
+    expect(state).toMatch(/outline:\s*2px solid var\(--pretable-focus-ring\)/);
+    expect(state).toMatch(/cursor:\s*default/);
+    // The list: the enum editor's surface, now the kit's.
+    const list = rulesSelecting(css, (s) => s.includes("data-pretable-listbox]") && !s.includes(":empty")).map((m) => m[2]).join("");
+    expect(list).toMatch(/max-height:\s*220px/);
+    expect(list).toMatch(/border:\s*1px solid var\(--pretable-rule-strong\)/);
+    expect(list).toMatch(/line-height:\s*[^;]+/);
+    const selectedOption = rulesSelecting(css, (s) => s.includes('data-pretable-option][aria-selected="true"]')).map((m) => m[2]).join("");
+    expect(selectedOption).toMatch(/background:\s*var\(--pretable-bg-selected\)/);
+    // No enum-only list rule survives; the editor rides the kit rules.
+    expect(rulesSelecting(css, (s) => s.includes("data-pretable-enum-listbox]") || s.includes("data-pretable-enum-option]")).length).toBe(0);
+    // Forced colours: the selected option is the system's pair.
+    const forced = forcedColorsBlock(css);
+    expect(rulesSelecting(forced, (s) => s.includes('data-pretable-option][aria-selected="true"]')).map((m) => m[2]).join("")).toMatch(/background-color:\s*Highlight/);
+  });
+```
+(`forcedColorsBlock` exists from #578.) Then extend the site constants at the top of the file: `const SELECT_SITES = ["filter-operator", "filter-row-column", "filter-row-operator", "aggregate"];` and, in the `a push-button site rule declares only what is its own` guard, add the select sites to its loop with their own owned list and OWN entries:
+
+```ts
+    const SELECT_OWNED = [
+      /(?:^|[;{\s])display:\s*inline-flex/, /(?:^|[;{\s])border:\s*1px solid var\(--pretable-rule\)/,
+      /border-radius:\s*var\(--pretable-radius-control\)/, /(?:^|[;{\s])background:\s*var\(--pretable-bg-grid\)/,
+      /(?:^|[;{\s])color:\s*var\(--pretable-text-cell\)/, /(?:^|[;{\s])font:\s*inherit/, /(?:^|[;{\s])cursor:\s*pointer/,
+    ];
+    // OWN: the dialog's picker is 28px wide-open in a column; the builder's
+    // and the aggregate picker are 24px flex items.
+    "filter-operator": /block-size:\s*28px/,
+    "filter-row-column": /block-size:\s*24px/,
+    "filter-row-operator": /block-size:\s*24px/,
+    "aggregate": /block-size:\s*24px/,
+```
+The loop runs `SELECT_OWNED` for select sites (and the shared ring/disabled/hover checks). This guard goes RED now (the site rules still declare the box) and green in Task 8.
+
+- [ ] **Step 2: Add the rules**
+
+In the kit section, after the button rules (before the listbox rules moved there in Task 3):
+
+```css
+  /* ---- Kit components: select ------------------------------------------
+     The select-only combobox's trigger. It is a FIELD, not a button: the
+     rule border, the grid surface, the cell ink, and the label at the start
+     with the caret at the end. Sites keep their size and their flex
+     participation; the list beneath it is the kit list above. */
+  :where([data-pretable-select]) {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 6px;
+    padding-inline: 6px;
+    border: 1px solid var(--pretable-rule);
+    border-radius: var(--pretable-radius-control);
+    background: var(--pretable-bg-grid);
+    color: var(--pretable-text-cell);
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+  :where([data-pretable-select-label]) {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  :where([data-pretable-select]) > [data-pretable-icon] {
+    flex: none;
+    color: var(--pretable-text-dim);
+  }
+  :where([data-pretable-option][data-active]) {
+    background: var(--pretable-bg-hover);
+  }
+```
+In the `Kit components: state` section add `[data-pretable-select]:focus-visible` to the ring rule's selector list and `[data-pretable-select]:disabled` to the disabled rule's; in the forced-colours block add `:where([data-pretable-option][aria-selected="true"]) { forced-color-adjust: none; background-color: Highlight; color: HighlightText; }` and `[data-pretable-select]:disabled` to the `GrayText` list.
+
+- [ ] **Step 3: Run — kit guard green, site guard red by design**
+
+```bash
+cd packages/ui && pnpm exec vitest run; cd ../..
+```
+Expected: one failure, `a push-button site rule declares only what is its own`, naming a select site. Paste its first line.
+
+- [ ] **Step 4: Commit**
+
+```bash
+npx prettier --write packages/ui/grid.css packages/ui/src/__tests__/css-cascade.test.ts
+git add packages/ui/grid.css packages/ui/src/__tests__/css-cascade.test.ts
+git commit -m "feat(ui): the kit select rules; the site guard learns the four pickers
+
+Trigger box, label ellipsis, caret, active option, ring and disabled in the
+state section, Highlight/HighlightText under forced colours. The site
+guard is red by design until the pickers' rules collapse.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 8: Migrate the four sites, their CSS, and their jsdom drivers
+
+**Files:**
+- Modify: `FilterMenu.tsx`, `FilterRow.tsx`, `GroupingSection.tsx`, `grid.css`, and the four test files named below
+
+- [ ] **Step 1: FilterMenu — the operator picker**
+
+`const selectRef = useRef<HTMLSelectElement>(null);` → `useRef<HTMLButtonElement>(null)`. Extend the existing `const { Button } = usePretableComponents();` to `const { Button, Select } = …`. Replace the `<select …>…</select>` with:
+
+```tsx
+        <Select
+          ref={selectRef}
+          site="filter-operator"
+          data-pretable-filter-operator=""
+          aria-label="Filter operator"
+          options={operators.map((op) => ({ value: op, label: OPERATOR_LABELS[op] }))}
+          value={draft.operator}
+          onChange={(op) => onOperatorChange(op as FilterOperator)}
+        />
+```
+Keep the comment about `menuOperators` and the pruned operator above it.
+
+- [ ] **Step 2: FilterRow — column and operator**
+
+`const { IconButton, Select } = usePretableComponents();` (extend the existing line). Column:
+
+```tsx
+      <Select
+        site="filter-row-column"
+        data-pretable-filter-row-column=""
+        aria-label={messages.toolPanelFilterColumnLabel({ hidden, groupedAway, groupedMarker: messages.toolPanelColumnGroupedMarker() })}
+        options={columns.map((c) => ({ value: c.id, label: c.label }))}
+        value={columnId}
+        onChange={onColumnChange}
+      />
+```
+(keep the SC 1.4.1 comment). Operator:
+
+```tsx
+      <Select
+        site="filter-row-operator"
+        data-pretable-filter-row-operator=""
+        aria-label={messages.toolPanelFilterOperatorLabel()}
+        options={operators.map((op) => ({ value: op, label: OPERATOR_LABELS[op] }))}
+        value={draft.operator}
+        onChange={(op) => onOperatorChange(op as FilterOperator)}
+      />
+```
+(keep the "not a surface message" comment).
+
+- [ ] **Step 3: GroupingSection — the aggregate picker**
+
+`const { Button, IconButton, Select } = usePretableComponents();`. Replace the `<select …>…</select>` with:
+
+```tsx
+                <Select
+                  site="aggregate"
+                  data-pretable-aggregate=""
+                  aria-label={messages.toolPanelAggregateColumnLabel({ label: column.label })}
+                  options={[
+                    { value: DEFAULT_OPTION, label: messages.toolPanelAggregateDefaultOption({ label: declaredFace }) },
+                    { value: NONE_OPTION, label: messages.toolPanelAggregateNoneOption() },
+                    ...builtins.map((name) => ({ value: name, label: builtinLabel(name) })),
+                    // A consumer CAN write an aggregator object through the
+                    // handle. The picker reflects it honestly: one extra
+                    // selected `Custom` entry, present only while that state
+                    // holds, disabled so it is never written back.
+                    ...(selected === CUSTOM_OPTION
+                      ? [{ value: CUSTOM_OPTION, label: messages.toolPanelAggregateCustomLabel(), disabled: true }]
+                      : []),
+                  ]}
+                  value={selected}
+                  onChange={(value) => {
+                    // The closed vocabulary IS the validation … (keep the comment)
+                    if (value === DEFAULT_OPTION) grid.setColumnAggregate(column.id, undefined);
+                    else if (value === NONE_OPTION) grid.setColumnAggregate(column.id, null);
+                    else if ((builtins as readonly string[]).includes(value)) grid.setColumnAggregate(column.id, value);
+                  }}
+                />
+```
+
+- [ ] **Step 4: CSS — rewrite the type-selected site rules onto attributes**
+
+The builder rule `:where([data-pretable-filter-row-column], [data-pretable-filter-row-operator], input[data-pretable-filter-row-value], [data-pretable-aggregate-row] select)` — the two pickers already select by attribute; replace `[data-pretable-aggregate-row] select` with `[data-pretable-aggregate]`. Then split the rule: the `input[data-pretable-filter-row-value]` keeps the full field box (it is an input, not a kit control); the three pickers keep ONLY `flex: 1 1 auto; min-inline-size: 24px; block-size: 24px;` — write them as their own rule directly after it, with a comment. The dialog rule `:where([data-pretable-filter-menu]) select, … input …` — remove `select` from that list and add a rule `:where([data-pretable-filter-operator]) { width: 100%; block-size: 28px; padding-inline: 7px; }` with a comment (28px: the dialog's roomier padding; 7px matches its inputs). Focus lists: replace `[data-pretable-filter-menu] select:focus-visible` and `[data-pretable-filter-row-column]:focus-visible, [data-pretable-filter-row-operator]:focus-visible, [data-pretable-aggregate-row] select:focus-visible` entries — remove them (the kit state rule rings `[data-pretable-select]`); keep the input entries. Search the file for any other `select` type selector (`grep -n "select" packages/ui/grid.css`) and treat each the same way.
+
+- [ ] **Step 5: Migrate the jsdom drivers**
+
+- `filter-builder.test.tsx`: `operatorSelect`/`columnSelect` query `[data-pretable-filter-row-operator]`/`[data-pretable-filter-row-column]` (drop the `select` tag, type `HTMLElement`); every `fireEvent.change(operatorSelect(c), { target: { value: v } })` → `chooseOption(operatorSelect(c), v)`; every `.value` read → `selectValue(...)`; any `[...select.options]` read → `readOptions(...)`. Import from `./select-helpers`.
+- `filter-menu.test.tsx`: `getByRole("combobox", { name: "Filter operator" })` still resolves (the trigger IS a combobox); `select.value` → `selectValue(select)`; `fireEvent.change(select, …)` → `chooseOption(select, …)`; `toHaveFocus()` on open stays (the ref focuses the trigger).
+- `filter-menu-surface.test.tsx`: `select.value` → `selectValue`; `select.options[select.selectedIndex]?.value` → `selectValue`; `Array.from(select.options).map(o => o.value)` → `readOptions(select).values`.
+- `tool-panel-aggregates-picker.test.tsx`: the picker query loses its `select` tag (`[data-pretable-aggregate-row] [data-pretable-aggregate]`); `optionValues`/`optionLabels` → `readOptions(picker).values/.labels`; `picker.value` → `selectValue(picker)`; `fireEvent.change(picker, {target:{value}})` → `chooseOption(picker, value)`; the "custom" entry assertions read `aria-disabled` on the option rather than expecting it selectable.
+- `components-override.test.tsx`: add `Select` to the 12-site pin tests (four more `expectKit(...)` calls with kind `"select"`, adapting the helper to accept `"select"` → `data-pretable-select`), and one override test: `components={{ Select: MySelect }}` replaces the dialog's operator picker (portalled) and the builder's column picker.
+
+- [ ] **Step 6: Run everything the migration touches**
+
+```bash
+cd packages/react && pnpm exec vitest run --environment jsdom src/__tests__/filter-builder.test.tsx src/__tests__/filter-menu.test.tsx src/__tests__/filter-menu-surface.test.tsx src/__tests__/tool-panel-aggregates-picker.test.tsx src/__tests__/components-override.test.tsx src/__tests__/tool-panel.test.tsx src/__tests__/grouping-options.test.tsx src/__tests__/grouping-aggregate-overrides.test.tsx; cd ../..
+cd packages/ui && pnpm exec vitest run; cd ../..
+pnpm typecheck && pnpm lint; echo exit:$?
+```
+Expected: all green, including the site guard from Task 7. A test that fails on a CLAIM (not a driver) is a behaviour change — investigate the site, not the test.
+
+- [ ] **Step 7: Mutation-check and commit**
+
+Add `border: 1px solid var(--pretable-rule);` back to the aggregate picker's site rule → site guard fails; revert by re-editing.
+
+```bash
+pnpm format:write >/dev/null; git add -A packages/react/src packages/ui
+git commit -m "refactor(react,ui): the four pickers render the kit Select
+
+Filter dialog operator (ref kept — the dialog focuses it on open), the
+builder's column and operator, the aggregate picker (custom entry now a
+disabled option, never written). Every site keeps its attribute; the
+aggregate picker gains one. Site rules that selected by element type are
+rewritten onto the attributes and keep only size and flex participation.
+Test drivers move to chooseOption / readOptions / selectValue; no claim
+changed. Site guard mutation-checked.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 9: Public API and the type test against the package
+
+- [ ] **Step 1:** In `public_api.ts` after the button exports: `export { PretableSelect } from "./components/select"; export type { PretableSelectOption, PretableSelectProps } from "./components/select"; export type { PretableSelectComponent } from "./components/context";` (add it to the existing context type-export block).
+- [ ] **Step 2:** In `type-tests/react/components-select.types.tsx` drop the TEMPORARY comment; import from `"@pretable/react"` (both imports); append `const components: PretableComponents = { Select: PretableSelect }; void components;` with `type PretableComponents` imported.
+- [ ] **Step 3:** `pnpm build && pnpm api && pnpm typecheck:public && pnpm api:check; echo exit:$?` — expect 0; only `packages/react/react.api.md` changes; no `ae-forgotten-export`; no `(undocumented)` on the new symbols.
+- [ ] **Step 4:** Commit `feat(react): export PretableSelect and the Select slot type`.
+
+---
+
+### Task 10: Re-measure the four trigger boxes
+
+- [ ] **Step 1:** `pnpm build`, serve on 3117, run the Task 1 script with `AFTER=1` into `<scratchpad>/selects-after.json`; expect `all 4 pickers measured`.
+- [ ] **Step 2:** Diff with the Task 12 script from SP1 (same flatten/compare). Classify: (a) rendered-equal — `display block→inline-flex/flex` with unchanged box; `justifyContent normal→space-between` with unchanged box; `cursor default→pointer` (a select had `default`? if the baseline says `default`, this IS a deliberate change: record it); (b) deliberate — the product focus ring (a native select wore the UA ring), `text-align start`; (c) anything else — `box.w/h`, padding, border colour, background, font — is a finding: restore the lost declaration to the site rule (sites may keep size/flex/padding-inline/width) and re-measure. Note the width of a `<select>` was content-sized by its widest OPTION; the trigger is sized by its current LABEL — a narrower box for the dialog's picker (`width: 100%`) is unaffected, but the builder's pickers are `flex: 1 1 auto` and share the row, so their widths may legitimately differ by a few px when the row re-flows; treat a builder-picker width change as (a) only if the row's total width is unchanged and each picker still has `flex: 1 1 auto`.
+- [ ] **Step 3:** Stop the server; commit only if a rule was corrected.
+
+---
+
+### Task 11: Docs
+
+- [ ] `components.mdx`: a `### Select` section after IconButton — prose (select-only combobox, keyboard: arrows/Home/End/typeahead/Enter/Escape; options data shape; `disabled` options; a value outside the options renders as its label; `data-pretable-value`) and a `| Prop | Type | Notes |` table with rows `options`, `value`, `onChange`, `aria-label`, `site`; the Replacing table gains a `Select` row. Update the Styling paragraph: "a select carries `data-pretable-select` and writes `data-pretable-value`".
+- [ ] `filtering.mdx:7` "an operator select" → "an operator picker"; `tool-panel.mdx:277` "one `<select>` per aggregate row" → "one aggregate picker per row — a select-only combobox"; and the same paragraph's "the same menu keyboard the filters pane's pickers use" is now literally true — add "(arrows, Home/End, typeahead, Enter, Escape)".
+- [ ] `docs-api-surface.test.ts`: register `"grid/components.mdx#Select": { types: [{ pkg: "react", name: "PretableSelectProps" }], complete: true }` and `MEMBER_TABLE_TYPES` `true`; the Replacing table's binding stays `PretableComponents` (now three rows — the guard requires the new `Select` row).
+- [ ] Run `cd apps/website && pnpm exec vitest run --environment jsdom lib/docs app/docs; cd ../..` — fix tables to satisfy guards, never the guards. Commit `docs: the Select on the Components page; three sentences stop saying select`.
+
+---
+
+### Task 12: Fixture, e2e helper, and the e2e migrations
+
+- [ ] **Fixture** `apps/website/app/fixtures/components/page.tsx`: add a `FixtureSelect: PretableSelectComponent = forwardRef(({ site, options, value, onChange, ...props }, ref) => <button {...props} ref={ref} type="button" data-fixture-select={site ?? ""} data-fixture-value={value} onClick={() => onChange(options[1]?.value ?? value)}>{value}</button>)` and pass `Select: FixtureSelect` in `components`.
+- [ ] **Helper** `apps/website/e2e/helpers.ts`: `export async function chooseOption(page: Page, trigger: Locator, value: string) { await trigger.click(); const option = page.locator(\`[data-pretable-listbox] [data-pretable-option][data-value="${value}"]\`); await expect(option).toBeVisible(); await option.click(); await expect(trigger).toHaveAttribute("data-pretable-value", value); }`.
+- [ ] **`tool-panel.spec.ts`**: every `toHaveValue(x)` on a picker → `toHaveAttribute("data-pretable-value", x)`; `qtyPicker.selectOption("avg")` → `chooseOption(page, page.locator('[data-pretable-aggregate-row][data-pretable-column-id="qty"] [data-pretable-aggregate]'), "avg")`; the `" select"` in that locator goes. The keyboard-order assertions that list `data-pretable-filter-row-column` / `-operator` among tab stops still hold (a button is a tab stop as a select was).
+- [ ] **`components.spec.ts`**: extend test 1 — the dialog's operator picker is `[data-fixture-select="filter-operator"]`; add a test: on the REAL (un-replaced) grid at `/docs/grid/tool-panel` or `/fixtures/grouping`, open the builder's operator picker with the keyboard (`focus`, `ArrowDown`), type `e` (typeahead → "equals" or "ends with" per the labels), `Enter`, and assert `data-pretable-value` — in webkit too.
+- [ ] Build, serve, run `playwright test tool-panel components grid-header-keyboard grid-header-popover-scroll smoke --workers=1`; all pass. Commit `test(website): the pickers in a real browser; e2e drivers move to chooseOption`.
+
+---
+
+### Task 13: Verification, changeset, PR
+
+- [ ] From the root, one builder at a time: `pnpm format:write >/dev/null; pnpm format && pnpm lint && pnpm typecheck && pnpm typecheck:public && pnpm api:check && pnpm test && pnpm bench:e2e` — all exit 0.
+- [ ] Changeset `.changeset/components-sp2-select.md` (`@pretable/react` minor, `@pretable/ui` patch): `PretableSelect` and the `Select` slot; the four pickers now render it; the enum editor's list is the kit's; **for consumers**: the pickers are `button[role="combobox"]` carrying `data-pretable-value`, not `select` elements — tests and styles keyed on `select` must move; the aggregate picker gained `data-pretable-aggregate`; the `custom` aggregate entry is a disabled option; keyboard: arrows, Home/End, typeahead, Enter/Space, Escape.
+- [ ] Commit, `git fetch origin && git log HEAD..origin/main` empty, push, `gh pr create` (body: what ships; the primitive proven by the enum suite passing unchanged; no pixel moved with the classified diff; guards mutation-checked; drivers migrated with no claim changed; browser keyboard/typeahead in webkit; the consumer-facing note), `gh pr merge --squash --auto`. Watch for FAILURE and CANCELLED.
+
+---
+
+## Self-review against the spec
+
+- Primitive (Listbox + hook, portal, placement, scroll, empty, outside-click, disabled) → Task 2. Enum editor renders it, suite unchanged → Task 3. Select contract (combobox trigger, attributes, open/commit/close keys, absent value, `data-pretable-value`, required name + warning, ref) → Task 4; type contract → Tasks 5, 9. Slot + four-part memo → Task 6. CSS (trigger, list rename, state, forced colours, guards incl. OWN) → Tasks 3, 7, 8. Migration + attributes kept + type-selected rules rewritten + jsdom drivers → Task 8. Measurement → Tasks 1, 10. Docs + registrations → Task 11. Fixture/e2e/helper → Task 12. Changeset/PR → Task 13. Out of scope untouched.
+- Names: `Listbox`, `ListboxOption`, `useListboxKeys` (`UseListboxKeysInput`/`Result`), `PretableSelect`, `PretableSelectProps`, `PretableSelectOption`, `PretableSelectComponent`; attributes `data-pretable-select`, `data-pretable-select-label`, `data-pretable-value`, `data-pretable-listbox`, `data-pretable-option`, `data-value`, `data-active`, `data-pretable-aggregate`; helpers `chooseOption`, `readOptions`, `selectValue`; sites `filter-operator`, `filter-row-column`, `filter-row-operator`, `aggregate`.

From c31a5ed1223cdd998dbe902b0f3a25d75251c8a6 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 20:45:21 -0700
Subject: [PATCH 03/27] feat(react): the Listbox primitive and its trigger
 keyboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The kit's one list — the portalled role=listbox markup in one place — and
the keyboard both triggers need: arrows with wrap and disabled-skip,
Home/End, 500ms typeahead, Enter/Space, Escape/Tab, and open-on-key for a
closed trigger. Mutation-checked: ignoring disabled in the step fails the
skip test.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-listbox.test.tsx | 238 ++++++++++++++++
 packages/react/src/components/listbox.tsx     | 265 ++++++++++++++++++
 2 files changed, 503 insertions(+)
 create mode 100644 packages/react/src/__tests__/components-listbox.test.tsx
 create mode 100644 packages/react/src/components/listbox.tsx

diff --git a/packages/react/src/__tests__/components-listbox.test.tsx b/packages/react/src/__tests__/components-listbox.test.tsx
new file mode 100644
index 00000000..c8dfe014
--- /dev/null
+++ b/packages/react/src/__tests__/components-listbox.test.tsx
@@ -0,0 +1,238 @@
+import "@testing-library/jest-dom/vitest";
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  renderHook,
+} from "@testing-library/react";
+import { createElement, useState } from "react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import {
+  Listbox,
+  useListboxKeys,
+  type ListboxOption,
+} from "../components/listbox";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+const OPTIONS: readonly ListboxOption[] = [
+  { value: "contains", label: "contains" },
+  { value: "equals", label: "equals" },
+  { value: "custom", label: "Custom", disabled: true },
+  { value: "endsWith", label: "ends with" },
+];
+const RECT = {
+  top: 10,
+  left: 20,
+  bottom: 30,
+  right: 120,
+  width: 100,
+  height: 20,
+  x: 20,
+  y: 10,
+  toJSON: () => ({}),
+} as DOMRect;
+
+describe("Listbox", () => {
+  test("renders the ARIA list from data, portalled to body, placed at the anchor", () => {
+    const onSelect = vi.fn();
+    render(
+      <Listbox
+        id="lb"
+        options={OPTIONS}
+        value="equals"
+        activeIndex={0}
+        anchor={RECT}
+        onSelect={onSelect}
+        onClose={() => {}}
+      />,
+    );
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(list.parentElement).toBe(document.body);
+    expect(list).toHaveAttribute("role", "listbox");
+    expect(list).toHaveAttribute("id", "lb");
+    expect((list as HTMLElement).style.position).toBe("fixed");
+    const options = list.querySelectorAll("[data-pretable-option]");
+    expect(options).toHaveLength(4);
+    expect(options[0]).toHaveAttribute("id", "lb-0");
+    expect(options[0]).toHaveAttribute("role", "option");
+    expect(options[0]).toHaveAttribute("data-value", "contains");
+    // aria-selected is the COMMITTED value, not the highlight.
+    expect(options[1]).toHaveAttribute("aria-selected", "true");
+    expect(options[0]).toHaveAttribute("aria-selected", "false");
+    expect(options[2]).toHaveAttribute("aria-disabled", "true");
+  });
+
+  test("clicking an option selects it; a disabled option is inert", () => {
+    const onSelect = vi.fn();
+    render(
+      <Listbox
+        id="lb"
+        options={OPTIONS}
+        value={null}
+        activeIndex={-1}
+        anchor={RECT}
+        onSelect={onSelect}
+        onClose={() => {}}
+      />,
+    );
+    fireEvent.click(
+      document.querySelector('[data-pretable-option][data-value="endsWith"]')!,
+    );
+    expect(onSelect).toHaveBeenCalledWith("endsWith");
+    fireEvent.click(
+      document.querySelector('[data-pretable-option][data-value="custom"]')!,
+    );
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  test("renders nothing for an empty list, not a bare box", () => {
+    render(
+      <Listbox
+        id="lb"
+        options={[]}
+        value={null}
+        activeIndex={-1}
+        anchor={RECT}
+        onSelect={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("an outside pointerdown closes; one inside does not", () => {
+    const onClose = vi.fn();
+    render(
+      <Listbox
+        id="lb"
+        options={OPTIONS}
+        value={null}
+        activeIndex={0}
+        anchor={RECT}
+        onSelect={() => {}}
+        onClose={onClose}
+      />,
+    );
+    fireEvent.pointerDown(document.querySelector("[data-pretable-option]")!);
+    expect(onClose).not.toHaveBeenCalled();
+    fireEvent.pointerDown(document.body);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  test("the active option is scrolled into view when the index changes", () => {
+    const scrolled: string[] = [];
+    Element.prototype.scrollIntoView = function () {
+      scrolled.push((this as HTMLElement).id);
+    };
+    function Host() {
+      const [i, setI] = useState(0);
+      return (
+        <>
+          <button onClick={() => setI(3)}>go</button>
+          <Listbox
+            id="lb"
+            options={OPTIONS}
+            value={null}
+            activeIndex={i}
+            anchor={RECT}
+            onSelect={() => {}}
+            onClose={() => {}}
+          />
+        </>
+      );
+    }
+    const view = render(<Host />);
+    fireEvent.click(view.getByText("go"));
+    expect(scrolled.at(-1)).toBe("lb-3");
+  });
+});
+
+describe("useListboxKeys", () => {
+  const key = (k: string) =>
+    ({
+      key: k,
+      preventDefault: vi.fn(),
+      stopPropagation: vi.fn(),
+    }) as unknown as React.KeyboardEvent;
+
+  function setup(open = true) {
+    const onOpen = vi.fn();
+    const onCommit = vi.fn();
+    const onClose = vi.fn();
+    const hook = renderHook(() =>
+      useListboxKeys({
+        options: OPTIONS,
+        open,
+        initialIndex: 0,
+        onOpen,
+        onCommit,
+        onClose,
+      }),
+    );
+    return { hook, onOpen, onCommit, onClose };
+  }
+
+  test("ArrowDown/ArrowUp move with wrap and skip a disabled option", () => {
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(1);
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(3); // skipped "custom"
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(0); // wrapped
+    act(() => hook.result.current.onKeyDown(key("ArrowUp")));
+    expect(hook.result.current.activeIndex).toBe(3);
+  });
+
+  test("Home and End jump to the first and last enabled option", () => {
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("End")));
+    expect(hook.result.current.activeIndex).toBe(3);
+    act(() => hook.result.current.onKeyDown(key("Home")));
+    expect(hook.result.current.activeIndex).toBe(0);
+  });
+
+  test("typeahead matches a label prefix and resets after 500ms", () => {
+    vi.useFakeTimers();
+    const { hook } = setup();
+    act(() => hook.result.current.onKeyDown(key("e")));
+    expect(hook.result.current.activeIndex).toBe(1); // "equals"
+    act(() => hook.result.current.onKeyDown(key("n")));
+    expect(hook.result.current.activeIndex).toBe(3); // "en…" → "ends with"
+    act(() => vi.advanceTimersByTime(600));
+    act(() => hook.result.current.onKeyDown(key("c")));
+    expect(hook.result.current.activeIndex).toBe(0); // buffer reset: "c" → "contains" (Custom is disabled)
+  });
+
+  test("Enter and Space commit the active option; Escape and Tab close", () => {
+    const { hook, onCommit, onClose } = setup();
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    const enter = key("Enter");
+    act(() => hook.result.current.onKeyDown(enter));
+    expect(onCommit).toHaveBeenCalledWith("equals");
+    expect(enter.preventDefault).toHaveBeenCalled();
+    act(() => hook.result.current.onKeyDown(key(" ")));
+    expect(onCommit).toHaveBeenCalledTimes(2);
+    act(() => hook.result.current.onKeyDown(key("Escape")));
+    expect(onClose).toHaveBeenCalledWith({ restoreFocus: true });
+    const tab = key("Tab");
+    act(() => hook.result.current.onKeyDown(tab));
+    expect(onClose).toHaveBeenCalledWith({ restoreFocus: false });
+    expect(tab.preventDefault).not.toHaveBeenCalled(); // Tab still moves
+  });
+
+  test("on a closed trigger, the navigation keys open rather than move", () => {
+    const { hook, onOpen } = setup(false);
+    for (const k of ["ArrowDown", "ArrowUp", "Enter", " "]) {
+      act(() => hook.result.current.onKeyDown(key(k)));
+    }
+    expect(onOpen).toHaveBeenCalledTimes(4);
+    expect(hook.result.current.activeIndex).toBe(0);
+  });
+});
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
new file mode 100644
index 00000000..b299f33a
--- /dev/null
+++ b/packages/react/src/components/listbox.tsx
@@ -0,0 +1,265 @@
+/**
+ * The kit's one list: what a select-only combobox and the enum cell editor
+ * both pop open. Two pieces with two responsibilities, so each trigger keeps
+ * its own shape:
+ *
+ * - `Listbox` RENDERS the portalled `role="listbox"` from data the trigger
+ *   owns — the ARIA markup lives here and nowhere else.
+ * - `useListboxKeys` is the trigger's KEYBOARD: arrows/Home/End with wrap and
+ *   disabled-skip, typeahead, Enter/Space to commit, Escape/Tab to close, and
+ *   the navigation keys opening a closed trigger — the native <select>
+ *   contract a keyboard user expects.
+ *
+ * Portalled for the standing reason: the grid viewport's `contain: content`
+ * would clip a fixed popover. Placed by `menuPopoverStyle`, so a list clamps
+ * against the viewport exactly as the menus do.
+ */
+import {
+  createElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { menuPopoverStyle } from "../overlay/popover-position";
+import { OverlayPortal } from "../overlay/OverlayPortal";
+
+/** One entry in a list. `disabled` is skipped by the keyboard and inert to click. */
+export interface ListboxOption {
+  readonly value: string;
+  readonly label: ReactNode;
+  readonly disabled?: boolean;
+}
+
+/** How long two keystrokes stay one typeahead query. The native control's feel. */
+const TYPEAHEAD_RESET_MS = 500;
+
+/** Text for typeahead: a string label as is, a node by its rendered text. */
+function labelText(label: ReactNode): string {
+  if (typeof label === "string") return label;
+  if (typeof label === "number") return String(label);
+  return "";
+}
+
+export interface ListboxProps {
+  /** The trigger's `aria-controls` target; option ids are `${id}-${index}`. */
+  id: string;
+  options: readonly ListboxOption[];
+  /** The committed value — `aria-selected` — or null. */
+  value: string | null;
+  /** The roving highlight; -1 for none. Owned by the trigger via the hook. */
+  activeIndex: number;
+  /** The trigger's rect; the list is placed against it. */
+  anchor: DOMRect;
+  "aria-label"?: string;
+  onSelect: (value: string) => void;
+  /** Outside pointerdown. No focus return: the press chose a new target. */
+  onClose: () => void;
+  /** Extra attributes for the `<ul>` — a site's own `data-pretable-*`. */
+  listProps?: Record<`data-${string}`, string>;
+}
+
+export function Listbox({
+  id,
+  options,
+  value,
+  activeIndex,
+  anchor,
+  "aria-label": ariaLabel,
+  onSelect,
+  onClose,
+  listProps,
+}: ListboxProps): ReactElement | null {
+  const rootRef = useRef<HTMLUListElement>(null);
+
+  useEffect(() => {
+    const onPointerDown = (e: PointerEvent) => {
+      const root = rootRef.current;
+      if (root && e.target instanceof Node && !root.contains(e.target))
+        onClose();
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [onClose]);
+
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    rootRef.current
+      ?.querySelector<HTMLElement>(`[id="${id}-${activeIndex}"]`)
+      ?.scrollIntoView?.({ block: "nearest" });
+  }, [id, activeIndex]);
+
+  // An empty list is not a list: no bare box (the enum editor's rule).
+  if (options.length === 0) return null;
+
+  return (
+    <OverlayPortal>
+      <ul
+        {...listProps}
+        ref={rootRef}
+        id={id}
+        role="listbox"
+        aria-label={ariaLabel}
+        data-pretable-listbox=""
+        style={menuPopoverStyle(anchor)}
+        // Keep focus on the trigger: a blur before the click lands would
+        // close (or, in the editor, commit) under the pointer.
+        onMouseDown={(e) => e.preventDefault()}
+      >
+        {options.map((option, i) => (
+          <li
+            key={option.value}
+            id={`${id}-${i}`}
+            role="option"
+            aria-selected={option.value === value}
+            aria-disabled={option.disabled ? true : undefined}
+            data-pretable-option=""
+            data-value={option.value}
+            data-active={i === activeIndex ? "" : undefined}
+            onClick={() => {
+              if (!option.disabled) onSelect(option.value);
+            }}
+          >
+            {option.label}
+          </li>
+        ))}
+      </ul>
+    </OverlayPortal>
+  );
+}
+
+export interface UseListboxKeysInput {
+  options: readonly ListboxOption[];
+  /** Whether the list is showing. Closed, the navigation keys OPEN. */
+  open: boolean;
+  /** Where the highlight starts when the list opens (the current value). */
+  initialIndex: number;
+  onOpen: () => void;
+  onCommit: (value: string) => void;
+  onClose: (why: { restoreFocus: boolean }) => void;
+}
+
+export interface UseListboxKeysResult {
+  activeIndex: number;
+  setActiveIndex: (index: number) => void;
+  onKeyDown: (event: KeyboardEvent) => void;
+}
+
+/** The next enabled index from `from` in `dir`, wrapping; `from` if none. */
+function step(
+  options: readonly ListboxOption[],
+  from: number,
+  dir: 1 | -1,
+): number {
+  const n = options.length;
+  for (let k = 1; k <= n; k++) {
+    const i = (from + dir * k + n) % n;
+    if (!options[i]?.disabled) return i;
+  }
+  return from;
+}
+
+function edge(options: readonly ListboxOption[], dir: 1 | -1): number {
+  const n = options.length;
+  for (let k = 0; k < n; k++) {
+    const i = dir === 1 ? k : n - 1 - k;
+    if (!options[i]?.disabled) return i;
+  }
+  return -1;
+}
+
+export function useListboxKeys({
+  options,
+  open,
+  initialIndex,
+  onOpen,
+  onCommit,
+  onClose,
+}: UseListboxKeysInput): UseListboxKeysResult {
+  const [activeIndex, setActiveIndex] = useState(initialIndex);
+  const buffer = useRef("");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Re-seed the highlight from the value each time the list opens.
+  useEffect(() => {
+    if (open) setActiveIndex(initialIndex);
+  }, [open, initialIndex]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      const { key } = e;
+      if (!open) {
+        if (
+          key === "ArrowDown" ||
+          key === "ArrowUp" ||
+          key === "Enter" ||
+          key === " "
+        ) {
+          e.preventDefault();
+          onOpen();
+        }
+        return;
+      }
+      if (key === "ArrowDown" || key === "ArrowUp") {
+        e.preventDefault();
+        e.stopPropagation();
+        setActiveIndex((i) =>
+          step(options, i < 0 ? -1 : i, key === "ArrowDown" ? 1 : -1),
+        );
+        return;
+      }
+      if (key === "Home" || key === "End") {
+        e.preventDefault();
+        setActiveIndex(edge(options, key === "Home" ? 1 : -1));
+        return;
+      }
+      if (key === "Enter" || key === " ") {
+        e.preventDefault();
+        e.stopPropagation();
+        const option = options[activeIndex];
+        if (option && !option.disabled) onCommit(option.value);
+        return;
+      }
+      if (key === "Escape" || key === "Esc") {
+        e.preventDefault();
+        e.stopPropagation();
+        onClose({ restoreFocus: true });
+        return;
+      }
+      if (key === "Tab") {
+        onClose({ restoreFocus: false });
+        return;
+      }
+      // Typeahead: one printable character at a time, accumulated for
+      // TYPEAHEAD_RESET_MS, matched against the labels' prefixes from the top.
+      if (key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        buffer.current += key.toLowerCase();
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+          buffer.current = "";
+        }, TYPEAHEAD_RESET_MS);
+        const query = buffer.current;
+        const hit = options.findIndex(
+          (o) =>
+            !o.disabled && labelText(o.label).toLowerCase().startsWith(query),
+        );
+        if (hit >= 0) setActiveIndex(hit);
+      }
+    },
+    [open, options, activeIndex, onOpen, onCommit, onClose],
+  );
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  return { activeIndex, setActiveIndex, onKeyDown };
+}

From 4cc62fc61d8e3f59c310be5fa3124b6051df5f7f Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 20:52:22 -0700
Subject: [PATCH 04/27] fix(react): re-seed the listbox highlight during
 render, not in an effect

The set-state-in-effect rule was right: an effect commits a frame of stale
highlight. Adjust during render instead, and pin the re-seed with a test.
Mutation-checked: deleting the re-seed fails it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-listbox.test.tsx | 20 +++++++++++++++++++
 packages/react/src/components/listbox.tsx     | 16 ++++++++++-----
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/__tests__/components-listbox.test.tsx b/packages/react/src/__tests__/components-listbox.test.tsx
index c8dfe014..f10f812d 100644
--- a/packages/react/src/__tests__/components-listbox.test.tsx
+++ b/packages/react/src/__tests__/components-listbox.test.tsx
@@ -235,4 +235,24 @@ describe("useListboxKeys", () => {
     expect(onOpen).toHaveBeenCalledTimes(4);
     expect(hook.result.current.activeIndex).toBe(0);
   });
+
+  test("re-opening re-seeds the highlight from the current value", () => {
+    const hook = renderHook(
+      ({ open }) =>
+        useListboxKeys({
+          options: OPTIONS,
+          open,
+          initialIndex: 1,
+          onOpen: () => {},
+          onCommit: () => {},
+          onClose: () => {},
+        }),
+      { initialProps: { open: true } },
+    );
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(3);
+    hook.rerender({ open: false });
+    hook.rerender({ open: true });
+    expect(hook.result.current.activeIndex).toBe(1);
+  });
 });
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index b299f33a..f96e282d 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -181,13 +181,19 @@ export function useListboxKeys({
   onClose,
 }: UseListboxKeysInput): UseListboxKeysResult {
   const [activeIndex, setActiveIndex] = useState(initialIndex);
-  const buffer = useRef("");
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Re-seed the highlight from the value each time the list opens.
-  useEffect(() => {
+  // Re-seed the highlight from the value each time the list opens —
+  // adjusting state during render, the React-sanctioned form; an effect
+  // would commit one frame of stale highlight and trips the
+  // set-state-in-effect rule.
+  const [prevOpen, setPrevOpen] = useState(open);
+  if (open !== prevOpen) {
+    setPrevOpen(open);
     if (open) setActiveIndex(initialIndex);
-  }, [open, initialIndex]);
+  }
+
+  const buffer = useRef("");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const onKeyDown = useCallback(
     (e: KeyboardEvent) => {

From 93c8371f93c6f8f7e40506ef3de609517c671521 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:04:35 -0700
Subject: [PATCH 05/27] =?UTF-8?q?fix(react):=20listbox=20review=20round=20?=
 =?UTF-8?q?=E2=80=94=20ArrowUp=20from=20nothing,=20empty-list=20close,=20i?=
 =?UTF-8?q?ds?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ArrowUp from no highlight lands on the last enabled option, as the native
control does; an empty list still closes on an outside press; option ids
come from one helper; the reveal effect watches the options too. Escape's
stopPropagation and the toggling-anchor contract are now stated, not
implied. An all-disabled list is pinned: no highlight, nothing commits.
One hook test now drives a real DOM keydown instead of a hand-rolled
event, and the scrollIntoView patch is restored.

Placement assertion pins menuPopoverStyle (mutation-checked by swapping in
popoverStyle); ArrowUp fix mutation-checked by reverting the start
normalisation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-listbox.test.tsx | 98 +++++++++++++++++--
 packages/react/src/components/listbox.tsx     | 60 ++++++++++--
 2 files changed, 141 insertions(+), 17 deletions(-)

diff --git a/packages/react/src/__tests__/components-listbox.test.tsx b/packages/react/src/__tests__/components-listbox.test.tsx
index f10f812d..e3a98841 100644
--- a/packages/react/src/__tests__/components-listbox.test.tsx
+++ b/packages/react/src/__tests__/components-listbox.test.tsx
@@ -11,13 +11,18 @@ import { afterEach, describe, expect, test, vi } from "vitest";
 
 import {
   Listbox,
+  listboxOptionId,
   useListboxKeys,
   type ListboxOption,
 } from "../components/listbox";
 
+/** Restored in `afterEach`: jsdom ships no scrollIntoView, tests patch one in. */
+const REAL_SCROLL_INTO_VIEW = Element.prototype.scrollIntoView;
+
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
+  Element.prototype.scrollIntoView = REAL_SCROLL_INTO_VIEW;
 });
 
 const OPTIONS: readonly ListboxOption[] = [
@@ -56,10 +61,21 @@ describe("Listbox", () => {
     expect(list.parentElement).toBe(document.body);
     expect(list).toHaveAttribute("role", "listbox");
     expect(list).toHaveAttribute("id", "lb");
-    expect((list as HTMLElement).style.position).toBe("fixed");
+    // The MENU placement, not the dialog's: `position: fixed` alone is true
+    // of `popoverStyle` too, so pin what only `menuPopoverStyle` produces —
+    // content width between a 160px floor and the 240px dialog cap — plus the
+    // `top` derived from the anchor's bottom edge (30 + the 4px gap).
+    const style = (list as HTMLElement).style;
+    expect(style.position).toBe("fixed");
+    expect(style.width).toBe("max-content");
+    expect(style.minWidth).toBe("160px");
+    expect(style.maxWidth).toBe("240px");
+    expect(style.top).toBe("34px");
+    expect(style.left).toBe("20px");
     const options = list.querySelectorAll("[data-pretable-option]");
     expect(options).toHaveLength(4);
-    expect(options[0]).toHaveAttribute("id", "lb-0");
+    expect(options[0]).toHaveAttribute("id", "lb-0"); // the format itself
+    expect(options[3]).toHaveAttribute("id", listboxOptionId("lb", 3));
     expect(options[0]).toHaveAttribute("role", "option");
     expect(options[0]).toHaveAttribute("data-value", "contains");
     // aria-selected is the COMMITTED value, not the highlight.
@@ -91,7 +107,8 @@ describe("Listbox", () => {
     expect(onSelect).toHaveBeenCalledTimes(1);
   });
 
-  test("renders nothing for an empty list, not a bare box", () => {
+  test("renders nothing for an empty list, and an outside press still closes it", () => {
+    const onClose = vi.fn();
     render(
       <Listbox
         id="lb"
@@ -100,10 +117,13 @@ describe("Listbox", () => {
         activeIndex={-1}
         anchor={RECT}
         onSelect={() => {}}
-        onClose={() => {}}
+        onClose={onClose}
       />,
     );
     expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+    // Nothing rendered means no root element; the press is still outside.
+    fireEvent.pointerDown(document.body);
+    expect(onClose).toHaveBeenCalledTimes(1);
   });
 
   test("an outside pointerdown closes; one inside does not", () => {
@@ -127,6 +147,7 @@ describe("Listbox", () => {
 
   test("the active option is scrolled into view when the index changes", () => {
     const scrolled: string[] = [];
+    // Restored by the suite-wide afterEach.
     Element.prototype.scrollIntoView = function () {
       scrolled.push((this as HTMLElement).id);
     };
@@ -161,15 +182,19 @@ describe("useListboxKeys", () => {
       stopPropagation: vi.fn(),
     }) as unknown as React.KeyboardEvent;
 
-  function setup(open = true) {
+  function setup(
+    open = true,
+    initialIndex = 0,
+    options: readonly ListboxOption[] = OPTIONS,
+  ) {
     const onOpen = vi.fn();
     const onCommit = vi.fn();
     const onClose = vi.fn();
     const hook = renderHook(() =>
       useListboxKeys({
-        options: OPTIONS,
+        options,
         open,
-        initialIndex: 0,
+        initialIndex,
         onOpen,
         onCommit,
         onClose,
@@ -190,6 +215,35 @@ describe("useListboxKeys", () => {
     expect(hook.result.current.activeIndex).toBe(3);
   });
 
+  test("from no highlight, ArrowUp lands on the last enabled option and ArrowDown on the first", () => {
+    const up = setup(true, -1);
+    act(() => up.hook.result.current.onKeyDown(key("ArrowUp")));
+    expect(up.hook.result.current.activeIndex).toBe(3);
+    const down = setup(true, -1);
+    act(() => down.hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(down.hook.result.current.activeIndex).toBe(0);
+  });
+
+  test("with every option disabled there is no highlight and nothing commits", () => {
+    const allDisabled: readonly ListboxOption[] = OPTIONS.map((o) => ({
+      ...o,
+      disabled: true,
+    }));
+    const { hook, onCommit } = setup(true, -1, allDisabled);
+    act(() => hook.result.current.onKeyDown(key("Home")));
+    expect(hook.result.current.activeIndex).toBe(-1);
+    act(() => hook.result.current.onKeyDown(key("End")));
+    expect(hook.result.current.activeIndex).toBe(-1);
+    act(() => hook.result.current.onKeyDown(key("ArrowDown")));
+    expect(hook.result.current.activeIndex).toBe(-1);
+    act(() => hook.result.current.onKeyDown(key("ArrowUp")));
+    expect(hook.result.current.activeIndex).toBe(-1);
+    act(() => hook.result.current.onKeyDown(key("e")));
+    expect(hook.result.current.activeIndex).toBe(-1); // typeahead skips them too
+    act(() => hook.result.current.onKeyDown(key("Enter")));
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
   test("Home and End jump to the first and last enabled option", () => {
     const { hook } = setup();
     act(() => hook.result.current.onKeyDown(key("End")));
@@ -236,6 +290,36 @@ describe("useListboxKeys", () => {
     expect(hook.result.current.activeIndex).toBe(0);
   });
 
+  // The tests above hand the handler a hand-rolled event object. This one
+  // drives it from a real DOM keydown, so the `key.length === 1` typeahead
+  // test and the ctrl/meta/alt guards are exercised against a real event.
+  test("wired to a real element, arrows commit and a printable key runs typeahead", () => {
+    const onCommit = vi.fn();
+    let index = -1;
+    function Host() {
+      const keys = useListboxKeys({
+        options: OPTIONS,
+        open: true,
+        initialIndex: 0,
+        onOpen: () => {},
+        onCommit,
+        onClose: () => {},
+      });
+      index = keys.activeIndex;
+      return <button onKeyDown={keys.onKeyDown}>trigger</button>;
+    }
+    const view = render(<Host />);
+    const trigger = view.getByText("trigger");
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(index).toBe(1);
+    fireEvent.keyDown(trigger, { key: "Enter" });
+    expect(onCommit).toHaveBeenCalledWith("equals");
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(index).toBe(3);
+    fireEvent.keyDown(trigger, { key: "e" });
+    expect(index).toBe(1); // moved back to "equals": typeahead saw the key
+  });
+
   test("re-opening re-seeds the highlight from the current value", () => {
     const hook = renderHook(
       ({ open }) =>
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index f96e282d..219db8e3 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -13,6 +13,11 @@
  * Portalled for the standing reason: the grid viewport's `contain: content`
  * would clip a fixed popover. Placed by `menuPopoverStyle`, so a list clamps
  * against the viewport exactly as the menus do.
+ *
+ * A TOGGLING trigger — one whose click both opens and closes the list — must
+ * `stopPropagation()` on its own pointerdown, or the outside-press listener
+ * below closes what the click then reopens, and the trigger could never
+ * dismiss its own list. Same contract `menu-keyboard.ts` states for menus.
  */
 import {
   createElement,
@@ -28,6 +33,16 @@ import {
 import { menuPopoverStyle } from "../overlay/popover-position";
 import { OverlayPortal } from "../overlay/OverlayPortal";
 
+/**
+ * The id of one option, from the list's own id and the option's index. One
+ * helper because three places must agree on the format: the `<li id>`, the
+ * reveal effect's query, and a trigger's `aria-activedescendant`.
+ */
+// eslint-disable-next-line react-refresh/only-export-components -- the list, its id format and its trigger keyboard are one unit
+export function listboxOptionId(id: string, index: number): string {
+  return `${id}-${index}`;
+}
+
 /** One entry in a list. `disabled` is skipped by the keyboard and inert to click. */
 export interface ListboxOption {
   readonly value: string;
@@ -79,19 +94,25 @@ export function Listbox({
   useEffect(() => {
     const onPointerDown = (e: PointerEvent) => {
       const root = rootRef.current;
-      if (root && e.target instanceof Node && !root.contains(e.target))
-        onClose();
+      // A null root is OUTSIDE, not "no answer": the empty list renders
+      // nothing (below) while these hooks still run, and a guard that
+      // required a root would swallow the only press that can close it.
+      if (e.target instanceof Node && !root?.contains(e.target)) onClose();
     };
     document.addEventListener("pointerdown", onPointerDown);
     return () => document.removeEventListener("pointerdown", onPointerDown);
   }, [onClose]);
 
+  // `options` is a dependency, not noise: filtering the list changes WHICH
+  // option sits at `activeIndex` without changing the index itself.
   useEffect(() => {
     if (activeIndex < 0) return;
     rootRef.current
-      ?.querySelector<HTMLElement>(`[id="${id}-${activeIndex}"]`)
+      ?.querySelector<HTMLElement>(`[id="${listboxOptionId(id, activeIndex)}"]`)
+      // Optional call for jsdom, which implements no scrollIntoView at all;
+      // every real DOM has one.
       ?.scrollIntoView?.({ block: "nearest" });
-  }, [id, activeIndex]);
+  }, [id, activeIndex, options]);
 
   // An empty list is not a list: no bare box (the enum editor's rule).
   if (options.length === 0) return null;
@@ -113,7 +134,7 @@ export function Listbox({
         {options.map((option, i) => (
           <li
             key={option.value}
-            id={`${id}-${i}`}
+            id={listboxOptionId(id, i)}
             role="option"
             aria-selected={option.value === value}
             aria-disabled={option.disabled ? true : undefined}
@@ -149,20 +170,35 @@ export interface UseListboxKeysResult {
   onKeyDown: (event: KeyboardEvent) => void;
 }
 
-/** The next enabled index from `from` in `dir`, wrapping; `from` if none. */
+/**
+ * The next enabled index from `from` in `dir`, wrapping; `from` if there is
+ * none — so with EVERY option disabled the highlight stays where it is and
+ * Enter commits nothing.
+ *
+ * "No highlight" (`from < 0`) is normalised to the position just OUTSIDE the
+ * end the walk starts from, which is what makes the first ArrowUp land on the
+ * last enabled option rather than the second-to-last, as `<select>` does.
+ * Note the `from` (not `start`) return: the no-match answer is still -1.
+ */
 function step(
   options: readonly ListboxOption[],
   from: number,
   dir: 1 | -1,
 ): number {
   const n = options.length;
+  const start = from < 0 ? (dir === 1 ? -1 : n) : from;
   for (let k = 1; k <= n; k++) {
-    const i = (from + dir * k + n) % n;
+    const i = (((start + dir * k) % n) + n) % n;
     if (!options[i]?.disabled) return i;
   }
   return from;
 }
 
+/**
+ * The first enabled index from the `dir` end — Home (`1`) and End (`-1`).
+ * `-1` when every option is disabled: there is no option to highlight, and
+ * -1 is the list's own "no highlight".
+ */
 function edge(options: readonly ListboxOption[], dir: 1 | -1): number {
   const n = options.length;
   for (let k = 0; k < n; k++) {
@@ -172,6 +208,7 @@ function edge(options: readonly ListboxOption[], dir: 1 | -1): number {
   return -1;
 }
 
+// eslint-disable-next-line react-refresh/only-export-components -- the list and its trigger keyboard are one unit
 export function useListboxKeys({
   options,
   open,
@@ -213,9 +250,7 @@ export function useListboxKeys({
       if (key === "ArrowDown" || key === "ArrowUp") {
         e.preventDefault();
         e.stopPropagation();
-        setActiveIndex((i) =>
-          step(options, i < 0 ? -1 : i, key === "ArrowDown" ? 1 : -1),
-        );
+        setActiveIndex((i) => step(options, i, key === "ArrowDown" ? 1 : -1));
         return;
       }
       if (key === "Home" || key === "End") {
@@ -232,6 +267,11 @@ export function useListboxKeys({
       }
       if (key === "Escape" || key === "Esc") {
         e.preventDefault();
+        // `stopPropagation` too, unlike the menus: a select's Escape closes
+        // the LIST and leaves focus on the trigger, so the tool pane must not
+        // also read it and punt focus to the rail tab. That is the header's
+        // `ColumnMenu` exception in `menu-keyboard.ts`, for the same reason —
+        // one popover, one dismissal, the anchor keeps the focus.
         e.stopPropagation();
         onClose({ restoreFocus: true });
         return;

From 2f47cd4d9d5587288e2362c029a7fa4953a6f76c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:13:17 -0700
Subject: [PATCH 06/27] refactor(react,ui): the enum editor renders the kit
 Listbox

Its list and its arrow keys come from the primitive; its filtering input,
its direction-aware commit and its strict blur stay its own; its list keeps
the dialog width through Listbox's new `width` prop, and aria-selected
keeps following the highlight, the editable-combobox pattern. The enum
editor suite passes unchanged, which is the proof. The list rules move to
[data-pretable-listbox] / [data-pretable-option] in the kit section; the
editor passes its own listbox attribute through. Mutation-checked: an
ignored width prop fails its test; a deleted line-height fails the trio
guard.

References found outside EnumCellEditor.tsx and grid.css, all in
packages/ui/src/__tests__/css-cascade.test.ts:
- the "styles the enum combobox listbox" guard: renamed to the kit
  attributes ([data-pretable-listbox], [data-pretable-option]).
- the "portaled popovers declare the whole inherited trio" guard: its
  block regex is now [data-pretable-listbox], and the listbox joins the
  blocks that must declare line-height.
No e2e locator, docs page or other test named either attribute.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-listbox.test.tsx |  24 +++
 packages/react/src/components/listbox.tsx     |  14 +-
 packages/react/src/editors/EnumCellEditor.tsx | 169 ++++++++++++------
 packages/ui/grid.css                          |  80 +++++----
 packages/ui/src/__tests__/css-cascade.test.ts |  22 ++-
 5 files changed, 208 insertions(+), 101 deletions(-)

diff --git a/packages/react/src/__tests__/components-listbox.test.tsx b/packages/react/src/__tests__/components-listbox.test.tsx
index e3a98841..7b10fe35 100644
--- a/packages/react/src/__tests__/components-listbox.test.tsx
+++ b/packages/react/src/__tests__/components-listbox.test.tsx
@@ -84,6 +84,30 @@ describe("Listbox", () => {
     expect(options[2]).toHaveAttribute("aria-disabled", "true");
   });
 
+  test('width="dialog" draws the cell editors\' fixed column', () => {
+    // The cell editors' list is the dialog width — the same 240px column
+    // their panels use — so the extraction leaves the enum editor's look
+    // unchanged. The default-placement test above is the positive twin.
+    render(
+      <Listbox
+        id="lb"
+        width="dialog"
+        options={OPTIONS}
+        value={null}
+        activeIndex={0}
+        anchor={RECT}
+        onSelect={() => {}}
+        onClose={() => {}}
+      />,
+    );
+    const style = document.querySelector<HTMLElement>(
+      "[data-pretable-listbox]",
+    )!.style;
+    expect(style.width).toBe("240px");
+    expect(style.minWidth).toBe("");
+    expect(style.maxWidth).toBe("");
+  });
+
   test("clicking an option selects it; a disabled option is inert", () => {
     const onSelect = vi.fn();
     render(
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index 219db8e3..ca96e579 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -30,7 +30,7 @@ import {
   type ReactNode,
 } from "react";
 
-import { menuPopoverStyle } from "../overlay/popover-position";
+import { menuPopoverStyle, popoverStyle } from "../overlay/popover-position";
 import { OverlayPortal } from "../overlay/OverlayPortal";
 
 /**
@@ -70,6 +70,13 @@ export interface ListboxProps {
   activeIndex: number;
   /** The trigger's rect; the list is placed against it. */
   anchor: DOMRect;
+  /**
+   * How wide the list draws: the cell editors' list is the DIALOG width, the
+   * fixed 240px column their panels use, so the list lines up with the field
+   * it drops from; a select's list sizes to its CONTENT, as the menus do.
+   * See `popover-position.ts` for both.
+   */
+  width?: "content" | "dialog";
   "aria-label"?: string;
   onSelect: (value: string) => void;
   /** Outside pointerdown. No focus return: the press chose a new target. */
@@ -84,6 +91,7 @@ export function Listbox({
   value,
   activeIndex,
   anchor,
+  width = "content",
   "aria-label": ariaLabel,
   onSelect,
   onClose,
@@ -126,7 +134,9 @@ export function Listbox({
         role="listbox"
         aria-label={ariaLabel}
         data-pretable-listbox=""
-        style={menuPopoverStyle(anchor)}
+        style={
+          width === "dialog" ? popoverStyle(anchor) : menuPopoverStyle(anchor)
+        }
         // Keep focus on the trigger: a blur before the click lands would
         // close (or, in the editor, commit) under the pointer.
         onMouseDown={(e) => e.preventDefault()}
diff --git a/packages/react/src/editors/EnumCellEditor.tsx b/packages/react/src/editors/EnumCellEditor.tsx
index 94c031a5..de9fd353 100644
--- a/packages/react/src/editors/EnumCellEditor.tsx
+++ b/packages/react/src/editors/EnumCellEditor.tsx
@@ -2,16 +2,44 @@ import { createElement, useId, useLayoutEffect, useRef, useState } from "react";
 
 import type { ColumnOption, PretableFocusDirection } from "@pretable/core";
 
-import { OverlayPortal } from "../overlay/OverlayPortal";
-import { popoverStyle } from "../overlay/popover-position";
+import {
+  Listbox,
+  listboxOptionId,
+  useListboxKeys,
+} from "../components/listbox";
 import type { PretableEditorInput } from "../types";
 import { filterOptions, matchOption, optionLabel } from "./enum-options";
 import { useEditorField } from "./use-editor-field";
 
+/**
+ * The anchor before the layout effect has measured one. The list places
+ * against it for that one frame instead of rendering unplaced.
+ * SSR-safe: no `DOMRect` constructor exists on the server.
+ */
+const EMPTY_RECT: DOMRect =
+  typeof DOMRect === "undefined"
+    ? ({
+        top: 0,
+        left: 0,
+        bottom: 0,
+        right: 0,
+        width: 0,
+        height: 0,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      } as DOMRect)
+    : new DOMRect(0, 0, 0, 0);
+
 /**
  * Strict enum combobox: the engine draft holds the input text, and commit maps
  * it to an option value (`parseDraftForType`). Free text that matches nothing
  * is rejected — `renderEditor` is the escape hatch for creatable comboboxes.
+ *
+ * The list and the arrow keys are the kit's `Listbox`/`useListboxKeys`; what
+ * stays here is what makes this editor an editable combobox rather than a
+ * select — the filtering input, the direction-aware commit, and the strict
+ * blur that reverts unmatched text.
  */
 export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
   const { ref, pending, fieldProps } = useEditorField<HTMLInputElement>(input);
@@ -19,16 +47,28 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
   const listId = useId();
   const anchorRef = useRef<HTMLSpanElement>(null);
   const [rect, setRect] = useState<DOMRect | null>(null);
-  // Until the user types, show every option (the seeded text is the current
-  // value and would otherwise filter the list down to one). A seed that
-  // matches nothing is a type-to-replace character, so filter right away.
-  const [dirty, setDirty] = useState(
-    () => !matchOption(options, String(input.draft ?? "")),
-  );
-  const [highlight, setHighlight] = useState(() => {
+  // The mount state, computed once and together because the highlight's seed
+  // depends on whether the list starts filtered.
+  //
+  // `dirty`: until the user types, show every option (the seeded text is the
+  // current value and would otherwise filter the list down to one). A seed
+  // that matches nothing is a type-to-replace character, so filter right away.
+  //
+  // `index`: the current value's row — but clamped against the list actually
+  // rendered, because that row indexes the FULL option list and a
+  // type-to-replace seed renders already-filtered. The hook owns the arrow
+  // arithmetic now and steps from its own state, so the clamp has to be in
+  // the seed rather than applied at each keypress, or the first press from a
+  // filtered mount skips a row.
+  const [initial] = useState(() => {
+    const seeded = String(input.draft ?? "");
+    const match = matchOption(options, seeded);
+    const shown = match ? options : filterOptions(options, seeded);
     const i = options.findIndex((o) => o.value === String(input.value ?? ""));
-    return i >= 0 ? i : 0;
+    const raw = i >= 0 ? i : 0;
+    return { dirty: !match, index: raw < shown.length ? raw : 0 };
   });
+  const [dirty, setDirty] = useState(initial.dirty);
 
   useLayoutEffect(() => {
     const measure = () => {
@@ -59,11 +99,10 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
 
   const text = String(input.draft ?? "");
   const visible = dirty ? filterOptions(options, text) : options;
-  // `highlight` indexes the full option list on mount, and a type-to-replace
-  // seed renders already-filtered — so clamp at render rather than trusting
-  // an onChange to have reset it.
-  const index = highlight < visible.length ? highlight : 0;
-  const active = visible[index];
+  const listOptions = visible.map((o) => ({
+    value: o.value,
+    label: optionLabel(o),
+  }));
 
   const choose = (
     option: ColumnOption | undefined,
@@ -79,6 +118,28 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
     else input.commit();
   };
 
+  const keys = useListboxKeys({
+    options: listOptions,
+    // Always open: the field and its list mount and unmount together.
+    open: true,
+    // Read once, on mount: the hook re-seeds the highlight on an open EDGE,
+    // and this list is always open.
+    initialIndex: initial.index,
+    onOpen: () => {},
+    onCommit: (value) =>
+      choose(
+        visible.find((o) => o.value === value),
+        "down",
+      ),
+    onClose: () => {},
+  });
+
+  // Belt and braces: the seed is already clamped and typing resets the
+  // highlight to 0, but a render must never point at an option that is not
+  // there.
+  const index = keys.activeIndex < visible.length ? keys.activeIndex : 0;
+  const active = visible[index];
+
   return (
     <span ref={anchorRef} data-pretable-enum-editor="">
       <input
@@ -88,11 +149,13 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
         aria-expanded
         aria-controls={listId}
         aria-autocomplete="list"
-        aria-activedescendant={active ? `${listId}-${index}` : undefined}
+        aria-activedescendant={
+          active ? listboxOptionId(listId, index) : undefined
+        }
         value={text}
         onChange={(e) => {
           setDirty(true);
-          setHighlight(0);
+          keys.setActiveIndex(0);
           input.setDraft(e.target.value);
         }}
         {...fieldProps}
@@ -104,25 +167,26 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
           else input.cancel();
         }}
         onKeyDown={(e) => {
-          if (e.key === "ArrowDown" || e.key === "ArrowUp") {
-            e.preventDefault();
-            e.stopPropagation();
-            const n = visible.length;
-            if (n > 0) {
-              setHighlight((h) => {
-                // Step from the value the render clamped to, not the stale raw
-                // one, or the first press from a clamped mount skips a row.
-                const from = h < n ? h : 0;
-                return e.key === "ArrowDown"
-                  ? (from + 1) % n
-                  : (from - 1 + n) % n;
-              });
-            }
+          // Only the navigation keys go to the kit's keyboard. NOT the
+          // printable ones: this combobox filters by typing, and the hook's
+          // typeahead would preventDefault the very characters the field is
+          // there to receive.
+          if (
+            e.key === "ArrowDown" ||
+            e.key === "ArrowUp" ||
+            e.key === "Home" ||
+            e.key === "End"
+          ) {
+            // Wrap, skip-disabled and Home/End come from the hook now — the
+            // arithmetic this editor used to spell out itself.
+            keys.onKeyDown(e);
             return;
           }
           if ((e.key === "Enter" || e.key === "Tab") && active) {
             e.preventDefault();
             e.stopPropagation();
+            // The editor's own commit, not the hook's: it carries a DIRECTION
+            // (Enter moves down, Tab right) that a list has no notion of.
             choose(active, e.key === "Enter" ? "down" : "right");
             return;
           }
@@ -131,30 +195,25 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
           fieldProps.onKeyDown(e);
         }}
       />
-      <OverlayPortal>
-        <ul
-          id={listId}
-          role="listbox"
-          data-pretable-enum-listbox=""
-          style={rect ? popoverStyle(rect) : undefined}
-          // Keep focus in the input; a blur would commit or revert before the
-          // click lands (same hazard as the number steppers).
-          onMouseDown={(e) => e.preventDefault()}
-        >
-          {visible.map((option, i) => (
-            <li
-              key={option.value}
-              id={`${listId}-${i}`}
-              role="option"
-              aria-selected={i === index}
-              data-pretable-enum-option=""
-              onClick={() => choose(option)}
-            >
-              {optionLabel(option)}
-            </li>
-          ))}
-        </ul>
-      </OverlayPortal>
+      <Listbox
+        id={listId}
+        // The cell editors' fixed column, not a menu's content width.
+        width="dialog"
+        options={listOptions}
+        // For an editable combobox aria-selected follows the HIGHLIGHT (the
+        // APG editable-combobox pattern), so the editor feeds the highlight
+        // in as the value; there is no separately committed value while
+        // editing.
+        value={active ? active.value : null}
+        activeIndex={index}
+        anchor={rect ?? EMPTY_RECT}
+        onSelect={(value) => choose(visible.find((o) => o.value === value))}
+        onClose={() => {
+          // Outside press: the strict combobox reverts unmatched text, as its
+          // onBlur does — the blur fires on its own.
+        }}
+        listProps={{ "data-pretable-enum-listbox": "" }}
+      />
     </span>
   );
 }
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 69635877..bab86a6f 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -162,6 +162,49 @@
     padding: 0;
   }
 
+  /* ---- Kit components: the list ----------------------------------------
+     One popover list, two sites: the enum cell editor pops it open under its
+     field, and `PretableSelect` under its trigger. Each site keeps only what
+     is its own — the editor still carries `data-pretable-enum-listbox` on the
+     same element, so a selector keyed on that goes on working. */
+  :where([data-pretable-listbox]) {
+    margin: 0;
+    padding: 4px 0;
+    list-style: none;
+    max-height: 220px;
+    overflow-y: auto;
+    background: var(--pretable-bg-grid);
+    border: 1px solid var(--pretable-rule-strong);
+    border-radius: var(--pretable-radius);
+    box-shadow: var(--pretable-shadow-overlay);
+    /* Portaled into <body> — see the filter menu below. Line-height joins the
+       trio (#580): the list is a kit surface now, and a kit control dropped
+       into it would otherwise read the HOST page's leading. */
+    font-family: var(--pretable-font-sans);
+    font-size: var(--pretable-font-size-cell);
+    color: var(--pretable-text-cell);
+    line-height: 1.5;
+  }
+
+  /* Typed text matching nothing leaves an empty list; don't paint a bare box. */
+  :where([data-pretable-listbox]:empty) {
+    display: none;
+  }
+
+  :where([data-pretable-option]) {
+    padding: var(--pretable-cell-padding-y) var(--pretable-cell-padding-x);
+    cursor: pointer;
+  }
+
+  :where([data-pretable-option]:hover) {
+    background: var(--pretable-bg-hover);
+  }
+
+  :where([data-pretable-option][aria-selected="true"]) {
+    background: var(--pretable-bg-selected);
+    color: var(--pretable-text-selected);
+  }
+
   /* Multi-sort priority badge (rendered only when 2+ columns are sorted) */
   :where([data-pretable-sort-priority]) {
     margin-left: 2px;
@@ -1294,48 +1337,13 @@
     border-top: 1px solid var(--pretable-rule);
   }
 
-  /* Enum combobox listbox (cell editor) */
+  /* Enum combobox anchor (cell editor) */
   :where([data-pretable-enum-editor]) {
     display: block;
     width: 100%;
     height: 100%;
   }
 
-  :where([data-pretable-enum-listbox]) {
-    margin: 0;
-    padding: 4px 0;
-    list-style: none;
-    max-height: 220px;
-    overflow-y: auto;
-    background: var(--pretable-bg-grid);
-    border: 1px solid var(--pretable-rule-strong);
-    border-radius: var(--pretable-radius);
-    box-shadow: var(--pretable-shadow-overlay);
-    /* Portaled into <body> — see the filter menu above. */
-    font-family: var(--pretable-font-sans);
-    font-size: var(--pretable-font-size-cell);
-    color: var(--pretable-text-cell);
-  }
-
-  /* Typed text matching nothing leaves an empty list; don't paint a bare box. */
-  :where([data-pretable-enum-listbox]:empty) {
-    display: none;
-  }
-
-  :where([data-pretable-enum-option]) {
-    padding: var(--pretable-cell-padding-y) var(--pretable-cell-padding-x);
-    cursor: pointer;
-  }
-
-  :where([data-pretable-enum-option]:hover) {
-    background: var(--pretable-bg-hover);
-  }
-
-  :where([data-pretable-enum-option][aria-selected="true"]) {
-    background: var(--pretable-bg-selected);
-    color: var(--pretable-text-selected);
-  }
-
   /* Date calendar (cell editor) */
   :where([data-pretable-date-editor]) {
     display: block;
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index c26439d6..ba528bb7 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -766,14 +766,17 @@ describe("grid.css cascade contract", () => {
     expect(viewport).toMatch(/border-radius:\s*var\(--pretable-radius\)/);
   });
 
-  test("grid.css styles the enum combobox listbox", () => {
+  test("grid.css styles the kit listbox the enum combobox pops open", () => {
     const css = fs.readFileSync(GRID_CSS, "utf8");
-    expect(css).toMatch(/:where\(\[data-pretable-enum-listbox\]\)/);
+    // The list is the kit's, shared with PretableSelect; the editor's own
+    // `data-pretable-enum-listbox` still rides on the same element, but the
+    // paint is keyed on the kit attributes.
+    expect(css).toMatch(/:where\(\[data-pretable-listbox\]\)/);
     expect(css).toMatch(
-      /:where\(\[data-pretable-enum-option\]\[aria-selected="true"\]\)/,
+      /:where\(\[data-pretable-option\]\[aria-selected="true"\]\)/,
     );
     // An empty result set must not paint a bare popover box.
-    expect(css).toMatch(/:where\(\[data-pretable-enum-listbox\]:empty\)/);
+    expect(css).toMatch(/:where\(\[data-pretable-listbox\]:empty\)/);
   });
 
   test("grid.css styles the date calendar popover", () => {
@@ -862,7 +865,7 @@ describe("grid.css cascade contract", () => {
     // font size while every other popover sat at the cell size.
     for (const block of [
       /:where\(\[data-pretable-filter-menu\]\)\s*\{[^}]*\}/,
-      /:where\(\[data-pretable-enum-listbox\]\)\s*\{[^}]*\}/,
+      /:where\(\[data-pretable-listbox\]\)\s*\{[^}]*\}/,
       /:where\(\[data-pretable-date-popover\]\)\s*\{[^}]*\}/,
       /:where\(\[data-pretable-column-menu\]\)\s*\{[^}]*\}/,
     ]) {
@@ -880,12 +883,15 @@ describe("grid.css cascade contract", () => {
     // declare `font: inherit` themselves (the Clear button, every menu
     // item) — and a `link` button has no fixed block-size, so without an
     // explicit line-height here those controls fall through to the HOST
-    // page's. The listbox and the calendar don't have this exposure: they
-    // set their own row heights directly, so a fourth trio member would be
-    // redundant there.
+    // page's. The kit listbox joins them since it became a KIT surface
+    // (#580): PretableSelect and the enum editor both render it, and a kit
+    // control dropped into an option would read the host page's leading.
+    // The calendar doesn't have this exposure: it sets its own row heights
+    // directly, so a fourth trio member would be redundant there.
     for (const block of [
       /:where\(\[data-pretable-filter-menu\]\)\s*\{[^}]*\}/,
       /:where\(\[data-pretable-column-menu\]\)\s*\{[^}]*\}/,
+      /:where\(\[data-pretable-listbox\]\)\s*\{[^}]*\}/,
     ]) {
       const match = css.match(block);
       expect(match?.[0]).toMatch(/line-height:\s*[^;]+/);

From 987c72ff25b7887c33d64c7036ecd3e6e7db9766 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:24:15 -0700
Subject: [PATCH 07/27] =?UTF-8?q?refactor(react,ui):=20enum=20editor=20rev?=
 =?UTF-8?q?iew=20round=20=E2=80=94=20no=20dead=20attribute,=20arrows=20onl?=
 =?UTF-8?q?y?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The listbox's enum attribute vouched for a consumer that did not exist;
it and the listProps passthrough go. Home/End stay on the text caret, the
editable-combobox pattern — only the arrows reach the kit keyboard
(test-pinned; mutation-checked by re-forwarding Home). The seed and the
render share one "what is shown" rule; the index clamp guards both ends;
the unreachable :empty rule and its guard go together; the editor's
dialog width is pinned (mutation-checked by dropping the prop).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/enum-cell-editor.test.tsx   |  18 ++-
 packages/react/src/components/listbox.tsx     |   4 -
 packages/react/src/editors/EnumCellEditor.tsx | 105 ++++++++++++------
 packages/ui/grid.css                          |   9 +-
 packages/ui/src/__tests__/css-cascade.test.ts |   5 -
 5 files changed, 86 insertions(+), 55 deletions(-)

diff --git a/packages/react/src/__tests__/enum-cell-editor.test.tsx b/packages/react/src/__tests__/enum-cell-editor.test.tsx
index 9b2b708b..81bd0415 100644
--- a/packages/react/src/__tests__/enum-cell-editor.test.tsx
+++ b/packages/react/src/__tests__/enum-cell-editor.test.tsx
@@ -37,10 +37,13 @@ function makeInput(
 }
 
 describe("EnumCellEditor (via dispatcher)", () => {
-  it("renders a combobox with every option listed", () => {
+  it("renders a combobox with every option listed, in the dialog width", () => {
     render(<CellEditor input={makeInput()} />);
     expect(screen.getByRole("combobox")).toBeInTheDocument();
     expect(screen.getAllByRole("option")).toHaveLength(3);
+    // The editor asks the kit list for `width="dialog"`: the cell editors'
+    // fixed 240px column, so the list lines up with the field it drops from.
+    expect(screen.getByRole("listbox").style.width).toBe("240px");
   });
 
   it("typing filters the option list", () => {
@@ -66,6 +69,19 @@ describe("EnumCellEditor (via dispatcher)", () => {
     expect(commit).toHaveBeenCalledWith("down");
   });
 
+  it("Home stays on the text caret rather than jumping the highlight", () => {
+    // The APG editable-combobox pattern: this trigger is a text field, so
+    // Home/End move the caret. Only the arrows reach the kit's keyboard.
+    render(<CellEditor input={makeInput()} />);
+    const box = screen.getByRole("combobox");
+    fireEvent.keyDown(box, { key: "ArrowDown" });
+    fireEvent.keyDown(box, { key: "ArrowDown" });
+    const before = box.getAttribute("aria-activedescendant");
+    const notPrevented = fireEvent.keyDown(box, { key: "Home" });
+    expect(notPrevented).toBe(true);
+    expect(box.getAttribute("aria-activedescendant")).toBe(before);
+  });
+
   it("clicking an option commits it in place", () => {
     const setDraft = vi.fn();
     const commit = vi.fn();
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index ca96e579..5bd15f21 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -81,8 +81,6 @@ export interface ListboxProps {
   onSelect: (value: string) => void;
   /** Outside pointerdown. No focus return: the press chose a new target. */
   onClose: () => void;
-  /** Extra attributes for the `<ul>` — a site's own `data-pretable-*`. */
-  listProps?: Record<`data-${string}`, string>;
 }
 
 export function Listbox({
@@ -95,7 +93,6 @@ export function Listbox({
   "aria-label": ariaLabel,
   onSelect,
   onClose,
-  listProps,
 }: ListboxProps): ReactElement | null {
   const rootRef = useRef<HTMLUListElement>(null);
 
@@ -128,7 +125,6 @@ export function Listbox({
   return (
     <OverlayPortal>
       <ul
-        {...listProps}
         ref={rootRef}
         id={id}
         role="listbox"
diff --git a/packages/react/src/editors/EnumCellEditor.tsx b/packages/react/src/editors/EnumCellEditor.tsx
index de9fd353..f4539656 100644
--- a/packages/react/src/editors/EnumCellEditor.tsx
+++ b/packages/react/src/editors/EnumCellEditor.tsx
@@ -1,4 +1,11 @@
-import { createElement, useId, useLayoutEffect, useRef, useState } from "react";
+import {
+  createElement,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 
 import type { ColumnOption, PretableFocusDirection } from "@pretable/core";
 
@@ -31,6 +38,29 @@ const EMPTY_RECT: DOMRect =
       } as DOMRect)
     : new DOMRect(0, 0, 0, 0);
 
+/**
+ * What the list shows: every option until the user has typed, the filtered
+ * set after. One function because the mount seed and every render must agree
+ * on it — a seed clamped against a different list than the one drawn puts the
+ * highlight on the wrong row.
+ */
+function shownFor(
+  options: readonly ColumnOption[],
+  dirty: boolean,
+  text: string,
+): readonly ColumnOption[] {
+  return dirty ? filterOptions(options, text) : options;
+}
+
+/**
+ * The inert handlers. The list is always open — the field and its list mount
+ * and unmount together — so nothing here opens or closes it; the outside
+ * press that would close a select is answered by the input's own strict blur.
+ * Module-level so the hook's callbacks and the list's outside-press listener
+ * are not rebuilt on every keystroke.
+ */
+const NOOP = () => {};
+
 /**
  * Strict enum combobox: the engine draft holds the input text, and commit maps
  * it to an option value (`parseDraftForType`). Free text that matches nothing
@@ -43,27 +73,29 @@ const EMPTY_RECT: DOMRect =
  */
 export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
   const { ref, pending, fieldProps } = useEditorField<HTMLInputElement>(input);
-  const options = input.column.options ?? [];
+  const options = useMemo(
+    () => input.column.options ?? [],
+    [input.column.options],
+  );
   const listId = useId();
   const anchorRef = useRef<HTMLSpanElement>(null);
   const [rect, setRect] = useState<DOMRect | null>(null);
   // The mount state, computed once and together because the highlight's seed
   // depends on whether the list starts filtered.
   //
-  // `dirty`: until the user types, show every option (the seeded text is the
-  // current value and would otherwise filter the list down to one). A seed
-  // that matches nothing is a type-to-replace character, so filter right away.
+  // `dirty`: until the user types, show every option — the seeded text is the
+  // current value and would otherwise filter the list down to one. A seed
+  // matching nothing is a type-to-replace character, so filter right away.
   //
-  // `index`: the current value's row — but clamped against the list actually
-  // rendered, because that row indexes the FULL option list and a
-  // type-to-replace seed renders already-filtered. The hook owns the arrow
-  // arithmetic now and steps from its own state, so the clamp has to be in
-  // the seed rather than applied at each keypress, or the first press from a
-  // filtered mount skips a row.
+  // `index`: the current value's row, clamped against the list actually
+  // shown, because that row indexes the FULL option list. The hook owns the
+  // arrow arithmetic and steps from its own state, so the clamp lives in the
+  // seed instead of at each keypress, or the first press from a filtered
+  // mount skips a row.
   const [initial] = useState(() => {
     const seeded = String(input.draft ?? "");
     const match = matchOption(options, seeded);
-    const shown = match ? options : filterOptions(options, seeded);
+    const shown = shownFor(options, !match, seeded);
     const i = options.findIndex((o) => o.value === String(input.value ?? ""));
     const raw = i >= 0 ? i : 0;
     return { dirty: !match, index: raw < shown.length ? raw : 0 };
@@ -98,11 +130,14 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
   }, []);
 
   const text = String(input.draft ?? "");
-  const visible = dirty ? filterOptions(options, text) : options;
-  const listOptions = visible.map((o) => ({
-    value: o.value,
-    label: optionLabel(o),
-  }));
+  const visible = useMemo(
+    () => shownFor(options, dirty, text),
+    [options, dirty, text],
+  );
+  const listOptions = useMemo(
+    () => visible.map((o) => ({ value: o.value, label: optionLabel(o) })),
+    [visible],
+  );
 
   const choose = (
     option: ColumnOption | undefined,
@@ -125,19 +160,22 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
     // Read once, on mount: the hook re-seeds the highlight on an open EDGE,
     // and this list is always open.
     initialIndex: initial.index,
-    onOpen: () => {},
+    onOpen: NOOP,
     onCommit: (value) =>
       choose(
         visible.find((o) => o.value === value),
         "down",
       ),
-    onClose: () => {},
+    onClose: NOOP,
   });
 
   // Belt and braces: the seed is already clamped and typing resets the
   // highlight to 0, but a render must never point at an option that is not
   // there.
-  const index = keys.activeIndex < visible.length ? keys.activeIndex : 0;
+  const index = Math.min(
+    Math.max(keys.activeIndex, 0),
+    Math.max(visible.length - 1, 0),
+  );
   const active = visible[index];
 
   return (
@@ -167,18 +205,13 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
           else input.cancel();
         }}
         onKeyDown={(e) => {
-          // Only the navigation keys go to the kit's keyboard. NOT the
-          // printable ones: this combobox filters by typing, and the hook's
-          // typeahead would preventDefault the very characters the field is
-          // there to receive.
-          if (
-            e.key === "ArrowDown" ||
-            e.key === "ArrowUp" ||
-            e.key === "Home" ||
-            e.key === "End"
-          ) {
-            // Wrap, skip-disabled and Home/End come from the hook now — the
-            // arithmetic this editor used to spell out itself.
+          // Only the arrows go to the kit's keyboard; Home/End stay on the
+          // caret (the editable-combobox pattern), printable keys filter —
+          // the hook's typeahead would preventDefault the very characters the
+          // field is there to receive.
+          if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+            // Wrap and skip-disabled come from the hook now — the arithmetic
+            // this editor used to spell out itself.
             keys.onKeyDown(e);
             return;
           }
@@ -208,11 +241,9 @@ export function EnumCellEditor({ input }: { input: PretableEditorInput }) {
         activeIndex={index}
         anchor={rect ?? EMPTY_RECT}
         onSelect={(value) => choose(visible.find((o) => o.value === value))}
-        onClose={() => {
-          // Outside press: the strict combobox reverts unmatched text, as its
-          // onBlur does — the blur fires on its own.
-        }}
-        listProps={{ "data-pretable-enum-listbox": "" }}
+        // Outside press: the strict combobox reverts unmatched text, as its
+        // onBlur does — the blur fires on its own.
+        onClose={NOOP}
       />
     </span>
   );
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index bab86a6f..6e4e4c1e 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -164,9 +164,7 @@
 
   /* ---- Kit components: the list ----------------------------------------
      One popover list, two sites: the enum cell editor pops it open under its
-     field, and `PretableSelect` under its trigger. Each site keeps only what
-     is its own — the editor still carries `data-pretable-enum-listbox` on the
-     same element, so a selector keyed on that goes on working. */
+     field, and `PretableSelect` under its trigger. */
   :where([data-pretable-listbox]) {
     margin: 0;
     padding: 4px 0;
@@ -186,11 +184,6 @@
     line-height: 1.5;
   }
 
-  /* Typed text matching nothing leaves an empty list; don't paint a bare box. */
-  :where([data-pretable-listbox]:empty) {
-    display: none;
-  }
-
   :where([data-pretable-option]) {
     padding: var(--pretable-cell-padding-y) var(--pretable-cell-padding-x);
     cursor: pointer;
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index ba528bb7..825d202e 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -768,15 +768,10 @@ describe("grid.css cascade contract", () => {
 
   test("grid.css styles the kit listbox the enum combobox pops open", () => {
     const css = fs.readFileSync(GRID_CSS, "utf8");
-    // The list is the kit's, shared with PretableSelect; the editor's own
-    // `data-pretable-enum-listbox` still rides on the same element, but the
-    // paint is keyed on the kit attributes.
     expect(css).toMatch(/:where\(\[data-pretable-listbox\]\)/);
     expect(css).toMatch(
       /:where\(\[data-pretable-option\]\[aria-selected="true"\]\)/,
     );
-    // An empty result set must not paint a bare popover box.
-    expect(css).toMatch(/:where\(\[data-pretable-listbox\]:empty\)/);
   });
 
   test("grid.css styles the date calendar popover", () => {

From bcf7429d1bece5bcbeffeab5530ecb960169712e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:27:29 -0700
Subject: [PATCH 08/27] docs(react): the NOOP comment claims only what holds

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/editors/EnumCellEditor.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/editors/EnumCellEditor.tsx b/packages/react/src/editors/EnumCellEditor.tsx
index f4539656..8c433026 100644
--- a/packages/react/src/editors/EnumCellEditor.tsx
+++ b/packages/react/src/editors/EnumCellEditor.tsx
@@ -56,8 +56,8 @@ function shownFor(
  * The inert handlers. The list is always open — the field and its list mount
  * and unmount together — so nothing here opens or closes it; the outside
  * press that would close a select is answered by the input's own strict blur.
- * Module-level so the hook's callbacks and the list's outside-press listener
- * are not rebuilt on every keystroke.
+ * Module-level so the list's outside-press listener is not re-subscribed on
+ * every keystroke (it is keyed on `onClose`).
  */
 const NOOP = () => {};
 

From 4a28084ce4b87eca4acf9ef628de0894edaa0be5 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:32:11 -0700
Subject: [PATCH 09/27] feat(react): PretableSelect, a select-only combobox on
 the kit Listbox
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A button[role=combobox] trigger carrying data-pretable-select / -site /
-value and the kit list beneath it; opens on click and on the navigation
keys, commits on option click or Enter/Space, closes on Escape (focus
returned), Tab and outside press; honours the toggling-anchor contract
(mutation-checked: dropping the pointerdown stopPropagation fails the
close-not-reopen test). A value absent from the options renders as its
own label — the pruned-operator case (mutation-checked). jsdom helpers
replace the native-select drivers every later test used.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-select.test.tsx  | 167 +++++++++++++
 .../react/src/__tests__/select-helpers.ts     |  46 ++++
 packages/react/src/components/button.tsx      |  12 +-
 packages/react/src/components/listbox.tsx     |  24 ++
 packages/react/src/components/select.tsx      | 226 ++++++++++++++++++
 packages/react/src/editors/EnumCellEditor.tsx |  21 +-
 6 files changed, 474 insertions(+), 22 deletions(-)
 create mode 100644 packages/react/src/__tests__/components-select.test.tsx
 create mode 100644 packages/react/src/__tests__/select-helpers.ts
 create mode 100644 packages/react/src/components/select.tsx

diff --git a/packages/react/src/__tests__/components-select.test.tsx b/packages/react/src/__tests__/components-select.test.tsx
new file mode 100644
index 00000000..c60cc594
--- /dev/null
+++ b/packages/react/src/__tests__/components-select.test.tsx
@@ -0,0 +1,167 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup, fireEvent, render } from "@testing-library/react";
+import { createRef, type ComponentProps } from "react";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { PretableSelect } from "../components/select";
+import { resetDevWarnings } from "../dev-warn";
+import { chooseOption, readOptions, selectValue } from "./select-helpers";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+beforeEach(() => {
+  resetDevWarnings();
+});
+
+const OPTIONS = [
+  { value: "contains", label: "contains" },
+  { value: "equals", label: "equals" },
+  { value: "custom", label: "Custom", disabled: true },
+];
+
+function renderSelect(
+  props: Partial<ComponentProps<typeof PretableSelect>> = {},
+) {
+  const onChange = vi.fn();
+  const view = render(
+    <PretableSelect
+      aria-label="Operator"
+      options={OPTIONS}
+      value="contains"
+      onChange={onChange}
+      site="filter-operator"
+      data-pretable-filter-operator=""
+      {...props}
+    />,
+  );
+  const trigger = view.getByRole("combobox", {
+    name: props["aria-label"] ?? "Operator",
+  });
+  return { view, trigger, onChange };
+}
+
+describe("PretableSelect", () => {
+  test("is a select-only combobox carrying the kit attributes and the value", () => {
+    const { trigger } = renderSelect();
+    expect(trigger.tagName).toBe("BUTTON");
+    expect(trigger).toHaveAttribute("type", "button");
+    expect(trigger).toHaveAttribute("aria-haspopup", "listbox");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveAttribute("data-pretable-select", "");
+    expect(trigger).toHaveAttribute("data-pretable-site", "filter-operator");
+    expect(trigger).toHaveAttribute("data-pretable-filter-operator", "");
+    expect(selectValue(trigger)).toBe("contains");
+    expect(trigger).toHaveTextContent("contains");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("opens on click with the current value highlighted, and commits a clicked option", () => {
+    const { trigger, onChange } = renderSelect();
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(trigger).toHaveAttribute("aria-controls", list.id);
+    expect(trigger).toHaveAttribute("aria-activedescendant", `${list.id}-0`);
+    fireEvent.click(list.querySelector('[data-value="equals"]')!);
+    expect(onChange).toHaveBeenCalledWith("equals");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
+  test("a press on the open trigger closes it — it does not close and reopen", () => {
+    // The toggling-anchor contract: the document's outside-press listener
+    // must not see the trigger's own pointerdown.
+    const { trigger } = renderSelect();
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.pointerDown(trigger);
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  test("the keyboard opens, moves, commits and closes", () => {
+    const { trigger, onChange } = renderSelect();
+    trigger.focus();
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(trigger).toHaveAttribute(
+      "aria-activedescendant",
+      expect.stringMatching(/-1$/) as unknown as string,
+    );
+    fireEvent.keyDown(trigger, { key: "Enter" });
+    expect(onChange).toHaveBeenCalledWith("equals");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    fireEvent.keyDown(trigger, { key: " " });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.keyDown(trigger, { key: "Escape" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveFocus();
+  });
+
+  test("Tab closes without trapping, and an outside press closes", () => {
+    const { trigger } = renderSelect();
+    fireEvent.click(trigger);
+    fireEvent.keyDown(trigger, { key: "Tab" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    fireEvent.click(trigger);
+    fireEvent.pointerDown(document.body);
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  test("a value absent from the options renders as its own label, not a wrong option", () => {
+    // The pruned-operator case: the applied operator is not in the permitted
+    // list; a native <select> would silently display its first option.
+    const { trigger } = renderSelect({ value: "endsWith" });
+    expect(trigger).toHaveTextContent("endsWith");
+    expect(selectValue(trigger)).toBe("endsWith");
+  });
+
+  test("the helpers drive it: chooseOption commits, readOptions lists", () => {
+    const { trigger, onChange } = renderSelect();
+    expect(readOptions(trigger)).toEqual({
+      values: ["contains", "equals", "custom"],
+      labels: ["contains", "equals", "Custom"],
+    });
+    expect(trigger).toHaveAttribute("aria-expanded", "false"); // readOptions closed it again
+    chooseOption(trigger, "equals");
+    expect(onChange).toHaveBeenCalledWith("equals");
+  });
+
+  test("disabled takes the standard treatment and does not open", () => {
+    const { trigger } = renderSelect({ disabled: true });
+    expect(trigger).toBeDisabled();
+    fireEvent.click(trigger);
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
+  test("forwards its ref; className and style pass through", () => {
+    const ref = createRef<HTMLButtonElement>();
+    const { trigger } = renderSelect({
+      ref,
+      className: "mine",
+      style: { width: 120 },
+    } as never);
+    expect(ref.current).toBe(trigger);
+    expect(trigger).toHaveClass("mine");
+    expect(trigger.style.width).toBe("120px");
+  });
+
+  test("warns in development on an empty accessible name", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(
+      <PretableSelect
+        aria-label="  "
+        options={OPTIONS}
+        value="contains"
+        onChange={() => {}}
+      />,
+    );
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toMatch(/PretableSelect/);
+  });
+});
diff --git a/packages/react/src/__tests__/select-helpers.ts b/packages/react/src/__tests__/select-helpers.ts
new file mode 100644
index 00000000..9c6c7db0
--- /dev/null
+++ b/packages/react/src/__tests__/select-helpers.ts
@@ -0,0 +1,46 @@
+/**
+ * Drivers for `PretableSelect` in jsdom. Not a suite: vitest's default
+ * `include` collects `*.test.*` / `*.spec.*` only, and this file is neither,
+ * so it is imported, never run.
+ */
+import { fireEvent } from "@testing-library/react";
+
+/**
+ * Drive a PretableSelect the way a pointer does: open it, click the option.
+ * Replaces `fireEvent.change(select, { target: { value } })`, which a
+ * button[role=combobox] cannot honour. The list is portalled to body.
+ */
+export function chooseOption(trigger: HTMLElement, value: string): void {
+  fireEvent.click(trigger);
+  const option = document.querySelector<HTMLElement>(
+    `[data-pretable-listbox] [data-pretable-option][data-value="${value}"]`,
+  );
+  if (!option) {
+    throw new Error(`chooseOption: no option "${value}" in the open list`);
+  }
+  fireEvent.click(option);
+}
+
+/** The option values and labels a PretableSelect offers, read by opening it. */
+export function readOptions(trigger: HTMLElement): {
+  values: string[];
+  labels: string[];
+} {
+  fireEvent.click(trigger);
+  const items = Array.from(
+    document.querySelectorAll<HTMLElement>(
+      "[data-pretable-listbox] [data-pretable-option]",
+    ),
+  );
+  const result = {
+    values: items.map((el) => el.getAttribute("data-value") ?? ""),
+    labels: items.map((el) => el.textContent ?? ""),
+  };
+  fireEvent.keyDown(trigger, { key: "Escape" });
+  return result;
+}
+
+/** The committed value, from the attribute the component writes for exactly this. */
+export function selectValue(trigger: HTMLElement): string | null {
+  return trigger.getAttribute("data-pretable-value");
+}
diff --git a/packages/react/src/components/button.tsx b/packages/react/src/components/button.tsx
index 168fac55..d83f3da9 100644
--- a/packages/react/src/components/button.tsx
+++ b/packages/react/src/components/button.tsx
@@ -36,8 +36,9 @@ import { warnOnce } from "../dev-warn";
 export type PretableButtonVariant = "ghost" | "link";
 
 /**
- * Where in the grid a built-in button sits. Each name is the site's own
+ * Where in the grid a built-in control sits. Each name is the site's own
  * `data-pretable-*` attribute suffix, so there is one vocabulary, not two.
+ * Shared by every kit control that takes a `site`, buttons and pickers alike.
  *
  * @public
  */
@@ -53,7 +54,14 @@ export type PretableBuiltInButtonSite =
   | "tool-row-menu-button"
   | "chip-remove"
   | "filter-row-remove"
-  | "tool-group-remove";
+  | "tool-group-remove"
+  // The select sites. One vocabulary for every kit control's placement, not a
+  // per-component union: a site names where in the grid a control sits, which
+  // is not a fact about whether that control is a button or a picker.
+  | "filter-operator"
+  | "filter-row-column"
+  | "filter-row-operator"
+  | "aggregate";
 
 /**
  * A built-in site, or any string: autocomplete for the grid's own, no type
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index 5bd15f21..1117b700 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -43,6 +43,30 @@ export function listboxOptionId(id: string, index: number): string {
   return `${id}-${index}`;
 }
 
+/**
+ * The anchor a trigger places its list against before the layout effect has
+ * measured one. The list draws against it for that one frame instead of
+ * rendering unplaced. SSR-safe: no `DOMRect` constructor exists on the server.
+ *
+ * Here rather than at each trigger because every trigger of this list needs
+ * exactly the same placeholder.
+ */
+// eslint-disable-next-line react-refresh/only-export-components -- the list and its triggers' shared anchor placeholder are one unit
+export const EMPTY_RECT: DOMRect =
+  typeof DOMRect === "undefined"
+    ? ({
+        top: 0,
+        left: 0,
+        bottom: 0,
+        right: 0,
+        width: 0,
+        height: 0,
+        x: 0,
+        y: 0,
+        toJSON: () => ({}),
+      } as DOMRect)
+    : new DOMRect(0, 0, 0, 0);
+
 /** One entry in a list. `disabled` is skipped by the keyboard and inert to click. */
 export interface ListboxOption {
   readonly value: string;
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
new file mode 100644
index 00000000..29a23706
--- /dev/null
+++ b/packages/react/src/components/select.tsx
@@ -0,0 +1,226 @@
+/**
+ * A select-only combobox: the kit's answer to the native <select>, whose open
+ * list no theme can reach. The trigger is a button carrying
+ * `role="combobox"`; the list is the kit's `Listbox`, portalled and placed
+ * against the trigger. Both halves are styled by grid.css through
+ * `data-pretable-select` (trigger) and `data-pretable-listbox` /
+ * `data-pretable-option` (list), and a site's own attribute still arrives on
+ * the trigger through the spread.
+ *
+ * `data-pretable-value` is written for one reason: a button has no `.value`,
+ * and every test that used to read one reads this instead.
+ */
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type ReactElement,
+} from "react";
+
+import { warnOnce } from "../dev-warn";
+import { ChevronDownIcon } from "../icons";
+import type { PretableButtonSite } from "./button";
+import {
+  EMPTY_RECT,
+  Listbox,
+  listboxOptionId,
+  useListboxKeys,
+  type ListboxOption,
+} from "./listbox";
+
+/**
+ * One entry in a {@link PretableSelect}. A `disabled` option is shown, skipped
+ * by the keyboard, and inert to click — how the aggregate picker shows a
+ * consumer-written custom aggregate it must never write back.
+ *
+ * @public
+ */
+export type PretableSelectOption = ListboxOption;
+
+/**
+ * Props for {@link PretableSelect}.
+ *
+ * @public
+ */
+export interface PretableSelectProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "type" | "value" | "onChange" | "aria-label"
+> {
+  options: readonly PretableSelectOption[];
+  /** The committed value. Absent from `options`, it renders as its own label. */
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Required. A picker with no accessible name is the icon-button problem
+   * again. An empty string warns in development.
+   */
+  "aria-label": string;
+  /** Where in the grid this picker is; lands as `data-pretable-site`. */
+  site?: PretableButtonSite;
+}
+
+/**
+ * A select-only combobox in the grid's own chrome.
+ *
+ * ```tsx
+ * <PretableSelect
+ *   aria-label="Filter operator"
+ *   options={operators.map((op) => ({ value: op, label: OPERATOR_LABELS[op] }))}
+ *   value={draft.operator}
+ *   onChange={(op) => setOperator(op as FilterOperator)}
+ * />
+ * ```
+ *
+ * @public
+ */
+export const PretableSelect = forwardRef<
+  HTMLButtonElement,
+  PretableSelectProps
+>(function PretableSelect(
+  {
+    options,
+    value,
+    onChange,
+    "aria-label": ariaLabel,
+    site,
+    disabled,
+    onClick,
+    onKeyDown,
+    onPointerDown,
+    ...buttonProps
+  },
+  ref,
+): ReactElement {
+  if ((ariaLabel ?? "").trim() === "") {
+    warnOnce(
+      "select-empty-name",
+      "[pretable] <PretableSelect> rendered with an empty aria-label. A " +
+        "picker with no accessible name reads as an unnamed button to a " +
+        "screen reader. Name what it chooses, e.g. `Filter operator`.",
+    );
+  }
+
+  const listId = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  useImperativeHandle(ref, () => triggerRef.current as HTMLButtonElement);
+  const [open, setOpen] = useState(false);
+  const [rect, setRect] = useState<DOMRect>(EMPTY_RECT);
+
+  const selectedIndex = options.findIndex((o) => o.value === value);
+  const selected = options[selectedIndex];
+
+  const close = useCallback((why: { restoreFocus: boolean }) => {
+    setOpen(false);
+    if (why.restoreFocus) triggerRef.current?.focus({ preventScroll: true });
+  }, []);
+  // The list's own dismissal: the press chose a new target, so focus stays
+  // where the pointer put it. A `useCallback`, not an inline arrow — the
+  // outside-press listener is keyed on this identity and would otherwise
+  // re-subscribe on every render.
+  const closeFromOutside = useCallback(() => {
+    close({ restoreFocus: false });
+  }, [close]);
+  const commit = useCallback(
+    (next: string) => {
+      if (next !== value) onChange(next);
+      close({ restoreFocus: true });
+    },
+    [value, onChange, close],
+  );
+  const openList = useCallback(() => {
+    if (disabled) return;
+    if (triggerRef.current) setRect(triggerRef.current.getBoundingClientRect());
+    setOpen(true);
+  }, [disabled]);
+
+  const keys = useListboxKeys({
+    options,
+    open,
+    initialIndex: selectedIndex >= 0 ? selectedIndex : 0,
+    onOpen: openList,
+    onCommit: commit,
+    onClose: close,
+  });
+
+  // The list is `position: fixed` in a portal: re-anchor when anything
+  // scrolls or resizes while it is open (capture catches the grid's own
+  // scrollers, which do not bubble).
+  useLayoutEffect(() => {
+    if (!open) return;
+    const measure = () => {
+      if (triggerRef.current) {
+        setRect(triggerRef.current.getBoundingClientRect());
+      }
+    };
+    window.addEventListener("scroll", measure, true);
+    window.addEventListener("resize", measure);
+    return () => {
+      window.removeEventListener("scroll", measure, true);
+      window.removeEventListener("resize", measure);
+    };
+  }, [open]);
+
+  return (
+    <>
+      <button
+        {...buttonProps}
+        ref={triggerRef}
+        type="button"
+        role="combobox"
+        aria-label={ariaLabel}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        aria-controls={open ? listId : undefined}
+        aria-activedescendant={
+          open && keys.activeIndex >= 0
+            ? listboxOptionId(listId, keys.activeIndex)
+            : undefined
+        }
+        disabled={disabled}
+        data-pretable-select=""
+        data-pretable-site={site}
+        data-pretable-value={value}
+        onPointerDown={(e) => {
+          onPointerDown?.(e);
+          // The toggling-anchor contract (see listbox.tsx): the document's
+          // outside-press listener must not see this press, or it closes the
+          // list that the click then reopens.
+          e.stopPropagation();
+        }}
+        onClick={(e) => {
+          onClick?.(e);
+          if (e.defaultPrevented) return;
+          if (open) close({ restoreFocus: true });
+          else openList();
+        }}
+        onKeyDown={(e) => {
+          onKeyDown?.(e);
+          if (e.defaultPrevented) return;
+          keys.onKeyDown(e);
+        }}
+      >
+        <span data-pretable-select-label="">
+          {selected ? selected.label : value}
+        </span>
+        <ChevronDownIcon />
+      </button>
+      {open ? (
+        <Listbox
+          id={listId}
+          options={options}
+          value={value}
+          activeIndex={keys.activeIndex}
+          anchor={rect}
+          onSelect={commit}
+          onClose={closeFromOutside}
+        />
+      ) : null}
+    </>
+  );
+});
diff --git a/packages/react/src/editors/EnumCellEditor.tsx b/packages/react/src/editors/EnumCellEditor.tsx
index 8c433026..ca15b3bf 100644
--- a/packages/react/src/editors/EnumCellEditor.tsx
+++ b/packages/react/src/editors/EnumCellEditor.tsx
@@ -10,6 +10,7 @@ import {
 import type { ColumnOption, PretableFocusDirection } from "@pretable/core";
 
 import {
+  EMPTY_RECT,
   Listbox,
   listboxOptionId,
   useListboxKeys,
@@ -18,26 +19,6 @@ import type { PretableEditorInput } from "../types";
 import { filterOptions, matchOption, optionLabel } from "./enum-options";
 import { useEditorField } from "./use-editor-field";
 
-/**
- * The anchor before the layout effect has measured one. The list places
- * against it for that one frame instead of rendering unplaced.
- * SSR-safe: no `DOMRect` constructor exists on the server.
- */
-const EMPTY_RECT: DOMRect =
-  typeof DOMRect === "undefined"
-    ? ({
-        top: 0,
-        left: 0,
-        bottom: 0,
-        right: 0,
-        width: 0,
-        height: 0,
-        x: 0,
-        y: 0,
-        toJSON: () => ({}),
-      } as DOMRect)
-    : new DOMRect(0, 0, 0, 0);
-
 /**
  * What the list shows: every option until the user has typed, the filtered
  * set after. One function because the mount seed and every render must agree

From 9f272e05ff652b6b84f9ff05b8291fe68ac24a59 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:42:10 -0700
Subject: [PATCH 10/27] =?UTF-8?q?fix(react):=20select=20review=20round=20?=
 =?UTF-8?q?=E2=80=94=20list=20presses=20stay=20inside,=20disabled=20closes?=
 =?UTF-8?q?,=20named=20list?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A press inside the portalled list no longer reaches a host popover's
outside-press listener (the mirror of the trigger's own stopPropagation;
mutation-checked). Disabling an open select closes it — a disabled button
gets no keydown, so Escape would have died with it (mutation-checked).
The list takes the trigger's name. A merged callback ref replaces the
imperative handle; children are a compile error; an absent value seeds the
highlight on the first enabled option (mutation-checked); re-selecting the
current value fires no onChange (mutation-checked); the read-only helper
no longer moves focus.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-listbox.test.tsx | 28 ++++++++++
 .../src/__tests__/components-select.test.tsx  | 54 ++++++++++++++++---
 .../react/src/__tests__/select-helpers.ts     |  8 ++-
 packages/react/src/components/listbox.tsx     | 18 +++++++
 packages/react/src/components/select.tsx      | 34 ++++++++----
 5 files changed, 125 insertions(+), 17 deletions(-)

diff --git a/packages/react/src/__tests__/components-listbox.test.tsx b/packages/react/src/__tests__/components-listbox.test.tsx
index 7b10fe35..bde96b70 100644
--- a/packages/react/src/__tests__/components-listbox.test.tsx
+++ b/packages/react/src/__tests__/components-listbox.test.tsx
@@ -169,6 +169,34 @@ describe("Listbox", () => {
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 
+  test("a press inside the list does not reach a host popover's outside-press listener", () => {
+    // The list is portalled to body: unstopped, a press on an option would
+    // read as OUTSIDE to the dialog or menu the select sits in, dismissing
+    // the host under the pointer.
+    const hostListener = vi.fn();
+    document.addEventListener("pointerdown", hostListener);
+    try {
+      render(
+        <Listbox
+          id="lb"
+          options={OPTIONS}
+          value={null}
+          activeIndex={0}
+          anchor={RECT}
+          onSelect={() => {}}
+          onClose={() => {}}
+        />,
+      );
+      fireEvent.pointerDown(document.querySelector("[data-pretable-option]")!);
+      expect(hostListener).not.toHaveBeenCalled();
+      // The positive twin: a real outside press still reaches the host.
+      fireEvent.pointerDown(document.body);
+      expect(hostListener).toHaveBeenCalledTimes(1);
+    } finally {
+      document.removeEventListener("pointerdown", hostListener);
+    }
+  });
+
   test("the active option is scrolled into view when the index changes", () => {
     const scrolled: string[] = [];
     // Restored by the suite-wide afterEach.
diff --git a/packages/react/src/__tests__/components-select.test.tsx b/packages/react/src/__tests__/components-select.test.tsx
index c60cc594..23b094f1 100644
--- a/packages/react/src/__tests__/components-select.test.tsx
+++ b/packages/react/src/__tests__/components-select.test.tsx
@@ -55,14 +55,19 @@ describe("PretableSelect", () => {
     expect(trigger).toHaveAttribute("data-pretable-filter-operator", "");
     expect(selectValue(trigger)).toBe("contains");
     expect(trigger).toHaveTextContent("contains");
+    expect(trigger).not.toHaveAttribute("aria-controls");
+    expect(trigger).not.toHaveAttribute("aria-activedescendant");
     expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
   });
 
   test("opens on click with the current value highlighted, and commits a clicked option", () => {
-    const { trigger, onChange } = renderSelect();
+    const { view, trigger, onChange } = renderSelect();
     fireEvent.click(trigger);
     expect(trigger).toHaveAttribute("aria-expanded", "true");
     const list = document.querySelector("[data-pretable-listbox]")!;
+    // The list carries the trigger's name: a screen reader announcing the
+    // popup should say what it is choosing.
+    expect(view.getByRole("listbox", { name: "Operator" })).toBe(list);
     expect(trigger).toHaveAttribute("aria-controls", list.id);
     expect(trigger).toHaveAttribute("aria-activedescendant", `${list.id}-0`);
     fireEvent.click(list.querySelector('[data-value="equals"]')!);
@@ -88,10 +93,8 @@ describe("PretableSelect", () => {
     fireEvent.keyDown(trigger, { key: "ArrowDown" });
     expect(trigger).toHaveAttribute("aria-expanded", "true");
     fireEvent.keyDown(trigger, { key: "ArrowDown" });
-    expect(trigger).toHaveAttribute(
-      "aria-activedescendant",
-      expect.stringMatching(/-1$/) as unknown as string,
-    );
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(trigger).toHaveAttribute("aria-activedescendant", `${list.id}-1`);
     fireEvent.keyDown(trigger, { key: "Enter" });
     expect(onChange).toHaveBeenCalledWith("equals");
     expect(trigger).toHaveAttribute("aria-expanded", "false");
@@ -131,6 +134,45 @@ describe("PretableSelect", () => {
     expect(onChange).toHaveBeenCalledWith("equals");
   });
 
+  test("re-selecting the committed value commits without calling onChange", () => {
+    const { trigger, onChange } = renderSelect();
+    chooseOption(trigger, "contains");
+    expect(onChange).not.toHaveBeenCalled();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  test("an absent value seeds the highlight on the first ENABLED option", () => {
+    const { trigger } = renderSelect({
+      value: "endsWith",
+      options: [
+        { value: "contains", label: "contains", disabled: true },
+        { value: "equals", label: "equals" },
+      ],
+    });
+    fireEvent.click(trigger);
+    const list = document.querySelector("[data-pretable-listbox]")!;
+    expect(trigger).toHaveAttribute("aria-activedescendant", `${list.id}-1`);
+  });
+
+  test("disabling an open select closes it — Escape would die with the keydown", () => {
+    const { view, trigger, onChange } = renderSelect();
+    fireEvent.click(trigger);
+    expect(document.querySelector("[data-pretable-listbox]")).not.toBeNull();
+    view.rerender(
+      <PretableSelect
+        aria-label="Operator"
+        options={OPTIONS}
+        value="contains"
+        onChange={onChange}
+        site="filter-operator"
+        data-pretable-filter-operator=""
+        disabled
+      />,
+    );
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
   test("disabled takes the standard treatment and does not open", () => {
     const { trigger } = renderSelect({ disabled: true });
     expect(trigger).toBeDisabled();
@@ -145,7 +187,7 @@ describe("PretableSelect", () => {
       ref,
       className: "mine",
       style: { width: 120 },
-    } as never);
+    });
     expect(ref.current).toBe(trigger);
     expect(trigger).toHaveClass("mine");
     expect(trigger.style.width).toBe("120px");
diff --git a/packages/react/src/__tests__/select-helpers.ts b/packages/react/src/__tests__/select-helpers.ts
index 9c6c7db0..af875b8e 100644
--- a/packages/react/src/__tests__/select-helpers.ts
+++ b/packages/react/src/__tests__/select-helpers.ts
@@ -21,7 +21,11 @@ export function chooseOption(trigger: HTMLElement, value: string): void {
   fireEvent.click(option);
 }
 
-/** The option values and labels a PretableSelect offers, read by opening it. */
+/**
+ * The option values and labels a PretableSelect offers, read by opening it and
+ * closing it again with an outside press — not Escape, which would return
+ * focus to the trigger and make a read-only helper move the caller's focus.
+ */
 export function readOptions(trigger: HTMLElement): {
   values: string[];
   labels: string[];
@@ -36,7 +40,7 @@ export function readOptions(trigger: HTMLElement): {
     values: items.map((el) => el.getAttribute("data-value") ?? ""),
     labels: items.map((el) => el.textContent ?? ""),
   };
-  fireEvent.keyDown(trigger, { key: "Escape" });
+  fireEvent.pointerDown(document.body);
   return result;
 }
 
diff --git a/packages/react/src/components/listbox.tsx b/packages/react/src/components/listbox.tsx
index 1117b700..c7557ca4 100644
--- a/packages/react/src/components/listbox.tsx
+++ b/packages/react/src/components/listbox.tsx
@@ -160,6 +160,14 @@ export function Listbox({
         // Keep focus on the trigger: a blur before the click lands would
         // close (or, in the editor, commit) under the pointer.
         onMouseDown={(e) => e.preventDefault()}
+        // The list is portalled to body, so every host popover's own
+        // outside-press listener (the filter menu's, a dialog's) would read a
+        // press INSIDE this list as outside and dismiss itself under the
+        // pointer. Stopping it here is the mirror of the toggling trigger's
+        // own stopPropagation. This list's dismissal is unaffected: its
+        // listener tests containment, so the press it must not see is exactly
+        // the one it no longer receives, and an outside press still arrives.
+        onPointerDown={(e) => e.stopPropagation()}
       >
         {options.map((option, i) => (
           <li
@@ -238,6 +246,16 @@ function edge(options: readonly ListboxOption[], dir: 1 | -1): number {
   return -1;
 }
 
+/**
+ * The first option a trigger can highlight — where the roving highlight starts
+ * when the committed value is not in the list at all. `-1` when every option
+ * is disabled, the list's own "no highlight".
+ */
+// eslint-disable-next-line react-refresh/only-export-components -- the list and its triggers' shared seeding rule are one unit
+export function firstEnabledIndex(options: readonly ListboxOption[]): number {
+  return edge(options, 1);
+}
+
 // eslint-disable-next-line react-refresh/only-export-components -- the list and its trigger keyboard are one unit
 export function useListboxKeys({
   options,
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index 29a23706..4abb9d92 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -3,9 +3,9 @@
  * list no theme can reach. The trigger is a button carrying
  * `role="combobox"`; the list is the kit's `Listbox`, portalled and placed
  * against the trigger. Both halves are styled by grid.css through
- * `data-pretable-select` (trigger) and `data-pretable-listbox` /
- * `data-pretable-option` (list), and a site's own attribute still arrives on
- * the trigger through the spread.
+ * `data-pretable-select` (trigger), `data-pretable-select-label` (the label
+ * span) and `data-pretable-listbox` / `data-pretable-option` (list), and a
+ * site's own attribute still arrives on the trigger through the spread.
  *
  * `data-pretable-value` is written for one reason: a button has no `.value`,
  * and every test that used to read one reads this instead.
@@ -15,7 +15,6 @@ import {
   forwardRef,
   useCallback,
   useId,
-  useImperativeHandle,
   useLayoutEffect,
   useRef,
   useState,
@@ -28,6 +27,7 @@ import { ChevronDownIcon } from "../icons";
 import type { PretableButtonSite } from "./button";
 import {
   EMPTY_RECT,
+  firstEnabledIndex,
   Listbox,
   listboxOptionId,
   useListboxKeys,
@@ -50,7 +50,7 @@ export type PretableSelectOption = ListboxOption;
  */
 export interface PretableSelectProps extends Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
-  "type" | "value" | "onChange" | "aria-label"
+  "type" | "value" | "onChange" | "aria-label" | "children"
 > {
   options: readonly PretableSelectOption[];
   /** The committed value. Absent from `options`, it renders as its own label. */
@@ -108,10 +108,24 @@ export const PretableSelect = forwardRef<
 
   const listId = useId();
   const triggerRef = useRef<HTMLButtonElement>(null);
-  useImperativeHandle(ref, () => triggerRef.current as HTMLButtonElement);
+  // A merged callback ref: the component needs the node (to measure and to
+  // restore focus) and the consumer still gets whichever ref form it passed.
+  const setTriggerRef = useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref],
+  );
   const [open, setOpen] = useState(false);
   const [rect, setRect] = useState<DOMRect>(EMPTY_RECT);
 
+  // Disabled mid-open: nothing else can close the list, and a disabled button
+  // receives no keydown, so Escape goes with it. Adjusting state during
+  // render, the React-sanctioned form.
+  if (disabled && open) setOpen(false);
+
   const selectedIndex = options.findIndex((o) => o.value === value);
   const selected = options[selectedIndex];
 
@@ -142,7 +156,8 @@ export const PretableSelect = forwardRef<
   const keys = useListboxKeys({
     options,
     open,
-    initialIndex: selectedIndex >= 0 ? selectedIndex : 0,
+    initialIndex:
+      selectedIndex >= 0 ? selectedIndex : firstEnabledIndex(options),
     onOpen: openList,
     onCommit: commit,
     onClose: close,
@@ -170,7 +185,7 @@ export const PretableSelect = forwardRef<
     <>
       <button
         {...buttonProps}
-        ref={triggerRef}
+        ref={setTriggerRef}
         type="button"
         role="combobox"
         aria-label={ariaLabel}
@@ -210,9 +225,10 @@ export const PretableSelect = forwardRef<
         </span>
         <ChevronDownIcon />
       </button>
-      {open ? (
+      {open && !disabled ? (
         <Listbox
           id={listId}
+          aria-label={ariaLabel}
           options={options}
           value={value}
           activeIndex={keys.activeIndex}

From 66d629d0e4a8609d6e947e73a253a4fcd5375a24 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:48:17 -0700
Subject: [PATCH 11/27] test(react): pin the PretableSelect type contract

Name required, string value in and out, no type/children leak, the four
select sites in the built-in vocabulary (mutation-checked by removing one),
ref and native attributes through.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 type-tests/react/components-select.types.tsx | 103 +++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 type-tests/react/components-select.types.tsx

diff --git a/type-tests/react/components-select.types.tsx b/type-tests/react/components-select.types.tsx
new file mode 100644
index 00000000..6e1f5c37
--- /dev/null
+++ b/type-tests/react/components-select.types.tsx
@@ -0,0 +1,103 @@
+// TEMPORARY: imported from source because `@pretable/react` does not export
+// these yet. Task 9 of the SP2 plan switches this to the package.
+import {
+  PretableSelect,
+  type PretableSelectOption,
+  type PretableSelectProps,
+} from "../../packages/react/src/components/select";
+import type {
+  PretableBuiltInButtonSite,
+  PretableButtonSite,
+} from "../../packages/react/src/components/button";
+import type { Equal, Expect } from "../shared/assert";
+
+const options: readonly PretableSelectOption[] = [
+  { value: "a", label: "A" },
+  { value: "b", label: "B", disabled: true },
+];
+
+// The name is required.
+// @ts-expect-error — aria-label is required
+<PretableSelect options={options} value="a" onChange={() => {}} />;
+<PretableSelect
+  aria-label="Pick"
+  options={options}
+  value="a"
+  onChange={() => {}}
+/>;
+
+// The value is a string, and onChange hands one back.
+// prettier-ignore
+// @ts-expect-error — value is a string
+<PretableSelect aria-label="Pick" options={options} value={1} onChange={() => {}} />;
+<PretableSelect
+  aria-label="Pick"
+  options={options}
+  value="a"
+  onChange={(v) => {
+    const s: string = v;
+    void s;
+  }}
+/>;
+
+// No `type`, no children, no native onChange/value shapes leak through.
+// prettier-ignore
+// @ts-expect-error — the element is always type="button"
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}} type="submit" />;
+// prettier-ignore
+// @ts-expect-error — the trigger draws its own label; children are not a channel
+<PretableSelect aria-label="Pick" options={options} value="a" onChange={() => {}}>x</PretableSelect>;
+
+// The four select sites are in the kit's vocabulary, and it stays open.
+<PretableSelect
+  aria-label="Pick"
+  options={options}
+  value="a"
+  onChange={() => {}}
+  site="filter-operator"
+/>;
+<PretableSelect
+  aria-label="Pick"
+  options={options}
+  value="a"
+  onChange={() => {}}
+  site="my-app-picker"
+/>;
+// `Extract<Union, X>` over a union containing `(string & {})` is vacuous —
+// pin the built-in union directly, so removing a site from it fails this.
+export type SelectSitesAreBuiltIn = Expect<
+  Equal<
+    Extract<
+      PretableBuiltInButtonSite,
+      | "aggregate"
+      | "filter-row-column"
+      | "filter-row-operator"
+      | "filter-operator"
+    >,
+    | "aggregate"
+    | "filter-row-column"
+    | "filter-row-operator"
+    | "filter-operator"
+  >
+>;
+
+// Refs and native attributes flow through.
+const ref = { current: null as HTMLButtonElement | null };
+<PretableSelect
+  ref={ref}
+  aria-label="Pick"
+  options={options}
+  value="a"
+  onChange={() => {}}
+  disabled
+  className="x"
+/>;
+
+export type NameIsRequired = Expect<
+  Equal<PretableSelectProps["aria-label"], string>
+>;
+
+// `site` accepts the built-ins and any string.
+export type SiteIsOpen = Expect<
+  Equal<PretableSelectProps["site"], PretableButtonSite | undefined>
+>;

From f10cbe0783fdfd71d89b290cc5cd0bb7bdd2d7d5 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:51:47 -0700
Subject: [PATCH 12/27] feat(react): the Select slot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comparison, defaults, literal and deps all gain it — the four-part edit —
and the changed-slot test now covers it; mutation-checked by dropping the
dep.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-button.test.tsx  | 31 ++++++++++++++++++-
 packages/react/src/components/context.ts      | 24 ++++++++++++--
 2 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/__tests__/components-button.test.tsx b/packages/react/src/__tests__/components-button.test.tsx
index 5f21e247..a3cd99bd 100644
--- a/packages/react/src/__tests__/components-button.test.tsx
+++ b/packages/react/src/__tests__/components-button.test.tsx
@@ -14,6 +14,7 @@ import {
   usePretableComponents,
   useResolvedComponents,
 } from "../components/context";
+import { PretableSelect } from "../components/select";
 import { resetDevWarnings } from "../dev-warn";
 
 afterEach(() => {
@@ -232,7 +233,11 @@ describe("components context", () => {
       HTMLButtonElement,
       ComponentProps<typeof PretableIconButton>
     >((props, ref) => <button {...props} ref={ref} data-mine="" />);
-    const value = { Button: PretableButton, IconButton: MyIcon };
+    const value = {
+      Button: PretableButton,
+      IconButton: MyIcon,
+      Select: PretableSelect,
+    };
     const { result } = renderHook(() => usePretableComponents(), {
       wrapper: ({ children }) => (
         <PretableComponentsProvider value={value}>
@@ -242,4 +247,28 @@ describe("components context", () => {
     });
     expect(result.current.IconButton).toBe(MyIcon);
   });
+
+  test("the Select slot resolves like the other two, and its own change is its own", () => {
+    const MySelect = forwardRef<
+      HTMLButtonElement,
+      ComponentProps<typeof PretableSelect>
+    >((props, ref) => <button {...(props as object)} ref={ref} data-mine="" />);
+    const { result, rerender } = renderHook(
+      ({ components }) => useResolvedComponents(components),
+      { initialProps: { components: {} as { Select?: typeof MySelect } } },
+    );
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+    expect(result.current.Select).toBe(PretableSelect);
+    rerender({ components: { Select: MySelect } });
+    expect(result.current.Select).toBe(MySelect);
+    expect(result.current.Button).toBe(PretableButton);
+    const withSelect = result.current;
+    rerender({ components: { Select: MySelect } });
+    expect(result.current).toBe(withSelect);
+    // The four-part edit the SP1 review flagged: the slot must be in the
+    // comparison, the defaults, the literal AND the deps. A slot left out of
+    // the deps would make this rerender a stale hit.
+    rerender({ components: {} });
+    expect(result.current).toBe(DEFAULT_COMPONENTS);
+  });
 });
diff --git a/packages/react/src/components/context.ts b/packages/react/src/components/context.ts
index 909c53d1..07308bab 100644
--- a/packages/react/src/components/context.ts
+++ b/packages/react/src/components/context.ts
@@ -32,6 +32,7 @@ import {
   type PretableButtonProps,
   type PretableIconButtonProps,
 } from "./button";
+import { PretableSelect, type PretableSelectProps } from "./select";
 
 /**
  * The component a `components.Button` replacement must be: it receives
@@ -57,6 +58,17 @@ export type PretableIconButtonComponent = ComponentType<
   PretableIconButtonProps & RefAttributes<HTMLButtonElement>
 >;
 
+/**
+ * The component a `components.Select` replacement must be: it receives
+ * {@link PretableSelectProps} and forwards its `ref` to the trigger node —
+ * the filter dialog focuses its operator picker on open through that ref.
+ *
+ * @public
+ */
+export type PretableSelectComponent = ComponentType<
+  PretableSelectProps & RefAttributes<HTMLButtonElement>
+>;
+
 /**
  * The kit components a consumer can replace, one slot per type. Every slot is
  * optional; an absent one is the built-in.
@@ -68,18 +80,22 @@ export interface PretableComponents {
   readonly Button?: PretableButtonComponent;
   /** Every icon-only push-button the grid draws; receives {@link PretableIconButtonProps}. */
   readonly IconButton?: PretableIconButtonComponent;
+  /** Every select-only picker the grid draws; receives {@link PretableSelectProps}. */
+  readonly Select?: PretableSelectComponent;
 }
 
 /** The map after resolution: every slot filled. Internal. */
 export interface ResolvedPretableComponents {
   readonly Button: PretableButtonComponent;
   readonly IconButton: PretableIconButtonComponent;
+  readonly Select: PretableSelectComponent;
 }
 
 /** The built-ins, frozen: also the identity a no-op resolution returns. */
 export const DEFAULT_COMPONENTS: ResolvedPretableComponents = Object.freeze({
   Button: PretableButton,
   IconButton: PretableIconButton,
+  Select: PretableSelect,
 });
 
 const PretableComponentsContext =
@@ -105,12 +121,14 @@ export function useResolvedComponents(
 ): ResolvedPretableComponents {
   const Button = components?.Button ?? DEFAULT_COMPONENTS.Button;
   const IconButton = components?.IconButton ?? DEFAULT_COMPONENTS.IconButton;
+  const Select = components?.Select ?? DEFAULT_COMPONENTS.Select;
   return useMemo(
     () =>
       Button === DEFAULT_COMPONENTS.Button &&
-      IconButton === DEFAULT_COMPONENTS.IconButton
+      IconButton === DEFAULT_COMPONENTS.IconButton &&
+      Select === DEFAULT_COMPONENTS.Select
         ? DEFAULT_COMPONENTS
-        : Object.freeze({ Button, IconButton }),
-    [Button, IconButton],
+        : Object.freeze({ Button, IconButton, Select }),
+    [Button, IconButton, Select],
   );
 }

From f76bf9ef04f5868947beaf57ff27fc7f52936178 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 21:59:02 -0700
Subject: [PATCH 13/27] feat(ui): the kit select rules; the site guard learns
 the four pickers

Trigger box, label ellipsis, caret, active option, ring and disabled in
the state section, Highlight/HighlightText under forced colours. The
site guard is red by design until the pickers' rules collapse in the
migration. Kit guard mutation-checked by deleting cursor: pointer.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/ui/grid.css                          |  67 +++++++++-
 packages/ui/src/__tests__/css-cascade.test.ts | 126 +++++++++++++++++-
 2 files changed, 185 insertions(+), 8 deletions(-)

diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 6e4e4c1e..51dc54d3 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -162,6 +162,46 @@
     padding: 0;
   }
 
+  /* ---- Kit components: select ------------------------------------------
+     `PretableSelect`'s trigger. It is a FIELD, not a button: the rule
+     border, the grid surface, the cell ink, the label at the start and the
+     caret at the end. Each site keeps only its size and its flex
+     participation — the site rules further down win at equal specificity by
+     source order — and the list it opens is the kit list below.
+     `font: inherit` is safe here for the same reason it is on the buttons:
+     the trigger sits in a grid surface that declares its own font trio. */
+  :where([data-pretable-select]) {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 6px;
+    padding-inline: 6px;
+    border: 1px solid var(--pretable-rule);
+    border-radius: var(--pretable-radius-control);
+    background: var(--pretable-bg-grid);
+    color: var(--pretable-text-cell);
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+  /* The label takes the slack and ellipsizes; `min-inline-size: 0` is what
+     lets it, a flex item's automatic minimum being its content otherwise —
+     without it a long option widens the picker instead of truncating. */
+  :where([data-pretable-select-label]) {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  /* The caret never shrinks, and speaks in the dim ink like every other
+     affordance glyph in the grid. */
+  :where([data-pretable-select]) > :where([data-pretable-icon]) {
+    flex: none;
+    color: var(--pretable-text-dim);
+  }
+
   /* ---- Kit components: the list ----------------------------------------
      One popover list, two sites: the enum cell editor pops it open under its
      field, and `PretableSelect` under its trigger. */
@@ -193,6 +233,14 @@
     background: var(--pretable-bg-hover);
   }
 
+  /* The roving highlight: keyboard navigation's `data-active`, painted like
+     a hover. DECLARED BEFORE the selected rule on purpose — an option that
+     is both active and committed should read as SELECTED, and at equal
+     (0,0,0) specificity source order is what decides that. */
+  :where([data-pretable-option][data-active]) {
+    background: var(--pretable-bg-hover);
+  }
+
   :where([data-pretable-option][aria-selected="true"]) {
     background: var(--pretable-bg-selected);
     color: var(--pretable-text-selected);
@@ -2184,7 +2232,8 @@
      so they cannot be the site rule this ordering guards against. */
   :where(
     [data-pretable-button]:focus-visible,
-    [data-pretable-icon-button]:focus-visible
+    [data-pretable-icon-button]:focus-visible,
+    [data-pretable-select]:focus-visible
   ) {
     outline: 2px solid var(--pretable-focus-ring);
     outline-offset: -2px;
@@ -2192,7 +2241,8 @@
   /* The standard disabled treatment (#573): dim by token, drop the pointer. */
   :where(
     [data-pretable-button]:disabled,
-    [data-pretable-icon-button]:disabled
+    [data-pretable-icon-button]:disabled,
+    [data-pretable-select]:disabled
   ) {
     color: var(--pretable-text-dim);
     cursor: default;
@@ -2402,10 +2452,21 @@
     :where(
       [data-pretable-menu-item]:disabled,
       [data-pretable-button]:disabled,
-      [data-pretable-icon-button]:disabled
+      [data-pretable-icon-button]:disabled,
+      [data-pretable-select]:disabled
     ) {
       color: GrayText;
     }
+    /* The committed option's fill is an author background the UA would erase,
+       leaving the chosen row indistinguishable from the rest of the list —
+       the same failure the selected cell above has, answered the same way:
+       the system's own guaranteed pair, and `forced-color-adjust: none` so
+       the pair survives. */
+    :where([data-pretable-option][aria-selected="true"]) {
+      forced-color-adjust: none;
+      background-color: Highlight;
+      color: HighlightText;
+    }
   }
 
   /* Reduced motion. Every animated declaration in this file is named here:
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 825d202e..b2fa0414 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -46,6 +46,18 @@ const ICON_BUTTON_SITES = [
 ];
 const PUSH_BUTTON_SITES = [...LABELLED_BUTTON_SITES, ...ICON_BUTTON_SITES];
 
+/** The four picker sites `PretableSelect` collapses: the filter dialog's
+ *  operator, the builder row's column and operator, and the grouping
+ *  section's aggregate. Their site attributes have the same shape as the
+ *  buttons' (`data-pretable-<site>`), so the site guard finds them the same
+ *  way. */
+const SELECT_SITES = [
+  "filter-operator",
+  "filter-row-column",
+  "filter-row-operator",
+  "aggregate",
+];
+
 /** The token names pretable.css declares — the contract a section may read
  *  from and must not add to. Same source the token contract test loads. */
 const tokenContract = () => {
@@ -408,6 +420,87 @@ describe("grid.css cascade contract", () => {
     );
   });
 
+  test("the kit select trigger carries the field box, and the list its surface", () => {
+    const css = strippedCss();
+    const trigger = rulesSelecting(
+      css,
+      (s) =>
+        s.includes("data-pretable-select]") &&
+        !s.includes("::") &&
+        !s.includes(":hover") &&
+        !s.includes(":focus") &&
+        !s.includes(":disabled"),
+    );
+    expect(trigger.length, "no kit select rule").toBeGreaterThan(0);
+    const body = trigger.map((m) => m[2]).join("");
+    for (const decl of [
+      /display:\s*inline-flex/,
+      /align-items:\s*center/,
+      /justify-content:\s*space-between/,
+      /box-sizing:\s*border-box/,
+      /border:\s*1px solid var\(--pretable-rule\)/,
+      /border-radius:\s*var\(--pretable-radius-control\)/,
+      /background:\s*var\(--pretable-bg-grid\)/,
+      /color:\s*var\(--pretable-text-cell\)/,
+      /font:\s*inherit/,
+      /cursor:\s*pointer/,
+      /text-align:\s*start/,
+    ])
+      expect(body).toMatch(decl);
+    // Ring and disabled ink in the state section, like the buttons.
+    const state = rulesSelecting(
+      css,
+      (s) =>
+        s.includes("data-pretable-select]:focus-visible") ||
+        s.includes("data-pretable-select]:disabled"),
+    )
+      .map((m) => m[2])
+      .join("");
+    expect(state).toMatch(/outline:\s*2px solid var\(--pretable-focus-ring\)/);
+    expect(state).toMatch(/cursor:\s*default/);
+    // The list: the enum editor's surface, now the kit's.
+    const list = rulesSelecting(css, (s) =>
+      s.includes("data-pretable-listbox]"),
+    )
+      .map((m) => m[2])
+      .join("");
+    expect(list).toMatch(/max-height:\s*220px/);
+    expect(list).toMatch(/border:\s*1px solid var\(--pretable-rule-strong\)/);
+    expect(list).toMatch(/line-height:\s*[^;]+/);
+    const selectedOption = rulesSelecting(css, (s) =>
+      s.includes('data-pretable-option][aria-selected="true"]'),
+    )
+      .map((m) => m[2])
+      .join("");
+    expect(selectedOption).toMatch(
+      /background:\s*var\(--pretable-bg-selected\)/,
+    );
+    const activeOption = rulesSelecting(css, (s) =>
+      s.includes("data-pretable-option][data-active]"),
+    )
+      .map((m) => m[2])
+      .join("");
+    expect(activeOption).toMatch(/background:\s*var\(--pretable-bg-hover\)/);
+    // No enum-only list rule survives; the editor rides the kit rules.
+    expect(
+      rulesSelecting(
+        css,
+        (s) =>
+          s.includes("data-pretable-enum-listbox]") ||
+          s.includes("data-pretable-enum-option]"),
+      ).length,
+    ).toBe(0);
+    // Forced colours: the selected option is the system's pair.
+    const forced = forcedColorsBlock(css);
+    expect(
+      rulesSelecting(forced, (s) =>
+        s.includes('data-pretable-option][aria-selected="true"]'),
+      )
+        .map((m) => m[2])
+        .join(""),
+    ).toMatch(/background-color:\s*Highlight/);
+  });
+
   test("a push-button site rule declares only what is its own", () => {
     // The kit rules own the box: the border, the background, the radius, the
     // cursor, the font, the flex centring, the ring and the disabled ink. A
@@ -438,6 +531,19 @@ describe("grid.css cascade contract", () => {
       /(?:^|[;{\s])flex:\s*none/,
       /(?:^|[;{\s])padding:\s*0\s*;/,
     ];
+    // The kit select rule owns the field box the four pickers used to each
+    // declare: the frame, the surface, the ink, the font and the pointer. A
+    // picker site that redeclares any of them is the per-site copy coming
+    // back. Its SIZE and its flex participation are its own, and stay.
+    const SELECT_OWNED = [
+      /(?:^|[;{\s])display:\s*inline-flex/,
+      /(?:^|[;{\s])border:\s*1px solid var\(--pretable-rule\)/,
+      /border-radius:\s*var\(--pretable-radius-control\)/,
+      /(?:^|[;{\s])background:\s*var\(--pretable-bg-grid\)/,
+      /(?:^|[;{\s])color:\s*var\(--pretable-text-cell\)/,
+      /(?:^|[;{\s])font:\s*inherit/,
+      /(?:^|[;{\s])cursor:\s*pointer/,
+    ];
 
     // What each site genuinely OWNS, and must keep after the collapse: a
     // size, a reveal, an alignment. Without this the guard passes for a site
@@ -462,9 +568,15 @@ describe("grid.css cascade contract", () => {
       "chip-remove": /width:\s*14px|inline-size:\s*14px/,
       "filter-row-remove": /inline-size:\s*24px|width:\s*24px/,
       "tool-group-remove": /inline-size:\s*24px|width:\s*24px/,
+      // The dialog's picker is 28px, full width, with the dialog's 7px inset;
+      // the builder's and the aggregate picker are 24px flex items.
+      "filter-operator": /block-size:\s*28px/,
+      "filter-row-column": /block-size:\s*24px/,
+      "filter-row-operator": /block-size:\s*24px/,
+      aggregate: /block-size:\s*24px/,
     };
 
-    for (const site of PUSH_BUTTON_SITES) {
+    for (const site of [...PUSH_BUTTON_SITES, ...SELECT_SITES]) {
       const attr = `data-pretable-${site}]`;
       // Every rule that NAMES the site and is not a state or a pseudo —
       // including the :has() ancestor rules, which is where two of these
@@ -478,10 +590,14 @@ describe("grid.css cascade contract", () => {
           !selector.includes(":focus") &&
           !selector.includes(":disabled"),
       );
-      const forbidden = [
-        ...OWNED,
-        ...(LABELLED_BUTTON_SITES.includes(site) ? LABELLED_OWNED : ICON_OWNED),
-      ];
+      const forbidden = SELECT_SITES.includes(site)
+        ? SELECT_OWNED
+        : [
+            ...OWNED,
+            ...(LABELLED_BUTTON_SITES.includes(site)
+              ? LABELLED_OWNED
+              : ICON_OWNED),
+          ];
       for (const [, selector, body] of rules) {
         for (const owned of forbidden) {
           expect(

From 9c19ca1e4b4edce88d549411887256ac6a21eebd Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:14:03 -0700
Subject: [PATCH 14/27] refactor(react,ui): the four pickers render the kit
 Select
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Filter dialog operator (ref kept — the dialog focuses it on open), the
builder's column and operator, the aggregate picker (custom entry now a
disabled option, never written). Every site keeps its attribute; the
aggregate picker gains one. Site rules that selected by element type are
rewritten onto the attributes and keep only size and flex participation.
Test drivers move to chooseOption / readOptions / selectValue; no claim
changed. Site guard mutation-checked (a re-added border fails it); the
kit guard now covers the label and caret (a deleted label rule fails it);
the bracket guard covers the select sites.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/attribute-contract.test.tsx |   4 +-
 .../__tests__/components-override.test.tsx    |  77 +++++++-
 .../src/__tests__/filter-builder.test.tsx     | 106 +++++------
 .../__tests__/filter-menu-surface.test.tsx    |  34 ++--
 .../react/src/__tests__/filter-menu.test.tsx  |  21 +--
 .../tool-panel-aggregates-picker.test.tsx     | 120 ++++++++-----
 .../react/src/__tests__/tool-panel.test.tsx   |  26 ++-
 packages/react/src/filter-menu/FilterMenu.tsx |  21 ++-
 .../src/tool-panel/filters/FilterRow.tsx      |  44 +++--
 .../tool-panel/grouping/GroupingSection.tsx   |  64 ++++---
 packages/ui/grid.css                          |  99 ++++++-----
 packages/ui/src/__tests__/css-cascade.test.ts | 168 +++++++++++++-----
 12 files changed, 485 insertions(+), 299 deletions(-)

diff --git a/packages/react/src/__tests__/attribute-contract.test.tsx b/packages/react/src/__tests__/attribute-contract.test.tsx
index d1eced8f..3fd9000d 100644
--- a/packages/react/src/__tests__/attribute-contract.test.tsx
+++ b/packages/react/src/__tests__/attribute-contract.test.tsx
@@ -118,7 +118,9 @@ describe("attribute contract", () => {
       container.querySelector("input[data-pretable-hide-grouped]"),
     ).not.toBeNull();
     expect(
-      container.querySelector("[data-pretable-aggregate-row] select"),
+      container.querySelector(
+        "[data-pretable-aggregate-row] button[data-pretable-aggregate]",
+      ),
     ).not.toBeNull();
     const ALLOWED = new Set(["data-testid"]);
     const offenders = new Set<string>();
diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
index fdde15ee..394a65bd 100644
--- a/packages/react/src/__tests__/components-override.test.tsx
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -11,6 +11,7 @@ import type {
   PretableButtonComponent,
   PretableComponents,
   PretableIconButtonComponent,
+  PretableSelectComponent,
 } from "../components/context";
 
 afterEach(() => {
@@ -50,6 +51,30 @@ const MyIconButton: PretableIconButtonComponent = forwardRef(
   },
 );
 
+/**
+ * A replacement picker. `options`, `value`, `onChange` and `site` are the
+ * kit's own props and mean nothing to a <button>, so they are destructured
+ * AWAY before the spread — left in, React warns about every one of them on
+ * every render and the suite's console fills with noise that hides real
+ * warnings.
+ */
+const MySelect: PretableSelectComponent = forwardRef(function MySelect(
+  { options, value, onChange, site, ...props },
+  ref,
+) {
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      data-mine-select={site ?? ""}
+      data-mine-value={value}
+      data-mine-option-count={options.length}
+      onClick={() => onChange(options[0]?.value ?? "")}
+    />
+  );
+});
+
 // `PretableSurface` is generic, so `ComponentProps<typeof PretableSurface>`
 // resolves its props against `{}`; the prop's own type is the direct thing to
 // name here anyway.
@@ -176,7 +201,7 @@ describe("components on the surface", () => {
     );
     const expectKit = (
       attr: string,
-      kind: "button" | "icon-button",
+      kind: "button" | "icon-button" | "select",
       site: string,
     ) => {
       const el =
@@ -196,13 +221,16 @@ describe("components on the surface", () => {
     expectKit("column-menu-button", "icon-button", "column-menu-button");
     // Group panel chip remove (a grouped column renders a chip).
     expectKit("chip-remove", "icon-button", "chip-remove");
+    // The grouping section's aggregate picker — the kit Select, not a native
+    // <select>, and the only one of the four sites this fixture renders.
+    expectKit("aggregate", "select", "aggregate");
   });
 
   it("the columns and filters sections' sites render the kit component too", async () => {
     const view = renderSurface(); // columns section open
     const kit = (
       attr: string,
-      kind: "button" | "icon-button",
+      kind: "button" | "icon-button" | "select",
       site: string,
     ) => {
       const el = view.container.querySelector(`[data-pretable-${attr}]`);
@@ -219,6 +247,9 @@ describe("components on the surface", () => {
       view.container.querySelector("[data-pretable-filter-add]")!,
     );
     kit("filter-row-remove", "icon-button", "filter-row-remove");
+    // The leaf row's two pickers are kit Selects.
+    kit("filter-row-column", "select", "filter-row-column");
+    kit("filter-row-operator", "select", "filter-row-operator");
     // The dialog's Clear is portalled: open a funnel.
     const funnel = view.container.querySelector(
       "[data-pretable-filter-funnel]",
@@ -234,6 +265,48 @@ describe("components on the surface", () => {
     expect(clear).not.toBeNull();
     expect(clear).toHaveAttribute("data-pretable-button", "");
     expect(clear).toHaveAttribute("data-pretable-site", "filter-clear");
+    // And the dialog's operator picker, the fourth select site.
+    const operator = dialog.querySelector("[data-pretable-filter-operator]");
+    expect(operator).not.toBeNull();
+    expect(operator).toHaveAttribute("data-pretable-select", "");
+    expect(operator).toHaveAttribute("data-pretable-site", "filter-operator");
+  });
+
+  it("replaces every Select — the portalled dialog's picker and the builder's", async () => {
+    const view = renderSurface({ Select: MySelect });
+
+    // The builder's column picker, inside the pane.
+    fireEvent.click(view.getByRole("tab", { name: /filter/i }));
+    fireEvent.click(
+      view.container.querySelector("[data-pretable-filter-add]")!,
+    );
+    const column = view.container.querySelector(
+      "[data-pretable-filter-row-column]",
+    )!;
+    expect(column).toHaveAttribute("data-mine-select", "filter-row-column");
+    expect(column).toHaveAttribute("data-mine-value", "name");
+    // Nothing that identified this picker before stops identifying it, and
+    // the kit's own attribute is gone with the kit component.
+    expect(column).not.toHaveAttribute("data-pretable-select");
+
+    // And the dialog's operator picker, which renders through OverlayPortal
+    // into document.body — the reason this is context and not props.
+    const funnel = view.container.querySelector(
+      "[data-pretable-filter-funnel]",
+    )!;
+    fireEvent.pointerDown(funnel);
+    fireEvent.click(funnel);
+    const dialog = await waitFor(() => {
+      const el = document.querySelector("[data-pretable-filter-menu]");
+      if (!el) throw new Error("dialog not open");
+      return el;
+    });
+    const operator = dialog.querySelector("[data-pretable-filter-operator]")!;
+    expect(operator).toHaveAttribute("data-mine-select", "filter-operator");
+    expect(operator).not.toHaveAttribute("data-pretable-select");
+    // The dialog focuses the picker on open through the ref it holds, so a
+    // replacement that forwards its ref keeps that working.
+    expect(operator).toHaveFocus();
   });
 });
 
diff --git a/packages/react/src/__tests__/filter-builder.test.tsx b/packages/react/src/__tests__/filter-builder.test.tsx
index 7dc17633..a4c44083 100644
--- a/packages/react/src/__tests__/filter-builder.test.tsx
+++ b/packages/react/src/__tests__/filter-builder.test.tsx
@@ -20,6 +20,7 @@ import {
 import { FiltersSection } from "../tool-panel/filters/FiltersSection";
 import { JoinControl } from "../tool-panel/filters/JoinControl";
 import { defaultMessages } from "../messages";
+import { chooseOption, readOptions, selectValue } from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -271,20 +272,15 @@ const COLUMNS: FilterRowColumn[] = [
 const row = (container: HTMLElement) =>
   container.querySelector<HTMLElement>("[data-pretable-filter-row]")!;
 const operatorSelect = (container: HTMLElement) =>
-  container.querySelector<HTMLSelectElement>(
-    "select[data-pretable-filter-row-operator]",
-  )!;
+  container.querySelector<HTMLElement>("[data-pretable-filter-row-operator]")!;
 const columnSelect = (container: HTMLElement) =>
-  container.querySelector<HTMLSelectElement>(
-    "select[data-pretable-filter-row-column]",
-  )!;
+  container.querySelector<HTMLElement>("[data-pretable-filter-row-column]")!;
 /** Every value control the row is currently rendering, in document order. */
 const values = (container: HTMLElement) =>
   Array.from(
     container.querySelectorAll<HTMLElement>("[data-pretable-filter-row-value]"),
   );
-const options = (select: HTMLSelectElement) =>
-  Array.from(select.options).map((o) => o.value);
+const options = (select: HTMLElement) => readOptions(select).values;
 /** The checked boxes of a set-shape row, as the filter value they encode. */
 const checkedValues = (container: HTMLElement) =>
   Array.from(
@@ -362,9 +358,7 @@ describe("FilterRow", () => {
     // The default (`equals`) is a single value; `between` is the shape change.
     expect(values(container)).toHaveLength(1);
 
-    fireEvent.change(operatorSelect(container), {
-      target: { value: "between" },
-    });
+    chooseOption(operatorSelect(container), "between");
 
     const [min, max] = values(container);
     expect(values(container)).toHaveLength(2);
@@ -380,7 +374,7 @@ describe("FilterRow", () => {
   it("renders a multi-select for an enum column's `isAnyOf`", () => {
     const { container, getByLabelText } = render(<Leaf columnId="status" />);
 
-    expect(operatorSelect(container).value).toBe("isAnyOf");
+    expect(selectValue(operatorSelect(container))).toBe("isAnyOf");
     const [group, ...rest] = values(container);
     expect(rest).toHaveLength(0);
     expect(group).toHaveAttribute("role", "group");
@@ -407,11 +401,9 @@ describe("FilterRow", () => {
   it("renders NO value control for `isEmpty`", () => {
     const { container } = render(<Leaf />);
 
-    fireEvent.change(operatorSelect(container), {
-      target: { value: "isEmpty" },
-    });
+    chooseOption(operatorSelect(container), "isEmpty");
 
-    expect(operatorSelect(container).value).toBe("isEmpty");
+    expect(selectValue(operatorSelect(container))).toBe("isEmpty");
     expect(values(container)).toHaveLength(0);
     expect(container.querySelector("input[type=text]")).toBeNull();
   });
@@ -420,18 +412,16 @@ describe("FilterRow", () => {
     const onChange = vi.fn();
     const { container } = render(<Leaf onChange={onChange} />);
 
-    fireEvent.change(operatorSelect(container), {
-      target: { value: "contains" },
-    });
+    chooseOption(operatorSelect(container), "contains");
     fireEvent.change(values(container)[0]!, { target: { value: "acme" } });
-    expect(operatorSelect(container).value).toBe("contains");
+    expect(selectValue(operatorSelect(container))).toBe("contains");
 
     // `contains` is not a number operator; leaving it would name a filter the
     // engine cannot run on this column.
-    fireEvent.change(columnSelect(container), { target: { value: "revenue" } });
+    chooseOption(columnSelect(container), "revenue");
 
-    expect(columnSelect(container).value).toBe("revenue");
-    expect(operatorSelect(container).value).toBe(
+    expect(selectValue(columnSelect(container))).toBe("revenue");
+    expect(selectValue(operatorSelect(container))).toBe(
       defaultDraft("number").operator,
     );
     expect(options(operatorSelect(container))).toEqual(
@@ -450,15 +440,13 @@ describe("FilterRow", () => {
   it("keeps an operator the new column can still run", () => {
     const { container } = render(<Leaf />);
 
-    fireEvent.change(operatorSelect(container), {
-      target: { value: "endsWith" },
-    });
+    chooseOption(operatorSelect(container), "endsWith");
     fireEvent.change(values(container)[0]!, { target: { value: "corp" } });
 
-    fireEvent.change(columnSelect(container), { target: { value: "notes" } });
+    chooseOption(columnSelect(container), "notes");
 
-    expect(columnSelect(container).value).toBe("notes");
-    expect(operatorSelect(container).value).toBe("endsWith");
+    expect(selectValue(columnSelect(container))).toBe("notes");
+    expect(selectValue(operatorSelect(container))).toBe("endsWith");
     expect(values(container)[0]).toHaveValue("corp");
   });
 
@@ -558,10 +546,16 @@ describe("FilterRow", () => {
     );
 
     const select = operatorSelect(container);
-    // The one assertion that catches the silent substitution: what the select
-    // holds and what it DISPLAYS are the same operator.
-    expect(select.value).toBe("equals");
-    expect(select.options[select.selectedIndex]?.value).toBe("equals");
+    // The one assertion that catches the silent substitution: what the picker
+    // holds and what it DISPLAYS are the same operator. The trigger renders
+    // the OPTION's label when the value matches one, and the bare value when
+    // it does not, so reading the label span is the same question a native
+    // <select>'s `options[selectedIndex]` used to answer.
+    expect(selectValue(select)).toBe("equals");
+    const listed = readOptions(select);
+    expect(
+      select.querySelector("[data-pretable-select-label]")?.textContent,
+    ).toBe(listed.labels[listed.values.indexOf("equals")]);
     expect(options(select)).toContain("equals");
     // Written out, not `toEqual(menuOperators(...))`: comparing the component
     // against the very function it calls passes whenever both are wrong. The
@@ -578,7 +572,7 @@ describe("FilterRow", () => {
     const { container } = render(<Leaf columnId="stage" />);
 
     expect(options(operatorSelect(container))).toEqual(["contains", "isEmpty"]);
-    expect(operatorSelect(container).value).toBe("contains");
+    expect(selectValue(operatorSelect(container))).toBe("contains");
   });
 
   /* THE SET-SHAPE COLUMN CHANGE. `isAnyOf` is permitted on every enum and
@@ -598,11 +592,9 @@ describe("FilterRow", () => {
     expect(checkedValues(container)).toEqual(["open"]);
 
     // Enum -> boolean: `open` is not a value this column has.
-    fireEvent.change(columnSelect(container), {
-      target: { value: "verified" },
-    });
+    chooseOption(columnSelect(container), "verified");
 
-    expect(operatorSelect(container).value).toBe("isAnyOf");
+    expect(selectValue(operatorSelect(container))).toBe("isAnyOf");
     expect(onChange).toHaveBeenLastCalledWith({
       columnId: "verified",
       draft: defaultDraft("boolean"),
@@ -627,9 +619,7 @@ describe("FilterRow", () => {
     expect(checkedValues(container)).toEqual(["open", "won"]);
 
     // `substatus` offers `open` and `blocked` — the overlap is `open` alone.
-    fireEvent.change(columnSelect(container), {
-      target: { value: "substatus" },
-    });
+    chooseOption(columnSelect(container), "substatus");
 
     expect(checkedValues(container)).toEqual(["open"]);
     expect(values(container)[0]).toHaveTextContent("Blocked");
@@ -651,7 +641,7 @@ describe("FilterRow", () => {
     expect(options(operatorSelect(container))).toEqual(
       operatorsForType("boolean"),
     );
-    expect(operatorSelect(container).value).toBe("isAnyOf");
+    expect(selectValue(operatorSelect(container))).toBe("isAnyOf");
 
     fireEvent.click(getByLabelText("True"));
     fireEvent.click(getByLabelText("False"));
@@ -689,9 +679,7 @@ describe("FilterRow", () => {
     expect(values(container)[0]).toHaveTextContent("ana");
     distinctValues.mockClear();
 
-    fireEvent.change(operatorSelect(container), {
-      target: { value: "isEmpty" },
-    });
+    chooseOption(operatorSelect(container), "isEmpty");
 
     expect(values(container)).toHaveLength(0);
     expect(distinctValues).not.toHaveBeenCalled();
@@ -892,9 +880,9 @@ describe("FiltersSection", () => {
       row.querySelector<HTMLElement>("[data-pretable-filter-join]")!,
     );
   const columnOf = (row: HTMLElement) =>
-    row.querySelector<HTMLSelectElement>(
-      "select[data-pretable-filter-row-column]",
-    )!.value;
+    selectValue(
+      row.querySelector<HTMLElement>("[data-pretable-filter-row-column]")!,
+    );
   const valueOf = (row: HTMLElement) =>
     row.querySelector<HTMLInputElement>(
       "input[data-pretable-filter-row-value]",
@@ -1072,9 +1060,9 @@ describe("FiltersSection", () => {
     const view = renderSection([leafNode("name", "contains", "acme")]);
     const row = filterRows(view.container)[0]!;
 
-    fireEvent.change(
-      row.querySelector("select[data-pretable-filter-row-operator]")!,
-      { target: { value: "isEmpty" } },
+    chooseOption(
+      row.querySelector<HTMLElement>("[data-pretable-filter-row-operator]")!,
+      "isEmpty",
     );
 
     expect(view.writes).toHaveBeenCalledTimes(1);
@@ -1260,11 +1248,11 @@ describe("FiltersSection", () => {
     });
     // A DISCRETE edit on the other row — it applies at once, and it must
     // settle the write it is taking the timer away from rather than drop it.
-    fireEvent.change(
-      filterRows(view.container)[1]!.querySelector(
-        "select[data-pretable-filter-row-operator]",
+    chooseOption(
+      filterRows(view.container)[1]!.querySelector<HTMLElement>(
+        "[data-pretable-filter-row-operator]",
       )!,
-      { target: { value: "isNotEmpty" } },
+      "isNotEmpty",
     );
     act(() => {
       vi.advanceTimersByTime(500);
@@ -1517,11 +1505,11 @@ describe("FiltersSection", () => {
 
     // Now the wanted SET changes, which is the only thing that re-runs the
     // load: the second row starts showing a checklist.
-    fireEvent.change(
-      filterRows(view.container)[1]!.querySelector(
-        "select[data-pretable-filter-row-operator]",
+    chooseOption(
+      filterRows(view.container)[1]!.querySelector<HTMLElement>(
+        "[data-pretable-filter-row-operator]",
       )!,
-      { target: { value: "isAnyOf" } },
+      "isAnyOf",
     );
 
     // The new column is asked. The one that already answered is not.
diff --git a/packages/react/src/__tests__/filter-menu-surface.test.tsx b/packages/react/src/__tests__/filter-menu-surface.test.tsx
index 4576f957..f8943dd8 100644
--- a/packages/react/src/__tests__/filter-menu-surface.test.tsx
+++ b/packages/react/src/__tests__/filter-menu-surface.test.tsx
@@ -16,6 +16,7 @@ import {
   type PretableSurfaceProps,
 } from "../pretable-surface";
 import type { PretableColumn } from "../types";
+import { readOptions, selectValue } from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -172,21 +173,22 @@ describe("PretableSurface — built-in filter funnel", () => {
 
     fireEvent.click(view.getByRole("button", { name: "Filter Owner" }));
     const dialog = view.getByRole("dialog", { name: "Filter Owner" });
-    const select = dialog.querySelector<HTMLSelectElement>(
+    const select = dialog.querySelector<HTMLElement>(
       "[data-pretable-filter-operator]",
     )!;
 
-    expect(select.value).toBe("equals");
+    expect(selectValue(select)).toBe("equals");
     // What it HOLDS and what it DISPLAYS are the same operator — the
-    // assertion the value check alone does not make.
-    expect(select.options[select.selectedIndex]?.value).toBe("equals");
+    // assertion the value check alone does not make. The trigger shows the
+    // OPTION's label when the value names one and the bare value when it does
+    // not, which is the substitution a native <select> hid.
+    const listed = readOptions(select);
+    expect(
+      select.querySelector("[data-pretable-select-label]")?.textContent,
+    ).toBe(listed.labels[listed.values.indexOf("equals")]);
     // The permitted pair plus the applied operator, in the type's own order;
     // everything else the column pruned stays pruned.
-    expect(Array.from(select.options).map((o) => o.value)).toEqual([
-      "contains",
-      "equals",
-      "isEmpty",
-    ]);
+    expect(listed.values).toEqual(["contains", "equals", "isEmpty"]);
   });
 
   it("re-hydrates the dialog when switching directly between two open funnels", () => {
@@ -208,16 +210,18 @@ describe("PretableSurface — built-in filter funnel", () => {
     fireEvent.click(view.getByRole("button", { name: "Filter Title" }));
     let dialog = view.getByRole("dialog", { name: "Filter Title" });
     expect(
-      dialog.querySelector<HTMLSelectElement>("[data-pretable-filter-operator]")
-        ?.value,
+      selectValue(
+        dialog.querySelector<HTMLElement>("[data-pretable-filter-operator]")!,
+      ),
     ).toBe("endsWith");
 
     // Click Count's funnel WHILE Title's menu is open → switch + re-hydrate.
     fireEvent.click(view.getByRole("button", { name: "Filter Count" }));
     dialog = view.getByRole("dialog", { name: "Filter Count" });
     expect(
-      dialog.querySelector<HTMLSelectElement>("[data-pretable-filter-operator]")
-        ?.value,
+      selectValue(
+        dialog.querySelector<HTMLElement>("[data-pretable-filter-operator]")!,
+      ),
     ).toBe("gt");
     expect(
       dialog.querySelector<HTMLInputElement>("[data-pretable-filter-value]")
@@ -445,7 +449,7 @@ describe("PretableSurface — built-in filter funnel", () => {
     // Opening hydrates the dialog to the active operator/value.
     fireEvent.click(funnel);
     const dialog = view.getByRole("dialog", { name: "Filter Title" });
-    expect(within(dialog).getByLabelText("Filter operator")).toHaveValue(
+    expect(selectValue(within(dialog).getByLabelText("Filter operator"))).toBe(
       "contains",
     );
     expect(within(dialog).getByLabelText("Filter value")).toHaveValue("beta");
@@ -654,7 +658,7 @@ describe("PretableSurface — filter trees", () => {
 
     fireEvent.click(view.getByRole("button", { name: "Filter Title" }));
     const dialog = view.getByRole("dialog", { name: "Filter Title" });
-    expect(within(dialog).getByLabelText("Filter operator")).toHaveValue(
+    expect(selectValue(within(dialog).getByLabelText("Filter operator"))).toBe(
       "endsWith",
     );
     expect(within(dialog).getByLabelText("Filter value")).toHaveValue("crash");
diff --git a/packages/react/src/__tests__/filter-menu.test.tsx b/packages/react/src/__tests__/filter-menu.test.tsx
index 9bad2f5b..e29d58ac 100644
--- a/packages/react/src/__tests__/filter-menu.test.tsx
+++ b/packages/react/src/__tests__/filter-menu.test.tsx
@@ -14,6 +14,7 @@ import type {
 } from "@pretable/core";
 
 import { FilterMenu } from "../filter-menu";
+import { chooseOption, selectValue } from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -79,8 +80,8 @@ describe("FilterMenu — dialog basics", () => {
     renderMenu({ type: "text" });
     const select = screen.getByRole("combobox", {
       name: "Filter operator",
-    }) as HTMLSelectElement;
-    expect(select.value).toBe("contains");
+    });
+    expect(selectValue(select)).toBe("contains");
   });
 });
 
@@ -110,9 +111,7 @@ describe("FilterMenu — operator switch", () => {
     const { onChange } = renderMenu({ type: "text" });
     const select = screen.getByRole("combobox", { name: "Filter operator" });
 
-    act(() => {
-      fireEvent.change(select, { target: { value: "isEmpty" } });
-    });
+    chooseOption(select, "isEmpty");
 
     expect(screen.queryByRole("textbox", { name: "Filter value" })).toBeNull();
     expect(lastCall(onChange)).toEqual(["c", { operator: "isEmpty" }]);
@@ -124,9 +123,7 @@ describe("FilterMenu — number between gating", () => {
     const { onChange } = renderMenu({ type: "number" });
     const select = screen.getByRole("combobox", { name: "Filter operator" });
 
-    act(() => {
-      fireEvent.change(select, { target: { value: "between" } });
-    });
+    chooseOption(select, "between");
     // operator change with empty range → null
     expect(lastCall(onChange)).toEqual(["c", null]);
 
@@ -325,8 +322,8 @@ describe("FilterMenu — hydrate from initialFilter", () => {
     });
     const select = screen.getByRole("combobox", {
       name: "Filter operator",
-    }) as HTMLSelectElement;
-    expect(select.value).toBe("startsWith");
+    });
+    expect(selectValue(select)).toBe("startsWith");
     expect(screen.getByRole("textbox", { name: "Filter value" })).toHaveValue(
       "Ad",
     );
@@ -337,9 +334,7 @@ describe("FilterMenu — date single applies immediately", () => {
   it("date input applies without waiting for the debounce", () => {
     const { onChange } = renderMenu({ type: "date" });
     const select = screen.getByRole("combobox", { name: "Filter operator" });
-    act(() => {
-      fireEvent.change(select, { target: { value: "before" } });
-    });
+    chooseOption(select, "before");
     const input = screen.getByLabelText("Filter value");
     act(() => {
       fireEvent.change(input, { target: { value: "2026-06-18" } });
diff --git a/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx b/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
index 81e42659..1e01dfa8 100644
--- a/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
+++ b/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
@@ -13,6 +13,7 @@ import { defaultMessages } from "../messages";
 import { PretableSurface } from "../pretable-surface";
 import { GroupingSection } from "../tool-panel/grouping";
 import type { GroupingSectionColumn } from "../tool-panel/grouping";
+import { chooseOption, readOptions, selectValue } from "./select-helpers";
 
 afterEach(cleanup);
 
@@ -89,25 +90,32 @@ function techAggregateText(container: HTMLElement): string | null {
   return cell.textContent ?? "";
 }
 
-function pickerFor(
-  container: HTMLElement,
-  columnId: string,
-): HTMLSelectElement {
-  const select = container.querySelector(
-    `[data-pretable-aggregate-row][data-pretable-column-id="${columnId}"] select`,
+function pickerFor(container: HTMLElement, columnId: string): HTMLElement {
+  const picker = container.querySelector(
+    `[data-pretable-aggregate-row][data-pretable-column-id="${columnId}"] [data-pretable-aggregate]`,
   );
-  if (!(select instanceof HTMLSelectElement)) {
+  if (!(picker instanceof HTMLElement)) {
     throw new Error(`No aggregate picker rendered for ${columnId}`);
   }
-  return select;
+  return picker;
 }
 
-function optionValues(select: HTMLSelectElement): string[] {
-  return [...select.options].map((option) => option.value);
+function optionValues(picker: HTMLElement): string[] {
+  return readOptions(picker).values;
 }
 
-function optionLabels(select: HTMLSelectElement): string[] {
-  return [...select.options].map((option) => option.textContent ?? "");
+function optionLabels(picker: HTMLElement): string[] {
+  return readOptions(picker).labels;
+}
+
+/** The label the picker offers for one option value, read from the open list. */
+function optionLabelFor(
+  picker: HTMLElement,
+  value: string,
+): string | undefined {
+  const listed = readOptions(picker);
+  const at = listed.values.indexOf(value);
+  return at < 0 ? undefined : listed.labels[at];
 }
 
 /**
@@ -174,17 +182,14 @@ describe("aggregate picker over a real grouped grid", () => {
     const picker = pickerFor(container, "qty");
     // No override yet: the picker shows the explicit Default face, carrying
     // the declared aggregate's display name (spec decision 4).
-    expect(picker.value).toBe("default");
-    expect(
-      [...picker.options].find((option) => option.value === "default")
-        ?.textContent,
-    ).toBe("Default (Average)");
+    expect(selectValue(picker)).toBe("default");
+    expect(optionLabelFor(picker, "default")).toBe("Default (Average)");
 
-    fireEvent.change(picker, { target: { value: "sum" } });
+    chooseOption(picker, "sum");
     await waitFor(() => {
       expect(techAggregateText(container)).toBe("30"); // sum ≠ avg: 10 + 20
     });
-    expect(picker.value).toBe("sum");
+    expect(selectValue(picker)).toBe("sum");
   });
 
   it("None strips the declared aggregate; Default restores it", async () => {
@@ -195,19 +200,19 @@ describe("aggregate picker over a real grouped grid", () => {
     });
     const picker = pickerFor(container, "qty");
 
-    fireEvent.change(picker, { target: { value: "none" } });
+    chooseOption(picker, "none");
     await waitFor(() => {
       // The CELL still exists (null would mean the row went missing) — it is
       // the aggregate inside it that the sentinel stripped to empty.
       expect(techAggregateText(container)).toBe("");
     });
-    expect(picker.value).toBe("none");
+    expect(selectValue(picker)).toBe("none");
 
-    fireEvent.change(picker, { target: { value: "default" } });
+    chooseOption(picker, "default");
     await waitFor(() => {
       expect(techAggregateText(container)).toBe("15"); // declared avg again
     });
-    expect(picker.value).toBe("default");
+    expect(selectValue(picker)).toBe("default");
   });
 });
 
@@ -220,12 +225,12 @@ describe("aggregate picker select state (structural fakes, zero flips)", () => {
       columnAggregates: { qty: "sum" },
     });
     const overriddenPicker = pickerFor(overridden.container, "qty");
-    expect(overriddenPicker.value).toBe("sum");
+    expect(selectValue(overriddenPicker)).toBe("sum");
     cleanup();
 
     const clean = renderSection({ columns: [QTY_COLUMN] });
     const cleanPicker = pickerFor(clean.container, "qty");
-    expect(cleanPicker.value).toBe("default");
+    expect(selectValue(cleanPicker)).toBe("default");
     // The EXACT list, not membership: the onChange mapping assumes the
     // chrome values (`default`/`none`, and `custom` when reflected) stay
     // disjoint from the builtin names — nothing structural enforces that,
@@ -241,26 +246,37 @@ describe("aggregate picker select state (structural fakes, zero flips)", () => {
     ]);
     // Both faces exist side by side in one vocabulary: the Default option
     // names the declared value it would restore.
-    expect(
-      [...cleanPicker.options].find((option) => option.value === "default")
-        ?.textContent,
-    ).toBe("Default (Sum)");
+    expect(optionLabelFor(cleanPicker, "default")).toBe("Default (Sum)");
   });
 
   it("an override to a consumer-written aggregator OBJECT shows a Custom option", () => {
     // The pane never writes an object, but the handle allows one; the picker
     // reflects it honestly with a selected Custom entry rather than lying
     // with Default.
-    const { container } = renderSection({
+    const { container, calls } = renderSection({
       columns: [QTY_COLUMN],
       columnAggregates: { qty: { init: () => 0 } },
     });
     const picker = pickerFor(container, "qty");
-    expect(picker.value).toBe("custom");
-    expect(
-      [...picker.options].find((option) => option.value === "custom")
-        ?.textContent,
-    ).toBe("Custom");
+    expect(selectValue(picker)).toBe("custom");
+    expect(optionLabelFor(picker, "custom")).toBe("Custom");
+
+    // DISABLED, not merely reflect-only: the entry exists so the state is
+    // legible, and the kit list marks it inert rather than leaving a decoy
+    // that looks choosable.
+    fireEvent.click(picker);
+    const custom = document.querySelector(
+      '[data-pretable-listbox] [data-pretable-option][data-value="custom"]',
+    );
+    expect(custom).not.toBeNull();
+    expect(custom).toHaveAttribute("aria-disabled", "true");
+
+    // And clicking it writes NOTHING — the guard the old reflect-only branch
+    // was making: the pane must never hand an aggregator object back to
+    // `setColumnAggregate`.
+    fireEvent.click(custom!);
+    expect(calls).toEqual([]);
+    expect(selectValue(picker)).toBe("custom");
   });
 
   it("stays rendered while ungrouped, and the block is ABSENT when aggregates are disabled", () => {
@@ -300,17 +316,31 @@ describe("aggregate picker select state (structural fakes, zero flips)", () => {
     // The destroys-the-grid guard: the engine stores aggregates
     // uninterpreted and an invalid one throws inside a React commit, so the
     // recorded arguments are asserted EXACTLY.
-    const { container, calls } = renderSection({ columns: [QTY_COLUMN] });
-    const picker = pickerFor(container, "qty");
+    // One render per write, each seeded so the chosen option is NOT the one
+    // already committed: a picker reports a change, and choosing what is
+    // already selected is a no-op — in the kit exactly as in a native
+    // <select>. The structural fakes never move `columnAggregates`, so
+    // driving all three from one mount would ask the picker to re-choose
+    // `default` while it still holds `default` and silently record nothing.
+    const fromDeclared = renderSection({ columns: [QTY_COLUMN] });
+    chooseOption(pickerFor(fromDeclared.container, "qty"), "avg");
+    expect(fromDeclared.calls).toEqual([["qty", "avg"]]);
+    cleanup();
 
-    fireEvent.change(picker, { target: { value: "avg" } });
-    fireEvent.change(picker, { target: { value: "none" } });
-    fireEvent.change(picker, { target: { value: "default" } });
-    expect(calls).toEqual([
-      ["qty", "avg"],
-      ["qty", null],
-      ["qty", undefined],
-    ]);
+    const fromBuiltin = renderSection({
+      columns: [QTY_COLUMN],
+      columnAggregates: { qty: "avg" },
+    });
+    chooseOption(pickerFor(fromBuiltin.container, "qty"), "none");
+    expect(fromBuiltin.calls).toEqual([["qty", null]]);
+    cleanup();
+
+    const fromNone = renderSection({
+      columns: [QTY_COLUMN],
+      columnAggregates: { qty: null },
+    });
+    chooseOption(pickerFor(fromNone.container, "qty"), "default");
+    expect(fromNone.calls).toEqual([["qty", undefined]]);
   });
 });
 
diff --git a/packages/react/src/__tests__/tool-panel.test.tsx b/packages/react/src/__tests__/tool-panel.test.tsx
index 9f3cfa38..69cc3ad5 100644
--- a/packages/react/src/__tests__/tool-panel.test.tsx
+++ b/packages/react/src/__tests__/tool-panel.test.tsx
@@ -25,6 +25,7 @@ import type {
   ToolPanelSectionDescriptor,
   ToolPanelSectionId,
 } from "../tool-panel";
+import { chooseOption, readOptions } from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -1538,9 +1539,8 @@ function mountFiltersSection(options?: {
       Array.from(
         view.container.querySelectorAll("[data-pretable-filter-row]"),
       ) as HTMLElement[],
-    columnPicker: () =>
-      q<HTMLSelectElement>("[data-pretable-filter-row-column]"),
-    operator: () => q<HTMLSelectElement>("[data-pretable-filter-row-operator]"),
+    columnPicker: () => q<HTMLElement>("[data-pretable-filter-row-column]"),
+    operator: () => q<HTMLElement>("[data-pretable-filter-row-operator]"),
     value: () => q<HTMLInputElement>("[data-pretable-filter-row-value]"),
     drawnRowCount: () =>
       view.container.querySelectorAll("[data-pretable-row]").length,
@@ -1553,11 +1553,9 @@ describe("filters section on the surface", () => {
     fireEvent.click(h.addFilter());
     const picker = h.columnPicker();
     expect(picker).not.toBeNull();
+    const listed = readOptions(picker!);
     expect(
-      Array.from(picker!.options).map((option) => [
-        option.value,
-        option.textContent,
-      ]),
+      listed.values.map((value, at) => [value, listed.labels[at]]),
     ).toEqual([
       ["name", "Name"],
       ["amount", "Amount"],
@@ -1567,8 +1565,8 @@ describe("filters section on the surface", () => {
   it("carries the column TYPE through, so a number column offers number operators", () => {
     const h = mountFiltersSection();
     fireEvent.click(h.addFilter());
-    fireEvent.change(h.columnPicker()!, { target: { value: "amount" } });
-    const operators = Array.from(h.operator()!.options).map((o) => o.value);
+    chooseOption(h.columnPicker()!, "amount");
+    const operators = readOptions(h.operator()!).values;
     expect(operators).toContain("gt");
     expect(operators).not.toContain("contains");
   });
@@ -1580,7 +1578,7 @@ describe("filters section on the surface", () => {
       expect(h.drawnRowCount()).toBe(2);
 
       fireEvent.click(h.addFilter());
-      fireEvent.change(h.operator()!, { target: { value: "equals" } });
+      chooseOption(h.operator()!, "equals");
       fireEvent.change(h.value()!, { target: { value: "Alpha" } });
       act(() => {
         vi.advanceTimersByTime(250);
@@ -1699,11 +1697,11 @@ describe("filters section on the surface", () => {
           (row) =>
             row.querySelector(
               "[data-pretable-filter-row-column]",
-            ) as HTMLSelectElement,
+            ) as HTMLElement,
         );
     // Row 1 keeps the grouped-away column; row 2 filters a column hidden by
     // VISIBILITY. Both markers on screen at once, and distinct.
-    fireEvent.change(pickers()[1]!, { target: { value: "amount" } });
+    chooseOption(pickers()[1]!, "amount");
     act(() => {
       h.grid.setColumnVisible("amount", false);
     });
@@ -1774,9 +1772,7 @@ describe("filters section on the surface", () => {
       ],
     });
     fireEvent.click(h.addFilter());
-    expect(Array.from(h.columnPicker()!.options).map((o) => o.value)).toEqual([
-      "name",
-    ]);
+    expect(readOptions(h.columnPicker()!).values).toEqual(["name"]);
   });
 });
 
diff --git a/packages/react/src/filter-menu/FilterMenu.tsx b/packages/react/src/filter-menu/FilterMenu.tsx
index 1f55d7e1..7e0eb90e 100644
--- a/packages/react/src/filter-menu/FilterMenu.tsx
+++ b/packages/react/src/filter-menu/FilterMenu.tsx
@@ -74,7 +74,7 @@ export function FilterMenu({
   onChange: (columnId: string, filter: ColumnFilter | null) => void;
   onClose: () => void;
 }): JSX.Element {
-  const { Button } = usePretableComponents();
+  const { Button, Select } = usePretableComponents();
   const [draft, setDraft] = useState<FilterDraft>(() =>
     fromColumnFilter(type, initialFilter, allowedOperators),
   );
@@ -82,7 +82,7 @@ export function FilterMenu({
     useState<DistinctValueState>({ kind: "idle" });
 
   const rootRef = useRef<HTMLDivElement>(null);
-  const selectRef = useRef<HTMLSelectElement>(null);
+  const selectRef = useRef<HTMLButtonElement>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   // Keep the latest draft in a ref so the unmount flush sees current state.
@@ -303,19 +303,18 @@ export function FilterMenu({
         data-pretable-popover=""
         style={style}
       >
-        <select
+        <Select
           ref={selectRef}
+          site="filter-operator"
           data-pretable-filter-operator=""
           aria-label="Filter operator"
+          options={operators.map((op) => ({
+            value: op,
+            label: OPERATOR_LABELS[op],
+          }))}
           value={draft.operator}
-          onChange={(e) => onOperatorChange(e.target.value as FilterOperator)}
-        >
-          {operators.map((op) => (
-            <option key={op} value={op}>
-              {OPERATOR_LABELS[op]}
-            </option>
-          ))}
-        </select>
+          onChange={(op) => onOperatorChange(op as FilterOperator)}
+        />
 
         {shape === "single" ? (
           <input
diff --git a/packages/react/src/tool-panel/filters/FilterRow.tsx b/packages/react/src/tool-panel/filters/FilterRow.tsx
index 3fa455a8..c4b6e91a 100644
--- a/packages/react/src/tool-panel/filters/FilterRow.tsx
+++ b/packages/react/src/tool-panel/filters/FilterRow.tsx
@@ -174,7 +174,7 @@ export function FilterRow({
   processing,
   messages,
 }: FilterRowProps) {
-  const { IconButton } = usePretableComponents();
+  const { IconButton, Select } = usePretableComponents();
   const column = columns.find((c) => c.id === columnId);
   const type = column?.type ?? "text";
   const label = column?.label ?? columnId;
@@ -307,7 +307,8 @@ export function FilterRow({
     >
       {join}
 
-      <select
+      <Select
+        site="filter-row-column"
         data-pretable-filter-row-column=""
         // The state is in the NAME, not only in the row's dim colour: colour
         // alone is SC 1.4.1 (Use of Colour), and this picker is where a
@@ -320,33 +321,28 @@ export function FilterRow({
           // overridden — `toolPanelFilterJoinActionLabel`'s pattern.
           groupedMarker: messages.toolPanelColumnGroupedMarker(),
         })}
+        options={columns.map((c) => ({ value: c.id, label: c.label }))}
         value={columnId}
-        onChange={(e) => onColumnChange(e.target.value)}
-      >
-        {columns.map((c) => (
-          <option key={c.id} value={c.id}>
-            {c.label}
-          </option>
-        ))}
-      </select>
+        onChange={onColumnChange}
+      />
 
-      <select
+      {/* The operator labels are the one string in this row that is NOT a
+          surface message. They are shared with the header funnel, which has
+          no messages thread, so localizing them here alone would show one
+          operator in two languages in one grid — see the TSDoc on
+          `OPERATOR_LABELS`, which records what paying that debt actually
+          requires. */}
+      <Select
+        site="filter-row-operator"
         data-pretable-filter-row-operator=""
         aria-label={messages.toolPanelFilterOperatorLabel()}
+        options={operators.map((op) => ({
+          value: op,
+          label: OPERATOR_LABELS[op],
+        }))}
         value={draft.operator}
-        onChange={(e) => onOperatorChange(e.target.value as FilterOperator)}
-      >
-        {/* The one string in this row that is NOT a surface message. It is
-            shared with the header funnel, which has no messages thread, so
-            localizing it here alone would show one operator in two languages
-            in one grid — see the TSDoc on `OPERATOR_LABELS`, which records
-            what paying that debt actually requires. */}
-        {operators.map((op) => (
-          <option key={op} value={op}>
-            {OPERATOR_LABELS[op]}
-          </option>
-        ))}
-      </select>
+        onChange={(op) => onOperatorChange(op as FilterOperator)}
+      />
 
       {shape === "single" ? (
         <input
diff --git a/packages/react/src/tool-panel/grouping/GroupingSection.tsx b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
index 3a3bc0e1..e9272dbf 100644
--- a/packages/react/src/tool-panel/grouping/GroupingSection.tsx
+++ b/packages/react/src/tool-panel/grouping/GroupingSection.tsx
@@ -148,7 +148,7 @@ export function GroupingSection({
   aggregatesEnabled,
   messages,
 }: GroupingSectionProps) {
-  const { Button, IconButton } = usePretableComponents();
+  const { Button, IconButton, Select } = usePretableComponents();
   // The section's OWN subscription, and the SNAPSHOT slice rather than the
   // state (FiltersSection's pattern): `rowGroups` changes identity only when
   // a query commits, so every other publish bails in useSyncExternalStore's
@@ -560,17 +560,47 @@ export function GroupingSection({
                 key={column.id}
               >
                 <span data-pretable-tool-column-label="">{column.label}</span>
-                <select
+                <Select
+                  site="aggregate"
+                  data-pretable-aggregate=""
                   aria-label={messages.toolPanelAggregateColumnLabel({
                     label: column.label,
                   })}
+                  options={[
+                    {
+                      value: DEFAULT_OPTION,
+                      label: messages.toolPanelAggregateDefaultOption({
+                        label: declaredFace,
+                      }),
+                    },
+                    {
+                      value: NONE_OPTION,
+                      label: messages.toolPanelAggregateNoneOption(),
+                    },
+                    ...builtins.map((name) => ({
+                      value: name as string,
+                      label: builtinLabel(name),
+                    })),
+                    // A consumer CAN write an aggregator object through the
+                    // handle. The picker reflects it honestly: one extra,
+                    // selected `Custom` entry, present only while that state
+                    // holds, disabled so it is never written back.
+                    ...(selected === CUSTOM_OPTION
+                      ? [
+                          {
+                            value: CUSTOM_OPTION,
+                            label: messages.toolPanelAggregateCustomLabel(),
+                            disabled: true,
+                          },
+                        ]
+                      : []),
+                  ]}
                   value={selected}
-                  onChange={(event) => {
+                  onChange={(value) => {
                     // The closed vocabulary IS the validation: an invalid
                     // aggregate destroys the mounted grid (setColumnAggregate
                     // TSDoc), so NOTHING outside these three mappings is
                     // ever written — the option VALUES, never their labels.
-                    const value = event.target.value;
                     if (value === DEFAULT_OPTION) {
                       grid.setColumnAggregate(column.id, undefined);
                     } else if (value === NONE_OPTION) {
@@ -582,31 +612,7 @@ export function GroupingSection({
                     }
                     // `custom` (and anything else): reflect-only, no write.
                   }}
-                >
-                  <option value={DEFAULT_OPTION}>
-                    {messages.toolPanelAggregateDefaultOption({
-                      label: declaredFace,
-                    })}
-                  </option>
-                  <option value={NONE_OPTION}>
-                    {messages.toolPanelAggregateNoneOption()}
-                  </option>
-                  {builtins.map((name) => (
-                    <option key={name} value={name}>
-                      {builtinLabel(name)}
-                    </option>
-                  ))}
-                  {/* A consumer CAN write an aggregator object through the
-                    handle. The picker reflects it honestly: one extra
-                    selected `Custom` entry, present only while that state
-                    holds — not a disabled decoy, and never something the
-                    pane would write back (re-selecting it is a no-op). */}
-                  {selected === CUSTOM_OPTION ? (
-                    <option value={CUSTOM_OPTION}>
-                      {messages.toolPanelAggregateCustomLabel()}
-                    </option>
-                  ) : null}
-                </select>
+                />
               </div>
             );
           })}
diff --git a/packages/ui/grid.css b/packages/ui/grid.css
index 51dc54d3..05b5089c 100644
--- a/packages/ui/grid.css
+++ b/packages/ui/grid.css
@@ -1119,17 +1119,16 @@
     line-height: 1.5;
     color: var(--pretable-text-cell);
   }
-  :where([data-pretable-filter-menu]) select,
   :where([data-pretable-filter-menu]) input[type="text"],
   :where([data-pretable-filter-menu]) input[type="date"],
   :where([data-pretable-filter-menu]) input:not([type]) {
     width: 100%;
     box-sizing: border-box;
-    /* An explicit box, like the tool pane's identical controls: Chrome forces
-       `line-height: normal` on a <select> and ignores what it is given, so a
-       select and an input with the same padding come out different heights —
-       28 and 33 here, a stacked pair a few pixels apart. Both centre their
-       own text vertically once the height is set, so the block padding goes. */
+    /* An explicit box, like the tool pane's identical controls: the operator
+       picker beside these is a kit select with its own fixed block-size, and
+       an input left to its own padding comes out several pixels taller — a
+       stacked pair that does not line up. Both centre their own text
+       vertically once the height is set, so the block padding goes. */
     block-size: 28px;
     padding-inline: 7px;
     border: 1px solid var(--pretable-rule);
@@ -1138,15 +1137,22 @@
     color: var(--pretable-text-cell);
     font: inherit;
   }
+  /* The dialog's operator picker. A kit select: the rule above draws the box
+     for the INPUTS beside it, and the kit rule at the top of this file draws
+     this one's. What is the dialog's own is the size — full width, the 28px
+     the fields beside it stand at, and this dialog's 7px inset rather than
+     the kit's 6px. */
+  :where([data-pretable-filter-operator]) {
+    width: 100%;
+    block-size: 28px;
+    padding-inline: 7px;
+  }
   /* The product's focus ring, not the host page's. Without this the dialog's
      fields keep the UA ring — which takes the CONSUMER's accent-color, so
      tabbing from the pane's copy of these same controls to this one changed
      the ring's colour, width and offset. The declaration the builder rows
      already share. */
-  :where(
-    [data-pretable-filter-menu] select:focus-visible,
-    [data-pretable-filter-menu] input:focus-visible
-  ) {
+  :where([data-pretable-filter-menu] input:focus-visible) {
     outline: 2px solid var(--pretable-focus-ring);
     outline-offset: -2px;
   }
@@ -1782,7 +1788,7 @@
      rules — the grouping block below adds nothing of its own.
      [data-pretable-aggregate-row] (the aggregates block's rows) rides the
      BASE rule only: same box, but nothing in it hovers, drags or takes row
-     focus — its select carries its own states via the filter-field lists. */
+     focus — its picker is a kit select and carries its own states. */
   :where(
     [data-pretable-tool-column-row],
     [data-pretable-tool-group-row],
@@ -1977,18 +1983,20 @@
     color: var(--pretable-text-dim);
   }
 
-  /* The two pickers and the single-value field, in ONE rule: they are the same
-     box, and the difference between "which column", "which operator" and
-     "what value" is the words inside it, not the frame around them.
+  /* The single-value field. NOT a kit control — an <input>, which no kit rule
+     draws — so it keeps the whole box here: the frame, the surface, the ink
+     and the font, at the same 24px the pickers beside it stand at, because
+     the difference between "which column", "which operator" and "what value"
+     is the words inside the box, not the frame around it.
      `flex: 1 1 auto` WITH an explicit `min-inline-size`, which is the pair
-     that makes the wrapping row above work: a <select>'s automatic minimum
-     size is its longest option, so one long header name would hold the row
-     wider than the pane and push the value onto a line of its own no matter
-     how the row wraps. ANY explicit value overrides that automatic minimum,
-     so 24px shrinks and ellipsizes exactly as 0 would — and unlike 0 it does
-     not hand back, on the inline axis, the WCAG 2.5.8 floor the block-size
-     below is claiming. A rule that states a 24px target and then permits a
-     4px-wide one states nothing.
+     that makes the wrapping row above work: a field's automatic minimum size
+     is its content, so one long value would hold the row wider than the pane
+     and push the controls onto a line of their own no matter how the row
+     wraps. ANY explicit value overrides that automatic minimum, so 24px
+     shrinks and ellipsizes exactly as 0 would — and unlike 0 it does not hand
+     back, on the inline axis, the WCAG 2.5.8 floor the block-size is
+     claiming. A rule that states a 24px target and then permits a 4px-wide
+     one states nothing.
      24px is the height this section bought for the join and the add actions,
      so the whole row clears 2.5.8 on every pointer rather than only where a
      coarse-pointer block applies.
@@ -1996,17 +2004,7 @@
      join's longhands: UA stylesheets set their own font on form controls, and
      this rule sets no size of its own, so there is nothing for the shorthand
      to overwrite. */
-  /* [data-pretable-aggregate-row] select (the grouping section's aggregate
-     picker) rides this list and the focus ring below: it is the same box as
-     the builder's pickers, and the shared rule is what keeps the two panes'
-     selects from drifting apart. Appended AFTER the pinned head — the
-     cascade guard anchors on [data-pretable-filter-row-column] leading. */
-  :where(
-    [data-pretable-filter-row-column],
-    [data-pretable-filter-row-operator],
-    input[data-pretable-filter-row-value],
-    [data-pretable-aggregate-row] select
-  ) {
+  :where(input[data-pretable-filter-row-value]) {
     box-sizing: border-box;
     flex: 1 1 auto;
     min-inline-size: 24px;
@@ -2018,6 +2016,25 @@
     color: var(--pretable-text-cell);
     font: inherit;
   }
+  /* The builder's pickers: size and flex participation only — the kit select
+     rule at the top of this file draws the box. `min-inline-size` matters for
+     the same reason it does on the field above: without it the longest option
+     sets the trigger's automatic minimum and one long header name holds the
+     row wider than the pane.
+     [data-pretable-aggregate] (the grouping section's aggregate picker) rides
+     this rule: it is the same 24px flex item as the builder's two, and the
+     shared rule is what keeps the two panes' pickers from drifting apart.
+     Appended AFTER the pinned head — the cascade guard anchors on
+     [data-pretable-filter-row-column] leading. */
+  :where(
+    [data-pretable-filter-row-column],
+    [data-pretable-filter-row-operator],
+    [data-pretable-aggregate]
+  ) {
+    flex: 1 1 auto;
+    min-inline-size: 24px;
+    block-size: 24px;
+  }
 
   /* The set shape's checklist, which is not a field: it takes its own line
      (`flex-basis: 100%` in a wrapping row) because a column of checkboxes
@@ -2066,22 +2083,18 @@
     );
     color: var(--pretable-text-cell);
   }
-  /* One ring for every control in the row, an OUTLINE like every other ring
-     in this file: a box-shadow would spend the one shadow slot these controls
-     might later want for elevation, and whichever declaration lost would lose
-     silently.
+  /* The value field's ring, an OUTLINE like every other ring in this file: a
+     box-shadow would spend the one shadow slot this control might later want
+     for elevation, and whichever declaration lost would lose silently. The
+     two pickers beside it take the KIT select's ring — same declaration, one
+     source — so only the input is named here.
      `input[...-value]`, not the bare attribute: the set shape wears the same
      attribute on a <div> wrapper, which takes no focus. A rule that matched it
      would be inert today and would paint a ring around the whole checklist the
      day anything made that wrapper focusable — a state nobody would have
      designed. The FIELDS are what focus, so the field is what the selector
      names. */
-  :where(
-    [data-pretable-filter-row-column]:focus-visible,
-    [data-pretable-filter-row-operator]:focus-visible,
-    input[data-pretable-filter-row-value]:focus-visible,
-    [data-pretable-aggregate-row] select:focus-visible
-  ) {
+  :where(input[data-pretable-filter-row-value]:focus-visible) {
     outline: 2px solid var(--pretable-focus-ring);
     outline-offset: -2px;
   }
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index b2fa0414..65c16c3e 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -426,6 +426,10 @@ describe("grid.css cascade contract", () => {
       css,
       (s) =>
         s.includes("data-pretable-select]") &&
+        // The caret rule is a DESCENDANT of the trigger and has its own
+        // assertions below; letting it into this bucket would let its
+        // declarations vouch for the trigger's.
+        !s.includes("data-pretable-icon]") &&
         !s.includes("::") &&
         !s.includes(":hover") &&
         !s.includes(":focus") &&
@@ -445,8 +449,32 @@ describe("grid.css cascade contract", () => {
       /font:\s*inherit/,
       /cursor:\s*pointer/,
       /text-align:\s*start/,
+      // The inner spacing is the kit's too, and it is what the sites stop
+      // declaring: 6px between the label and the caret, 6px inside the frame.
+      /gap:\s*6px/,
+      /padding-inline:\s*6px/,
     ])
       expect(body).toMatch(decl);
+    // The label ellipsizes rather than widening the trigger, and the caret
+    // never shrinks. Both are what makes a picker survive a long option in a
+    // 264px pane, and neither is visible from the trigger rule alone.
+    const label = rulesSelecting(css, (s) =>
+      s.includes("data-pretable-select-label]"),
+    );
+    expect(label.length, "no kit select label rule").toBeGreaterThan(0);
+    const labelBody = label.map((m) => m[2]).join("");
+    expect(labelBody).toMatch(/text-overflow:\s*ellipsis/);
+    expect(labelBody).toMatch(/min-inline-size:\s*0/);
+    const caret = rulesSelecting(
+      css,
+      (s) =>
+        s.includes("data-pretable-select]") &&
+        s.includes("data-pretable-icon]"),
+    );
+    expect(caret.length, "no kit select caret rule").toBeGreaterThan(0);
+    const caretBody = caret.map((m) => m[2]).join("");
+    expect(caretBody).toMatch(/flex:\s*none/);
+    expect(caretBody).toMatch(/color:\s*var\(--pretable-text-dim\)/);
     // Ring and disabled ink in the state section, like the buttons.
     const state = rulesSelecting(
       css,
@@ -481,15 +509,6 @@ describe("grid.css cascade contract", () => {
       .map((m) => m[2])
       .join("");
     expect(activeOption).toMatch(/background:\s*var\(--pretable-bg-hover\)/);
-    // No enum-only list rule survives; the editor rides the kit rules.
-    expect(
-      rulesSelecting(
-        css,
-        (s) =>
-          s.includes("data-pretable-enum-listbox]") ||
-          s.includes("data-pretable-enum-option]"),
-      ).length,
-    ).toBe(0);
     // Forced colours: the selected option is the system's pair.
     const forced = forcedColorsBlock(css);
     expect(
@@ -602,7 +621,7 @@ describe("grid.css cascade contract", () => {
         for (const owned of forbidden) {
           expect(
             body,
-            `"${selector.trim()}" redeclares ${owned} — the kit button rule owns it`,
+            `"${selector.trim()}" redeclares ${owned} — the kit rule owns it`,
           ).not.toMatch(owned);
         }
       }
@@ -693,6 +712,11 @@ describe("grid.css cascade contract", () => {
       ":where([data-pretable-button], [data-pretable-icon-button])",
     );
     expect(kitBase, "no kit base rule").toBeGreaterThan(-1);
+    // The select trigger's shared box is a SECOND kit base rule, and the four
+    // picker sites rest on the same ordering. Anchoring only on the buttons'
+    // would let the select rule move below its sites unnoticed.
+    const kitSelectBase = css.indexOf(":where([data-pretable-select])");
+    expect(kitSelectBase, "no kit select base rule").toBeGreaterThan(-1);
 
     const positions = (attr: string) => {
       const out: number[] = [];
@@ -700,14 +724,22 @@ describe("grid.css cascade contract", () => {
         out.push(at);
       return out;
     };
-    const sitePositions = PUSH_BUTTON_SITES.flatMap((site) =>
-      positions(`data-pretable-${site}]`),
+    const sitePositions = [...PUSH_BUTTON_SITES, ...SELECT_SITES].flatMap(
+      (site) => positions(`data-pretable-${site}]`),
     );
     expect(sitePositions.length, "no site rules at all").toBeGreaterThan(0);
     expect(
       kitBase,
       "the kit's shared box comes after a site rule, which then cannot win at equal specificity",
     ).toBeLessThan(Math.min(...sitePositions));
+    expect(
+      kitSelectBase,
+      "the kit select's shared box comes after a site rule, which then cannot win at equal specificity",
+    ).toBeLessThan(
+      Math.min(
+        ...SELECT_SITES.flatMap((site) => positions(`data-pretable-${site}]`)),
+      ),
+    );
 
     // Measured against the site rules OUTSIDE the media blocks: the coarse
     // and forced-colours blocks at the end of the layer are the file's last
@@ -731,6 +763,20 @@ describe("grid.css cascade contract", () => {
       disabled,
       "the kit disabled treatment precedes a site rule, which can then overwrite it",
     ).toBeGreaterThan(lastSite);
+
+    // The select trigger's states, held to the same order for the same reason.
+    const selectRing = css.search(/\[data-pretable-select\]:focus-visible/);
+    expect(selectRing, "no kit select focus-visible rule").toBeGreaterThan(-1);
+    expect(
+      selectRing,
+      "the kit select ring precedes a site rule, which can then overwrite it",
+    ).toBeGreaterThan(lastSite);
+    const selectDisabled = css.search(/\[data-pretable-select\]:disabled/);
+    expect(selectDisabled, "no kit select disabled rule").toBeGreaterThan(-1);
+    expect(
+      selectDisabled,
+      "the kit select disabled treatment precedes a site rule, which can then overwrite it",
+    ).toBeGreaterThan(lastSite);
   });
 
   test("a focused cell draws its ring with `outline`, never `box-shadow`", () => {
@@ -1870,49 +1916,87 @@ describe("grid.css cascade contract", () => {
     });
 
     test("the leaf row's fields can shrink inside the pane", () => {
-      // A <select>'s automatic minimum size is its longest option. With the
-      // default `min-inline-size: auto` one long header name holds the row
-      // wider than the 264px pane — the row still wraps, but every wrap
-      // leaves one control alone on its line, which is the layout the
-      // wrapping decision exists to avoid. `flex: 1 1 auto` alone does not
-      // fix it; the automatic minimum is what overrides the shrink.
-      // The BOX rule, not merely a rule that names the field: the focus ring
-      // below groups the same attributes, and an earlier draft of this guard
+      // A control's automatic minimum size is its content — for a picker, its
+      // longest option. With the default `min-inline-size: auto` one long
+      // header name holds the row wider than the 264px pane — the row still
+      // wraps, but every wrap leaves one control alone on its line, which is
+      // the layout the wrapping decision exists to avoid. `flex: 1 1 auto`
+      // alone does not fix it; the automatic minimum is what overrides the
+      // shrink.
+      //
+      // TWO rules now, not one: the two pickers are kit selects and take
+      // their box from the kit rule, so their site rule carries only the
+      // size and the flex participation; the value field is an <input>, which
+      // no kit rule draws, so it keeps the whole box. Both are held to the
+      // same shrink contract here — dropping either attribute out of its rule
+      // leaves a control that cannot shrink in a 264px pane.
+      // The BOX rules, not merely rules that name the field: the focus ring
+      // below names the same attribute, and an earlier draft of this guard
       // let the operator picker fall out of the box rule entirely while the
       // ring alone kept every assertion green.
-      const boxRules = rulesSelecting(
-        strippedCss(),
+      const css = strippedCss();
+      const pickerRules = rulesSelecting(
+        css,
         (sel) =>
           sel.includes("data-pretable-filter-row-column") &&
           !sel.includes(":focus"),
       );
-      expect(boxRules, "no leaf-row field box rule").toHaveLength(1);
-      const [, selector, fields] = boxRules[0]!;
-      // All three fields share it. A field dropped from the list keeps its
-      // attribute (the ring still names it) and loses its border, height and
-      // shrink — visibly a naked UA control in the pane.
+      expect(pickerRules, "no leaf-row picker box rule").toHaveLength(1);
+      const [, pickerSelector, pickers] = pickerRules[0]!;
+      // Both pickers share it, and so does the grouping section's aggregate
+      // picker — one rule is what keeps the two panes from drifting.
       for (const attr of [
         "data-pretable-filter-row-operator",
-        "data-pretable-filter-row-value",
+        "data-pretable-aggregate",
       ]) {
         expect(
-          selector,
-          `[${attr}] is not in the leaf row's shared box rule`,
+          pickerSelector,
+          `[${attr}] is not in the leaf row's shared picker rule`,
         ).toContain(attr);
       }
-      // An EXPLICIT minimum is what overrides a <select>'s automatic
-      // longest-option minimum, and any value does that — so this one is also
-      // held to the section's 24px floor. `min-inline-size: 0` shrinks
-      // identically while permitting a 4px-wide target, which would make the
-      // 2.5.8 claim the block-size makes true on one axis and false on the
-      // other.
+      const fieldRules = rulesSelecting(
+        css,
+        (sel) =>
+          sel.includes("input[data-pretable-filter-row-value]") &&
+          !sel.includes(":focus"),
+      );
+      expect(fieldRules, "no leaf-row value field box rule").toHaveLength(1);
+      const field = fieldRules[0]![2];
+
+      // An EXPLICIT minimum is what overrides the automatic longest-content
+      // minimum, and any value does that — so this one is also held to the
+      // section's 24px floor. `min-inline-size: 0` shrinks identically while
+      // permitting a 4px-wide target, which would make the 2.5.8 claim the
+      // block-size makes true on one axis and false on the other.
+      for (const [what, body] of [
+        ["pickers", pickers],
+        ["value field", field],
+      ] as const) {
+        expect(
+          body,
+          `the ${what} need an explicit min-inline-size of at least 24px: 0 shrinks the same way but gives back the WCAG 2.5.8 floor on the inline axis`,
+        ).toMatch(/min-inline-size:\s*(2[4-9]|[3-9]\d|\d{3,})px/);
+        expect(body, `the ${what} do not flex`).toMatch(/flex:\s*1 1 auto/);
+        expect(body, `the ${what} are not 24px tall`).toMatch(
+          /block-size:\s*24px/,
+        );
+      }
+      // The field's own box-sizing; the pickers take the kit rule's.
+      expect(field).toMatch(/box-sizing:\s*border-box/);
       expect(
-        fields,
-        "the fields need an explicit min-inline-size of at least 24px: 0 shrinks the same way but gives back the WCAG 2.5.8 floor on the inline axis",
-      ).toMatch(/min-inline-size:\s*(2[4-9]|[3-9]\d|\d{3,})px/);
-      expect(fields).toMatch(/flex:\s*1 1 auto/);
-      expect(fields).toMatch(/block-size:\s*24px/);
-      expect(fields).toMatch(/box-sizing:\s*border-box/);
+        rulesSelecting(
+          css,
+          (sel) =>
+            sel.includes("data-pretable-select]") &&
+            !sel.includes("data-pretable-icon]") &&
+            !sel.includes("::") &&
+            !sel.includes(":hover") &&
+            !sel.includes(":focus") &&
+            !sel.includes(":disabled"),
+        )
+          .map((m) => m[2])
+          .join(""),
+      ).toMatch(/box-sizing:\s*border-box/);
     });
 
     test("the set shape's checklist takes its own line, and rings by token", () => {

From 11afd4bc0514d94450e500c850228e4d7983992d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:26:55 -0700
Subject: [PATCH 15/27] fix(ui,react): the select bracket anchor matches the
 base rule, not the caret

The anchor was a prefix match that the caret rule also satisfied, so the
ordering guard could not fail (mutation-checked by moving the base rule
below the builder pickers). Comments that still described native-select
substitution now describe what the kit picker does; the pane-width floor's
rationale says what it was measured against; the label helper lives in one
place; the override test checks the option count it records.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../__tests__/components-override.test.tsx    |  7 ++++++
 .../src/__tests__/filter-builder.test.tsx     | 24 +++++++++++--------
 .../__tests__/filter-menu-surface.test.tsx    | 20 ++++++++--------
 .../react/src/__tests__/select-helpers.ts     | 13 ++++++++++
 .../tool-panel-aggregates-picker.test.tsx     | 23 +++++++-----------
 packages/react/src/filter-menu/FilterMenu.tsx |  8 +++----
 .../react/src/filter-menu/filter-operators.ts |  8 +++----
 packages/react/src/pretable-surface.tsx       |  4 ++--
 .../src/tool-panel/filters/FilterRow.tsx      |  8 +++----
 packages/react/src/tool-panel/pane-resize.ts  | 16 +++++++++----
 packages/ui/src/__tests__/css-cascade.test.ts |  2 +-
 11 files changed, 79 insertions(+), 54 deletions(-)

diff --git a/packages/react/src/__tests__/components-override.test.tsx b/packages/react/src/__tests__/components-override.test.tsx
index 394a65bd..4ef4cd15 100644
--- a/packages/react/src/__tests__/components-override.test.tsx
+++ b/packages/react/src/__tests__/components-override.test.tsx
@@ -285,6 +285,13 @@ describe("components on the surface", () => {
     )!;
     expect(column).toHaveAttribute("data-mine-select", "filter-row-column");
     expect(column).toHaveAttribute("data-mine-value", "name");
+    // The override receives every filterable column in the fixture, not a
+    // truncated or empty list — a site that handed it nothing would still
+    // pass the checks above.
+    expect(column).toHaveAttribute(
+      "data-mine-option-count",
+      String(columns.length),
+    );
     // Nothing that identified this picker before stops identifying it, and
     // the kit's own attribute is gone with the kit component.
     expect(column).not.toHaveAttribute("data-pretable-select");
diff --git a/packages/react/src/__tests__/filter-builder.test.tsx b/packages/react/src/__tests__/filter-builder.test.tsx
index a4c44083..de16fcc9 100644
--- a/packages/react/src/__tests__/filter-builder.test.tsx
+++ b/packages/react/src/__tests__/filter-builder.test.tsx
@@ -20,7 +20,12 @@ import {
 import { FiltersSection } from "../tool-panel/filters/FiltersSection";
 import { JoinControl } from "../tool-panel/filters/JoinControl";
 import { defaultMessages } from "../messages";
-import { chooseOption, readOptions, selectValue } from "./select-helpers";
+import {
+  chooseOption,
+  readOptions,
+  selectLabel,
+  selectValue,
+} from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -533,10 +538,10 @@ describe("FilterRow", () => {
   /* A leaf seeded from an APPLIED filter — `fromColumnFilter`, which is how
      the section will build every row it did not just add — can carry an
      operator the column's `filterOperators` prunes. `onColumnChange` never
-     sees that path. A <select> whose value matches no option displays
-     something else, so the row would name a filter it is not applying, and
-     the real one would be unreachable (choosing what is already displayed
-     fires no change event). `menuOperators` is the module's answer. */
+     sees that path. Without the applied operator in the list, the picker
+     would show a bare identifier for a filter the row IS applying, and the
+     real one would be unreachable (choosing what is already displayed fires
+     no change event). `menuOperators` is the module's answer. */
   it("names the applied operator even when the column prunes it", () => {
     const { container } = render(
       <Leaf
@@ -549,13 +554,12 @@ describe("FilterRow", () => {
     // The one assertion that catches the silent substitution: what the picker
     // holds and what it DISPLAYS are the same operator. The trigger renders
     // the OPTION's label when the value matches one, and the bare value when
-    // it does not, so reading the label span is the same question a native
-    // <select>'s `options[selectedIndex]` used to answer.
+    // it does not.
     expect(selectValue(select)).toBe("equals");
     const listed = readOptions(select);
-    expect(
-      select.querySelector("[data-pretable-select-label]")?.textContent,
-    ).toBe(listed.labels[listed.values.indexOf("equals")]);
+    expect(selectLabel(select)).toBe(
+      listed.labels[listed.values.indexOf("equals")],
+    );
     expect(options(select)).toContain("equals");
     // Written out, not `toEqual(menuOperators(...))`: comparing the component
     // against the very function it calls passes whenever both are wrong. The
diff --git a/packages/react/src/__tests__/filter-menu-surface.test.tsx b/packages/react/src/__tests__/filter-menu-surface.test.tsx
index f8943dd8..e2df4ecb 100644
--- a/packages/react/src/__tests__/filter-menu-surface.test.tsx
+++ b/packages/react/src/__tests__/filter-menu-surface.test.tsx
@@ -16,7 +16,7 @@ import {
   type PretableSurfaceProps,
 } from "../pretable-surface";
 import type { PretableColumn } from "../types";
-import { readOptions, selectValue } from "./select-helpers";
+import { readOptions, selectLabel, selectValue } from "./select-helpers";
 
 afterEach(() => {
   cleanup();
@@ -157,11 +157,11 @@ describe("PretableSurface — built-in filter funnel", () => {
   /* A column whose `filterOperators` prunes the operator its filter is
      ACTUALLY using. The menu hydrates from the applied filter
      (`fromColumnFilter`), so the draft can hold an operator the permitted list
-     does not contain — and a <select> whose value matches no option displays a
-     different one. The menu would then name a filter it is not applying, and
-     the applied one would be unreachable: choosing what is already displayed
-     fires no change event. `menuOperators` is the module's answer, and the
-     tool panel's leaf row reaches the same case by the same route. */
+     does not contain — and without the applied operator in the list, the
+     picker would show a bare identifier for a filter the menu IS applying,
+     and the user could not re-choose it. `menuOperators` is the module's
+     answer, and the tool panel's leaf row reaches the same case by the same
+     route. */
   it("keeps naming the applied operator when the column prunes it", () => {
     const view = renderSurface({
       state: {
@@ -181,11 +181,11 @@ describe("PretableSurface — built-in filter funnel", () => {
     // What it HOLDS and what it DISPLAYS are the same operator — the
     // assertion the value check alone does not make. The trigger shows the
     // OPTION's label when the value names one and the bare value when it does
-    // not, which is the substitution a native <select> hid.
+    // not.
     const listed = readOptions(select);
-    expect(
-      select.querySelector("[data-pretable-select-label]")?.textContent,
-    ).toBe(listed.labels[listed.values.indexOf("equals")]);
+    expect(selectLabel(select)).toBe(
+      listed.labels[listed.values.indexOf("equals")],
+    );
     // The permitted pair plus the applied operator, in the type's own order;
     // everything else the column pruned stays pruned.
     expect(listed.values).toEqual(["contains", "equals", "isEmpty"]);
diff --git a/packages/react/src/__tests__/select-helpers.ts b/packages/react/src/__tests__/select-helpers.ts
index af875b8e..8769d0e1 100644
--- a/packages/react/src/__tests__/select-helpers.ts
+++ b/packages/react/src/__tests__/select-helpers.ts
@@ -48,3 +48,16 @@ export function readOptions(trigger: HTMLElement): {
 export function selectValue(trigger: HTMLElement): string | null {
   return trigger.getAttribute("data-pretable-value");
 }
+
+/**
+ * What the trigger DISPLAYS, from the label span's text — as opposed to
+ * `selectValue`, which reads what it HOLDS. The trigger renders the matching
+ * option's label when the value names one, and the bare value when it does
+ * not, so comparing this against the list's own label for that value is how
+ * a caller catches a value that has silently fallen out of the option set.
+ */
+export function selectLabel(trigger: HTMLElement): string | null {
+  return (
+    trigger.querySelector("[data-pretable-select-label]")?.textContent ?? null
+  );
+}
diff --git a/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx b/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
index 1e01dfa8..1d607b07 100644
--- a/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
+++ b/packages/react/src/__tests__/tool-panel-aggregates-picker.test.tsx
@@ -13,7 +13,12 @@ import { defaultMessages } from "../messages";
 import { PretableSurface } from "../pretable-surface";
 import { GroupingSection } from "../tool-panel/grouping";
 import type { GroupingSectionColumn } from "../tool-panel/grouping";
-import { chooseOption, readOptions, selectValue } from "./select-helpers";
+import {
+  chooseOption,
+  readOptions,
+  selectLabel,
+  selectValue,
+} from "./select-helpers";
 
 afterEach(cleanup);
 
@@ -108,16 +113,6 @@ function optionLabels(picker: HTMLElement): string[] {
   return readOptions(picker).labels;
 }
 
-/** The label the picker offers for one option value, read from the open list. */
-function optionLabelFor(
-  picker: HTMLElement,
-  value: string,
-): string | undefined {
-  const listed = readOptions(picker);
-  const at = listed.values.indexOf(value);
-  return at < 0 ? undefined : listed.labels[at];
-}
-
 /**
  * Structural fakes for the pure select-state tests — no grid, no derivation
  * flips, same shape the group-by tests use. Stable state objects:
@@ -183,7 +178,7 @@ describe("aggregate picker over a real grouped grid", () => {
     // No override yet: the picker shows the explicit Default face, carrying
     // the declared aggregate's display name (spec decision 4).
     expect(selectValue(picker)).toBe("default");
-    expect(optionLabelFor(picker, "default")).toBe("Default (Average)");
+    expect(selectLabel(picker)).toBe("Default (Average)");
 
     chooseOption(picker, "sum");
     await waitFor(() => {
@@ -246,7 +241,7 @@ describe("aggregate picker select state (structural fakes, zero flips)", () => {
     ]);
     // Both faces exist side by side in one vocabulary: the Default option
     // names the declared value it would restore.
-    expect(optionLabelFor(cleanPicker, "default")).toBe("Default (Sum)");
+    expect(selectLabel(cleanPicker)).toBe("Default (Sum)");
   });
 
   it("an override to a consumer-written aggregator OBJECT shows a Custom option", () => {
@@ -259,7 +254,7 @@ describe("aggregate picker select state (structural fakes, zero flips)", () => {
     });
     const picker = pickerFor(container, "qty");
     expect(selectValue(picker)).toBe("custom");
-    expect(optionLabelFor(picker, "custom")).toBe("Custom");
+    expect(selectLabel(picker)).toBe("Custom");
 
     // DISABLED, not merely reflect-only: the entry exists so the state is
     // legible, and the kit list marks it inert rather than leaving a decoy
diff --git a/packages/react/src/filter-menu/FilterMenu.tsx b/packages/react/src/filter-menu/FilterMenu.tsx
index 7e0eb90e..e2ecfc58 100644
--- a/packages/react/src/filter-menu/FilterMenu.tsx
+++ b/packages/react/src/filter-menu/FilterMenu.tsx
@@ -198,10 +198,10 @@ export function FilterMenu({
   const shape = operatorValueShape(draft.operator);
   // `menuOperators`, not `operatorsForType`: the draft hydrates from the
   // APPLIED filter, so it can hold an operator this column's
-  // `filterOperators` prunes — and a <select> whose value matches no option
-  // displays a different one, naming a filter the grid is not applying and
-  // leaving the real one unreachable. The tool panel's leaf row reaches the
-  // same case by the same route.
+  // `filterOperators` prunes — and without the applied operator in the list,
+  // the picker would show a bare identifier for a filter the grid IS
+  // applying, and the user could not re-choose it. The tool panel's leaf row
+  // reaches the same case by the same route.
   const operators = menuOperators(type, draft.operator, allowedOperators);
   const inputType = type === "date" ? "date" : "text";
   const numericProps =
diff --git a/packages/react/src/filter-menu/filter-operators.ts b/packages/react/src/filter-menu/filter-operators.ts
index fc1be7e0..f99f2b7b 100644
--- a/packages/react/src/filter-menu/filter-operators.ts
+++ b/packages/react/src/filter-menu/filter-operators.ts
@@ -79,10 +79,10 @@ export function operatorsForType(
 
 /**
  * The operators the select renders: the permitted set, plus whichever operator
- * the filter currently applies. A `<select>` whose value matches no option
- * silently displays the first one, so pruning the applied operator would leave
- * the menu naming an operator the filter is not using — and that named operator
- * unreachable, since choosing what is already displayed fires no change event.
+ * the filter currently applies. Without the applied operator in the list, the
+ * picker would show a bare identifier for a filter the grid IS applying — and
+ * that operator would stay unreachable, since choosing what is already
+ * displayed fires no change event.
  */
 export function menuOperators(
   type: ColumnType,
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index 6bc82309..97b45621 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -5112,8 +5112,8 @@ export function PretableSurface<
   // Focus restoration when a header popover closes.
   //
   // `useHeaderPopover` closes on Escape from a document-level listener and does
-  // not restore focus, and FilterMenu focuses its own `<select>` on open — so
-  // Escape from a keyboard-opened filter left `document.activeElement` on a
+  // not restore focus, and FilterMenu focuses its own operator picker on open —
+  // so Escape from a keyboard-opened filter left `document.activeElement` on a
   // node that had just been unmounted, i.e. on `<body>`. The user was outside
   // the grid with no way back except Tab. (ColumnMenu restores to its anchor
   // itself; this then agrees with it rather than fighting it.)
diff --git a/packages/react/src/tool-panel/filters/FilterRow.tsx b/packages/react/src/tool-panel/filters/FilterRow.tsx
index c4b6e91a..1e0ae905 100644
--- a/packages/react/src/tool-panel/filters/FilterRow.tsx
+++ b/packages/react/src/tool-panel/filters/FilterRow.tsx
@@ -187,10 +187,10 @@ export function FilterRow({
   const groupedAway = !hidden && column?.groupedAway === true;
 
   // `menuOperators`, not `operatorsForType`: the render list must contain the
-  // operator the leaf is actually holding. A <select> whose value matches no
-  // option displays a different one, so the row would NAME a filter it is not
-  // applying — and the real one would be unreachable, since choosing what is
-  // already displayed fires no change event.
+  // operator the leaf is actually holding. Without the applied operator in
+  // the list, the picker would show a bare identifier for a filter the row
+  // IS applying — and the real one would be unreachable, since choosing what
+  // is already displayed fires no change event.
   //
   // `onColumnChange` below cannot cover this. It guards the one path it can
   // see; a leaf seeded from an applied filter (`fromColumnFilter`, which is
diff --git a/packages/react/src/tool-panel/pane-resize.ts b/packages/react/src/tool-panel/pane-resize.ts
index 40b344b4..e9290202 100644
--- a/packages/react/src/tool-panel/pane-resize.ts
+++ b/packages/react/src/tool-panel/pane-resize.ts
@@ -34,11 +34,17 @@ export interface PaneWidthBounds {
  * Measured (2026-08-30, Chromium via the `fixtures/tool-panel-sections`
  * route) against the filters section's narrowest usable row, per spec A4:
  * the filter row wraps, so its floor is set by the widest control that must
- * fit a wrapped line alone — the operator `<select>`, whose max-content
- * width over its longest option ("does not contain", text vocabulary) is
- * 161px. On its wrapped line the control receives `pane − 25px` (4px row
- * padding ×2 + 8px section padding ×2 + 1px pane border), so the narrowest
- * pane that renders every operator label unclipped is 161 + 25 = 186px.
+ * fit a wrapped line alone — at the time, the operator `<select>`, whose
+ * max-content width over its longest option ("does not contain", text
+ * vocabulary) was 161px, giving 161 + 25 = 186px on its wrapped line (4px
+ * row padding ×2 + 8px section padding ×2 + 1px pane border).
+ *
+ * The operator picker is now a kit `Select` button: its label ellipsizes
+ * rather than growing the control to fit the longest option, so this floor
+ * no longer bounds "does the longest option fit" — it bounds legibility of
+ * an ellipsized label instead. The number is kept as-is pending a browser
+ * re-measurement against the kit picker; re-measure if the floor is ever
+ * revisited.
  */
 export const PANE_MIN_WIDTH_PX = 186;
 
diff --git a/packages/ui/src/__tests__/css-cascade.test.ts b/packages/ui/src/__tests__/css-cascade.test.ts
index 65c16c3e..d8a66791 100644
--- a/packages/ui/src/__tests__/css-cascade.test.ts
+++ b/packages/ui/src/__tests__/css-cascade.test.ts
@@ -715,7 +715,7 @@ describe("grid.css cascade contract", () => {
     // The select trigger's shared box is a SECOND kit base rule, and the four
     // picker sites rest on the same ordering. Anchoring only on the buttons'
     // would let the select rule move below its sites unnoticed.
-    const kitSelectBase = css.indexOf(":where([data-pretable-select])");
+    const kitSelectBase = css.search(/:where\(\[data-pretable-select\]\)\s*\{/);
     expect(kitSelectBase, "no kit select base rule").toBeGreaterThan(-1);
 
     const positions = (attr: string) => {

From 157d885589fe43375e38b9453c762e8d9a6e5614 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:32:19 -0700
Subject: [PATCH 16/27] docs(react): the pruned-operator comments describe the
 kit picker, not a select

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/__tests__/filter-builder.test.tsx | 4 ++--
 packages/react/src/filter-menu/filter-operators.ts   | 6 +++---
 packages/react/src/tool-panel/filters/FilterRow.tsx  | 4 ++--
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/react/src/__tests__/filter-builder.test.tsx b/packages/react/src/__tests__/filter-builder.test.tsx
index de16fcc9..71d41bf4 100644
--- a/packages/react/src/__tests__/filter-builder.test.tsx
+++ b/packages/react/src/__tests__/filter-builder.test.tsx
@@ -540,8 +540,8 @@ describe("FilterRow", () => {
      operator the column's `filterOperators` prunes. `onColumnChange` never
      sees that path. Without the applied operator in the list, the picker
      would show a bare identifier for a filter the row IS applying, and the
-     real one would be unreachable (choosing what is already displayed fires
-     no change event). `menuOperators` is the module's answer. */
+     applied operator would be unreachable simply because it is not in the
+     list. `menuOperators` is the module's answer. */
   it("names the applied operator even when the column prunes it", () => {
     const { container } = render(
       <Leaf
diff --git a/packages/react/src/filter-menu/filter-operators.ts b/packages/react/src/filter-menu/filter-operators.ts
index f99f2b7b..6e90596b 100644
--- a/packages/react/src/filter-menu/filter-operators.ts
+++ b/packages/react/src/filter-menu/filter-operators.ts
@@ -80,9 +80,9 @@ export function operatorsForType(
 /**
  * The operators the select renders: the permitted set, plus whichever operator
  * the filter currently applies. Without the applied operator in the list, the
- * picker would show a bare identifier for a filter the grid IS applying — and
- * that operator would stay unreachable, since choosing what is already
- * displayed fires no change event.
+ * picker would show a bare identifier for a filter the grid IS applying, and
+ * the applied operator would be unreachable simply because it is not in the
+ * list.
  */
 export function menuOperators(
   type: ColumnType,
diff --git a/packages/react/src/tool-panel/filters/FilterRow.tsx b/packages/react/src/tool-panel/filters/FilterRow.tsx
index 1e0ae905..23e3cfff 100644
--- a/packages/react/src/tool-panel/filters/FilterRow.tsx
+++ b/packages/react/src/tool-panel/filters/FilterRow.tsx
@@ -189,8 +189,8 @@ export function FilterRow({
   // `menuOperators`, not `operatorsForType`: the render list must contain the
   // operator the leaf is actually holding. Without the applied operator in
   // the list, the picker would show a bare identifier for a filter the row
-  // IS applying — and the real one would be unreachable, since choosing what
-  // is already displayed fires no change event.
+  // IS applying, and the applied operator would be unreachable simply
+  // because it is not in the list.
   //
   // `onColumnChange` below cannot cover this. It guards the one path it can
   // see; a leaf seeded from an applied filter (`fromColumnFilter`, which is

From 3368b2843109d2a008d377455f2602079f59fc49 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:36:24 -0700
Subject: [PATCH 17/27] feat(react): export PretableSelect and the Select slot
 type

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/react.api.md                  | 30 +++++++++++++++++++-
 packages/react/src/components/select.tsx     |  8 ++++--
 packages/react/src/public_api.ts             |  6 ++++
 type-tests/react/components-select.types.tsx | 19 ++++++++-----
 4 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index 0924c00b..e56cf360 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -425,7 +425,7 @@ export type PretableBodyStateKind = "loading" | "empty" | "error" | "error-strip
 export type PretableBuiltinAggregate<TValue, TType extends PretableColumnType> = "count" | (TType extends "number" ? NonNullable<TValue> extends number ? "sum" | "avg" | "min" | "max" : never : TType extends "date" ? NonNullable<TValue> extends string ? "min" | "max" : never : never);
 
 // @public
-export type PretableBuiltInButtonSite = "filter-add" | "add-group" | "expand-all" | "collapse-all" | "filter-clear" | "tool-reset" | "filter-funnel" | "column-menu-button" | "tool-row-menu-button" | "chip-remove" | "filter-row-remove" | "tool-group-remove";
+export type PretableBuiltInButtonSite = "filter-add" | "add-group" | "expand-all" | "collapse-all" | "filter-clear" | "tool-reset" | "filter-funnel" | "column-menu-button" | "tool-row-menu-button" | "chip-remove" | "filter-row-remove" | "tool-group-remove" | "filter-operator" | "filter-row-column" | "filter-row-operator" | "aggregate";
 
 // @public
 export const PretableButton: ForwardRefExoticComponent<PretableButtonProps & RefAttributes<HTMLButtonElement>>;
@@ -846,6 +846,7 @@ export interface PretableCompatibleAggregator<TRow extends object, TValue, TOutp
 export interface PretableComponents {
     readonly Button?: PretableButtonComponent;
     readonly IconButton?: PretableIconButtonComponent;
+    readonly Select?: PretableSelectComponent;
 }
 
 // @public
@@ -2003,6 +2004,12 @@ export interface PretableRowUpdate<TRow extends object, TRowId extends PretableR
     readonly id: TRowId;
 }
 
+// @public
+export const PretableSelect: ForwardRefExoticComponent<PretableSelectProps & RefAttributes<HTMLButtonElement>>;
+
+// @public
+export type PretableSelectComponent = ComponentType<PretableSelectProps & RefAttributes<HTMLButtonElement>>;
+
 // @public
 export interface PretableSelectionFor<TColumns, TRowId extends PretableRowId = string> {
     // (undocumented)
@@ -2019,6 +2026,27 @@ export interface PretableSelectionState {
     ranges: PretableCellRange[];
 }
 
+// @public
+export interface PretableSelectOption {
+    // (undocumented)
+    readonly disabled?: boolean;
+    // (undocumented)
+    readonly label: ReactNode;
+    // (undocumented)
+    readonly value: string;
+}
+
+// @public
+export interface PretableSelectProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "value" | "onChange" | "aria-label" | "children"> {
+    "aria-label": string;
+    // (undocumented)
+    onChange: (value: string) => void;
+    // (undocumented)
+    options: readonly PretableSelectOption[];
+    site?: PretableButtonSite;
+    value: string;
+}
+
 // @public
 export interface PretableSetValueInput<TRow extends object, TValue> {
     // (undocumented)
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index 4abb9d92..ec64fa1a 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -20,6 +20,7 @@ import {
   useState,
   type ButtonHTMLAttributes,
   type ReactElement,
+  type ReactNode,
 } from "react";
 
 import { warnOnce } from "../dev-warn";
@@ -31,7 +32,6 @@ import {
   Listbox,
   listboxOptionId,
   useListboxKeys,
-  type ListboxOption,
 } from "./listbox";
 
 /**
@@ -41,7 +41,11 @@ import {
  *
  * @public
  */
-export type PretableSelectOption = ListboxOption;
+export interface PretableSelectOption {
+  readonly value: string;
+  readonly label: ReactNode;
+  readonly disabled?: boolean;
+}
 
 /**
  * Props for {@link PretableSelect}.
diff --git a/packages/react/src/public_api.ts b/packages/react/src/public_api.ts
index 52519e56..68a9c302 100644
--- a/packages/react/src/public_api.ts
+++ b/packages/react/src/public_api.ts
@@ -36,10 +36,16 @@ export type {
   PretableButtonVariant,
   PretableIconButtonProps,
 } from "./components/button";
+export { PretableSelect } from "./components/select";
+export type {
+  PretableSelectOption,
+  PretableSelectProps,
+} from "./components/select";
 export type {
   PretableButtonComponent,
   PretableComponents,
   PretableIconButtonComponent,
+  PretableSelectComponent,
 } from "./components/context";
 
 // Hooks
diff --git a/type-tests/react/components-select.types.tsx b/type-tests/react/components-select.types.tsx
index 6e1f5c37..8b94bd15 100644
--- a/type-tests/react/components-select.types.tsx
+++ b/type-tests/react/components-select.types.tsx
@@ -1,14 +1,12 @@
-// TEMPORARY: imported from source because `@pretable/react` does not export
-// these yet. Task 9 of the SP2 plan switches this to the package.
 import {
   PretableSelect,
+  type PretableBuiltInButtonSite,
+  type PretableButtonSite,
+  type PretableComponents,
+  type PretableSelectComponent,
   type PretableSelectOption,
   type PretableSelectProps,
-} from "../../packages/react/src/components/select";
-import type {
-  PretableBuiltInButtonSite,
-  PretableButtonSite,
-} from "../../packages/react/src/components/button";
+} from "@pretable/react";
 import type { Equal, Expect } from "../shared/assert";
 
 const options: readonly PretableSelectOption[] = [
@@ -101,3 +99,10 @@ export type NameIsRequired = Expect<
 export type SiteIsOpen = Expect<
   Equal<PretableSelectProps["site"], PretableButtonSite | undefined>
 >;
+
+// The built-in satisfies its own slot type, and a replacement is written
+// against `PretableSelectProps` like every other kit component.
+const components: PretableComponents = { Select: PretableSelect };
+void components;
+const slot: PretableSelectComponent = PretableSelect;
+void slot;

From 119d5b8066e75599b9fdd651377266ef19a1920a Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:45:10 -0700
Subject: [PATCH 18/27] fix(react): import Fragment in PretableSelect so it
 renders at all
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`select.tsx` returns a `<>…</>` fragment, but the package builds JSX with
the classic pragma (`pragma: createElement`, `pragmaFrag: Fragment`), so the
missing import made every rendered PretableSelect throw
"Fragment is not defined" and take the whole grid down with it. The vitest
suite could not see this: it transforms JSX with the automatic runtime, which
needs no import.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/src/components/select.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index ec64fa1a..8ed0e7ba 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -12,6 +12,7 @@
  */
 import {
   createElement,
+  Fragment,
   forwardRef,
   useCallback,
   useId,

From cc996b4a547c1e1f2ba6f820d636726ac08266cf Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:51:00 -0700
Subject: [PATCH 19/27] fix(react): document the select members; pin the option
 shape; guard the classic-JSX imports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The five undocumented members of PretableSelectOption/Props now carry
their docs in the API report. PretableSelectOption is pinned to the
internal ListboxOption by TYPE IDENTITY, not two-way assignability — an
optional field added to either side satisfies both assignments and would
have slipped through (mutation-checked with `readonly extra?: string` on
ListboxOption: typecheck fails). A new test walks every shipped .tsx and
demands the createElement / Fragment imports the classic JSX build needs —
the trap that shipped an undefined Fragment in PretableSelect while 1844
unit tests stayed green (mutation-checked by removing the import; the test
fails naming components/select.tsx). No other offenders: every other
shipped .tsx already imports what it calls.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/react/react.api.md                   |   5 -
 .../src/__tests__/jsx-runtime-imports.test.ts | 165 ++++++++++++++++++
 packages/react/src/components/select.tsx      |  23 +++
 3 files changed, 188 insertions(+), 5 deletions(-)
 create mode 100644 packages/react/src/__tests__/jsx-runtime-imports.test.ts

diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index e56cf360..ed781d72 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -2028,20 +2028,15 @@ export interface PretableSelectionState {
 
 // @public
 export interface PretableSelectOption {
-    // (undocumented)
     readonly disabled?: boolean;
-    // (undocumented)
     readonly label: ReactNode;
-    // (undocumented)
     readonly value: string;
 }
 
 // @public
 export interface PretableSelectProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "value" | "onChange" | "aria-label" | "children"> {
     "aria-label": string;
-    // (undocumented)
     onChange: (value: string) => void;
-    // (undocumented)
     options: readonly PretableSelectOption[];
     site?: PretableButtonSite;
     value: string;
diff --git a/packages/react/src/__tests__/jsx-runtime-imports.test.ts b/packages/react/src/__tests__/jsx-runtime-imports.test.ts
new file mode 100644
index 00000000..402956f2
--- /dev/null
+++ b/packages/react/src/__tests__/jsx-runtime-imports.test.ts
@@ -0,0 +1,165 @@
+/**
+ * The classic-JSX-runtime guard.
+ *
+ * `tsdown.config.ts` builds this package with
+ * `transform.jsx = { runtime: "classic", pragma: "createElement",
+ * pragmaFrag: "Fragment" }`. Under that runtime the compiler does NOT inject
+ * anything: `<div/>` becomes a call to whatever `createElement` is in scope,
+ * and `<>…</>` becomes a call to whatever `Fragment` is in scope. A shipped
+ * `.tsx` that renders JSX without importing those names from `"react"`
+ * therefore compiles, type-checks and lints cleanly, and then throws
+ * `Fragment is not defined` in the consumer's browser.
+ *
+ * Vitest cannot see it. The test runner transforms with esbuild's default
+ * AUTOMATIC runtime, which imports `jsx`/`Fragment` from `react/jsx-runtime`
+ * itself — so the unit suite renders the component happily while the built
+ * artifact is broken. That is exactly what happened to `PretableSelect`
+ * (fixed in 119d5b80): 1844 unit tests green, every production render dead.
+ *
+ * So this test reads the SOURCE rather than executing it.
+ *
+ * Heuristic. Comments and string/template literals are stripped first, then:
+ *   - JSX is "a `<` that starts a tag" — `<` followed by a letter or by `>`,
+ *     and NOT preceded by an identifier character, `.`, `)` or `]`. The
+ *     preceding-character rule is what separates JSX (`return <div>`,
+ *     `{cond ? <A/> : null}`) from a generic type argument
+ *     (`useState<DOMRect>`, `forwardRef<HTMLButtonElement, Props>`).
+ *   - a fragment is `<>` or `<Fragment`.
+ * Known blind spots, all of which fail SAFE (a missed file is not a false
+ * accusation, and the mutation check below proves the detector still bites):
+ *   - regex literals are not tracked by the stripper, so a regex containing a
+ *     quote or a slash could desynchronise it;
+ *   - JSX interpolated inside a template literal is stripped away with the
+ *     template;
+ *   - `import * as React from "react"` + `React.createElement` is not
+ *     recognised as an import of the pragma names (this package does not use
+ *     that form, and the classic pragmas here are bare identifiers anyway);
+ *   - a spaced comparison written as `a <b` reads as a tag.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { expect, it } from "vitest";
+
+const SRC = path.join(process.cwd(), "src");
+
+/** Every `.tsx` under `src`, excluding the test directories. */
+async function shippedTsxFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const found: string[] = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "__tests__" || entry.name === "node_modules") continue;
+      found.push(...(await shippedTsxFiles(full)));
+    } else if (entry.name.endsWith(".tsx")) {
+      found.push(full);
+    }
+  }
+  return found.sort();
+}
+
+/**
+ * Blanks out line comments, block comments and string/template literals,
+ * preserving length so nothing shifts. Regex literals are not tracked — see
+ * the blind spots above.
+ */
+function stripCommentsAndStrings(source: string): string {
+  const out = source.split("");
+  let i = 0;
+  const blank = (from: number, to: number) => {
+    for (let k = from; k < to && k < out.length; k += 1) {
+      if (out[k] !== "\n") out[k] = " ";
+    }
+  };
+  while (i < source.length) {
+    const two = source.slice(i, i + 2);
+    if (two === "//") {
+      const end = source.indexOf("\n", i);
+      const stop = end === -1 ? source.length : end;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    if (two === "/*") {
+      const end = source.indexOf("*/", i + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    const quote = source[i];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      let j = i + 1;
+      while (j < source.length) {
+        if (source[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (source[j] === quote) break;
+        j += 1;
+      }
+      blank(i, Math.min(j + 1, source.length));
+      i = Math.min(j + 1, source.length);
+      continue;
+    }
+    i += 1;
+  }
+  return out.join("");
+}
+
+/** Names imported from `"react"` by a named import, across any number of lines. */
+function reactImportedNames(source: string): Set<string> {
+  const names = new Set<string>();
+  const pattern = /import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*["']react["']/g;
+  for (const match of source.matchAll(pattern)) {
+    for (const raw of match[1].split(",")) {
+      const name = raw
+        .trim()
+        .replace(/^type\s+/, "")
+        .split(/\s+as\s+/)[0];
+      if (name) names.add(name.trim());
+    }
+  }
+  return names;
+}
+
+const JSX_TAG = /(?<![A-Za-z0-9_$.\])])<(?:[A-Za-z]|>)/;
+const FRAGMENT = /(?<![A-Za-z0-9_$.\])])(?:<>|<Fragment)/;
+
+it("every shipped .tsx imports the pragmas the classic JSX build calls", async () => {
+  const files = await shippedTsxFiles(SRC);
+  expect(files.length).toBeGreaterThan(10);
+
+  const missingCreateElement: string[] = [];
+  const missingFragment: string[] = [];
+
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    const code = stripCommentsAndStrings(source);
+    const imported = reactImportedNames(source);
+    const rel = path.relative(SRC, file);
+
+    if (JSX_TAG.test(code) && !imported.has("createElement")) {
+      missingCreateElement.push(rel);
+    }
+    if (FRAGMENT.test(code) && !imported.has("Fragment")) {
+      missingFragment.push(rel);
+    }
+  }
+
+  expect({ missingCreateElement, missingFragment }).toEqual({
+    missingCreateElement: [],
+    missingFragment: [],
+  });
+});
+
+it("pins the build config the guard exists for", async () => {
+  const config = await readFile(
+    path.join(process.cwd(), "tsdown.config.ts"),
+    "utf8",
+  );
+  expect(config).toContain('runtime: "classic"');
+  expect(config).toContain('pragma: "createElement"');
+  expect(config).toContain('pragmaFrag: "Fragment"');
+});
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index 8ed0e7ba..01a266e3 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -33,6 +33,7 @@ import {
   Listbox,
   listboxOptionId,
   useListboxKeys,
+  type ListboxOption,
 } from "./listbox";
 
 /**
@@ -43,11 +44,31 @@ import {
  * @public
  */
 export interface PretableSelectOption {
+  /** The string handed back to `onChange` and written to `data-pretable-value`. */
   readonly value: string;
+  /** What the option shows, and what the trigger shows once it is chosen. */
   readonly label: ReactNode;
+  /** Shown, skipped by the keyboard, inert to click. */
   readonly disabled?: boolean;
 }
 
+/**
+ * Type identity, not two-way assignability: an OPTIONAL field added to one
+ * side is assignable to the other and would slip through a pair of
+ * assignments. The conditional-signature trick compares the types themselves.
+ */
+type Equal<TLeft, TRight> =
+  (<T>() => T extends TLeft ? 1 : 2) extends <T>() => T extends TRight ? 1 : 2
+    ? true
+    : false;
+
+// The public option shape IS the list's option shape. Pinned, because a
+// divergence in the internal `ListboxOption` would otherwise leave
+// `PretableSelectOption` quietly describing something consumers do not get.
+// A `false` here is a compile error, and names the field that drifted.
+const _optionShapePin: Equal<PretableSelectOption, ListboxOption> = true;
+void _optionShapePin;
+
 /**
  * Props for {@link PretableSelect}.
  *
@@ -57,9 +78,11 @@ export interface PretableSelectProps extends Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "type" | "value" | "onChange" | "aria-label" | "children"
 > {
+  /** The choices, in display order. */
   options: readonly PretableSelectOption[];
   /** The committed value. Absent from `options`, it renders as its own label. */
   value: string;
+  /** Called with the chosen value, and only when it differs from `value`. */
   onChange: (value: string) => void;
   /**
    * Required. A picker with no accessible name is the icon-button problem

From 339a241c210507c7ae4e6ba02af961bd053eb19d Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 22:54:17 -0700
Subject: [PATCH 20/27] docs: the Select on the Components page; three
 sentences stop saying select

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/content/docs/grid/components.mdx | 89 ++++++++++++++++---
 apps/website/content/docs/grid/filtering.mdx  |  4 +-
 apps/website/content/docs/grid/tool-panel.mdx |  4 +-
 .../docs/__tests__/docs-api-surface.test.ts   |  5 ++
 4 files changed, 87 insertions(+), 15 deletions(-)

diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
index 82b3ada0..e96549f4 100644
--- a/apps/website/content/docs/grid/components.mdx
+++ b/apps/website/content/docs/grid/components.mdx
@@ -1,22 +1,24 @@
 ---
 title: Components
-description: "The kit components the grid renders its own chrome from — Button and IconButton — how to style them, and how to replace either with your own."
+description: "The kit components the grid renders its own chrome from — Button, IconButton and Select — how to style them, and how to replace any of them with your own."
 nav: Grid
 ---
 
 `@pretable/react` renders its own controls from a small component kit, and
 ships those components for you to use and to replace. This page covers the
-first two: `PretableButton` and `PretableIconButton`. Here is a grid whose
-every labelled button is the app's own:
+three that ship today: `PretableButton`, `PretableIconButton` and
+`PretableSelect`. Here is a grid whose every labelled button is the app's
+own:
 
 <Example id="components-button" />
 
 ## The components
 
-Both render `<button type="button">`, always — every grid button is one, and a
-stray submit inside your `<form>` is a real bug class, so `type` is not a prop.
-`className` and `style` pass straight through — the components set neither,
-so yours is the whole value. Both forward their `ref` to the button node.
+All three render `<button type="button">`, always — every grid control is
+one, and a stray submit inside your `<form>` is a real bug class, so `type` is
+not a prop. `className` and `style` pass straight through — the components set
+neither, so yours is the whole value. All three forward their `ref` to the
+button node.
 
 ### Button
 
@@ -38,12 +40,67 @@ accessibility failure discovered later. An empty one warns in development.
 | `aria-label` | `string`             | Required. The accessible name.                                  |
 | `site`       | `PretableButtonSite` | Where in the grid the button is; lands as `data-pretable-site`. |
 
+### Select
+
+A select-only combobox: the kit's answer to the native `<select>`, whose open
+list no theme can reach. The trigger is a `<button role="combobox">`; the list
+is a portalled `role="listbox"` placed against it. `aria-label` is
+**required**, for the same reason it is on `IconButton` — a picker with no
+accessible name reads as an unnamed button — and an empty one warns in
+development. Four grid pickers are this component: the funnel menu's
+[operator](/docs/grid/filtering#the-built-in-menu), the tool panel's
+[filter-builder column and operator](/docs/grid/tool-panel#dom-hooks-and-strings),
+and the grouping section's
+[aggregate picker](/docs/grid/tool-panel#aggregates).
+
+The keyboard is the listbox one: `↓` / `↑` open the list and move through it,
+wrapping at the ends and skipping disabled options; `Home` / `End` jump to the
+first and last enabled option; typing jumps by label prefix, the prefix
+resetting after 500ms of silence; `Enter` or `Space` commits the active option;
+`Escape` closes the list and returns focus to the trigger; `Tab` closes it and
+moves on. `onChange` fires only when the chosen value differs from `value`.
+
+A `disabled` option is shown, skipped by the keyboard and inert to click —
+that is how the aggregate picker shows a consumer-written custom aggregate it
+must never write back. And a `value` that is absent from `options` renders as
+its own label rather than as an empty trigger, so a picker never silently
+disagrees with the state behind it.
+
+```tsx
+import { PretableSelect } from "@pretable/react";
+
+<PretableSelect
+  aria-label="Filter operator"
+  options={[
+    { value: "contains", label: "Contains" },
+    { value: "equals", label: "Equals" },
+    { value: "regex", label: "Matches regex", disabled: true },
+  ]}
+  value={operator}
+  onChange={setOperator}
+/>;
+```
+
+| Prop         | Type                              | Notes                                                                         |
+| ------------ | --------------------------------- | ----------------------------------------------------------------------------- |
+| `options`    | `readonly PretableSelectOption[]` | The choices, in display order. Each is `{ value, label, disabled? }`.         |
+| `value`      | `string`                          | The committed value. Absent from `options`, it renders as its own label.      |
+| `onChange`   | `(value: string) => void`         | Called with the chosen value, and only when it differs from `value`.          |
+| `aria-label` | `string`                          | Required. The accessible name — name what it chooses, e.g. `Filter operator`. |
+| `site`       | `PretableButtonSite`              | Where in the grid the picker is; lands as `data-pretable-site`.               |
+
 ## Styling
 
 The styling channel is the one the whole grid uses: attributes and tokens.
 Every button carries `data-pretable-button` or `data-pretable-icon-button`; a
-labelled button also carries `data-pretable-variant`, and either carries
-`data-pretable-site` when the grid gave it one. The grid's own sites also
+labelled button also carries `data-pretable-variant`, and any of them carries
+`data-pretable-site` when the grid gave it one. A select's trigger carries
+`data-pretable-select` and writes its committed value to
+`data-pretable-value` — a `<button>` has no `.value`, so that attribute is the
+truth a test reads and a selector matches. Its label span is
+`data-pretable-select-label`; the open list is `data-pretable-listbox` with a
+`data-pretable-option` per entry, the keyboard-active one carrying
+`data-active` and the chosen one `aria-selected="true"`. The grid's own sites also
 keep their original attribute (`data-pretable-filter-clear`,
 `data-pretable-tool-reset`, …), so a selector you already wrote keeps matching.
 
@@ -54,6 +111,13 @@ keep their original attribute (`data-pretable-filter-clear`,
 [data-pretable-site="tool-reset"] {
   color: var(--pretable-text-error);
 }
+[data-pretable-select][data-pretable-value="between"] {
+  font-variant-numeric: tabular-nums;
+}
+[data-pretable-option][data-active],
+[data-pretable-option][aria-selected="true"] {
+  background: var(--pretable-surface-hover);
+}
 ```
 
 ## Replacing a component
@@ -61,7 +125,8 @@ keep their original attribute (`data-pretable-filter-clear`,
 Pass `components` to `<PretableSurface>` (or `<Pretable>`) with one entry per
 component type you want to replace. The replacement is used everywhere that
 type appears — the tool panel and the portalled filter dialog for `Button`;
-the header, the tool panel and the group panel for `IconButton` — and
+the header, the tool panel and the group panel for `IconButton`; the filter
+dialog, the filter builder and the grouping section for `Select` — and
 receives exactly the props the built-in does, `site` included, so it can
 branch on where it is.
 
@@ -69,9 +134,11 @@ branch on where it is.
 | ------------ | ----------------------------- | ------------------------------------------------------------------------------ |
 | `Button`     | `PretableButtonComponent`     | Receives `PretableButtonProps`; must forward its `ref` to the button node.     |
 | `IconButton` | `PretableIconButtonComponent` | Receives `PretableIconButtonProps`; must forward its `ref` to the button node. |
+| `Select`     | `PretableSelectComponent`     | Receives `PretableSelectProps`; must forward its `ref` to the button node.     |
 
 Forwarding the `ref` is the one obligation on a replacement: the grid anchors
-menus on the node and returns keyboard focus to it. Under React 18 that means
+menus on the node and returns keyboard focus to it — a replaced `Select` owes
+it too, because the filter dialog focuses its operator picker when it opens. Under React 18 that means
 `forwardRef`; under React 19 a plain `ref` prop is enough. The set of built-in
 `site` names is the `PretableBuiltInButtonSite` type and grows additively — a
 new grid button may introduce a new site without a major bump.
diff --git a/apps/website/content/docs/grid/filtering.mdx b/apps/website/content/docs/grid/filtering.mdx
index 74965923..8fd54224 100644
--- a/apps/website/content/docs/grid/filtering.mdx
+++ b/apps/website/content/docs/grid/filtering.mdx
@@ -4,7 +4,7 @@ description: "Operator-based column filters: the built-in header menu, per-colum
 nav: Grid
 ---
 
-Every column is filterable **by default**. Hover a header row and a funnel button appears in each header; click it and a small menu opens with an operator select and a typed value control. On a touch device there is no hover, so the funnel is [drawn all the time](#the-funnel-on-touch) instead. Filters apply live as you type, combine across columns with AND, and survive row updates — set `filterable: false` on a column to opt it out.
+Every column is filterable **by default**. Hover a header row and a funnel button appears in each header; click it and a small menu opens with an operator picker and a typed value control. On a touch device there is no hover, so the funnel is [drawn all the time](#the-funnel-on-touch) instead. Filters apply live as you type, combine across columns with AND, and survive row updates — set `filterable: false` on a column to opt it out.
 
 Filters are the `filters` field of one typed query object alongside `sort` and `rowGroups`. The grid owns that query by default. To control it, pass the exact `query` and `onQueryChange` pair; partial ownership is intentionally rejected.
 
@@ -71,7 +71,7 @@ Semantics worth knowing:
 
 The funnel button renders in every filterable header. With the `@pretable/ui` skin **on a fine pointer** it stays hidden until you hover the header row, focus it with the keyboard, or the column has an active filter — an active funnel stays visible and tinted with the accent color. On a coarse pointer it is always drawn; see [The funnel on touch](#the-funnel-on-touch).
 
-Clicking the funnel opens a popover (`role="dialog"`, labeled `Filter {header}`) anchored under the button, with the operator `<select>` focused. From there:
+Clicking the funnel opens a popover (`role="dialog"`, labeled `Filter {header}`) anchored under the button, with the operator picker focused. From there:
 
 - **Filters apply live.** Free-text and number typing is debounced (~200&nbsp;ms); operator changes, date picks, and enum checkboxes apply immediately. Closing the menu flushes any pending keystrokes.
 - **Ranges wait for both bounds.** `between` / `dateBetween` only take effect once min and max are both set (and numeric, for numbers). An incomplete value clears the column's filter rather than half-applying it.
diff --git a/apps/website/content/docs/grid/tool-panel.mdx b/apps/website/content/docs/grid/tool-panel.mdx
index b7969769..3ee9b85d 100644
--- a/apps/website/content/docs/grid/tool-panel.mdx
+++ b/apps/website/content/docs/grid/tool-panel.mdx
@@ -161,7 +161,7 @@ The block renders **in rows mode only**. In explicit-model mode the caller owns
 
 ### The grouping section's DOM hooks and strings
 
-The section's container is `data-pretable-tool-grouping`. A group-by row is `data-pretable-tool-group-row` (with `data-pretable-column-id`), its grip `data-pretable-tool-row-grip` and its remove button `data-pretable-tool-group-remove`; the add button is `data-pretable-add-group` and its menu `data-pretable-add-group-menu`. The expansion pair is `data-pretable-expand-all` / `data-pretable-collapse-all`, the switch's input `data-pretable-hide-grouped`, and an aggregate row `data-pretable-aggregate-row` (with `data-pretable-column-id`).
+The section's container is `data-pretable-tool-grouping`. A group-by row is `data-pretable-tool-group-row` (with `data-pretable-column-id`), its grip `data-pretable-tool-row-grip` and its remove button `data-pretable-tool-group-remove`; the add button is `data-pretable-add-group` and its menu `data-pretable-add-group-menu`. The expansion pair is `data-pretable-expand-all` / `data-pretable-collapse-all`, the switch's input `data-pretable-hide-grouped`, and an aggregate row `data-pretable-aggregate-row` (with `data-pretable-column-id`), whose picker is `data-pretable-aggregate`.
 
 Every string is a message: `toolPanelGroupByLabel`, `toolPanelAddRowGroupLabel`, `toolPanelRemoveGroupLabel`, `toolPanelReorderGroupLabel`, and `toolPanelNoGroupsMessage` for the group-by block; `toolPanelExpandAllLabel` and `toolPanelCollapseAllLabel`; `toolPanelHideGroupedColumnsLabel`; and for the pickers `toolPanelAggregatesLabel`, `toolPanelAggregateColumnLabel`, `toolPanelAggregateDefaultOption`, `toolPanelAggregateNoneOption`, `toolPanelAggregateCustomLabel`, and the five builtin names (`toolPanelAggregateSumLabel` through `toolPanelAggregateCountLabel`). The reorder grip deliberately does **not** reuse the columns section's "Reorder {column}": the two grips coexist in one panel, and identical accessible names would leave a screen-reader user unable to tell reordering a column from reordering a grouping level.
 
@@ -274,7 +274,7 @@ The rail is one Tab stop, however many sections it grows.
 
 Each row's grip is its own Tab stop, so the chord is reachable without a pointer. The two panes' grips carry different accessible names — "Reorder {column}" in the columns section, "Reorder grouping by {column}" in the grouping section — because both can be in the panel at once. Pinning into an empty pinned group is the one operation the chord cannot express — that is the columns row's ⋮ menu.
 
-The grouping pane's remaining controls are ordinary form controls — the expansion buttons, the switch, one `<select>` per aggregate row — and its **+ Add group** menu is the same menu keyboard the filters pane's pickers use: arrows move, `Enter` selects, `Escape` closes back to the button.
+The grouping pane's remaining controls are ordinary form controls — the expansion buttons, the switch, one aggregate picker per row — a select-only combobox, not a native `<select>` — and its **+ Add group** menu is now literally the same keyboard the filters pane's pickers use: arrows move, `Home` / `End` jump to the ends, typing jumps by prefix, `Enter` selects, and `Escape` closes back to the button.
 
 The filters pane needs no chords of its own: its controls are ordinary form controls, walked in the order the tree reads — column, operator, value, remove, then the run's add pair, and the same again inside each group. Two things are not stops there. The **join** is focusable only where it can actually change anything: on the second and later rows of a nested run it is a button, and everywhere else — every run's first row, and every row of the root run, whose implicit AND has nothing to flip — it is plain text. And the plain buttons may be skipped by the browser: WebKit leaves a `<button>` out of the Tab order unless macOS's "Tab moves between all controls" is on, which is a platform preference rather than something a grid can set.
 
diff --git a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
index cceca147..2da667cc 100644
--- a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
+++ b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
@@ -1370,6 +1370,10 @@ const TABLES: Record<string, TableBinding> = {
     types: [{ pkg: "react", name: "PretableIconButtonProps" }],
     complete: true,
   },
+  "grid/components.mdx#Select": {
+    types: [{ pkg: "react", name: "PretableSelectProps" }],
+    complete: true,
+  },
   "grid/components.mdx#Replacing a component": {
     types: [{ pkg: "react", name: "PretableComponents" }],
     complete: true,
@@ -1579,6 +1583,7 @@ const MEMBER_TABLE_TYPES: Record<string, true | string> = {
 
   "grid/components.mdx#Button": true,
   "grid/components.mdx#IconButton": true,
+  "grid/components.mdx#Select": true,
   "grid/components.mdx#Replacing a component": true,
 };
 

From 927c175ec0be00cdccecbdbad82f0b27b017ce39 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:13:38 -0700
Subject: [PATCH 21/27] test(website): the pickers in a real browser; e2e
 drivers move to chooseOption

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/app/fixtures/components/page.tsx | 41 +++++++-
 apps/website/e2e/components.spec.ts           | 94 +++++++++++++++++++
 apps/website/e2e/helpers.ts                   | 32 +++++++
 apps/website/e2e/tool-panel.spec.ts           | 63 ++++++++-----
 4 files changed, 206 insertions(+), 24 deletions(-)

diff --git a/apps/website/app/fixtures/components/page.tsx b/apps/website/app/fixtures/components/page.tsx
index a6bf4729..37010788 100644
--- a/apps/website/app/fixtures/components/page.tsx
+++ b/apps/website/app/fixtures/components/page.tsx
@@ -5,6 +5,7 @@ import {
   type PretableButtonComponent,
   type PretableColumn,
   type PretableIconButtonComponent,
+  type PretableSelectComponent,
 } from "@pretable/react";
 import { forwardRef } from "react";
 
@@ -68,13 +69,51 @@ const FixtureIconButton: PretableIconButtonComponent = forwardRef(
   },
 );
 
+/**
+ * A picker replacement that is a plain button, not a combobox — deliberately
+ * nothing like the kit's own. It records what the grid handed it (`site`, the
+ * committed value, how many options) and, on click, commits the first other
+ * enabled option, so a test can prove the grid's `onChange` reaches the model
+ * through a replacement that shares none of the kit's internals.
+ */
+const FixtureSelect: PretableSelectComponent = forwardRef(
+  function FixtureSelect(
+    { site, options, value, onChange, "aria-label": label, ...props },
+    ref,
+  ) {
+    return (
+      <button
+        {...props}
+        ref={ref}
+        type="button"
+        aria-label={label}
+        data-fixture-select={site ?? ""}
+        data-fixture-value={value}
+        data-fixture-option-count={options.length}
+        onClick={() =>
+          onChange(
+            options.find((o) => o.value !== value && !o.disabled)?.value ??
+              value,
+          )
+        }
+      >
+        {value}
+      </button>
+    );
+  },
+);
+
 export default function ComponentsFixturePage() {
   return (
     <main style={{ padding: 24 }}>
       <PretableSurface
         ariaLabel="components-fixture"
         columns={COLUMNS}
-        components={{ Button: FixtureButton, IconButton: FixtureIconButton }}
+        components={{
+          Button: FixtureButton,
+          IconButton: FixtureIconButton,
+          Select: FixtureSelect,
+        }}
         getRowId={(row) => row.id}
         rows={ROWS}
         toolPanel={{ defaultActiveSection: "columns" }}
diff --git a/apps/website/e2e/components.spec.ts b/apps/website/e2e/components.spec.ts
index d6e63807..cdad95b8 100644
--- a/apps/website/e2e/components.spec.ts
+++ b/apps/website/e2e/components.spec.ts
@@ -43,7 +43,33 @@ test("every button in the grid is the consumer's, including inside the portalled
     "data-fixture-button",
     "filter-clear",
   );
+
+  // The dialog's operator picker is the replacement too — and the grid's own
+  // behaviour on it survived: `FilterMenu` focuses the picker on mount through
+  // a ref, so a replacement that dropped its ref would leave focus on <body>.
+  const operator = dialog.locator("[data-fixture-select]");
+  await expect(operator).toHaveAttribute(
+    "data-fixture-select",
+    "filter-operator",
+  );
+  // `name` is a text column, so the draft opens on the type's first operator.
+  await expect(operator).toHaveAttribute("data-fixture-value", "contains");
+  await expect(operator).toBeFocused();
   await page.keyboard.press("Escape");
+
+  // The builder's pickers are replaced at their sites as well, and the grid
+  // hands them a real option list rather than rendering the kit's own.
+  await page
+    .locator('[data-pretable-tool-tab][data-pretable-section="filters"]')
+    .click();
+  await page.getByRole("button", { name: "+ filter", exact: true }).click();
+  const rowColumn = page.locator('[data-fixture-select="filter-row-column"]');
+  await expect(rowColumn).toHaveCount(1);
+  expect(
+    Number(await rowColumn.getAttribute("data-fixture-option-count")),
+  ).toBeGreaterThan(0);
+  // Still nothing the kit draws itself, now that a second site has rendered.
+  await expect(page.locator("[data-pretable-select]")).toHaveCount(0);
 });
 
 test("the grid still anchors a menu on, and returns focus to, a replaced icon button", async ({
@@ -92,3 +118,71 @@ test("the grid still anchors a menu on, and returns focus to, a replaced icon bu
   // A replacement that dropped its ref would leave focus on <body> here.
   await expect(kebab).toBeFocused();
 });
+
+/**
+ * The kit's own picker, on a real grid with nothing replaced.
+ *
+ * The unit suite drives `PretableSelect` in jsdom, where a keypress is a
+ * synthesised React event and focus is bookkeeping. This is the browser's
+ * verdict on the same contract, at a site where a wrong commit is visible in
+ * the grid: `/fixtures/grouping` declares `aggregate: "sum"` on `qty` with a
+ * `formatAggregate` of `Σ <n>`, and Industry 01-2's five values are 121…125 —
+ * so sum (Σ 615) and avg (Σ 123) disagree, and the group row's cell says which
+ * one the keyboard actually chose.
+ */
+test("the kit's picker commits by keyboard, with typeahead, and Escape leaves focus on the trigger", async ({
+  page,
+}) => {
+  await page.goto("/fixtures/grouping", { waitUntil: "domcontentloaded" });
+  await waitForGridReady(page);
+
+  const section = page.locator("[data-pretable-tool-grouping]");
+  await page
+    .locator('[data-pretable-tool-tab][data-pretable-section="grouping"]')
+    .click();
+  await expect(section).toBeVisible();
+
+  const picker = page.locator(
+    '[data-pretable-aggregate-row][data-pretable-column-id="qty"] [data-pretable-aggregate]',
+  );
+  await expect(picker).toHaveAttribute("data-pretable-value", "default");
+  const aggregateCell = page
+    .locator("[data-pretable-group-row]")
+    .filter({ hasText: "Industry 01-2" })
+    .locator('[data-pretable-cell][data-pretable-column-id="qty"]');
+  await expect(aggregateCell).toHaveText("Σ 615");
+
+  const list = page.locator("[data-pretable-listbox]");
+
+  // ArrowDown on a closed trigger opens the list — the native <select>
+  // contract — and the list is portalled out to <body>, which is the whole
+  // reason it needs its own placement.
+  await picker.focus();
+  await page.keyboard.press("ArrowDown");
+  await expect(list).toBeVisible();
+  expect(await list.evaluate((el) => el.parentElement === document.body)).toBe(
+    true,
+  );
+
+  // Typeahead by label prefix. The offered labels here are `Default (Sum)`,
+  // `None`, `Sum`, `Average`, `Min`, `Max`, `Count`, so "a" is unambiguous —
+  // and it is NOT the committed value, so the assertion below can fail.
+  await page.keyboard.press("a");
+  await page.keyboard.press("Enter");
+
+  await expect(picker).toHaveAttribute("data-pretable-value", "avg");
+  await expect(list).toHaveCount(0);
+  // Enter commits and hands focus back to the trigger, not to <body>.
+  await expect(picker).toBeFocused();
+  // ...and the commit reached the model, not just the trigger's own state.
+  await expect(aggregateCell).toHaveText("Σ 123");
+
+  // Space opens too, and Escape closes without committing anything.
+  await page.keyboard.press(" ");
+  await expect(list).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(list).toHaveCount(0);
+  await expect(picker).toBeFocused();
+  await expect(picker).toHaveAttribute("data-pretable-value", "avg");
+  await expect(aggregateCell).toHaveText("Σ 123");
+});
diff --git a/apps/website/e2e/helpers.ts b/apps/website/e2e/helpers.ts
index 48ef6f37..ca2a73b6 100644
--- a/apps/website/e2e/helpers.ts
+++ b/apps/website/e2e/helpers.ts
@@ -334,3 +334,35 @@ export async function dragResizeHandle(handle: Locator, deltaX: number) {
     "column resize never engaged: data-pretable-dragging stayed false across 3 presses",
   );
 }
+
+/**
+ * Chooses `value` from a kit picker (`PretableSelect`), and waits for the
+ * commit.
+ *
+ * The pickers used to be native `<select>`s, which Playwright drives in one
+ * call (`selectOption`) and reads with `toHaveValue`. They are select-only
+ * comboboxes now: the trigger is a `<button>`, which has no `.value` at all,
+ * and its list is not a child of the trigger — it is portalled to
+ * `document.body` (the grid viewport's `contain: content` would clip a fixed
+ * popover), so it cannot be located under the trigger either.
+ *
+ * Hence the three steps: press the trigger, find the option by its `data-value`
+ * anywhere in the document, and read the commit back off the trigger's
+ * `data-pretable-value` — the attribute the component writes for exactly this
+ * reason. Waiting on that attribute rather than returning after the click also
+ * keeps the caller off a stale value: the commit is a React state update, so
+ * the next assertion would otherwise race it.
+ */
+export async function chooseOption(
+  page: Page,
+  trigger: Locator,
+  value: string,
+): Promise<void> {
+  await trigger.click();
+  const option = page.locator(
+    `[data-pretable-listbox] [data-pretable-option][data-value="${value}"]`,
+  );
+  await expect(option).toBeVisible();
+  await option.click();
+  await expect(trigger).toHaveAttribute("data-pretable-value", value);
+}
diff --git a/apps/website/e2e/tool-panel.spec.ts b/apps/website/e2e/tool-panel.spec.ts
index 5384b742..4e262fd3 100644
--- a/apps/website/e2e/tool-panel.spec.ts
+++ b/apps/website/e2e/tool-panel.spec.ts
@@ -1,6 +1,10 @@
 import { expect, test, type Locator, type Page } from "@playwright/test";
 
-import { waitForGridReady, waitForStablePosition } from "./helpers";
+import {
+  chooseOption,
+  waitForGridReady,
+  waitForStablePosition,
+} from "./helpers";
 
 /**
  * The tool panel, driven with a real pointer and a real keyboard — the
@@ -536,9 +540,9 @@ test("filters: a filter drops the row count, and an empty group does not", async
   // A fresh row lands on the first column with its type's default operator —
   // and holds its place as an empty group until it has a value, so the grid
   // is still unfiltered at this point.
-  await expect(row.locator("[data-pretable-filter-row-column]")).toHaveValue(
-    "symbol",
-  );
+  await expect(
+    row.locator("[data-pretable-filter-row-column]"),
+  ).toHaveAttribute("data-pretable-value", "symbol");
   await expect(shownRowCount(page)).toHaveText("12");
 
   await row.locator("[data-pretable-filter-row-value]").fill("s");
@@ -641,7 +645,15 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
   // derived from what the browser gave: the stops it does offer come in tree
   // order, every stop that exists everywhere is among them, and the walk ends
   // at the rail.
-  const BUTTONS = new Set([
+  //
+  // The two pickers are on THIS side of that line now. They were native
+  // `<select>`s — a stop in every browser — and are the kit's select-only
+  // combobox since SP2, whose trigger is a plain `<button>`; measured here,
+  // WebKit offers neither unless the preference is on. Their being stops at
+  // all is still asserted, just conditionally, alongside the other buttons.
+  const CONDITIONAL = new Set([
+    "data-pretable-filter-row-column",
+    "data-pretable-filter-row-operator",
     "data-pretable-filter-row-remove",
     "data-pretable-filter-add",
   ]);
@@ -660,17 +672,16 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
   expect(isSubsequenceOf(FULL, seen), `walk was ${seen.join(" → ")}`).toBe(
     true,
   );
-  // The non-button controls are stops in every browser, so they are asserted
-  // exactly: the two selects, the operand field, and the rail.
-  expect(seen.filter((part) => !BUTTONS.has(part))).toEqual([
-    "data-pretable-filter-row-column",
-    "data-pretable-filter-row-operator",
+  // The unconditional stops are asserted exactly: the operand field (a text
+  // input, which every browser offers) and the rail.
+  expect(seen.filter((part) => !CONDITIONAL.has(part))).toEqual([
     "data-pretable-filter-row-value",
     "data-pretable-tool-tab",
   ]);
   // And where the browser offers button stops at all, it must offer all of
-  // them — a missing remove or add button there is a real bug, not a policy.
-  if (seen.some((part) => BUTTONS.has(part))) {
+  // them — a missing picker, remove or add button there is a real bug, not a
+  // policy.
+  if (seen.some((part) => CONDITIONAL.has(part))) {
     expect(seen).toEqual(FULL);
   }
   // ...and the walk LEAVES. `grid-tab-wrap-rows.spec.ts` makes the same claim
@@ -835,9 +846,9 @@ test("grouping: an aggregate override changes what the group row shows, and clea
   await expect(aggregateCell).toHaveText("Σ 615");
 
   const qtyPicker = page.locator(
-    '[data-pretable-aggregate-row][data-pretable-column-id="qty"] select',
+    '[data-pretable-aggregate-row][data-pretable-column-id="qty"] [data-pretable-aggregate]',
   );
-  await qtyPicker.selectOption("avg");
+  await chooseOption(page, qtyPicker, "avg");
 
   // The differently-computed value, not a re-render of the same one: sum and
   // avg genuinely disagree on this fixture.
@@ -845,7 +856,7 @@ test("grouping: an aggregate override changes what the group row shows, and clea
 
   // Back to Default: the override was a layer over the declared aggregate,
   // not a rewrite of it — clearing it restores the declared sum.
-  await qtyPicker.selectOption("default");
+  await chooseOption(page, qtyPicker, "default");
   await expect(aggregateCell).toHaveText("Σ 615");
 });
 
@@ -942,14 +953,20 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   expect(isSubsequenceOf(FULL, seen), `walk was ${seen.join(" → ")}`).toBe(
     true,
   );
-  // The stops that exist in every browser, exactly: every aggregate picker,
-  // then the rail as the panel's last stop.
-  expect(
-    seen.filter((stop) => stop !== "hide-grouped" && stop !== "add-group"),
-  ).toEqual([
-    ...Array<string>(aggregateCount).fill("aggregate-select"),
-    "rail",
-  ]);
+  // The one stop that exists in every browser: the rail, as the panel's last
+  // stop. The aggregate pickers used to be here too — they were native
+  // `<select>`s — but since SP2 each is the kit's combobox, whose trigger is
+  // a plain `<button>`, so they joined the conditional stops (WebKit offers
+  // none of them unless "Tab moves between all controls" is on).
+  const CONDITIONAL = new Set(["hide-grouped", "add-group", "aggregate-select"]);
+  expect(seen.filter((stop) => !CONDITIONAL.has(stop))).toEqual(["rail"]);
+  // Where the browser offers button stops at all, it must offer EVERY
+  // picker — one missing aggregate row is a real bug, not a policy.
+  if (seen.includes("aggregate-select")) {
+    expect(seen.filter((stop) => stop === "aggregate-select")).toHaveLength(
+      aggregateCount,
+    );
+  }
 
   // Escape-returns-to-rail is deliberately not re-proven here: the columns
   // and filters walks already pin it, and the handler is the pane shell's —

From 06699b2382712f101a17cbe3223f9253a293ccfe Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:16:20 -0700
Subject: [PATCH 22/27] docs: the add-group menu keeps its own keyboard; the
 site count is sixteen

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/content/docs/grid/components.mdx | 47 ++++++++++---------
 apps/website/content/docs/grid/tool-panel.mdx |  2 +-
 .../docs/__tests__/docs-api-surface.test.ts   |  8 ++--
 3 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
index e96549f4..c3e89929 100644
--- a/apps/website/content/docs/grid/components.mdx
+++ b/apps/website/content/docs/grid/components.mdx
@@ -53,12 +53,13 @@ development. Four grid pickers are this component: the funnel menu's
 and the grouping section's
 [aggregate picker](/docs/grid/tool-panel#aggregates).
 
-The keyboard is the listbox one: `↓` / `↑` open the list and move through it,
-wrapping at the ends and skipping disabled options; `Home` / `End` jump to the
-first and last enabled option; typing jumps by label prefix, the prefix
-resetting after 500ms of silence; `Enter` or `Space` commits the active option;
-`Escape` closes the list and returns focus to the trigger; `Tab` closes it and
-moves on. `onChange` fires only when the chosen value differs from `value`.
+The keyboard is the listbox one: on a closed trigger, `↓`, `↑`, `Enter` or
+`Space` opens the list; open, `↓` / `↑` move through it, wrapping at the ends
+and skipping disabled options; `Home` / `End` jump to the first and last
+enabled option; typing jumps by label prefix, the prefix resetting after
+500ms of silence; `Enter` or `Space` commits the active option; `Escape`
+closes the list and returns focus to the trigger; `Tab` closes it and moves
+on. `onChange` fires only when the chosen value differs from `value`.
 
 A `disabled` option is shown, skipped by the keyboard and inert to click —
 that is how the aggregate picker shows a consumer-written custom aggregate it
@@ -92,17 +93,18 @@ import { PretableSelect } from "@pretable/react";
 ## Styling
 
 The styling channel is the one the whole grid uses: attributes and tokens.
-Every button carries `data-pretable-button` or `data-pretable-icon-button`; a
-labelled button also carries `data-pretable-variant`, and any of them carries
-`data-pretable-site` when the grid gave it one. A select's trigger carries
-`data-pretable-select` and writes its committed value to
-`data-pretable-value` — a `<button>` has no `.value`, so that attribute is the
-truth a test reads and a selector matches. Its label span is
-`data-pretable-select-label`; the open list is `data-pretable-listbox` with a
-`data-pretable-option` per entry, the keyboard-active one carrying
-`data-active` and the chosen one `aria-selected="true"`. The grid's own sites also
-keep their original attribute (`data-pretable-filter-clear`,
-`data-pretable-tool-reset`, …), so a selector you already wrote keeps matching.
+Every push-button carries `data-pretable-button` or
+`data-pretable-icon-button`; a labelled button also carries
+`data-pretable-variant`, and any of them carries `data-pretable-site` when
+the grid gave it one. A select's trigger carries `data-pretable-select` and
+writes its committed value to `data-pretable-value` — a `<button>` has no
+`.value`, so that attribute is the truth a test reads and a selector
+matches. Its label span is `data-pretable-select-label`; the open list is
+`data-pretable-listbox` with a `data-pretable-option` per entry, the
+keyboard-active one carrying `data-active` and the chosen one
+`aria-selected="true"`. The grid's own sites also keep their original
+attribute (`data-pretable-filter-clear`, `data-pretable-tool-reset`, …), so a
+selector you already wrote keeps matching.
 
 ```css
 [data-pretable-button][data-pretable-variant="ghost"] {
@@ -137,8 +139,9 @@ branch on where it is.
 | `Select`     | `PretableSelectComponent`     | Receives `PretableSelectProps`; must forward its `ref` to the button node.     |
 
 Forwarding the `ref` is the one obligation on a replacement: the grid anchors
-menus on the node and returns keyboard focus to it — a replaced `Select` owes
-it too, because the filter dialog focuses its operator picker when it opens. Under React 18 that means
-`forwardRef`; under React 19 a plain `ref` prop is enough. The set of built-in
-`site` names is the `PretableBuiltInButtonSite` type and grows additively — a
-new grid button may introduce a new site without a major bump.
+menus on the node and returns keyboard focus to it — a replaced `Select`
+owes it too, because the filter dialog focuses its operator picker when it
+opens. Under React 18 that means `forwardRef`; under React 19 a plain `ref`
+prop is enough. The set of built-in `site` names is the
+`PretableBuiltInButtonSite` type and grows additively — a new grid button
+may introduce a new site without a major bump.
diff --git a/apps/website/content/docs/grid/tool-panel.mdx b/apps/website/content/docs/grid/tool-panel.mdx
index 3ee9b85d..ca10aafd 100644
--- a/apps/website/content/docs/grid/tool-panel.mdx
+++ b/apps/website/content/docs/grid/tool-panel.mdx
@@ -274,7 +274,7 @@ The rail is one Tab stop, however many sections it grows.
 
 Each row's grip is its own Tab stop, so the chord is reachable without a pointer. The two panes' grips carry different accessible names — "Reorder {column}" in the columns section, "Reorder grouping by {column}" in the grouping section — because both can be in the panel at once. Pinning into an empty pinned group is the one operation the chord cannot express — that is the columns row's ⋮ menu.
 
-The grouping pane's remaining controls are ordinary form controls — the expansion buttons, the switch, one aggregate picker per row — a select-only combobox, not a native `<select>` — and its **+ Add group** menu is now literally the same keyboard the filters pane's pickers use: arrows move, `Home` / `End` jump to the ends, typing jumps by prefix, `Enter` selects, and `Escape` closes back to the button.
+The grouping pane's remaining controls are ordinary form controls — the expansion buttons and the switch. One aggregate picker per row is a [select-only combobox](/docs/grid/components#select), not a native `<select>`, and it keeps that component's own keyboard: arrows open and move, `Home` / `End` jump to the ends, typing jumps by prefix, `Enter` / `Space` commits, `Escape` closes it. Its **+ Add group** menu is a plainer, separate control — a focus-roving menu, not a combobox: `↑` / `↓` move between items, `Enter` activates the focused one (native button activation, not a keyboard handler), and `Escape` closes it back to the button. There is no `Home` / `End` and no typeahead in this menu.
 
 The filters pane needs no chords of its own: its controls are ordinary form controls, walked in the order the tree reads — column, operator, value, remove, then the run's add pair, and the same again inside each group. Two things are not stops there. The **join** is focusable only where it can actually change anything: on the second and later rows of a nested run it is a button, and everywhere else — every run's first row, and every row of the root run, whose implicit AND has nothing to flip — it is plain text. And the plain buttons may be skipped by the browser: WebKit leaves a `<button>` out of the Tab order unless macOS's "Tab moves between all controls" is on, which is a platform preference rather than something a grid can set.
 
diff --git a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
index 2da667cc..c89a49a1 100644
--- a/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
+++ b/apps/website/lib/docs/__tests__/docs-api-surface.test.ts
@@ -1778,9 +1778,11 @@ const STRING_UNIONS: Record<string, UnionBinding> = {
   // The built-in button sites. `grid/components.mdx` names the type as the
   // vocabulary `site` draws from and says outright that it grows additively —
   // a new grid control may introduce a new site without a major bump. The
-  // twelve names are the grid's own control inventory rather than a menu a
-  // reader picks from, so no page lists them, and there is nothing here to
-  // hold a sentence to.
+  // sixteen names — twelve buttons plus the four picker sites (the funnel
+  // and filter-builder operators, the filter-builder column, and the
+  // grouping aggregate) — are the grid's own control inventory rather than a
+  // menu a reader picks from, so no page lists them, and there is nothing
+  // here to hold a sentence to.
   "react/PretableBuiltInButtonSite": {
     unenumerated:
       "grid/components.mdx names the type as where `site`'s built-in values come from and states that the set grows additively; no page spells the members out.",

From c313a02382c12470e329381e0b825bef4fdef52c Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:19:46 -0700
Subject: [PATCH 23/27] test(react): the JSX-import guard ignores commented and
 aliased imports

The guard's reactImportedNames read the unstripped source (so a mention
of createElement/Fragment inside a comment counted as a real import)
and matched `X as Y` by X (so `createElement as h` satisfied the guard
even though the classic pragma needs the bare name in scope). Both were
false negatives: a shipped file could pass the guard and still throw
"Fragment is not defined" at runtime.

Fixed by scanning a comments-only-stripped source (stripping strings too
would blank the "react" specifier itself) and binding each import by its
post-alias name. Added unit tests for the helper covering a commented-out
import, an aliased import, and a multi-line import; updated the header
comment to describe the two-stripper split and alias-binding rule.

Also corrected an over-claiming comment on the option-shape pin in
select.tsx: a `false` there is a compile error at that line, not
something that names the drifted field.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/jsx-runtime-imports.test.ts | 110 ++++++++++++++++--
 packages/react/src/components/select.tsx      |   4 +-
 2 files changed, 103 insertions(+), 11 deletions(-)

diff --git a/packages/react/src/__tests__/jsx-runtime-imports.test.ts b/packages/react/src/__tests__/jsx-runtime-imports.test.ts
index 402956f2..a3bb42a5 100644
--- a/packages/react/src/__tests__/jsx-runtime-imports.test.ts
+++ b/packages/react/src/__tests__/jsx-runtime-imports.test.ts
@@ -18,17 +18,28 @@
  *
  * So this test reads the SOURCE rather than executing it.
  *
- * Heuristic. Comments and string/template literals are stripped first, then:
+ * Heuristic, for the JSX scan: comments and string/template literals are
+ * stripped first, then:
  *   - JSX is "a `<` that starts a tag" — `<` followed by a letter or by `>`,
  *     and NOT preceded by an identifier character, `.`, `)` or `]`. The
  *     preceding-character rule is what separates JSX (`return <div>`,
  *     `{cond ? <A/> : null}`) from a generic type argument
  *     (`useState<DOMRect>`, `forwardRef<HTMLButtonElement, Props>`).
  *   - a fragment is `<>` or `<Fragment`.
+ *
+ * The import scan (`reactImportedNames`) strips only COMMENTS, not strings —
+ * stripping strings too would blank out the `"react"` module specifier
+ * itself and make every import invisible to the scan. Skipping the
+ * string-strip is safe here because the scan only needs to see the import
+ * statement's shape, not anything inside a string value. It also binds each
+ * name by where it lands in scope: `import { createElement as h }` binds
+ * `h`, not `createElement` — the classic pragma needs the bare name
+ * `createElement` in scope, and an aliased import does not put it there.
+ *
  * Known blind spots, all of which fail SAFE (a missed file is not a false
  * accusation, and the mutation check below proves the detector still bites):
- *   - regex literals are not tracked by the stripper, so a regex containing a
- *     quote or a slash could desynchronise it;
+ *   - regex literals are not tracked by either stripper, so a regex
+ *     containing a quote or a slash could desynchronise it;
  *   - JSX interpolated inside a template literal is stripped away with the
  *     template;
  *   - `import * as React from "react"` + `React.createElement` is not
@@ -108,17 +119,75 @@ function stripCommentsAndStrings(source: string): string {
   return out.join("");
 }
 
-/** Names imported from `"react"` by a named import, across any number of lines. */
+/**
+ * Blanks out line and block comments only, leaving string/template literals
+ * untouched — used for the import scan, where the `"react"` specifier itself
+ * is a string literal we still need to see. Quotes are tracked (without
+ * blanking) purely so a `//` or `/*` sitting inside a string doesn't get
+ * mistaken for the start of a real comment.
+ */
+function stripComments(source: string): string {
+  const out = source.split("");
+  const blank = (from: number, to: number) => {
+    for (let k = from; k < to && k < out.length; k += 1) {
+      if (out[k] !== "\n") out[k] = " ";
+    }
+  };
+  let i = 0;
+  while (i < source.length) {
+    const two = source.slice(i, i + 2);
+    if (two === "//") {
+      const end = source.indexOf("\n", i);
+      const stop = end === -1 ? source.length : end;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    if (two === "/*") {
+      const end = source.indexOf("*/", i + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      blank(i, stop);
+      i = stop;
+      continue;
+    }
+    const quote = source[i];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      let j = i + 1;
+      while (j < source.length) {
+        if (source[j] === "\\") {
+          j += 2;
+          continue;
+        }
+        if (source[j] === quote) break;
+        j += 1;
+      }
+      i = Math.min(j + 1, source.length);
+      continue;
+    }
+    i += 1;
+  }
+  return out.join("");
+}
+
+/**
+ * Names imported from `"react"` by a named import, across any number of
+ * lines. Reads the comment-stripped source (see `stripComments`) so a
+ * mention of a pragma name inside a comment is never mistaken for a real
+ * import. An aliased specifier (`x as y`) is recorded as `y`: that is the
+ * only name the alias actually puts in scope, and the classic-runtime
+ * pragmas require the bare original name.
+ */
 function reactImportedNames(source: string): Set<string> {
   const names = new Set<string>();
+  const code = stripComments(source);
   const pattern = /import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*["']react["']/g;
-  for (const match of source.matchAll(pattern)) {
+  for (const match of code.matchAll(pattern)) {
     for (const raw of match[1].split(",")) {
-      const name = raw
-        .trim()
-        .replace(/^type\s+/, "")
-        .split(/\s+as\s+/)[0];
-      if (name) names.add(name.trim());
+      const cleaned = raw.trim().replace(/^type\s+/, "");
+      if (!cleaned) continue;
+      const parts = cleaned.split(/\s+as\s+/);
+      const bound = parts.length > 1 ? parts[1] : parts[0];
+      if (bound) names.add(bound.trim());
     }
   }
   return names;
@@ -127,6 +196,27 @@ function reactImportedNames(source: string): Set<string> {
 const JSX_TAG = /(?<![A-Za-z0-9_$.\])])<(?:[A-Za-z]|>)/;
 const FRAGMENT = /(?<![A-Za-z0-9_$.\])])(?:<>|<Fragment)/;
 
+it("reactImportedNames ignores a react import written inside a comment", () => {
+  const source = `// import { createElement, Fragment } from "react";\nconst x = 1;`;
+  const imported = reactImportedNames(source);
+  expect(imported.has("createElement")).toBe(false);
+  expect(imported.has("Fragment")).toBe(false);
+});
+
+it("reactImportedNames treats an aliased import as not binding the original name", () => {
+  const source = `import { createElement as h } from "react";`;
+  const imported = reactImportedNames(source);
+  expect(imported.has("createElement")).toBe(false);
+  expect(imported.has("h")).toBe(true);
+});
+
+it("reactImportedNames sees a multi-line import", () => {
+  const source = `import {\n  createElement,\n  Fragment,\n} from "react";`;
+  const imported = reactImportedNames(source);
+  expect(imported.has("createElement")).toBe(true);
+  expect(imported.has("Fragment")).toBe(true);
+});
+
 it("every shipped .tsx imports the pragmas the classic JSX build calls", async () => {
   const files = await shippedTsxFiles(SRC);
   expect(files.length).toBeGreaterThan(10);
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index 01a266e3..428c0808 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -65,7 +65,9 @@ type Equal<TLeft, TRight> =
 // The public option shape IS the list's option shape. Pinned, because a
 // divergence in the internal `ListboxOption` would otherwise leave
 // `PretableSelectOption` quietly describing something consumers do not get.
-// A `false` here is a compile error, and names the field that drifted.
+// A `false` here is a compile error at this line ("Type 'true' is not
+// assignable to type 'false'") — it does not name the field that drifted.
+// Diff `PretableSelectOption` against `ListboxOption` by hand to find it.
 const _optionShapePin: Equal<PretableSelectOption, ListboxOption> = true;
 void _optionShapePin;
 

From 8381db066cf4d320725a4e768add1365d91c2323 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:29:31 -0700
Subject: [PATCH 24/27] test(website): grouping walk pins the full roster;
 pane-open helpers shared; search combobox scoped

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/e2e/components.spec.ts | 16 ++++----
 apps/website/e2e/docs.spec.ts       |  6 ++-
 apps/website/e2e/helpers.ts         | 42 +++++++++++++++++++++
 apps/website/e2e/tool-panel.spec.ts | 57 ++++++++---------------------
 4 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/apps/website/e2e/components.spec.ts b/apps/website/e2e/components.spec.ts
index cdad95b8..552de9ab 100644
--- a/apps/website/e2e/components.spec.ts
+++ b/apps/website/e2e/components.spec.ts
@@ -1,6 +1,10 @@
 import { expect, test } from "@playwright/test";
 
-import { waitForGridReady } from "./helpers";
+import {
+  mountGroupingFixture,
+  openGroupingPane,
+  waitForGridReady,
+} from "./helpers";
 
 /**
  * The `components` slot in a real browser. The jsdom suite proves the
@@ -133,14 +137,8 @@ test("the grid still anchors a menu on, and returns focus to, a replaced icon bu
 test("the kit's picker commits by keyboard, with typeahead, and Escape leaves focus on the trigger", async ({
   page,
 }) => {
-  await page.goto("/fixtures/grouping", { waitUntil: "domcontentloaded" });
-  await waitForGridReady(page);
-
-  const section = page.locator("[data-pretable-tool-grouping]");
-  await page
-    .locator('[data-pretable-tool-tab][data-pretable-section="grouping"]')
-    .click();
-  await expect(section).toBeVisible();
+  await mountGroupingFixture(page);
+  await openGroupingPane(page);
 
   const picker = page.locator(
     '[data-pretable-aggregate-row][data-pretable-column-id="qty"] [data-pretable-aggregate]',
diff --git a/apps/website/e2e/docs.spec.ts b/apps/website/e2e/docs.spec.ts
index 30e19572..85fefc1e 100644
--- a/apps/website/e2e/docs.spec.ts
+++ b/apps/website/e2e/docs.spec.ts
@@ -97,8 +97,10 @@ test("keyboard shortcut opens search palette and focuses input", async ({
   page,
 }) => {
   await page.goto("/docs");
-  await openDocsSearch(page);
-  await expect(page.getByRole("combobox")).toBeFocused();
+  const dialog = await openDocsSearch(page);
+  // Scoped to the palette: a bare page-level `combobox` role is a strict-mode
+  // hazard now that the kit's select-only picker reports that role too.
+  await expect(dialog.getByRole("combobox")).toBeFocused();
 });
 
 test("/docs/<slug>.md returns markdown content", async ({ request }) => {
diff --git a/apps/website/e2e/helpers.ts b/apps/website/e2e/helpers.ts
index ca2a73b6..542864b9 100644
--- a/apps/website/e2e/helpers.ts
+++ b/apps/website/e2e/helpers.ts
@@ -352,6 +352,11 @@ export async function dragResizeHandle(handle: Locator, deltaX: number) {
  * reason. Waiting on that attribute rather than returning after the click also
  * keeps the caller off a stale value: the commit is a React state update, so
  * the next assertion would otherwise race it.
+ *
+ * Call it with the value the picker has ALREADY committed and it proves
+ * nothing: the component fires no `onChange` for a no-op choice, so the
+ * closing attribute assertion passes on the value that was there before the
+ * click. Callers must choose a value different from the current one.
  */
 export async function chooseOption(
   page: Page,
@@ -366,3 +371,40 @@ export async function chooseOption(
   await option.click();
   await expect(trigger).toHaveAttribute("data-pretable-value", value);
 }
+
+/** The grouping section's rail tab. */
+export function groupingRailTab(page: Page): Locator {
+  return page.locator(
+    '[data-pretable-tool-tab][data-pretable-section="grouping"]',
+  );
+}
+
+/**
+ * Loads `/fixtures/grouping` and waits until its grid — and the tool panel
+ * rail beside it — have stopped moving, so the press that follows lands.
+ */
+export async function mountGroupingFixture(page: Page): Promise<void> {
+  await page.goto("/fixtures/grouping", { waitUntil: "domcontentloaded" });
+  await waitForGridReady(page);
+  await waitForStablePosition(groupingRailTab(page));
+}
+
+/**
+ * Opens the grouping pane from its rail tab, with the same bounded re-click
+ * as the columns pane, for the same dropped-press family — and toggle-safe
+ * for the same reason: the section mounts synchronously with the activation,
+ * so "no section after the wait" means the click never landed.
+ */
+export async function openGroupingPane(page: Page): Promise<void> {
+  const section = page.locator("[data-pretable-tool-grouping]");
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await groupingRailTab(page).click();
+    try {
+      await expect(section).toBeVisible({ timeout: 1_500 });
+      return;
+    } catch {
+      // fall through to re-click
+    }
+  }
+  await expect(section).toBeVisible();
+}
diff --git a/apps/website/e2e/tool-panel.spec.ts b/apps/website/e2e/tool-panel.spec.ts
index 4e262fd3..dc45db83 100644
--- a/apps/website/e2e/tool-panel.spec.ts
+++ b/apps/website/e2e/tool-panel.spec.ts
@@ -2,6 +2,9 @@ import { expect, test, type Locator, type Page } from "@playwright/test";
 
 import {
   chooseOption,
+  groupingRailTab,
+  mountGroupingFixture,
+  openGroupingPane,
   waitForGridReady,
   waitForStablePosition,
 } from "./helpers";
@@ -715,38 +718,6 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
  * full control set (aggregate pickers included) while ungrouped.
  * ---------------------------------------------------------------------- */
 
-const GROUPING_FIXTURE = "/fixtures/grouping";
-
-function groupingRailTab(page: Page): Locator {
-  return page.locator(
-    '[data-pretable-tool-tab][data-pretable-section="grouping"]',
-  );
-}
-
-async function mountGroupingFixture(page: Page): Promise<void> {
-  await page.goto(GROUPING_FIXTURE, { waitUntil: "domcontentloaded" });
-  await waitForGridReady(page);
-  await waitForStablePosition(groupingRailTab(page));
-}
-
-/** Same bounded re-click as `openColumnsPane`, for the same dropped-press
- * family — and toggle-safe for the same reason: the section mounts
- * synchronously with the activation, so "no section after the wait" means
- * the click never landed. */
-async function openGroupingPane(page: Page): Promise<void> {
-  const section = page.locator("[data-pretable-tool-grouping]");
-  for (let attempt = 0; attempt < 3; attempt++) {
-    await groupingRailTab(page).click();
-    try {
-      await expect(section).toBeVisible({ timeout: 1_500 });
-      return;
-    } catch {
-      // fall through to re-click
-    }
-  }
-  await expect(section).toBeVisible();
-}
-
 /** The pane's group-by list, in order. */
 const paneGroupIds = (page: Page) =>
   page
@@ -889,10 +860,12 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   // roster after it is: the add-group button (a plain <button> — a
   // conditional stop, per the filters walk's WebKit note), expand/
   // collapse-all (DISABLED — never stops), the hide-grouped checkbox, one
-  // aggregate select per column, then the rail. Selects — and the rail tab,
-  // which carries an explicit tabindex — are Tab stops in every browser; the
-  // checkbox and the add-group button are the conditional RECORDED stops,
-  // per the platform's "Tab moves between all controls" preference.
+  // aggregate picker per column, then the rail. Only the rail tab, which
+  // carries an explicit tabindex, is a stop in every browser: the pickers
+  // used to be native `<select>`s but are the kit's combobox since SP2, whose
+  // trigger is a plain `<button>` — so they join the checkbox and the
+  // add-group button as the conditional RECORDED stops, per the platform's
+  // "Tab moves between all controls" preference.
   const aggregateCount = await page
     .locator("[data-pretable-aggregate-row]")
     .count();
@@ -960,12 +933,12 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   // none of them unless "Tab moves between all controls" is on).
   const CONDITIONAL = new Set(["hide-grouped", "add-group", "aggregate-select"]);
   expect(seen.filter((stop) => !CONDITIONAL.has(stop))).toEqual(["rail"]);
-  // Where the browser offers button stops at all, it must offer EVERY
-  // picker — one missing aggregate row is a real bug, not a policy.
-  if (seen.includes("aggregate-select")) {
-    expect(seen.filter((stop) => stop === "aggregate-select")).toHaveLength(
-      aggregateCount,
-    );
+  // And where the browser offers button stops at all, it must offer ALL of
+  // them, in this exact order — a missing add-group, checkbox or aggregate
+  // picker there is a real bug, not a policy. The filters walk's tail,
+  // spelled the same way.
+  if (seen.some((stop) => CONDITIONAL.has(stop))) {
+    expect(seen).toEqual(FULL);
   }
 
   // Escape-returns-to-rail is deliberately not re-proven here: the columns

From 5e906a17841623e1c959762eff735d09b33fdc3e Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:40:46 -0700
Subject: [PATCH 25/27] fix(react): the select trigger is a Tab stop
 everywhere; an empty list never opens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four pickers this component replaced were native <select>s — a stop in
every browser's sequential focus order. A plain <button> is not one in
WebKit unless macOS's "Tab moves between all controls" is on, so the
trigger carries an explicit `tabIndex={0}`, placed before the prop spread
so a consumer running its own roving tabindex still wins. The tool panel's
rail tab carries one for the same reason.

And `openList` returns early on an empty option set: opening there left the
trigger claiming `aria-expanded="true"` with `aria-controls` pointing at a
list that renders nothing. The keyboard path opens through the same
`onOpen`, so one guard covers both.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/__tests__/components-select.test.tsx  | 29 +++++++++++++++++++
 packages/react/src/components/select.tsx      | 16 +++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/__tests__/components-select.test.tsx b/packages/react/src/__tests__/components-select.test.tsx
index 23b094f1..7daaf736 100644
--- a/packages/react/src/__tests__/components-select.test.tsx
+++ b/packages/react/src/__tests__/components-select.test.tsx
@@ -193,6 +193,35 @@ describe("PretableSelect", () => {
     expect(trigger.style.width).toBe("120px");
   });
 
+  test("is a Tab stop everywhere: an explicit tabindex, which a consumer's own overrides", () => {
+    // The parity claim, not a style one. The controls this replaced were
+    // native <select>s, which WebKit puts in the sequential order; a plain
+    // <button> it skips unless "Tab moves between all controls" is on.
+    const { trigger } = renderSelect();
+    expect(trigger).toHaveAttribute("tabindex", "0");
+
+    // ...and it is a default, not a decree: a consumer running its own
+    // roving tabindex still gets the value it passed.
+    cleanup();
+    const { trigger: roving } = renderSelect({ tabIndex: -1 });
+    expect(roving).toHaveAttribute("tabindex", "-1");
+  });
+
+  test("an empty option set never opens — no list to announce", () => {
+    const { trigger } = renderSelect({ options: [], value: "contains" });
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).not.toHaveAttribute("aria-controls");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+
+    // The keyboard path opens through the same `onOpen`, so it is covered by
+    // the same guard.
+    fireEvent.keyDown(trigger, { key: "ArrowDown" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).not.toHaveAttribute("aria-controls");
+    expect(document.querySelector("[data-pretable-listbox]")).toBeNull();
+  });
+
   test("warns in development on an empty accessible name", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     render(
diff --git a/packages/react/src/components/select.tsx b/packages/react/src/components/select.tsx
index 428c0808..ca6e5b79 100644
--- a/packages/react/src/components/select.tsx
+++ b/packages/react/src/components/select.tsx
@@ -179,9 +179,15 @@ export const PretableSelect = forwardRef<
   );
   const openList = useCallback(() => {
     if (disabled) return;
+    // Nothing to choose. Opening on an empty roster would leave the trigger
+    // claiming `aria-expanded="true"` with `aria-controls` pointing at a list
+    // that renders nothing — a screen reader is told a list opened and finds
+    // no list. The keyboard path lands here too: `useListboxKeys` opens a
+    // closed trigger through `onOpen`, which is this.
+    if (options.length === 0) return;
     if (triggerRef.current) setRect(triggerRef.current.getBoundingClientRect());
     setOpen(true);
-  }, [disabled]);
+  }, [disabled, options.length]);
 
   const keys = useListboxKeys({
     options,
@@ -214,6 +220,14 @@ export const PretableSelect = forwardRef<
   return (
     <>
       <button
+        // WebKit's sequential focus navigation omits a plain <button> unless
+        // macOS's "Tab moves between all controls" is on. The four pickers
+        // this replaced were native <select>s — a Tab stop in every browser —
+        // so an explicit tabindex is what keeps that parity. The tool panel's
+        // rail tab carries one for the same reason. BEFORE the spread on
+        // purpose: a consumer passing its own `tabIndex` (a roving `-1`, say)
+        // still wins.
+        tabIndex={0}
         {...buttonProps}
         ref={setTriggerRef}
         type="button"

From 1b8183c282713289ed356206ebf4096bfe98d044 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:46:01 -0700
Subject: [PATCH 26/27] test(website),docs: the funnel dialog survives a picked
 operator; prose stops describing native selects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The list is portalled to <body>, so the option a pointer picks is outside the
funnel dialog's subtree and its outside-press listener sees that press. A
browser test on `/fixtures/grouping` now picks an operator and asserts the
dialog is still standing with the new value, then that Escape unwinds one
layer per press: the list first, the dialog second.

The tool panel's two keyboard walks move the pickers back out of the
conditional sets. They carry an explicit tabindex again, so their exact
position is asserted in every browser — verified against WebKit, which
offered all of them.

Prose only, no declarations: the two skins' `color-scheme` comments named an
operator select and its popup list that are no longer native, and the token
reference said `--pretable-bg-selected` is read in two cell editors when it
is the kit's shared selected-option rule plus the date picker's day. The
components page's styling recipe named `--pretable-surface-hover`, which does
not exist; it is `--pretable-bg-hover`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/website/content/docs/grid/components.mdx |  2 +-
 .../content/docs/theming/token-reference.mdx  | 16 +++----
 apps/website/e2e/components.spec.ts           | 38 +++++++++++++++
 apps/website/e2e/tool-panel.spec.ts           | 47 ++++++++++---------
 packages/ui/themes/excel.css                  | 13 +++--
 packages/ui/themes/material.css               | 13 +++--
 6 files changed, 88 insertions(+), 41 deletions(-)

diff --git a/apps/website/content/docs/grid/components.mdx b/apps/website/content/docs/grid/components.mdx
index c3e89929..13d5b1e6 100644
--- a/apps/website/content/docs/grid/components.mdx
+++ b/apps/website/content/docs/grid/components.mdx
@@ -118,7 +118,7 @@ selector you already wrote keeps matching.
 }
 [data-pretable-option][data-active],
 [data-pretable-option][aria-selected="true"] {
-  background: var(--pretable-surface-hover);
+  background: var(--pretable-bg-hover);
 }
 ```
 
diff --git a/apps/website/content/docs/theming/token-reference.mdx b/apps/website/content/docs/theming/token-reference.mdx
index 2540fea9..0ca4fd5b 100644
--- a/apps/website/content/docs/theming/token-reference.mdx
+++ b/apps/website/content/docs/theming/token-reference.mdx
@@ -51,14 +51,14 @@ Pretable's public theming surface is 50 CSS variables, all `--pretable-*` prefix
 
 ## State (4)
 
-| Token                      | Description                                      | Type  | pretable (default)       | Excel                     | Material 3 (light)                           |
-| -------------------------- | ------------------------------------------------ | ----- | ------------------------ | ------------------------- | -------------------------------------------- |
-| `--pretable-bg-hover`      | Row hover background                             | color | `rgba(24, 24, 32, 0.05)` | `transparent` (no hover)  | `rgba(28, 28, 28, 0.08)` (`on-surface @ 8%`) |
-| `--pretable-bg-selected`   | Selected-option background (enum + date editors) | color | `#dfe6fb`                | `rgba(16, 124, 65, 0.10)` | `#d1e4ff` (`secondary-container`)            |
-| `--pretable-text-selected` | Selected cell text, and selected-option text     | color | `#131826`                | `#1f1f1f`                 | `#001d36` (`on-secondary-container`)         |
-| `--pretable-focus-ring`    | Focus outline color (cell focus, kbd nav)        | color | `#2554cf`                | `#107c41` (Excel green)   | `#0061a4` (`primary`)                        |
-
-> `--pretable-bg-selected` does **not** fill a selected cell, despite the name. The grid stylesheet reads it in exactly two places, both of them a highlighted option in a cell editor: the enum listbox and the date picker's day. The fill behind a selected cell or range is `--pretable-selection-bg`, in Grid controls below — it is a translucent tint, drawn as a background layer so a pinned cell keeps its opaque fill underneath. `--pretable-text-selected` is the one of the pair that does span both: it colors selected cell text as well as those two options.
+| Token                      | Description                                       | Type  | pretable (default)       | Excel                     | Material 3 (light)                           |
+| -------------------------- | ------------------------------------------------- | ----- | ------------------------ | ------------------------- | -------------------------------------------- |
+| `--pretable-bg-hover`      | Row hover background                              | color | `rgba(24, 24, 32, 0.05)` | `transparent` (no hover)  | `rgba(28, 28, 28, 0.08)` (`on-surface @ 8%`) |
+| `--pretable-bg-selected`   | Selected-option background (kit lists + date day) | color | `#dfe6fb`                | `rgba(16, 124, 65, 0.10)` | `#d1e4ff` (`secondary-container`)            |
+| `--pretable-text-selected` | Selected cell text, and selected-option text      | color | `#131826`                | `#1f1f1f`                 | `#001d36` (`on-secondary-container`)         |
+| `--pretable-focus-ring`    | Focus outline color (cell focus, kbd nav)         | color | `#2554cf`                | `#107c41` (Excel green)   | `#0061a4` (`primary`)                        |
+
+> `--pretable-bg-selected` does **not** fill a selected cell, despite the name. The grid stylesheet reads it in exactly two places, and neither is a cell: the shared `[data-pretable-option][aria-selected="true"]` rule — which paints the chosen entry in every list the kit draws, the filter dialog's and the tool panel's operator and column pickers, the grouping pane's aggregate picker, and the enum cell editor alike — and the date picker's selected day. The fill behind a selected cell or range is `--pretable-selection-bg`, in Grid controls below — it is a translucent tint, drawn as a background layer so a pinned cell keeps its opaque fill underneath. `--pretable-text-selected` is the one of the pair that does span both: it colors selected cell text as well as those two marks.
 
 ## Editing (2)
 
diff --git a/apps/website/e2e/components.spec.ts b/apps/website/e2e/components.spec.ts
index 552de9ab..be57e1d6 100644
--- a/apps/website/e2e/components.spec.ts
+++ b/apps/website/e2e/components.spec.ts
@@ -1,7 +1,9 @@
 import { expect, test } from "@playwright/test";
 
 import {
+  chooseOption,
   mountGroupingFixture,
+  openFilterMenu,
   openGroupingPane,
   waitForGridReady,
 } from "./helpers";
@@ -184,3 +186,39 @@ test("the kit's picker commits by keyboard, with typeahead, and Escape leaves fo
   await expect(picker).toHaveAttribute("data-pretable-value", "avg");
   await expect(aggregateCell).toHaveText("Σ 123");
 });
+
+test("the funnel dialog survives a picked operator, and Escape unwinds one layer at a time", async ({
+  page,
+}) => {
+  await page.goto("/fixtures/grouping", { waitUntil: "domcontentloaded" });
+  const dialog = await openFilterMenu(page, "Name");
+  const operator = dialog.locator("[data-pretable-filter-operator]");
+  const list = page.locator("[data-pretable-listbox]");
+
+  // `name` is a text column, so the draft opens on the type's first operator.
+  await expect(operator).toHaveAttribute("data-pretable-value", "contains");
+
+  // The claim only a real browser can make. The list is portalled to <body>,
+  // so its options are OUTSIDE the dialog's subtree: the dialog's own
+  // outside-press listener sees the pointerdown that picks one. Nothing here
+  // asserts a style — this passes only if that press is recognised as
+  // belonging to the dialog, and fails by the dialog vanishing mid-choice.
+  await chooseOption(page, operator, "startsWith");
+  await expect(page.locator("[data-pretable-filter-menu]")).toBeVisible();
+  await expect(dialog).toBeVisible();
+  await expect(operator).toHaveAttribute("data-pretable-value", "startsWith");
+
+  // Escape unwinds ONE layer per press: the list is the innermost dismissable
+  // thing, so the first press closes it and leaves the dialog standing (with
+  // focus back on the trigger, not lost to <body>); the second closes the
+  // dialog. A list that let Escape through would take both at once.
+  await operator.click();
+  await expect(list).toBeVisible();
+  await page.keyboard.press("Escape");
+  await expect(list).toHaveCount(0);
+  await expect(dialog).toBeVisible();
+  await expect(operator).toBeFocused();
+
+  await page.keyboard.press("Escape");
+  await expect(dialog).toBeHidden();
+});
diff --git a/apps/website/e2e/tool-panel.spec.ts b/apps/website/e2e/tool-panel.spec.ts
index dc45db83..a7a4bdb4 100644
--- a/apps/website/e2e/tool-panel.spec.ts
+++ b/apps/website/e2e/tool-panel.spec.ts
@@ -649,14 +649,12 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
   // order, every stop that exists everywhere is among them, and the walk ends
   // at the rail.
   //
-  // The two pickers are on THIS side of that line now. They were native
-  // `<select>`s — a stop in every browser — and are the kit's select-only
-  // combobox since SP2, whose trigger is a plain `<button>`; measured here,
-  // WebKit offers neither unless the preference is on. Their being stops at
-  // all is still asserted, just conditionally, alongside the other buttons.
+  // The two pickers are NOT on that side of the line. They were native
+  // `<select>`s — a stop in every browser — and the kit's combobox that
+  // replaced them carries an explicit `tabIndex={0}` for exactly that parity,
+  // so WebKit offers them regardless of the preference. Their exact position
+  // is asserted in every browser, alongside the operand field and the rail.
   const CONDITIONAL = new Set([
-    "data-pretable-filter-row-column",
-    "data-pretable-filter-row-operator",
     "data-pretable-filter-row-remove",
     "data-pretable-filter-add",
   ]);
@@ -675,9 +673,12 @@ test("filters: the pane is walkable and forward-Tab still exits the panel", asyn
   expect(isSubsequenceOf(FULL, seen), `walk was ${seen.join(" → ")}`).toBe(
     true,
   );
-  // The unconditional stops are asserted exactly: the operand field (a text
-  // input, which every browser offers) and the rail.
+  // The unconditional stops are asserted exactly: the two pickers (explicit
+  // tabindex), the operand field (a text input, which every browser offers)
+  // and the rail.
   expect(seen.filter((part) => !CONDITIONAL.has(part))).toEqual([
+    "data-pretable-filter-row-column",
+    "data-pretable-filter-row-operator",
     "data-pretable-filter-row-value",
     "data-pretable-tool-tab",
   ]);
@@ -860,12 +861,12 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   // roster after it is: the add-group button (a plain <button> — a
   // conditional stop, per the filters walk's WebKit note), expand/
   // collapse-all (DISABLED — never stops), the hide-grouped checkbox, one
-  // aggregate picker per column, then the rail. Only the rail tab, which
-  // carries an explicit tabindex, is a stop in every browser: the pickers
-  // used to be native `<select>`s but are the kit's combobox since SP2, whose
-  // trigger is a plain `<button>` — so they join the checkbox and the
-  // add-group button as the conditional RECORDED stops, per the platform's
-  // "Tab moves between all controls" preference.
+  // aggregate picker per column, then the rail. Two kinds of stop are offered
+  // in every browser: the rail tab and each aggregate picker, both of which
+  // carry an explicit tabindex — the picker's is what keeps the parity the
+  // native `<select>` it replaced had. The checkbox and the add-group button
+  // remain the conditional RECORDED stops, per the platform's "Tab moves
+  // between all controls" preference.
   const aggregateCount = await page
     .locator("[data-pretable-aggregate-row]")
     .count();
@@ -926,13 +927,15 @@ test("grouping: arrows reach its rail tab, Enter opens it, and forward-Tab exits
   expect(isSubsequenceOf(FULL, seen), `walk was ${seen.join(" → ")}`).toBe(
     true,
   );
-  // The one stop that exists in every browser: the rail, as the panel's last
-  // stop. The aggregate pickers used to be here too — they were native
-  // `<select>`s — but since SP2 each is the kit's combobox, whose trigger is
-  // a plain `<button>`, so they joined the conditional stops (WebKit offers
-  // none of them unless "Tab moves between all controls" is on).
-  const CONDITIONAL = new Set(["hide-grouped", "add-group", "aggregate-select"]);
-  expect(seen.filter((stop) => !CONDITIONAL.has(stop))).toEqual(["rail"]);
+  // The stops that exist in every browser, in order: one aggregate picker per
+  // column — each the kit's combobox, carrying the explicit tabindex the
+  // native `<select>` it replaced got for free — and then the rail, as the
+  // panel's last stop.
+  const CONDITIONAL = new Set(["hide-grouped", "add-group"]);
+  expect(seen.filter((stop) => !CONDITIONAL.has(stop))).toEqual([
+    ...Array<string>(aggregateCount).fill("aggregate-select"),
+    "rail",
+  ]);
   // And where the browser offers button stops at all, it must offer ALL of
   // them, in this exact order — a missing add-group, checkbox or aggregate
   // picker there is a real bug, not a policy. The filters walk's tail,
diff --git a/packages/ui/themes/excel.css b/packages/ui/themes/excel.css
index 1d691703..bcba68f7 100644
--- a/packages/ui/themes/excel.css
+++ b/packages/ui/themes/excel.css
@@ -9,11 +9,14 @@
 
 :root {
   /* Declared for the same reason pretable.css does: the browser paints the
-     scroll viewport's scrollbars and every native control inside the grid —
-     the filter dialog's operator select, its popup list — from this, not from
-     the tokens. Without it a dark-mode host keeps this grid's scrollbars light and a light
-     select popup, which is the one part of the surface a theme cannot reach
-     with a custom property. */
+     scroll viewport's scrollbars and the native chrome still left inside the
+     grid — the filter dialog's text and date inputs (and the date input's own
+     calendar popup), and the enum checklist's checkboxes — from this, not from
+     the tokens. Without it a dark-mode host keeps this grid's scrollbars
+     light and its inputs and checkboxes on a light field, which is the part
+     of the surface a theme cannot reach with a custom property. The operator picker is no longer
+     among them: it is the kit's own combobox, styled through
+     `data-pretable-select` and `data-pretable-listbox`. */
   color-scheme: light;
 
   /* Surfaces */
diff --git a/packages/ui/themes/material.css b/packages/ui/themes/material.css
index 7be67a44..b812ab81 100644
--- a/packages/ui/themes/material.css
+++ b/packages/ui/themes/material.css
@@ -14,11 +14,14 @@
 
 :root {
   /* Declared for the same reason pretable.css does: the browser paints the
-     scroll viewport's scrollbars and every native control inside the grid —
-     the filter dialog's operator select, its popup list — from this, not from
-     the tokens. Without it a dark-mode grid keeps light scrollbars and a light
-     select popup, which is the one part of the surface a theme cannot reach
-     with a custom property. */
+     scroll viewport's scrollbars and the native chrome still left inside the
+     grid — the filter dialog's text and date inputs (and the date input's own
+     calendar popup), and the enum checklist's checkboxes — from this, not from
+     the tokens. Without it a dark-mode grid keeps light scrollbars and its
+     inputs and checkboxes on a light field, which is the part of the surface
+     a theme cannot reach with a custom property. The operator picker is no longer
+     among them: it is the kit's own combobox, styled through
+     `data-pretable-select` and `data-pretable-listbox`. */
   color-scheme: light;
 
   /* Surfaces — M3 neutral grayscale (untinted by primary seed) */

From 02347f93c90dd5af251984b5c2772693db14d9e3 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 23:57:12 -0700
Subject: [PATCH 27/27] chore: changeset for components SP2

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .changeset/components-sp2-select.md | 44 +++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 .changeset/components-sp2-select.md

diff --git a/.changeset/components-sp2-select.md b/.changeset/components-sp2-select.md
new file mode 100644
index 00000000..4763362a
--- /dev/null
+++ b/.changeset/components-sp2-select.md
@@ -0,0 +1,44 @@
+---
+"@pretable/react": minor
+"@pretable/ui": patch
+---
+
+The kit's picker, and the four `<select>` elements in the grid rebuilt on it.
+
+`PretableSelect` is a `button[role="combobox"]` that opens a portalled listbox,
+with `PretableSelectProps`, `PretableSelectOption` and `PretableSelectComponent`
+alongside it and a `Select` slot on `PretableComponents` —
+`components={{ Select }}` on `<PretableSurface>` and `<Pretable>` replaces every
+picker in the grid, the same way `Button` and `IconButton` already do.
+`PretableBuiltInButtonSite` gains four names: `filter-operator`,
+`filter-row-column`, `filter-row-operator` and `aggregate`.
+
+**The four pickers are no longer `<select>` elements.** The filter dialog's
+operator, the tool panel's filter column and filter operator, and the grouping
+aggregate picker are now `button[role="combobox"]` triggers carrying
+`data-pretable-value`, which open a `[data-pretable-listbox]` of
+`[data-pretable-option][data-value]` in `document.body`. A test keyed on
+`select`, on `.value`, on Playwright's `selectOption()` or on `toHaveValue()`
+must read the attribute and click the option instead. Every site keeps the
+`data-pretable-*` attribute it already had, and the aggregate picker gains
+`data-pretable-aggregate`.
+
+**Keyboard.** Arrows, Enter and Space open a closed picker; arrows wrap and skip
+disabled options; Home and End jump to the ends; typing a prefix jumps to the
+first match (the buffer clears after 500ms); Enter or Space commits; Escape
+closes back to the trigger; Tab closes and moves on. `onChange` fires only when
+the value actually changes. The trigger is an explicit tab stop in every
+browser, which the native control was not in WebKit.
+
+A disabled option is shown, skipped and inert rather than hidden — that is the
+aggregate picker's `Custom` entry, a consumer-written aggregator the grid
+displays but never writes back.
+
+**Styling.** The enum cell editor's list is now the kit list, so
+`data-pretable-enum-listbox` and `data-pretable-enum-option` are gone, replaced
+by `data-pretable-listbox` and `data-pretable-option` — plus `[data-active]` for
+the roving highlight and `[aria-selected="true"]` for the current value. Tokens
+are unchanged.
+
+**Layout.** The tool panel's filter rows wrap less: a picker now sizes to its
+own label, with an ellipsis, instead of to its longest option.