pixelize-native-library 1.0.6 → 1.2.0

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

@@ -9,7 +9,7 @@ primitive" philosophy `Modal`/`Select` already apply to RN's raw `<Modal>`.
 | File | Role |
 |------|------|
 | `Slider.tsx` | The component. `PanResponder` wiring, layout measurement, accessibility actions. |
-| `Slider.variants.ts` | Pure drag math (`resolveSliderPositionValue`, `snapSliderValue`, `stepSliderValue`, …), colour resolvers, accessibility resolver, and the `createThemedVariants` structural resolvers. No React, no PanResponder. |
+| `Slider.variants.ts` | Pure drag math (`resolveSliderPositionValue`, `snapSliderValue`, `stepSliderValue`, …), the keyboard map (`resolveSliderKeyValue`, `sliderPageStep`), colour resolvers, accessibility resolver, and the `createThemedVariants` structural resolvers. No React, no PanResponder. |
 | `index.ts` | Public surface: `Slider`, `SliderProps`, `SliderSize`. |
 | `__tests__/Slider.test.ts` | Pure: WCAG contrast (all brands × modes) + drag-math/step/accessibility contracts. |
 | `__tests__/Slider.render.test.tsx` | Render: layout-driven positioning, the REAL `PanResponder` gesture fired end-to-end, increment/decrement actions, disabled. |
@@ -27,7 +27,7 @@ primitive" philosophy `Modal`/`Select` already apply to RN's raw `<Modal>`.
 | `size` | `sm \| md` | `md` | Closed union — track height + thumb diameter. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once. No `width`/`fullWidth` prop — the row stretches to its container by RN's default `alignItems: stretch`, same as `ProgressBar`. |
 | `accessibilityLabel` | `string` | — | **Required** — the control structurally never renders visible text, so this is the only accessible name a screen reader has (mirrors `Switch`'s and `Button`'s icon-only contract). |
-| `testID` | `string` | — | Also stamps `${testID}-fill` and `${testID}-thumb`. |
+| `testID` | `string` | — | Also stamps `${testID}-fill`, `${testID}-thumb`, and `${testID}-focus-ring` (present only while focused). |
 
 ## Two design choices (spec left these open — documented here)
 
@@ -45,6 +45,20 @@ primitive" philosophy `Modal`/`Select` already apply to RN's raw `<Modal>`.
 
 ## Accessibility contract (WCAG)
 
+- **2.1.1 (keyboard)** — the root sets `tabIndex={disabled ? -1 : 0}` (plus `focusable` for
+  native/TV) and handles `onKeyDown`. Both are load-bearing: RNW emits a `tabIndex` only for an
+  explicit `tabIndex`/`focusable`, a natively-focusable tag, or a role in
+  `button|checkbox|link|radio|textbox|switch`. `accessibilityRole="adjustable"` maps to
+  `role="slider"`, which is in none of them — and RNW does not forward RN's `accessible` prop at all
+  — so before this the control could not be reached by Tab, and `accessibilityActions` (a
+  screen-reader gesture) was the only non-pointer path. Keys, via `resolveSliderKeyValue`:
+  Left/Down decrement and Right/Up increment by `step`, Home/End jump to `min`/`max`, PageDown/PageUp
+  move by `sliderPageStep` (the whole number of steps nearest a tenth of the range, never fewer than
+  one). Every one of them fires `onSlidingComplete`, and calls `preventDefault` so the page does not
+  scroll instead. RN's TypeScript `ViewPropTypes.d.ts` omits `onKeyDown` (its Flow types declare it),
+  so the root `View` is re-typed once, locally, in `Slider.tsx`.
+- **2.4.7 (focus visible)** — Button's `border.focus` ring, drawn a 2dp gap OUTSIDE the row (nothing
+  clips the slider), rendered only while focused and never while disabled.
 - **2.5.7 (dragging movements)** — `accessibilityRole="adjustable"` with `accessibilityActions`
   declaring `increment`/`decrement` and `onAccessibilityAction` adjusting `value` by `step`, clamped.
   iOS's `adjustable` trait already offers these via the two-finger swipe gesture without the actions
@@ -65,8 +79,12 @@ primitive" philosophy `Modal`/`Select` already apply to RN's raw `<Modal>`.
     actually carries the boundary, not the 2dp ring.
 - **2.3.3 (reduced motion)** — N/A. No animation: the thumb's position is a direct function of
   `value`, never an eased/animated transition.
-- `accessibilityValue={{ min, max, now }}` — `now` is clamped onto `[min, max]` even if a caller
-  passes an out-of-range `value`, so a screen reader never announces something the track can't render.
+- Flat `aria-valuemin`/`aria-valuemax`/`aria-valuenow`, not `accessibilityValue={{…}}` —
+  react-native-web 0.21 drops the object form, so this used to announce `role="slider"` with no
+  position on web. The host here is a `View`, which merges the flat props into `accessibilityValue`
+  natively, so one form is correct on both platforms. `aria-valuenow` is clamped onto `[min, max]`
+  even if a caller passes an out-of-range `value`, so a screen reader never announces something the
+  track can't render. Proven on the real DOM by `__tests__/Slider.dom.test.tsx`.
 
 ## Patterns
 
@@ -88,8 +106,16 @@ primitive" philosophy `Modal`/`Select` already apply to RN's raw `<Modal>`.
 
 ## Known gaps
 
-None.
+- The thumb does not move under an active drag on a keyboard-only device — that is by design (there
+  is no drag), but it also means `onSlidingComplete` fires per keystroke rather than once per
+  "gesture", so a consumer that persists on every completion will write once per arrow press.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `applyTouch`/`handleLayout`/`handleAccessibilityAction` are only wired to the root `View`'s host props, never handed to a library child component — nothing 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/slider/Slider.js

@@ -21,9 +21,19 @@
 
 import { memo, useRef, useState } from "react";
 import { PanResponder, StyleSheet, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
-import { resolveSliderAccessibility, resolveSliderPositionValue, resolveSliderThumbColors, resolveSliderTrackColors, sliderFillStructure, sliderRowStructure, SLIDER_HIT_SLOP, SLIDER_SIZES, sliderThumbStructure, sliderTrackStructure, sliderValueToFraction, stepSliderValue } from "./Slider.variants.js";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveSliderAccessibility, resolveSliderKeyValue, resolveSliderPositionValue, resolveSliderThumbColors, resolveSliderTrackColors, sliderFillStructure, sliderRowStructure, SLIDER_HIT_SLOP, SLIDER_SIZES, sliderThumbStructure, sliderTrackStructure, sliderValueToFraction, stepSliderValue } from "./Slider.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * RN's Flow `ViewProps` declares `onKeyDown` and react-native-web forwards it straight to the DOM
+ * node, but RN's TypeScript `ViewPropTypes.d.ts` omits it — this re-type is the only cast here.
+ */
+const KeyboardView = View;
+
+// Same offset ring as Button: `border.focus` a small gap OUTSIDE the control, on the canvas, which
+// is the surface that role token is proven ≥ 3:1 against (WCAG 2.4.11).
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_GAP = 2;
 export const Slider = /*#__PURE__*/memo(function Slider(props) {
   const {
     value,
@@ -40,6 +50,8 @@ export const Slider = /*#__PURE__*/memo(function Slider(props) {
   } = props;
   const theme = useTheme();
   const [trackWidth, setTrackWidth] = useState(0);
+  // Keyboard / external-keyboard / TV-remote focus (no-op on pure touch, correct everywhere else).
+  const [focused, setFocused] = useState(false);
 
   // The PanResponder callbacks below are created ONCE (see `useState` lazy init further down) and
   // must never close over a stale render's props. Reassigning a ref's `.current` in the render body
@@ -110,6 +122,13 @@ export const Slider = /*#__PURE__*/memo(function Slider(props) {
     setTrackWidth(event.nativeEvent.layout.width);
   };
 
+  /** One non-drag adjustment: report it, then mirror a drag's release. */
+  const commitValue = next => {
+    const state = live.current;
+    state.onValueChange(next);
+    state.onSlidingComplete?.(next);
+  };
+
   // WCAG 2.5.7 — the non-drag alternative. iOS's `adjustable` trait already offers increment/decrement
   // via the two-finger swipe gesture; Android TalkBack needs them declared as `accessibilityActions`
   // (below) to surface them at all.
@@ -120,19 +139,42 @@ export const Slider = /*#__PURE__*/memo(function Slider(props) {
       actionName
     } = event.nativeEvent;
     if (actionName !== "increment" && actionName !== "decrement") return;
-    const next = stepSliderValue(state.value, actionName === "increment" ? 1 : -1, state.min, state.max, state.step);
-    state.onValueChange(next);
-    state.onSlidingComplete?.(next);
+    commitValue(stepSliderValue(state.value, actionName === "increment" ? 1 : -1, state.min, state.max, state.step));
+  };
+
+  // WCAG 2.1.1 — the sighted keyboard user's only path in. `accessibilityActions` above is a
+  // screen-reader gesture, so without this the control is operable by pointer alone.
+  const handleKeyDown = event => {
+    const state = live.current;
+    if (state.disabled) return;
+    const next = resolveSliderKeyValue(event.nativeEvent.key, state);
+    if (next === undefined) return;
+    // Arrow/Page/Home/End would otherwise scroll the page out from under the control.
+    event.preventDefault?.();
+    commitValue(next);
   };
-  return /*#__PURE__*/_jsxs(View, {
+  const handleFocus = () => setFocused(true);
+  const handleBlur = () => setFocused(false);
+  return /*#__PURE__*/_jsxs(KeyboardView, {
     testID: testID,
     accessible: true,
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: accessibilityLabel,
-    accessibilityValue: a11y.accessibilityValue,
-    accessibilityState: a11y.accessibilityState,
+    "aria-valuemin": a11y["aria-valuemin"],
+    "aria-valuemax": a11y["aria-valuemax"],
+    "aria-valuenow": a11y["aria-valuenow"],
+    "aria-disabled": a11y["aria-disabled"],
     accessibilityActions: a11y.accessibilityActions,
-    onAccessibilityAction: handleAccessibilityAction,
+    onAccessibilityAction: handleAccessibilityAction
+    // RNW emits `tabIndex` only for an explicit one, an explicit `focusable`, a natively-focusable
+    // tag, or roles in button|checkbox|link|radio|textbox|switch — `adjustable` maps to
+    // `role="slider"`, which is in none of them, so without this Tab skips the control entirely.
+    ,
+    tabIndex: disabled ? -1 : 0,
+    focusable: !disabled,
+    onKeyDown: handleKeyDown,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
     onLayout: handleLayout,
     onStartShouldSetResponder: panResponder.panHandlers.onStartShouldSetResponder,
     onMoveShouldSetResponder: panResponder.panHandlers.onMoveShouldSetResponder,
@@ -145,7 +187,14 @@ export const Slider = /*#__PURE__*/memo(function Slider(props) {
     style: [sliderRowStructure(theme, {
       size
     }), disabled && styles.dimmed, style],
-    children: [/*#__PURE__*/_jsx(View, {
+    children: [focused && !disabled && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      testID: testID === undefined ? undefined : `${testID}-focus-ring`,
+      style: [styles.focusRing, {
+        borderColor: theme.colors.border.focus,
+        borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+      }]
+    }), /*#__PURE__*/_jsx(View, {
       pointerEvents: "none",
       style: [sliderTrackStructure(theme, {
         size
@@ -178,6 +227,14 @@ const styles = StyleSheet.create({
   // — the same treatment `Button`/`Checkbox`/`NumberInput` use.
   dimmed: {
     opacity: 0.5
+  },
+  focusRing: {
+    position: "absolute",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH
   }
 });
 //# sourceMappingURL=Slider.js.map

package/lib/module/modules/slider/Slider.variants.js

@@ -109,6 +109,51 @@ export function resolveSliderPositionValue(input) {
 export function stepSliderValue(value, direction, min, max, step) {
   return clampSliderValue(value + direction * step, min, max);
 }
+
+/** How much of the range PageUp/PageDown cover, before rounding onto a whole number of `step`s. */
+export const SLIDER_PAGE_FRACTION = 0.1;
+
+/**
+ * The coarse PageUp/PageDown amount — the whole number of `step`s nearest a tenth of the range,
+ * never fewer than one, so a 0–5 slider still pages by `step` instead of rounding down to zero.
+ */
+export function sliderPageStep(min, max, step) {
+  const safeStep = step > 0 ? step : 1;
+  const range = max - min;
+  if (range <= 0) return safeStep;
+  return Math.max(1, Math.round(range * SLIDER_PAGE_FRACTION / safeStep)) * safeStep;
+}
+/**
+ * The WAI-ARIA slider keyboard contract, resolved purely: Left/Down decrement and Right/Up increment
+ * by `step`, Home/End jump to the bounds, PageDown/PageUp move by `sliderPageStep`. Returns
+ * `undefined` for any other key, which is also how the caller knows not to swallow that keystroke.
+ */
+export function resolveSliderKeyValue(key, input) {
+  const {
+    value,
+    min,
+    max,
+    step
+  } = input;
+  switch (key) {
+    case "ArrowLeft":
+    case "ArrowDown":
+      return stepSliderValue(value, -1, min, max, step);
+    case "ArrowRight":
+    case "ArrowUp":
+      return stepSliderValue(value, 1, min, max, step);
+    case "Home":
+      return clampSliderValue(min, min, max);
+    case "End":
+      return clampSliderValue(max, min, max);
+    case "PageDown":
+      return stepSliderValue(value, -1, min, max, sliderPageStep(min, max, step));
+    case "PageUp":
+      return stepSliderValue(value, 1, min, max, sliderPageStep(min, max, step));
+    default:
+      return undefined;
+  }
+}
 /**
  * Maps the track's two colours onto ROLE tokens — never a raw ramp or a hardcoded hex. `fill` is
  * `accent.text`, NOT the seemingly-obvious `accent.solid`: measured, `accent.solid` against
@@ -146,23 +191,25 @@ export function resolveSliderThumbColors(colors) {
 }
 /**
  * Derives the accessibility surface once, purely, so the contract is testable without a renderer.
- * `now` is clamped onto `[min, max]` — a screen reader must never announce a value the track itself
- * couldn't render. `accessibilityActions` declares BOTH `increment`/`decrement` explicitly: iOS's
- * `adjustable` trait already offers these via the two-finger swipe-up/down gesture without them
- * declared, but Android TalkBack has no native "adjustable" gesture and only surfaces custom actions
- * that are declared here (WCAG 2.5.7 — a drag-only slider has no non-pointer alternative otherwise).
+ * `aria-valuenow` is clamped onto `[min, max]` — a screen reader must never announce a value the
+ * track itself couldn't render. `accessibilityActions` declares BOTH `increment`/`decrement`
+ * explicitly: iOS's `adjustable` trait already offers these via the two-finger swipe-up/down gesture
+ * without them declared, but Android TalkBack has no native "adjustable" gesture and only surfaces
+ * custom actions that are declared here (WCAG 2.5.7 — a drag-only slider has no non-pointer
+ * alternative otherwise).
+ *
+ * FLAT `aria-*`, not `accessibilityValue={{…}}`/`accessibilityState={{…}}`: react-native-web 0.21
+ * drops both objects, so on web the slider announced its role and NO position at all. The host here
+ * is a `View`, which merges every flat prop into the object form natively (`View.js`), so one flat
+ * form is right on both platforms.
  */
 export function resolveSliderAccessibility(input) {
   return {
     accessibilityRole: "adjustable",
-    accessibilityValue: {
-      min: input.min,
-      max: input.max,
-      now: clampSliderValue(input.value, input.min, input.max)
-    },
-    accessibilityState: {
-      disabled: input.disabled === true
-    },
+    "aria-valuemin": input.min,
+    "aria-valuemax": input.max,
+    "aria-valuenow": clampSliderValue(input.value, input.min, input.max),
+    "aria-disabled": input.disabled === true,
     accessibilityActions: [{
       name: "increment"
     }, {

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

@@ -41,12 +41,16 @@ the scale lives on the child, never the box.
 ## Accessibility contract (WCAG)
 
 - **The OUTER box, not the glyph, carries the whole contract** — `accessibilityRole="progressbar"`,
-  the accessible name (`accessibilityLabel ?? "Loading"`), and `accessibilityState={{ busy: true }}`
-  (1.4.1 — the loading state is announced, not left to be inferred from a shape appearing on
-  screen). The inner `ActivityIndicator` is `accessibilityElementsHidden` +
-  `importantForAccessibility="no-hide-descendants"` — decorative chrome, exactly how `Button` treats
-  its own embedded loading spinner, so a screen reader announces ONE "Loading" node, never a nested
-  second element.
+  the accessible name (`accessibilityLabel ?? "Loading"`), and `aria-busy={true}` (1.4.1 — the
+  loading state is announced, not left to be inferred from a shape appearing on screen). The inner
+  `ActivityIndicator` is `aria-hidden` — decorative chrome, exactly how `Button` treats its own
+  embedded loading spinner, so a screen reader announces ONE "Loading" node, never a nested second
+  element.
+- **Flat `aria-*`, not `accessibilityState`/`accessibilityElementsHidden`+`importantForAccessibility`**
+  — react-native-web 0.21.2 forwards only the flat vocabulary to the DOM; the object form and the two
+  native-only hiding props reach nothing on web (`accessibilityHint` has zero occurrences in RNW's
+  dist). `aria-hidden={true}` alone covers both platforms: RN's `View` maps it onto
+  `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"` for native.
 - **1.4.11 (Graphical Objects)** — a spinner is a graphical object required to understand that work
   is ongoing, so both tones are measured ≥ 3:1 against `bg.canvas`, `bg.surface`, AND `bg.raised` on
   all 8 brands × both modes (`Spinner.test.ts`) — never eyeballed.
@@ -95,3 +99,9 @@ None — no icon, no new theme token, no new core helper needed for this compone
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Only child is `ActivityIndicator` (RN host primitive) receiving primitives/plain style values — nothing 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/spinner/Spinner.js

@@ -7,10 +7,10 @@
  * screen reader announces one "Loading" node — never the indicator as a second, redundant element.
  */
 
-import { memo } from "react";
+import { memo, useMemo } from "react";
 import { ActivityIndicator, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
-import { useThemeColors } from "../../theme/index.js";
+import { useMotion } from "../../core/motion/index.js";
+import { useThemeColors } from "../../theme/hooks.js";
 import { resolveSpinnerAccessibility, resolveSpinnerTone, spinnerBox, spinnerGlyphScale } from "./Spinner.variants.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 export const Spinner = /*#__PURE__*/memo(function Spinner({
@@ -21,37 +21,41 @@ export const Spinner = /*#__PURE__*/memo(function Spinner({
   accessibilityLabel
 }) {
   const colors = useThemeColors();
-  const reducedMotion = useReducedMotion();
+  const motion = useMotion();
   const color = resolveSpinnerTone(colors, tone);
   const a11y = resolveSpinnerAccessibility({
     accessibilityLabel
   });
+  const rootStyle = useMemo(() => [spinnerBox({
+    size
+  }), style], [size, style]);
+  const glyphStyle = useMemo(() => spinnerGlyphScale({
+    size
+  }), [size]);
   return /*#__PURE__*/_jsx(View, {
     testID: testID,
     accessible: true,
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: a11y.accessibilityLabel,
-    accessibilityState: a11y.accessibilityState,
-    style: [spinnerBox({
-      size
-    }), style],
+    "aria-busy": a11y["aria-busy"],
+    style: rootStyle,
     children: /*#__PURE__*/_jsx(ActivityIndicator, {
       testID: testID === undefined ? undefined : `${testID}-glyph`,
       size: "small",
       color: color
       // A frozen (non-spinning) glyph for a reduced-motion user (WCAG 2.3.3) — the box's own
       // `busy` state + label above is the real signal, exactly how `Button` treats ITS embedded
-      // spinner as decoration on top of `accessibilityState.busy`. `hidesWhenStopped={false}`
+      // spinner as decoration on top of `aria-busy`. `hidesWhenStopped={false}`
       // (iOS defaults this to `true`) keeps a still-visible ring rather than the glyph vanishing:
       // freezing the motion shouldn't also remove the only visual cue a sighted, non-AT user has.
       ,
-      animating: !reducedMotion,
-      hidesWhenStopped: false,
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no-hide-descendants",
-      style: spinnerGlyphScale({
-        size
-      })
+      animating: motion.enabled,
+      hidesWhenStopped: false
+      // Covers both platforms: RN maps this onto accessibilityElementsHidden +
+      // importantForAccessibility, which react-native-web discards entirely.
+      ,
+      "aria-hidden": true,
+      style: glyphStyle
     })
   });
 });

package/lib/module/modules/spinner/Spinner.variants.js

@@ -55,14 +55,16 @@ export const DEFAULT_SPINNER_LABEL = "Loading";
  * renderer. There is no interaction to gate (a Spinner is never pressable) — unlike
  * `resolveButtonAccessibility`, the only decision here is the label fallback; `busy` is always true
  * because a mounted Spinner, by definition, means work is in progress.
+ *
+ * Flat `aria-busy` rather than `accessibilityState={{ busy }}`: RN's `View` folds the flat prop back
+ * into `accessibilityState`, while react-native-web forwards only the flat form — the object reaches
+ * nothing at all on web, leaving the spinner announcing a role with no state.
  */
 export function resolveSpinnerAccessibility(input) {
   return {
     accessibilityRole: "progressbar",
     accessibilityLabel: input.accessibilityLabel ?? DEFAULT_SPINNER_LABEL,
-    accessibilityState: {
-      busy: true
-    }
+    "aria-busy": true
   };
 }
 

package/lib/module/modules/stage-progress/MODULE.md

@@ -0,0 +1,64 @@
+# stage-progress/
+
+Horizontal pipeline — `variant`: `pills` | `bar` | `stepper`. `value` is active stage id.
+
+## Files
+
+| File | Role |
+|------|------|
+| `StageProgress.variants.ts` | `resolveStageState` / `resolveActiveStageIndex`, the accessibility resolvers, `resolveStageProgressColors(RoleColors)`, and the structure resolvers. Plain, hook-free. |
+| `StageProgress.tsx` | Renders the row; picks the fill/text pair per stage state and wraps a pressable stage in `Pressable` only when it is interactive. |
+
+## Props
+
+`stages` (`StageProgressStage[]`: id, label, disabled) · `value` · `variant` · `readOnly` (default
+`true`) · `onStagePress(id)` · `style` (layout-only, outermost, once, last) · `testID`.
+
+## Accessibility
+
+- **`bar`** renders no text at all — only coloured rectangles — so the container carries one
+  `progressbar` summary from `resolveStageProgressAccessibility`: label `"Stage 2 of 3: Review"` and
+  the 0-indexed `{ min, max, now }` triple. Segments themselves are unlabelled; per-segment labels
+  would read the same track three times. No matching stage (`activeIndex` -1) clamps to ordinal 0,
+  `now` 0, and no `": label"` suffix.
+- **`pills` / `stepper`** label each stage instead: `resolveStageAccessibilityLabel` appends the
+  state — `", completed"` / `", current stage"` / `", not started"`. That suffix is the WCAG 1.4.1
+  fix; fill colour is otherwise the only thing separating a completed stage from an upcoming one, and
+  there is no "completed" state to announce directly. `resolveStageAccessibilityState` supplies flat
+  `aria-selected` (active only) / `aria-disabled` — not `accessibilityState={{…}}`, which
+  react-native-web 0.21.2 drops entirely on web.
+- **WCAG 2.4.7** — an interactive stage (`readOnly={false}`, not `disabled`) draws a `border.focus`
+  ring (`${testID}-focus-ring-${stage.id}`) while focused. It is drawn **inside** the stage's
+  bounds: `stageProgressRowStructure` clips to `overflow: "hidden"` and spaces stages one space step
+  apart, so a gap-outside ring would be cut off at the ends and overlap its neighbour elsewhere.
+  Over `activeFill` (`accent.solid`) the grey ring's contrast is unmeasured — see Known gaps.
+
+## Touch targets
+
+`MIN_TOUCH_TARGET` 44. `STAGE_PILL_MIN_HEIGHT` 32 and `STAGE_STEPPER_CIRCLE` 28 are padded to it by
+vertical-only `hitSlop` (`STAGE_PILL_HIT_SLOP`, `STAGE_STEPPER_HIT_SLOP`) — both shapes already
+exceed 44 horizontally (`minWidth` 72 / 64), so horizontal slop would only overlap neighbours. Slop
+is applied only where a stage is pressable; `readOnly` (and `disabled`) stages render a plain `View`,
+no `Pressable`, and need no target.
+
+## Contrast (measured, 9 brands × both modes)
+
+| Pair | Min |
+|------|-----|
+| `activeText` on `activeFill` (`accent.onSolid` / `accent.solid`) | 4.63 |
+| `completedText` on `completedFill` (`status.success.text` / `.subtle`) | 5.66 |
+| `upcomingText` on `upcomingFill` (`fg.muted` / `bg.sunken`) | 6.45 |
+| `upcomingText` on `bg.canvas` (the `stepper` label under the circle) | 6.52 |
+
+`track` is `border.default` — a decorative pill/circle outline at 1.08–1.43 on the canvas, never
+escalated to `border.interactive` / `border.focus`. Bar-segment fills are deliberately quiet
+(`bg.sunken` at ~1.01–1.12 on the canvas); the state they encode is carried by the progressbar
+label, not by contrast.
+
+## Known gaps
+
+- The focus ring's `border.focus` is the grey proven ≥ 3:1 against the **canvas**; over a stage's
+  own fill (notably `activeFill` = `accent.solid`) that ratio is unmeasured (WCAG 2.4.11). The ring
+  cannot move outside the stage — the row clips — so a fix would be a token-level decision, not a
+  change here.
+- There is no arrow-key path between stages: each interactive stage is its own tab stop.

package/lib/module/modules/stage-progress/StageProgress.js

@@ -0,0 +1,174 @@
+"use strict";
+
+/**
+ * StageProgress — horizontal pipeline stages (pills, bar, or stepper). Read-only by default;
+ * optional `onStagePress` when not `readOnly`.
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { resolveActiveStageIndex, resolveStageAccessibilityLabel, resolveStageAccessibilityState, resolveStageProgressAccessibility, resolveStageProgressColors, resolveStageState, stageBarStructure, stageFocusRingStructure, stagePillStructure, stageProgressRowStructure, stageStepperCircleStructure, STAGE_PILL_HIT_SLOP, STAGE_STEPPER_HIT_SLOP } from "./StageProgress.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const StageProgress = /*#__PURE__*/memo(function StageProgress({
+  stages,
+  value,
+  variant = "pills",
+  readOnly = true,
+  onStagePress,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const palette = resolveStageProgressColors(theme.colors);
+  const activeIndex = resolveActiveStageIndex(stages, value);
+  // Which interactive stage holds keyboard/AT focus. One value rather than per-stage state: only one
+  // stage can be focused, and the stages are rendered inline (a hook per stage is not an option).
+  const [focusedStageId, setFocusedStageId] = useState(null);
+  const handlePress = useCallback((stageId, disabled) => {
+    if (readOnly || disabled || onStagePress === undefined) return;
+    onStagePress(stageId);
+  }, [readOnly, onStagePress]);
+  const content = useMemo(() => {
+    if (variant === "bar") {
+      return stages.map((stage, index) => {
+        const state = resolveStageState(index, activeIndex, true);
+        const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
+        // No label per segment: the container announces the whole track as one progressbar
+        // (`resolveStageProgressAccessibility`), so a per-segment label would read four times over.
+        return /*#__PURE__*/_jsx(View, {
+          testID: testID ? `${testID}-bar-${stage.id}` : undefined,
+          style: [stageBarStructure(theme), {
+            backgroundColor: fill
+          }]
+        }, stage.id);
+      });
+    }
+    if (variant === "stepper") {
+      return stages.map((stage, index) => {
+        const state = resolveStageState(index, activeIndex, true);
+        const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
+        const text = state === "active" ? palette.activeText : state === "completed" ? palette.completedText : palette.upcomingText;
+        const node = /*#__PURE__*/_jsxs(View, {
+          style: {
+            alignItems: "center",
+            minWidth: 64
+          },
+          children: [/*#__PURE__*/_jsx(View, {
+            style: [stageStepperCircleStructure(theme), {
+              backgroundColor: fill,
+              borderColor: palette.track
+            }],
+            children: /*#__PURE__*/_jsx(Text, {
+              style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+                fontSize: theme.fontSizes.sm,
+                color: text
+              }],
+              children: index + 1
+            })
+          }), /*#__PURE__*/_jsx(Text, {
+            numberOfLines: 1,
+            style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
+              fontSize: theme.fontSizes.xs,
+              color: palette.upcomingText,
+              marginTop: theme.space[1]
+            }],
+            children: stage.label
+          })]
+        });
+        const a11yLabel = resolveStageAccessibilityLabel(stage.label, state);
+        const a11yState = resolveStageAccessibilityState(state, stage.disabled);
+        if (readOnly || stage.disabled) return /*#__PURE__*/_jsx(View, {
+          accessible: true,
+          accessibilityLabel: a11yLabel,
+          "aria-selected": a11yState["aria-selected"],
+          "aria-disabled": a11yState["aria-disabled"],
+          children: node
+        }, stage.id);
+        return /*#__PURE__*/_jsxs(Pressable, {
+          accessibilityRole: "button",
+          accessibilityLabel: a11yLabel,
+          "aria-selected": a11yState["aria-selected"],
+          "aria-disabled": a11yState["aria-disabled"],
+          hitSlop: STAGE_STEPPER_HIT_SLOP,
+          onPress: () => handlePress(stage.id, stage.disabled),
+          onFocus: () => setFocusedStageId(stage.id),
+          onBlur: () => setFocusedStageId(current => current === stage.id ? null : current),
+          children: [focusedStageId === stage.id && /*#__PURE__*/_jsx(View, {
+            pointerEvents: "none",
+            testID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
+            style: [stageFocusRingStructure(theme, {
+              variant: "stepper"
+            }), {
+              borderColor: theme.colors.border.focus
+            }]
+          }), node]
+        }, stage.id);
+      });
+    }
+    return stages.map((stage, index) => {
+      const state = resolveStageState(index, activeIndex, true);
+      const fill = state === "active" ? palette.activeFill : state === "completed" ? palette.completedFill : palette.upcomingFill;
+      const text = state === "active" ? palette.activeText : state === "completed" ? palette.completedText : palette.upcomingText;
+      const pill = /*#__PURE__*/_jsx(View, {
+        testID: testID ? `${testID}-pill-${stage.id}` : undefined,
+        style: [stagePillStructure(theme), {
+          backgroundColor: fill,
+          borderColor: palette.track
+        }],
+        children: /*#__PURE__*/_jsx(Text, {
+          numberOfLines: 1,
+          style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+            fontSize: theme.fontSizes.sm,
+            color: text
+          }],
+          children: stage.label
+        })
+      });
+      const a11yLabel = resolveStageAccessibilityLabel(stage.label, state);
+      const a11yState = resolveStageAccessibilityState(state, stage.disabled);
+      if (readOnly || stage.disabled) return /*#__PURE__*/_jsx(View, {
+        accessible: true,
+        accessibilityLabel: a11yLabel,
+        "aria-selected": a11yState["aria-selected"],
+        "aria-disabled": a11yState["aria-disabled"],
+        children: pill
+      }, stage.id);
+      return /*#__PURE__*/_jsxs(Pressable, {
+        accessibilityRole: "button",
+        accessibilityLabel: a11yLabel,
+        "aria-selected": a11yState["aria-selected"],
+        "aria-disabled": a11yState["aria-disabled"],
+        hitSlop: STAGE_PILL_HIT_SLOP,
+        onPress: () => handlePress(stage.id, stage.disabled),
+        onFocus: () => setFocusedStageId(stage.id),
+        onBlur: () => setFocusedStageId(current => current === stage.id ? null : current),
+        children: [focusedStageId === stage.id && /*#__PURE__*/_jsx(View, {
+          pointerEvents: "none",
+          testID: testID ? `${testID}-focus-ring-${stage.id}` : undefined,
+          style: [stageFocusRingStructure(theme, {
+            variant: "pill"
+          }), {
+            borderColor: theme.colors.border.focus
+          }]
+        }), pill]
+      }, stage.id);
+    });
+  }, [stages, variant, activeIndex, palette, theme, testID, readOnly, handlePress, focusedStageId]);
+
+  // Only the `bar` variant collapses into one announcement — `pills`/`stepper` render real text per
+  // stage, and swallowing it behind a container summary would lose the per-stage labels.
+  const barA11y = variant === "bar" ? resolveStageProgressAccessibility(stages, activeIndex) : null;
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessible: barA11y !== null,
+    accessibilityRole: barA11y?.accessibilityRole,
+    "aria-valuemin": barA11y?.["aria-valuemin"],
+    "aria-valuemax": barA11y?.["aria-valuemax"],
+    "aria-valuenow": barA11y?.["aria-valuenow"],
+    accessibilityLabel: barA11y?.accessibilityLabel,
+    style: [stageProgressRowStructure(theme), style],
+    children: content
+  });
+});
+//# sourceMappingURL=StageProgress.js.map