pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/combobox/Combobox.variants.js

@@ -0,0 +1,280 @@
+"use strict";
+
+/**
+ * Combobox's pure data/style/behaviour resolution — same split every reference module uses:
+ *  - STRUCTURE (heights, padding, radius, border WIDTH) lives in the `createThemedVariants`
+ *    resolvers, registered once per theme identity.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveComboboxTriggerColors` /
+ *    `resolveComboboxRowColors` / `resolveComboboxErrorTextColor`, never a raw ramp, never a
+ *    hardcoded hex.
+ *  - ACCESSIBILITY prop derivation (`resolveComboboxAccessibility`, `resolveComboboxRowAccessibility`)
+ *    is kept pure so the "disabled blocks opening / expanded tracks the sheet / selected+disabled per
+ *    row" contract is unit-testable without rendering React Native.
+ *  - SEARCH/SELECTION logic (`defaultComboboxFilter`, `resolveComboboxSummary`) is pure too, so the
+ *    filtering and trigger-summary rules are unit-tested directly. `defaultComboboxFilter` is the
+ *    SPEC of the default local filter, and is what a caller-supplied `filterFn` replaces — but the
+ *    component no longer calls it per option: it memoizes one normalized-label array per `options`
+ *    identity and reuses it for every pass (`Combobox.tsx`), which must stay byte-identical to this
+ *    function's result (`Combobox.filter.test.ts` pins that).
+ *
+ * `ComboboxOption` lives here, not in `Combobox.tsx`: unlike `Select`'s/`MultiSelect`'s option types
+ * (which carry a `ReactNode leading` and so must live in the component file), every field here is a
+ * plain value — no React import needed — so it can be pure like the rest of this file.
+ *
+ * Free of React and of any `Modal`/`Pressable`/`TextInput` import, so the WCAG + logic tests import
+ * this directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/** Same touch-target floor as Button/Select/Input (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+
+/** No `size` prop (unlike Select/MultiSelect) — not part of this module's spec, and a search sheet's
+ *  proportions don't benefit from the sm/lg range those triggers offer. One fixed box, sized exactly
+ *  like Input's/Select's `md`, so a Combobox lines up with either in the same form. */
+export const COMBOBOX_FIELD_HEIGHT = 40;
+export const COMBOBOX_FIELD_FONT_SIZE = 16;
+export const COMBOBOX_FIELD_ICON_SIZE = 18;
+export const COMBOBOX_FIELD_HIT_SLOP = slopFor(COMBOBOX_FIELD_HEIGHT);
+
+/** The trigger's clear ("x") affordance, nested inside the field `Pressable` exactly like
+ *  `DatePicker`'s own clear button — RN's responder system resolves a touch to the innermost
+ *  `Pressable` that claims it, so the field's own `onPress` never also fires. Narrower than the
+ *  field is tall, so it reaches 44×44 through `hitSlop` rather than through its own width. */
+export const COMBOBOX_CLEAR_BUTTON_WIDTH = 32;
+export const COMBOBOX_CLEAR_BUTTON_HIT_SLOP = slopFor(COMBOBOX_CLEAR_BUTTON_WIDTH);
+
+/** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). Not a
+ *  fixed height: a row with a `description` line grows past this floor. */
+export const COMBOBOX_ROW_MIN_HEIGHT = 44;
+export const COMBOBOX_ROW_ICON_SIZE = 18;
+export const DEFAULT_PLACEHOLDER = "Select…";
+export const DEFAULT_SEARCH_PLACEHOLDER = "Search…";
+export const DEFAULT_EMPTY_MESSAGE = "No results";
+export const DEFAULT_MAX_HEIGHT = 320;
+
+/** `onSearchChange` debounce window — a fixed design constant, not a caller-facing prop (the spec
+ *  this module was built against fixes it at 250ms). */
+export const SEARCH_DEBOUNCE_MS = 250;
+
+/** Local-filter debounce — shorter than the networked `SEARCH_DEBOUNCE_MS`; only outruns a typing burst. */
+export const FILTER_DEBOUNCE_MS = 140;
+
+/**
+ * Strips combining diacritical marks after Unicode NFD decomposition, so "José" and "jose" match the
+ * same query. Lowercased last so the comparison is also case-insensitive.
+ */
+export function normalizeForSearch(value) {
+  return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+}
+
+/**
+ * The option list's container role — what makes `aria-activedescendant` on the search field mean
+ * anything. RN 0.86's role unions have no `listbox` (both `Role` and `AccessibilityRole` jump
+ * `list` → `listitem` → `log`), so the widening lives on this ONE audited line instead of a cast at
+ * the call site. It is a type gap, not a runtime one: `react-native-web` emits the string as the DOM
+ * `role` verbatim, and native maps roles it doesn't know to nothing.
+ */
+export const COMBOBOX_LISTBOX_ROLE = "listbox";
+
+/**
+ * The DOM id of one option row. `aria-activedescendant` and `nativeID` must agree exactly, and
+ * every `aria-*` prop is UNCHECKED by TypeScript on an RN component (hyphenated JSX attributes are
+ * not type-checked at all) — so the id is derived here once rather than interpolated at each call
+ * site, where a typo would silently produce a dangling reference no compiler would catch.
+ */
+export function comboboxOptionNativeId(listId, value) {
+  return `${listId}-option-${value}`;
+}
+
+/**
+ * The default local `filterFn`: case-insensitive, diacritic-insensitive substring match on `label`.
+ * An empty/whitespace-only query matches everything, so clearing the search box restores the full
+ * list instead of an empty one.
+ */
+export function defaultComboboxFilter(option, query) {
+  const trimmed = query.trim();
+  if (trimmed === "") return true;
+  return normalizeForSearch(option.label).includes(normalizeForSearch(trimmed));
+}
+/**
+ * The trigger's display text — one rule for both single and multiple mode, since single mode is just
+ * "at most one selected value" flowing through the same collapsing rule: 0 → placeholder, 1 → that
+ * option's label, 2 → both labels joined, 3+ → "N selected". A selected value with no matching option
+ * (e.g. stale data) falls back to "1 selected" / the raw value rather than rendering nothing.
+ */
+export function resolveComboboxSummary(input) {
+  const {
+    options,
+    selectedValues,
+    placeholder
+  } = input;
+  const count = selectedValues.length;
+  if (count === 0) return placeholder;
+  const labelFor = value => options.find(option => option.value === value)?.label;
+  if (count === 1) {
+    const [only] = selectedValues;
+    return (only === undefined ? undefined : labelFor(only)) ?? "1 selected";
+  }
+  if (count === 2) {
+    return selectedValues.map(value => labelFor(value) ?? value).join(", ");
+  }
+  return `${count} selected`;
+}
+/**
+ * Maps trigger state onto role colours — the reason there is no free-form `color` prop. `error`
+ * mirrors `Input.resolveInputStatus`'s exact precedence: the error border reads `status.danger.solid`
+ * (NOT `status.danger.border`, which measures below 3:1 on every brand — see `Input.test.ts`'s
+ * identical finding).
+ */
+export function resolveComboboxTriggerColors(colors, state) {
+  return {
+    background: colors.bg.surface,
+    border: state.error ? colors.status.danger.solid : colors.border.interactive,
+    text: colors.fg.default,
+    placeholder: colors.fg.muted,
+    icon: colors.fg.muted
+  };
+}
+
+/** The error message under the field, read on the canvas — same role `Input.resolveInputStatus` uses
+ *  for its own `errorText`. */
+export function resolveComboboxErrorTextColor(colors) {
+  return colors.status.danger.text;
+}
+export function resolveComboboxRowColors(colors) {
+  return {
+    background: colors.bg.surface,
+    text: colors.fg.default,
+    muted: colors.fg.muted,
+    icon: colors.fg.muted,
+    checkIcon: colors.fg.default,
+    pressedRow: colors.bg.sunken
+  };
+}
+/**
+ * Derives the field's accessibility surface once, purely: `expanded` tracks whether the sheet is
+ * showing (WCAG 4.1.2), `disabled` blocks it from opening at all.
+ */
+export function resolveComboboxAccessibility(input) {
+  const disabled = input.disabled === true;
+  return {
+    accessibilityRole: "combobox",
+    "aria-disabled": disabled,
+    "aria-expanded": input.open,
+    disabled
+  };
+}
+/**
+ * Every row is `menuitem` (matching this library's `Menu`), in BOTH single and multiple mode — the
+ * spec this module was built against fixes this role regardless of mode, unlike `MultiSelect`'s own
+ * `checkbox` rows. Selection state rides `aria-selected`, never `aria-checked`.
+ */
+export function resolveComboboxRowAccessibility(input) {
+  return {
+    accessibilityRole: "menuitem",
+    "aria-selected": input.selected,
+    "aria-disabled": input.disabled,
+    disabled: input.disabled
+  };
+}
+
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (state-driven,
+ * applied inline over this), so this compiles once per theme identity via the themed resolver.
+ */
+export const comboboxFieldStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    height: COMBOBOX_FIELD_HEIGHT,
+    paddingHorizontal: theme.space[4],
+    borderRadius: theme.radii.base,
+    borderWidth: theme.borderWidths.thin
+  }
+}));
+
+/** The open-target's own inner row — the selected option's icon (single mode) + the summary text,
+ *  kept in one shrinkable cluster so the clear button and chevron stay pinned to the trailing edge. */
+export const comboboxFieldValueStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2]
+  }
+}));
+export const comboboxClearButtonStructure = createThemedVariants(theme => ({
+  base: {
+    width: COMBOBOX_CLEAR_BUTTON_WIDTH,
+    alignSelf: "stretch",
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: theme.radii.sm
+  }
+}));
+
+/** The full-screen overlay the sheet centers in — byte-identical to `Select`'s. `box-none` (applied
+ *  by the component) lets a tap on its empty padding fall through to the backdrop press underneath. */
+export const comboboxOverlayStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    justifyContent: "center",
+    paddingHorizontal: theme.space[6]
+  }
+}));
+
+/** No `maxHeight` baked in here — it is the one caller-configurable dimension (`maxHeight` prop,
+ *  default `DEFAULT_MAX_HEIGHT`) and is applied inline over this at the component boundary. */
+export const comboboxSheetStructure = createThemedVariants(theme => ({
+  base: {
+    borderRadius: theme.radii.base,
+    ...theme.elevation.lg
+  }
+}));
+
+/** The search row's bottom border doubles as the divider between it and the option list — one fewer
+ *  node than a dedicated `Divider`. Colour (`border.default`, the decorative rung) is applied inline. */
+export const comboboxSearchRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    height: COMBOBOX_FIELD_HEIGHT,
+    paddingHorizontal: theme.space[4],
+    borderBottomWidth: theme.borderWidths.thin
+  }
+}));
+
+/** The loading spinner / empty-message container — centered in the space the option list would
+ *  otherwise occupy. */
+export const comboboxListStateStructure = createThemedVariants(theme => ({
+  base: {
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: theme.space[6],
+    paddingHorizontal: theme.space[4]
+  }
+}));
+export const comboboxRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: COMBOBOX_ROW_MIN_HEIGHT,
+    columnGap: theme.space[3],
+    paddingHorizontal: theme.space[4],
+    paddingVertical: theme.space[2]
+  }
+}));
+
+/** The label + optional description cluster — `rowGap` mirrors `ListItem`'s identical title/subtitle
+ *  spacing. */
+export const comboboxRowTextStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    rowGap: theme.space[1]
+  }
+}));
+//# sourceMappingURL=Combobox.variants.js.map

package/lib/module/modules/combobox/MODULE.md

@@ -0,0 +1,183 @@
+# combobox/ — a searchable/filterable select in a native-Modal sheet
+
+`Combobox` is a `Select`/`MultiSelect` sibling that adds search: a trigger field opens a sheet in
+React Native's OWN `Modal` (never this library's own), containing an autofocused search box above a
+filtered option list. It is a NEW module, not a `searchable` prop on `Select` — a text input owning
+focus, live filtering, an async/loading path, and a "no results" state is a materially different
+interaction model, and bolting that onto `Select` would double its complexity for every existing
+caller who never needs search.
+
+Two narrow, deliberate cross-module reads: `../modal/ModalPortalContext` + `../modal/renderWebPortal`
+(a plain context + stateless helper, not the `Modal` component — the same web-portal opt-in
+`Select`/`MultiSelect`/`Menu` use), and `Spinner` (a small, dependency-free leaf this library already
+reuses directly, e.g. from `SearchBar`).
+
+## Files
+
+| File | Role |
+|------|------|
+| `Combobox.tsx` | The component. Trigger + `Modal` composition, open/close + search-query state, local/server filtering, single/multiple selection. |
+| `Combobox.variants.ts` | `ComboboxOption`, pure resolvers (filtering, trigger-summary text, colours, hitSlop, accessibility) + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `Combobox`, `ComboboxProps`, `ComboboxSingleProps`, `ComboboxMultipleProps`, `ComboboxOption`, `IconName`. |
+| `__tests__/Combobox.test.ts` | Pure: WCAG contrast (all brands × modes), touch target, filtering, trigger-summary, and accessibility contracts. |
+| `__tests__/Combobox.render.test.tsx` | Render: display, open/close, search filtering, single vs. multiple selection, clear, loading/empty states, web-portal opt-in, `keyboardShouldPersistTaps`, the row's resolved 44dp `minHeight`. |
+| `comboboxKeys.ts` / `.web.ts` | This module's own arrow/Home/End/Enter listener — see Keyboard below for why `core/a11y`'s `useRovingKeys` cannot be used here. |
+| `__tests__/Combobox.keyboard.test.tsx` | Web keyboard: `aria-activedescendant` tracks the arrows, Enter selects, Space stays with the search field, Escape closes, trigger opens on Space. |
+| `__tests__/Combobox.filter.test.tsx` | The memoized filter matches `defaultComboboxFilter` exactly across diacritics/mixed case; a `filterFn` still runs per option. |
+| `__tests__/Combobox.layout.test.tsx` | `getItemLayout` is derived for uniform rows and absent as soon as one option has a `description`. |
+| `__tests__/Combobox.motion.test.tsx` | Reduce-motion (WCAG 2.3.3): check-glyph and press feedback snap to their final values, and `Animated.timing` is never called. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `options` | `ComboboxOption[]` (`{ value; label; icon?: IconName; description?: string; disabled?: boolean }`) | — | Required. |
+| `value` / `onChange` | `string \| null` / `(value) => void` | — | Single mode (`multiple` absent/`false`). Required in that member of the union. |
+| `multiple` | `true` | `false` | Switches to multi mode. |
+| `values` / `onValuesChange` | `string[]` / `(values) => void` | — | Required when `multiple: true`. |
+| `placeholder` | `string` | `"Select…"` | |
+| `searchPlaceholder` | `string` | `"Search…"` | |
+| `label` | `string` | — | Above the field; folded into its accessible name. |
+| `disabled` | `boolean` | `false` | Blocks opening; dims the field. |
+| `error` | `string` | — | Red border + message below the field, announced on both platforms via `useAnnounce` (`core/a11y`) — was `accessibilityLiveRegion` alone, silent on iOS. |
+| `clearable` | `boolean` | `true` | Shows an "x" on the field once something is selected. |
+| `loading` | `boolean` | `false` | Swaps the LIST area (not the search field) for a centered `Spinner`. |
+| `emptyMessage` | `string` | `"No results"` | |
+| `onSearchChange` | `(query: string) => void` | — | Presence = server-side filtering: `options` render verbatim, `filterFn` is ignored, `Combobox` never filters locally. Debounced 250ms. Absence = local filtering. **The prop most likely to be misused** — it replaces local filtering, never adds to it. |
+| `filterFn` | `(option, query) => boolean` | `defaultComboboxFilter` | Local filtering only. Default is case- and diacritic-insensitive substring match on `label`. |
+| `maxHeight` | `number` | `320` | Caps the whole sheet (search row + list), not the list alone. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Seeds `-backdrop`, `-search`, `-spinner`, `-option-${value}` (+ `-content` / `-check` on that row's animated nodes), `-clear`, `-focus-ring`. |
+
+No `size` prop — one fixed box sized like `Input`'s/`Select`'s `md`. `ComboboxProps` is a
+**discriminated union**, not one flat interface: `multiple: true` requires `values`/`onValuesChange`,
+the default requires `value`/`onChange` — a caller can never wire the wrong pair for the active mode
+and have it silently do nothing. A deliberate refinement past the spec's flat prose description.
+
+**Trigger summary text** — one rule for both modes (single mode is "at most one selected value"
+through the same collapsing rule): 0 → placeholder, 1 → that option's label, 2 → both labels joined,
+3+ → `"N selected"`.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2** — the field is `accessibilityRole="combobox"` with flat `aria-expanded` tracking the
+  sheet. Rows are `accessibilityRole="menuitem"` (matching `Menu`, in BOTH single and multiple
+  mode — this module's own spec, unlike `MultiSelect`'s `checkbox` rows) with flat `aria-selected` /
+  `aria-disabled`. Flat, never `accessibilityState={{…}}`: react-native-web discards the object form
+  — see `docs/PLATFORM-A11Y-PROPS.md`.
+- **2.5.x target size** — the field reaches ≥ 44dp via `hitSlop`; the clear button — nested inside
+  the field `Pressable`, same structure as `DatePicker`'s — reaches 44×44 the same way; option rows
+  have a 44dp `minHeight` directly.
+- **1.4.3** — field/placeholder text, the label, option labels, descriptions, the search box's own
+  text, and the empty-state message are each measured ≥ 4.5:1 against their fill (including the row's
+  own pressed background), all 8 brands × both modes.
+- The search box carries its own `accessibilityLabel` (the `searchPlaceholder` text) — it has no
+  visible label of its own, and the leading `search` glyph is decorative.
+- **1.4.11** — the field boundary and the selected row's "check" glyph are measured ≥ 3:1.
+- The empty state carries `accessibilityLiveRegion="polite"` on Android (iOS/VoiceOver announces a
+  text-content change in an already-visible node without it).
+- **2.3.3** — RN's `Modal animationType` is always `"none"`; the reveal is `core/motion`'s
+  `useReveal`, which snaps to the final state (no tween) under reduce-motion. Row press feedback and
+  the check fade go through the same `motion.enabled` gate. Covered by
+  `__tests__/Combobox.motion.test.tsx`.
+- Disabled is exempt from the contrast minimum (WCAG 1.4.3) — signalled by `opacity: 0.5`, matching
+  every sibling picker.
+
+## Patterns copied from the reference modules
+
+1. **Structure vs colour split**, **pure testable resolvers**, no `{...rest}`, `style` once, outermost, last.
+2. **RN's own `Modal`**, never this library's — same reasoning as `Select`/`MultiSelect`/`Menu`.
+3. **Built only while `open`** — the whole sheet mounts nothing while closed.
+4. **`core/list`'s `VirtualList`, not `.map()`** — the option list windows a large roster, same as
+   `Select`/`MultiSelect`.
+5. **The field is a single `Pressable`, clear button nested inside it** — copied from `DatePicker`:
+   the whole visual box (including the trailing chevron) opens the sheet, and RN's responder system
+   resolves a press on the nested clear button to that `Pressable` alone, so it never also fires the
+   field's own `onPress`.
+
+## Design decisions specific to this module
+
+- **The search field is its own local `TextInput`, not this library's `Input`** — `SearchBar` already
+  established why: `Input` is not `forwardRef` and exposes no `autoFocus` surface. Duplicates
+  `Input`'s size/role-colour contract locally rather than re-litigating that precedent.
+- **Autofocus is belt-and-braces**: the `TextInput`'s own `autoFocus`, PLUS the native `<Modal>`'s
+  `onShow` imperatively calling `.focus()` via a ref — `autoFocus` alone is flaky timing-wise inside
+  a native `Modal` on iOS.
+- **The trigger's focus/open ring is `Input`'s offset ring**, not `Select`/`MultiSelect`'s
+  border-colour swap (their own docs flag that as provisional). The border itself is `error`-driven
+  only — a border swap AND a ring would double-signal the same state.
+- **`loading` swaps the LIST, not the search field's leading icon** (unlike `SearchBar`) — the spec
+  places the spinner "in the list area", so the search box keeps a static `search` glyph throughout.
+- **Closing the sheet resets the search query** (and cancels any pending debounce) so a reopen always
+  starts clean.
+- **`keyboardShouldPersistTaps="handled"`** on the `VirtualList` — otherwise a row tap while the
+  search field still has focus is swallowed as a keyboard-dismiss instead of a selection (WCAG
+  2.1.1). The search field autofocuses on every open, so this is the normal path, not an edge case.
+  `VirtualList` forwards the prop to both its FlashList and FlatList branches.
+
+## Keyboard (web)
+
+**`aria-activedescendant`, not roving focus.** DOM focus must stay in the search `TextInput` — moving
+it into the list stops the user typing — so the arrows move only which option the field points at.
+Each row gets a `nativeID` from `comboboxOptionNativeId()` (the one typed helper; every `aria-*` prop
+is completely unchecked by TS, so the id is never interpolated at a call site) and every row is
+`tabIndex={-1}`, leaving the field as the sheet's only tab stop. The active row is tinted with
+`pressedRow`, since there is no focus ring to show it.
+
+`useDismissOnEscape` + `useFocusTrap` come from `core/a11y/keyboard`; the trigger takes
+`useSpaceActivation` (`role="combobox"` is not `button`, so RNW leaves Space dead there).
+
+**The arrows come from this module's own `comboboxKeys.ts` / `.web.ts` pair, not `useRovingKeys`** —
+that helper `preventDefault()`s Space unconditionally, which in a container holding a `TextInput`
+makes the space bar untypable in the search box. A core option to opt out of Space activation would
+let this collapse back into `useRovingKeys`.
+
+The list container is `COMBOBOX_LISTBOX_ROLE`: RN 0.86's role unions have no `listbox`, so the
+widening is one audited cast in `Combobox.variants.ts`.
+
+## Known gaps
+
+- No per-brand-verified imperative-focus behaviour under a real device/OS — not verifiable from a Jest
+  render test (the mocked `Modal` submodule never calls `onShow`).
+- No measured anchor position — the sheet always centers, same known gap `Select`/`Menu` document.
+- **Arrowing past the mounted window does not scroll.** `core/list` exposes no imperative handle,
+  so on a long list End can name an option the list has not mounted. Needs a `scrollToIndex` there.
+
+## Performance
+
+Wrapped in `React.memo`. The option list is `core/list`'s `VirtualList`, built only while `open`;
+`filteredOptions` is `useMemo`'d over the *debounced* query, so a keystroke updates the visible text
+without re-filtering the whole roster.
+
+**The default filter does not call `defaultComboboxFilter` per option.** That function's whole cost is
+`normalizeForSearch(label)` — an NFD normalization plus two allocations, per option, per pass.
+`Combobox` memoizes one normalized-label array per `options` identity instead: measured on 5000
+options, 1.99 ms/pass → 0.10 ms (20×; hoisting only the query buys 1.3×). `defaultComboboxFilter`
+remains the exported SPEC and `Combobox.filter.test.tsx` pins the fast path to it byte-for-byte. A
+caller-supplied `filterFn` keeps the per-option path — it reads the raw `label`.
+
+**`itemHeight` is passed only when no option has a `description`.** It derives `getItemLayout`, whose
+offsets are exact only for uniform rows, and a description row computes to ≈54dp against the 44 that
+was being claimed — thousands of options deep that is blank gaps and a lying scrollbar
+(`core/MODULE.md`). Mixed lists measure instead. The
+debounce handler is `useCallback`'d since it owns a ref'd timer, mirroring `SearchBar`'s identical
+handler.
+
+## Motion
+
+Via `core/motion` only — `opacity`/`transform`, native driver, all reduce-motion aware.
+
+- **Row press** — `usePressMotion(rowDisabled)`; the row's content `Animated.View` (which carries
+  `comboboxRowStructure`, including the 44dp `minHeight`) scales/dips, while the `Pressable` keeps
+  the `pressedRow` background. `scale` is a transform, so the row's hit area is unaffected.
+- **Check glyph** — fades in/out on selection change, but a row that mounts already-selected
+  (scrolled into view) snaps: a `skipFirst` ref suppresses the first effect run.
+- **Sheet reveal** — `useReveal(open)`, the no-state variant: the sheet subtree is gated on `open`
+  (the same flag `<Modal visible>` uses), so there is no second source of truth and no extra render
+  per open/close. See `Select`/`MultiSelect` — all three pickers use this one gate.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.

package/lib/module/modules/combobox/comboboxKeys.js

@@ -0,0 +1,19 @@
+"use strict";
+
+/**
+ * Native/default counterpart of `comboboxKeys.web.ts` — the `core/a11y/keyboard.ts` pattern, local
+ * to this module. Physical-keyboard interaction is a web concern, so this is a no-op with an
+ * identical signature, and Metro keeps the DOM half out of the native graph entirely.
+ *
+ * **Why this exists instead of `core/a11y`'s `useRovingKeys`.** That helper is the right one for
+ * `menu`/`select`/`multi-select`, but its Enter/Space branch calls `preventDefault()`
+ * unconditionally — and this container holds the search `TextInput`. Attaching it here would make
+ * the space bar untypable in the search field, so Combobox handles the four navigation keys plus
+ * Enter itself and leaves Space entirely to the input. Everything else it needs (Escape, the focus
+ * trap) still comes from `core/a11y/keyboard`.
+ */
+
+export function useComboboxKeys(_ref, _active, _options) {
+  return;
+}
+//# sourceMappingURL=comboboxKeys.js.map

package/lib/module/modules/combobox/comboboxKeys.web.js

@@ -0,0 +1,76 @@
+"use strict";
+
+/**
+ * Web implementation of Combobox's own arrow-key navigation. Metro resolves this file only for a
+ * web bundle (see `comboboxKeys.ts`, which also documents why `core/a11y`'s `useRovingKeys` cannot
+ * be used for this particular container), so it is free to assume a DOM.
+ *
+ * DOM types are hand-written for the same reason `core/a11y/keyboard.web.ts` and
+ * `modules/modal/renderWebPortal.web.ts` hand-write theirs: `tsconfig.json` sets `"lib": ["ESNext"]`,
+ * so `document`/`HTMLElement`/`KeyboardEvent` do not exist as types, `any` is lint-banned, and
+ * augmenting `react-native`'s types would ship through `lib/typescript/**`.
+ */
+
+import { useEffect, useRef } from "react";
+/** RNW forwards a component's ref to the host element, so a `RefObject<View>` holds a DOM node. */
+function domNode(ref) {
+  return ref.current ?? null;
+}
+
+/**
+ * Arrow/Home/End/Enter navigation for the `aria-activedescendant` listbox pattern: focus never
+ * leaves the search field, only the active index moves.
+ *
+ * Listens on the CONTAINER in the CAPTURE phase — that is what gets past the focused `TextInput`,
+ * whose own key handling runs while the event bubbles.
+ */
+export function useComboboxKeys(ref, active, options) {
+  // Options are a fresh object each render; a ref keeps the listener subscribed once.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    if (!active) return;
+    const node = domNode(ref);
+    if (node === null) return;
+    const moveTo = next => {
+      const {
+        count,
+        onActiveIndexChange
+      } = optionsRef.current;
+      if (count <= 0) return;
+      onActiveIndexChange((next % count + count) % count);
+    };
+    const handleKeyDown = event => {
+      const opts = optionsRef.current;
+      switch (event.key) {
+        case "ArrowDown":
+          event.preventDefault();
+          moveTo(opts.activeIndex + 1);
+          return;
+        case "ArrowUp":
+          event.preventDefault();
+          moveTo(opts.activeIndex - 1);
+          return;
+        case "Home":
+          event.preventDefault();
+          moveTo(0);
+          return;
+        case "End":
+          event.preventDefault();
+          moveTo(opts.count - 1);
+          return;
+        case "Enter":
+          if (opts.count <= 0) return;
+          event.preventDefault();
+          opts.onActivate(opts.activeIndex);
+          return;
+        // Space is NOT an activation key here: it is a character the search field must receive.
+        default:
+          return;
+      }
+    };
+    node.addEventListener("keydown", handleKeyDown, true);
+    return () => node.removeEventListener("keydown", handleKeyDown, true);
+  }, [active, ref]);
+}
+//# sourceMappingURL=comboboxKeys.web.js.map

package/lib/module/modules/combobox/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/combobox`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers (`resolveComboboxTriggerColors`, `defaultComboboxFilter`, …)
+ * stay internal — a consumer configures a Combobox through its props, never by importing its
+ * internals.
+ */
+
+export { Combobox } from "./Combobox.js";
+
+// Re-exported so a caller can type `ComboboxOption.icon` without a separate import from `core/icon`.
+//# sourceMappingURL=index.js.map