pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/section-list/SectionList.variants.js

@@ -0,0 +1,11 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const sectionListHeaderStructure = createThemedVariants(theme => ({
+  base: {
+    paddingHorizontal: theme.space[3],
+    paddingTop: theme.space[3],
+    paddingBottom: theme.space[1]
+  }
+}));
+//# sourceMappingURL=SectionList.variants.js.map

package/lib/module/modules/section-list/index.js

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

package/lib/module/modules/segmented-control/MODULE.md

@@ -0,0 +1,124 @@
+# segmented-control/ — an inline, iOS-style single-choice picker
+
+`SegmentedControl` switches between 2–5 mutually exclusive options (filters, view modes, date
+ranges) inside one rounded track. The active segment is marked by a pill that slides to its
+measured position — the same `onLayout` + `Animated.Value` mechanism `Tabs`' sliding indicator
+uses — but unlike `Tabs`/`ButtonGroup`, the pill is a **neutral raised surface**, not an
+accent-coloured fill: elevation, not colour, is the selection cue here.
+
+## Files
+
+| File | Role |
+|------|------|
+| `SegmentedControl.tsx` | The component. Track + pill + segment composition, press wiring, a11y wiring, the pill's layout measurement + animation. |
+| `SegmentedControl.variants.ts` | Pure resolvers (`resolveSegmentedControlColors`, `resolveSegmentedControlSegmentAccessibility`, `resolveSegmentedControlSegmentHitSlop`) + the themed structural resolvers (`segmentedControlTrackStructure`, `segmentedControlPillStructure`, `segmentedControlSegmentStructure`). No React, no lucide. |
+| `index.ts` | Public surface: `SegmentedControl`, `SegmentedControlProps`, `SegmentedControlOption`, `SegmentedControlSize`, `IconName` (re-exported from `core/icon`). |
+| `__tests__/SegmentedControl.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
+| `__tests__/SegmentedControl.render.test.tsx` | Render: strip/segment roles, selection state, per-option and whole-group `disabled`, pill animation respects reduced motion. |
+| `__tests__/SegmentedControl.motion.test.tsx` | Motion: reduce-motion snap, the real slide, and the device tier's `durationScale` reaching the pill. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `options` | `{ value: string; label: string; icon?: IconName; disabled?: boolean }[]` | — | Rendered in order. `label` is always required — no icon-only segment, the same rule `Badge` documents. |
+| `value` | `string` | — | The selected option's `value`. |
+| `onChange` | `(value: string) => void` | — | Fires with the pressed segment's `value`. |
+| `size` | `sm \| md` | `md` | 32 / 40 dp fixed segment height; both reach 44dp via vertical-only `hitSlop`. |
+| `fullWidth` | `boolean` | `true` | `true`: segments `flex: 1` (equal width). `false`: segments size to content (padding + `minWidth`). |
+| `disabled` | `boolean` | `false` | Dims and blocks every segment, regardless of a per-option `disabled`. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost (the track `View`), applied exactly once, last. |
+| `testID` | `string` | — | Seeds `${testID}-pill`, `${testID}-${option.value}` and, while focused, `${testID}-${option.value}-focus-ring`. |
+
+No `tone`/`variant` union — the selected fill is always the neutral raised pill and the track is
+always `bg.sunken`; there is nothing for a closed union to resolve, the same reasoning `Tabs`/
+`RadioGroup` document for their own single-purpose shape.
+
+## Accessibility contract (WCAG)
+
+- **4.1.2** — `accessibilityRole="tablist"` on the track, `"tab"` per segment with flat
+  `aria-selected` / `aria-disabled` — `disabled` reflects `disabled` (whole-group) OR that option's
+  own `disabled`, unlike `Tabs`/`ButtonGroup`, which have no per-item disabled at all. Flat, never
+  `accessibilityState={{…}}`: react-native-web discards the object form — see
+  `docs/PLATFORM-A11Y-PROPS.md`.
+- **2.5.x target size** — every size reaches ≥ 44dp vertically via `hitSlop`. Horizontal `hitSlop`
+  is **always zero**: segments render flush (no gap — the sliding pill is the only boundary cue,
+  there is no per-segment border to interrupt), so any horizontal expansion risks the exact overlap
+  `ButtonGroup` documents fixing — React Native never clips `hitSlop` to a sibling's bounds and
+  resolves an overlap to whichever segment renders LATER, not whichever is visually closer to the
+  tap. Rather than tune a per-edge exception, every segment's own rendered `minWidth: 44` carries
+  the width floor instead (the only axis this spec requires — `fullWidth` segments are already well
+  over 44dp in practice).
+- **1.4.3** — the active label (`fg.default`, read on the pill's `bg.surface`) and the inactive
+  label (`fg.muted`, read on the track's `bg.sunken`) are each measured ≥ 4.5:1 for all 8 brands ×
+  both modes, including the inactive label against its own pressed background (`bg.raised`) — not
+  just the resting track.
+- **1.4.11** — deliberately **not** satisfied by colour: `bg.surface` (the pill) against
+  `bg.sunken` (the track) measures as low as 1.08:1, nowhere near 3:1, so this pairing could never
+  clear it on its own. The boundary is instead carried by elevation (`theme.elevation.md`, the
+  identical treatment `Card`'s `elevated` variant uses to differentiate itself with no border
+  either) — a decorative, not textual, distinction — and selection reaches assistive tech
+  independently via `aria-selected`, never by colour alone.
+- **2.4.7** — the focused segment draws a `border.focus` ring
+  (`${testID}-${option.value}-focus-ring`), the same treatment `BottomNavTab` uses. The pill is
+  **not** it: it marks selection and moves only on change. Drawn *inside* the segment's bounds —
+  segments render flush, so a gap-outside ring would spill over its neighbour.
+- **2.3.3** — the pill's movement is two `Animated.Value`s (`x`, `width`) driven off each segment's
+  own `onLayout` measurement, exactly `Tabs`' mechanism. Under reduced motion they're set with
+  `setValue` (an instant snap) instead of a tween — verified in the render tests by spying on
+  `Animated.timing` and asserting it isn't called when reduced motion is on.
+
+## Motion
+
+The slide goes through **`useMotion()`**, not a direct `MOTION_DURATION` import: passing the
+configured constant straight to `Animated.timing` read the CONFIGURED duration, never the one
+resolved against the device tier, so `MOTION_TIER[tier].durationScale` never reached the pill.
+Reduce-motion is `motion.enabled` — no second `useReducedMotion()` call (`core/motion/MODULE.md`
+rule 6). The in-flight slide is stopped on effect cleanup and on unmount.
+
+## Patterns copied from Tabs / ButtonGroup / Card
+
+1. **Structure vs colour split** — track padding/radius, segment height/padding, and the pill's
+   radius are `createThemedVariants` (registered once per `(theme, size)`); colour is resolved by
+   `resolveSegmentedControlColors` from role tokens and applied inline.
+2. **Pure, testable resolvers** in `SegmentedControl.variants.ts` — the WCAG + behaviour contract
+   is unit-tested against the real palettes, never eyeballed.
+3. **Measured sliding pill, keyed by `value`** — identical mechanism to `Tabs`' indicator, so
+   reordering `options` can never apply a stale measurement to the wrong segment.
+4. **Elevation as the selection boundary, not colour** — the same choice `Card`'s `elevated`
+   variant makes; see the 1.4.11 note above.
+
+## Design decisions specific to this module
+
+- **The pill is neutral (`bg.surface`), not accent-coloured.** This is what the spec this module
+  was built against calls for, and it is also the only choice that keeps every segment's label the
+  same colour whether or not it happens to be selected in a given render — no per-brand accent
+  contrast to chase the way `ButtonGroup`'s `accent.solid` fill required a whole edge-colour fix.
+- **Horizontal `hitSlop` is zero, full stop** — no per-edge "outer edge gets slop" exception like
+  `ButtonGroup`'s. Only the vertical target is spec-mandated here; adding the outer-edge case would
+  be unrequested surface area for a control whose segments (especially `fullWidth`) are already
+  comfortably wide.
+- **Per-option `disabled` dims only that segment**; whole-group `disabled` dims the entire track
+  (pill included) via one outer `opacity`. A disabled option that also happens to be `value` simply
+  renders its dim label on top of the pill — not specially handled, and not expected in practice.
+
+## Known gaps
+
+- The pill starts at `x: 0, width: 0` until the active segment's first `onLayout` fires — identical,
+  single-frame gap to `Tabs`' own documented known gap, for the same reason (native layout is
+  asynchronous; RNTL's test renderer never calls `onLayout` on its own, so the render tests fire it
+  manually).
+- No horizontal scrolling for an `options` list too wide for the viewport — v1 assumes 2–5 options
+  fit, the same scope decision `Tabs`/`RadioGroup` made for their own lists.
+
+## Performance
+
+Wrapped in `React.memo`. `handleSegmentLayout` is `useCallback`'d (mirroring `Tabs`' own
+`handleTabLayout`). The `options.map()` renders host `Pressable`/`Text` and the one library child,
+`Icon`, which only receives primitive props — nothing else to memoize.
+
+## 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/segmented-control/SegmentedControl.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * SegmentedControl — an inline, iOS-style single-choice control for switching between 2–5 mutually
+ * exclusive options (filters, view modes, date ranges). A rounded track (`bg.sunken`) holds every
+ * segment; the active one is marked by a raised pill (`bg.surface` + `Card`'s own elevation
+ * treatment) that slides to the selected segment's measured position — the identical
+ * measure-via-`onLayout` + `Animated.Value` mechanism `Tabs`' sliding indicator uses, keyed by
+ * `value` so reordering `options` can never apply a stale measurement to the wrong segment.
+ *
+ * Unlike `ButtonGroup`/`Tabs`, the active state is NOT accent-coloured: the pill is a neutral raised
+ * surface, and elevation — not colour — is what marks it, because `bg.surface` vs `bg.sunken` alone
+ * measures nowhere near WCAG 1.4.11's 3:1 (see `SegmentedControl.variants.ts`). Selection reaches
+ * assistive tech independently via `accessibilityState.selected`.
+ *
+ * The pill is a SELECTION marker, never a focus one — keyboard/AT focus draws its own inset ring on
+ * the focused segment (WCAG 2.4.7), the same treatment `BottomNavTab` uses.
+ */
+
+import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Pressable, StyleSheet, Text, View } from "react-native";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { Icon } from "../../core/icon/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveSegmentedControlColors, resolveSegmentedControlSegmentAccessibility, resolveSegmentedControlSegmentHitSlop, SEGMENTED_CONTROL_SIZES, segmentedControlFocusRingStructure, segmentedControlPillStructure, segmentedControlSegmentStructure, segmentedControlTrackStructure } from "./SegmentedControl.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const ICON_STROKE = 2;
+function SegmentedControlImpl({
+  options,
+  value,
+  onChange,
+  size = "md",
+  fullWidth = true,
+  disabled = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const motion = useMotion();
+  const colors = resolveSegmentedControlColors(theme.colors);
+  const spec = SEGMENTED_CONTROL_SIZES[size];
+  const hitSlop = resolveSegmentedControlSegmentHitSlop(size);
+  const [layouts, setLayouts] = useState({});
+  // Which segment holds keyboard/AT focus. One value rather than per-segment state: only one segment
+  // can be focused, and the segments are rendered inline (a hook per segment is not an option).
+  const [focusedValue, setFocusedValue] = useState(null);
+  const pillX = useAnimatedValue(0);
+  const running = useRef(null);
+  const activeLayout = layouts[value];
+  const handleSegmentLayout = useCallback((optionValue, event) => {
+    const {
+      x,
+      width
+    } = event.nativeEvent.layout;
+    setLayouts(prev => {
+      const existing = prev[optionValue];
+      if (existing !== undefined && existing.x === x && existing.width === width) return prev;
+      return {
+        ...prev,
+        [optionValue]: {
+          x,
+          width
+        }
+      };
+    });
+  }, []);
+  useEffect(() => {
+    if (activeLayout === undefined) return undefined;
+    running.current?.stop();
+    if (!motion.enabled) {
+      pillX.setValue(activeLayout.x);
+      return undefined;
+    }
+    running.current = motion.timing(pillX, activeLayout.x, {
+      easing: "standard"
+    });
+    running.current.start();
+    return () => running.current?.stop();
+  }, [activeLayout, motion, pillX]);
+  useEffect(() => () => running.current?.stop(), []);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    accessibilityRole: "tablist",
+    style: [segmentedControlTrackStructure(theme), {
+      backgroundColor: colors.track
+    }, disabled && styles.dimmed, style],
+    children: [/*#__PURE__*/_jsx(Animated.View, {
+      pointerEvents: "none",
+      testID: testID ? `${testID}-pill` : undefined,
+      style: [segmentedControlPillStructure(theme), theme.elevation.md, {
+        backgroundColor: colors.pill,
+        width: activeLayout?.width ?? 0,
+        transform: [{
+          translateX: pillX
+        }]
+      }]
+    }), options.map(option => {
+      const selected = option.value === value;
+      const segmentDisabled = disabled || option.disabled === true;
+      const a11y = resolveSegmentedControlSegmentAccessibility({
+        selected,
+        disabled: segmentDisabled
+      });
+      const labelColor = selected ? colors.activeLabel : colors.inactiveLabel;
+      return /*#__PURE__*/_jsxs(Pressable, {
+        testID: testID ? `${testID}-${option.value}` : undefined,
+        accessibilityRole: a11y.accessibilityRole,
+        "aria-selected": a11y["aria-selected"],
+        "aria-disabled": a11y["aria-disabled"],
+        accessibilityLabel: option.label,
+        disabled: a11y.disabled,
+        onPress: segmentDisabled ? undefined : () => onChange(option.value),
+        onLayout: event => handleSegmentLayout(option.value, event),
+        onFocus: () => setFocusedValue(option.value),
+        onBlur: () => setFocusedValue(current => current === option.value ? null : current),
+        hitSlop: hitSlop,
+        style: ({
+          pressed
+        }) => [segmentedControlSegmentStructure(theme, {
+          size,
+          fullWidth: fullWidth ? "on" : "off"
+        }), pressed && !selected && !segmentDisabled && {
+          backgroundColor: colors.pressedSegment
+        }, option.disabled === true && !disabled && styles.dimmed],
+        children: [focusedValue === option.value && /*#__PURE__*/_jsx(View, {
+          pointerEvents: "none",
+          testID: testID ? `${testID}-${option.value}-focus-ring` : undefined,
+          style: [segmentedControlFocusRingStructure(theme), {
+            borderColor: theme.colors.border.focus
+          }]
+        }), option.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
+          name: option.icon,
+          size: spec.iconSize,
+          color: labelColor,
+          strokeWidth: ICON_STROKE
+        }), /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+            fontSize: spec.fontSize,
+            color: labelColor
+          }],
+          children: option.label
+        })]
+      }, option.value);
+    })]
+  });
+}
+const styles = StyleSheet.create({
+  // A disabled control is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
+  dimmed: {
+    opacity: 0.5
+  }
+});
+
+// A consumer's screen re-renders far more often than SegmentedControl's own props change — memo is
+// near-free insurance for a design-system primitive (see CLAUDE.md "Performance" section).
+export const SegmentedControl = /*#__PURE__*/memo(SegmentedControlImpl);
+//# sourceMappingURL=SegmentedControl.js.map

package/lib/module/modules/segmented-control/SegmentedControl.variants.js

@@ -0,0 +1,167 @@
+"use strict";
+
+/**
+ * SegmentedControl's style + behaviour resolution — pure, React/lucide-free, same split as Tabs:
+ *  - STRUCTURE (track padding/radius, segment height/padding, pill radius) lives in the
+ *    `createThemedVariants` resolvers below, registered once per (theme, size) — never rebuilt per
+ *    render.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveSegmentedControlColors`), never a raw
+ *    hex: the track is always `bg.sunken`, the pill is always `bg.surface` (a neutral raised
+ *    surface, NOT the accent role — unlike `ButtonGroup`/`Tabs`, selection here is conveyed by
+ *    elevation + position, not by brand colour).
+ *  - `resolveSegmentedControlSegmentAccessibility` derives the per-segment a11y surface purely, so
+ *    the "selected"/"disabled" contract is unit-testable without rendering React Native.
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+/** Same floor as Button/Input/Tabs/ButtonGroup — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported:
+ * modules stay isolated. */
+export const MIN_TOUCH_TARGET = 44;
+const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+export const SEGMENTED_CONTROL_SIZES = {
+  sm: {
+    height: 32,
+    fontSize: 14,
+    iconSize: 16,
+    hitSlop: slopFor(32)
+  },
+  md: {
+    height: 40,
+    fontSize: 16,
+    iconSize: 18,
+    hitSlop: slopFor(40)
+  }
+};
+/**
+ * Maps the control's fixed visual roles onto ROLE colours — never a hardcoded hex. There is no
+ * per-segment `tone`: like `RadioGroup`/`Tabs`, this is pure indirection, not a union to resolve.
+ *
+ * The pill deliberately reads `bg.surface`, NOT an accent fill: `bg.surface` vs `bg.sunken` alone
+ * measures as low as 1.08:1 (nowhere near WCAG 1.4.11's 3:1 — see `SegmentedControl.test.ts`), so
+ * the boundary between the pill and the track is carried by elevation (`theme.elevation.md`, the
+ * same treatment `Card`'s `elevated` variant uses to differentiate itself with no border either),
+ * not by a colour contrast this pairing could never clear on its own. Selection is additionally
+ * conveyed to assistive tech via `accessibilityState.selected`, never by colour alone.
+ */
+export function resolveSegmentedControlColors(colors) {
+  return {
+    track: colors.bg.sunken,
+    pill: colors.bg.surface,
+    activeLabel: colors.fg.default,
+    inactiveLabel: colors.fg.muted,
+    pressedSegment: colors.bg.raised
+  };
+}
+export function resolveSegmentedControlSegmentAccessibility(input) {
+  return {
+    accessibilityRole: "tab",
+    "aria-selected": input.selected,
+    "aria-disabled": input.disabled,
+    disabled: input.disabled
+  };
+}
+/**
+ * Vertical-only touch expansion. Segments render flush against each other inside the track (no gap
+ * — the sliding pill is the only boundary cue, there is no per-segment border to interrupt), so ANY
+ * horizontal hitSlop would risk the exact overlap `ButtonGroup` documents fixing: React Native
+ * never clips hitSlop to a sibling's bounds and resolves an overlap to whichever segment renders
+ * LATER, not whichever is visually closer to the tap. Rather than tune a per-edge exception (`
+ * ButtonGroup`'s fix), horizontal hitSlop is zero everywhere and every segment's own rendered
+ * `minWidth` (see `segmentedControlSegmentStructure`) carries the width floor instead — the only
+ * touch-target axis this spec requires (`fullWidth` segments are already well over 44dp in
+ * practice; `minWidth` protects the narrow-content case).
+ */
+export function resolveSegmentedControlSegmentHitSlop(size) {
+  const slop = SEGMENTED_CONTROL_SIZES[size].hitSlop;
+  return {
+    top: slop,
+    bottom: slop,
+    left: 0,
+    right: 0
+  };
+}
+
+/** The outer track — padded so the pill has room to sit inset from the track's own edge. */
+export const segmentedControlTrackStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    position: "relative",
+    borderRadius: theme.radii.base,
+    padding: theme.space[1]
+  }
+}));
+
+/**
+ * The pill. `theme.radii.sm` — one step down from the track's `theme.radii.base` — nests cleanly
+ * inside the track's own `space[1]` inset, the same "inner radius ≈ outer radius − inset" geometry
+ * a nested rounded rect needs to read as concentric rather than mismatched. `top`/`bottom` pin it to
+ * the row's own height (set by the segments, its flow siblings); `left`/`width` are driven by
+ * `Animated.Value`s in `SegmentedControl.tsx`, keyed off each segment's own `onLayout` measurement —
+ * same mechanism as `Tabs`' sliding indicator.
+ */
+export const segmentedControlPillStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    borderRadius: theme.radii.sm
+  }
+}));
+
+/**
+ * The keyboard/AT focus ring drawn over one segment's own bounds — the same inset treatment
+ * `bottomNavFocusRingStructure` uses. Segments render flush against each other inside the track, so
+ * an outset ring would spill over its neighbour; and the sliding pill marks SELECTION, never focus.
+ * Its colour is applied inline over this, never hardcoded here.
+ */
+export const segmentedControlFocusRingStructure = createThemedVariants(theme => ({
+  base: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderWidth: theme.borderWidths.thick,
+    borderRadius: theme.radii.sm
+  }
+}));
+
+/**
+ * One segment's layout. `minWidth` is the real touch-target floor for the WIDTH axis (see
+ * `resolveSegmentedControlSegmentHitSlop` — horizontal hitSlop can't safely carry it here). `height`
+ * is fixed (not a minimum) so the vertical hitSlop math holds against what actually renders, and so
+ * the pill (pinned to the row's height via `top: 0, bottom: 0`) matches exactly.
+ */
+export const segmentedControlSegmentStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    minWidth: MIN_TOUCH_TARGET,
+    borderRadius: theme.radii.sm,
+    columnGap: theme.space[1]
+  },
+  variants: {
+    size: {
+      sm: {
+        height: SEGMENTED_CONTROL_SIZES.sm.height,
+        paddingHorizontal: theme.space[2]
+      },
+      md: {
+        height: SEGMENTED_CONTROL_SIZES.md.height,
+        paddingHorizontal: theme.space[3]
+      }
+    },
+    fullWidth: {
+      on: {
+        flex: 1
+      },
+      off: {}
+    }
+  },
+  defaultVariants: {
+    size: "md",
+    fullWidth: "on"
+  }
+}));
+//# sourceMappingURL=SegmentedControl.variants.js.map

package/lib/module/modules/segmented-control/index.js

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

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

@@ -15,17 +15,19 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 
 | File | Role |
 |------|------|
-| `Select.tsx` | The component. Trigger + `Modal` composition, open/close state, focus handling. |
+| `Select.tsx` | The component. Trigger + `Modal` composition, open/close state, focus handling. Option list is `core/list`'s `VirtualList` (device-tier windowing over FlashList-or-FlatList), built only while `open`. |
 | `Select.variants.ts` | Pure resolvers (`SELECT_SIZES`, `resolveSelectTriggerColors`, `resolveSelectRowColors`, `resolveSelectAccessibility`) + the themed structural resolvers (`selectTriggerStructure`, `selectOverlayStructure`, `selectSheetStructure`, `selectRowStructure`). No React, no lucide. |
 | `index.ts` | Public surface: `Select`, `SelectProps`, `SelectOption`, `SelectSize`. |
 | `__tests__/Select.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
-| `__tests__/Select.render.test.tsx` | Render: display, open/close, disabled gating, selection, backdrop dismiss, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/Select.render.test.tsx` | Render: display, open/close, disabled gating, selection, backdrop dismiss, the row's resolved 44dp `minHeight`, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/Select.keyboard.test.tsx` | Web keyboard: tab stop opens on the selected option, arrows/Home/End/typeahead, Space selection, Escape. |
+| `__tests__/Select.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` | `{ label: string; value: string }[]` | — | Required. |
+| `options` | `{ label: string; value: string; leading?: ReactNode }[]` | — | Required. `leading` is an optional fixed-size adornment (status chip / priority glyph / avatar) rendered before the row label AND on the trigger while that option is selected — the ReactNode content-slot precedent set by `ListItem`'s `leading`. |
 | `value` | `string` | — | The currently selected option's `value`. |
 | `onValueChange` | `(value: string) => void` | — | Required. Fired on row press; the menu closes right after. |
 | `placeholder` | `string` | — | Shown when `value` matches no option. |
@@ -33,7 +35,7 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 | `disabled` | `boolean` | `false` | Blocks opening the menu; dimmed like Button'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` and `${testID}-option-${value}`. |
+| `testID` | `string` | — | Also seeds `${testID}-backdrop` and `${testID}-option-${value}` (+ `-content` / `-check` on that row's animated nodes). |
 
 No `icon` prop — the chevron/check glyphs are fixed to the component's own semantics, not
 caller-configurable.
@@ -42,21 +44,24 @@ caller-configurable.
 
 - **2.5.x target size** — every trigger size reaches ≥ 44dp via `hitSlop`; option rows have a
   44dp `minHeight` directly (they're list items, not a single control that can grow with slop).
-- **4.1.2** — the trigger is `accessibilityRole="button"` with `accessibilityState.expanded`
-  tracking whether the option list is showing.
+- **4.1.2** — the trigger is `accessibilityRole="button"` with flat `aria-expanded` tracking whether
+  the option list 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) and
   the active row's "check" glyph are measured ≥ 3:1.
-- Selection is conveyed by the "check" glyph + `accessibilityState.selected`, never by a row
-  background swap: `bg.selected` isn't proven ≥ 4.5:1 against `fg.default` on every brand
-  (measured: fails on radiant/rosewood light), so `resolveSelectRowColors` keeps the row fill at
-  `bg.surface` for every row, selected or not.
-- Each option row is `accessibilityRole="menuitem"` with `accessibilityState={{ selected }}`; the
-  "check" icon is the sighted echo of the same state, never the only signal.
-- **2.3.3** — the menu's `animationType` is `"none"` instead of `"fade"` when
-  `useReducedMotion()` is true.
+- Selection is conveyed by the "check" glyph + `aria-selected`, never by a row background swap:
+  `bg.selected` isn't proven ≥ 4.5:1 against `fg.default` on every brand (measured: fails on
+  radiant/rosewood light), so `resolveSelectRowColors` keeps the row fill at `bg.surface` for every
+  row, selected or not.
+- Each option row is `accessibilityRole="menuitem"` with flat `aria-selected`; the "check" icon is
+  the sighted echo of the same state, never the only signal.
+- **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__/Select.motion.test.tsx`.
 - Disabled is exempt from the contrast minimum (WCAG 1.4.3) — like Button, it's signalled by a
   uniform `opacity: 0.5` dim rather than a separate, still-must-pass colour pair.
 
@@ -71,6 +76,23 @@ caller-configurable.
 4. `style` exception — Select exposes `containerStyle` (the documented exception for 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 **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 `menuitem` on Enter, and Space is
+supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `button` tag/role, which
+`menuitem` deliberately is not) — passing `onActivate` too would select twice.
+
+The list container is `SELECT_LISTBOX_ROLE`: RN 0.86's role unions have no `listbox`, so the
+widening is one audited cast in `Select.variants.ts` rather than a cast at the call site.
+
 ## Known gaps
 
 - No search/filter or multi-select — v1 is a single-select list, matching the spec this module
@@ -88,4 +110,49 @@ caller-configurable.
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The option rows use host `Pressable`/`Text` plus this library's `Icon`, which only ever receives primitive props — 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 (e.g. every org user, one
+`Avatar` per row) only mounts the rows near the viewport instead of firing every row's image request
+at once — and the whole sheet is built only while `open`, never while the trigger alone is on screen.
+Rows get `bg.sunken` press feedback (`pressedRow` — same non-`bg.hover` reasoning as
+`RadioGroup`/`Accordion`), contrast-measured in `Select.test.ts`.
+
+### Re-render contract (what keeps `SelectOptionRow`'s `memo` alive)
+
+`SelectOptionRow` is `React.memo`'d and takes the option itself, so every value it receives must be
+referentially stable across a parent render that changed nothing for it:
+
+- `resolveSelectTriggerColors` / `resolveSelectRowColors` / `resolveSelectAccessibility` and the
+  `select*Structure(theme)` resolvers are `useMemo`'d on their real inputs (`theme.colors`,
+  `[theme, size]`, …). `rowColors` is a row prop — an unmemoized call there re-rendered *every*
+  visible row on any parent render, which made the row memo dead.
+- `options.find(...)` for the selected option is `useMemo`'d; `renderItem`/`keyExtractor`/
+  `selectOption` and the focus/blur handlers are `useCallback`'d (eslint enforces the first two).
+- **`SelectOption.leading` is rendered into a fixed slot** (`selectRowLeadingStructure`). 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 that feed hot nodes (root container, trigger, sheet, label/value text) are `useMemo`'d;
+  the backdrop is a static `StyleSheet` entry. Inside the row, `selectRowStructure(theme)` is memoized
+  so the `Pressable` style callback doesn't rebuild it on every 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
+  `selectRowStructure`, 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, so nothing animates
+  during scrolling. The icon keeps its `{selected && …}` conditional render.
+- **Sheet reveal** — `useReveal(open)` on the inner sheet panel, 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 to disagree with it, and no extra render per open/close. `useEnterExit`'s `mounted` gate was
+  dropped here: RN's Modal keeps children rendered until `modalDismissed` anyway, and on the
+  web-portal path it left a full-screen backdrop `Pressable` capturing touches through the fade-out.
+  `MultiSelect`/`Combobox` use the identical 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.