react-native-tree-multi-select 3.0.0-beta.1 → 3.0.0-beta.3

package/src/hooks/useDragDrop.ts

@@ -16,7 +16,7 @@ interface UseDragDropParams<ID> {
     storeId: string;
     flattenedNodes: __FlattenedTreeNode__<ID>[];
     flashListRef: React.RefObject<FlashList<__FlattenedTreeNode__<ID>> | null>;
-    containerRef: React.RefObject<{ measureInWindow: (cb: (x: number, y: number, w: number, h: number) => void) => void } | null>;
+    containerRef: React.RefObject<{ measureInWindow: (cb: (x: number, y: number, w: number, h: number) => void) => void; } | null>;
     dragEnabled: boolean;
     onDragEnd?: (event: DragEndEvent<ID>) => void;
     longPressDuration: number;
@@ -26,20 +26,25 @@ interface UseDragDropParams<ID> {
     measuredItemHeightRef: React.MutableRefObject<number>;
     dragOverlayOffset: number;
     autoExpandDelay: number;
+    /** Pixels per nesting level, used for magnetic overlay shift. */
+    indentationMultiplier: number;
 }
 
 interface UseDragDropReturn<ID> {
     panResponder: PanResponderInstance;
     overlayY: Animated.Value;
+    overlayX: Animated.Value;
     isDragging: boolean;
     draggedNode: __FlattenedTreeNode__<ID> | null;
     dropTarget: DropTarget<ID> | null;
+    effectiveDropLevel: number;
     handleNodeTouchStart: (
         nodeId: ID,
         pageY: number,
         locationY: number,
         nodeIndex: number,
     ) => void;
+    handleNodeTouchEnd: () => void;
     cancelLongPressTimer: () => void;
     scrollOffsetRef: React.MutableRefObject<number>;
     headerOffsetRef: React.MutableRefObject<number>;
@@ -62,6 +67,7 @@ export function useDragDrop<ID>(
         measuredItemHeightRef,
         dragOverlayOffset,
         autoExpandDelay,
+        indentationMultiplier,
     } = params;
 
     // --- Refs for mutable state (no stale closures in PanResponder) ---
@@ -72,6 +78,7 @@ export function useDragDrop<ID>(
 
     const longPressTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
+    const containerPageXRef = useRef(0);
     const containerPageYRef = useRef(0);
     const containerHeightRef = useRef(0);
     const grabOffsetYRef = useRef(0);
@@ -80,6 +87,8 @@ export function useDragDrop<ID>(
     const itemHeightRef = useRef(36);
 
     const overlayY = useRef(new Animated.Value(0)).current;
+    const overlayX = useRef(new Animated.Value(0)).current;
+    const prevEffectiveLevelRef = useRef<number | null>(null);
 
     const autoScrollRAFRef = useRef<number | null>(null);
     const autoScrollSpeedRef = useRef(0);
@@ -94,8 +103,11 @@ export function useDragDrop<ID>(
     // Track which nodes were auto-expanded during this drag (to collapse on drag end)
     const autoExpandedDuringDragRef = useRef<Set<ID>>(new Set());
 
+    // Tracks whether the PanResponder has captured the current gesture
+    const panResponderActiveRef = useRef(false);
+
     // Previous drop target for hysteresis (prevents flicker between "below N" / "above N+1")
-    const prevDropTargetRef = useRef<{ targetIndex: number; position: "above" | "below" | "inside" } | null>(null);
+    const prevDropTargetRef = useRef<{ targetIndex: number; position: "above" | "below" | "inside"; } | null>(null);
 
     // Keep flattenedNodes ref current for PanResponder closures
     const flattenedNodesRef = useRef(flattenedNodes);
@@ -109,8 +121,9 @@ export function useDragDrop<ID>(
     const [isDragging, setIsDragging] = useState(false);
     const [draggedNode, setDraggedNode] = useState<__FlattenedTreeNode__<ID> | null>(null);
     const [dropTarget, setDropTarget] = useState<DropTarget<ID> | null>(null);
+    const [effectiveDropLevel, setEffectiveDropLevel] = useState(0);
 
-    // Ref mirror of dropTarget — avoids nesting Zustand updates inside React state updaters
+    // Ref mirror of dropTarget - avoids nesting Zustand updates inside React state updaters
     const dropTargetRef = useRef<DropTarget<ID> | null>(null);
 
     // --- Long press timer ---
@@ -152,7 +165,8 @@ export function useDragDrop<ID>(
             const container = containerRef.current;
             if (!container) return;
 
-            container.measureInWindow((_x, y, _w, h) => {
+            container.measureInWindow((x, y, _w, h) => {
+                containerPageXRef.current = x;
                 containerPageYRef.current = y;
                 containerHeightRef.current = h;
 
@@ -212,11 +226,16 @@ export function useDragDrop<ID>(
                 const overlayLocalY = fingerLocalY - locationY + dragOverlayOffset * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
+                // Reset magnetic overlay
+                overlayX.setValue(0);
+                prevEffectiveLevelRef.current = node.level ?? 0;
+
                 // Set React state
                 isDraggingRef.current = true;
                 autoExpandedDuringDragRef.current.clear();
                 setIsDragging(true);
                 setDraggedNode(node);
+                setEffectiveDropLevel(node.level ?? 0);
                 setDropTarget(null);
 
                 // Start auto-scroll loop
@@ -314,7 +333,7 @@ export function useDragDrop<ID>(
 
     // --- Calculate drop target ---
     const calculateDropTarget = useCallback(
-        (fingerPageY: number) => {
+        (fingerPageY: number, fingerPageX: number) => {
             const nodes = flattenedNodesRef.current;
             if (nodes.length === 0) return;
 
@@ -338,17 +357,120 @@ export function useDragDrop<ID>(
             const positionInItem =
                 (adjustedContentY - clampedIndex * iH) / iH;
             let position: "above" | "below" | "inside";
-            if (positionInItem < 0.3) {
+            if (positionInItem < 0.15) {
                 position = "above";
-            } else if (positionInItem > 0.7) {
+            } else if (positionInItem > 0.85) {
                 position = "below";
             } else {
                 position = "inside";
             }
 
+            // --- Horizontal control at level cliffs ---
+            // At the boundary between nodes at different depths, the user's
+            // horizontal finger position decides the drop level:
+            //   finger RIGHT of threshold → stay at deep level (inside parent)
+            //   finger LEFT of threshold → switch to shallow level (outside parent)
+            // The threshold uses a generous buffer so dragging slightly left is enough.
+            const fingerLocalX = fingerPageX - containerPageXRef.current;
+            // logicalTargetId/logicalPosition: when the visual indicator node differs
+            // from the actual moveTreeNode target (e.g., ancestor at a shallower level).
+            let logicalTargetId: ID | null = null;
+            let logicalPosition: "above" | "below" | "inside" | null = null;
+            let visualDropLevel: number | null = null;
+
+            if (position === "below" || position === "inside") {
+                const currentLevel = targetNode.level ?? 0;
+                let isCliff = false;
+                let shallowLevel = 0;
+
+                if (clampedIndex < nodes.length - 1) {
+                    const nextNode = nodes[clampedIndex + 1];
+                    const nextLevel = nextNode?.level ?? 0;
+                    if (nextNode && nextLevel < currentLevel) {
+                        isCliff = true;
+                        shallowLevel = nextLevel;
+                    }
+                } else if (currentLevel > 0) {
+                    // Last item in the list - treat as cliff to root level
+                    isCliff = true;
+                    shallowLevel = 0;
+                }
+
+                if (isCliff) {
+                    // Generous threshold: midpoint of the two levels + 2× indent buffer
+                    const threshold =
+                        ((currentLevel + shallowLevel) / 2) * indentationMultiplier
+                        + indentationMultiplier * 2;
+
+                    if (fingerLocalX < threshold) {
+                        // User wants the shallow level
+                        if (clampedIndex < nodes.length - 1) {
+                            // Non-last item: switch to "above" on the next (shallower) node
+                            const nextNode = nodes[clampedIndex + 1]!;
+                            clampedIndex = clampedIndex + 1;
+                            targetNode = nextNode;
+                            position = "above";
+                        } else {
+                            // Last item: find ancestor at shallow level, target it with "below"
+                            const { childToParentMap } = getTreeViewStore<ID>(storeId).getState();
+                            let ancestorId = targetNode.id;
+                            let walkLevel = currentLevel;
+                            while (walkLevel > shallowLevel) {
+                                const parentId = childToParentMap.get(ancestorId);
+                                if (parentId === undefined) break;
+                                ancestorId = parentId;
+                                walkLevel--;
+                            }
+                            // Visual stays on the last item; logical goes to ancestor
+                            logicalTargetId = ancestorId;
+                            logicalPosition = "below";
+                            visualDropLevel = shallowLevel;
+                        }
+                    }
+                }
+            }
+            if (position === "above" && clampedIndex > 0) {
+                const prevNode = nodes[clampedIndex - 1];
+                const prevLevel = prevNode?.level ?? 0;
+                const currentLevel = targetNode.level ?? 0;
+                if (prevNode && prevLevel > currentLevel) {
+                    // Level cliff above - same generous threshold
+                    const threshold =
+                        ((prevLevel + currentLevel) / 2) * indentationMultiplier
+                        + indentationMultiplier * 2;
+
+                    if (fingerLocalX >= threshold) {
+                        clampedIndex = clampedIndex - 1;
+                        targetNode = prevNode;
+                        position = "below";
+                    }
+                }
+            }
+
+            // --- Suppress "below" when it's redundant or confusing ---
+            // After horizontal control, any remaining "below" that isn't at a
+            // cliff is redundant with "above" on the next node → show "inside".
+            if (position === "below") {
+                const expandedSet = getTreeViewStore<ID>(storeId).getState().expanded;
+
+                // (a) Expanded parent: "below" visually sits at the parent/child junction
+                // but semantically inserts as a sibling after the entire subtree.
+                if (targetNode.children?.length && expandedSet.has(targetNode.id)) {
+                    position = "inside";
+                }
+                // (b) No level cliff below: convert to "inside" so the highlight
+                // covers the full bottom of the node.
+                else if (clampedIndex < nodes.length - 1) {
+                    const nextNode = nodes[clampedIndex + 1];
+                    if (nextNode && (nextNode.level ?? 0) >= (targetNode.level ?? 0)) {
+                        position = "inside";
+                    }
+                }
+            }
+
             // --- Hysteresis: prevent flicker between "below N" and "above N+1" ---
-            // These two positions represent the same visual gap between nodes.
-            // Keep the previous one to avoid the indicator jumping between nodes.
+            // Only applies to same-level boundaries. Level cliffs are handled
+            // by horizontal control above, so they pass through without forced resolution.
             const prev = prevDropTargetRef.current;
             if (prev) {
                 const sameGap =
@@ -357,8 +479,17 @@ export function useDragDrop<ID>(
                     (prev.position === "above" && position === "below" &&
                         clampedIndex === prev.targetIndex - 1);
                 if (sameGap) {
-                    // Keep previous target — they're at the same visual gap
-                    return;
+                    const upperIdx = Math.min(prev.targetIndex, clampedIndex);
+                    const lowerIdx = Math.max(prev.targetIndex, clampedIndex);
+                    const upperLevel = nodes[upperIdx]?.level ?? 0;
+                    const lowerLevel = nodes[lowerIdx]?.level ?? 0;
+
+                    if (upperLevel === lowerLevel) {
+                        // Same level - pure visual hysteresis, keep previous
+                        return;
+                    }
+                    // Level cliff - horizontal control already resolved this,
+                    // let the result pass through.
                 }
             }
             prevDropTargetRef.current = { targetIndex: clampedIndex, position };
@@ -376,7 +507,7 @@ export function useDragDrop<ID>(
             // --- Auto-expand: if hovering "inside" a collapsed expandable node ---
             if (isValid && position === "inside" && targetNode.children?.length && !expanded.has(targetNode.id)) {
                 if (autoExpandTargetRef.current !== targetNode.id) {
-                    // New hover target — start timer
+                    // New hover target - start timer
                     cancelAutoExpandTimer();
                     autoExpandTargetRef.current = targetNode.id;
                     autoExpandTimerRef.current = setTimeout(() => {
@@ -387,12 +518,46 @@ export function useDragDrop<ID>(
                     }, autoExpandDelay);
                 }
             } else {
-                // Not hovering inside a collapsed expandable node — cancel timer
+                // Not hovering inside a collapsed expandable node - cancel timer
                 if (autoExpandTargetRef.current !== null) {
                     cancelAutoExpandTimer();
                 }
             }
 
+            // --- Magnetic overlay: update the effective level so the overlay
+            //     renders its content at the correct indentation natively.
+            //     A brief translateX spring provides a smooth transition. ---
+            const draggedLevel = draggedNodeRef.current?.level ?? 0;
+            // When a logical target overrides the visual (e.g. ancestor at last-item cliff),
+            // the effective level comes from the visual drop level, not the target node.
+            const effectiveLevel = isValid
+                ? (visualDropLevel !== null
+                    ? visualDropLevel  // "below" ancestor → sibling at that level
+                    : position === "inside"
+                        ? (targetNode.level ?? 0) + 1
+                        : (targetNode.level ?? 0))
+                : draggedLevel;
+            if (effectiveLevel !== prevEffectiveLevelRef.current) {
+                const prevLevel = prevEffectiveLevelRef.current ?? effectiveLevel;
+                prevEffectiveLevelRef.current = effectiveLevel;
+                setEffectiveDropLevel(effectiveLevel);
+
+                // The level prop change snaps the content to the correct indent.
+                // Counteract that visual jump with an initial translateX offset,
+                // then spring to 0 for a smooth "magnetic snap" transition.
+                if (prevLevel !== effectiveLevel) {
+                    overlayX.setValue(
+                        (prevLevel - effectiveLevel) * indentationMultiplier
+                    );
+                    Animated.spring(overlayX, {
+                        toValue: 0,
+                        useNativeDriver: true,
+                        speed: 40,
+                        bounciness: 4,
+                    }).start();
+                }
+            }
+
             const newTarget: DropTarget<ID> = {
                 targetNodeId: targetNode.id,
                 targetIndex: clampedIndex,
@@ -404,13 +569,23 @@ export function useDragDrop<ID>(
 
             // Update the store so each Node can render its own indicator
             if (isValid) {
-                store.getState().updateDropTarget(targetNode.id, position);
+                store.getState().updateDropTarget(targetNode.id, position, visualDropLevel);
             } else {
                 store.getState().updateDropTarget(null, null);
             }
 
             // Keep ref in sync (used by handleDragEnd to avoid setState-during-render)
-            dropTargetRef.current = newTarget;
+            // When a logical target exists (e.g. ancestor at a cliff), use it
+            // for the actual move while the visual indicator stays on the current node.
+            if (logicalTargetId !== null && logicalPosition !== null) {
+                dropTargetRef.current = {
+                    ...newTarget,
+                    targetNodeId: logicalTargetId,
+                    position: logicalPosition,
+                };
+            } else {
+                dropTargetRef.current = newTarget;
+            }
 
             setDropTarget((prevTarget) => {
                 if (
@@ -424,12 +599,12 @@ export function useDragDrop<ID>(
                 return newTarget;
             });
         },
-        [storeId, autoExpandDelay, cancelAutoExpandTimer]
+        [storeId, autoExpandDelay, cancelAutoExpandTimer, indentationMultiplier, overlayX]
     );
 
     // --- Handle drag end ---
     const handleDragEnd = useCallback(
-        (fingerPageY?: number) => {
+        (fingerPageY?: number, fingerPageX?: number) => {
             stopAutoScroll();
             cancelLongPressTimer();
             cancelAutoExpandTimer();
@@ -438,9 +613,9 @@ export function useDragDrop<ID>(
             if (!isDraggingRef.current) return;
             isDraggingRef.current = false;
 
-            // Recalculate drop target at final position if we have a pageY
+            // Recalculate drop target at final position if we have coords
             if (fingerPageY !== undefined) {
-                calculateDropTarget(fingerPageY);
+                calculateDropTarget(fingerPageY, fingerPageX ?? 0);
             }
 
             // Cancel any auto-expand timer that calculateDropTarget may have just started.
@@ -498,17 +673,31 @@ export function useDragDrop<ID>(
                     newTreeData: newData,
                 });
 
-                // Scroll to the dropped node after React processes the expansion
+                // Scroll to the dropped node after React processes the expansion,
+                // but only if it's outside the visible viewport.  An animated
+                // scroll would consume the user's next touch (RN stops the
+                // animation on tap), so we skip when the node is already visible.
                 setTimeout(() => {
                     const nodes = flattenedNodesRef.current;
                     const idx = nodes.findIndex(n => n.id === droppedNodeId);
-                    if (idx >= 0) {
-                        flashListRef.current?.scrollToIndex?.({
-                            index: idx,
-                            animated: true,
-                            viewPosition: 0.5,
-                        });
+                    if (idx < 0) return;
+
+                    const itemH = itemHeightRef.current;
+                    const scrollTop = scrollOffsetRef.current;
+                    const containerH = containerHeightRef.current;
+                    const estimatedTop = idx * itemH;
+                    const estimatedBottom = estimatedTop + itemH;
+
+                    // Already in view → no scroll needed
+                    if (estimatedTop >= scrollTop && estimatedBottom <= scrollTop + containerH) {
+                        return;
                     }
+
+                    flashListRef.current?.scrollToIndex?.({
+                        index: idx,
+                        animated: true,
+                        viewPosition: 0.5,
+                    });
                 }, 100);
             }
 
@@ -547,6 +736,8 @@ export function useDragDrop<ID>(
             store2.getState().updateDropTarget(null, null);
 
             // Reset all refs
+            overlayX.setValue(0);
+            prevEffectiveLevelRef.current = null;
             dropTargetRef.current = null;
             draggedNodeRef.current = null;
             draggedNodeIdRef.current = null;
@@ -567,6 +758,16 @@ export function useDragDrop<ID>(
         ]
     );
 
+    // --- Handle node touch end ---
+    // If the PanResponder never captured the gesture (no movement after long
+    // press fired), end the drag here so the node doesn't stay "lifted".
+    const handleNodeTouchEnd = useCallback(() => {
+        cancelLongPressTimer();
+        if (isDraggingRef.current && !panResponderActiveRef.current) {
+            handleDragEnd();
+        }
+    }, [cancelLongPressTimer, handleDragEnd]);
+
     // --- PanResponder ---
     const panResponder = useRef(
         PanResponder.create({
@@ -578,7 +779,7 @@ export function useDragDrop<ID>(
                 isDraggingRef.current,
 
             onPanResponderGrant: () => {
-                // Touch captured successfully
+                panResponderActiveRef.current = true;
             },
 
             onPanResponderMove: (evt) => {
@@ -593,10 +794,10 @@ export function useDragDrop<ID>(
                     fingerLocalY - grabOffsetYRef.current + dragOverlayOffset * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
-                // Calculate drop target
-                calculateDropTarget(fingerPageY);
+                // Calculate drop target (horizontal position used at level cliffs)
+                calculateDropTarget(fingerPageY, evt.nativeEvent.pageX);
 
-                // Auto-scroll at edges — use delta-based position relative to container
+                // Auto-scroll at edges - use delta-based position relative to container
                 const fingerInContainer =
                     initialFingerContainerYRef.current +
                     (fingerPageY - initialFingerPageYRef.current);
@@ -604,10 +805,12 @@ export function useDragDrop<ID>(
             },
 
             onPanResponderRelease: (evt) => {
-                handleDragEnd(evt.nativeEvent.pageY);
+                panResponderActiveRef.current = false;
+                handleDragEnd(evt.nativeEvent.pageY, evt.nativeEvent.pageX);
             },
 
             onPanResponderTerminate: () => {
+                panResponderActiveRef.current = false;
                 handleDragEnd();
             },
         })
@@ -632,10 +835,13 @@ export function useDragDrop<ID>(
     return {
         panResponder,
         overlayY,
+        overlayX,
         isDragging,
         draggedNode,
         dropTarget,
+        effectiveDropLevel,
         handleNodeTouchStart,
+        handleNodeTouchEnd,
         cancelLongPressTimer,
         scrollOffsetRef,
         headerOffsetRef,

package/src/store/treeView.store.ts

@@ -54,7 +54,8 @@ export type TreeViewState<ID> = {
     // Drop target state (used by nodes to render their own indicator)
     dropTargetNodeId: ID | null;
     dropPosition: DropPosition | null;
-    updateDropTarget: (nodeId: ID | null, position: DropPosition | null) => void;
+    dropLevel: number | null;
+    updateDropTarget: (nodeId: ID | null, position: DropPosition | null, level?: number | null) => void;
 
     // Cleanup all states in this store
     cleanUpTreeViewStore: () => void;
@@ -120,9 +121,11 @@ export function getTreeViewStore<ID>(id: string): UseBoundStore<StoreApi<TreeVie
 
             dropTargetNodeId: null,
             dropPosition: null,
-            updateDropTarget: (nodeId, position) => set({
+            dropLevel: null,
+            updateDropTarget: (nodeId, position, level) => set({
                 dropTargetNodeId: nodeId,
                 dropPosition: position,
+                dropLevel: level ?? null,
             }),
 
             cleanUpTreeViewStore: () =>
@@ -141,6 +144,7 @@ export function getTreeViewStore<ID>(id: string): UseBoundStore<StoreApi<TreeVie
                     invalidDragTargetIds: new Set<ID>(),
                     dropTargetNodeId: null,
                     dropPosition: null,
+                    dropLevel: null,
                 }),
         }));
 

package/src/types/dragDrop.types.ts

@@ -1,7 +1,9 @@
 import type { TreeNode } from "./treeView.types";
 
+/** Where a node is dropped relative to the target: as a sibling above/below, or as a child inside */
 export type DropPosition = "above" | "below" | "inside";
 
+/** Event payload passed to the onDragEnd callback after a successful drop */
 export interface DragEndEvent<ID = string> {
     /** The id of the node that was dragged */
     draggedNodeId: ID;
@@ -13,11 +15,18 @@ export interface DragEndEvent<ID = string> {
     newTreeData: TreeNode<ID>[];
 }
 
+/** Internal representation of the current drop target during a drag operation */
 export interface DropTarget<ID = string> {
+    /** The id of the node being hovered over */
     targetNodeId: ID;
+    /** Index of the target node in the flattened list */
     targetIndex: number;
+    /** Where the drop would occur relative to the target */
     position: DropPosition;
+    /** Whether this is a valid drop location (e.g. not dropping a node onto itself or its descendants) */
     isValid: boolean;
+    /** Nesting level of the target node */
     targetLevel: number;
+    /** Y-coordinate for positioning the drop indicator */
     indicatorTop: number;
 }