react-native-drax 0.11.0-alpha.1 → 1.0.0

package/src/DraxList.tsx

@@ -0,0 +1,181 @@
+import type { ComponentType, ReactNode, Ref } from 'react';
+import { useRef } from 'react';
+import type {
+  FlatList,
+  ListRenderItemInfo,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+
+import { useSortableList } from './hooks/useSortableList';
+import { SortableContainer } from './SortableContainer';
+import { SortableItem } from './SortableItem';
+import type { EntryOrExitLayoutType } from 'react-native-reanimated';
+import type {
+  DraxViewProps,
+  SortableAnimationConfig,
+  SortableDragEndEvent,
+  SortableDragPositionChangeEvent,
+  SortableDragStartEvent,
+  SortableReorderEvent,
+  SortableReorderStrategy,
+} from './types';
+
+export interface DraxListProps<T> {
+  /**
+   * List component to render. Any component that accepts `data`, `renderItem`,
+   * and `keyExtractor` props (FlatList, FlashList, LegendList, etc.).
+   * @default FlatList
+   */
+  component?: ComponentType<any>;
+  ref?: Ref<any>;
+  /** Optional explicit DraxView id for the container */
+  id?: string;
+  data: T[];
+  keyExtractor: (item: T, index: number) => string;
+  onReorder: (event: SortableReorderEvent<T>) => void;
+  renderItem: (info: ListRenderItemInfo<T>) => ReactNode;
+  /** Reorder strategy. @default 'insert' */
+  reorderStrategy?: SortableReorderStrategy;
+  /** Long press delay before drag starts in ms. @default 250 */
+  longPressDelay?: number;
+  /** Lock item drags to the list's main axis. @default false */
+  lockToMainAxis?: boolean;
+  /** Animation config for item shift animations. @default 'default' */
+  animationConfig?: SortableAnimationConfig;
+  /** Style applied to all non-dragged items while a drag is active.
+   *  Use for dimming/scaling inactive items (e.g., `{ opacity: 0.5 }`). */
+  inactiveItemStyle?: ViewStyle;
+  /** Reanimated layout animation for items entering the list (e.g., `FadeIn`). */
+  itemEntering?: EntryOrExitLayoutType;
+  /** Reanimated layout animation for items exiting the list (e.g., `FadeOut`). */
+  itemExiting?: EntryOrExitLayoutType;
+  /** DraxView props to apply to each item */
+  itemDraxViewProps?: Partial<DraxViewProps>;
+  /** DraxView props for the container */
+  containerDraxViewProps?: Partial<DraxViewProps>;
+  /** Style for the container */
+  containerStyle?: StyleProp<ViewStyle>;
+  /** Style for the list component */
+  style?: StyleProp<ViewStyle>;
+  /** Horizontal list layout. @default false */
+  horizontal?: boolean;
+  /** Number of columns (grid layout). @default 1 */
+  numColumns?: number;
+  /** Callback when drag starts */
+  onDragStart?: (event: SortableDragStartEvent<T>) => void;
+  /** Callback when drag position changes */
+  onDragPositionChange?: (event: SortableDragPositionChangeEvent<T>) => void;
+  /** Callback when drag ends */
+  onDragEnd?: (event: SortableDragEndEvent<T>) => void;
+}
+
+/**
+ * List-agnostic sortable list component.
+ *
+ * Wraps any list component (FlatList, FlashList, LegendList, etc.) with
+ * drag-and-drop reordering powered by `useSortableList` + `SortableContainer` + `SortableItem`.
+ *
+ * For full control, use the composable API directly:
+ * `useSortableList` + `SortableContainer` + `SortableItem`.
+ *
+ * Any extra props beyond the ones defined in `DraxListProps` are forwarded
+ * to the underlying list component (e.g. `estimatedItemSize` for FlashList).
+ */
+export const DraxList = <T,>({
+  component: ListComponent,
+  ref,
+  id,
+  data,
+  keyExtractor,
+  onReorder,
+  renderItem,
+  reorderStrategy,
+  longPressDelay,
+  lockToMainAxis,
+  animationConfig,
+  inactiveItemStyle,
+  itemEntering,
+  itemExiting,
+  itemDraxViewProps,
+  containerDraxViewProps,
+  containerStyle,
+  onDragStart,
+  onDragPositionChange,
+  onDragEnd,
+  style,
+  horizontal,
+  numColumns,
+  ...listProps
+}: DraxListProps<T> & Record<string, any>): ReactNode => {
+  const isHorizontal = horizontal ?? false;
+  const cols = numColumns ?? 1;
+
+  const sortable = useSortableList({
+    id,
+    data,
+    keyExtractor,
+    onReorder,
+    horizontal: isHorizontal,
+    numColumns: cols,
+    reorderStrategy,
+    longPressDelay,
+    lockToMainAxis,
+    animationConfig,
+    inactiveItemStyle,
+    itemEntering,
+    itemExiting,
+    onDragStart,
+    onDragPositionChange,
+    onDragEnd,
+  });
+
+  const listRef = useRef<FlatList<T>>(null);
+
+  // Forward external ref
+  const setRef = (instance: FlatList<T> | null) => {
+    (listRef as any).current = instance;
+    if (ref) {
+      if (typeof ref === 'function') {
+        ref(instance);
+      } else {
+        (ref as any).current = instance;
+      }
+    }
+  };
+
+  // Lazy-load FlatList only when no component is provided.
+  // This avoids importing react-native's FlatList at module scope
+  // when the consumer uses a different list component.
+  const ResolvedList = ListComponent ?? require('react-native').FlatList;
+
+  return (
+    <SortableContainer
+      sortable={sortable}
+      scrollRef={listRef}
+      style={containerStyle}
+      draxViewProps={containerDraxViewProps}
+    >
+      <ResolvedList
+        {...listProps}
+        style={style}
+        ref={setRef}
+        horizontal={isHorizontal}
+        keyExtractor={sortable.stableKeyExtractor}
+        numColumns={cols}
+        data={sortable.data}
+        onScroll={sortable.onScroll}
+        onContentSizeChange={sortable.onContentSizeChange}
+        renderItem={(info: ListRenderItemInfo<T>) => (
+          <SortableItem
+            sortable={sortable}
+            index={info.index}
+            {...itemDraxViewProps}
+          >
+            {renderItem(info)}
+          </SortableItem>
+        )}
+      />
+    </SortableContainer>
+  );
+};

package/src/DraxProvider.tsx

@@ -0,0 +1,224 @@
+import type { ReactNode, RefObject } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import type { HostInstance } from 'react-native';
+import { StyleSheet, View } from 'react-native';
+import { useSharedValue } from 'react-native-reanimated';
+
+import { DebugOverlay } from './DebugOverlay';
+import { DraxContext } from './DraxContext';
+import type { FlattenedHoverStyles } from './HoverLayer';
+import { HoverLayer } from './HoverLayer';
+import { useCallbackDispatch } from './hooks/useCallbackDispatch';
+import { useSpatialIndex } from './hooks/useSpatialIndex';
+import type {
+  DragPhase,
+  DraxContextValue,
+  DraxProviderProps,
+  Position,
+} from './types';
+
+export const DraxProvider = ({
+  style = styles.provider,
+  debug = false,
+  onDragStart: onProviderDragStart,
+  onDrag: onProviderDrag,
+  onDragEnd: onProviderDragEnd,
+  children,
+}: DraxProviderProps): ReactNode => {
+  // ── Split SharedValues (by update frequency) ───────────────────────
+  // Changes ~2x per drag. Read by all DraxView useAnimatedStyle.
+  const draggedIdSV = useSharedValue<string>('');
+  // Changes ~3-5x per drag. Read by all DraxView useAnimatedStyle.
+  const receiverIdSV = useSharedValue<string>('');
+  // Changes ~3x per drag. Read by all DraxView useAnimatedStyle.
+  const dragPhaseSV = useSharedValue<DragPhase>('idle');
+  // Changes every frame during drag. Read ONLY by HoverLayer (1 component).
+  const hoverPositionSV = useSharedValue<Position>({ x: 0, y: 0 });
+  // Changes every frame during drag. Used by gesture worklet for hit-testing.
+  // NOT read by any useAnimatedStyle.
+  const dragAbsolutePositionSV = useSharedValue<Position>({ x: 0, y: 0 });
+  // ID of the most recently rejected receiver. Read by gesture worklet to skip
+  // re-detecting the same rejected receiver. Cleared when drag leaves its bounds.
+  const rejectedReceiverIdSV = useSharedValue<string>('');
+  // Set once per drag start.
+  const grabOffsetSV = useSharedValue<Position>({ x: 0, y: 0 });
+  const startPositionSV = useSharedValue<Position>({ x: 0, y: 0 });
+  // Screen offset of the root view (measured on layout).
+  const rootOffsetSV = useSharedValue<Position>({ x: 0, y: 0 });
+  // True after hover content is committed to DOM. False after snap completes.
+  const hoverReadySV = useSharedValue(false);
+  // Set by SortableContainer.finalizeDrag to defer hover clearing to useLayoutEffect.
+  const hoverClearDeferredRef = useRef(false);
+  // Animated dimensions for hover content during cross-container transfer.
+  // x = width, y = height. {0,0} = no constraint (natural size).
+  const hoverDimsSV = useSharedValue<Position>({ x: 0, y: 0 });
+
+  // ── Dropped items tracking ─────────────────────────────────────────
+  const droppedItemsRef = useRef<Map<string, Set<string>>>(new Map());
+
+  // ── Spatial index + registry ───────────────────────────────────────
+  const {
+    spatialIndexSV,
+    scrollOffsetsSV,
+    registerView,
+    unregisterView,
+    updateMeasurements,
+    updateScrollOffset,
+    updateViewProps,
+    getViewEntry,
+  } = useSpatialIndex();
+
+  // ── Hover content (ref-based to avoid provider re-renders) ─────────
+  // Store content in a ref so changing it doesn't re-render the entire tree.
+  // Only HoverLayer re-renders via the version counter.
+  const hoverContentRef: RefObject<ReactNode> = useRef<ReactNode>(null);
+  const hoverStylesRef: RefObject<FlattenedHoverStyles | null> = useRef<FlattenedHoverStyles | null>(null);
+  const [hoverVersion, setHoverVersion] = useState(0);
+  const setHoverContent = useCallback((content: ReactNode | null) => {
+    hoverContentRef.current = content;
+    if (content === null) {
+      hoverStylesRef.current = null;
+    }
+    setHoverVersion((v) => v + 1);
+  }, []);
+
+  // ── Callback dispatch ──────────────────────────────────────────────
+  const { handleDragStart, handleReceiverChange, handleDragEnd } =
+    useCallbackDispatch({
+      getViewEntry,
+      spatialIndexSV,
+      scrollOffsetsSV,
+      draggedIdSV,
+      receiverIdSV,
+      rejectedReceiverIdSV,
+      dragPhaseSV,
+      hoverPositionSV,
+      grabOffsetSV,
+      startPositionSV,
+      setHoverContent,
+      hoverReadySV,
+      hoverClearDeferredRef,
+      hoverStylesRef,
+      onProviderDragStart,
+      onProviderDrag,
+      onProviderDragEnd,
+      droppedItemsRef,
+    });
+
+  // ── Root view ref ──────────────────────────────────────────────────
+  const rootViewRef = useRef<HostInstance>(null);
+  const setRootViewRef = (ref: HostInstance | null) => {
+    rootViewRef.current = ref;
+  };
+
+  // Measure root view's screen position on layout
+  const handleRootLayout = useCallback(() => {
+    const view = rootViewRef.current;
+    if (view) {
+      (view as unknown as { measure: (cb: (...args: number[]) => void) => void })
+        .measure((_x, _y, _w, _h, pageX, pageY) => {
+          rootOffsetSV.value = { x: pageX, y: pageY };
+        });
+    }
+  }, [rootOffsetSV]);
+
+  // ── Stable context value ───────────────────────────────────────────
+  const contextValue = useMemo<DraxContextValue>(
+    () => ({
+      // SharedValues
+      draggedIdSV,
+      receiverIdSV,
+      dragPhaseSV,
+      hoverPositionSV,
+      dragAbsolutePositionSV,
+      rejectedReceiverIdSV,
+      spatialIndexSV,
+      scrollOffsetsSV,
+      grabOffsetSV,
+      startPositionSV,
+      rootOffsetSV,
+      hoverReadySV,
+      hoverClearDeferredRef,
+      hoverDimsSV,
+
+      // Registry methods
+      registerView,
+      unregisterView,
+      updateMeasurements,
+      updateScrollOffset,
+      updateViewProps,
+      getViewEntry,
+
+      // Callback dispatch
+      handleDragStart,
+      handleReceiverChange,
+      handleDragEnd,
+
+      // Hover content
+      setHoverContent,
+
+      // Dropped items
+      droppedItemsRef,
+
+      // Refs
+      rootViewRef,
+    }),
+    [
+      draggedIdSV,
+      receiverIdSV,
+      dragPhaseSV,
+      hoverPositionSV,
+      dragAbsolutePositionSV,
+      rejectedReceiverIdSV,
+      spatialIndexSV,
+      scrollOffsetsSV,
+      grabOffsetSV,
+      startPositionSV,
+      rootOffsetSV,
+      hoverReadySV,
+      hoverClearDeferredRef,
+      hoverDimsSV,
+      registerView,
+      unregisterView,
+      updateMeasurements,
+      updateScrollOffset,
+      updateViewProps,
+      getViewEntry,
+      handleDragStart,
+      handleReceiverChange,
+      handleDragEnd,
+      setHoverContent,
+      droppedItemsRef,
+    ]
+  );
+
+  return (
+    <DraxContext value={contextValue}>
+      <View style={style} ref={setRootViewRef} onLayout={handleRootLayout} collapsable={false}>
+        {children}
+        {debug && (
+          <DebugOverlay
+            spatialIndexSV={spatialIndexSV}
+            scrollOffsetsSV={scrollOffsetsSV}
+          />
+        )}
+        <HoverLayer
+          hoverContentRef={hoverContentRef}
+          hoverVersion={hoverVersion}
+          hoverPositionSV={hoverPositionSV}
+          dragPhaseSV={dragPhaseSV}
+          receiverIdSV={receiverIdSV}
+          hoverReadySV={hoverReadySV}
+          hoverDimsSV={hoverDimsSV}
+          hoverStylesRef={hoverStylesRef}
+        />
+      </View>
+    </DraxContext>
+  );
+};
+
+const styles = StyleSheet.create({
+  provider: {
+    flex: 1,
+  },
+});

package/src/DraxScrollView.tsx

@@ -0,0 +1,180 @@
+import type { PropsWithChildren, Ref } from 'react';
+import { useRef, type RefObject } from 'react';
+import { ScrollView } from 'react-native';
+import Reanimated from 'react-native-reanimated';
+
+import { DraxSubprovider } from './DraxSubprovider';
+import { DraxView } from './DraxView';
+import { useDraxScrollHandler } from './hooks/useDraxScrollHandler';
+import { useWebScrollFreeze } from './hooks/useWebScrollFreeze';
+import {
+  defaultAutoScrollBackThreshold,
+  defaultAutoScrollForwardThreshold,
+  defaultAutoScrollJumpRatio,
+  defaultScrollEventThrottle,
+} from './params';
+import type {
+  AutoScrollState,
+  DraxMonitorEventData,
+  DraxScrollViewProps,
+} from './types';
+import { AutoScrollDirection } from './types';
+
+export const DraxScrollView = (
+  props: PropsWithChildren<DraxScrollViewProps> & { ref?: Ref<ScrollView> }
+) => {
+  const {
+    ref,
+    children,
+    style,
+    onContentSizeChange: onContentSizeChangeProp,
+    scrollEventThrottle = defaultScrollEventThrottle,
+    autoScrollJumpRatio = defaultAutoScrollJumpRatio,
+    autoScrollBackThreshold = defaultAutoScrollBackThreshold,
+    autoScrollForwardThreshold = defaultAutoScrollForwardThreshold,
+    id: idProp,
+    ...scrollViewProps
+  } = props;
+
+  // Auto-scroll state.
+  const autoScrollStateRef = useRef<AutoScrollState>({
+    x: AutoScrollDirection.None,
+    y: AutoScrollDirection.None,
+  });
+
+  // Handle auto-scrolling on interval (ref-based to avoid circular deps with useDraxScrollHandler).
+  const doScrollRef: RefObject<() => void> = useRef(() => {});
+
+  const {
+    id,
+    containerMeasurementsRef,
+    contentSizeRef,
+    onContentSizeChange,
+    onMeasureContainer,
+    onScroll,
+    scrollRef,
+    scrollPosition,
+    setScrollRefs,
+    startScroll,
+    stopScroll,
+  } = useDraxScrollHandler<ScrollView>({
+    idProp,
+    onContentSizeChangeProp,
+    onScrollProp: props?.onScroll,
+    externalRef: ref,
+    doScroll: doScrollRef,
+  });
+
+  // Assign doScroll implementation now that we have scrollRef, measurements, etc.
+  doScrollRef.current = () => {
+    const scroll = scrollRef.current;
+    const containerMeasurements = containerMeasurementsRef.current;
+    const contentSize = contentSizeRef.current;
+    if (!scroll || !containerMeasurements || !contentSize) return;
+    const autoScrollState = autoScrollStateRef.current;
+    const jump = {
+      x: containerMeasurements.width * autoScrollJumpRatio,
+      y: containerMeasurements.height * autoScrollJumpRatio,
+    };
+    let xNew: number | undefined;
+    let yNew: number | undefined;
+    if (autoScrollState.x === AutoScrollDirection.Forward) {
+      const xMax = contentSize.x - containerMeasurements.width;
+      if (scrollPosition.value.x < xMax) {
+        xNew = Math.min(scrollPosition.value.x + jump.x, xMax);
+      }
+    } else if (autoScrollState.x === AutoScrollDirection.Back) {
+      if (scrollPosition.value.x > 0) {
+        xNew = Math.max(scrollPosition.value.x - jump.x, 0);
+      }
+    }
+    if (autoScrollState.y === AutoScrollDirection.Forward) {
+      const yMax = contentSize.y - containerMeasurements.height;
+      if (scrollPosition.value.y < yMax) {
+        yNew = Math.min(scrollPosition.value.y + jump.y, yMax);
+      }
+    } else if (autoScrollState.y === AutoScrollDirection.Back) {
+      if (scrollPosition.value.y > 0) {
+        yNew = Math.max(scrollPosition.value.y - jump.y, 0);
+      }
+    }
+    if (xNew !== undefined || yNew !== undefined) {
+      // @ts-expect-error Reanimated's type augmentation hides scrollTo, but it exists at runtime
+      scroll.scrollTo({
+        x: xNew ?? scrollPosition.value.x,
+        y: yNew ?? scrollPosition.value.y,
+      });
+      if (
+        'flashScrollIndicators' in scroll &&
+        typeof scroll.flashScrollIndicators === 'function'
+      ) {
+        scroll.flashScrollIndicators();
+      }
+    }
+  };
+
+  const { freeze: freezeScroll, unfreeze: unfreezeScroll } = useWebScrollFreeze(scrollRef);
+
+  // Clear auto-scroll direction and stop the auto-scrolling interval.
+  const resetScroll = () => {
+    const autoScrollState = autoScrollStateRef.current;
+    autoScrollState.x = AutoScrollDirection.None;
+    autoScrollState.y = AutoScrollDirection.None;
+    stopScroll();
+    unfreezeScroll();
+  };
+
+  // Monitor drag-over events to react with auto-scrolling.
+  const onMonitorDragOver = (event: DraxMonitorEventData) => {
+    const { monitorOffsetRatio } = event;
+    const autoScrollState = autoScrollStateRef.current;
+    if (monitorOffsetRatio.x >= autoScrollForwardThreshold) {
+      autoScrollState.x = AutoScrollDirection.Forward;
+    } else if (monitorOffsetRatio.x <= autoScrollBackThreshold) {
+      autoScrollState.x = AutoScrollDirection.Back;
+    } else {
+      autoScrollState.x = AutoScrollDirection.None;
+    }
+    if (monitorOffsetRatio.y >= autoScrollForwardThreshold) {
+      autoScrollState.y = AutoScrollDirection.Forward;
+    } else if (monitorOffsetRatio.y <= autoScrollBackThreshold) {
+      autoScrollState.y = AutoScrollDirection.Back;
+    } else {
+      autoScrollState.y = AutoScrollDirection.None;
+    }
+    if (autoScrollState.x === AutoScrollDirection.None && autoScrollState.y === AutoScrollDirection.None) {
+      stopScroll();
+    } else {
+      startScroll();
+    }
+  };
+
+  const scrollViewParent = { id, viewRef: scrollRef, isScrollContainer: true };
+
+  return (
+    <DraxView
+      id={id}
+      style={style}
+      scrollPosition={scrollPosition}
+      onMeasure={onMeasureContainer}
+      onMonitorDragStart={freezeScroll}
+      onMonitorDragOver={onMonitorDragOver}
+      onMonitorDragExit={resetScroll}
+      onMonitorDragEnd={resetScroll}
+      onMonitorDragDrop={resetScroll}
+    >
+      <DraxSubprovider parent={scrollViewParent}>
+        <Reanimated.ScrollView
+          {...scrollViewProps}
+          // @ts-expect-error — callback ref bridges AnimatedRef + external ref; runtime-compatible
+          ref={setScrollRefs}
+          onContentSizeChange={onContentSizeChange}
+          scrollEventThrottle={scrollEventThrottle}
+          onScroll={onScroll}
+        >
+          {children}
+        </Reanimated.ScrollView>
+      </DraxSubprovider>
+    </DraxView>
+  );
+};

package/src/DraxSubprovider.tsx

@@ -0,0 +1,22 @@
+import type { PropsWithChildren } from 'react';
+import { useMemo } from 'react';
+
+import { DraxContext } from './DraxContext';
+import { useDraxContext } from './hooks';
+import type { DraxSubproviderProps } from './types';
+
+export const DraxSubprovider = ({
+  parent,
+  children,
+}: PropsWithChildren<DraxSubproviderProps>) => {
+  const contextValue = useDraxContext();
+  const subContextValue = useMemo(
+    () => ({ ...contextValue, parent }),
+    [contextValue, parent]
+  );
+  return (
+    <DraxContext value={subContextValue}>
+      {children}
+    </DraxContext>
+  );
+};