react-native-reanimated-dnd 1.0.1

package/lib/hooks/useSortable.js

@@ -0,0 +1,361 @@
+import { useState, useRef, useEffect } from "react";
+import React from "react";
+import { runOnJS, runOnUI, useAnimatedGestureHandler, useAnimatedReaction, useAnimatedStyle, useDerivedValue, useSharedValue, withSpring, withTiming, } from "react-native-reanimated";
+export var ScrollDirection;
+(function (ScrollDirection) {
+    ScrollDirection["None"] = "none";
+    ScrollDirection["Up"] = "up";
+    ScrollDirection["Down"] = "down";
+})(ScrollDirection || (ScrollDirection = {}));
+export function clamp(value, lowerBound, upperBound) {
+    "worklet";
+    return Math.max(lowerBound, Math.min(value, upperBound));
+}
+export function objectMove(object, from, to) {
+    "worklet";
+    const newObject = Object.assign({}, object);
+    for (const id in object) {
+        if (object[id] === from) {
+            newObject[id] = to;
+        }
+        if (object[id] === to) {
+            newObject[id] = from;
+        }
+    }
+    return newObject;
+}
+export function listToObject(list) {
+    const values = Object.values(list);
+    const object = {};
+    for (let i = 0; i < values.length; i++) {
+        object[values[i].id] = i;
+    }
+    return object;
+}
+export function setPosition(positionY, itemsCount, positions, id, itemHeight) {
+    "worklet";
+    const newPosition = clamp(Math.floor(positionY / itemHeight), 0, itemsCount - 1);
+    if (newPosition !== positions.value[id]) {
+        positions.value = objectMove(positions.value, positions.value[id], newPosition);
+    }
+}
+export function setAutoScroll(positionY, lowerBound, upperBound, scrollThreshold, autoScroll) {
+    "worklet";
+    if (positionY <= lowerBound + scrollThreshold) {
+        autoScroll.value = ScrollDirection.Up;
+    }
+    else if (positionY >= upperBound - scrollThreshold) {
+        autoScroll.value = ScrollDirection.Down;
+    }
+    else {
+        autoScroll.value = ScrollDirection.None;
+    }
+}
+/**
+ * A hook for creating sortable list items with drag-and-drop reordering capabilities.
+ *
+ * This hook provides the core functionality for individual items within a sortable list,
+ * handling drag gestures, position animations, auto-scrolling, and reordering logic.
+ * It works in conjunction with useSortableList to provide a complete sortable solution.
+ *
+ * @template T - The type of data associated with the sortable item
+ * @param options - Configuration options for the sortable item behavior
+ * @returns Object containing animated styles, gesture handlers, and state for the sortable item
+ *
+ * @example
+ * Basic sortable item:
+ * ```typescript
+ * import { useSortable } from './hooks/useSortable';
+ *
+ * function SortableTaskItem({ task, positions, ...sortableProps }) {
+ *   const { animatedStyle, panGestureHandler, isMoving } = useSortable({
+ *     id: task.id,
+ *     positions,
+ *     ...sortableProps,
+ *     onMove: (id, from, to) => {
+ *       console.log(`Task ${id} moved from ${from} to ${to}`);
+ *       reorderTasks(id, from, to);
+ *     }
+ *   });
+ *
+ *   return (
+ *     <PanGestureHandler {...panGestureHandler}>
+ *       <Animated.View style={[styles.taskItem, animatedStyle]}>
+ *         <Text style={[styles.taskText, isMoving && styles.dragging]}>
+ *           {task.title}
+ *         </Text>
+ *       </Animated.View>
+ *     </PanGestureHandler>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable item with drag handle:
+ * ```typescript
+ * import { useSortable } from './hooks/useSortable';
+ * import { SortableHandle } from './components/SortableItem';
+ *
+ * function TaskWithHandle({ task, ...sortableProps }) {
+ *   const { animatedStyle, panGestureHandler, hasHandle } = useSortable({
+ *     id: task.id,
+ *     ...sortableProps,
+ *     children: (
+ *       <View style={styles.taskContent}>
+ *         <Text>{task.title}</Text>
+ *         <SortableHandle>
+ *           <Icon name="drag-handle" />
+ *         </SortableHandle>
+ *       </View>
+ *     )
+ *   });
+ *
+ *   return (
+ *     <PanGestureHandler {...panGestureHandler}>
+ *       <Animated.View style={[styles.taskItem, animatedStyle]}>
+ *         <View style={styles.taskContent}>
+ *           <Text>{task.title}</Text>
+ *           <SortableHandle>
+ *             <Icon name="drag-handle" />
+ *           </SortableHandle>
+ *         </View>
+ *       </Animated.View>
+ *     </PanGestureHandler>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable item with callbacks and state tracking:
+ * ```typescript
+ * function AdvancedSortableItem({ item, ...sortableProps }) {
+ *   const [isDragging, setIsDragging] = useState(false);
+ *
+ *   const { animatedStyle, panGestureHandler } = useSortable({
+ *     id: item.id,
+ *     ...sortableProps,
+ *     onDragStart: (id, position) => {
+ *       setIsDragging(true);
+ *       analytics.track('drag_start', { itemId: id, position });
+ *     },
+ *     onDrop: (id, position) => {
+ *       setIsDragging(false);
+ *       analytics.track('drag_end', { itemId: id, position });
+ *     },
+ *     onDragging: (id, overItemId, yPosition) => {
+ *       if (overItemId) {
+ *         showDropPreview(overItemId);
+ *       }
+ *     }
+ *   });
+ *
+ *   return (
+ *     <PanGestureHandler {...panGestureHandler}>
+ *       <Animated.View
+ *         style={[
+ *           styles.item,
+ *           animatedStyle,
+ *           isDragging && styles.dragging
+ *         ]}
+ *       >
+ *         <Text>{item.title}</Text>
+ *       </Animated.View>
+ *     </PanGestureHandler>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link UseSortableOptions} for configuration options
+ * @see {@link UseSortableReturn} for return value details
+ * @see {@link useSortableList} for list-level management
+ * @see {@link SortableItem} for component implementation
+ * @see {@link Sortable} for high-level sortable list component
+ */
+export function useSortable(options) {
+    const { id, positions, lowerBound, autoScrollDirection, itemsCount, itemHeight, containerHeight = 500, onMove, onDragStart, onDrop, onDragging, children, handleComponent, } = options;
+    const [isMoving, setIsMoving] = useState(false);
+    const [hasHandle, setHasHandle] = useState(false);
+    const movingSV = useSharedValue(false);
+    const currentOverItemId = useSharedValue(null);
+    const onDraggingLastCallTimestamp = useSharedValue(0);
+    const THROTTLE_INTERVAL = 50; // milliseconds
+    const positionY = useSharedValue(0);
+    const top = useSharedValue(0);
+    const targetLowerBound = useSharedValue(0);
+    useEffect(() => {
+        runOnUI(() => {
+            "worklet";
+            const initialTopVal = positions.value[id] * itemHeight;
+            const initialLowerBoundVal = lowerBound.value;
+            top.value = initialTopVal;
+            positionY.value = initialTopVal;
+            targetLowerBound.value = initialLowerBoundVal;
+        })();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const calculatedContainerHeight = useRef(containerHeight).current;
+    const upperBound = useDerivedValue(() => lowerBound.value + calculatedContainerHeight);
+    useEffect(() => {
+        if (!children || !handleComponent) {
+            setHasHandle(false);
+            return;
+        }
+        const checkForHandle = (child) => {
+            if (React.isValidElement(child)) {
+                if (child.type === handleComponent) {
+                    return true;
+                }
+                if (child.props && child.props.children) {
+                    if (React.Children.toArray(child.props.children).some(checkForHandle)) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        };
+        setHasHandle(React.Children.toArray(children).some(checkForHandle));
+    }, [children, handleComponent]);
+    useAnimatedReaction(() => positionY.value, (currentY, previousY) => {
+        if (currentY === null || !movingSV.value) {
+            return;
+        }
+        if (previousY !== null && currentY === previousY) {
+            return;
+        }
+        // Calculate target discrete position
+        const clampedPosition = Math.min(Math.max(0, Math.ceil(currentY / itemHeight)), itemsCount - 1);
+        // Determine overItemId based on the current state of positions.value
+        // BEFORE setPosition modifies it for this specific currentY
+        let newOverItemId = null;
+        for (const [itemIdIter, itemPosIter] of Object.entries(positions.value)) {
+            if (itemPosIter === clampedPosition && itemIdIter !== id) {
+                newOverItemId = itemIdIter;
+                break;
+            }
+        }
+        if (currentOverItemId.value !== newOverItemId) {
+            currentOverItemId.value = newOverItemId;
+        }
+        if (onDragging) {
+            const now = Date.now();
+            if (now - onDraggingLastCallTimestamp.value > THROTTLE_INTERVAL) {
+                runOnJS(onDragging)(id, newOverItemId, Math.round(currentY));
+                onDraggingLastCallTimestamp.value = now;
+            }
+        }
+        // Update visual position and logical positions
+        top.value = currentY;
+        setPosition(currentY, itemsCount, positions, id, itemHeight);
+        setAutoScroll(currentY, lowerBound.value, upperBound.value, itemHeight, autoScrollDirection);
+    }, [
+        movingSV,
+        itemHeight,
+        itemsCount,
+        positions,
+        id,
+        onDragging,
+        lowerBound,
+        upperBound,
+        autoScrollDirection,
+        currentOverItemId,
+        top,
+        onDraggingLastCallTimestamp,
+    ]);
+    useAnimatedReaction(() => positions.value[id], (currentPosition, previousPosition) => {
+        if (currentPosition !== null &&
+            previousPosition !== null &&
+            currentPosition !== previousPosition) {
+            if (!movingSV.value) {
+                top.value = withSpring(currentPosition * itemHeight);
+                if (onMove) {
+                    runOnJS(onMove)(id, previousPosition, currentPosition);
+                }
+            }
+        }
+    }, [movingSV]);
+    useAnimatedReaction(() => autoScrollDirection.value, (scrollDirection, previousValue) => {
+        if (scrollDirection !== null &&
+            previousValue !== null &&
+            scrollDirection !== previousValue) {
+            switch (scrollDirection) {
+                case ScrollDirection.Up: {
+                    targetLowerBound.value = lowerBound.value;
+                    targetLowerBound.value = withTiming(0, { duration: 1500 });
+                    break;
+                }
+                case ScrollDirection.Down: {
+                    const contentHeight = itemsCount * itemHeight;
+                    const maxScroll = contentHeight - calculatedContainerHeight;
+                    targetLowerBound.value = lowerBound.value;
+                    targetLowerBound.value = withTiming(maxScroll, { duration: 1500 });
+                    break;
+                }
+                case ScrollDirection.None: {
+                    targetLowerBound.value = lowerBound.value;
+                    break;
+                }
+            }
+        }
+    });
+    useAnimatedReaction(() => targetLowerBound.value, (targetLowerBoundValue, previousValue) => {
+        if (targetLowerBoundValue !== null &&
+            previousValue !== null &&
+            targetLowerBoundValue !== previousValue) {
+            if (movingSV.value) {
+                lowerBound.value = targetLowerBoundValue;
+            }
+        }
+    }, [movingSV]);
+    const panGestureHandler = useAnimatedGestureHandler({
+        onStart(event, ctx) {
+            "worklet";
+            ctx.initialItemContentY = positions.value[id] * itemHeight;
+            ctx.initialFingerAbsoluteY = event.absoluteY;
+            ctx.initialLowerBound = lowerBound.value;
+            positionY.value = ctx.initialItemContentY;
+            movingSV.value = true;
+            runOnJS(setIsMoving)(true);
+            if (onDragStart) {
+                runOnJS(onDragStart)(id, positions.value[id]);
+            }
+        },
+        onActive(event, ctx) {
+            "worklet";
+            const fingerDyScreen = event.absoluteY - ctx.initialFingerAbsoluteY;
+            const scrollDeltaSinceStart = lowerBound.value - ctx.initialLowerBound;
+            positionY.value =
+                ctx.initialItemContentY + fingerDyScreen + scrollDeltaSinceStart;
+        },
+        onFinish() {
+            "worklet";
+            const finishPosition = positions.value[id] * itemHeight;
+            top.value = withTiming(finishPosition);
+            movingSV.value = false;
+            runOnJS(setIsMoving)(false);
+            if (onDrop) {
+                runOnJS(onDrop)(id, positions.value[id]);
+            }
+            currentOverItemId.value = null;
+        },
+    });
+    const animatedStyle = useAnimatedStyle(() => {
+        "worklet";
+        return {
+            position: "absolute",
+            left: 0,
+            right: 0,
+            top: top.value,
+            zIndex: movingSV.value ? 1 : 0,
+            backgroundColor: "#000000",
+            shadowColor: "black",
+            shadowOpacity: withSpring(movingSV.value ? 0.2 : 0),
+            shadowRadius: 10,
+        };
+    }, [movingSV]);
+    return {
+        animatedStyle,
+        panGestureHandler,
+        isMoving,
+        hasHandle,
+    };
+}

package/lib/hooks/useSortableList.d.ts

@@ -0,0 +1,182 @@
+import { DropProviderRef } from "../types/context";
+export interface UseSortableListOptions<TData> {
+    data: TData[];
+    itemHeight: number;
+    itemKeyExtractor?: (item: TData, index: number) => string;
+}
+export interface UseSortableListReturn<TData> {
+    positions: any;
+    scrollY: any;
+    autoScroll: any;
+    scrollViewRef: any;
+    dropProviderRef: React.RefObject<DropProviderRef>;
+    handleScroll: any;
+    handleScrollEnd: () => void;
+    contentHeight: number;
+    getItemProps: (item: TData, index: number) => {
+        id: string;
+        positions: any;
+        lowerBound: any;
+        autoScrollDirection: any;
+        itemsCount: number;
+        itemHeight: number;
+    };
+}
+/**
+ * A hook for managing sortable lists with drag-and-drop reordering capabilities.
+ *
+ * This hook provides the foundational state management and utilities needed to create
+ * sortable lists. It handles position tracking, scroll synchronization, auto-scrolling,
+ * and provides helper functions for individual sortable items.
+ *
+ * @template TData - The type of data items in the sortable list (must extend `{ id: string }`)
+ * @param options - Configuration options for the sortable list
+ * @returns Object containing shared values, refs, handlers, and utilities for the sortable list
+ *
+ * @example
+ * Basic sortable list setup:
+ * ```typescript
+ * import { useSortableList } from './hooks/useSortableList';
+ * import { SortableItem } from './components/SortableItem';
+ *
+ * interface Task {
+ *   id: string;
+ *   title: string;
+ *   completed: boolean;
+ * }
+ *
+ * function TaskList() {
+ *   const [tasks, setTasks] = useState<Task[]>([
+ *     { id: '1', title: 'Learn React Native', completed: false },
+ *     { id: '2', title: 'Build an app', completed: false },
+ *     { id: '3', title: 'Deploy to store', completed: false }
+ *   ]);
+ *
+ *   const {
+ *     scrollViewRef,
+ *     dropProviderRef,
+ *     handleScroll,
+ *     handleScrollEnd,
+ *     contentHeight,
+ *     getItemProps,
+ *   } = useSortableList({
+ *     data: tasks,
+ *     itemHeight: 60,
+ *   });
+ *
+ *   return (
+ *     <GestureHandlerRootView style={styles.container}>
+ *       <DropProvider ref={dropProviderRef}>
+ *         <Animated.ScrollView
+ *           ref={scrollViewRef}
+ *           onScroll={handleScroll}
+ *           scrollEventThrottle={16}
+ *           style={styles.scrollView}
+ *           contentContainerStyle={{ height: contentHeight }}
+ *           onScrollEndDrag={handleScrollEnd}
+ *           onMomentumScrollEnd={handleScrollEnd}
+ *         >
+ *           {tasks.map((task, index) => {
+ *             const itemProps = getItemProps(task, index);
+ *             return (
+ *               <SortableItem key={task.id} {...itemProps}>
+ *                 <View style={styles.taskItem}>
+ *                   <Text>{task.title}</Text>
+ *                 </View>
+ *               </SortableItem>
+ *             );
+ *           })}
+ *         </Animated.ScrollView>
+ *       </DropProvider>
+ *     </GestureHandlerRootView>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with custom key extractor:
+ * ```typescript
+ * interface CustomItem {
+ *   uuid: string;
+ *   name: string;
+ *   order: number;
+ * }
+ *
+ * function CustomSortableList() {
+ *   const [items, setItems] = useState<CustomItem[]>(data);
+ *
+ *   const sortableListProps = useSortableList({
+ *     data: items,
+ *     itemHeight: 50,
+ *     itemKeyExtractor: (item) => item.uuid, // Use uuid instead of id
+ *   });
+ *
+ *   const { getItemProps, ...otherProps } = sortableListProps;
+ *
+ *   return (
+ *     <SortableListContainer {...otherProps}>
+ *       {items.map((item, index) => {
+ *         const itemProps = getItemProps(item, index);
+ *         return (
+ *           <SortableItem key={item.uuid} {...itemProps}>
+ *             <View style={styles.customItem}>
+ *               <Text>{item.name}</Text>
+ *               <Text>Order: {item.order}</Text>
+ *             </View>
+ *           </SortableItem>
+ *         );
+ *       })}
+ *     </SortableListContainer>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with reordering logic:
+ * ```typescript
+ * function ReorderableTaskList() {
+ *   const [tasks, setTasks] = useState(initialTasks);
+ *
+ *   const handleReorder = useCallback((id: string, from: number, to: number) => {
+ *     setTasks(prevTasks => {
+ *       const newTasks = [...prevTasks];
+ *       const [movedTask] = newTasks.splice(from, 1);
+ *       newTasks.splice(to, 0, movedTask);
+ *       return newTasks;
+ *     });
+ *   }, []);
+ *
+ *   const sortableProps = useSortableList({
+ *     data: tasks,
+ *     itemHeight: 80,
+ *   });
+ *
+ *   return (
+ *     <SortableListContainer {...sortableProps}>
+ *       {tasks.map((task, index) => {
+ *         const itemProps = sortableProps.getItemProps(task, index);
+ *         return (
+ *           <SortableItem
+ *             key={task.id}
+ *             {...itemProps}
+ *             onMove={handleReorder}
+ *           >
+ *             <TaskCard task={task} />
+ *           </SortableItem>
+ *         );
+ *       })}
+ *     </SortableListContainer>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link UseSortableListOptions} for configuration options
+ * @see {@link UseSortableListReturn} for return value details
+ * @see {@link useSortable} for individual item management
+ * @see {@link SortableItem} for component implementation
+ * @see {@link Sortable} for high-level sortable list component
+ * @see {@link DropProvider} for drag-and-drop context
+ */
+export declare function useSortableList<TData extends {
+    id: string;
+}>(options: UseSortableListOptions<TData>): UseSortableListReturn<TData>;