pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/button-group/ButtonGroup.js

@@ -1,28 +1,139 @@
 "use strict";
 
+// Segmented single-choice control: segments share one tonal container fill, not a bordered frame.
+// A hairline divider sits between adjacent unselected segments, omitted at the selected edge (WCAG
+// 1.4.11) — see `resolveButtonGroupSegmentEdgeColors`. Never imports `../button`; a different shape.
+
+import { memo, useCallback, useMemo, useRef, useState } 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 { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
+import { useTheme } from "../../theme/hooks.js";
+import { BUTTON_GROUP_SIZES, buttonGroupSegmentStructure, buttonGroupStructure, resolveButtonGroupColors, resolveButtonGroupKeyIndex, resolveButtonGroupSegmentAccessibility, resolveButtonGroupSegmentEdgeColors, resolveButtonGroupSegmentHitSlop } from "./ButtonGroup.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
- * ButtonGroup — a segmented single-choice control. Visually connected segments sharing one outer
- * border and a divider line between adjacent segments, NOT a row of standalone `Button`s — that
- * connected/segmented treatment is a different structural shape than Button's own pill/rect
- * variants, so this is a standalone sibling (it never imports `../button`). The border/divider is
- * drawn PER SEGMENT, not once on the container: every edge that touches the selected segment omits
- * the stroke (see `resolveButtonGroupSegmentEdgeColors` — WCAG 1.4.11) and relies on the selected
- * fill's own contrast against the canvas instead.
- *
- * One component owns the whole group, same as `RadioGroup`: each segment carries its own
- * `accessibilityRole="radio"` + `accessibilityState.checked`, and the container carries
- * `accessibilityRole="radiogroup"` so assistive tech announces the grouping without collapsing the
- * individually-focusable segments into one.
- *
- * No animation anywhere (selection is a conditional fill, not a slide or a fade), so — like
- * `RadioGroup` — there is nothing here for `useReducedMotion` (WCAG 2.3.3) to gate.
+ * 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;
 
-import { memo } from "react";
-import { Pressable, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
-import { BUTTON_GROUP_SIZES, buttonGroupSegmentStructure, buttonGroupStructure, resolveButtonGroupColors, resolveButtonGroupSegmentAccessibility, resolveButtonGroupSegmentEdgeColors, resolveButtonGroupSegmentHitSlop } from "./ButtonGroup.variants.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The ring is drawn INSIDE the segment (positive offsets), unlike Button's outside ring: the
+ * container is `overflow: "hidden"` so it can clip the joined segment radii, which would erase an
+ * outside ring entirely (`ButtonGroup.render.test.tsx` asserts both halves of this).
+ */
+const FOCUS_RING_WIDTH = 2;
+const FOCUS_RING_INSET = 2;
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+function ButtonGroupSegmentImpl({
+  label,
+  value,
+  selected,
+  nextSelected,
+  isFirst,
+  isLast,
+  index,
+  active,
+  size,
+  disabled,
+  colors,
+  fontSize,
+  onValueChange,
+  registerRef,
+  testID
+}) {
+  const theme = useTheme();
+  const press = usePressState(disabled || selected);
+  const [focused, setFocused] = useState(false);
+  const a11y = useMemo(() => resolveButtonGroupSegmentAccessibility({
+    selected,
+    disabled
+  }), [selected, disabled]);
+  const edges = useMemo(() => resolveButtonGroupSegmentEdgeColors(colors, {
+    selected,
+    nextSelected
+  }), [colors, selected, nextSelected]);
+  const hitSlop = useMemo(() => resolveButtonGroupSegmentHitSlop(size, {
+    isFirst,
+    isLast
+  }), [size, isFirst, isLast]);
+  const androidRipple = useMemo(() => {
+    if (Platform.OS !== "android" || disabled || selected) return undefined;
+    return {
+      color: rippleColor(theme.mode),
+      borderless: false
+    };
+  }, [theme.mode, disabled, selected]);
+  const handlePress = useCallback(() => onValueChange(value), [onValueChange, value]);
+  const handleFocus = useCallback(() => setFocused(true), []);
+  const handleBlur = useCallback(() => setFocused(false), []);
+  const setRef = useCallback(node => {
+    registerRef(index, node);
+  }, [registerRef, index]);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    pointerEvents: "none",
+    top: FOCUS_RING_INSET,
+    left: FOCUS_RING_INSET,
+    right: FOCUS_RING_INSET,
+    bottom: FOCUS_RING_INSET,
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: Math.max(0, theme.radii.md - FOCUS_RING_INSET)
+  }), [theme.colors.border.focus, theme.radii.md]);
+  const segmentStyle = useMemo(() => [buttonGroupSegmentStructure(theme, {
+    size,
+    first: isFirst ? "on" : "off",
+    last: isLast ? "on" : "off"
+  }), {
+    borderRightColor: edges.right
+  }, selected ? {
+    backgroundColor: colors.selectedFill
+  } : null, {
+    overflow: "hidden"
+  }, press.animatedStyle, disabled && styles.dimmed], [theme, size, isFirst, isLast, edges, selected, disabled, colors, press.animatedStyle]);
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: Math.max(0, theme.radii.md - FOCUS_RING_INSET)
+  }), [theme.mode, theme.radii.md]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize,
+    color: selected ? colors.onSelectedFill : colors.label
+  }], [theme, fontSize, selected, colors]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
+    ref: setRef,
+    testID: testID,
+    accessibilityRole: a11y.accessibilityRole,
+    "aria-checked": a11y["aria-checked"],
+    "aria-disabled": a11y["aria-disabled"],
+    accessibilityLabel: label,
+    disabled: a11y.disabled,
+    tabIndex: active && !disabled ? 0 : -1,
+    focusable: !disabled,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onPress: disabled ? undefined : handlePress,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    hitSlop: hitSlop,
+    android_ripple: androidRipple,
+    style: segmentStyle,
+    children: [!selected && /*#__PURE__*/_jsx(Animated.View, {
+      pointerEvents: "none",
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+    }), focused && !disabled && /*#__PURE__*/_jsx(View, {
+      testID: testID === undefined ? undefined : `${testID}-focus-ring`,
+      style: focusRingStyle
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: label
+    })]
+  });
+}
+const ButtonGroupSegment = /*#__PURE__*/memo(ButtonGroupSegmentImpl);
 function ButtonGroupImpl({
   options,
   value,
@@ -33,62 +144,58 @@ function ButtonGroupImpl({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveButtonGroupColors(theme.colors);
+  const colors = useMemo(() => resolveButtonGroupColors(theme.colors), [theme.colors]);
   const fontSize = BUTTON_GROUP_SIZES[size].fontSize;
   const lastIndex = options.length - 1;
-  return /*#__PURE__*/_jsx(View, {
+
+  // `accessibilityRole="radio"` per segment means ARIA requires the group to be ONE tab stop, and
+  // its arrows both move and select — so the roving tab stop is simply the selected segment (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 segmentRefs = useRef([]);
+  const registerRef = useCallback((index, node) => {
+    segmentRefs.current[index] = node;
+  }, []);
+  const handleKeyDown = event => {
+    if (disabled) return;
+    const next = resolveButtonGroupKeyIndex({
+      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?.();
+    onValueChange(option.value);
+    // The tab stop moves with the selection, so DOM focus has to follow it or the ring is stranded.
+    segmentRefs.current[next]?.focus();
+  };
+  return /*#__PURE__*/_jsx(KeyboardView, {
     testID: testID,
     accessibilityRole: "radiogroup",
+    onKeyDown: handleKeyDown,
     style: [buttonGroupStructure(theme), style],
     children: options.map((option, index) => {
-      const selected = option.value === value;
-      const isFirst = index === 0;
       const isLast = index === lastIndex;
-      const nextSelected = !isLast && options[index + 1]?.value === value;
-      const a11y = resolveButtonGroupSegmentAccessibility({
-        selected,
-        disabled
-      });
-      const edges = resolveButtonGroupSegmentEdgeColors(colors, {
-        selected,
-        nextSelected
-      });
-      const hitSlop = resolveButtonGroupSegmentHitSlop(size, {
-        isFirst,
-        isLast
-      });
-      return /*#__PURE__*/_jsx(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: hitSlop,
-        style: ({
-          pressed
-        }) => [buttonGroupSegmentStructure(theme, {
-          size,
-          first: isFirst ? "on" : "off",
-          last: isLast ? "on" : "off"
-        }), {
-          borderTopColor: edges.top,
-          borderBottomColor: edges.bottom,
-          borderLeftColor: edges.left,
-          borderRightColor: edges.right
-        }, selected ? {
-          backgroundColor: colors.selectedFill
-        } : pressed && !disabled && {
-          backgroundColor: colors.pressedFill
-        }, disabled && styles.dimmed],
-        children: /*#__PURE__*/_jsx(Text, {
-          numberOfLines: 1,
-          style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
-            fontSize,
-            color: selected ? colors.onSelectedFill : colors.label
-          }],
-          children: option.label
-        })
+      return /*#__PURE__*/_jsx(ButtonGroupSegment, {
+        label: option.label,
+        value: option.value,
+        selected: option.value === value,
+        nextSelected: !isLast && options[index + 1]?.value === value,
+        isFirst: index === 0,
+        isLast: isLast,
+        index: index,
+        active: index === activeIndex,
+        size: size,
+        disabled: disabled,
+        colors: colors,
+        fontSize: fontSize,
+        onValueChange: onValueChange,
+        registerRef: registerRef,
+        testID: testID ? `${testID}-${option.value}` : undefined
       }, option.value);
     })
   });

package/lib/module/modules/button-group/ButtonGroup.variants.js

@@ -65,12 +65,7 @@ export function resolveButtonGroupColors(colors) {
     selectedFill: colors.accent.solid,
     onSelectedFill: colors.accent.onSolid,
     label: colors.fg.default,
-    // `bg.sunken` (a pale neutral tint), NOT `bg.hover`: measured, `bg.hover`'s saturated mid-tone
-    // drops the brand-tinted `fg.default` label below 4.5:1 on several brands — same class of bug
-    // Button's "neutral" tone and RadioGroup's pressed row document fixing the same way. Composited
-    // with a small `bg.canvas` overlay (see `PRESSED_FILL_OVERLAY_ALPHA_HEX` above) so it also clears
-    // 3:1 against `selectedFill` — the boundary a segment adjacent to the selected one actually draws
-    // while being pressed.
+    containerFill: colors.bg.raised,
     pressedFill: compositeOver(`${colors.bg.canvas}${PRESSED_FILL_OVERLAY_ALPHA_HEX}`, colors.bg.sunken),
     outline: colors.border.interactive
   };
@@ -80,19 +75,9 @@ export function resolveButtonGroupColors(colors) {
  * the WIDTH constant (see `buttonGroupSegmentStructure`) and only swapping the COLOUR avoids a
  * layout shift when a segment's selection changes. */
 const OMITTED_EDGE = "transparent";
-/**
- * Per-edge, per-segment outline colour — the WCAG 1.4.11 fix. An edge draws the shared `outline`
- * colour only when BOTH sides of it are unselected; any edge touching the selected segment is
- * `transparent` instead, so the selected fill's own contrast against the canvas (or, for the
- * divider case, against the neighbour's transparent/canvas background) is what marks the boundary.
- */
 export function resolveButtonGroupSegmentEdgeColors(colors, input) {
-  const own = input.selected ? OMITTED_EDGE : colors.outline;
   const right = input.selected || input.nextSelected ? OMITTED_EDGE : colors.outline;
   return {
-    top: own,
-    bottom: own,
-    left: own,
     right
   };
 }
@@ -131,46 +116,64 @@ export function resolveButtonGroupSegmentHitSlop(size, position) {
 export function resolveButtonGroupSegmentAccessibility(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 segment and WRAP (the
+ * 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 that keystroke.
+ * Duplicated from `RadioGroup.variants.ts` rather than imported: modules stay isolated.
+ */
+export function resolveButtonGroupKeyIndex(input) {
+  const {
+    key,
+    index,
+    count
+  } = input;
+  if (count <= 0) return undefined;
+  switch (key) {
+    case "ArrowRight":
+    case "ArrowDown":
+      return (index + 1) % count;
+    case "ArrowLeft":
+    case "ArrowUp":
+      return (index - 1 + count) % count;
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    default:
+      return undefined;
+  }
+}
 
 /**
- * The container — a clipping rect only. `overflow: hidden` + `borderRadius` clips every segment's
- * fill (and the outer segments' square corners) to this single rounded outline, so the selected
- * segment never shows a corner poking past the shared shape — the visual mechanism that makes this
- * read as ONE connected control rather than a row of standalone buttons. It carries NO border of its
- * own: the outer border is drawn by the first/last segments themselves (see
- * `buttonGroupSegmentStructure`), because only a per-segment border can be selectively omitted where
- * it touches the selected segment (WCAG 1.4.11) — a single container-wide border is one colour for
- * its entire perimeter and cannot vary by which segment it runs along.
+ * The container. `overflow: hidden` + `borderRadius` clips every segment's fill (and the outer
+ * segments' square corners) to one rounded shape, so the selected segment never pokes a corner past
+ * it. `backgroundColor: bg.raised` is the group's tonal frame — it replaces the old outer hairline,
+ * so unselected segments (transparent) read as sitting on one continuous raised surface.
  */
 export const buttonGroupStructure = createThemedVariants(theme => ({
   base: {
     flexDirection: "row",
-    borderRadius: theme.radii.base,
-    overflow: "hidden"
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
+    overflow: "hidden",
+    backgroundColor: theme.colors.bg.raised
   }
 }));
 
 /**
  * One segment's layout. `minWidth: MIN_TOUCH_TARGET` is the real ≥44dp touch-target floor for the
- * WIDTH axis — horizontal hitSlop can no longer safely pad an internal segment (see
- * `resolveButtonGroupSegmentHitSlop`), so the rendered node itself must never shrink narrower than
- * 44dp, for a realistic 2–4 option row at either size. `height` is fixed (not a minimum) so the
+ * WIDTH axis (see `resolveButtonGroupSegmentHitSlop`). `height` is fixed (not a minimum) so the
  * vertical hitSlop math holds against what actually renders.
  *
- * Every segment structurally carries a top, bottom, and right border (thin width) — the right one is
- * the divider on every segment except the last, where it is instead that segment's own outer right
- * edge. Only the FIRST segment gets a left border and left-corner radii (the group's own outer left
- * edge); only the LAST segment gets right-corner radii (matching the container's own `borderRadius`,
- * so that segment's own border curves rather than being clipped into an L by the container). Border
- * WIDTHS are structural and constant; COLOURS (drawn vs `transparent`) are resolved per render by
- * `resolveButtonGroupSegmentEdgeColors` and applied inline over this.
+ * Only a right border remains, structural on every segment but the last — the internal divider
+ * between two adjacent unselected segments (see `resolveButtonGroupSegmentEdgeColors`). There is no
+ * more top/bottom/left border: the container's own tonal fill carries the group's outer shape now.
  */
 export const buttonGroupSegmentStructure = createThemedVariants(theme => ({
   base: {
@@ -178,8 +181,6 @@ export const buttonGroupSegmentStructure = createThemedVariants(theme => ({
     minWidth: MIN_TOUCH_TARGET,
     alignItems: "center",
     justifyContent: "center",
-    borderTopWidth: theme.borderWidths.thin,
-    borderBottomWidth: theme.borderWidths.thin,
     borderRightWidth: theme.borderWidths.thin
   },
   variants: {
@@ -195,18 +196,18 @@ export const buttonGroupSegmentStructure = createThemedVariants(theme => ({
     },
     first: {
       on: {
-        borderLeftWidth: theme.borderWidths.thin,
-        borderTopLeftRadius: theme.radii.base,
-        borderBottomLeftRadius: theme.radii.base
+        borderTopLeftRadius: theme.radii.md,
+        borderBottomLeftRadius: theme.radii.md,
+        borderCurve: "continuous"
       },
-      off: {
-        borderLeftWidth: 0
-      }
+      off: {}
     },
     last: {
       on: {
-        borderTopRightRadius: theme.radii.base,
-        borderBottomRightRadius: theme.radii.base
+        borderTopRightRadius: theme.radii.md,
+        borderBottomRightRadius: theme.radii.md,
+        borderCurve: "continuous",
+        borderRightWidth: 0
       },
       off: {}
     }

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

@@ -1,12 +1,13 @@
 # button-group/ — a segmented single-choice control
 
-Visually connected segments sharing one outer border and a divider line between adjacent
-segments — NOT a row of standalone `Button`s. One component owns the whole group, same shape as
-`radio-group/`: each segment carries its own `accessibilityRole="radio"`; the container carries
-`accessibilityRole="radiogroup"` so assistive tech announces the grouping without collapsing the
-individually-focusable segments into one. The border/divider is drawn PER SEGMENT (never once on
-the container) so it can be selectively omitted where it touches the selected segment — see
-**1.4.11** below.
+Segments sit on one shared tonal container fill (`bg.raised`) with a hairline divider between
+adjacent unselected segments — NOT a row of standalone `Button`s. One component owns the whole
+group, same shape as `radio-group/`: each segment carries its own `accessibilityRole="radio"`; the
+container carries `accessibilityRole="radiogroup"` so assistive tech announces the grouping without
+collapsing the individually-focusable segments into one. The divider is drawn PER SEGMENT (never
+once on the container) so it can be selectively omitted where it touches the selected segment — see
+**1.4.11** below. There is no outer frame border any more (Wave 5 tonal restyle) — the container's
+own fill carries the group's shape.
 
 ## Files
 
@@ -28,7 +29,7 @@ the container) so it can be selectively omitted where it touches the selected se
 | `disabled` | `boolean` | `false` | Dims every segment and blocks all presses (whole-group only — no per-option `disabled`). |
 | `size` | `sm \| md` | `md` | 32 / 40 dp fixed segment height (matches Button's `sm`/`md`); both reach 44dp via `hitSlop`. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost (the container `View`), applied exactly once, last. |
-| `testID` | `string` | — | Container's testID; each segment gets `` `${testID}-${option.value}` `` when set. |
+| `testID` | `string` | — | Container's testID; each segment gets `` `${testID}-${option.value}` ``, and the focused segment a `` `${testID}-${option.value}-focus-ring` `` child, when set. |
 
 No `tone`/`variant` union and no `icon` — this is a single-purpose control, not a closed union of
 appearances. The selected fill is always `accent.solid`; the shared outline/divider is always
@@ -36,10 +37,12 @@ appearances. The selected fill is always `accent.solid`; the shared outline/divi
 
 ## Accessibility contract (WCAG)
 
-- **4.1.2** — `accessibilityRole="radio"` per segment, `accessibilityState={ checked, disabled }`
+- **4.1.2** — `accessibilityRole="radio"` per segment, flat `aria-checked` / `aria-disabled`
   (NOT `role="tab"`/`.selected` — a tab switches content panels, which this control does not do; it
   is the same single-choice value selector shape `RadioGroup` already uses, just drawn as connected
-  segments instead of rows); `accessibilityRole="radiogroup"` on the container.
+  segments instead of rows); `accessibilityRole="radiogroup"` on the container. Flat, never
+  `accessibilityState={{…}}`: react-native-web discards the object form — see
+  `docs/PLATFORM-A11Y-PROPS.md`.
 - **2.5.x target size** — every segment reaches ≥ 44dp on BOTH axes, but not through one flat
   `hitSlop`:
   - **Vertical** — symmetric `hitSlop` on every segment (32dp/40dp visual height + 6/2dp slop = 44dp).
@@ -63,20 +66,29 @@ appearances. The selected fill is always `accent.solid`; the shared outline/divi
   canvas (resting) and `bg.sunken` (pressed) — NOT `bg.hover`, whose saturated mid-tone was measured
   to drop the brand-tinted label below 4.5:1 on several brands, the same class of bug Button's
   "neutral" tone and RadioGroup's pressed row document fixing the same way.
-- **1.4.11** — the shared `outline` token (`border.interactive`) clears 3:1 against `bg.canvas` on
-  every brand × mode, but measured against a SELECTED segment's `accent.solid` fill it FAILS 3:1 on
-  15 of 16 brand × mode combinations (some catastrophically: slate light 1.00, emerald light 1.02).
-  Because `value` is required, some segment is always selected — that adjacency is every render, not
-  an edge case, and it previously went unmeasured (the shipped test only checked outline-vs-canvas).
-  Fixed: `resolveButtonGroupSegmentEdgeColors` computes, per edge of per segment, whether that edge
-  touches the selected segment; any edge that does gets `transparent` instead of `outline`, and the
-  boundary there is served instead by the selected fill's own contrast against the canvas —
-  `accent.solid` clears 3:1 against `bg.canvas` on all 16 brand × mode combinations (worst case
-  3.24:1, emerald light) — the same mechanism every other solid-fill component in this library
-  already relies on. `ButtonGroup.test.ts` measures every actually-rendered boundary pairing (not
-  just the easy outline-vs-canvas one) for first/middle/last selected × all 8 brands × both modes.
-- **2.3.3** — n/a: nothing here animates. Selection is a conditional fill (not a slide or a fade), so
-  there is no transition for `useReducedMotion` to gate — same as `RadioGroup`.
+- **1.4.11** — the shared `outline` token (`border.interactive`) is now only ever drawn as the
+  divider between two adjacent unselected segments; any edge touching the selected segment gets
+  `transparent` instead, and the boundary there is served by `accent.solid` (`selectedFill`) against
+  the group's own `containerFill` (`bg.raised`) — measured ≥ 3:1 on all 16 brand × mode combinations
+  (worst case 3.31:1, rosewood light). `ButtonGroup.test.ts` measures every actually-rendered
+  boundary for first/middle/last selected × all 8 brands × both modes.
+- **2.1.1 (keyboard) — roving tabindex.** `accessibilityRole="radio"` per segment means ARIA requires
+  the group to be ONE tab stop whose arrows both move and select. `tabIndex` is `0` on exactly one
+  segment and `-1` on the rest; arrows move and select (wrapping), Home/End jump to the ends
+  (`resolveButtonGroupKeyIndex`), and the handler calls `preventDefault` so the page does not scroll.
+  The active index is **derived** from `value` (falling back to segment 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 segment's node, because the tab stop moved and
+  DOM focus has to follow it or the ring is stranded. 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) — the ring is INSET here, unlike Button's.** `buttonGroupStructure` is
+  `overflow: "hidden"` and has to be (that clip is what joins the segment radii into one shape), so
+  Button's ring at negative offsets would be clipped away entirely. This one is drawn at positive
+  offsets inside the segment instead; `ButtonGroup.render.test.tsx` asserts both halves — that the
+  container really clips, and that every ring edge is a positive inset that therefore survives it.
+  Segments also carry `focusable={!disabled}`, since RN's `Pressable` stays focusable when disabled.
+- **2.3.3** — n/a for selection (conditional fill, not a slide). Segment presses use `usePressState`
+  (scale + state-layer overlay), which snaps under reduce motion — same gating as `Button`.
 - Disabled segments are exempt from the contrast minimum (WCAG 1.4.3), so the uniform `opacity: 0.5`
   dim is correct, same as Button/RadioGroup.
 
@@ -88,15 +100,12 @@ appearances. The selected fill is always `accent.solid`; the shared outline/divi
    and — per edge, per segment — `outline` vs `transparent`) is resolved by `resolveButtonGroupColors`
    / `resolveButtonGroupSegmentEdgeColors` from role tokens and applied inline over the structural
    style.
-2. **One connected control, not N buttons — and the border lives on the segments, not the container.**
-   The container is only a clipping rect (`overflow: 'hidden'` + `borderRadius`, no border of its
-   own): it clips a filled end segment's square corner into the shared rounded shape. Every segment
-   structurally carries its own top/bottom/right border; the right one is the divider on every
-   segment except the last, where it is instead that segment's own outer right edge; only the FIRST
-   segment gets a left border + left-corner radii, only the LAST gets right-corner radii. A single
-   container-wide border could never be selectively omitted per segment (one colour for its whole
-   perimeter), which is exactly why 1.4.11 shipped broken the first time — moving the border onto the
-   segments is what makes the WCAG fix possible at all.
+2. **One connected control, not N buttons — the divider lives on the segments, the shape on the
+   container.** The container clips (`overflow: 'hidden'` + `borderRadius`) AND carries the tonal
+   `containerFill`; it clips a filled end segment's square corner into the shared rounded shape.
+   Every segment but the last structurally carries its own right border, the divider between it and
+   its neighbour; a single container-wide border could never be selectively omitted per segment (one
+   colour for its whole perimeter), which is why the divider still lives on the segments.
 3. **Pure, testable resolvers** in `ButtonGroup.variants.ts` (no React) so the WCAG + behaviour
    contract is unit-tested against the real palettes — never eyeballed.
 4. **No `{...rest}`, `style` once on the outermost node**, no icon (per spec), no import from
@@ -107,10 +116,13 @@ appearances. The selected fill is always `accent.solid`; the shared outline/divi
 
 ## Known gaps
 
-- No visible keyboard-focus ring (Button's `border.focus` ring pattern, WCAG 2.4.7) — left out of v1
-  for the same reason `RadioGroup` left it out: 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 segments
+  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.
+- The focus ring's contrast is **not** measured per brand the way every other boundary in this module
+  is. It is `border.focus` (a neutral grey, chosen library-wide precisely so a ring survives an
+  accent-filled control) drawn inside the segment, so on a SELECTED segment it sits over
+  `accent.solid` rather than the canvas — the one pairing this module's WCAG suite does not cover.
 
 ### Resolved — the adjacent-pressed-segment boundary (WCAG 1.4.11)
 
@@ -127,3 +139,12 @@ an `if (dark)` branch. Worst case now 3.08:1 (rosewood light); the unselected la
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — renamed to `ButtonGroupImpl` internally, exported as `ButtonGroup = memo(ButtonGroupImpl)`. The `options.map()` hands every per-row prop to host elements (`Pressable`/`Text`/`View`), never a library child component, so no `useCallback`/`useMemo` was needed.
+
+Android segments carry `android_ripple` (mirrors Button/RadioGroup), gated off while
+`disabled || selected` since a selected segment already reads via its fill.
+
+## 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.