react-native-reanimated-dnd 1.0.1

package/lib/hooks/useDroppable.js

@@ -0,0 +1,261 @@
+import { useRef, useEffect, useContext, useCallback, useMemo, } from "react";
+import { StyleSheet } from "react-native";
+import { useAnimatedRef, measure, runOnUI, runOnJS, } from "react-native-reanimated";
+import { SlotsContext, } from "../types/context";
+import { _getUniqueDroppableId } from "../components/Droppable";
+/**
+ * A hook for creating drop zones that can receive draggable items.
+ *
+ * This hook handles the registration of drop zones, collision detection with draggable items,
+ * visual feedback during hover states, and proper positioning of dropped items within the zone.
+ * It integrates seamlessly with the drag-and-drop context to provide a complete solution.
+ *
+ * @template TData - The type of data that can be dropped on this droppable
+ * @param options - Configuration options for the droppable behavior
+ * @returns Object containing view props, active state, and internal references
+ *
+ * @example
+ * Basic drop zone:
+ * ```typescript
+ * import { useDroppable } from './hooks/useDroppable';
+ *
+ * function BasicDropZone() {
+ *   const { viewProps, isActive } = useDroppable({
+ *     onDrop: (data) => {
+ *       console.log('Item dropped:', data);
+ *       // Handle the dropped item
+ *     }
+ *   });
+ *
+ *   return (
+ *     <Animated.View
+ *       {...viewProps}
+ *       style={[
+ *         styles.dropZone,
+ *         viewProps.style, // Important: include the active style
+ *         isActive && styles.highlighted
+ *       ]}
+ *     >
+ *       <Text>Drop items here</Text>
+ *     </Animated.View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Drop zone with custom alignment and capacity:
+ * ```typescript
+ * function TaskColumn() {
+ *   const [tasks, setTasks] = useState<Task[]>([]);
+ *
+ *   const { viewProps, isActive } = useDroppable({
+ *     droppableId: 'in-progress-column',
+ *     onDrop: (task: Task) => {
+ *       setTasks(prev => [...prev, task]);
+ *       updateTaskStatus(task.id, 'in-progress');
+ *     },
+ *     dropAlignment: 'top-center',
+ *     dropOffset: { x: 0, y: 10 },
+ *     capacity: 10, // Max 10 tasks in this column
+ *     activeStyle: {
+ *       backgroundColor: 'rgba(59, 130, 246, 0.1)',
+ *       borderColor: '#3b82f6',
+ *       borderWidth: 2,
+ *       borderStyle: 'dashed'
+ *     }
+ *   });
+ *
+ *   return (
+ *     <Animated.View {...viewProps} style={[styles.column, viewProps.style]}>
+ *       <Text style={styles.columnTitle}>In Progress ({tasks.length}/10)</Text>
+ *       {tasks.map(task => (
+ *         <TaskCard key={task.id} task={task} />
+ *       ))}
+ *       {isActive && (
+ *         <Text style={styles.dropHint}>Release to add task</Text>
+ *       )}
+ *     </Animated.View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Conditional drop zone with validation:
+ * ```typescript
+ * function RestrictedDropZone() {
+ *   const [canAcceptItems, setCanAcceptItems] = useState(true);
+ *
+ *   const { viewProps, isActive } = useDroppable({
+ *     onDrop: (data: FileData) => {
+ *       if (data.type === 'image' && data.size < 5000000) {
+ *         uploadFile(data);
+ *       } else {
+ *         showError('Only images under 5MB allowed');
+ *       }
+ *     },
+ *     dropDisabled: !canAcceptItems,
+ *     onActiveChange: (active) => {
+ *       if (active) {
+ *         setHoverFeedback('Drop your image here');
+ *       } else {
+ *         setHoverFeedback('');
+ *       }
+ *     },
+ *     activeStyle: {
+ *       backgroundColor: canAcceptItems ? 'rgba(34, 197, 94, 0.1)' : 'rgba(239, 68, 68, 0.1)',
+ *       borderColor: canAcceptItems ? '#22c55e' : '#ef4444'
+ *     }
+ *   });
+ *
+ *   return (
+ *     <Animated.View
+ *       {...viewProps}
+ *       style={[
+ *         styles.uploadZone,
+ *         viewProps.style,
+ *         !canAcceptItems && styles.disabled
+ *       ]}
+ *     >
+ *       <Text>
+ *         {canAcceptItems ? 'Drop images here' : 'Upload disabled'}
+ *       </Text>
+ *       {isActive && <Text>Release to upload</Text>}
+ *     </Animated.View>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link DropAlignment} for alignment options
+ * @see {@link DropOffset} for offset configuration
+ * @see {@link UseDroppableOptions} for configuration options
+ * @see {@link UseDroppableReturn} for return value details
+ */
+export const useDroppable = (options) => {
+    const { onDrop, dropDisabled, onActiveChange, dropAlignment, dropOffset, activeStyle, droppableId, capacity, } = options;
+    // Create animated ref first
+    const animatedViewRef = useAnimatedRef();
+    const id = useRef(_getUniqueDroppableId()).current;
+    const stringId = useRef(droppableId || `droppable-${id}`).current;
+    const instanceId = useRef(`droppable-${id}-${Math.random().toString(36).substr(2, 9)}`).current;
+    const { register, unregister, isRegistered, activeHoverSlotId: contextActiveHoverSlotId, registerPositionUpdateListener, unregisterPositionUpdateListener, } = useContext(SlotsContext);
+    const isActive = contextActiveHoverSlotId === id;
+    // Process active style to separate transforms from other styles
+    const { processedActiveStyle, activeTransforms } = useMemo(() => {
+        if (!isActive || !activeStyle) {
+            return { processedActiveStyle: null, activeTransforms: [] };
+        }
+        const flattenedStyle = StyleSheet.flatten(activeStyle);
+        let processedStyle = { ...flattenedStyle };
+        let transforms = [];
+        // Extract and process transforms if present
+        if (flattenedStyle.transform) {
+            if (Array.isArray(flattenedStyle.transform)) {
+                transforms = [...flattenedStyle.transform];
+            }
+            // Remove transform from the main style to avoid conflicts
+            delete processedStyle.transform;
+        }
+        return {
+            processedActiveStyle: processedStyle,
+            activeTransforms: transforms,
+        };
+    }, [isActive, activeStyle]);
+    // Create the final style with transforms properly handled
+    const combinedActiveStyle = useMemo(() => {
+        if (!isActive || !activeStyle) {
+            return undefined;
+        }
+        // If there are no transforms, just return the processed style
+        if (activeTransforms.length === 0) {
+            return processedActiveStyle;
+        }
+        // Add transforms to the style
+        return {
+            ...processedActiveStyle,
+            transform: activeTransforms,
+        };
+    }, [isActive, activeStyle, processedActiveStyle, activeTransforms]);
+    useEffect(() => {
+        onActiveChange === null || onActiveChange === void 0 ? void 0 : onActiveChange(isActive);
+    }, [isActive, onActiveChange]);
+    useEffect(() => {
+        console.log(`Droppable ${id} using string ID: ${stringId}, provided ID: ${droppableId || "none"}`);
+    }, [id, stringId, droppableId]);
+    const updateDroppablePosition = useCallback(() => {
+        runOnUI(() => {
+            "worklet";
+            const measurement = measure(animatedViewRef);
+            if (measurement === null) {
+                return;
+            }
+            if (measurement.width > 0 && measurement.height > 0) {
+                // Ensure valid dimensions before registering
+                runOnJS(register)(id, {
+                    id: droppableId || `droppable-${id}`,
+                    x: measurement.pageX,
+                    y: measurement.pageY,
+                    width: measurement.width,
+                    height: measurement.height,
+                    onDrop,
+                    dropAlignment: dropAlignment || "center",
+                    dropOffset: dropOffset || { x: 0, y: 0 },
+                    capacity,
+                });
+            }
+        })();
+    }, [
+        id,
+        droppableId,
+        onDrop,
+        register,
+        animatedViewRef,
+        dropAlignment,
+        dropOffset,
+        capacity,
+    ]);
+    const handleLayoutHandler = useCallback((_event) => {
+        updateDroppablePosition();
+    }, [updateDroppablePosition]);
+    useEffect(() => {
+        registerPositionUpdateListener(instanceId, updateDroppablePosition);
+        return () => {
+            unregisterPositionUpdateListener(instanceId);
+        };
+    }, [
+        instanceId,
+        registerPositionUpdateListener,
+        unregisterPositionUpdateListener,
+        updateDroppablePosition,
+    ]);
+    useEffect(() => {
+        if (dropDisabled) {
+            unregister(id);
+        }
+        else {
+            // Initial registration or re-registration if it became enabled
+            updateDroppablePosition();
+        }
+        // Not relying on isRegistered here for initial registration to ensure it always attempts
+        // to register if not disabled. The measure call inside updateDroppablePosition is the gatekeeper.
+    }, [
+        dropDisabled,
+        id,
+        unregister, // only unregister is truly a dependency for the disabled case
+        updateDroppablePosition, // for the enabled case
+    ]);
+    useEffect(() => {
+        // Cleanup on unmount
+        return () => {
+            unregister(id);
+        };
+    }, [id, unregister]);
+    return {
+        viewProps: {
+            onLayout: handleLayoutHandler,
+            style: combinedActiveStyle,
+        },
+        isActive,
+        activeStyle,
+        animatedViewRef,
+    };
+};

package/lib/hooks/useSortable.d.ts

@@ -0,0 +1,174 @@
+import { StyleProp, ViewStyle } from "react-native";
+import React from "react";
+import { SharedValue } from "react-native-reanimated";
+export declare enum ScrollDirection {
+    None = "none",
+    Up = "up",
+    Down = "down"
+}
+export declare function clamp(value: number, lowerBound: number, upperBound: number): number;
+export declare function objectMove(object: {
+    [id: string]: number;
+}, from: number, to: number): {
+    [id: string]: number;
+};
+export declare function listToObject<T extends {
+    id: string;
+}>(list: T[]): {
+    [id: string]: number;
+};
+export declare function setPosition(positionY: number, itemsCount: number, positions: SharedValue<{
+    [id: string]: number;
+}>, id: string, itemHeight: number): void;
+export declare function setAutoScroll(positionY: number, lowerBound: number, upperBound: number, scrollThreshold: number, autoScroll: SharedValue<ScrollDirection>): void;
+/**
+ * @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 interface UseSortableOptions<T> {
+    id: string;
+    positions: SharedValue<{
+        [id: string]: number;
+    }>;
+    lowerBound: SharedValue<number>;
+    autoScrollDirection: SharedValue<ScrollDirection>;
+    itemsCount: number;
+    itemHeight: number;
+    containerHeight?: number;
+    onMove?: (id: string, from: number, to: number) => void;
+    onDragStart?: (id: string, position: number) => void;
+    onDrop?: (id: string, position: number) => void;
+    onDragging?: (id: string, overItemId: string | null, yPosition: number) => void;
+    children?: React.ReactNode;
+    handleComponent?: React.ComponentType<any>;
+}
+export interface UseSortableReturn {
+    animatedStyle: StyleProp<ViewStyle>;
+    panGestureHandler: any;
+    isMoving: boolean;
+    hasHandle: boolean;
+}
+/**
+ * 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 declare function useSortable<T>(options: UseSortableOptions<T>): UseSortableReturn;