pixelize-native-library 1.0.7 → 1.2.1

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

@@ -0,0 +1,168 @@
+"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.md,
+    borderCurve: "continuous",
+    padding: theme.space[1]
+  }
+}));
+
+/**
+ * The pill. `theme.radii.sm` — one step down from the track's `theme.radii.md` — 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; 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. |
@@ -33,32 +35,56 @@ 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.
 
+### `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
   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="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)
 
@@ -71,6 +97,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 on Enter regardless of role, and Space is
+supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `button` tag/role, which
+`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.
+
 ## Known gaps
 
 - No search/filter or multi-select — v1 is a single-select list, matching the spec this module
@@ -88,4 +131,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.