react-native-drax 0.11.0-alpha.2 → 1.1.0

package/src/SortableItem.tsx

@@ -0,0 +1,264 @@
+import type { ReactNode } from 'react';
+import { memo, useEffect, useMemo, useRef } from 'react';
+import type { ViewStyle } from 'react-native';
+import { Platform } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import { useDerivedValue, useSharedValue } from 'react-native-reanimated';
+import Reanimated, {
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+import { DraxView } from './DraxView';
+import { useDraxContext } from './hooks/useDraxContext';
+import type { SortableItemContextValue } from './SortableItemContext';
+import { SortableItemContext } from './SortableItemContext';
+import type { ResolvedAnimationConfig } from './params';
+import { resolveAnimationConfig } from './params';
+import type {
+  DraxViewMeasurementHandler,
+  DraxViewProps,
+  Position,
+  SortableItemMeasurement,
+  SortableListHandle,
+} from './types';
+
+/**
+ * Isolated hook for SortableItem animated style.
+ * Kept separate so the worklet closure only contains SharedValues —
+ * never React refs from the component scope.
+ */
+function useSortableItemStyle(
+  hoverReadySV: SharedValue<boolean>,
+  draggedIdSV: SharedValue<string>,
+  viewIdSV: SharedValue<string>,
+  shiftsValidSV: SharedValue<boolean>,
+  shiftsRef: SharedValue<Record<string, Position>>,
+  instantClearSV: SharedValue<boolean>,
+  itemKey: string | undefined,
+  animConfig: ResolvedAnimationConfig,
+  reducedMotion: boolean,
+  inactiveItemStyle?: ViewStyle,
+) {
+  return useAnimatedStyle(() => {
+    // Guard: viewIdSV starts as '' before DraxView registers. Without the
+    // non-empty check, a newly mounted item would match a cleared draggedIdSV ('')
+    // and be hidden (opacity 0) until hoverReadySV clears — visible in cross-container transfers.
+    const isDragged = hoverReadySV.value && viewIdSV.value !== '' && draggedIdSV.value === viewIdSV.value;
+    const dragActive = draggedIdSV.value !== '';
+    const valid = shiftsValidSV.value;
+    const shifts = shiftsRef.value;
+    const shift = valid && itemKey ? shifts[itemKey] : undefined;
+    const instant = instantClearSV.value;
+    // When shifts are invalidated (data committing), snap to 0 instantly — no animation.
+    // When reduced motion is on, skip all animations.
+    const skipAnimation = instant || !valid || reducedMotion;
+
+    const toX = shift?.x ?? 0;
+    const toY = shift?.y ?? 0;
+
+    let translateX: number;
+    let translateY: number;
+
+    if (skipAnimation) {
+      translateX = toX;
+      translateY = toY;
+    } else if (animConfig.useSpring) {
+      const springConfig = {
+        damping: animConfig.springDamping,
+        stiffness: animConfig.springStiffness,
+        mass: animConfig.springMass,
+      };
+      translateX = withSpring(toX, springConfig);
+      translateY = withSpring(toY, springConfig);
+    } else {
+      const timingConfig = { duration: animConfig.shiftDuration, easing: Easing.linear };
+      translateX = withTiming(toX, timingConfig);
+      translateY = withTiming(toY, timingConfig);
+    }
+
+    // Apply inactive style to non-dragged items while a drag is active
+    const isInactive = dragActive && !isDragged;
+
+    return {
+      opacity: isDragged ? 0 : 1,
+      transform: [
+        { translateX },
+        { translateY },
+      ] as const,
+      ...(isInactive && inactiveItemStyle ? inactiveItemStyle : {}),
+    };
+  });
+}
+
+export interface SortableItemProps extends DraxViewProps {
+  sortable: SortableListHandle<any>;
+  index: number;
+  /** When true, this item cannot be dragged and stays in its position.
+   *  Other items will skip over it during reorder. */
+  fixed?: boolean;
+  children: ReactNode;
+}
+
+const SortableItemInner = ({
+  sortable,
+  index,
+  fixed = false,
+  children,
+  ...draxViewProps
+}: SortableItemProps) => {
+  const {
+    horizontal,
+    lockToMainAxis,
+    longPressDelay,
+    animationConfig,
+    inactiveItemStyle,
+    itemEntering,
+    itemExiting,
+    shiftsRef,
+    instantClearSV,
+    shiftsValidSV,
+    itemMeasurements,
+    keyExtractor,
+    rawData,
+    originalIndexes,
+    scrollPosition,
+    onItemSnapEnd,
+    fixedKeys,
+  } = sortable._internal;
+
+  // Get hoverReadySV and draggedIdSV from DraxContext (provider-level SharedValues)
+  const { hoverReadySV, draggedIdSV } = useDraxContext();
+
+  const originalIndex = originalIndexes[index] ?? index;
+  const item = rawData[originalIndex];
+  const itemKey = item !== undefined ? keyExtractor(item, index) : undefined;
+
+  // Register/unregister fixed items so reorder logic can skip them.
+  useEffect(() => {
+    if (!itemKey) return;
+    if (fixed) {
+      fixedKeys.current.add(itemKey);
+    } else {
+      fixedKeys.current.delete(itemKey);
+    }
+    return () => { fixedKeys.current.delete(itemKey); };
+  }, [fixed, itemKey, fixedKeys]);
+
+  // Store this DraxView's registered ID in a SharedValue so useAnimatedStyle
+  // can compare it with draggedIdSV on the UI thread.
+  const viewIdSV = useSharedValue('');
+
+  const measureFnRef = useRef<
+    ((handler?: DraxViewMeasurementHandler) => void) | null
+  >(null);
+
+  // Resolve animation config and check reduced motion preference
+  const resolvedAnimConfig = useMemo(() => resolveAnimationConfig(animationConfig), [animationConfig]);
+  const reducedMotion = useReducedMotion();
+
+  // Delegated to isolated hook so worklet closure has no refs from this scope.
+  const itemStyle = useSortableItemStyle(
+    hoverReadySV, draggedIdSV, viewIdSV,
+    shiftsValidSV, shiftsRef, instantClearSV, itemKey,
+    resolvedAnimConfig, reducedMotion, inactiveItemStyle,
+  );
+
+  // Derive isActive SharedValue for useItemContext consumers
+  const isActive = useDerivedValue(() => {
+    return viewIdSV.value !== '' && draggedIdSV.value === viewIdSV.value;
+  });
+
+  // Build context value for useItemContext
+  const itemContextValue = useMemo<SortableItemContextValue | null>(() => {
+    if (!itemKey) return null;
+    return {
+      itemKey,
+      index,
+      isActive,
+      activeItemId: draggedIdSV,
+    };
+  }, [itemKey, index, isActive, draggedIdSV]);
+
+  // Auto-generate accessibility props (can be overridden via draxViewProps)
+  const totalItems = rawData.length;
+  const defaultA11yLabel = `Item ${index + 1} of ${totalItems}`;
+  const defaultA11yHint = 'Long press to drag and reorder';
+
+  const mergedPayload = useMemo(() => ({
+    ...(typeof draxViewProps.payload === 'object' && draxViewProps.payload !== null
+      ? draxViewProps.payload : {}),
+    index, originalIndex, item,
+  }), [draxViewProps.payload, index, originalIndex, item]);
+
+  return (
+    <SortableItemContext value={itemContextValue}>
+    <Reanimated.View style={itemStyle} entering={itemEntering} exiting={itemExiting}>
+      <DraxView
+        longPressDelay={longPressDelay}
+        lockDragXPosition={lockToMainAxis && !horizontal}
+        lockDragYPosition={lockToMainAxis && horizontal}
+        scrollHorizontal={horizontal || undefined}
+        draggable={!fixed}
+        accessibilityLabel={defaultA11yLabel}
+        accessibilityHint={defaultA11yHint}
+        accessibilityRole="adjustable"
+        {...draxViewProps}
+        payload={mergedPayload}
+        registration={(reg) => {
+          measureFnRef.current = reg?.measure ?? null;
+          // Capture the DraxView's registered ID so useAnimatedStyle can match
+          // it against draggedIdSV for visibility control.
+          viewIdSV.value = reg?.id ?? '';
+        }}
+        onDragEnd={(event) => {
+          draxViewProps.onDragEnd?.(event);
+        }}
+        onDragDrop={(event) => {
+          draxViewProps.onDragDrop?.(event);
+        }}
+        onSnapEnd={(snapData) => {
+          onItemSnapEnd?.();
+          draxViewProps.onSnapEnd?.(snapData);
+        }}
+        onMeasure={(measurements) => {
+          draxViewProps.onMeasure?.(measurements);
+          if (itemKey && measurements) {
+            // Subtract Drax shift transforms when they're included in the
+            // measurement. On web: measureLayout always includes transforms.
+            // On native: measureLayout ignores transforms, UNLESS DraxView
+            // auto-detected transform-based positioning (LegendList) and
+            // switched to measure() — flagged via _transformDetected.
+            let adjX = measurements.x;
+            let adjY = measurements.y;
+            if (Platform.OS === 'web' || measurements._transformDetected) {
+              const currentShift = shiftsRef.value[itemKey];
+              if (currentShift) {
+                adjX -= currentShift.x;
+                adjY -= currentShift.y;
+              }
+            }
+            const entry: SortableItemMeasurement = {
+              x: adjX,
+              y: adjY,
+              width: measurements.width,
+              height: measurements.height,
+              key: itemKey,
+              index,
+              scrollAtMeasure: { x: scrollPosition.value.x, y: scrollPosition.value.y },
+            };
+            itemMeasurements.current.set(itemKey, entry);
+          }
+        }}
+      >
+        {children}
+      </DraxView>
+    </Reanimated.View>
+    </SortableItemContext>
+  );
+};
+
+export const SortableItem = memo(SortableItemInner) as typeof SortableItemInner;

package/src/SortableItemContext.ts

@@ -0,0 +1,46 @@
+import { createContext, use } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+
+/** Per-item state exposed by useItemContext */
+export interface SortableItemContextValue {
+  /** The item's key (from keyExtractor) */
+  itemKey: string;
+  /** Display index in the current sort order */
+  index: number;
+  /** SharedValue: true when this item is being dragged */
+  isActive: SharedValue<boolean>;
+  /** SharedValue: ID of the currently dragged item (empty string if none) */
+  activeItemId: SharedValue<string>;
+}
+
+export const SortableItemContext = createContext<SortableItemContextValue | null>(null);
+
+/**
+ * Access per-item state from within a SortableItem's children.
+ *
+ * Returns SharedValues for reactive animations:
+ * - `isActive` — true when THIS item is being dragged
+ * - `activeItemId` — ID of the currently dragged item
+ * - `itemKey` — this item's key
+ * - `index` — this item's display index
+ *
+ * Must be called within a `<SortableItem>`.
+ *
+ * @example
+ * ```tsx
+ * function MyItem() {
+ *   const { isActive } = useItemContext();
+ *   const style = useAnimatedStyle(() => ({
+ *     transform: [{ scale: isActive.value ? 1.1 : 1 }],
+ *   }));
+ *   return <Reanimated.View style={style}>...</Reanimated.View>;
+ * }
+ * ```
+ */
+export const useItemContext = (): SortableItemContextValue => {
+  const ctx = use(SortableItemContext);
+  if (!ctx) {
+    throw new Error('useItemContext must be used within a SortableItem');
+  }
+  return ctx;
+};

package/src/compat/detectVersion.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime detection of react-native-gesture-handler version.
+ * Returns true if v3 hook API (usePanGesture) is available.
+ * Result is cached after first call.
+ */
+let _isV3: boolean | null = null;
+
+export function isGestureHandlerV3(): boolean {
+  if (_isV3 !== null) return _isV3;
+  try {
+    const rngh = require('react-native-gesture-handler');
+    _isV3 = typeof rngh.usePanGesture === 'function';
+  } catch {
+    _isV3 = false;
+  }
+  return _isV3;
+}

package/src/compat/index.ts

@@ -0,0 +1,7 @@
+export { useDraxPanGesture } from './useDraxPanGesture';
+export type {
+  DraxPanEvent,
+  DraxPanGesture,
+  DraxPanGestureConfig,
+} from './types';
+export { isGestureHandlerV3 } from './detectVersion';

package/src/compat/types.ts

@@ -0,0 +1,35 @@
+import type { SharedValue } from 'react-native-reanimated';
+
+/**
+ * Re-export PanGesture from RNGH — resolves to the correct type per installed version:
+ * - v3: SingleGesture<PanHandlerData, PanGestureInternalProperties>
+ * - v2: PanGesture class extending ContinousBaseGesture
+ */
+export type { PanGesture as DraxPanGesture } from 'react-native-gesture-handler';
+
+/** Minimal event shape — only the fields Drax uses (present in both v2 and v3). */
+export interface DraxPanEvent {
+  x: number;
+  y: number;
+  absoluteX: number;
+  absoluteY: number;
+}
+
+/** Config for the version-agnostic pan gesture hook. */
+export interface DraxPanGestureConfig {
+  enabledSV: SharedValue<boolean>;
+  longPressDelaySV: SharedValue<number>;
+  maxPointers: number;
+  shouldCancelWhenOutside: boolean;
+  /** Web: CSS touch-action for the gesture view. Set to 'pan-y' or 'pan-x'
+   *  to allow native scrolling before the long-press activates. */
+  touchAction?: string;
+  /** Fail the gesture if finger moves more than this distance during activation.
+   *  Prevents accidental drags when the user is trying to scroll. */
+  failOffsetX?: number | [number, number];
+  failOffsetY?: number | [number, number];
+  onActivate: (event: DraxPanEvent) => void;
+  onUpdate: (event: DraxPanEvent) => void;
+  onDeactivate: (event: DraxPanEvent) => void;
+  onFinalize: (event: DraxPanEvent, didSucceed: boolean) => void;
+}

package/src/compat/useDraxPanGesture.ts

@@ -0,0 +1,112 @@
+import { useMemo, useState } from 'react';
+import { useAnimatedReaction } from 'react-native-reanimated';
+import { runOnJS } from 'react-native-worklets';
+
+import { isGestureHandlerV3 } from './detectVersion';
+import type { DraxPanEvent, DraxPanGesture, DraxPanGestureConfig } from './types';
+
+// Module-scope require — cached by the bundler, always the same reference.
+// Hoisted out of the hook body so the compiler sees a stable function identity.
+const rngh = require('react-native-gesture-handler');
+
+/**
+ * v3 path — passes through to RNGH's usePanGesture with SharedValue config.
+ * Zero overhead, UI-thread-driven reconfiguration.
+ */
+function useDraxPanGestureV3(config: DraxPanGestureConfig): DraxPanGesture {
+  // Build config without undefined failOffset keys — RNGH v3 warns on
+  // undefined keys that survive transformOffsetProp without deletion.
+  // Spread is not allowed here (Reanimated workletizes hook arguments).
+  const panConfig: Record<string, unknown> = {
+    enabled: config.enabledSV,
+    activateAfterLongPress: config.longPressDelaySV,
+    maxPointers: config.maxPointers,
+    shouldCancelWhenOutside: config.shouldCancelWhenOutside,
+    touchAction: config.touchAction,
+    onActivate: config.onActivate,
+    onUpdate: config.onUpdate,
+    onDeactivate: config.onDeactivate,
+    onFinalize: config.onFinalize,
+  };
+  if (config.failOffsetX !== undefined) panConfig.failOffsetX = config.failOffsetX;
+  if (config.failOffsetY !== undefined) panConfig.failOffsetY = config.failOffsetY;
+  return rngh.usePanGesture(panConfig);
+}
+
+/**
+ * v2 path — wraps Gesture.Pan() builder pattern.
+ * SharedValue config is watched via useAnimatedReaction and triggers gesture
+ * recreation on change. This is slower than v3 but functionally correct.
+ * In practice, enabled/longPressDelay change very rarely (prop updates only).
+ */
+function useDraxPanGestureV2(config: DraxPanGestureConfig): DraxPanGesture {
+  const Gesture = rngh.Gesture;
+
+  // Mirror SharedValues to React state for v2 gesture config
+  const [enabled, setEnabled] = useState(config.enabledSV.value);
+  const [longPressDelay, setLongPressDelay] = useState(
+    config.longPressDelaySV.value
+  );
+
+  // Watch SharedValue changes and sync to JS state
+  useAnimatedReaction(
+    () => config.enabledSV.value,
+    (current, prev) => {
+      if (prev !== null && current !== prev) {
+        runOnJS(setEnabled)(current);
+      }
+    }
+  );
+
+  useAnimatedReaction(
+    () => config.longPressDelaySV.value,
+    (current, prev) => {
+      if (prev !== null && current !== prev) {
+        runOnJS(setLongPressDelay)(current);
+      }
+    }
+  );
+
+  // Typed as DraxPanGesture directly — v2 builder returns a legacy type that's structurally
+  // different from v3's PanGesture at compile time, but GestureDetector accepts both at runtime.
+  // Since Gesture comes from require() (any), the assignment is valid without a cast.
+  const gesture: DraxPanGesture = useMemo(() => {
+    let g = Gesture.Pan()
+      .enabled(enabled)
+      .activateAfterLongPress(longPressDelay)
+      .maxPointers(config.maxPointers)
+      .shouldCancelWhenOutside(config.shouldCancelWhenOutside);
+    if (config.failOffsetX !== undefined) g = g.failOffsetX(config.failOffsetX);
+    if (config.failOffsetY !== undefined) g = g.failOffsetY(config.failOffsetY);
+    return g
+      .onStart((event: DraxPanEvent) => {
+        'worklet';
+        config.onActivate(event);
+      })
+      .onUpdate((event: DraxPanEvent) => {
+        'worklet';
+        config.onUpdate(event);
+      })
+      .onEnd((event: DraxPanEvent) => {
+        'worklet';
+        config.onDeactivate(event);
+      })
+      .onFinalize((event: DraxPanEvent, success: boolean) => {
+        'worklet';
+        config.onFinalize(event, success);
+      });
+  }, [Gesture, enabled, longPressDelay, config]);
+
+  return gesture;
+}
+
+/**
+ * Version-agnostic pan gesture hook.
+ * Delegates to v3's usePanGesture (optimal) or v2's Gesture.Pan() builder (compat).
+ * Selected at module load time to avoid conditional hook calls.
+ */
+export const useDraxPanGesture: (
+  config: DraxPanGestureConfig
+) => DraxPanGesture = isGestureHandlerV3()
+  ? useDraxPanGestureV3
+  : useDraxPanGestureV2;

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useDraxContext } from './useDraxContext';
+export { useDraxId } from './useDraxId';