react-native-reanimated-dnd 1.0.1

package/lib/components/Droppable.js

@@ -0,0 +1,284 @@
+// Node Modules
+import React from "react";
+import Animated from "react-native-reanimated";
+import { useDroppable } from "../hooks/useDroppable";
+let _nextDroppableId = 1;
+export const _getUniqueDroppableId = () => {
+    return _nextDroppableId++;
+};
+/**
+ * A component that creates drop zones for receiving draggable items.
+ *
+ * The Droppable component provides visual feedback when draggable items hover over it
+ * and handles the drop logic when items are released. It integrates seamlessly with
+ * the drag-and-drop context to provide collision detection and proper positioning
+ * of dropped items.
+ *
+ * @template TData - The type of data that can be dropped on this droppable
+ * @param props - Configuration props for the droppable component
+ *
+ * @example
+ * Basic drop zone:
+ * ```typescript
+ * import { Droppable } from './components/Droppable';
+ *
+ * function BasicDropZone() {
+ *   const handleDrop = (data) => {
+ *     console.log('Item dropped:', data);
+ *     // Handle the dropped item
+ *     addItemToList(data);
+ *   };
+ *
+ *   return (
+ *     <Droppable onDrop={handleDrop}>
+ *       <View style={styles.dropZone}>
+ *         <Text>Drop items here</Text>
+ *       </View>
+ *     </Droppable>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Drop zone with visual feedback:
+ * ```typescript
+ * function VisualDropZone() {
+ *   const [isHovered, setIsHovered] = useState(false);
+ *
+ *   return (
+ *     <Droppable
+ *       onDrop={(data) => {
+ *         console.log('Dropped:', data.name);
+ *         processDroppedItem(data);
+ *       }}
+ *       onActiveChange={setIsHovered}
+ *       activeStyle={{
+ *         backgroundColor: 'rgba(0, 255, 0, 0.2)',
+ *         borderColor: '#00ff00',
+ *         borderWidth: 2,
+ *         transform: [{ scale: 1.05 }]
+ *       }}
+ *       style={styles.dropZone}
+ *     >
+ *       <View style={[
+ *         styles.dropContent,
+ *         isHovered && styles.hoveredContent
+ *       ]}>
+ *         <Icon
+ *           name="cloud-upload"
+ *           size={32}
+ *           color={isHovered ? '#00ff00' : '#666'}
+ *         />
+ *         <Text style={styles.dropText}>
+ *           {isHovered ? 'Release to drop' : 'Drag files here'}
+ *         </Text>
+ *       </View>
+ *     </Droppable>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Drop zone with custom alignment and capacity:
+ * ```typescript
+ * function TaskColumn() {
+ *   const [tasks, setTasks] = useState([]);
+ *   const maxTasks = 5;
+ *
+ *   return (
+ *     <Droppable
+ *       droppableId="todo-column"
+ *       onDrop={(task) => {
+ *         if (tasks.length < maxTasks) {
+ *           setTasks(prev => [...prev, task]);
+ *           updateTaskStatus(task.id, 'todo');
+ *         }
+ *       }}
+ *       dropAlignment="top-center"
+ *       dropOffset={{ x: 0, y: 10 }}
+ *       capacity={maxTasks}
+ *       activeStyle={{
+ *         backgroundColor: 'rgba(59, 130, 246, 0.1)',
+ *         borderColor: '#3b82f6',
+ *         borderWidth: 2,
+ *         borderStyle: 'dashed'
+ *       }}
+ *       style={styles.column}
+ *     >
+ *       <Text style={styles.columnTitle}>
+ *         To Do ({tasks.length}/{maxTasks})
+ *       </Text>
+ *
+ *       {tasks.map(task => (
+ *         <TaskCard key={task.id} task={task} />
+ *       ))}
+ *
+ *       {tasks.length === 0 && (
+ *         <Text style={styles.emptyText}>
+ *           Drop tasks here
+ *         </Text>
+ *       )}
+ *     </Droppable>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Conditional drop zone with validation:
+ * ```typescript
+ * function RestrictedDropZone() {
+ *   const [canAcceptFiles, setCanAcceptFiles] = useState(true);
+ *   const [uploadProgress, setUploadProgress] = useState(0);
+ *
+ *   const handleDrop = (fileData) => {
+ *     // Validate file type and size
+ *     if (fileData.type !== 'image') {
+ *       showError('Only image files are allowed');
+ *       return;
+ *     }
+ *
+ *     if (fileData.size > 5000000) { // 5MB limit
+ *       showError('File size must be under 5MB');
+ *       return;
+ *     }
+ *
+ *     // Start upload
+ *     setCanAcceptFiles(false);
+ *     uploadFile(fileData, setUploadProgress)
+ *       .then(() => {
+ *         showSuccess('File uploaded successfully');
+ *         setCanAcceptFiles(true);
+ *         setUploadProgress(0);
+ *       })
+ *       .catch(() => {
+ *         showError('Upload failed');
+ *         setCanAcceptFiles(true);
+ *         setUploadProgress(0);
+ *       });
+ *   };
+ *
+ *   return (
+ *     <Droppable
+ *       onDrop={handleDrop}
+ *       dropDisabled={!canAcceptFiles}
+ *       onActiveChange={(active) => {
+ *         if (active && !canAcceptFiles) {
+ *           showTooltip('Upload in progress...');
+ *         }
+ *       }}
+ *       activeStyle={{
+ *         backgroundColor: canAcceptFiles
+ *           ? 'rgba(34, 197, 94, 0.1)'
+ *           : 'rgba(239, 68, 68, 0.1)',
+ *         borderColor: canAcceptFiles ? '#22c55e' : '#ef4444'
+ *       }}
+ *       style={[
+ *         styles.uploadZone,
+ *         !canAcceptFiles && styles.disabled
+ *       ]}
+ *     >
+ *       <View style={styles.uploadContent}>
+ *         {uploadProgress > 0 ? (
+ *           <>
+ *             <ProgressBar progress={uploadProgress} />
+ *             <Text>Uploading... {Math.round(uploadProgress * 100)}%</Text>
+ *           </>
+ *         ) : (
+ *           <>
+ *             <Icon
+ *               name="image"
+ *               size={48}
+ *               color={canAcceptFiles ? '#22c55e' : '#ef4444'}
+ *             />
+ *             <Text style={styles.uploadText}>
+ *               {canAcceptFiles
+ *                 ? 'Drop images here (max 5MB)'
+ *                 : 'Upload in progress...'}
+ *             </Text>
+ *           </>
+ *         )}
+ *       </View>
+ *     </Droppable>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Multiple drop zones with different behaviors:
+ * ```typescript
+ * function MultiDropZoneExample() {
+ *   const [items, setItems] = useState([]);
+ *   const [trash, setTrash] = useState([]);
+ *
+ *   return (
+ *     <DropProvider>
+ *       <View style={styles.container}>
+ *         {/* Source items *\/}
+ *         {items.map(item => (
+ *           <Draggable key={item.id} data={item}>
+ *             <ItemCard item={item} />
+ *           </Draggable>
+ *         ))}
+ *
+ *         {/* Archive drop zone *\/}
+ *         <Droppable
+ *           droppableId="archive"
+ *           onDrop={(item) => {
+ *             archiveItem(item.id);
+ *             setItems(prev => prev.filter(i => i.id !== item.id));
+ *           }}
+ *           dropAlignment="center"
+ *           activeStyle={styles.archiveActive}
+ *         >
+ *           <View style={styles.archiveZone}>
+ *             <Icon name="archive" size={24} />
+ *             <Text>Archive</Text>
+ *           </View>
+ *         </Droppable>
+ *
+ *         {/* Trash drop zone *\/}
+ *         <Droppable
+ *           droppableId="trash"
+ *           onDrop={(item) => {
+ *             setTrash(prev => [...prev, item]);
+ *             setItems(prev => prev.filter(i => i.id !== item.id));
+ *           }}
+ *           dropAlignment="center"
+ *           activeStyle={styles.trashActive}
+ *           capacity={10} // Max 10 items in trash
+ *         >
+ *           <View style={styles.trashZone}>
+ *             <Icon name="trash" size={24} />
+ *             <Text>Trash ({trash.length}/10)</Text>
+ *           </View>
+ *         </Droppable>
+ *       </View>
+ *     </DropProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useDroppable} for the underlying hook
+ * @see {@link Draggable} for draggable components
+ * @see {@link DropAlignment} for alignment options
+ * @see {@link DropOffset} for offset configuration
+ * @see {@link UseDroppableOptions} for configuration options
+ * @see {@link UseDroppableReturn} for hook return details
+ * @see {@link DropProvider} for drag-and-drop context setup
+ */
+export const Droppable = ({ onDrop, dropDisabled, onActiveChange, dropAlignment, dropOffset, activeStyle, droppableId, capacity, style, children, }) => {
+    const { viewProps, animatedViewRef } = useDroppable({
+        onDrop,
+        dropDisabled,
+        onActiveChange,
+        dropAlignment,
+        dropOffset,
+        activeStyle,
+        droppableId,
+        capacity,
+    });
+    // The style is now fully handled in the hook and returned via viewProps.style
+    return (<Animated.View ref={animatedViewRef} {...viewProps} style={[style, viewProps.style]} collapsable={false}>
+      {children}
+    </Animated.View>);
+};

package/lib/components/Sortable.d.ts

@@ -0,0 +1,184 @@
+import React from "react";
+import { SortableProps } from "../types/sortable";
+/**
+ * A high-level component for creating sortable lists with smooth reordering animations.
+ *
+ * The Sortable component provides a complete solution for sortable lists, handling
+ * all the complex state management, gesture handling, and animations internally.
+ * It renders a scrollable list where items can be dragged to reorder them with
+ * smooth animations and auto-scrolling support.
+ *
+ * @template TData - The type of data items in the list (must extend `{ id: string }`)
+ * @param props - Configuration props for the sortable list
+ *
+ * @example
+ * Basic sortable list:
+ * ```typescript
+ * import { Sortable } from './components/Sortable';
+ *
+ * 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 renderTask = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.taskItem}>
+ *         <Text>{item.title}</Text>
+ *         <Text>{item.completed ? '✓' : '○'}</Text>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={tasks}
+ *       renderItem={renderTask}
+ *       itemHeight={60}
+ *       style={styles.list}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with custom styling and callbacks:
+ * ```typescript
+ * function AdvancedTaskList() {
+ *   const [tasks, setTasks] = useState(initialTasks);
+ *
+ *   const renderTask = ({ item, id, positions, ...props }) => (
+ *     <SortableItem
+ *       key={id}
+ *       id={id}
+ *       positions={positions}
+ *       {...props}
+ *       onMove={(itemId, from, to) => {
+ *         // Update data when items are reordered
+ *         const newTasks = [...tasks];
+ *         const [movedTask] = newTasks.splice(from, 1);
+ *         newTasks.splice(to, 0, movedTask);
+ *         setTasks(newTasks);
+ *
+ *         // Analytics
+ *         analytics.track('task_reordered', { taskId: itemId, from, to });
+ *       }}
+ *       onDragStart={(itemId) => {
+ *         hapticFeedback();
+ *         setDraggingTask(itemId);
+ *       }}
+ *       onDrop={(itemId) => {
+ *         setDraggingTask(null);
+ *       }}
+ *     >
+ *       <Animated.View style={[styles.taskItem, item.priority === 'high' && styles.highPriority]}>
+ *         <Text style={styles.taskTitle}>{item.title}</Text>
+ *         <Text style={styles.taskDue}>{item.dueDate}</Text>
+ *         <View style={styles.dragHandle}>
+ *           <Icon name="drag-handle" size={20} color="#666" />
+ *         </View>
+ *       </Animated.View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <View style={styles.container}>
+ *       <Text style={styles.header}>My Tasks ({tasks.length})</Text>
+ *       <Sortable
+ *         data={tasks}
+ *         renderItem={renderTask}
+ *         itemHeight={80}
+ *         style={styles.sortableList}
+ *         contentContainerStyle={styles.listContent}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with drag handles:
+ * ```typescript
+ * function SortableWithHandles() {
+ *   const [items, setItems] = useState(data);
+ *
+ *   const renderItem = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.itemContainer}>
+ *         <View style={styles.itemContent}>
+ *           <Text style={styles.itemTitle}>{item.title}</Text>
+ *           <Text style={styles.itemSubtitle}>{item.subtitle}</Text>
+ *         </View>
+ *
+ *         {/* Only this handle area can initiate dragging *\/}
+ *         <SortableItem.Handle style={styles.dragHandle}>
+ *           <View style={styles.handleIcon}>
+ *             <View style={styles.handleDot} />
+ *             <View style={styles.handleDot} />
+ *             <View style={styles.handleDot} />
+ *           </View>
+ *         </SortableItem.Handle>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={items}
+ *       renderItem={renderItem}
+ *       itemHeight={70}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @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 renderItem = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.customItem}>
+ *         <Text>{item.name}</Text>
+ *         <Text>Order: {item.order}</Text>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={items}
+ *       renderItem={renderItem}
+ *       itemHeight={50}
+ *       itemKeyExtractor={(item) => item.uuid} // Use uuid instead of id
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link SortableItem} for individual item component
+ * @see {@link useSortableList} for the underlying hook
+ * @see {@link SortableRenderItemProps} for render function props
+ * @see {@link UseSortableListOptions} for configuration options
+ * @see {@link UseSortableListReturn} for hook return details
+ * @see {@link DropProvider} for drag-and-drop context
+ */
+export declare function Sortable<TData extends {
+    id: string;
+}>({ data, renderItem, itemHeight, style, contentContainerStyle, itemKeyExtractor, }: SortableProps<TData>): React.JSX.Element;

package/lib/components/Sortable.js

@@ -0,0 +1,225 @@
+import React from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { GestureHandlerRootView, ScrollView, } from "react-native-gesture-handler";
+import { DropProvider } from "../context/DropContext";
+import { useSortableList, } from "../hooks/useSortableList";
+// Create an animated version of the ScrollView
+const AnimatedScrollView = Animated.createAnimatedComponent(ScrollView);
+/**
+ * A high-level component for creating sortable lists with smooth reordering animations.
+ *
+ * The Sortable component provides a complete solution for sortable lists, handling
+ * all the complex state management, gesture handling, and animations internally.
+ * It renders a scrollable list where items can be dragged to reorder them with
+ * smooth animations and auto-scrolling support.
+ *
+ * @template TData - The type of data items in the list (must extend `{ id: string }`)
+ * @param props - Configuration props for the sortable list
+ *
+ * @example
+ * Basic sortable list:
+ * ```typescript
+ * import { Sortable } from './components/Sortable';
+ *
+ * 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 renderTask = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.taskItem}>
+ *         <Text>{item.title}</Text>
+ *         <Text>{item.completed ? '✓' : '○'}</Text>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={tasks}
+ *       renderItem={renderTask}
+ *       itemHeight={60}
+ *       style={styles.list}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with custom styling and callbacks:
+ * ```typescript
+ * function AdvancedTaskList() {
+ *   const [tasks, setTasks] = useState(initialTasks);
+ *
+ *   const renderTask = ({ item, id, positions, ...props }) => (
+ *     <SortableItem
+ *       key={id}
+ *       id={id}
+ *       positions={positions}
+ *       {...props}
+ *       onMove={(itemId, from, to) => {
+ *         // Update data when items are reordered
+ *         const newTasks = [...tasks];
+ *         const [movedTask] = newTasks.splice(from, 1);
+ *         newTasks.splice(to, 0, movedTask);
+ *         setTasks(newTasks);
+ *
+ *         // Analytics
+ *         analytics.track('task_reordered', { taskId: itemId, from, to });
+ *       }}
+ *       onDragStart={(itemId) => {
+ *         hapticFeedback();
+ *         setDraggingTask(itemId);
+ *       }}
+ *       onDrop={(itemId) => {
+ *         setDraggingTask(null);
+ *       }}
+ *     >
+ *       <Animated.View style={[styles.taskItem, item.priority === 'high' && styles.highPriority]}>
+ *         <Text style={styles.taskTitle}>{item.title}</Text>
+ *         <Text style={styles.taskDue}>{item.dueDate}</Text>
+ *         <View style={styles.dragHandle}>
+ *           <Icon name="drag-handle" size={20} color="#666" />
+ *         </View>
+ *       </Animated.View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <View style={styles.container}>
+ *       <Text style={styles.header}>My Tasks ({tasks.length})</Text>
+ *       <Sortable
+ *         data={tasks}
+ *         renderItem={renderTask}
+ *         itemHeight={80}
+ *         style={styles.sortableList}
+ *         contentContainerStyle={styles.listContent}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable list with drag handles:
+ * ```typescript
+ * function SortableWithHandles() {
+ *   const [items, setItems] = useState(data);
+ *
+ *   const renderItem = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.itemContainer}>
+ *         <View style={styles.itemContent}>
+ *           <Text style={styles.itemTitle}>{item.title}</Text>
+ *           <Text style={styles.itemSubtitle}>{item.subtitle}</Text>
+ *         </View>
+ *
+ *         {/* Only this handle area can initiate dragging *\/}
+ *         <SortableItem.Handle style={styles.dragHandle}>
+ *           <View style={styles.handleIcon}>
+ *             <View style={styles.handleDot} />
+ *             <View style={styles.handleDot} />
+ *             <View style={styles.handleDot} />
+ *           </View>
+ *         </SortableItem.Handle>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={items}
+ *       renderItem={renderItem}
+ *       itemHeight={70}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @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 renderItem = ({ item, id, positions, ...props }) => (
+ *     <SortableItem key={id} id={id} positions={positions} {...props}>
+ *       <View style={styles.customItem}>
+ *         <Text>{item.name}</Text>
+ *         <Text>Order: {item.order}</Text>
+ *       </View>
+ *     </SortableItem>
+ *   );
+ *
+ *   return (
+ *     <Sortable
+ *       data={items}
+ *       renderItem={renderItem}
+ *       itemHeight={50}
+ *       itemKeyExtractor={(item) => item.uuid} // Use uuid instead of id
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link SortableItem} for individual item component
+ * @see {@link useSortableList} for the underlying hook
+ * @see {@link SortableRenderItemProps} for render function props
+ * @see {@link UseSortableListOptions} for configuration options
+ * @see {@link UseSortableListReturn} for hook return details
+ * @see {@link DropProvider} for drag-and-drop context
+ */
+export function Sortable({ data, renderItem, itemHeight, style, contentContainerStyle, itemKeyExtractor = (item) => item.id, }) {
+    const sortableOptions = {
+        data,
+        itemHeight,
+        itemKeyExtractor,
+    };
+    const { scrollViewRef, dropProviderRef, handleScroll, handleScrollEnd, contentHeight, getItemProps, } = useSortableList(sortableOptions);
+    return (<GestureHandlerRootView style={styles.flex}>
+      <DropProvider ref={dropProviderRef}>
+        <AnimatedScrollView ref={scrollViewRef} onScroll={handleScroll} scrollEventThrottle={16} style={[styles.scrollView, style]} contentContainerStyle={[
+            { height: contentHeight },
+            contentContainerStyle,
+        ]} onScrollEndDrag={handleScrollEnd} onMomentumScrollEnd={handleScrollEnd} simultaneousHandlers={dropProviderRef}>
+          {data.map((item, index) => {
+            // Get the item props from our hook
+            const itemProps = getItemProps(item, index);
+            // Create the complete props with the item and index
+            const sortableItemProps = {
+                item,
+                index,
+                ...itemProps,
+            };
+            return renderItem(sortableItemProps);
+        })}
+        </AnimatedScrollView>
+      </DropProvider>
+    </GestureHandlerRootView>);
+}
+const styles = StyleSheet.create({
+    flex: {
+        flex: 1,
+    },
+    scrollView: {
+        flex: 1,
+        position: "relative",
+        backgroundColor: "white",
+    },
+});