pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/radio-group/MODULE.md

@@ -23,9 +23,10 @@ without collapsing the individually-focusable rows into one.
 | `value` | `string` | — | The selected option's `value`. |
 | `onValueChange` | `(value: string) => void` | — | Fires with the pressed option's `value`; gated off while `disabled`. |
 | `disabled` | `boolean` | `false` | Dims every row and blocks all presses. |
-| `size` | `sm \| md` | `md` | 36 / 44 dp visual row height; `sm` reaches 44 via `hitSlop`. |
+| `size` | `sm \| md` | `md` | Both rows are 44 dp tall (see WCAG below); `sm` is the denser variant through its smaller ring/dot/font and tighter gaps. |
+| `accessibilityLabel` | `string` | — | Names the `radiogroup` container. Previously absent, so the container was announced unnamed — a reader heard each option's own label but nothing saying what the set was FOR (WCAG 1.3.1). |
 | `style` | `LayoutStyle` | — | Layout-only, outermost (the container `View`), applied exactly once, last. |
-| `testID` | `string` | — | Container's testID; each row gets `` `${testID}-${option.value}` `` when set. |
+| `testID` | `string` | — | Container's testID; each row gets `` `${testID}-${option.value}` ``, and the focused row a `` `${testID}-${option.value}-focus-ring` `` child, when set. |
 
 No per-option `disabled` and no `tone` — this is a single-purpose, single-select control, not a
 closed union of appearances. The ring is always `border.interactive`; the selected dot is always
@@ -33,19 +34,39 @@ closed union of appearances. The ring is always `border.interactive`; the select
 
 ## Accessibility contract (WCAG)
 
-- **2.5.x target size** — every size reaches ≥ 44 dp: `sm`'s 36 dp row grows via `hitSlop`; `md` is
-  already 44 dp.
+- **2.5.5 / 2.5.8 target size** — both sizes reach ≥ 44 dp with the RENDERED row (`rowMinHeight: 44`),
+  so `hitSlop` resolves to 0 and no row expands into the gap its neighbour also sits in. `sm` used to
+  be a 36 dp row + 4 dp slop inside a 4 dp `rowGap`: adjacent hit rectangles met exactly, and RN
+  resolves overlapping siblings' `hitSlop` by z-order rather than by which row is visually closer —
+  so a tap on the seam could select the wrong option. Fixed the way `ButtonGroup`/`Pagination` fix
+  the same class of bug: meet the floor with the node, never with `hitSlop`. `RadioGroup.render.test.tsx`
+  asserts on the real rendered `rowGap`/`hitSlop` that adjacent expanded targets stay disjoint.
 - **1.4.3** — the label uses `fg.default` on the canvas, measured ≥ 4.5:1 for every brand × mode.
 - **1.4.11** — the ring boundary is `border.interactive` (≥ 3:1 on the canvas, every brand × mode);
   the selected dot (`accent.solid`) is measured the same way as a non-text UI indicator.
-- **4.1.2** — `accessibilityRole="radio"` per row, `accessibilityState={ checked, disabled }` (not
-  `selected` — that key is for `role="tab"`/`"option"`; Checkbox/Switch use the same `checked`
-  semantics for their own toggle roles);
-  `accessibilityRole="radiogroup"` on the container (a real, recognised RN role — no fallback
-  needed on this RN version). The container is intentionally left non-`accessible` so it groups
-  without swallowing the rows into one focus stop.
-- **2.3.3** — n/a: nothing here animates. The dot appears/disappears by conditional render (not a
-  fade or a slide), so there is no transition for `useReducedMotion` to gate.
+- **4.1.2** — `accessibilityRole="radio"` per row, flat `aria-checked`/`aria-disabled` (not
+  `aria-selected` — that one is for `role="tab"`/`"option"`; Checkbox/Switch use the same `checked`
+  semantics for their own toggle roles). FLAT props, not `accessibilityState={{…}}` —
+  react-native-web 0.21 drops the object entirely, so a row used to announce `role="radio"` with no
+  checked state on web; `Pressable` merges the flat form into `accessibilityState` on native, so one
+  form is correct on both. `accessibilityRole="radiogroup"` on the container (a real, recognised RN
+  role — no fallback needed on this RN version), with `accessibilityLabel` naming it. The container
+  is intentionally left non-`accessible` so it groups without swallowing the rows into one focus stop.
+- **2.1.1 (keyboard) — roving tabindex.** `accessibilityRole="radio"` per row means ARIA requires the
+  group to be ONE tab stop whose arrows both move and select. `tabIndex` is `0` on exactly one row and
+  `-1` on the rest; arrows move and select (wrapping), Home/End jump to the ends
+  (`resolveRadioGroupKeyIndex`), and the handler calls `preventDefault` so the page does not scroll.
+  The active index is **derived** from `value` (falling back to row 0), never held in state — a
+  `value` the consumer changes from outside can then never desync the tab stop. After an arrow the
+  handler also calls `.focus()` on the newly-selected row's node, because the tab stop moved and DOM
+  focus has to follow it or the ring is stranded on the old row. RN's TypeScript `ViewPropTypes.d.ts`
+  omits `onKeyDown` (its Flow types declare it), so the container `View` is re-typed once, locally.
+- **2.4.7 (focus visible)** — Button's `border.focus` ring, drawn a 2dp gap OUTSIDE the row (nothing
+  in the group clips), on the focused row only, never while disabled. Rows also carry
+  `focusable={!disabled}` — RN's `Pressable` stays focusable when disabled, which on a TV remote
+  would otherwise land on a row that renders no ring (same fix NumberInput's steppers use).
+- **2.3.3** — n/a for selection dot (conditional render). Row presses use `usePressState` (scale +
+  state-layer overlay), which snaps under reduce motion.
 - Disabled rows are exempt from the contrast minimum (WCAG 1.4.3), so the uniform `opacity: 0.5`
   dim is correct, same as Button.
 
@@ -65,11 +86,16 @@ closed union of appearances. The ring is always `border.interactive`; the select
 
 ## Known gaps
 
-- No visible keyboard-focus ring (Button's `border.focus` ring pattern, WCAG 2.4.7) — left out of
-  v1 since touch is the primary input surface for this control; the same `onFocus`/`onBlur` +
-  `border.focus` pattern from `Button.tsx` would extend cleanly here if a future task needs it for
-  external-keyboard / RN Web use.
+- Arrow keys move the tab stop by moving the SELECTION, so a keyboard user cannot browse the options
+  without changing the value. That is the WAI-ARIA radio-group pattern, not a defect — but it does
+  mean `onValueChange` fires once per arrow press.
 
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The `options.map()` renders host `Pressable`/`View`/`Text`, not a library child component, so the inline per-row `onPress`/style closures were left as-is.
+
+## 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/radio-group/RadioGroup.js

@@ -10,78 +10,201 @@
  * so there is nothing for `useReducedMotion` (WCAG 2.3.3) to gate — unlike Button's press fade.
  */
 
-import { memo } from "react";
-import { Pressable, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
-import { RADIO_GROUP_SIZES, radioDotStructure, radioGroupStructure, radioRingStructure, radioRowStructure, resolveRadioGroupColors, resolveRadioRowAccessibility } from "./RadioGroup.variants.js";
+import { memo, useRef, useState, useMemo, useCallback } from "react";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
+import { useTheme } from "../../theme/hooks.js";
+import { RADIO_GROUP_SIZES, radioDotStructure, radioGroupStructure, radioRingStructure, radioRowStructure, resolveRadioGroupColors, resolveRadioGroupKeyIndex, resolveRadioRowAccessibility } from "./RadioGroup.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 row, 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;
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+function RadioRow({
+  option,
+  index,
+  selected,
+  disabled,
+  active,
+  size,
+  colors,
+  spec,
+  theme,
+  focusRingStyle,
+  focusedIndex,
+  setFocusedIndex,
+  selectValue,
+  rowRefs,
+  testID
+}) {
+  const press = usePressState(disabled);
+  const a11y = resolveRadioRowAccessibility({
+    selected,
+    disabled
+  });
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.rowHost,
+    children: [focusedIndex === index && !disabled && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      testID: testID ? `${testID}-${option.value}-focus-ring` : undefined,
+      style: [styles.focusRing, focusRingStyle]
+    }), /*#__PURE__*/_jsxs(AnimatedPressable, {
+      ref: node => {
+        rowRefs.current[index] = node;
+      },
+      testID: testID ? `${testID}-${option.value}` : undefined,
+      accessibilityRole: a11y.accessibilityRole,
+      "aria-checked": a11y["aria-checked"],
+      "aria-disabled": a11y["aria-disabled"],
+      accessibilityLabel: option.label,
+      disabled: a11y.disabled,
+      tabIndex: !disabled && active ? 0 : -1,
+      focusable: !disabled,
+      onFocus: () => setFocusedIndex(() => index),
+      onBlur: () => setFocusedIndex(current => current === index ? null : current),
+      onPress: disabled ? undefined : () => selectValue(option.value),
+      onPressIn: press.handlers.onPressIn,
+      onPressOut: press.handlers.onPressOut,
+      onLayout: press.onLayout,
+      hitSlop: spec.hitSlop,
+      android_ripple: Platform.OS === "android" && !disabled ? {
+        color: rippleColor(theme.mode),
+        borderless: false
+      } : undefined,
+      style: [radioRowStructure(theme, {
+        size
+      }), {
+        overflow: "hidden"
+      }, press.animatedStyle, disabled && styles.dimmed],
+      children: [/*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+      }), /*#__PURE__*/_jsx(View, {
+        style: [radioRingStructure(theme, {
+          size
+        }), {
+          borderColor: colors.ring
+        }],
+        children: selected && /*#__PURE__*/_jsx(View, {
+          style: [radioDotStructure({
+            size
+          }), {
+            backgroundColor: colors.dot
+          }]
+        })
+      }), /*#__PURE__*/_jsx(Text, {
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          fontSize: spec.fontSize,
+          color: colors.label
+        }],
+        children: option.label
+      })]
+    }, option.value)]
+  });
+}
 export const RadioGroup = /*#__PURE__*/memo(function RadioGroup({
   options,
   value,
   onValueChange,
   disabled = false,
   size = "md",
+  accessibilityLabel,
   style,
   testID
 }) {
   const theme = useTheme();
+  const haptics = useHaptics();
   const spec = RADIO_GROUP_SIZES[size];
   const colors = resolveRadioGroupColors(theme.colors);
-  return /*#__PURE__*/_jsx(View, {
+
+  // A radio group is ONE tab stop, and its arrows both move and select — so the roving tab stop is
+  // simply the checked row (the first when `value` matches nothing), derived rather than held in
+  // state so a `value` the consumer changes from outside can never desync it.
+  const selectedIndex = options.findIndex(option => option.value === value);
+  const activeIndex = selectedIndex >= 0 ? selectedIndex : 0;
+  const rowRefs = useRef([]);
+  const [focusedIndex, setFocusedIndex] = useState(null);
+  const selectValue = useCallback(nextValue => {
+    haptics.selection();
+    onValueChange(nextValue);
+  }, [haptics, onValueChange]);
+  const handleKeyDown = event => {
+    if (disabled) return;
+    const next = resolveRadioGroupKeyIndex({
+      key: event.nativeEvent.key,
+      index: activeIndex,
+      count: options.length
+    });
+    const option = next === undefined ? undefined : options[next];
+    if (next === undefined || option === undefined) return;
+    // Arrow/Home/End would otherwise scroll the page out from under the group.
+    event.preventDefault?.();
+    selectValue(option.value);
+    // The tab stop moves with the selection, so DOM focus has to follow it or the ring is stranded.
+    rowRefs.current[next]?.focus();
+  };
+  const focusRingStyle = {
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.md + FOCUS_RING_GAP + FOCUS_RING_WIDTH,
+    borderCurve: "continuous"
+  };
+  return /*#__PURE__*/_jsx(KeyboardView, {
     testID: testID,
     accessibilityRole: "radiogroup",
+    accessibilityLabel: accessibilityLabel,
+    "aria-disabled": disabled,
+    onKeyDown: handleKeyDown,
     style: [radioGroupStructure(theme, {
       size
     }), style],
-    children: options.map(option => {
-      const selected = option.value === value;
-      const a11y = resolveRadioRowAccessibility({
-        selected,
-        disabled
-      });
-      return /*#__PURE__*/_jsxs(Pressable, {
-        testID: testID ? `${testID}-${option.value}` : undefined,
-        accessibilityRole: a11y.accessibilityRole,
-        accessibilityState: a11y.accessibilityState,
-        accessibilityLabel: option.label,
-        disabled: a11y.disabled,
-        onPress: disabled ? undefined : () => onValueChange(option.value),
-        hitSlop: spec.hitSlop,
-        style: ({
-          pressed
-        }) => [radioRowStructure(theme, {
-          size
-        }), pressed && !disabled && {
-          backgroundColor: colors.pressedRow
-        }, disabled && styles.dimmed],
-        children: [/*#__PURE__*/_jsx(View, {
-          style: [radioRingStructure(theme, {
-            size
-          }), {
-            borderColor: colors.ring
-          }],
-          children: selected && /*#__PURE__*/_jsx(View, {
-            style: [radioDotStructure({
-              size
-            }), {
-              backgroundColor: colors.dot
-            }]
-          })
-        }), /*#__PURE__*/_jsx(Text, {
-          style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-            fontSize: spec.fontSize,
-            color: colors.label
-          }],
-          children: option.label
-        })]
-      }, option.value);
-    })
+    children: options.map((option, index) => /*#__PURE__*/_jsx(RadioRow, {
+      option: option,
+      index: index,
+      selected: option.value === value,
+      disabled: disabled,
+      active: index === activeIndex,
+      size: size,
+      colors: colors,
+      spec: spec,
+      theme: theme,
+      focusRingStyle: focusRingStyle,
+      focusedIndex: focusedIndex,
+      setFocusedIndex: setFocusedIndex,
+      selectValue: selectValue,
+      rowRefs: rowRefs,
+      testID: testID
+    }, option.value))
   });
 });
 const styles = StyleSheet.create({
-  // A disabled row is exempt from the contrast minimum (WCAG 1.4.3), so a uniform dim is correct.
   dimmed: {
     opacity: 0.5
+  },
+  rowHost: {
+    position: "relative"
+  },
+  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=RadioGroup.js.map

package/lib/module/modules/radio-group/RadioGroup.variants.js

@@ -17,14 +17,21 @@ const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2)
 /**
  * RadioGroup-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
  * test can assert `rowMinHeight + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.
+ *
+ * Both sizes meet the 44dp floor with the RENDERED row, so `slopFor` resolves to 0 and no row's
+ * touch rectangle expands into the `rowGap` a neighbour would also expand into. `sm` used to be a
+ * 36dp row + 4dp slop inside a 4dp gap, so adjacent rows' hit rectangles met exactly and a tap on
+ * the seam was resolved by sibling z-order rather than geometry (WCAG 2.5.8) — the same defect
+ * `ButtonGroup`/`Pagination` fix the same way: meet the floor with the node, never with `hitSlop`.
+ * `sm` stays the denser variant through its smaller ring/dot/font and tighter gaps.
  */
 export const RADIO_GROUP_SIZES = {
   sm: {
-    rowMinHeight: 36,
+    rowMinHeight: 44,
     ringSize: 18,
     dotSize: 8,
     fontSize: 14,
-    hitSlop: slopFor(36)
+    hitSlop: slopFor(44)
   },
   md: {
     rowMinHeight: 44,
@@ -52,21 +59,50 @@ export function resolveRadioGroupColors(colors) {
 }
 /**
  * Derives one row's accessibility surface purely, mirroring `resolveButtonAccessibility`. Reports
- * `accessibilityState.checked` — not `.selected` (that key is for role="tab"/"option"; a radio's
- * checked state is `checked`, same as this repo's Checkbox/Switch) — so the rendered `disabled`
- * prop and the announced `accessibilityState.disabled` always agree, so a screen reader never
- * hears a state the touch handling contradicts.
+ * `aria-checked` — not `aria-selected` (that one is for role="tab"/"option"; a radio's checked state
+ * is `checked`, same as this repo's Checkbox/Switch) — so the rendered `disabled` prop and the
+ * announced `aria-disabled` always agree, so a screen reader never hears a state the touch handling
+ * contradicts.
+ *
+ * FLAT `aria-*` rather than `accessibilityState={{…}}`: react-native-web 0.21 drops the object form
+ * outright, so the web build announced `role="radio"` with no checked state. See
+ * `Checkbox.variants.ts` for the full reasoning — both platforms read the flat form.
  */
 export function resolveRadioRowAccessibility(input) {
   return {
     accessibilityRole: "radio",
-    accessibilityState: {
-      checked: input.selected,
-      disabled: input.disabled
-    },
+    "aria-checked": input.selected,
+    "aria-disabled": input.disabled,
     disabled: input.disabled
   };
 }
+/**
+ * The WAI-ARIA radio-group keyboard contract, resolved purely: arrows move one row and WRAP (a radio
+ * group's arrows both move and select, so there is no "past the end" to fall off), Home/End jump to
+ * the ends. Returns `undefined` for any other key — also how the caller knows not to swallow it.
+ */
+export function resolveRadioGroupKeyIndex(input) {
+  const {
+    key,
+    index,
+    count
+  } = input;
+  if (count <= 0) return undefined;
+  switch (key) {
+    case "ArrowDown":
+    case "ArrowRight":
+      return (index + 1) % count;
+    case "ArrowUp":
+    case "ArrowLeft":
+      return (index - 1 + count) % count;
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    default:
+      return undefined;
+  }
+}
 
 /** Gap between rows. Structural, theme-scaled, registered once per (theme, size). */
 export const radioGroupStructure = createThemedVariants(theme => ({
@@ -93,7 +129,8 @@ export const radioRowStructure = createThemedVariants(theme => ({
   base: {
     flexDirection: "row",
     alignItems: "center",
-    borderRadius: theme.radii.base
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
   },
   variants: {
     size: {