pixelize-native-library 1.0.7 → 1.2.1

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,115 @@ 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.**
+
+Drag completion uses `scheduleOnRN` from `react-native-worklets` (not deprecated `runOnJS`).