pixelize-native-library 1.2.0 → 1.3.0

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

@@ -2,8 +2,7 @@
 
 `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
+measured position — the same `onLayout` + shared-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
@@ -14,7 +13,7 @@ accent-coloured fill: elevation, not colour, is the selection cue here.
 | `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.render.test.tsx` | Render: track/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
@@ -30,9 +29,10 @@ accent-coloured fill: elevation, not colour, is the selection cue here.
 | `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.
+No `tone`/`variant` union — the selected fill is always the neutral raised pill; there is nothing
+for a closed union to resolve, the same reasoning `Tabs`/`RadioGroup` document for their own
+single-purpose shape. Track and pill backgrounds are resolved live from `floatingBackground`, not
+from `resolveSegmentedControlColors` (which only maps the two label colours) — see 1.4.11 below.
 
 ## Accessibility contract (WCAG)
 
@@ -49,32 +49,33 @@ always `bg.sunken`; there is nothing for a closed union to resolve, the same rea
   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.
+- **1.4.3** — the active label (`fg.default`, read on the pill — `floatingBackground(theme, 'md')`)
+  and the inactive label (`fg.muted`, read on the track — `floatingBackground(theme, 'sm')`) are
+  each measured ≥ 4.5:1 for all 9 brands × both modes, including the inactive label against its own
+  pressed overlay (`stateLayerScrim` at `STATE_LAYER_OPACITY.pressed`, composited onto the track).
+- **1.4.11** — deliberately **not** satisfied by colour: the pill/track pairing measures ~1.1:1,
+  nowhere near 3:1, in dark mode. The pill is one `floatingBackground` level above the track
+  (`'md'` vs `'sm'`, the same step `Card`'s `elevated` variant uses), which guarantees it is
+  **lighter**, never darker — a real regression once shipped raw `bg.surface` under `theme.elevation.md`,
+  which measured pill *darker* than track (1.04–1.12:1 inverted) since that shadow token is
+  mode-unaware. Selection reaches assistive tech independently via `aria-selected`, never by colour.
 - **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.
+- **2.3.3** — only the pill's `translateX` animates: one Reanimated shared value driven off each
+  segment's own `onLayout` measurement (the pill's `width` is set straight from that measurement, not
+  tweened). Under reduced motion the value is assigned directly — an instant snap instead of a tween,
+  verified in the render and motion tests by asserting `withTiming` is not called.
 
 ## 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.
+The slide goes through **`useMotion()`**, never a direct `MOTION_DURATION` import — only
+`motion.timing` applies `MOTION_TIER[tier].durationScale`, so a raw constant would ignore the device
+tier. Reduce-motion is `motion.enabled` — no second `useReducedMotion()` call (`core/motion/MODULE.md`
+rule 6). Segment presses use `usePressState` (scale + state-layer overlay), a bounded
+`android_ripple` (gated off while the segment is disabled), and fire `haptics.selection()` on change.
+The in-flight slide is stopped on effect cleanup and on unmount.
 
 ## Patterns copied from Tabs / ButtonGroup / Card
 
@@ -90,10 +91,13 @@ rule 6). The in-flight slide is stopped on effect cleanup and on unmount.
 
 ## Design decisions specific to this module
 
-- **The pill is neutral (`bg.surface`), not accent-coloured.** This is what the spec this module
+- **The pill is a neutral raised 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.
+- **Nested radii stay concentric.** Pill, focus ring and segment all use `radii.base` (8) —
+  `radii.md` (12) minus the track's `space[1]` inset (4) — never `radii.sm`, which under-rounds
+  them by 4dp against the track's own corner.
 - **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

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

@@ -1,30 +1,104 @@
 "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.
- */
+/** Inline single-choice control; see `MODULE.md` for the elevation/a11y contract. */
 
-import { memo, useCallback, useEffect, useRef, useState } from "react";
-import { Animated, Pressable, StyleSheet, Text, View } from "react-native";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
 import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
 import { Icon } from "../../core/icon/index.js";
+import { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/index.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;
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
+const SegmentButton = /*#__PURE__*/memo(function SegmentButton({
+  option,
+  selected,
+  segmentDisabled,
+  size,
+  fullWidth,
+  labelColor,
+  hitSlop,
+  focused,
+  onChange,
+  onLayout,
+  onFocus,
+  onBlur,
+  testID
+}) {
+  const theme = useTheme();
+  const press = usePressState(segmentDisabled);
+  const a11y = resolveSegmentedControlSegmentAccessibility({
+    selected,
+    disabled: segmentDisabled
+  });
+  const spec = SEGMENTED_CONTROL_SIZES[size];
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android" || segmentDisabled) return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: false
+    };
+  }, [segmentDisabled, theme.mode]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
+    testID: testID,
+    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 => {
+      press.onLayout(event);
+      onLayout(option.value, event);
+    },
+    onFocus: () => onFocus(option.value),
+    onBlur: () => onBlur(option.value),
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    hitSlop: hitSlop,
+    android_ripple: androidRipple,
+    style: [segmentedControlSegmentStructure(theme, {
+      size,
+      fullWidth: fullWidth ? "on" : "off"
+    }), {
+      overflow: "hidden"
+    }, press.animatedStyle, option.disabled === true && !segmentDisabled && styles.dimmed],
+    children: [/*#__PURE__*/_jsx(Reanimated.View, {
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle, {
+        pointerEvents: "none"
+      }]
+    }), focused && /*#__PURE__*/_jsx(View, {
+      testID: testID ? `${testID}-focus-ring` : undefined,
+      style: [segmentedControlFocusRingStructure(theme), {
+        borderColor: theme.colors.border.focus,
+        pointerEvents: "none"
+      }]
+    }), 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
+    })]
+  });
+});
 function SegmentedControlImpl({
   options,
   value,
@@ -37,8 +111,8 @@ function SegmentedControlImpl({
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const haptics = useHaptics();
   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
@@ -46,6 +120,11 @@ function SegmentedControlImpl({
   const [focusedValue, setFocusedValue] = useState(null);
   const pillX = useAnimatedValue(0);
   const running = useRef(null);
+  const pillMotionStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateX: pillX.value
+    }]
+  }));
   const activeLayout = layouts[value];
   const handleSegmentLayout = useCallback((optionValue, event) => {
     const {
@@ -68,7 +147,7 @@ function SegmentedControlImpl({
     if (activeLayout === undefined) return undefined;
     running.current?.stop();
     if (!motion.enabled) {
-      pillX.setValue(activeLayout.x);
+      pillX.value = activeLayout.x;
       return undefined;
     }
     running.current = motion.timing(pillX, activeLayout.x, {
@@ -78,69 +157,44 @@ function SegmentedControlImpl({
     return () => running.current?.stop();
   }, [activeLayout, motion, pillX]);
   useEffect(() => () => running.current?.stop(), []);
+  const handleChange = useCallback(optionValue => {
+    haptics.selection();
+    onChange(optionValue);
+  }, [haptics, onChange]);
   return /*#__PURE__*/_jsxs(View, {
     testID: testID,
     accessibilityRole: "tablist",
     style: [segmentedControlTrackStructure(theme), {
-      backgroundColor: colors.track
+      backgroundColor: floatingBackground(theme, "sm"),
+      ...floatingSurfaceStyle(theme, "sm")
     }, disabled && styles.dimmed, style],
-    children: [/*#__PURE__*/_jsx(Animated.View, {
-      pointerEvents: "none",
+    children: [/*#__PURE__*/_jsx(Reanimated.View, {
       testID: testID ? `${testID}-pill` : undefined,
-      style: [segmentedControlPillStructure(theme), theme.elevation.md, {
-        backgroundColor: colors.pill,
+      style: [segmentedControlPillStructure(theme), {
+        backgroundColor: floatingBackground(theme, "md"),
         width: activeLayout?.width ?? 0,
-        transform: [{
-          translateX: pillX
-        }]
+        ...floatingSurfaceStyle(theme, "md")
+      }, pillMotionStyle, {
+        pointerEvents: "none"
       }]
     }), 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),
+      return /*#__PURE__*/_jsx(SegmentButton, {
+        option: option,
+        selected: selected,
+        segmentDisabled: segmentDisabled,
+        size: size,
+        fullWidth: fullWidth,
+        labelColor: labelColor,
         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
-        })]
+        focused: focusedValue === option.value,
+        onChange: handleChange,
+        onLayout: handleSegmentLayout,
+        onFocus: setFocusedValue,
+        onBlur: v => setFocusedValue(current => current === v ? null : current),
+        testID: testID ? `${testID}-${option.value}` : undefined
       }, option.value);
     })]
   });

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

@@ -1,23 +1,10 @@
 "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.
- */
+/** Pure style + a11y resolvers for SegmentedControl — no React, no lucide. */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 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 { MIN_TOUCH_TARGET };
 export const SEGMENTED_CONTROL_SIZES = {
   sm: {
     height: 32,
@@ -32,24 +19,11 @@ export const SEGMENTED_CONTROL_SIZES = {
     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.
- */
+/** Label colours only — track/pill/pressed backgrounds are resolved live in `SegmentedControl.tsx`. */
 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
+    inactiveLabel: colors.fg.muted
   };
 }
 export function resolveSegmentedControlSegmentAccessibility(input) {
@@ -86,25 +60,19 @@ export const segmentedControlTrackStructure = createThemedVariants(theme => ({
   base: {
     flexDirection: "row",
     position: "relative",
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     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.
- */
+/** `radii.base` (12 − the track's `space[1]` inset of 4) nests concentric inside `radii.md`. */
 export const segmentedControlPillStructure = createThemedVariants(theme => ({
   base: {
     position: "absolute",
     top: 0,
     bottom: 0,
-    borderRadius: theme.radii.sm
+    borderRadius: theme.radii.base
   }
 }));
 
@@ -122,7 +90,7 @@ export const segmentedControlFocusRingStructure = createThemedVariants(theme =>
     right: 0,
     bottom: 0,
     borderWidth: theme.borderWidths.thick,
-    borderRadius: theme.radii.sm
+    borderRadius: theme.radii.base
   }
 }));
 
@@ -138,7 +106,7 @@ export const segmentedControlSegmentStructure = createThemedVariants(theme => ({
     alignItems: "center",
     justifyContent: "center",
     minWidth: MIN_TOUCH_TARGET,
-    borderRadius: theme.radii.sm,
+    borderRadius: theme.radii.base,
     columnGap: theme.space[1]
   },
   variants: {

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

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

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

@@ -17,21 +17,24 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 |------|------|
 | `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`. |
+| `index.ts` | Public surface: `Select`, `SelectProps`, `SelectOption`, `SelectOptionTone`, `SelectOptionCustomColors`, `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, 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. |
+| `__tests__/Select.motion.test.tsx` | Reduce-motion (WCAG 2.3.3): check-glyph and press feedback snap to their final values, and no Reanimated timing runs. |
+| `__tests__/Select.dom.test.tsx` | Real DOM (`jest.web.config.js`): the trigger and sheet under `react-dom`. |
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `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`. |
+| `options` | `SelectOption[]` | — | Required. Each option may set `tone` / `customColors` (same `custom` escape hatch as `Badge`). |
 | `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. |
 | `label` | `string` | — | Field label above the trigger; also folded into its accessible name. |
+| `status` | `InputStatus` | `"default"` | `"error"` paints the danger border and sets `aria-invalid`, same union as `Input`. |
+| `errorText` | `string` | — | Rendered below the trigger, but only while `status="error"`. |
 | `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. |
@@ -40,6 +43,16 @@ context + a stateless helper with no React-tree footprint of its own, not a depe
 No `icon` prop — the chevron/check glyphs are fixed to the component's own semantics, not
 caller-configurable.
 
+### `SelectOption`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `label` | `string` | Row label (required). |
+| `value` | `string` | Stable id (required). |
+| `leading` | `ReactNode` | Optional fixed-size adornment on the row and trigger. |
+| `tone` | `SelectOptionTone` | Optional label colour from role tokens, or `"custom"`. |
+| `customColors` | `{ bg, fg }` | Required when `tone="custom"`. Label reads `fg`. |
+
 ## Accessibility contract (WCAG)
 
 - **2.5.x target size** — every trigger size reaches ≥ 44dp via `hitSlop`; option rows have a
@@ -56,14 +69,25 @@ caller-configurable.
   `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.
+- Each option row is `accessibilityRole="option"` with flat `aria-selected`; the "check" icon is
+  the sighted echo of the same state, never the only signal. **2026-08 sweep:** rows were
+  `accessibilityRole="menuitem"`, which made `aria-selected` invalid ARIA (only valid on
+  `option`/`row`/`tab`/`gridcell`/`treeitem`). Unlike `OrgSwitcher`'s identical bug — fixed to
+  `role="radio"` + `aria-checked` because that sheet's row list carries no `listbox` role — Select's
+  rows sit inside a `SELECT_LISTBOX_ROLE` (`"listbox"`) container, so `option` + `aria-selected` is
+  the textbook-correct ARIA listbox pattern; only the row's `accessibilityRole` changed, `aria-selected`
+  was already the right prop.
 - **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.
+- **Android touch feedback** — the trigger and every option row carry `android_ripple`
+  (`rippleColor(theme.mode)`, `borderless: false`), gated on `Platform.OS === "android"`. The trigger
+  and the sheet container both gained `overflow: "hidden"` so the ripple clips to their rounded
+  bounds — rows have no radius of their own, the sheet does. The backdrop carries no ripple; it is
+  `accessible={false}` and not a real press target.
 
 ## Patterns copied from Button (the reference module)
 
@@ -86,9 +110,9 @@ the tab stop, and `useFocusTrap` needs the focused node to still be tabbable or
 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
+**`useRovingKeys` gets no `onActivate`.** RNW already presses on Enter regardless of role, 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.
+`option` 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.
@@ -99,9 +123,7 @@ widening is one audited cast in `Select.variants.ts` rather than a cast at the c
   was built against. A future `Combobox`/`MultiSelect` would be a separate module, not a prop
   added here (closed-prop-contract).
 - The trigger's focus ring is a border-colour swap (`border.focus`), not Button's offset ring —
-  intentional: Select mimics Input-style focus conventions, which this library has not built an
-  `Input` module to confirm against yet (parallel build). Revisit if `Input` lands a different
-  convention and the two should be reconciled.
+  intentional: Select follows `input/`'s focus convention rather than Button's.
 - No measured anchor position — the overlay always centers within its container, regardless of
   where the trigger sits on screen, same as Menu's identical `justifyContent: "center"` overlay
   (see `menu/MODULE.md`'s Known gaps). A real anchor would need `Button` to forward refs (it
@@ -156,3 +178,5 @@ Via `core/motion` only — `opacity`/`transform`, native driver, all reduce-moti
 
 - 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.
+
+Backdrop scrim uses MOTION_TRANSFORM.scrimOpacity (aligned with Modal).