react-native-reanimated-dnd 1.0.1

package/lib/types/draggable.d.ts

@@ -0,0 +1,313 @@
+import { ViewStyle, View, StyleProp } from "react-native";
+import Animated, { AnimatedStyle, useAnimatedRef } from "react-native-reanimated";
+import { GestureType } from "react-native-gesture-handler";
+import { LayoutChangeEvent } from "react-native";
+/**
+ * Enum representing the different states a draggable item can be in.
+ *
+ * @example
+ * ```typescript
+ * import { DraggableState } from './types/draggable';
+ *
+ * const handleStateChange = (state: DraggableState) => {
+ *   switch (state) {
+ *     case DraggableState.IDLE:
+ *       console.log('Item is at rest');
+ *       break;
+ *     case DraggableState.DRAGGING:
+ *       console.log('Item is being dragged');
+ *       break;
+ *     case DraggableState.DROPPED:
+ *       console.log('Item was successfully dropped');
+ *       break;
+ *   }
+ * };
+ * ```
+ */
+export declare enum DraggableState {
+    /** Item is at rest in its original or dropped position */
+    IDLE = "IDLE",
+    /** Item is currently being dragged by the user */
+    DRAGGING = "DRAGGING",
+    /** Item has been successfully dropped on a valid drop zone */
+    DROPPED = "DROPPED"
+}
+/**
+ * Custom animation function type for controlling how draggable items animate.
+ *
+ * @param toValue - The target value to animate to
+ * @returns The animated value (typically from withSpring, withTiming, etc.)
+ *
+ * @example
+ * ```typescript
+ * const customAnimation: AnimationFunction = (toValue) => {
+ *   'worklet';
+ *   return withTiming(toValue, { duration: 500, easing: Easing.bounce });
+ * };
+ * ```
+ */
+export type AnimationFunction = (toValue: number) => number;
+/**
+ * Collision detection algorithms for determining when a draggable overlaps with a droppable.
+ *
+ * - `center`: Collision detected when the center point of the draggable is over the droppable
+ * - `intersect`: Collision detected when any part of the draggable overlaps with the droppable (default)
+ * - `contain`: Collision detected when the entire draggable is contained within the droppable
+ *
+ * @example
+ * ```typescript
+ * // For precise dropping, use center collision
+ * const preciseDraggable = useDraggable({
+ *   data: myData,
+ *   collisionAlgorithm: 'center'
+ * });
+ *
+ * // For easy dropping, use intersect (default)
+ * const easyDraggable = useDraggable({
+ *   data: myData,
+ *   collisionAlgorithm: 'intersect'
+ * });
+ *
+ * // For strict containment, use contain
+ * const strictDraggable = useDraggable({
+ *   data: myData,
+ *   collisionAlgorithm: 'contain'
+ * });
+ * ```
+ */
+export type CollisionAlgorithm = "center" | "intersect" | "contain";
+/**
+ * Configuration options for the useDraggable hook.
+ *
+ * @template TData - The type of data associated with the draggable item
+ */
+export interface UseDraggableOptions<TData = unknown> {
+    /**
+     * Data payload associated with this draggable item. This data is passed to drop handlers
+     * when the item is successfully dropped.
+     *
+     * @example
+     * ```typescript
+     * const data = { id: '1', name: 'Task 1', priority: 'high' };
+     * ```
+     */
+    data: TData;
+    /**
+     * Unique identifier for this draggable item. If not provided, one will be generated automatically.
+     * Used for tracking dropped items and managing state.
+     */
+    draggableId?: string;
+    /**
+     * Whether dragging is disabled for this item. When true, the item cannot be dragged.
+     * Useful for conditionally enabling/disabling drag functionality.
+     *
+     * @default false
+     */
+    dragDisabled?: boolean;
+    /**
+     * Callback fired when dragging starts.
+     *
+     * @param data - The data associated with the draggable item
+     *
+     * @example
+     * ```typescript
+     * const handleDragStart = (data) => {
+     *   console.log('Started dragging:', data.name);
+     *   setIsDragging(true);
+     * };
+     * ```
+     */
+    onDragStart?: (data: TData) => void;
+    /**
+     * Callback fired when dragging ends (regardless of whether it was dropped successfully).
+     *
+     * @param data - The data associated with the draggable item
+     *
+     * @example
+     * ```typescript
+     * const handleDragEnd = (data) => {
+     *   console.log('Finished dragging:', data.name);
+     *   setIsDragging(false);
+     * };
+     * ```
+     */
+    onDragEnd?: (data: TData) => void;
+    /**
+     * Callback fired continuously while dragging. Useful for real-time feedback.
+     *
+     * @param payload - Object containing position and translation information
+     * @param payload.x - Original X position of the item
+     * @param payload.y - Original Y position of the item
+     * @param payload.tx - Current X translation from original position
+     * @param payload.ty - Current Y translation from original position
+     * @param payload.itemData - The data associated with the draggable item
+     *
+     * @example
+     * ```typescript
+     * const handleDragging = ({ x, y, tx, ty, itemData }) => {
+     *   const currentX = x + tx;
+     *   const currentY = y + ty;
+     *   console.log(`${itemData.name} is at (${currentX}, ${currentY})`);
+     * };
+     * ```
+     */
+    onDragging?: (payload: {
+        x: number;
+        y: number;
+        tx: number;
+        ty: number;
+        itemData: TData;
+    }) => void;
+    /**
+     * Callback fired when the draggable state changes.
+     *
+     * @param state - The new state of the draggable item
+     *
+     * @example
+     * ```typescript
+     * const handleStateChange = (state) => {
+     *   if (state === DraggableState.DROPPED) {
+     *     showSuccessMessage();
+     *   }
+     * };
+     * ```
+     */
+    onStateChange?: (state: DraggableState) => void;
+    /**
+     * Custom animation function for controlling how the item animates when dropped.
+     * If not provided, uses default spring animation.
+     *
+     * @example
+     * ```typescript
+     * const bounceAnimation = (toValue) => {
+     *   'worklet';
+     *   return withTiming(toValue, {
+     *     duration: 600,
+     *     easing: Easing.bounce
+     *   });
+     * };
+     * ```
+     */
+    animationFunction?: AnimationFunction;
+    /**
+     * Reference to a View that defines the dragging boundaries. The draggable item
+     * will be constrained within this view's bounds.
+     *
+     * @example
+     * ```typescript
+     * const boundsRef = useRef<View>(null);
+     *
+     * return (
+     *   <View ref={boundsRef} style={styles.container}>
+     *     <Draggable dragBoundsRef={boundsRef} data={data}>
+     *       <Text>Bounded draggable</Text>
+     *     </Draggable>
+     *   </View>
+     * );
+     * ```
+     */
+    dragBoundsRef?: React.RefObject<Animated.View | View>;
+    /**
+     * Constrains dragging to a specific axis.
+     *
+     * - `x`: Only horizontal movement allowed
+     * - `y`: Only vertical movement allowed
+     * - `both`: Movement in both directions (default)
+     *
+     * @default "both"
+     *
+     * @example
+     * ```typescript
+     * // Horizontal slider
+     * const horizontalDraggable = useDraggable({
+     *   data: sliderData,
+     *   dragAxis: 'x'
+     * });
+     *
+     * // Vertical slider
+     * const verticalDraggable = useDraggable({
+     *   data: sliderData,
+     *   dragAxis: 'y'
+     * });
+     * ```
+     */
+    dragAxis?: "x" | "y" | "both";
+    /**
+     * Algorithm used for collision detection with drop zones.
+     *
+     * @default "intersect"
+     *
+     * @see {@link CollisionAlgorithm} for detailed explanation of each algorithm
+     */
+    collisionAlgorithm?: CollisionAlgorithm;
+    /**
+     * 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 useDraggable hook.
+ */
+export interface UseDraggableReturn {
+    /**
+     * Props to spread on the animated view that will be draggable.
+     * Contains the animated style and layout handler.
+     */
+    animatedViewProps: {
+        /** Animated style containing transform values for dragging */
+        style: AnimatedStyle<ViewStyle>;
+        /** Layout change handler for position updates */
+        onLayout: (event: LayoutChangeEvent) => void;
+    };
+    /**
+     * Gesture object to attach to GestureDetector for handling drag interactions.
+     * Only used when no handle is present (entire component is draggable).
+     */
+    gesture: GestureType;
+    /**
+     * Current state of the draggable item.
+     * @see {@link DraggableState}
+     */
+    state: DraggableState;
+    /**
+     * Animated ref for the draggable view. Used internally for measurements.
+     */
+    animatedViewRef: ReturnType<typeof useAnimatedRef<Animated.View>>;
+    /**
+     * Whether this draggable has a handle component. When true, only the handle
+     * can initiate dragging. When false, the entire component is draggable.
+     */
+    hasHandle: boolean;
+}
+export interface DraggableContextValue {
+    gesture: any;
+    state: DraggableState;
+}
+/**
+ * Props for the Draggable component.
+ *
+ * @template TData - The type of data associated with the draggable item
+ */
+export interface DraggableProps<TData = unknown> extends UseDraggableOptions<TData> {
+    /** Style to apply to the draggable container */
+    style?: StyleProp<ViewStyle>;
+    /** The content to render inside the draggable */
+    children: React.ReactNode;
+    /** Callback fired when the draggable state changes */
+    onStateChange?: (state: DraggableState) => void;
+}
+/**
+ * Props for the Handle component.
+ */
+export interface DraggableHandleProps {
+    /** The content to render inside the handle */
+    children: React.ReactNode;
+    /** Optional style to apply to the handle */
+    style?: StyleProp<ViewStyle>;
+}

package/lib/types/draggable.js

@@ -0,0 +1,31 @@
+/**
+ * Enum representing the different states a draggable item can be in.
+ *
+ * @example
+ * ```typescript
+ * import { DraggableState } from './types/draggable';
+ *
+ * const handleStateChange = (state: DraggableState) => {
+ *   switch (state) {
+ *     case DraggableState.IDLE:
+ *       console.log('Item is at rest');
+ *       break;
+ *     case DraggableState.DRAGGING:
+ *       console.log('Item is being dragged');
+ *       break;
+ *     case DraggableState.DROPPED:
+ *       console.log('Item was successfully dropped');
+ *       break;
+ *   }
+ * };
+ * ```
+ */
+export var DraggableState;
+(function (DraggableState) {
+    /** Item is at rest in its original or dropped position */
+    DraggableState["IDLE"] = "IDLE";
+    /** Item is currently being dragged by the user */
+    DraggableState["DRAGGING"] = "DRAGGING";
+    /** Item has been successfully dropped on a valid drop zone */
+    DraggableState["DROPPED"] = "DROPPED";
+})(DraggableState || (DraggableState = {}));

package/lib/types/droppable.d.ts

@@ -0,0 +1,197 @@
+import { LayoutChangeEvent, StyleProp, ViewStyle } from "react-native";
+import Animated, { useAnimatedRef } from "react-native-reanimated";
+import { DropAlignment, DropOffset } from "./context";
+/**
+ * Configuration options for the useDroppable hook.
+ *
+ * @template TData - The type of data that can be dropped on this droppable
+ */
+export interface UseDroppableOptions<TData = unknown> {
+    /**
+     * Callback function fired when an item is successfully dropped on this droppable.
+     * This is where you handle the drop logic for your application.
+     *
+     * @param data - The data from the draggable item that was dropped
+     *
+     * @example
+     * ```typescript
+     * const handleDrop = (data: TaskData) => {
+     *   console.log('Task dropped:', data.name);
+     *   moveTaskToColumn(data.id, 'completed');
+     *   showNotification(`${data.name} completed!`);
+     * };
+     * ```
+     */
+    onDrop: (data: TData) => void;
+    /**
+     * Whether this droppable is disabled. When true, items cannot be dropped here.
+     * Useful for conditionally enabling/disabling drop functionality.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * const isDisabled = user.role !== 'admin';
+     *
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   dropDisabled: isDisabled
+     * });
+     * ```
+     */
+    dropDisabled?: boolean;
+    /**
+     * Callback fired when the active state of this droppable changes.
+     * Active state indicates whether a draggable item is currently hovering over this droppable.
+     *
+     * @param isActive - Whether a draggable is currently hovering over this droppable
+     *
+     * @example
+     * ```typescript
+     * const handleActiveChange = (isActive: boolean) => {
+     *   if (isActive) {
+     *     playHoverSound();
+     *     setHighlighted(true);
+     *   } else {
+     *     setHighlighted(false);
+     *   }
+     * };
+     * ```
+     */
+    onActiveChange?: (isActive: boolean) => void;
+    /**
+     * How dropped items should be aligned within this droppable area.
+     *
+     * Available alignments:
+     * - `center`: Center the item within the droppable (default)
+     * - `top-left`: Align to top-left corner
+     * - `top-center`: Align to top edge, centered horizontally
+     * - `top-right`: Align to top-right corner
+     * - `center-left`: Align to left edge, centered vertically
+     * - `center-right`: Align to right edge, centered vertically
+     * - `bottom-left`: Align to bottom-left corner
+     * - `bottom-center`: Align to bottom edge, centered horizontally
+     * - `bottom-right`: Align to bottom-right corner
+     *
+     * @default "center"
+     *
+     * @example
+     * ```typescript
+     * // Items dropped here will snap to the top-left corner
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   dropAlignment: 'top-left'
+     * });
+     * ```
+     */
+    dropAlignment?: DropAlignment;
+    /**
+     * Additional pixel offset to apply after alignment.
+     * Useful for fine-tuning the exact position where items are dropped.
+     *
+     * @example
+     * ```typescript
+     * // Drop items 10px to the right and 5px down from the center
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   dropAlignment: 'center',
+     *   dropOffset: { x: 10, y: 5 }
+     * });
+     * ```
+     */
+    dropOffset?: DropOffset;
+    /**
+     * Style to apply when a draggable item is hovering over this droppable.
+     * This provides visual feedback to users about valid drop targets.
+     *
+     * @example
+     * ```typescript
+     * const activeStyle = {
+     *   backgroundColor: 'rgba(0, 255, 0, 0.2)',
+     *   borderColor: '#00ff00',
+     *   borderWidth: 2,
+     *   transform: [{ scale: 1.05 }]
+     * };
+     *
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   activeStyle
+     * });
+     * ```
+     */
+    activeStyle?: StyleProp<ViewStyle>;
+    /**
+     * Unique identifier for this droppable. If not provided, one will be generated automatically.
+     * Used for tracking which droppable items are dropped on.
+     *
+     * @example
+     * ```typescript
+     * const { viewProps } = useDroppable({
+     *   droppableId: 'todo-column',
+     *   onDrop: handleDrop
+     * });
+     * ```
+     */
+    droppableId?: string;
+    /**
+     * Maximum number of items that can be dropped on this droppable.
+     * When capacity is reached, additional items cannot be dropped here.
+     *
+     * @default 1
+     *
+     * @example
+     * ```typescript
+     * // Allow up to 5 items in this drop zone
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   capacity: 5
+     * });
+     *
+     * // Unlimited capacity
+     * const { viewProps } = useDroppable({
+     *   onDrop: handleDrop,
+     *   capacity: Infinity
+     * });
+     * ```
+     */
+    capacity?: number;
+}
+/**
+ * Return value from the useDroppable hook.
+ */
+export interface UseDroppableReturn {
+    /**
+     * Props to spread on the view that will act as a drop zone.
+     * Contains layout handler and conditional active styling.
+     */
+    viewProps: {
+        /** Layout change handler for position tracking */
+        onLayout: (event: LayoutChangeEvent) => void;
+        /** Style applied when active (draggable hovering) */
+        style?: StyleProp<ViewStyle>;
+    };
+    /**
+     * Whether a draggable item is currently hovering over this droppable.
+     * Useful for conditional rendering or additional visual feedback.
+     */
+    isActive: boolean;
+    /**
+     * The active style that was passed in options. Useful for external styling logic.
+     */
+    activeStyle?: StyleProp<ViewStyle>;
+    /**
+     * Animated ref for the droppable view. Used internally for measurements.
+     */
+    animatedViewRef: ReturnType<typeof useAnimatedRef<Animated.View>>;
+}
+/**
+ * Props for the Droppable component.
+ *
+ * @template TData - The type of data that can be dropped on this droppable
+ */
+export interface DroppableProps<TData = unknown> extends UseDroppableOptions<TData> {
+    /** Style to apply to the droppable container */
+    style?: StyleProp<ViewStyle>;
+    /** The content to render inside the droppable */
+    children: React.ReactNode;
+}

package/lib/types/droppable.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./draggable";
+export * from "./droppable";
+export * from "./sortable";
+export * from "./context";

package/lib/types/index.js

@@ -0,0 +1,8 @@
+// Re-export all draggable types
+export * from "./draggable";
+// Re-export all droppable types
+export * from "./droppable";
+// Re-export all sortable types
+export * from "./sortable";
+// Re-export all context types
+export * from "./context";