pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/multi-select/MODULE.md

@@ -18,17 +18,19 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 
 | File | Role |
 |------|------|
-| `MultiSelect.tsx` | The component. Trigger + `Modal` composition, open/close state, immediate per-row toggling, focus handling. |
+| `MultiSelect.tsx` | The component. Trigger + `Modal` composition, open/close state, immediate per-row toggling, focus handling. Option list is `core/list`'s `VirtualList` (device-tier windowing over FlashList-or-FlatList), built only while `open`. |
 | `MultiSelect.variants.ts` | Pure resolvers (`MULTI_SELECT_SIZES`, `resolveMultiSelectTriggerColors`, `resolveMultiSelectRowColors`, `resolveMultiSelectAccessibility`) + the themed structural resolvers (`multiSelectTriggerStructure`, `multiSelectOverlayStructure`, `multiSelectSheetStructure`, `multiSelectHeaderStructure`, `multiSelectCloseButtonStructure`, `multiSelectRowStructure`, `multiSelectRowIndicatorStructure`). No React, no lucide. |
 | `index.ts` | Public surface: `MultiSelect`, `MultiSelectProps`, `MultiSelectOption`, `MultiSelectSize`. |
 | `__tests__/MultiSelect.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
-| `__tests__/MultiSelect.render.test.tsx` | Render: trigger summary text, open/close, disabled gating, immediate toggling, per-row `checked` state, backdrop + close-button dismissal, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/MultiSelect.render.test.tsx` | Render: trigger summary text, open/close, disabled gating, immediate toggling, per-row `checked` state, backdrop + close-button dismissal, the row's resolved 44dp `minHeight`, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/MultiSelect.keyboard.test.tsx` | Web keyboard: roving tabindex, arrows/Home/End, Space toggling, Escape — plus that the identity-stable `toggleValue` still reads the latest `values`. |
+| `__tests__/MultiSelect.motion.test.tsx` | Reduce-motion (WCAG 2.3.3): indicator check and press feedback snap to their final values, and `Animated.timing` is never called. |
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `options` | `{ label: string; value: string }[]` | — | Required. |
+| `options` | `{ label: string; value: string; leading?: ReactNode }[]` | — | Required. `leading` is an optional fixed-size adornment (e.g. an avatar) rendered between the checkbox indicator and the row label — the ReactNode content-slot precedent set by `ListItem`'s `leading`. Rows only; the trigger keeps its text-only summary. |
 | `values` | `string[]` | — | Required. The currently selected `value`s. |
 | `onValuesChange` | `(values: string[]) => void` | — | Required. Fired immediately on row press with the next array — no separate Apply/Cancel. |
 | `placeholder` | `string` | — | Shown when `values` is empty. |
@@ -36,7 +38,7 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 | `disabled` | `boolean` | `false` | Blocks opening the sheet; dimmed like Select's disabled state. |
 | `size` | `sm \| md \| lg` | `md` | 32 / 40 / 48 dp; short sizes reach 44 via `hitSlop`. |
 | `containerStyle` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
-| `testID` | `string` | — | Also seeds `${testID}-backdrop`, `${testID}-close`, and `${testID}-option-${value}`. |
+| `testID` | `string` | — | Also seeds `${testID}-backdrop`, `${testID}-close`, and `${testID}-option-${value}` (+ `-content` / `-check` on that row's animated nodes). |
 
 No `icon` prop — the chevron/check/close glyphs are fixed to the component's own semantics, not
 caller-configurable.
@@ -53,22 +55,25 @@ caller-configurable.
 - **2.5.x target size** — the trigger reaches ≥ 44dp via `hitSlop` at every size; option rows have a
   44dp `minHeight` directly (list items, not slop-expandable); the header close button reaches 44dp
   via `hitSlop`.
-- **4.1.2** — the trigger is `accessibilityRole="button"` with `accessibilityState.expanded`
-  tracking whether the sheet is showing.
+- **4.1.2** — the trigger is `accessibilityRole="button"` with flat `aria-expanded` tracking whether
+  the sheet is showing (never `accessibilityState={{…}}` — react-native-web discards the object
+  form, see `docs/PLATFORM-A11Y-PROPS.md`).
 - **1.4.3** — trigger value/placeholder text, the field label, and option-row labels are measured
   ≥ 4.5:1 against their own fill (`bg.canvas` for the label, `bg.surface` for the trigger and every
   row — row fill is constant across selection, see below).
 - **1.4.11** — the trigger boundary (`border.interactive`, `border.focus` while focused/open), the
   row indicator's unchecked outline, and its checked fill are each measured ≥ 3:1 against the sheet
   fill.
-- Each option row is `accessibilityRole="checkbox"` with `accessibilityState={{ checked }}`, toggled
-  immediately on press — the indicator box (outline when unchecked, `accent.solid` fill + "check"
-  glyph when checked) is the sighted echo of the same state, never the only signal.
+- Each option row is `accessibilityRole="checkbox"` with flat `aria-checked`, toggled immediately on
+  press — the indicator box (outline when unchecked, `accent.solid` fill + "check" glyph when
+  checked) is the sighted echo of the same state, never the only signal.
 - The header close button is `accessibilityRole="button"` with a fixed `accessibilityLabel="Close"`
   (icon-only, hardcoded — not a caller-configurable slot); its icon shares the row label's colour
   pairing, already measured ≥ 3:1 (in practice ≥ 4.5:1) on the sheet fill.
-- **2.3.3** — the sheet's `animationType` is `"none"` instead of `"fade"` when `useReducedMotion()`
-  is true.
+- **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 indicator's check fade go through the same `motion.enabled` gate. Covered by
+  `__tests__/MultiSelect.motion.test.tsx`.
 - Disabled is exempt from the contrast minimum (WCAG 1.4.3) — like Select, it's signalled by a
   uniform `opacity: 0.5` dim rather than a separate, still-must-pass colour pair.
 
@@ -82,19 +87,80 @@ caller-configurable.
    `accent.solid` / `accent.onSolid`) — duplicated locally, not imported: modules never import
    across `src/modules/*`.
 4. **Closed-ish surface** — `size` is a closed union; `options`/`values`/`onValuesChange` are the
-   data contract a multi-select inherently needs, not a colour escape hatch.
-5. `style` exception — MultiSelect exposes `containerStyle` (the documented exception for a
-   component wrapping a native primitive's outer box), not a second `style` prop.
+   data contract a multi-select inherently needs, not a colour escape hatch. `containerStyle` is the
+   one `style` exception (a component wrapping a native primitive's outer box), not a second `style` prop.
+
+## Keyboard (web)
+
+Wired to `core/a11y/keyboard` (all no-ops on native). The option list is **one tab stop**: exactly one
+row carries `tabIndex={0}` (`focusItemProps`) and the arrows / Home / End / typeahead move it
+(`useRovingKeys` on the sheet, capture phase). Opening lands it on the **first **selected** option, not the
+first (WCAG 2.4.3). Each row focuses itself when it becomes active — the tabindex alone only names
+the tab stop, and `useFocusTrap` needs the focused node to still be tabbable or Tab escapes the
+sheet. `useFocusTrap` also restores focus to the trigger on close; `useDismissOnEscape` closes on
+Escape.
+
+**`useRovingKeys` gets no `onActivate`.** RNW already presses a row on Enter, and Space is
+supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `button` tag/role, which
+`checkbox` deliberately is not) — passing `onActivate` too would toggle twice, i.e. not at all.
+
+The list container is `MULTI_SELECT_LISTBOX_ROLE`: RN 0.86's role unions have no `listbox`, so the
+widening is one audited cast in `MultiSelect.variants.ts` rather than a cast at the call site.
 
 ## Known gaps
 
-- No search/filter — matches the spec this module was built against. A future `Combobox` would be a
-  separate module, not a prop added here (closed-prop-contract).
-- No per-option `disabled` — every row is togglable whenever the sheet is open; not requested by
-  this module's spec.
+- No search/filter, no per-option `disabled` — matches the spec this module was built against; a
+  future `Combobox` would be a separate module, not props added here (closed-prop-contract).
 - The trigger's focus ring is a border-colour swap (`border.focus`), same convention `Select`
   documents as provisional pending a dedicated `Input` focus-ring reconciliation.
+- The trigger summarises selection as text ("N selected"), not chips/tokens — so there is no
+  add/remove chip motion. A chip surface would be a new API, not a prop added here.
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Its one library child, `Icon`, only ever receives primitives; the `options.map()` list renders host `Pressable`/`View`/`Text` — nothing to memoize.
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The option
+list is a `VirtualList`, not a full `.map()` in a `ScrollView` — a large roster only mounts rows near the
+viewport — and the sheet is built only while `open`. Rows get `bg.sunken` press feedback
+(`pressedRow`, same non-`bg.hover` reasoning as `RadioGroup`/`Accordion`), measured in `MultiSelect.test.ts`.
+
+### Re-render contract (what keeps `MultiSelectOptionRow`'s `memo` alive)
+
+- **Membership is O(1)** — `values` becomes a `useMemo`'d `Set`, so `renderItem` no longer runs
+  `values.includes(...)` per row (O(n·m) across the list).
+- `resolveMultiSelect*Colors` / `resolveMultiSelectAccessibility` and the `multiSelect*Structure(theme)`
+  resolvers are `useMemo`'d on their real inputs. `rowColors` is a row prop — unmemoized it
+  re-rendered every visible row on any parent render, making the row memo dead.
+- The single-selection `options.find(...)` is `useMemo`'d; `renderItem`/`keyExtractor`/`toggleValue`
+  and the focus/blur handlers are `useCallback`'d.
+- **`toggleValue` reads `values` through a ref, so its identity never changes.** As a dependency it
+  was re-created on every toggle (`values` necessarily changes), which defeated `React.memo` on
+  *every* mounted row rather than just the one whose `checked` flipped. Virtualization caps that at
+  ~10-20 wasted row renders per tap, each re-running four `useMemo`s — small, but free to remove.
+  `renderItem`'s own dependency on `selectedValues` is correct and stays.
+- **`MultiSelectOption.leading` is rendered into a fixed slot** (`multiSelectRowLeadingStructure`).
+  An unconstrained consumer node could make a row taller than 44dp and falsify the list's
+  `getItemLayout` offsets; the slot keeps the uniform fast path true by construction.
+- Style arrays feeding hot nodes (root container, trigger, sheet, header, label/value text) are
+  `useMemo`'d; the backdrop is a static `StyleSheet` entry. Inside the row, the row and indicator
+  structures are memoized so the `Pressable` style callback doesn't rebuild them per press-state flip.
+
+## Motion
+
+Via `core/motion` only — `opacity`/`transform`, native driver, all reduce-motion aware.
+
+- **Row press** — `usePressMotion()`; the row's content `Animated.View` (which carries
+  `multiSelectRowStructure`, 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.
+- **Indicator check glyph** — fades on toggle, but a row that mounts already-checked (scrolled into
+  view) snaps: a `skipFirst` ref suppresses the first effect run, so nothing animates during
+  scrolling. The indicator's own border/fill colours still flip instantly (colour is never animated).
+- **Sheet reveal** — `useReveal(open)` on the inner sheet panel, the no-state variant: the subtree is
+  gated on `open` — the same flag `<Modal visible>` uses — so there is no second source of truth to
+  disagree with it, and no extra render per open/close. See `select/MODULE.md`'s Motion section for
+  why `useEnterExit`'s `mounted` gate was dropped; `Select`/`Combobox` use the identical gate.
+- No chip/token UI on the trigger, so there is nothing to animate there (see Known gaps).
+
+## 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.

package/lib/module/modules/multi-select/MultiSelect.js

@@ -1,32 +1,123 @@
 "use strict";
 
 /**
- * MultiSelect — a trigger styled like Select/Input that opens a checkbox-style option list in React
- * Native's OWN `Modal`. Imported directly from `"react-native"` here on purpose, and built as a
- * standalone sibling of `Select` rather than on top of it: selection semantics differ enough
- * (multiple values, a running "N selected" summary, checkbox-row indicators instead of a single
- * check mark) that importing Select would force awkward prop overloading — and this module must not
- * depend on any sibling module, including the library's own Modal (built in parallel elsewhere).
- *
- * The one deliberate exception is the web portal mechanism: `ModalPortalContext`/`renderWebPortal`
- * are a plain context + a stateless helper with no React-tree footprint of their own (not the
- * `Modal` component), so MultiSelect reads the same ones `Modal.tsx`/`Select.tsx` read to stay
- * consistent once a consumer opts in via `ModalPortalProvider` — see `../modal/ModalPortalContext.ts`.
+ * MultiSelect — a trigger styled like Select/Input that opens a checkbox-style option list.
  */
 
-import { memo, useContext, useState } from "react";
-import { Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Modal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { focusItemProps, useDismissOnEscape, useFocusTrap, useRovingKeys, useSpaceActivation } from "../../core/a11y/keyboard";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { VirtualList } from "../../core/list/index.js";
+import { useMotion, usePressMotion, useReveal } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "../modal/ModalPortalContext.js";
 import { renderWebPortal } from "../modal/renderWebPortal";
-import { MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP, MULTI_SELECT_CLOSE_ICON_SIZE, MULTI_SELECT_ROW_ICON_SIZE, MULTI_SELECT_SIZES, multiSelectCloseButtonStructure, multiSelectHeaderStructure, multiSelectOverlayStructure, multiSelectRowIndicatorStructure, multiSelectRowStructure, multiSelectSheetStructure, multiSelectTriggerStructure, resolveMultiSelectAccessibility, resolveMultiSelectRowColors, resolveMultiSelectTriggerColors } from "./MultiSelect.variants.js";
+import { MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP, MULTI_SELECT_CLOSE_ICON_SIZE, MULTI_SELECT_LISTBOX_ROLE, MULTI_SELECT_ROW_ICON_SIZE, MULTI_SELECT_ROW_MIN_HEIGHT, MULTI_SELECT_SIZES, multiSelectCloseButtonStructure, multiSelectHeaderStructure, multiSelectOverlayStructure, multiSelectRowIndicatorStructure, multiSelectRowLeadingStructure, multiSelectRowStructure, multiSelectSheetStructure, multiSelectTriggerStructure, resolveMultiSelectAccessibility, resolveMultiSelectRowColors, resolveMultiSelectTriggerColors } from "./MultiSelect.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const ICON_STROKE = 2;
-// Decorative dismiss scrim behind the sheet — a design constant, not a role token: it is neither
-// text nor an interactive boundary, so WCAG's contrast minimums don't apply to it.
 const BACKDROP_SCRIM = "#00000099";
+const MultiSelectOptionRow = /*#__PURE__*/memo(function MultiSelectOptionRow({
+  option,
+  checked,
+  tabIndex,
+  theme,
+  rowColors,
+  onToggle,
+  testID
+}) {
+  const motion = useMotion();
+  const press = usePressMotion();
+  const handlePress = useCallback(() => onToggle(option.value), [onToggle, option.value]);
+  const rowRef = useRef(null);
+  const active = tabIndex === 0;
+
+  // The tabindex alone only names the tab stop — focus has to follow the arrows too, or the focus
+  // trap's Tab handler sees a focused row that is no longer tabbable and lets Tab leave the sheet.
+  useEffect(() => {
+    if (!active || Platform.OS !== "web") return;
+    rowRef.current?.focus();
+  }, [active]);
+
+  // `checkbox` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  useSpaceActivation(rowRef, handlePress);
+  const checkOpacity = useRef(new Animated.Value(checked ? 1 : 0)).current;
+  const skipFirst = useRef(true);
+  const running = useRef(null);
+  useEffect(() => {
+    running.current?.stop();
+    // A row scrolled into view already-checked must snap, never fade.
+    if (skipFirst.current) {
+      skipFirst.current = false;
+      checkOpacity.setValue(checked ? 1 : 0);
+      return;
+    }
+    if (!motion.enabled) {
+      checkOpacity.setValue(checked ? 1 : 0);
+      return;
+    }
+    running.current = motion.timing(checkOpacity, checked ? 1 : 0, {
+      duration: "fast"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [checked, motion, checkOpacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const rowStructure = useMemo(() => multiSelectRowStructure(theme), [theme]);
+  const indicatorStructure = useMemo(() => multiSelectRowIndicatorStructure(theme), [theme]);
+  const leadingStructure = useMemo(() => multiSelectRowLeadingStructure(theme), [theme]);
+  const rowStyle = useCallback(({
+    pressed
+  }) => ({
+    backgroundColor: pressed ? rowColors.pressedRow : rowColors.background
+  }), [rowColors]);
+  const indicatorStyle = useMemo(() => [indicatorStructure, {
+    borderColor: checked ? rowColors.indicatorFill : rowColors.indicatorBorder,
+    backgroundColor: checked ? rowColors.indicatorFill : "transparent"
+  }], [indicatorStructure, checked, rowColors]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flex: 1,
+    fontSize: theme.fontSizes.md,
+    color: rowColors.text
+  }], [theme, rowColors]);
+  return /*#__PURE__*/_jsx(Pressable, {
+    ref: rowRef,
+    testID: testID ? `${testID}-option-${option.value}` : undefined,
+    accessibilityRole: "checkbox",
+    "aria-checked": checked,
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    style: rowStyle,
+    children: /*#__PURE__*/_jsxs(Animated.View, {
+      testID: testID ? `${testID}-option-${option.value}-content` : undefined,
+      style: [rowStructure, press.style],
+      children: [/*#__PURE__*/_jsx(View, {
+        style: indicatorStyle,
+        children: checked && /*#__PURE__*/_jsx(Animated.View, {
+          testID: testID ? `${testID}-option-${option.value}-check` : undefined,
+          style: {
+            opacity: checkOpacity
+          },
+          children: /*#__PURE__*/_jsx(Icon, {
+            name: "check",
+            size: MULTI_SELECT_ROW_ICON_SIZE,
+            color: rowColors.indicatorIcon,
+            strokeWidth: ICON_STROKE
+          })
+        })
+      }), option.leading !== undefined && /*#__PURE__*/_jsx(View, {
+        style: leadingStructure,
+        children: option.leading
+      }), /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: labelStyle,
+        children: option.label
+      })]
+    })
+  });
+});
 export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   options,
   values,
@@ -39,55 +130,119 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
   const portalContainer = useContext(ModalPortalContext);
   const [open, setOpen] = useState(false);
   const [focused, setFocused] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const sheetRef = useRef(null);
+  const reveal = useReveal(open);
   const spec = MULTI_SELECT_SIZES[size];
   const selectedCount = values.length;
   const isPlaceholder = selectedCount === 0;
-  const singleLabel = selectedCount === 1 ? options.find(option => option.value === values[0])?.label : undefined;
+  const selectedValues = useMemo(() => new Set(values), [values]);
+  const singleLabel = useMemo(() => selectedCount === 1 ? options.find(option => option.value === values[0])?.label : undefined, [selectedCount, options, values]);
   const displayText = isPlaceholder ? placeholder ?? "" : singleLabel ?? `${selectedCount} selected`;
-  const triggerColors = resolveMultiSelectTriggerColors(theme.colors, focused || open);
-  const rowColors = resolveMultiSelectRowColors(theme.colors);
-  const a11y = resolveMultiSelectAccessibility({
+  const triggerColors = useMemo(() => resolveMultiSelectTriggerColors(theme.colors, focused || open), [theme.colors, focused, open]);
+  const rowColors = useMemo(() => resolveMultiSelectRowColors(theme.colors), [theme.colors]);
+  const a11y = useMemo(() => resolveMultiSelectAccessibility({
     disabled,
     open
-  });
+  }), [disabled, open]);
   const accessibleName = label !== undefined ? displayText ? `${label}, ${displayText}` : label : undefined;
-  const openMenu = () => {
+  const firstSelectedIndex = useMemo(() => options.findIndex(option => selectedValues.has(option.value)), [options, selectedValues]);
+  const openMenu = useCallback(() => {
     if (disabled) return;
+    // Opening lands the keyboard on the first SELECTED option, not the first one (WCAG 2.4.3).
+    setActiveIndex(firstSelectedIndex === -1 ? 0 : firstSelectedIndex);
     setOpen(true);
-  };
-  const closeMenu = () => setOpen(false);
-  const toggleValue = value => {
-    const next = values.includes(value) ? values.filter(v => v !== value) : [...values, value];
-    onValuesChange(next);
-  };
-  const sheet = /*#__PURE__*/_jsxs(_Fragment, {
+  }, [disabled, firstSelectedIndex]);
+  const closeMenu = useCallback(() => setOpen(false), []);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+
+  // `values` necessarily changes on every toggle, so reading it through a ref is what keeps
+  // `toggleValue` identity-stable — as a dependency it re-created the callback per toggle and
+  // defeated `React.memo` on every mounted row, not just the one whose `checked` flipped.
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+  const onValuesChangeRef = useRef(onValuesChange);
+  onValuesChangeRef.current = onValuesChange;
+  const toggleValue = useCallback(value => {
+    const current = valuesRef.current;
+    const next = current.includes(value) ? current.filter(v => v !== value) : [...current, value];
+    onValuesChangeRef.current(next);
+  }, []);
+  const typeaheadLabels = useMemo(() => options.map(option => option.label), [options]);
+
+  // Keyboard (web only — every hook below is a no-op on native, see `core/a11y/keyboard.ts`).
+  // No `onActivate`: RNW already presses a row on Enter, and each row's own `useSpaceActivation`
+  // owns Space — passing it here would toggle twice, i.e. not at all.
+  useDismissOnEscape(open, closeMenu);
+  useFocusTrap(sheetRef, open);
+  useRovingKeys(sheetRef, open, {
+    count: options.length,
+    activeIndex,
+    onActiveIndexChange: setActiveIndex,
+    typeaheadLabels
+  });
+  const keyExtractor = useCallback(option => option.value, []);
+  const renderItem = useCallback(({
+    item: option,
+    index
+  }) => /*#__PURE__*/_jsx(MultiSelectOptionRow, {
+    option: option,
+    checked: selectedValues.has(option.value),
+    tabIndex: focusItemProps(index, activeIndex).tabIndex,
+    theme: theme,
+    rowColors: rowColors,
+    onToggle: toggleValue,
+    testID: testID
+  }), [selectedValues, activeIndex, theme, rowColors, toggleValue, testID]);
+  const rootStyle = useMemo(() => [styles.container, containerStyle], [containerStyle]);
+  const triggerStyle = useMemo(() => [multiSelectTriggerStructure(theme, {
+    size
+  }), {
+    backgroundColor: triggerColors.background,
+    borderColor: triggerColors.border
+  }, disabled && styles.dimmed], [theme, size, triggerColors, disabled]);
+  const overlayStructure = useMemo(() => multiSelectOverlayStructure(theme), [theme]);
+  const headerStructure = useMemo(() => multiSelectHeaderStructure(theme), [theme]);
+  const closeButtonStructure = useMemo(() => multiSelectCloseButtonStructure(theme), [theme]);
+  const sheetStyle = useMemo(() => [multiSelectSheetStructure(theme), {
+    backgroundColor: theme.colors.bg.surface
+  }], [theme]);
+  const fieldLabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.muted,
+    marginBottom: theme.space[1]
+  }], [theme]);
+  const valueTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flexShrink: 1,
+    fontSize: spec.fontSize,
+    color: isPlaceholder ? triggerColors.placeholder : triggerColors.text
+  }], [theme, spec, isPlaceholder, triggerColors]);
+  const sheet = open ? /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: BACKDROP_SCRIM
-      }],
+      tabIndex: -1,
+      style: styles.backdrop,
       onPress: closeMenu
     }), /*#__PURE__*/_jsx(View, {
-      style: multiSelectOverlayStructure(theme),
+      style: overlayStructure,
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsxs(View, {
-        style: [multiSelectSheetStructure(theme), {
-          backgroundColor: theme.colors.bg.surface
-        }],
+      children: /*#__PURE__*/_jsxs(Animated.View, {
+        ref: sheetRef,
+        style: [sheetStyle, reveal.style],
         children: [/*#__PURE__*/_jsx(View, {
-          style: multiSelectHeaderStructure(theme),
+          style: headerStructure,
           children: /*#__PURE__*/_jsx(Pressable, {
             testID: testID ? `${testID}-close` : undefined,
             accessibilityRole: "button",
             accessibilityLabel: "Close",
             onPress: closeMenu,
             hitSlop: MULTI_SELECT_CLOSE_BUTTON_HIT_SLOP,
-            style: multiSelectCloseButtonStructure(theme),
+            style: closeButtonStructure,
             children: /*#__PURE__*/_jsx(Icon, {
               name: "x",
               size: MULTI_SELECT_CLOSE_ICON_SIZE,
@@ -95,50 +250,16 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
               strokeWidth: ICON_STROKE
             })
           })
-        }), /*#__PURE__*/_jsx(ScrollView, {
-          bounces: false,
-          children: options.map(option => {
-            const checked = values.includes(option.value);
-            return /*#__PURE__*/_jsxs(Pressable, {
-              testID: testID ? `${testID}-option-${option.value}` : undefined,
-              accessibilityRole: "checkbox",
-              accessibilityState: {
-                checked
-              },
-              onPress: () => toggleValue(option.value),
-              style: [multiSelectRowStructure(theme), {
-                backgroundColor: rowColors.background
-              }],
-              children: [/*#__PURE__*/_jsx(View, {
-                style: [multiSelectRowIndicatorStructure(theme), {
-                  borderColor: checked ? rowColors.indicatorFill : rowColors.indicatorBorder,
-                  backgroundColor: checked ? rowColors.indicatorFill : "transparent"
-                }],
-                children: checked && /*#__PURE__*/_jsx(Icon, {
-                  name: "check",
-                  size: MULTI_SELECT_ROW_ICON_SIZE,
-                  color: rowColors.indicatorIcon,
-                  strokeWidth: ICON_STROKE
-                })
-              }), /*#__PURE__*/_jsx(Text, {
-                numberOfLines: 1,
-                style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-                  flex: 1,
-                  fontSize: theme.fontSizes.md,
-                  color: rowColors.text
-                }],
-                children: option.label
-              })]
-            }, option.value);
-          })
+        }), /*#__PURE__*/_jsx(VirtualList, {
+          data: options,
+          keyExtractor: keyExtractor,
+          renderItem: renderItem,
+          itemHeight: MULTI_SELECT_ROW_MIN_HEIGHT,
+          accessibilityRole: MULTI_SELECT_LISTBOX_ROLE
         })]
       })
     })]
-  });
-
-  // Web portal opt-in — see Modal.tsx's/Select.tsx's identical branch + ModalPortalContext.ts.
-  // Every other case (native, or web with no ModalPortalProvider) renders through RN's own
-  // <Modal> below, unchanged.
+  }) : null;
   const menu = Platform.OS === "web" && portalContainer != null ? open ? renderWebPortal(/*#__PURE__*/_jsx(View, {
     style: StyleSheet.absoluteFill,
     pointerEvents: "box-none",
@@ -146,42 +267,30 @@ export const MultiSelect = /*#__PURE__*/memo(function MultiSelect({
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
-    animationType: reducedMotion ? "none" : "fade",
+    animationType: "none",
     onRequestClose: closeMenu,
     children: sheet
   });
   return /*#__PURE__*/_jsxs(View, {
-    style: [styles.container, containerStyle],
+    style: rootStyle,
     children: [label !== undefined && /*#__PURE__*/_jsx(Text, {
-      style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
-        fontSize: theme.fontSizes.sm,
-        color: theme.colors.fg.muted,
-        marginBottom: theme.space[1]
-      }],
+      style: fieldLabelStyle,
       children: label
     }), /*#__PURE__*/_jsxs(Pressable, {
       testID: testID,
       accessibilityRole: a11y.accessibilityRole,
       accessibilityLabel: accessibleName,
-      accessibilityState: a11y.accessibilityState,
+      "aria-disabled": a11y["aria-disabled"],
+      "aria-expanded": a11y["aria-expanded"],
       disabled: a11y.disabled,
       onPress: openMenu,
-      onFocus: () => setFocused(true),
-      onBlur: () => setFocused(false),
+      onFocus: handleFocus,
+      onBlur: handleBlur,
       hitSlop: spec.hitSlop,
-      style: [multiSelectTriggerStructure(theme, {
-        size
-      }), {
-        backgroundColor: triggerColors.background,
-        borderColor: triggerColors.border
-      }, disabled && styles.dimmed],
+      style: triggerStyle,
       children: [/*#__PURE__*/_jsx(Text, {
         numberOfLines: 1,
-        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-          flexShrink: 1,
-          fontSize: spec.fontSize,
-          color: isPlaceholder ? triggerColors.placeholder : triggerColors.text
-        }],
+        style: valueTextStyle,
         children: displayText
       }), /*#__PURE__*/_jsx(Icon, {
         name: "chevron-down",
@@ -196,9 +305,12 @@ const styles = StyleSheet.create({
   container: {
     alignSelf: "stretch"
   },
-  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
   dimmed: {
     opacity: 0.5
+  },
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BACKDROP_SCRIM
   }
 });
 //# sourceMappingURL=MultiSelect.js.map

package/lib/module/modules/multi-select/MultiSelect.variants.js

@@ -46,6 +46,14 @@ export const MULTI_SELECT_SIZES = {
 /** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). */
 export const MULTI_SELECT_ROW_MIN_HEIGHT = 44;
 
+/**
+ * The option list's container role. 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 MULTI_SELECT_LISTBOX_ROLE = "listbox";
+
 /** Row checkbox-style indicator box side, in dp. Fixed — independent of the trigger's own `size`,
  *  same reasoning as `Select`'s row "check" glyph. */
 export const MULTI_SELECT_ROW_INDICATOR_SIZE = 20;
@@ -78,7 +86,8 @@ export function resolveMultiSelectRowColors(colors) {
     text: colors.fg.default,
     indicatorBorder: colors.border.interactive,
     indicatorFill: colors.accent.solid,
-    indicatorIcon: colors.accent.onSolid
+    indicatorIcon: colors.accent.onSolid,
+    pressedRow: colors.bg.sunken
   };
 }
 /**
@@ -90,10 +99,8 @@ export function resolveMultiSelectAccessibility(input) {
   const disabled = input.disabled === true;
   return {
     accessibilityRole: "button",
-    accessibilityState: {
-      disabled,
-      expanded: input.open
-    },
+    "aria-disabled": disabled,
+    "aria-expanded": input.open,
     disabled
   };
 }
@@ -180,6 +187,22 @@ export const multiSelectRowStructure = createThemedVariants(theme => ({
   }
 }));
 
+/**
+ * `MultiSelectOption.leading` is an arbitrary consumer node, so an unconstrained one could make a
+ * row taller than `MULTI_SELECT_ROW_MIN_HEIGHT` and silently falsify the list's `getItemLayout`
+ * offsets. This slot bounds it to the row's own indicator box instead, which is what keeps the
+ * uniform-height fast path true by construction (`core/MODULE.md`: `itemHeight` is uniform-only).
+ */
+export const multiSelectRowLeadingStructure = createThemedVariants(() => ({
+  base: {
+    width: MULTI_SELECT_ROW_INDICATOR_SIZE,
+    height: MULTI_SELECT_ROW_INDICATOR_SIZE,
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden"
+  }
+}));
+
 /** Structural indicator-box styles only — size, radius, border WIDTH. No colours: border/fill
  *  colour is checked-state-driven and applied inline over this, same split as `checkboxBoxStructure`. */
 export const multiSelectRowIndicatorStructure = createThemedVariants(theme => ({