react-native-reanimated-dnd 1.0.1

package/lib/hooks/useSortableList.js

@@ -0,0 +1,211 @@
+import { useRef, useCallback } from "react";
+import { scrollTo, useAnimatedReaction, useAnimatedRef, useAnimatedScrollHandler, useSharedValue, } from "react-native-reanimated";
+import { listToObject } from "../components/sortableUtils";
+import { ScrollDirection } from "../types/sortable";
+/**
+ * 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 function useSortableList(options) {
+    const { data, itemHeight, itemKeyExtractor = (item) => item.id } = options;
+    // Set up shared values
+    const positions = useSharedValue(listToObject(data));
+    const scrollY = useSharedValue(0);
+    const autoScroll = useSharedValue(ScrollDirection.None);
+    const scrollViewRef = useAnimatedRef();
+    const dropProviderRef = useRef(null);
+    // Scrolling synchronization
+    useAnimatedReaction(() => scrollY.value, (scrolling) => {
+        scrollTo(scrollViewRef, 0, scrolling, false);
+    });
+    // Handle scroll events
+    const handleScroll = useAnimatedScrollHandler((event) => {
+        scrollY.value = event.contentOffset.y;
+    });
+    const handleScrollEnd = useCallback(() => {
+        let localScrollTimeout = null;
+        if (localScrollTimeout) {
+            clearTimeout(localScrollTimeout);
+        }
+        localScrollTimeout = setTimeout(() => {
+            var _a;
+            (_a = dropProviderRef.current) === null || _a === void 0 ? void 0 : _a.requestPositionUpdate();
+        }, 50);
+    }, []);
+    // Calculate content height
+    const contentHeight = data.length * itemHeight;
+    // Helper to get props for each sortable item
+    const getItemProps = useCallback((item, index) => {
+        const id = itemKeyExtractor(item, index);
+        return {
+            id,
+            positions,
+            lowerBound: scrollY,
+            autoScrollDirection: autoScroll,
+            itemsCount: data.length,
+            itemHeight,
+        };
+    }, [data.length, itemHeight, itemKeyExtractor, positions, scrollY, autoScroll]);
+    return {
+        positions,
+        scrollY,
+        autoScroll,
+        scrollViewRef,
+        dropProviderRef,
+        handleScroll,
+        handleScrollEnd,
+        contentHeight,
+        getItemProps,
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+export { Draggable } from "./components/Draggable";
+export { Droppable } from "./components/Droppable";
+export { Sortable } from "./components/Sortable";
+export { SortableItem } from "./components/SortableItem";
+export { DropProvider } from "./context/DropContext";
+export * from "./types";
+export { listToObject, setAutoScroll, setPosition, clamp, objectMove, ScrollDirection, } from "./components/sortableUtils";
+export { useDraggable } from "./hooks/useDraggable";
+export { useDroppable } from "./hooks/useDroppable";
+export { useSortable } from "./hooks/useSortable";
+export { useSortableList } from "./hooks/useSortableList";

package/lib/index.js

@@ -0,0 +1,16 @@
+// Components
+export { Draggable } from "./components/Draggable";
+export { Droppable } from "./components/Droppable";
+export { Sortable } from "./components/Sortable";
+export { SortableItem } from "./components/SortableItem";
+// Context
+export { DropProvider } from "./context/DropContext";
+// Types
+export * from "./types";
+// Utils
+export { listToObject, setAutoScroll, setPosition, clamp, objectMove, ScrollDirection, } from "./components/sortableUtils";
+// Hooks
+export { useDraggable } from "./hooks/useDraggable";
+export { useDroppable } from "./hooks/useDroppable";
+export { useSortable } from "./hooks/useSortable";
+export { useSortableList } from "./hooks/useSortableList";

package/lib/types/context.d.ts

@@ -0,0 +1,166 @@
+import { ReactNode } from "react";
+/**
+ * Alignment options for positioning dropped items within a droppable area.
+ *
+ * Determines where within the droppable bounds the draggable item will be positioned
+ * when successfully dropped. Can be combined with DropOffset for fine-tuning.
+ *
+ * @example
+ * ```typescript
+ * // Center the dropped item (default)
+ * const centerAlignment: DropAlignment = 'center';
+ *
+ * // Position at top-left corner
+ * const topLeftAlignment: DropAlignment = 'top-left';
+ *
+ * // Position at bottom edge, centered horizontally
+ * const bottomCenterAlignment: DropAlignment = 'bottom-center';
+ * ```
+ *
+ * @see {@link DropOffset} for additional positioning control
+ * @see {@link UseDroppableOptions} for usage in droppables
+ */
+export type DropAlignment = "center" | "top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";
+/**
+ * Pixel offset to apply after alignment positioning.
+ *
+ * Provides fine-grained control over the exact position where dropped items
+ * are placed within a droppable area. Applied after the DropAlignment calculation.
+ *
+ * @example
+ * ```typescript
+ * // No offset (default)
+ * const noOffset: DropOffset = { x: 0, y: 0 };
+ *
+ * // Move 10px right and 5px down from aligned position
+ * const customOffset: DropOffset = { x: 10, y: 5 };
+ *
+ * // Move 20px left from aligned position
+ * const leftOffset: DropOffset = { x: -20, y: 0 };
+ * ```
+ *
+ * @see {@link DropAlignment} for base positioning
+ * @see {@link UseDroppableOptions} for usage in droppables
+ */
+export interface DropOffset {
+    /** Horizontal offset in pixels (positive = right, negative = left) */
+    x: number;
+    /** Vertical offset in pixels (positive = down, negative = up) */
+    y: number;
+}
+export interface DroppedItemsMap<TData = unknown> {
+    [draggableId: string]: {
+        droppableId: string;
+        data: TData;
+    };
+}
+export interface DropSlot<TData = unknown> {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    onDrop: (data: TData) => void;
+    dropAlignment?: DropAlignment;
+    dropOffset?: DropOffset;
+    capacity?: number;
+}
+export type PositionUpdateListener = () => void;
+export interface SlotsContextValue<TData = unknown> {
+    register: (id: number, slot: DropSlot<TData>) => void;
+    unregister: (id: number) => void;
+    getSlots: () => Record<number, DropSlot<TData>>;
+    isRegistered: (id: number) => boolean;
+    setActiveHoverSlot: (id: number | null) => void;
+    activeHoverSlotId: number | null;
+    registerPositionUpdateListener: (id: string, listener: PositionUpdateListener) => void;
+    unregisterPositionUpdateListener: (id: string) => void;
+    requestPositionUpdate: () => void;
+    registerDroppedItem: (draggableId: string, droppableId: string, itemData: any) => void;
+    unregisterDroppedItem: (draggableId: string) => void;
+    getDroppedItems: () => DroppedItemsMap<any>;
+    hasAvailableCapacity: (droppableId: string) => boolean;
+    onDragging?: (payload: {
+        x: number;
+        y: number;
+        tx: number;
+        ty: number;
+        itemData: any;
+    }) => void;
+    onDragStart?: (data: any) => void;
+    onDragEnd?: (data: any) => void;
+}
+export declare const SlotsContext: import("react").Context<SlotsContextValue<any>>;
+/**
+ * Props for the DropProvider component.
+ *
+ * @see {@link DropProvider} for component usage
+ */
+export interface DropProviderProps {
+    /** The child components that will have access to the drag-and-drop context */
+    children: ReactNode;
+    /**
+     * Callback fired when layout updates are complete.
+     * Useful for triggering additional UI updates after position recalculations.
+     */
+    onLayoutUpdateComplete?: () => void;
+    /**
+     * Callback fired when the dropped items mapping changes.
+     * Provides access to the current state of which items are dropped where.
+     *
+     * @param droppedItems - Current mapping of draggable IDs to their drop locations
+     */
+    onDroppedItemsUpdate?: (droppedItems: DroppedItemsMap) => void;
+    /**
+     * Global callback fired during drag operations.
+     * Receives position updates for all draggable items.
+     *
+     * @param payload - Position and data information for the dragging item
+     */
+    onDragging?: (payload: {
+        x: number;
+        y: number;
+        tx: number;
+        ty: number;
+        itemData: any;
+    }) => void;
+    /**
+     * Global callback fired when any drag operation starts.
+     * @param data - The data associated with the draggable item
+     */
+    onDragStart?: (data: any) => void;
+    /**
+     * Global callback fired when any drag operation ends.
+     * @param data - The data associated with the draggable item
+     */
+    onDragEnd?: (data: any) => void;
+}
+/**
+ * Imperative handle interface for the DropProvider component.
+ * Provides methods that can be called on the DropProvider ref.
+ *
+ * @example
+ * ```typescript
+ * const dropProviderRef = useRef<DropProviderRef>(null);
+ *
+ * // Trigger position update
+ * dropProviderRef.current?.requestPositionUpdate();
+ *
+ * // Get current dropped items
+ * const droppedItems = dropProviderRef.current?.getDroppedItems();
+ * ```
+ *
+ * @see {@link DropProvider} for component usage
+ */
+export interface DropProviderRef {
+    /**
+     * Manually trigger a position update for all registered droppables and draggables.
+     * Useful after layout changes or when positions may have become stale.
+     */
+    requestPositionUpdate: () => void;
+    /**
+     * Get the current mapping of dropped items.
+     * @returns Object mapping draggable IDs to their drop information
+     */
+    getDroppedItems: () => DroppedItemsMap;
+}

package/lib/types/context.js

@@ -0,0 +1,80 @@
+// Define DropAlignment and DropOffset types here
+import { createContext } from "react";
+// Default context value using 'any' for broad compatibility
+const defaultSlotsContextValue = {
+    register: (_id, _slot) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: register called without a Provider.");
+        }
+    },
+    unregister: (_id) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: unregister called without a Provider.");
+        }
+    },
+    getSlots: () => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: getSlots called without a Provider.");
+        }
+        return {};
+    },
+    isRegistered: (_id) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: isRegistered called without a Provider.");
+        }
+        return false;
+    },
+    setActiveHoverSlot: (_id) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: setActiveHoverSlot called without a Provider.");
+        }
+    },
+    activeHoverSlotId: null,
+    registerPositionUpdateListener: (_id, _listener) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: registerPositionUpdateListener called without a Provider.");
+        }
+    },
+    unregisterPositionUpdateListener: (_id) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: unregisterPositionUpdateListener called without a Provider.");
+        }
+    },
+    requestPositionUpdate: () => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: requestPositionUpdate called without a Provider (internally).");
+        }
+    },
+    // Update default implementations
+    registerDroppedItem: (_draggableId, _droppableId, _itemData) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: registerDroppedItem called without a Provider.");
+        }
+    },
+    unregisterDroppedItem: (_draggableId) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: unregisterDroppedItem called without a Provider.");
+        }
+    },
+    getDroppedItems: () => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: getDroppedItems called without a Provider.");
+        }
+        return {};
+    },
+    hasAvailableCapacity: (_droppableId) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: hasAvailableCapacity called without a Provider.");
+        }
+        return false;
+    },
+    onDragging: (payload) => {
+        if (process.env.NODE_ENV !== "production") {
+            console.warn("SlotsContext: onDragging called without a Provider.");
+        }
+    },
+    onDragStart: undefined,
+    onDragEnd: undefined,
+};
+// Create the context
+export const SlotsContext = createContext(defaultSlotsContextValue);