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

package/src/hooks/useDragGesture.ts

@@ -0,0 +1,273 @@
+import { Platform } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
+import { runOnJS } from 'react-native-worklets';
+
+import { useDraxPanGesture } from '../compat';
+import { computeAbsolutePositionWorklet, hitTestWorklet } from '../math';
+import type { Position } from '../types';
+import { useDraxContext } from './useDraxContext';
+
+/**
+ * Creates a Pan gesture for a draggable DraxView.
+ * Hit-testing runs entirely on the UI thread — zero runOnJS per frame
+ * unless the receiver changes.
+ *
+ * On RNGH v3, `enabledSV` and `longPressDelaySV` are SharedValues that
+ * reconfigure the native gesture handler on the UI thread — zero JS bridge.
+ * On RNGH v2, they are mirrored to plain values with gesture recreation on change.
+ */
+export const useDragGesture = (
+  id: string,
+  viewSpatialIndexSV: SharedValue<number>,
+  enabledSV: SharedValue<boolean>,
+  longPressDelaySV: SharedValue<number>,
+  lockDragXPosition?: boolean,
+  lockDragYPosition?: boolean,
+  dragBoundsSV?: SharedValue<{ x: number; y: number; width: number; height: number } | null>,
+  dragActivationFailOffset?: number,
+  scrollHorizontal?: boolean
+) => {
+  const {
+    draggedIdSV,
+    receiverIdSV,
+    rejectedReceiverIdSV,
+    dragPhaseSV,
+    hoverPositionSV,
+    dragAbsolutePositionSV,
+    spatialIndexSV,
+    scrollOffsetsSV,
+    grabOffsetSV,
+    startPositionSV,
+    rootOffsetSV,
+    handleDragStart,
+    handleReceiverChange,
+    handleDragEnd,
+  } = useDraxContext();
+
+  // On web, RNGH defaults touch-action to 'none' which blocks native scroll.
+  // Allow the scroll direction so users can scroll before long-press activates.
+  // SortableContainer freezes the scroll container when drag starts.
+  //
+  // Priority: lockDragYPosition (explicit axis lock → pan-x) > scrollHorizontal
+  // (hint from SortableItem for horizontal lists without axis lock) > default pan-y.
+  const touchAction = Platform.OS === 'web'
+    ? ((lockDragYPosition || scrollHorizontal) ? 'pan-x' : 'pan-y')
+    : undefined;
+
+  const failOffset = dragActivationFailOffset !== undefined
+    ? [-dragActivationFailOffset, dragActivationFailOffset] as [number, number]
+    : undefined;
+
+  const gesture = useDraxPanGesture({
+    enabledSV,
+    longPressDelaySV,
+    maxPointers: 1,
+    shouldCancelWhenOutside: false,
+    touchAction,
+    failOffsetX: failOffset,
+    failOffsetY: failOffset,
+    onActivate: (event) => {
+      'worklet';
+
+      // Convert screen-absolute touch to root-view-relative
+      const rootOffset = rootOffsetSV.value;
+      const rootRelX = event.absoluteX - rootOffset.x;
+      const rootRelY = event.absoluteY - rootOffset.y;
+
+      // Derive the view's visual position from the gesture event.
+      // event.x/y = touch relative to the view's bounds (accounts for transforms).
+      // This is more accurate than the spatial index for sortable items where
+      // permanent shifts move views via CSS transform without updating layout.
+      const viewAbsPos: Position = {
+        x: rootRelX - event.x,
+        y: rootRelY - event.y,
+      };
+
+      // Grab offset = touch position within the view
+      const grabOffset: Position = {
+        x: event.x,
+        y: event.y,
+      };
+
+      // Store shared state (all positions in root-relative space).
+      // DO NOT set dragPhaseSV here — it's set by HoverLayer's useLayoutEffect
+      // AFTER hover content is committed to the DOM. This prevents the grab blink
+      // (item going invisible before hover is visible).
+      draggedIdSV.value = id;
+      grabOffsetSV.value = grabOffset;
+      startPositionSV.value = { x: rootRelX, y: rootRelY };
+      dragAbsolutePositionSV.value = { x: rootRelX, y: rootRelY };
+
+      // Compute initial hover position (root-relative)
+      let hoverX = lockDragXPosition ? viewAbsPos.x : rootRelX - grabOffset.x;
+      let hoverY = lockDragYPosition ? viewAbsPos.y : rootRelY - grabOffset.y;
+
+      // Clamp to drag bounds if specified
+      if (dragBoundsSV?.value) {
+        const b = dragBoundsSV.value;
+        const entries = spatialIndexSV.value;
+        const viewEntry = entries[viewSpatialIndexSV.value];
+        const vw = viewEntry ? viewEntry.width : 0;
+        const vh = viewEntry ? viewEntry.height : 0;
+        hoverX = Math.max(b.x, Math.min(b.x + b.width - vw, hoverX));
+        hoverY = Math.max(b.y, Math.min(b.y + b.height - vh, hoverY));
+      }
+
+      hoverPositionSV.value = { x: hoverX, y: hoverY };
+
+      // Reset receiver and rejection cache
+      receiverIdSV.value = '';
+      rejectedReceiverIdSV.value = '';
+
+      // Bounce to JS for callback dispatch + hover content setup
+      runOnJS(handleDragStart)(
+        id,
+        { x: rootRelX, y: rootRelY },
+        grabOffset
+      );
+    },
+    onUpdate: (event) => {
+      'worklet';
+
+      // Convert screen-absolute touch to root-view-relative
+      const rootOffset = rootOffsetSV.value;
+      const rootRelX = event.absoluteX - rootOffset.x;
+      const rootRelY = event.absoluteY - rootOffset.y;
+      const rootRelPos: Position = { x: rootRelX, y: rootRelY };
+
+      dragAbsolutePositionSV.value = rootRelPos;
+
+      // Compute hover position (root-relative)
+      const grabOffset = grabOffsetSV.value;
+
+      // Read current spatial index
+      const spatialIndex = viewSpatialIndexSV.value;
+      const entries = spatialIndexSV.value;
+      const viewAbsPos = computeAbsolutePositionWorklet(
+        spatialIndex,
+        entries,
+        scrollOffsetsSV.value
+      );
+
+      let hoverX = lockDragXPosition ? viewAbsPos.x : rootRelX - grabOffset.x;
+      let hoverY = lockDragYPosition ? viewAbsPos.y : rootRelY - grabOffset.y;
+
+      // Clamp to drag bounds if specified
+      if (dragBoundsSV?.value) {
+        const b = dragBoundsSV.value;
+        const viewEntry = entries[spatialIndex];
+        const vw = viewEntry ? viewEntry.width : 0;
+        const vh = viewEntry ? viewEntry.height : 0;
+        hoverX = Math.max(b.x, Math.min(b.x + b.width - vw, hoverX));
+        hoverY = Math.max(b.y, Math.min(b.y + b.height - vh, hoverY));
+      }
+
+      hoverPositionSV.value = { x: hoverX, y: hoverY };
+
+      // Hit-test at the center of the hover view (not at the raw finger position)
+      // so that receiving activates when the dragged item visually overlaps the receiver.
+      const viewEntry = entries[spatialIndex];
+      const hitTestPos: Position = {
+        x: hoverX + (viewEntry ? viewEntry.width / 2 : 0),
+        y: hoverY + (viewEntry ? viewEntry.height / 2 : 0),
+      };
+      dragAbsolutePositionSV.value = hitTestPos;
+
+      const result = hitTestWorklet(
+        hitTestPos,
+        entries,
+        scrollOffsetsSV.value,
+        id,
+        viewEntry ? { width: viewEntry.width, height: viewEntry.height } : undefined
+      );
+
+      // Skip the rejected receiver — don't set it in receiverIdSV and don't
+      // send it to JS. This prevents the reject → clear → re-detect → reject loop.
+      let candidateReceiverId = result.receiverId;
+      if (candidateReceiverId === rejectedReceiverIdSV.value) {
+        candidateReceiverId = '';
+      }
+
+      // Clear rejection cache once drag leaves the rejected receiver's bounds
+      if (result.receiverId !== rejectedReceiverIdSV.value && rejectedReceiverIdSV.value !== '') {
+        rejectedReceiverIdSV.value = '';
+      }
+
+      // Always bounce to JS for callback dispatch.
+      // handleReceiverChange safely handles same-receiver calls (skips exit/enter)
+      // and dispatches continuous callbacks (onDrag, onDragOver, onReceiveDragOver)
+      // plus monitor position updates for slot detection.
+      const oldReceiver = receiverIdSV.value;
+      const receiverChanged = candidateReceiverId !== oldReceiver;
+      if (receiverChanged) {
+        receiverIdSV.value = candidateReceiverId;
+      }
+      runOnJS(handleReceiverChange)(
+        oldReceiver,
+        candidateReceiverId,
+        hitTestPos,
+        result.monitorIds
+      );
+    },
+    onDeactivate: (_event) => {
+      'worklet';
+
+      const currentDraggedId = draggedIdSV.value;
+      const currentReceiverId = receiverIdSV.value;
+
+      // Run final hit-test to capture current monitors.
+      // Monitor IDs are only updated on receiver changes, so if no receiver
+      // change happened during the drag, monitors would be empty in handleDragEnd.
+      const deactivateEntries = spatialIndexSV.value;
+      const viewEntryFinal = deactivateEntries[viewSpatialIndexSV.value];
+      const finalDims = viewEntryFinal
+        ? { width: viewEntryFinal.width, height: viewEntryFinal.height }
+        : undefined;
+      const finalHitResult = hitTestWorklet(
+        dragAbsolutePositionSV.value,
+        deactivateEntries,
+        scrollOffsetsSV.value,
+        id,
+        finalDims
+      );
+
+      // Set phase and clear receiver on UI thread so useAnimatedStyle
+      // re-evaluates immediately (receiver style clears instantly).
+      dragPhaseSV.value = 'releasing';
+      receiverIdSV.value = '';
+
+      // Bounce to JS for end callbacks + snap animation
+      runOnJS(handleDragEnd)(currentDraggedId, currentReceiverId, false, finalHitResult.monitorIds);
+    },
+    onFinalize: (_event, didSucceed) => {
+      'worklet';
+
+      // If gesture was cancelled (not ended normally).
+      // Check draggedIdSV (set in onActivate) instead of dragPhaseSV
+      // because phase is now set later in handleDragStart via runOnUI.
+      if (!didSucceed && draggedIdSV.value !== '') {
+        const currentDraggedId = draggedIdSV.value;
+        const currentReceiverId = receiverIdSV.value;
+
+        const viewEntryCancel = spatialIndexSV.value[viewSpatialIndexSV.value];
+        const cancelDims = viewEntryCancel
+          ? { width: viewEntryCancel.width, height: viewEntryCancel.height }
+          : undefined;
+        const finalHitResult = hitTestWorklet(
+          dragAbsolutePositionSV.value,
+          spatialIndexSV.value,
+          scrollOffsetsSV.value,
+          id,
+          cancelDims
+        );
+
+        dragPhaseSV.value = 'releasing';
+        receiverIdSV.value = '';
+
+        runOnJS(handleDragEnd)(currentDraggedId, currentReceiverId, true, finalHitResult.monitorIds);
+      }
+    },
+  });
+
+  return gesture;
+};

package/src/hooks/useDraxContext.ts

@@ -0,0 +1,11 @@
+import { use } from 'react';
+
+import { DraxContext } from '../DraxContext';
+
+export const useDraxContext = () => {
+  const drax = use(DraxContext);
+  if (!drax) {
+    throw Error('No DraxProvider found');
+  }
+  return drax;
+};

package/src/hooks/useDraxId.ts

@@ -0,0 +1,11 @@
+import { useState } from 'react';
+
+import { generateRandomId } from '../math';
+
+// Return explicitId, or a consistent randomly generated identifier if explicitId is falsy.
+export const useDraxId = (explicitId?: string) => {
+  // A generated unique identifier for this view, for use if id prop is not specified.
+  const [randomId] = useState(generateRandomId);
+  // We use || rather than ?? for the return value in case explicitId is an empty string.
+  return explicitId || randomId;
+};

package/src/hooks/useDraxMethods.ts

@@ -0,0 +1,71 @@
+import { useDraxContext } from './useDraxContext';
+
+/**
+ * Imperative methods for controlling and querying the Drax provider.
+ *
+ * Must be called within a `<DraxProvider>`.
+ */
+export const useDraxMethods = () => {
+  const ctx = useDraxContext();
+
+  /**
+   * Trigger re-measurement of all registered views.
+   * Useful after dynamic layout changes where onLayout may not fire
+   * (e.g., orientation changes, animated layout transitions).
+   */
+  const requestPositionUpdate = () => {
+    // Re-measuring is done by reading each view's measure function from
+    // the spatial index. For now, this triggers a spatial index refresh
+    // by writing the current value back — views that are still mounted
+    // will re-measure on the next layout pass.
+    const current = ctx.spatialIndexSV.value;
+    ctx.spatialIndexSV.value = [...current];
+  };
+
+  /**
+   * Get the set of dragged item IDs currently dropped on a specific receiver.
+   * Returns an empty Set if no items have been dropped on the receiver.
+   */
+  const getDroppedItems = (receiverId?: string): Map<string, Set<string>> | Set<string> => {
+    if (receiverId) {
+      return ctx.droppedItemsRef.current.get(receiverId) ?? new Set();
+    }
+    return new Map(ctx.droppedItemsRef.current);
+  };
+
+  /**
+   * Clear all tracked dropped items for a specific receiver,
+   * or clear all dropped items if no receiverId is provided.
+   * Call this when items are programmatically removed from a drop zone.
+   */
+  const clearDroppedItems = (receiverId?: string) => {
+    if (receiverId) {
+      ctx.droppedItemsRef.current.delete(receiverId);
+    } else {
+      ctx.droppedItemsRef.current.clear();
+    }
+  };
+
+  /**
+   * Check if a drag is currently active.
+   */
+  const isDragging = (): boolean => {
+    return ctx.draggedIdSV.value !== '';
+  };
+
+  /**
+   * Get the ID of the currently dragged view, or undefined if no drag is active.
+   */
+  const getDraggedId = (): string | undefined => {
+    const id = ctx.draggedIdSV.value;
+    return id || undefined;
+  };
+
+  return {
+    requestPositionUpdate,
+    getDroppedItems,
+    clearDroppedItems,
+    isDragging,
+    getDraggedId,
+  };
+};

package/src/hooks/useDraxScrollHandler.ts

@@ -0,0 +1,121 @@
+import type { Ref, RefObject } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+import { FlatList, ScrollView } from 'react-native';
+import {
+  runOnUI,
+  useSharedValue,
+} from 'react-native-reanimated';
+
+import { defaultAutoScrollIntervalLength } from '../params';
+import type { DraxViewMeasurements, Position } from '../types';
+import { useDraxId } from './useDraxId';
+
+// FlatList is invariant in its type parameter — `any` is the only valid union constraint
+type ScrollableComponents = FlatList<any> | ScrollView;
+
+type DraxScrollHandlerArgs<T extends ScrollableComponents> = {
+  idProp?: string;
+  onContentSizeChangeProp?: (w: number, h: number) => void;
+  onScrollProp?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  externalRef?: Ref<T>;
+  doScroll: RefObject<() => void>;
+};
+
+export const useDraxScrollHandler = <T extends ScrollableComponents>({
+  idProp,
+  onContentSizeChangeProp,
+  onScrollProp,
+  externalRef,
+  doScroll,
+}: DraxScrollHandlerArgs<T>) => {
+  const scrollRef = useRef<T>(null);
+  const id = useDraxId(idProp);
+  const containerMeasurementsRef = useRef<DraxViewMeasurements | undefined>(
+    undefined
+  );
+  const scrollIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(
+    undefined
+  );
+  const contentSizeRef = useRef<Position | undefined>(undefined);
+
+  const scrollPosition = useSharedValue<Position>({ x: 0, y: 0 });
+
+  const onMeasureContainer = (measurements: DraxViewMeasurements | undefined) => {
+    containerMeasurementsRef.current = measurements;
+  };
+
+  const onContentSizeChange = (width: number, height: number) => {
+    contentSizeRef.current = { x: width, y: height };
+    return onContentSizeChangeProp?.(width, height);
+  };
+
+  const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    onScrollProp?.(event);
+
+    runOnUI((_scrollPos: typeof scrollPosition, _event: NativeScrollEvent) => {
+      'worklet';
+      _scrollPos.value = {
+        x: _event.contentOffset.x,
+        y: _event.contentOffset.y,
+      };
+    })(scrollPosition, event.nativeEvent);
+  };
+
+  const setScrollRefs = (instance: T | null) => {
+    if (instance) {
+      scrollRef.current = instance;
+      if (externalRef) {
+        if (typeof externalRef === 'function') {
+          externalRef(instance);
+        } else {
+          externalRef.current = instance;
+        }
+      }
+    }
+  };
+
+  const startScroll = useCallback(() => {
+    if (scrollIntervalRef.current) {
+      return;
+    }
+    doScroll.current();
+    scrollIntervalRef.current = setInterval(
+      () => doScroll.current(),
+      defaultAutoScrollIntervalLength
+    );
+  }, [doScroll]);
+
+  const stopScroll = useCallback(() => {
+    if (scrollIntervalRef.current) {
+      clearInterval(scrollIntervalRef.current);
+      scrollIntervalRef.current = undefined;
+    }
+  }, []);
+
+  useEffect(() => {
+    if (scrollIntervalRef.current) {
+      stopScroll();
+      startScroll();
+    }
+  }, [stopScroll, startScroll]);
+
+  // Clean up interval on unmount
+  useEffect(() => {
+    return () => stopScroll();
+  }, [stopScroll]);
+
+  return {
+    id,
+    containerMeasurementsRef,
+    contentSizeRef,
+    onContentSizeChange,
+    onMeasureContainer,
+    onScroll,
+    scrollRef,
+    scrollPosition,
+    setScrollRefs,
+    startScroll,
+    stopScroll,
+  };
+};

package/src/hooks/useSortableBoard.ts

@@ -0,0 +1,44 @@
+import { useCallback, useRef } from 'react';
+import type {
+  SortableBoardHandle,
+  SortableBoardInternal,
+  SortableBoardTransferState,
+  SortableListInternal,
+  UseSortableBoardOptions,
+} from '../types';
+
+/**
+ * Board-level coordinator for cross-container sortable drag.
+ *
+ * Maintains a registry of columns (each with their own useSortableList)
+ * and tracks cross-container transfer state. The actual monitor callbacks
+ * are handled by SortableBoardContainer.
+ */
+export const useSortableBoard = <TItem,>(
+  options: UseSortableBoardOptions<TItem>
+): SortableBoardHandle<TItem> => {
+  const { keyExtractor, onTransfer } = options;
+
+  const columnsRef = useRef<Map<string, SortableListInternal<unknown>>>(new Map());
+  const transferStateRef = useRef<SortableBoardTransferState | undefined>(undefined);
+
+  const registerColumn = useCallback((id: string, internal: SortableListInternal<unknown>) => {
+    columnsRef.current.set(id, internal);
+  }, []);
+
+  const unregisterColumn = useCallback((id: string) => {
+    columnsRef.current.delete(id);
+  }, []);
+
+  const internal: SortableBoardInternal<TItem> = {
+    keyExtractor,
+    onTransfer,
+    columns: columnsRef.current,
+    registerColumn,
+    unregisterColumn,
+    transferState: transferStateRef,
+    // finalizeTransfer is set by SortableBoardContainer (needs DraxContext access)
+  };
+
+  return { _internal: internal };
+};