react-native-reanimated-dnd 1.0.1

package/lib/types/sortable.d.ts

@@ -0,0 +1,432 @@
+import { StyleProp, ViewStyle } from "react-native";
+import { SharedValue } from "react-native-reanimated";
+import { DropProviderRef } from "../types/context";
+import { ReactNode } from "react";
+export declare enum ScrollDirection {
+    None = "none",
+    Up = "up",
+    Down = "down"
+}
+/**
+ * Configuration options for the useSortable hook.
+ *
+ * @template T - The type of data associated with the sortable item
+ */
+export interface UseSortableOptions<T> {
+    /**
+     * Unique identifier for this sortable item. Must be unique within the sortable list.
+     * Used for tracking position changes and managing reordering logic.
+     *
+     * @example
+     * ```typescript
+     * const itemId = `task-${task.id}`;
+     * ```
+     */
+    id: string;
+    /**
+     * Shared value containing the current positions of all items in the sortable list.
+     * This is typically managed by the parent sortable list component.
+     *
+     * @example
+     * ```typescript
+     * // Managed by useSortableList hook
+     * const positions = useSharedValue({
+     *   'item-1': 0,
+     *   'item-2': 1,
+     *   'item-3': 2
+     * });
+     * ```
+     */
+    positions: SharedValue<{
+        [id: string]: number;
+    }>;
+    /**
+     * Shared value representing the current scroll position (lower bound) of the container.
+     * Used for auto-scrolling during drag operations.
+     */
+    lowerBound: SharedValue<number>;
+    /**
+     * Shared value indicating the current auto-scroll direction.
+     * Used to trigger automatic scrolling when dragging near container edges.
+     */
+    autoScrollDirection: SharedValue<ScrollDirection>;
+    /**
+     * Total number of items in the sortable list.
+     * Used for boundary calculations and position validation.
+     */
+    itemsCount: number;
+    /**
+     * Height of each item in pixels. All items must have the same height.
+     * Used for position calculations and auto-scrolling.
+     *
+     * @example
+     * ```typescript
+     * const ITEM_HEIGHT = 60; // 60px per item
+     * ```
+     */
+    itemHeight: number;
+    /**
+     * Height of the scrollable container in pixels.
+     * Used for auto-scroll calculations and determining scroll boundaries.
+     *
+     * @default 500
+     */
+    containerHeight?: number;
+    /**
+     * Callback fired when an item's position changes within the list.
+     * This is called for both the moved item and any items that were displaced.
+     *
+     * @param id - The ID of the item that moved
+     * @param from - The previous position index
+     * @param to - The new position index
+     *
+     * @example
+     * ```typescript
+     * const handleMove = (id: string, from: number, to: number) => {
+     *   console.log(`Item ${id} moved from position ${from} to ${to}`);
+     *   // Update your data model
+     *   reorderItems(id, from, to);
+     * };
+     * ```
+     */
+    onMove?: (id: string, from: number, to: number) => void;
+    /**
+     * Callback fired when dragging starts for this item.
+     *
+     * @param id - The ID of the item being dragged
+     * @param position - The current position index of the item
+     *
+     * @example
+     * ```typescript
+     * const handleDragStart = (id: string, position: number) => {
+     *   console.log(`Started dragging item ${id} from position ${position}`);
+     *   setDraggingItem(id);
+     *   hapticFeedback();
+     * };
+     * ```
+     */
+    onDragStart?: (id: string, position: number) => void;
+    /**
+     * Callback fired when dragging ends for this item.
+     *
+     * @param id - The ID of the item that was being dragged
+     * @param position - The final position index of the item
+     *
+     * @example
+     * ```typescript
+     * const handleDrop = (id: string, position: number) => {
+     *   console.log(`Dropped item ${id} at position ${position}`);
+     *   setDraggingItem(null);
+     *   saveNewOrder();
+     * };
+     * ```
+     */
+    onDrop?: (id: string, position: number) => void;
+    /**
+     * Callback fired continuously while dragging, providing real-time position updates.
+     * Useful for showing visual feedback or updating UI during drag operations.
+     *
+     * @param id - The ID of the item being dragged
+     * @param overItemId - The ID of the item currently being hovered over (null if none)
+     * @param yPosition - The current Y position of the dragged item
+     *
+     * @example
+     * ```typescript
+     * const handleDragging = (id: string, overItemId: string | null, yPosition: number) => {
+     *   if (overItemId) {
+     *     console.log(`Item ${id} is hovering over ${overItemId}`);
+     *     setHoverTarget(overItemId);
+     *   } else {
+     *     setHoverTarget(null);
+     *   }
+     * };
+     * ```
+     */
+    onDragging?: (id: string, overItemId: string | null, yPosition: number) => void;
+    /**
+     * Children elements - used internally for handle detection.
+     * @internal
+     */
+    children?: React.ReactNode;
+    /**
+     * Handle component type - used internally for handle detection.
+     * @internal
+     */
+    handleComponent?: React.ComponentType<any>;
+}
+/**
+ * Return value from the useSortable hook.
+ */
+export interface UseSortableReturn {
+    /**
+     * Animated style to apply to the sortable item.
+     * Contains position transforms and visual effects for dragging state.
+     */
+    animatedStyle: StyleProp<ViewStyle>;
+    /**
+     * Pan gesture handler for drag interactions.
+     * Attach this to a PanGestureHandler to enable dragging.
+     */
+    panGestureHandler: any;
+    /**
+     * Whether this item is currently being moved/dragged.
+     * Useful for conditional styling or behavior.
+     */
+    isMoving: boolean;
+    /**
+     * Whether this sortable item has a handle component.
+     * When true, only the handle can initiate dragging.
+     * When false, the entire item is draggable.
+     */
+    hasHandle: boolean;
+}
+/**
+ * Configuration options for the useSortableList hook.
+ *
+ * @template TData - The type of data items in the sortable list
+ */
+export interface UseSortableListOptions<TData> {
+    /**
+     * Array of data items to be rendered as sortable list items.
+     * Each item must have an `id` property for tracking.
+     *
+     * @example
+     * ```typescript
+     * const tasks = [
+     *   { id: '1', title: 'Task 1', completed: false },
+     *   { id: '2', title: 'Task 2', completed: true },
+     *   { id: '3', title: 'Task 3', completed: false }
+     * ];
+     * ```
+     */
+    data: TData[];
+    /**
+     * Height of each item in pixels. All items must have the same height
+     * for proper position calculations and smooth animations.
+     *
+     * @example
+     * ```typescript
+     * const ITEM_HEIGHT = 80; // Each list item is 80px tall
+     * ```
+     */
+    itemHeight: number;
+    /**
+     * Function to extract a unique key from each data item.
+     * If not provided, defaults to using the `id` property.
+     *
+     * @param item - The data item
+     * @param index - The index of the item in the array
+     * @returns Unique string identifier for the item
+     *
+     * @default (item) => item.id
+     *
+     * @example
+     * ```typescript
+     * // Custom key extractor for items without id property
+     * const keyExtractor = (item, index) => `${item.type}-${item.name}-${index}`;
+     *
+     * // Using a compound key
+     * const keyExtractor = (item) => `${item.category}_${item.id}`;
+     * ```
+     */
+    itemKeyExtractor?: (item: TData, index: number) => string;
+}
+/**
+ * Return value from the useSortableList hook.
+ *
+ * @template TData - The type of data items in the sortable list
+ */
+export interface UseSortableListReturn<TData> {
+    /**
+     * Shared value containing the current positions of all items.
+     * Maps item IDs to their current position indices.
+     *
+     * @example
+     * ```typescript
+     * // positions.value might look like:
+     * {
+     *   'item-1': 0,
+     *   'item-2': 1,
+     *   'item-3': 2
+     * }
+     * ```
+     */
+    positions: any;
+    /**
+     * Shared value tracking the current scroll position.
+     * Used for auto-scrolling during drag operations.
+     */
+    scrollY: any;
+    /**
+     * Shared value indicating the current auto-scroll direction.
+     * Used to trigger automatic scrolling when dragging near edges.
+     */
+    autoScroll: any;
+    /**
+     * Animated ref for the scroll view component.
+     * Used for programmatic scrolling during drag operations.
+     */
+    scrollViewRef: any;
+    /**
+     * Ref for the drop provider context.
+     * Used for triggering position updates after scroll events.
+     */
+    dropProviderRef: React.RefObject<DropProviderRef>;
+    /**
+     * Animated scroll handler to attach to the ScrollView.
+     * Tracks scroll position for auto-scroll calculations.
+     */
+    handleScroll: any;
+    /**
+     * Callback to call when scrolling ends.
+     * Triggers position recalculation for accurate drop zone detection.
+     */
+    handleScrollEnd: () => void;
+    /**
+     * Total height of the scrollable content.
+     * Calculated as `data.length * itemHeight`.
+     */
+    contentHeight: number;
+    /**
+     * Helper function to get props for individual sortable items.
+     *
+     * @param item - The data item
+     * @param index - The index of the item in the array
+     * @returns Props object to pass to the sortable item component
+     *
+     * @example
+     * ```typescript
+     * {data.map((item, index) => {
+     *   const itemProps = getItemProps(item, index);
+     *   return (
+     *     <SortableItem key={itemProps.id} {...itemProps}>
+     *       <Text>{item.title}</Text>
+     *     </SortableItem>
+     *   );
+     * })}
+     * ```
+     */
+    getItemProps: (item: TData, index: number) => {
+        /** Unique identifier for the item */
+        id: string;
+        /** Shared positions object */
+        positions: any;
+        /** Shared scroll position */
+        lowerBound: any;
+        /** Shared auto-scroll direction */
+        autoScrollDirection: any;
+        /** Total number of items */
+        itemsCount: number;
+        /** Height of each item */
+        itemHeight: number;
+    };
+}
+/**
+ * Props interface for the SortableItem component.
+ *
+ * @template T - The type of data associated with the sortable item
+ *
+ * @see {@link SortableItem} for component usage
+ * @see {@link useSortable} for the underlying hook
+ * @see {@link UseSortableOptions} for hook configuration options
+ * @see {@link UseSortableReturn} for hook return details
+ */
+export interface SortableItemProps<T> {
+    /** Unique identifier for this sortable item */
+    id: string;
+    /** Data associated with this sortable item */
+    data: T;
+    /** Shared value containing positions of all items in the list */
+    positions: SharedValue<{
+        [id: string]: number;
+    }>;
+    /** Shared value representing the current scroll position */
+    lowerBound: SharedValue<number>;
+    /** Shared value indicating the current auto-scroll direction */
+    autoScrollDirection: SharedValue<ScrollDirection>;
+    /** Total number of items in the sortable list */
+    itemsCount: number;
+    /** Height of each item in pixels */
+    itemHeight: number;
+    /** Height of the scrollable container (optional) */
+    containerHeight?: number;
+    /** Child components to render inside the sortable item */
+    children: ReactNode;
+    /** Style to apply to the item container */
+    style?: StyleProp<ViewStyle>;
+    /** Additional animated style to apply */
+    animatedStyle?: StyleProp<ViewStyle>;
+    /** Callback fired when item position changes */
+    onMove?: (id: string, from: number, to: number) => void;
+    /** Callback fired when dragging starts */
+    onDragStart?: (id: string, position: number) => void;
+    /** Callback fired when dragging ends */
+    onDrop?: (id: string, position: number) => void;
+    /** Callback fired during dragging with position updates */
+    onDragging?: (id: string, overItemId: string | null, yPosition: number) => void;
+}
+/**
+ * Props interface for the Sortable component.
+ *
+ * @template TData - The type of data items in the sortable list
+ *
+ * @see {@link Sortable} for component usage
+ * @see {@link useSortableList} for the underlying hook
+ * @see {@link UseSortableListOptions} for hook configuration options
+ * @see {@link UseSortableListReturn} for hook return details
+ */
+export interface SortableProps<TData> {
+    /** Array of data items to render as sortable list */
+    data: TData[];
+    /** Function to render each sortable item */
+    renderItem: (props: SortableRenderItemProps<TData>) => ReactNode;
+    /** Height of each item in pixels */
+    itemHeight: number;
+    /** Style to apply to the scroll view */
+    style?: StyleProp<ViewStyle>;
+    /** Style to apply to the scroll view content container */
+    contentContainerStyle?: StyleProp<ViewStyle>;
+    /** Function to extract unique key from each item */
+    itemKeyExtractor?: (item: TData, index: number) => string;
+}
+/**
+ * Props passed to the renderItem function in Sortable component.
+ *
+ * @template TData - The type of data item being rendered
+ *
+ * @see {@link SortableProps} for usage
+ * @see {@link Sortable} for component usage
+ * @see {@link SortableItem} for individual item component
+ */
+export interface SortableRenderItemProps<TData> {
+    /** The data item being rendered */
+    item: TData;
+    /** Index of the item in the original data array */
+    index: number;
+    /** Unique identifier for this item */
+    id: string;
+    /** Shared value containing positions of all items */
+    positions: SharedValue<{
+        [id: string]: number;
+    }>;
+    /** Shared value representing the current scroll position */
+    lowerBound: SharedValue<number>;
+    /** Shared value indicating the current auto-scroll direction */
+    autoScrollDirection: SharedValue<ScrollDirection>;
+    /** Total number of items in the list */
+    itemsCount: number;
+    /** Height of each item in pixels */
+    itemHeight: number;
+}
+export interface SortableContextValue {
+    panGestureHandler: any;
+}
+/**
+ * Props for the SortableHandle component.
+ */
+export interface SortableHandleProps {
+    /** The content to render inside the handle */
+    children: React.ReactNode;
+    /** Optional style to apply to the handle */
+    style?: StyleProp<ViewStyle>;
+}

package/lib/types/sortable.js

@@ -0,0 +1,6 @@
+export var ScrollDirection;
+(function (ScrollDirection) {
+    ScrollDirection["None"] = "none";
+    ScrollDirection["Up"] = "up";
+    ScrollDirection["Down"] = "down";
+})(ScrollDirection || (ScrollDirection = {}));

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "react-native-reanimated-dnd",
+  "version": "1.0.1",
+  "description": "A powerful drag-and-drop library for React Native using Reanimated 3",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml}\" --ignore-path .prettierignore",
+    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml}\" --ignore-path .prettierignore"
+  },
+  "keywords": [
+    "react-native",
+    "drag-and-drop",
+    "reanimated",
+    "sortable",
+    "dnd",
+    "gesture-handler"
+  ],
+  "author": "Vishesh Raheja <github.com/entropyconquers>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/entropyconquers/react-native-reanimated-dnd.git"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-gesture-handler": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "react": "^18.2.0",
+    "react-native": "^0.72.0",
+    "react-native-reanimated": "^3.5.0",
+    "react-native-gesture-handler": "^2.13.0",
+    "prettier": "^3.5.3"
+  },
+  "files": [
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ]
+}