pixelize-native-library 1.0.7 → 1.2.0

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,17 +34,37 @@ 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.
+- **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: 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.
 - Disabled rows are exempt from the contrast minimum (WCAG 1.4.3), so the uniform `opacity: 0.5`
@@ -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,41 +10,93 @@
  * so there is nothing for `useReducedMotion` (WCAG 2.3.3) to gate — unlike Button's press fade.
  */
 
-import { memo } from "react";
+import { memo, useRef, useState } 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 { 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;
 export const RadioGroup = /*#__PURE__*/memo(function RadioGroup({
   options,
   value,
   onValueChange,
   disabled = false,
   size = "md",
+  accessibilityLabel,
   style,
   testID
 }) {
   const theme = useTheme();
   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 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?.();
+    onValueChange(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.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  };
+  return /*#__PURE__*/_jsx(KeyboardView, {
     testID: testID,
     accessibilityRole: "radiogroup",
+    accessibilityLabel: accessibilityLabel,
+    "aria-disabled": disabled,
+    onKeyDown: handleKeyDown,
     style: [radioGroupStructure(theme, {
       size
     }), style],
-    children: options.map(option => {
+    children: options.map((option, index) => {
       const selected = option.value === value;
       const a11y = resolveRadioRowAccessibility({
         selected,
         disabled
       });
       return /*#__PURE__*/_jsxs(Pressable, {
+        ref: node => {
+          rowRefs.current[index] = node;
+        },
         testID: testID ? `${testID}-${option.value}` : undefined,
         accessibilityRole: a11y.accessibilityRole,
-        accessibilityState: a11y.accessibilityState,
+        "aria-checked": a11y["aria-checked"],
+        "aria-disabled": a11y["aria-disabled"],
         accessibilityLabel: option.label,
         disabled: a11y.disabled,
+        tabIndex: !disabled && index === activeIndex ? 0 : -1
+        // RN's Pressable stays `focusable` when disabled, so a TV remote could otherwise land on
+        // a row that renders no ring (WCAG 2.4.7) — the same fix NumberInput's steppers use.
+        ,
+        focusable: !disabled,
+        onFocus: () => setFocusedIndex(index),
+        onBlur: () => setFocusedIndex(current => current === index ? null : current),
         onPress: disabled ? undefined : () => onValueChange(option.value),
         hitSlop: spec.hitSlop,
         style: ({
@@ -54,7 +106,11 @@ export const RadioGroup = /*#__PURE__*/memo(function RadioGroup({
         }), pressed && !disabled && {
           backgroundColor: colors.pressedRow
         }, disabled && styles.dimmed],
-        children: [/*#__PURE__*/_jsx(View, {
+        children: [focusedIndex === index && !disabled && /*#__PURE__*/_jsx(View, {
+          pointerEvents: "none",
+          testID: testID ? `${testID}-${option.value}-focus-ring` : undefined,
+          style: [styles.focusRing, focusRingStyle]
+        }), /*#__PURE__*/_jsx(View, {
           style: [radioRingStructure(theme, {
             size
           }), {
@@ -82,6 +138,14 @@ 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
+  },
+  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 => ({

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

@@ -2,18 +2,19 @@
 
 `Reorder` renders a vertical list of `{ id, label }` items, each with a drag "grip" glyph on the
 left and a label. Dragging the grip reorders the list live, with the other rows sliding out of the
-way to preview the drop position. Wave 3: hand-built on `PanResponder` + `Animated` only — no new
-dependency.
+way to preview the drop position. Built on **one** shared `Gesture.Pan()`
+(`react-native-gesture-handler`) + `react-native-reanimated` shared values, virtualized through
+`core/list`'s `VirtualList`.
 
 ## Files
 
 | File | Role |
 |------|------|
-| `Reorder.tsx` | The component. `PanResponder` wiring on the grip only, the ephemeral drag-preview state, and the two `Button` up/down alternatives. `ReorderRow` is a private sub-component (its shift-settle effect needs a per-row hook instance, and Rules of Hooks forbid a hook inside the `.map()` body); each row's `shift` `Animated.Value` itself is owned by `Reorder`, keyed by `item.id` in a `Map`, so `handleDragEnd` can reset every row's `shift` to 0 synchronously on drop. |
-| `Reorder.variants.ts` | Pure resolvers (`resolveReorderColors`, `resolveReorderMoveState`, `moveItem`, `resolveRowPitch`, `resolveDragTargetIndex`, `resolveRowShift`) + the themed/untethered structural resolvers. No React, no lucide. |
+| `Reorder.tsx` | The component. The single shared pan, the five shared values that drive every row, and the two `Button` up/down alternatives. `ReorderRow` is a private, memoized sub-component rendered through `VirtualList`. |
+| `Reorder.variants.ts` | Pure resolvers (`resolveReorderColors`, `resolveReorderMoveState`, `moveItem`, `resolveRowPitch`, `resolveDragTargetIndex`, `resolveRowShift`) + the themed/untethered structural resolvers. No React, no lucide. The two drag-math resolvers are `"worklet"`-marked so the UI thread can call them. |
 | `index.ts` | Public surface: `Reorder`, `ReorderProps`, `ReorderItem`. |
-| `__tests__/Reorder.test.ts` | Pure: WCAG contrast (all brands × modes), grip touch target, and the drag/alternative-path arithmetic (`moveItem`, `resolveRowPitch`, `resolveDragTargetIndex`, `resolveRowShift`, `resolveReorderMoveState`). |
-| `__tests__/Reorder.render.test.tsx` | Render: label rendering, grip hidden from a11y, grip start/move gating, the WCAG 2.5.7 alternative reordering the first/last/a middle item both directions, disabled gating, testID wiring, reduced-motion shift animation, and a real (fabricated-touch-history) grant/move/release regression test proving a previewed row's `shift` resets to 0 synchronously on drop. |
+| `__tests__/Reorder.test.ts` | Pure: WCAG contrast (all brands × modes), grip touch target, and the drag/alternative-path arithmetic. |
+| `__tests__/Reorder.render.test.tsx` | Render: labels, grip hidden from a11y, grip drag gating, the WCAG 2.5.7 alternative in both directions, disabled gating, testID wiring, the reduced-motion row shift, and the shift reset on drop. Mocks both animation peers locally and captures the pan's callbacks so a test drives a real drag. |
 
 ## Props
 
@@ -25,107 +26,113 @@ dependency.
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Seeds `${testID}-item-<i>`, `-grip`, `-move-up`, `-move-down` per row. |
 
-No `variant`/`size`/`tone` — every row reads identically (same reasoning `Timeline`'s minimal prop
-set documents for its own tone-less component); the only per-row state is structural (dragging or
-not), not a caller-facing appearance choice.
+No `variant`/`size`/`tone` — every row reads identically; the only per-row state is structural
+(dragging or not), not a caller-facing appearance choice.
 
 ## Interaction model
 
-- **Drag path**: `PanResponder` lives on the grip `View` only (not the row), so the label never
-  fights the gesture. While dragging, `Reorder` tracks only `{ startIndex, targetIndex }` — the
-  `items` array itself is NEVER mutated mid-drag. Every other row's on-screen offset is a pure
-  function of that pair (`resolveRowShift`); the dragged row's own offset follows the raw touch `dy`
-  via a shared `Animated.Value`. On release, `moveItem(items, startIndex, targetIndex)` is computed
-  once and handed to `onReorder` — a no-op if the position didn't change.
-- **Row pitch**: the drag math (`resolveDragTargetIndex`, `resolveRowShift`) is driven by
-  `resolveRowPitch(theme.space[2])` — `REORDER_ROW_HEIGHT` (56dp) PLUS the list's `rowGap` (the same
-  `theme.space[2]` token `reorderListStructure` applies), never `REORDER_ROW_HEIGHT` alone. That gap
-  is real on-screen distance between row tops; a pitch that ignores it flips the target row early and
-  undershoots the preview shift by `rowGap` per row.
-- **Shift reset on drop**: each row's `shift` `Animated.Value` is owned by `Reorder` (a `Map` keyed by
-  `item.id`), not by `ReorderRow` itself, so `handleDragEnd` can call `setValue(0)` on every row
-  synchronously, in the same tick the array reorder commits — BEFORE the `dragState → null` update
-  flips every row's `shiftTarget` prop to 0. Because React relocates a reordered row instantly via its
-  stable `item.id` key, a row still holding a stale mid-drag `shift` at that instant would visibly
-  jump to its new slot and then animate back — the synchronous reset is what prevents that.
-- **`onReorder` is called as a plain statement in `handleDragEnd`, never inside a `setDragState`
-  updater function.** `useState` updaters must be pure; nesting the consumer's own state setter
-  (`onReorder`, e.g. `setItems`) inside `setDragState((prev) => …)` let React invoke it while
-  processing `Reorder`'s own render, surfacing as "Cannot update a component while rendering a
-  different component" (fixed — was a real bug, not a lint nit). `handleDragEnd` reads the current
-  value via a `dragStateRef` mirror (kept in sync every render) rather than closing over `dragState`
-  directly — see "Performance" below for why the callback itself must NOT depend on `dragState` —
-  calls `onReorder` first if the position changed, then `setDragState(null)` — same synchronous
-  ordering relative to the `shiftValues` reset above, so the shift-reset-on-drop fix is unaffected.
-- **Accessible alternative (WCAG 2.5.7 — required, not optional)**: every row also renders two
-  `Button` icon-only presses, "Move `<label>` up" / "Move `<label>` down", reusing the shipped
-  `chevron-up`/`chevron-down` `IconName`s. Each is a real `Button` (`variant="ghost" size="sm"
-  tone="neutral"`) — a real `accessibilityRole="button"`, Button's own verified ≥44dp touch target,
-  and Button's own disabled/focus/press contract, all reused rather than reimplemented. Disabled at
-  the list's own start/end via `resolveReorderMoveState`, and by the list's `disabled` prop
-  everywhere. This path calls the exact same `moveItem` the drag path calls, so both are guaranteed
-  to agree on the result for the same intent.
-- **Grip glyph**: no `IconName` in the closed 22-name set represents a drag handle, and that set is
-  never extended for one component (per the build brief) — the grip is three plain themed `View`
-  bars (`fg.muted`, `radii.full`), not an icon.
+- **One gesture, five shared values, N rows.** `Reorder` builds a single `Gesture.Pan()` and five
+  `useSharedValue`s (`activeIndex`, `targetIndex`, `translationY`, `lift`, `itemCount`) for the WHOLE
+  list — never one per row. A row's grip reports only WHICH item was grabbed (`onGrab(id)`, from
+  `onTouchStart`); the pan then owns the drag on the UI thread. Every row's `useAnimatedStyle` reads
+  those shared values, so a live drag re-renders **nothing** — React state flips only twice per drag
+  (`activeRow`, for the lifted row's non-animatable chrome).
+- **The pan owns the drag's END, the grip does not.** gesture-handler cancels the underlying view's
+  RN touches once the pan activates, so a grip `onTouchEnd`/`onTouchCancel` would fire mid-drag and
+  kill it. `onFinalize` is the single release path (it fires even when the pan never activated, so a
+  plain tap on the grip still clears the state).
+- **`manualActivation(true)`.** The pan wraps the virtualized list, so without manual activation it
+  would swallow the list's own scroll. `onTouchesMove` activates it only while a grip is held
+  (`activeIndex !== IDLE`) and fails it otherwise, handing the touch back to the list.
+- **Virtualization.** Rows render through `core/list`'s `VirtualList` with
+  `itemHeight = resolveRowPitch(theme.space[2])`, so `getItemLayout` matches the real layout and only
+  on-screen rows mount. The inter-row gap is the row's own `marginBottom`, not a container `rowGap` —
+  a container gap never lands between virtualized cells.
+- **Row pitch**: the drag math is driven by `resolveRowPitch(theme.space[2])` — `REORDER_ROW_HEIGHT`
+  (56dp) PLUS the row's gap, never the height alone. A pitch that ignores the gap flips the target
+  row early and undershoots the preview shift by `rowGap` per row.
+- **Fully controlled**: `items` is never mutated mid-drag. Only `{ activeIndex, targetIndex }` change
+  during a drag; `moveItem(items, from, to)` is computed once, on release, and handed to `onReorder`
+  (a no-op if the position didn't change). Because `resolveRowShift` (preview) and `moveItem`
+  (commit) share the same splice semantics, the dragged row lands exactly in the slot its shifted
+  neighbours vacated.
+- **Shift reset on drop**: `endDrag` sets `activeIndex` back to IDLE, and every row's animated style
+  takes its idle branch — a literal `translateY: 0`, never a `withTiming` from the stale mid-drag
+  offset. There is no lingering animation to outlive the drop, and `cancelAnimation` stops the
+  in-flight lift on drop and on unmount.
+- **Accessible alternative (WCAG 2.5.7 — required)**: every row renders two icon-only `Button`s,
+  "Move `<label>` up" / "Move `<label>` down", reusing the shipped `chevron-up`/`chevron-down`
+  `IconName`s and Button's own verified ≥44dp target, disabled/focus/press contract. Gated by
+  `resolveReorderMoveState` at the list's ends and by the list's `disabled` everywhere. Both paths
+  call the same `moveItem`, so they cannot disagree.
+- **Grip glyph**: no `IconName` in the closed 22-name set represents a drag handle, so the grip is
+  three plain themed `View` bars (`fg.muted`, `radii.full`), not an icon.
+
+## Motion
+
+Every timing comes from `core/motion` — `useMotion().duration("fast")` for the lift and the row
+shift, `useMotion().transform.pressOpacity` for the lifted row's opacity. No local duration constant
+lives in this module. Only `opacity` and `transform` animate, on reanimated's UI thread.
 
 ## Accessibility contract (WCAG)
 
-- **2.5.7 (Dragging Movements)** — the up/down `Button`s ARE the required non-dragging alternative;
-  see "Interaction model" above. Verified end-to-end in `Reorder.render.test.tsx`: pressing "Move
-  Alpha down" (first item), "Move Gamma up" (last item), and "Move Beta up"/"Move Beta down" (a
-  middle item, both directions) each produce the exact expected resulting array — no drag involved.
-- **Grip hidden from assistive tech** — `PanResponder` gestures are invisible to a screen reader;
-  exposing the grip as a focusable-but-non-operable element would be worse than not exposing it at
-  all. It carries `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`
-  (the same pairing `Timeline`'s decorative connector uses) — the up/down `Button`s are the one real
-  accessible affordance for reordering.
+- **2.5.7 (Dragging Movements)** — the up/down `Button`s ARE the required non-dragging alternative.
+  Verified end-to-end in `Reorder.render.test.tsx` for the first, last and a middle item, both
+  directions — no drag involved.
+- **Grip hidden from assistive tech** — a pan gesture is invisible to a screen reader, and a
+  focusable-but-non-operable element would be worse than none. The grip carries
+  `accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`; the up/down
+  `Button`s are the one real accessible affordance for reordering.
 - **2.5.5 / 2.5.8 (target size)** — the grip's visual footprint (three 20×3dp bars + gaps) reaches
-  44dp via `hitSlop` on BOTH axes (`GRIP_HIT_SLOP`), same discipline as `Button`'s own `hitSlop`
-  extended to two dimensions. The move buttons reuse `Button`'s own already-verified `sm` touch
-  target (32dp visual + 6dp slop each side = 44dp) — not re-tested here, since that contract lives
-  and is proven in `button/__tests__/Button.test.ts`.
-- **1.4.3** — the row label (`fg.default`) is measured ≥ 4.5:1 against BOTH the resting row fill
-  (`bg.surface`) and the dragging row fill (`bg.raised`), for all 8 brands × both modes.
-- **1.4.11** — the grip glyph (`fg.muted`) is measured ≥ 3:1 against both row fills as a graphical
-  UI affordance, same reasoning `Spinner.variants.ts` documents for its own "Graphical Objects"
-  clause. The grip's disabled colour (`fg.disabled`) is NOT contrast-gated — a disabled control is
-  exempt from the minimum, same reasoning `Button`'s `dimmed` state documents.
-- **2.3.3 (reduced motion)** — the row-shift preview is skipped (`Animated.Value.setValue`, no
-  `Animated.timing`) when `useReducedMotion()` is true, the identical pattern
-  `Accordion`'s chevron rotation uses, verified the same way (`jest.spyOn(Animated, "timing")`).
-
-## Why the drag never mutates `items` mid-gesture
-
-`Reorder` is fully controlled — the consumer owns `items` via `onReorder`. Mutating a local copy
-mid-drag would create a second source of truth that has to be reconciled with the next `items` prop
-the consumer sends back, and — because the dragged row's `key` is stable (`item.id`) — reordering the
-underlying array WOULD re-mount nothing, but WOULD instantly reset every row's `index` prop mid-
-gesture, which is exactly what the shift-preview math is built to avoid needing. Instead, only the
-ephemeral `{ startIndex, targetIndex }` pair changes during a drag, and `moveItem` is computed once,
-on release. Because the preview's `resolveRowShift` and the commit's `moveItem` share the same splice
-semantics, the row a shifted neighbour vacated is exactly where the dragged row lands — no jump when
-the consumer's new `items` prop arrives.
+  44dp via `GRIP_HIT_SLOP` on BOTH axes. The move buttons reuse `Button`'s already-proven `sm`
+  target.
+- **1.4.3** — the row label (`fg.default`) is measured ≥ 4.5:1 against both the resting (`bg.surface`)
+  and dragging (`bg.raised`) row fills, for all 8 brands × both modes.
+- **1.4.11** — the grip glyph (`fg.muted`) is measured ≥ 3:1 against both row fills. Its disabled
+  colour (`fg.disabled`) is NOT contrast-gated — a disabled control is exempt.
+- **2.3.3 (reduced motion)** — when `useMotion().enabled` is false the lift and the row shift snap to
+  their final value instead of tweening; `withTiming` is never called. Verified on the real rendered
+  row style, in both directions.
+- **2.4.3 (focus order)** — a move button disables at the list's end **unless it currently holds
+  keyboard focus**. Moving an item to an end otherwise disables the very button just pressed, and
+  RNW gives a disabled `Pressable` `tabIndex={-1}` in the same commit, so focus drops to the
+  document body (total loss on Android TV). The focused button therefore stays operable-but-inert —
+  `handleMove` ignores an out-of-range target — and re-disables the moment focus leaves it. The
+  alternative (imperatively focusing the sibling on commit) needs a ref `Button` does not expose.
+- **1.3.1 (row position)** — a row's accessible name is `"<label>, item <n> of <count>"`
+  (`resolveReorderRowLabel`), set on the label `Text`'s `accessibilityLabel` so the VISIBLE text
+  stays the plain label; order is otherwise readable only from where a row sits on screen.
+- **4.1.3 (move result)** — a committed move — from either the drag gesture (`endDrag`) or a move
+  button (`handleMove`) — calls `useAnnounce` with `resolveReorderMoveAnnouncement` ("`<label>` moved
+  to position `<n>` of `<count>`"). The 2.5.7 buttons already moved the list; without this the new
+  order was observable only by sight, which defeated the reason they exist. Fires once per committed
+  move (state, not a ref), never per drag frame — a live drag renders nothing (see above), so there
+  is nothing to over-announce.
 
 ## Known gaps
 
-- The live drag gesture's EXACT arithmetic is not re-derived from a fabricated `gestureState` end to
-  end: `PanResponder`'s internal handlers reconstruct `gestureState.dy` from `event.touchHistory`'s
-  centroid bookkeeping, and asserting a specific `dy` from fabricated touch history would mostly test
-  that reconstruction, not `Reorder` — so the exact arithmetic (`resolveDragTargetIndex`,
-  `resolveRowShift`, `moveItem`) is exhaustively pure-tested instead. What IS verified on the real
-  rendered node: `onStartShouldSetResponder`/`onMoveShouldSetResponder` (the gating predicates, which
-  read no touch data) correctly return `false` when `disabled`; a real fabricated-touch-history
-  grant/move/release (using a saturating `dy`, so it never depends on an exact row boundary) proves
-  the shift-reset-on-drop fix; and every other consequence of a real drag beyond that is a manual/QA
-  pass on-device before release.
-- No `variant`/`size` — a single fixed 56dp row height (`REORDER_ROW_HEIGHT`) and one visual style,
-  per the build brief's preference for a fixed height over per-row `onLayout` measurement.
-- The dragged row is visually lifted via `elevation.md` + a raised fill + `zIndex`, not a scale
-  transform — the build brief left this as an implementation choice ("slightly scaled or just
-  elevated — your call"); scale was skipped to avoid a second `Animated.Value` per row for a purely
-  decorative flourish.
+- The drag is driven in tests through the pan's captured callbacks, not a native gesture — the
+  gesture recognizer's own activation thresholds and its interplay with the list's scroll are a
+  manual/QA pass on-device before release.
+- No `variant`/`size` — one fixed 56dp row height (`REORDER_ROW_HEIGHT`) and one visual style, per
+  the build brief's preference for a fixed height over per-row `onLayout` measurement.
+- The dragged row is lifted via `elevation.md` + a raised fill + `zIndex`, not a scale transform —
+  the build brief left this as an implementation choice.
+- While a focused end button is operable-but-inert, a screen reader hears no "dimmed" state for it —
+  the trade taken for never losing focus. Every unfocused end button still announces as disabled.
 
 ## Performance
 
-`Reorder` (exported) and the internal `ReorderRow` are both wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — the literal "Reorder rows" case CLAUDE.md's Performance section calls out by name; without memoizing the row itself, memoizing its callbacks would have no effect, since `Reorder` re-renders every row on each drag-move tick. `colors` is `useMemo`'d; `handleDragStart`/`handleDragMove`/`handleMove`/`handleMoveUp`/`handleMoveDown` are `useCallback`'d with stable deps, so a row whose own props didn't change skips re-rendering during a drag. `handleDragEnd` needs the CURRENT `dragState` at drop time but must NOT be recreated on every drag-target transition (that would hand every row a changed `onDragEnd` reference and defeat their memo on the exact hot path this pass targets) — it reads `dragState` through a `dragStateRef` mirror instead of depending on `dragState` directly, so its own identity stays stable across a whole drag. `onMoveUp`/`onMoveDown` are now `(index: number) => void` (was `() => void`) so one stable per-list callback replaces the old per-row `() => handleMove(index, index ± 1)` closure; `ReorderRow` itself binds its own `index` via `handlePressUp`/`handlePressDown` so `Button` (a library child) also gets a stable `onPress`.
+`Reorder` and the private `ReorderRow` are both `React.memo`'d. `colors` is `useMemo`'d; `beginDrag`,
+`endDrag`, `handleMove`, `handleMoveUp`, `handleMoveDown`, `renderItem` and `keyExtractor` are all
+`useCallback`/`useMemo`'d with stable deps, so a live drag re-renders no row at all. The drag commit
+reads the current `items`/`onReorder` through refs, so the `Gesture.Pan()` object never has to be
+rebuilt mid-drag (re-registering a `GestureDetector` mid-drag drops the live gesture). Row callbacks
+take an `index`/`id` argument, so no per-row closure is allocated in the render loop.
+
+## History (v1.0.7)
+
+Replaced the original `PanResponder` + per-row `Animated.Value` implementation — one responder AND
+one animated node per row, no virtualization, unusable past a few hundred rows — with the single
+shared gesture + `VirtualList` described above. `react-native-gesture-handler` and
+`react-native-reanimated` are non-optional peers. **No public prop API change.**