pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/modal/Modal.js

@@ -6,6 +6,12 @@
  * backdrop scrim dismisses it on press; the panel sits on `bg.surface` with `theme.radii.lg` and
  * `theme.elevation.lg`, capped to one of three closed widths (`size`).
  *
+ * Motion split: RN's own `animationType` owns the SURFACE fade (in AND out, natively, with no JS
+ * timer), and the global motion system (`core/motion`) owns the panel's own entrance lift. The exit
+ * is deliberately left to the native transition — a JS-timed exit would have to keep the `<Modal>`
+ * mounted past `visible`, widening the window in which iOS drops a sibling `<Modal>` presented while
+ * this one is dismissing.
+ *
  * Fully controlled: the caller owns `visible` and reacts to `onRequestClose`, which fires from the
  * backdrop press, the Android hardware back button, and — via `onAccessibilityEscape` on the panel
  * — iOS VoiceOver's two-finger-Z escape gesture. (RN's `<Modal>` only fires `onRequestClose` from a
@@ -19,12 +25,19 @@
  * `renderWebPortal` instead — see `ModalPortalContext.ts` for why. Every other case (native, or web
  * with no provider — the default `ModalPortalContext` value is `null`) renders through RN's own
  * `<Modal>`, byte-identical to before this mechanism existed.
+ *
+ * Physical-keyboard support is scoped to exactly that portal branch. `react-native-web`'s own
+ * `<Modal>` already ships Escape, a Tab trap and focus restore (`ModalContent`/`ModalFocusTrap`),
+ * so the RNModal path below must stay untouched — wiring the hooks there too would give the page
+ * two Escape listeners and two competing traps. The portal branch renders no `<RNModal>` at all,
+ * which is where all three silently went missing.
  */
 
-import { memo, useContext } from "react";
-import { Modal as RNModal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
-import { useTheme } from "../../theme/index.js";
+import { memo, useContext, useEffect, useMemo, useRef } from "react";
+import { Animated, Modal as RNModal, Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import { useDismissOnEscape, useFocusTrap } from "../../core/a11y/keyboard";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "./ModalPortalContext.js";
 import { renderWebPortal } from "./renderWebPortal";
 import { modalOverlayStructure, modalPanelStructure, resolveModalAnimationType, resolveModalPanelColors } from "./Modal.variants.js";
@@ -42,42 +55,73 @@ export const Modal = /*#__PURE__*/memo(function Modal({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
-  const panelColors = resolveModalPanelColors(theme.colors);
+  const motion = useMotion();
+  const panelColors = useMemo(() => resolveModalPanelColors(theme.colors), [theme.colors]);
   const portalContainer = useContext(ModalPortalContext);
+  const panelRef = useRef(null);
+  const portalled = Platform.OS === "web" && portalContainer != null;
+  useDismissOnEscape(portalled && visible, onRequestClose);
+  useFocusTrap(panelRef, portalled && visible);
+  const enter = useAnimatedValue(visible ? 1 : 0);
+  const entering = useRef(null);
+  useEffect(() => {
+    entering.current?.stop();
+    if (!visible) {
+      enter.setValue(0);
+      return;
+    }
+    if (!motion.enabled) {
+      enter.setValue(1);
+      return;
+    }
+    enter.setValue(0);
+    entering.current = motion.timing(enter, 1, {
+      easing: "decelerate"
+    });
+    entering.current.start();
+  }, [visible, motion, enter]);
+  useEffect(() => () => entering.current?.stop(), []);
+  const panelStyle = useMemo(() => [modalPanelStructure(theme, {
+    size
+  }), {
+    backgroundColor: panelColors.background,
+    transform: [{
+      translateY: enter.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.offsetY, 0]
+      })
+    }]
+  }], [theme, size, panelColors.background, enter, motion.transform.offsetY]);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: theme.fontSizes.lg,
+    color: panelColors.title,
+    marginBottom: theme.space[3]
+  }], [theme, panelColors.title]);
   const overlay = /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: MODAL_BACKDROP
-      }],
+      tabIndex: -1,
+      style: styles.backdrop,
       onPress: onRequestClose
     }), /*#__PURE__*/_jsx(View, {
       style: modalOverlayStructure(theme),
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsxs(View, {
+      children: /*#__PURE__*/_jsxs(Animated.View, {
+        ref: panelRef,
         testID: testID ? `${testID}-panel` : undefined,
         accessibilityViewIsModal: true,
         onAccessibilityEscape: onRequestClose,
-        style: [modalPanelStructure(theme, {
-          size
-        }), {
-          backgroundColor: panelColors.background
-        }],
+        style: panelStyle,
         children: [title !== undefined && /*#__PURE__*/_jsx(Text, {
           accessibilityRole: "header",
-          style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-            fontSize: theme.fontSizes.lg,
-            color: panelColors.title,
-            marginBottom: theme.space[3]
-          }],
+          style: titleStyle,
           children: title
         }), children]
       })
     })]
   });
-  if (Platform.OS === "web" && portalContainer != null) {
+  if (portalled) {
     if (!visible) return null;
     // RN's own <Modal> supplies a `position: fixed`/full-screen ancestor for `overlay`'s children
     // to size against (see ModalPortalContext.ts) — reproduce just that sizing here (never touching
@@ -93,9 +137,15 @@ export const Modal = /*#__PURE__*/memo(function Modal({
   return /*#__PURE__*/_jsx(RNModal, {
     visible: visible,
     transparent: true,
-    animationType: resolveModalAnimationType(reducedMotion),
+    animationType: resolveModalAnimationType(!motion.enabled),
     onRequestClose: onRequestClose,
     children: overlay
   });
 });
+const styles = StyleSheet.create({
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: MODAL_BACKDROP
+  }
+});
 //# sourceMappingURL=Modal.js.map

package/lib/module/modules/more-items/MODULE.md

@@ -0,0 +1,72 @@
+# more-items/ — a "+N more" overflow affordance
+
+`MoreItems` is a `Pressable` "+N more" badge (with optional leading text) that opens a `Modal` sheet
+listing the hidden items, each with an optional tone dot. It is the overflow tail for any capped
+row — assignees, tags, labels — so a caller renders the first few itself and hands the rest here.
+
+Fully controlled and store-agnostic: `items` and `moreCount` come from the host, and the component
+owns nothing but its open/closed state.
+
+## Files
+
+| File | Role |
+|------|------|
+| `MoreItems.tsx` | The component: trigger, `Modal` sheet, and the memo'd `MoreItemsRow`. |
+| `MoreItems.variants.ts` | Pure `resolveMoreItemsCount` / `resolveMoreItemsDotColor` (tone reuses `Badge`'s tone table) + the themed structural resolvers. No React. |
+| `index.ts` | Public surface: `MoreItems`, `MoreItemsProps`, `MoreItemsEntry`. |
+| `__tests__/MoreItems.test.ts` | Pure: the count fallback (`moreCount` wins over `items.length`). |
+| `__tests__/MoreItems.render.test.tsx` | Render: the trigger opens the sheet, the entries show, the real rendered touch-target size, label-in-name, modal semantics, and the hidden tone dot. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `items` | `readonly MoreItemsEntry[]` | — | `{ id, label, tone? }`; `tone` is a `BadgeTone`, defaulting to `accent`. |
+| `moreCount` | `number` | `items.length` | The number on the badge when it differs from the list length. |
+| `triggerText` | `string` | — | Optional text before the badge. Rendered alone when the count is ≤0. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Trigger gets it directly. Also seeds `${testID}-sheet`, `${testID}-backdrop`, `${testID}-list` and `${testID}-row-${item.id}` (+ `-dot` under that). |
+
+Renders `null` when the count is ≤0 and there is no `triggerText` — nothing to overflow.
+
+## Accessibility
+
+- **Touch target (WCAG 2.5.5 / 2.5.8)** — the trigger carries `minHeight: 44` (this library's
+  floor). It is a standalone node with no neighbouring target to overlap, so the floor is real
+  height via `minHeight`, not `hitSlop` expansion the way `Button`'s shorter sizes reach it.
+- **Label in Name (WCAG 2.5.3)** — the accessible name is built to CONTAIN the visible text
+  (`"${triggerText} +${count} more"`, or just `"+${count} more"` with no leading text), not a
+  separately-worded `"${count} more items"`. Voice control says what it reads; the old name shared no
+  full word with what was on screen.
+- **Modal semantics** — the sheet panel carries `accessibilityViewIsModal` + `onAccessibilityEscape`,
+  the same pair every other overlay in this library gives its panel, and an `accessibilityLabel`
+  matching the trigger's name. The scrim `Pressable` is `accessible={false}` + `tabIndex={-1}` so it
+  doesn't surface as an unlabelled full-screen button ahead of the sheet.
+- **Colour as sole carrier (WCAG 1.4.1)** — a row's tone dot has no text equivalent for its colour, so
+  it is `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`; the row
+  itself is one `accessible` node with `accessibilityRole="text"` reading only the label.
+
+## Performance contract
+
+- The sheet's list is `core/list`'s `VirtualList`, not a `ScrollView` + `.map()`: `items` is
+  caller-supplied and unbounded, so a long overflow list would otherwise mount every row at once.
+  **No `itemHeight`** is passed — a row's height is text-driven (it grows with the OS font scale),
+  so a fixed `getItemLayout` would mis-position the scroll offset.
+- `MoreItemsRow` is extracted + `React.memo`'d; `renderItem`/`keyExtractor` are `useCallback`s.
+- Every `*Structure(theme)` result, `resolveMoreItemsDotColor` call and style array literal is
+  `useMemo`'d on `[theme]` (plus `[item.tone]` in the row) — a fresh object per render defeats the
+  row's `memo`.
+
+## Motion (`core/motion` only — never a local duration)
+
+- **Press** — the trigger uses `usePressMotion`, applied to an inner `Animated.View` so the
+  consumer's `style` stays on the outermost node.
+- **Sheet** — `useEnterExit(open)` on the panel; the `Modal` keeps `visible={open}` with
+  `animationType="none"` so the library owns the reveal and the sheet fully unmounts when closed.
+- Rows carry no motion of their own: they are not interactive, and per-row animation must never run
+  during scroll.
+
+## Known gaps
+
+- Rows are display-only — no press/selection. A selectable overflow list would be a different
+  component (`Select`/`Menu`), not a prop added here.

package/lib/module/modules/more-items/MoreItems.js

@@ -0,0 +1,162 @@
+"use strict";
+
+/**
+ * MoreItems — "+N more" overflow affordance opening a sheet of hidden items (avatars, tags, etc.).
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { Animated, Modal, Pressable, StyleSheet, Text, View } from "react-native";
+import { VirtualList } from "../../core/list/index.js";
+import { useEnterExit, usePressMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { moreItemsBadgeStructure, moreItemsDotStructure, moreItemsOverlayStructure, moreItemsRowStructure, moreItemsSheetStructure, moreItemsTriggerContentStructure, moreItemsTriggerStructure, resolveMoreItemsCount, resolveMoreItemsDotColor } from "./MoreItems.variants.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const BACKDROP = "#00000080";
+const MoreItemsRow = /*#__PURE__*/memo(function MoreItemsRow({
+  item,
+  theme,
+  testID
+}) {
+  const rowStructure = useMemo(() => moreItemsRowStructure(theme), [theme]);
+  const dotStyle = useMemo(() => [moreItemsDotStructure(theme), {
+    backgroundColor: resolveMoreItemsDotColor(theme.colors, item.tone)
+  }], [theme, item.tone]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.muted,
+    flex: 1
+  }], [theme]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    accessible: true,
+    accessibilityRole: "text",
+    style: rowStructure,
+    children: [/*#__PURE__*/_jsx(View, {
+      testID: testID === undefined ? undefined : `${testID}-dot`,
+      style: dotStyle,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants"
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: item.label
+    })]
+  });
+});
+export const MoreItems = /*#__PURE__*/memo(function MoreItems({
+  items,
+  moreCount,
+  triggerText,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const [open, setOpen] = useState(false);
+  const press = usePressMotion();
+  const sheetMotion = useEnterExit(open);
+  const count = resolveMoreItemsCount(moreCount, items.length);
+  const openSheet = useCallback(() => setOpen(true), []);
+  const closeSheet = useCallback(() => setOpen(false), []);
+  const emptyTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default
+  }], [theme]);
+  const triggerStyle = useMemo(() => [moreItemsTriggerStructure(theme), style], [theme, style]);
+  const triggerContentStructure = useMemo(() => moreItemsTriggerContentStructure(theme), [theme]);
+  const triggerTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.default,
+    flexShrink: 1
+  }], [theme]);
+  const badgeStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), moreItemsBadgeStructure(theme), {
+    color: theme.colors.accent.text,
+    backgroundColor: theme.colors.accent.subtle
+  }], [theme]);
+  const overlayStructure = useMemo(() => moreItemsOverlayStructure(theme), [theme]);
+  const sheetStyle = useMemo(() => [moreItemsSheetStructure(theme), {
+    backgroundColor: theme.colors.bg.surface
+  }], [theme]);
+
+  // WCAG 2.5.3: the accessible name must CONTAIN the visible text, or a voice-control user saying
+  // what they can read ("tap plus three more") never activates the trigger.
+  const accessibleName = triggerText === undefined ? `+${count} more` : `${triggerText} +${count} more`;
+  const keyExtractor = useCallback(item => item.id, []);
+  const renderItem = useCallback(({
+    item
+  }) => /*#__PURE__*/_jsx(MoreItemsRow, {
+    item: item,
+    theme: theme,
+    testID: testID === undefined ? undefined : `${testID}-row-${item.id}`
+  }), [theme, testID]);
+  if (count <= 0) {
+    return triggerText ? /*#__PURE__*/_jsx(Text, {
+      style: emptyTextStyle,
+      children: triggerText
+    }) : null;
+  }
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Pressable, {
+      testID: testID,
+      accessibilityRole: "button",
+      accessibilityLabel: accessibleName,
+      accessibilityHint: "Opens the full list",
+      onPress: openSheet,
+      onPressIn: press.onPressIn,
+      onPressOut: press.onPressOut,
+      style: triggerStyle,
+      children: /*#__PURE__*/_jsxs(Animated.View, {
+        style: [triggerContentStructure, press.style],
+        children: [triggerText !== undefined && /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: triggerTextStyle,
+          children: triggerText
+        }), /*#__PURE__*/_jsxs(Text, {
+          style: badgeStyle,
+          children: ["+", count, " more"]
+        })]
+      })
+    }), /*#__PURE__*/_jsxs(Modal, {
+      visible: open,
+      transparent: true,
+      animationType: "none",
+      onRequestClose: closeSheet,
+      children: [/*#__PURE__*/_jsx(Pressable, {
+        testID: testID === undefined ? undefined : `${testID}-backdrop`
+        // Otherwise the scrim is an unlabelled full-screen button sitting ahead of the sheet.
+        ,
+        accessible: false,
+        tabIndex: -1,
+        style: StyleSheet.absoluteFill,
+        onPress: closeSheet,
+        children: /*#__PURE__*/_jsx(View, {
+          style: styles.backdrop
+        })
+      }), /*#__PURE__*/_jsx(View, {
+        style: overlayStructure,
+        pointerEvents: "box-none",
+        children: /*#__PURE__*/_jsx(Animated.View, {
+          testID: testID ? `${testID}-sheet` : undefined
+          // The modal-semantics pair every other overlay in this library gives its panel, plus a
+          // name: the sheet had neither, so VoiceOver could wander into the row behind it.
+          ,
+          accessibilityViewIsModal: true,
+          onAccessibilityEscape: closeSheet,
+          accessibilityLabel: accessibleName,
+          style: [sheetStyle, sheetMotion.style],
+          children: /*#__PURE__*/_jsx(VirtualList, {
+            data: items,
+            keyExtractor: keyExtractor,
+            renderItem: renderItem,
+            testID: testID === undefined ? undefined : `${testID}-list`
+          })
+        })
+      })]
+    })]
+  });
+});
+const styles = StyleSheet.create({
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BACKDROP
+  }
+});
+//# sourceMappingURL=MoreItems.js.map

package/lib/module/modules/more-items/MoreItems.variants.js

@@ -0,0 +1,80 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+import { resolveBadgeTone } from "../badge/Badge.variants.js";
+export function resolveMoreItemsCount(moreCount, itemsLength) {
+  return moreCount ?? itemsLength;
+}
+
+/** Tone dot beside each overflow label. */
+export const MORE_ITEMS_DOT_SIZE = 8;
+
+/** The sheet never grows past this — the list inside it scrolls (and virtualizes). */
+export const MORE_ITEMS_SHEET_MAX_HEIGHT = 280;
+
+/**
+ * 44dp is Apple's HIG minimum and WCAG 2.5.5 (AAA); it comfortably exceeds 2.5.8's 24×24 (AA). The
+ * trigger reaches it with `minHeight` rather than `hitSlop`: it is a standalone node with no
+ * neighbouring target to overlap, and a slop-expanded rectangle would still leave a ~22dp visual
+ * control that misses under an unsteady finger.
+ */
+export const MIN_TOUCH_TARGET = 44;
+export const moreItemsTriggerStructure = createThemedVariants(_theme => ({
+  base: {
+    maxWidth: 250,
+    minHeight: MIN_TOUCH_TARGET,
+    justifyContent: "center"
+  }
+}));
+
+/** The trigger's animated layer: press motion moves the content, never the outer layout box. */
+export const moreItemsTriggerContentStructure = createThemedVariants(_theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center"
+  }
+}));
+
+/** Overflow-list row. Height is text-driven (font scaling), so the list gets no fixed itemHeight. */
+export const moreItemsRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[2],
+    paddingVertical: theme.space[1]
+  }
+}));
+export const moreItemsDotStructure = createThemedVariants(theme => ({
+  base: {
+    width: MORE_ITEMS_DOT_SIZE,
+    height: MORE_ITEMS_DOT_SIZE,
+    borderRadius: theme.radii.full
+  }
+}));
+export const moreItemsOverlayStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    justifyContent: "center",
+    padding: theme.space[4]
+  }
+}));
+export const moreItemsSheetStructure = createThemedVariants(theme => ({
+  base: {
+    borderRadius: theme.radii.lg,
+    padding: theme.space[3],
+    maxHeight: MORE_ITEMS_SHEET_MAX_HEIGHT
+  }
+}));
+export const moreItemsBadgeStructure = createThemedVariants(theme => ({
+  base: {
+    marginLeft: theme.space[1],
+    paddingHorizontal: theme.space[2],
+    paddingVertical: 2,
+    borderRadius: theme.radii.full,
+    fontSize: theme.fontSizes.xs
+  }
+}));
+export function resolveMoreItemsDotColor(colors, tone = "accent") {
+  return resolveBadgeTone(colors, tone).text;
+}
+//# sourceMappingURL=MoreItems.variants.js.map

package/lib/module/modules/more-items/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { MoreItems } from "./MoreItems.js";
+//# sourceMappingURL=index.js.map

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

@@ -18,11 +18,13 @@ 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
 
@@ -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.