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

package/src/helpers/toggleCheckbox.helper.ts

@@ -1,5 +1,56 @@
+import type { CheckboxValueType, TreeNode } from "../types/treeView.types";
 import { getTreeViewStore } from "../store/treeView.store";
 
+/** Derive the tri-state checkbox value from checked and indeterminate booleans. */
+export function getCheckboxValue(
+    isChecked: boolean,
+    isIndeterminate: boolean
+): CheckboxValueType {
+    if (isIndeterminate) return "indeterminate";
+    return isChecked;
+}
+
+/**
+ * Update a parent node's checked/indeterminate state based on its children.
+ * Mutates tempChecked and tempIndeterminate in-place.
+ */
+function updateParentCheckState<ID>(
+    parentId: ID,
+    children: TreeNode<ID>[],
+    tempChecked: Set<ID>,
+    tempIndeterminate: Set<ID>,
+): void {
+    let allChecked = true;
+    let anyCheckedOrIndeterminate = false;
+
+    for (const child of children) {
+        const isChecked = tempChecked.has(child.id);
+        const isIndeterminate = tempIndeterminate.has(child.id);
+
+        if (isChecked) {
+            anyCheckedOrIndeterminate = true;
+        } else if (isIndeterminate) {
+            anyCheckedOrIndeterminate = true;
+            allChecked = false;
+        } else {
+            allChecked = false;
+        }
+
+        if (!allChecked && anyCheckedOrIndeterminate) break;
+    }
+
+    if (allChecked) {
+        tempChecked.add(parentId);
+        tempIndeterminate.delete(parentId);
+    } else if (anyCheckedOrIndeterminate) {
+        tempChecked.delete(parentId);
+        tempIndeterminate.add(parentId);
+    } else {
+        tempChecked.delete(parentId);
+        tempIndeterminate.delete(parentId);
+    }
+}
+
 /**
  * Function to toggle checkbox state for a tree structure.
  * It sets the checked and indeterminate state for all affected nodes in the tree after an action to check/uncheck is made.
@@ -106,7 +157,7 @@ export function toggleCheckboxes<ID>(
         while (stack.length > 0) {
             const nodeId = stack.pop()!;
             const node = nodeMap.get(nodeId);
-            if (!node) continue; // Node does not exist; skip
+            if (!node) continue;
 
             if (childrenChecked) {
                 tempChecked.add(nodeId);
@@ -157,43 +208,8 @@ export function toggleCheckboxes<ID>(
      */
     function updateNodeState(nodeId: ID) {
         const node = nodeMap.get(nodeId);
-        if (!node || !node.children || node.children.length === 0) {
-            // Leaf nodes are already updated.
-            return;
-        }
-
-        let allChildrenChecked = true;
-        let anyChildCheckedOrIndeterminate = false;
-
-        for (const child of node.children) {
-            const isChecked = tempChecked.has(child.id);
-            const isIndeterminate = tempIndeterminate.has(child.id);
-
-            if (isChecked) {
-                anyChildCheckedOrIndeterminate = true;
-            } else if (isIndeterminate) {
-                anyChildCheckedOrIndeterminate = true;
-                allChildrenChecked = false;
-            } else {
-                allChildrenChecked = false;
-            }
-
-            // If both conditions are met, we can break early.
-            if (!allChildrenChecked && anyChildCheckedOrIndeterminate) {
-                break;
-            }
-        }
-
-        if (allChildrenChecked) {
-            tempChecked.add(nodeId);
-            tempIndeterminate.delete(nodeId);
-        } else if (anyChildCheckedOrIndeterminate) {
-            tempChecked.delete(nodeId);
-            tempIndeterminate.add(nodeId);
-        } else {
-            tempChecked.delete(nodeId);
-            tempIndeterminate.delete(nodeId);
-        }
+        if (!node?.children?.length) return;
+        updateParentCheckState(nodeId, node.children, tempChecked, tempIndeterminate);
     }
 
     // Update the state object with the new checked and indeterminate sets.
@@ -260,37 +276,9 @@ export function recalculateCheckedStates<ID>(storeId: string) {
     // Update each parent based on its children's current state
     for (const parentId of parentNodes) {
         const node = nodeMap.get(parentId);
+        /* istanbul ignore next -- parentNodes is built from nodeMap entries with children above; same nodeMap, same iteration - unreachable unless nodeMap mutates between loops */
         if (!node?.children?.length) continue;
-
-        let allChecked = true;
-        let anyCheckedOrIndeterminate = false;
-
-        for (const child of node.children) {
-            const isChecked = tempChecked.has(child.id);
-            const isIndeterminate = tempIndeterminate.has(child.id);
-
-            if (isChecked) {
-                anyCheckedOrIndeterminate = true;
-            } else if (isIndeterminate) {
-                anyCheckedOrIndeterminate = true;
-                allChecked = false;
-            } else {
-                allChecked = false;
-            }
-
-            if (!allChecked && anyCheckedOrIndeterminate) break;
-        }
-
-        if (allChecked) {
-            tempChecked.add(parentId);
-            tempIndeterminate.delete(parentId);
-        } else if (anyCheckedOrIndeterminate) {
-            tempChecked.delete(parentId);
-            tempIndeterminate.add(parentId);
-        } else {
-            tempChecked.delete(parentId);
-            tempIndeterminate.delete(parentId);
-        }
+        updateParentCheckState(parentId, node.children, tempChecked, tempIndeterminate);
     }
 
     updateChecked(tempChecked);

package/src/hooks/useDragDrop.ts

@@ -1,33 +1,67 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+    MutableRefObject,
+    RefObject,
+    useCallback,
+    useEffect,
+    useRef,
+    useState
+} from "react";
 import {
     Animated,
     PanResponder,
+    Platform,
     type PanResponderInstance,
 } from "react-native";
 import type { FlashList } from "@shopify/flash-list";
 
-import type { __FlattenedTreeNode__, TreeNode } from "../types/treeView.types";
-import type { DragEndEvent, DropTarget } from "../types/dragDrop.types";
+import type { __FlattenedTreeNode__, TreeNode, DropAutoScrollOptions } from "../types/treeView.types";
+import type { ScrollToNodeHandlerRef } from "./useScrollToNode";
+import type { DragCancelEvent, DragEndEvent, DragStartEvent, DropTarget } from "../types/dragDrop.types";
 import { getTreeViewStore } from "../store/treeView.store";
-import { collapseNodes, expandNodes, handleToggleExpand, initializeNodeMaps, recalculateCheckedStates } from "../helpers";
+import {
+    collapseNodes,
+    expandNodes,
+    handleToggleExpand,
+    initializeNodeMaps,
+    recalculateCheckedStates
+} from "../helpers";
 import { moveTreeNode } from "../helpers/moveTreeNode.helper";
+import { listHeaderFooterPadding } from "../constants/treeView.constants";
+
+// Android reports locationY slightly differently, causing the overlay
+// to appear ~1 item height closer to the finger than on iOS.
+const PLATFORM_OVERLAY_Y_CORRECTION = Platform.OS === "android" ? -2 : 0;
 
 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>;
+    flashListRef: RefObject<FlashList<__FlattenedTreeNode__<ID>> | null>;
+    containerRef: RefObject<{ measureInWindow: (cb: (x: number, y: number, w: number, h: number) => void) => void; } | null>;
     dragEnabled: boolean;
+    onDragStart?: (event: DragStartEvent<ID>) => void;
     onDragEnd?: (event: DragEndEvent<ID>) => void;
+    onDragCancel?: (event: DragCancelEvent<ID>) => void;
     longPressDuration: number;
     autoScrollThreshold: number;
     autoScrollSpeed: number;
-    internalDataRef: React.MutableRefObject<TreeNode<ID>[] | null>;
-    measuredItemHeightRef: React.MutableRefObject<number>;
+    internalDataRef: MutableRefObject<TreeNode<ID>[] | null>;
+    measuredItemHeightRef: MutableRefObject<number>;
     dragOverlayOffset: number;
     autoExpandDelay: number;
     /** Pixels per nesting level, used for magnetic overlay shift. */
     indentationMultiplier: number;
+    /** Callback to determine if a drop is allowed on a specific target. */
+    canDrop?: (draggedNode: TreeNode<ID>, targetNode: TreeNode<ID>, position: "above" | "below" | "inside") => boolean;
+    /** Maximum nesting depth allowed. */
+    maxDepth?: number;
+    /** Callback to determine if a node can accept children. */
+    canNodeHaveChildren?: (node: TreeNode<ID>) => boolean;
+    /** Ref for scrolling to a node after drop. */
+    scrollToNodeHandlerRef: RefObject<ScrollToNodeHandlerRef<ID> | null>;
+    /** Auto-scroll configuration for after drop. */
+    autoScrollToDroppedNode?: boolean | DropAutoScrollOptions;
+    /** Callback to determine if a node can be dragged. */
+    canDrag?: (node: TreeNode<ID>) => boolean;
 }
 
 interface UseDragDropReturn<ID> {
@@ -46,8 +80,8 @@ interface UseDragDropReturn<ID> {
     ) => void;
     handleNodeTouchEnd: () => void;
     cancelLongPressTimer: () => void;
-    scrollOffsetRef: React.MutableRefObject<number>;
-    headerOffsetRef: React.MutableRefObject<number>;
+    scrollOffsetRef: MutableRefObject<number>;
+    headerOffsetRef: MutableRefObject<number>;
 }
 
 export function useDragDrop<ID>(
@@ -59,7 +93,9 @@ export function useDragDrop<ID>(
         flashListRef,
         containerRef,
         dragEnabled,
+        onDragStart,
         onDragEnd,
+        onDragCancel,
         longPressDuration,
         autoScrollThreshold,
         autoScrollSpeed,
@@ -68,6 +104,12 @@ export function useDragDrop<ID>(
         dragOverlayOffset,
         autoExpandDelay,
         indentationMultiplier,
+        canDrop: canDropCallback,
+        maxDepth,
+        canNodeHaveChildren,
+        canDrag,
+        scrollToNodeHandlerRef,
+        autoScrollToDroppedNode,
     } = params;
 
     // --- Refs for mutable state (no stale closures in PanResponder) ---
@@ -80,6 +122,7 @@ export function useDragDrop<ID>(
 
     const containerPageXRef = useRef(0);
     const containerPageYRef = useRef(0);
+    const containerWidthRef = useRef(0);
     const containerHeightRef = useRef(0);
     const grabOffsetYRef = useRef(0);
     const scrollOffsetRef = useRef(0);
@@ -109,13 +152,40 @@ export function useDragDrop<ID>(
     // Previous drop target for hysteresis (prevents flicker between "below N" / "above N+1")
     const prevDropTargetRef = useRef<{ targetIndex: number; position: "above" | "below" | "inside"; } | null>(null);
 
+    // Depth of the dragged subtree (computed once at drag start, used for maxDepth check)
+    const draggedSubtreeDepthRef = useRef(0);
+
     // Keep flattenedNodes ref current for PanResponder closures
     const flattenedNodesRef = useRef(flattenedNodes);
     flattenedNodesRef.current = flattenedNodes;
 
     // Keep callbacks current
+    const onDragStartRef = useRef(onDragStart);
+    onDragStartRef.current = onDragStart;
     const onDragEndRef = useRef(onDragEnd);
     onDragEndRef.current = onDragEnd;
+    const onDragCancelRef = useRef(onDragCancel);
+    onDragCancelRef.current = onDragCancel;
+    const canDropRef = useRef(canDropCallback);
+    canDropRef.current = canDropCallback;
+    const canNodeHaveChildrenRef = useRef(canNodeHaveChildren);
+    canNodeHaveChildrenRef.current = canNodeHaveChildren;
+    const canDragRef = useRef(canDrag);
+    canDragRef.current = canDrag;
+
+    // Keep config values current for PanResponder closures
+    const dragOverlayOffsetRef = useRef(dragOverlayOffset);
+    dragOverlayOffsetRef.current = dragOverlayOffset;
+    const autoScrollThresholdRef = useRef(autoScrollThreshold);
+    autoScrollThresholdRef.current = autoScrollThreshold;
+    const autoScrollSpeedParamRef = useRef(autoScrollSpeed);
+    autoScrollSpeedParamRef.current = autoScrollSpeed;
+    const autoExpandDelayRef = useRef(autoExpandDelay);
+    autoExpandDelayRef.current = autoExpandDelay;
+    const indentationMultiplierRef = useRef(indentationMultiplier);
+    indentationMultiplierRef.current = indentationMultiplier;
+    const maxDepthRef = useRef(maxDepth);
+    maxDepthRef.current = maxDepth;
 
     // --- React state (triggers re-renders only at drag start/end + indicator changes) ---
     const [isDragging, setIsDragging] = useState(false);
@@ -157,6 +227,22 @@ export function useDragDrop<ID>(
         [storeId]
     );
 
+    // --- Get the maximum depth of a subtree (0 for leaf nodes) ---
+    const getSubtreeDepth = useCallback(
+        (nodeId: ID): number => {
+            const store = getTreeViewStore<ID>(storeId);
+            const { nodeMap } = store.getState();
+            const node = nodeMap.get(nodeId);
+            if (!node?.children?.length) return 0;
+            let max = 0;
+            for (const child of node.children) {
+                max = Math.max(max, 1 + getSubtreeDepth(child.id));
+            }
+            return max;
+        },
+        [storeId]
+    );
+
     // --- Initiate drag ---
     const initiateDrag = useCallback(
         (nodeId: ID, pageY: number, locationY: number, nodeIndex: number) => {
@@ -165,9 +251,10 @@ 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;
+                containerWidthRef.current = w;
                 containerHeightRef.current = h;
 
                 // Find the node in flattened list
@@ -187,12 +274,11 @@ export function useDragDrop<ID>(
                 draggedNodeRef.current = node;
                 draggedNodeIdRef.current = nodeId;
                 draggedNodeIndexRef.current = nodeIndex;
+                draggedSubtreeDepthRef.current = getSubtreeDepth(nodeId);
 
-                // Use measured item height if available, fall back to estimatedItemSize
+                // Use measured item height if available, fall back to default
                 const measured = measuredItemHeightRef.current;
-                const estimatedSize =
-                    (flashListRef.current as any)?.props?.estimatedItemSize ?? 36;
-                itemHeightRef.current = measured > 0 ? measured : estimatedSize;
+                itemHeightRef.current = measured > 0 ? measured : 36;
 
                 // Calculate headerOffset dynamically:
                 // fingerLocalY = pageY - containerPageY
@@ -207,9 +293,8 @@ export function useDragDrop<ID>(
 
                 // Delta-based auto-scroll: compute finger's position in the container
                 // from the node's known index (avoids unreliable containerPageY).
-                // The FlashList header (padding:5 → ~10px) + nodeIndex * itemHeight - scroll + locationY
                 const iH = itemHeightRef.current;
-                const listHeaderHeight = 10; // HeaderFooterView has padding: 5 → 10px total
+                const listHeaderHeight = listHeaderFooterPadding * 2;
                 initialFingerPageYRef.current = pageY;
                 initialFingerContainerYRef.current =
                     listHeaderHeight + nodeIndex * iH - scrollOffsetRef.current + locationY;
@@ -223,7 +308,7 @@ export function useDragDrop<ID>(
                 store.getState().updateInvalidDragTargetIds(descendants);
 
                 // Set overlay initial position (with configurable offset)
-                const overlayLocalY = fingerLocalY - locationY + dragOverlayOffset * itemHeightRef.current;
+                const overlayLocalY = fingerLocalY - locationY + (dragOverlayOffsetRef.current + PLATFORM_OVERLAY_Y_CORRECTION) * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
                 // Reset magnetic overlay
@@ -238,6 +323,9 @@ export function useDragDrop<ID>(
                 setEffectiveDropLevel(node.level ?? 0);
                 setDropTarget(null);
 
+                // Notify consumer that drag has started
+                onDragStartRef.current?.({ draggedNodeId: nodeId });
+
                 // Start auto-scroll loop
                 startAutoScrollLoop();
             });
@@ -249,6 +337,7 @@ export function useDragDrop<ID>(
             containerRef,
             flashListRef,
             getDescendantIds,
+            getSubtreeDepth,
             overlayY,
         ]
     );
@@ -258,6 +347,12 @@ export function useDragDrop<ID>(
         (nodeId: ID, pageY: number, locationY: number, nodeIndex: number) => {
             if (!dragEnabled) return;
 
+            // Check if this node can be dragged
+            if (canDragRef.current) {
+                const node = flattenedNodesRef.current[nodeIndex];
+                if (node && !canDragRef.current(node)) return;
+            }
+
             // Cancel any existing timer
             cancelLongPressTimer();
 
@@ -281,7 +376,7 @@ export function useDragDrop<ID>(
                     scrollOffsetRef.current + autoScrollSpeedRef.current
                 );
                 scrollOffsetRef.current = newOffset;
-                (flashListRef.current as any)?.scrollToOffset?.({
+                flashListRef.current?.scrollToOffset?.({
                     offset: newOffset,
                     animated: false,
                 });
@@ -302,8 +397,8 @@ export function useDragDrop<ID>(
 
     const updateAutoScroll = useCallback(
         (fingerInContainer: number) => {
-            const threshold = autoScrollThreshold;
-            const maxSpeed = 8 * autoScrollSpeed;
+            const threshold = autoScrollThresholdRef.current;
+            const maxSpeed = 8 * autoScrollSpeedParamRef.current;
             const containerH = containerHeightRef.current;
 
             if (fingerInContainer < threshold) {
@@ -319,7 +414,7 @@ export function useDragDrop<ID>(
                 autoScrollSpeedRef.current = 0;
             }
         },
-        [autoScrollThreshold, autoScrollSpeed]
+        []
     );
 
     // --- Cancel auto-expand timer ---
@@ -357,14 +452,34 @@ export function useDragDrop<ID>(
             const positionInItem =
                 (adjustedContentY - clampedIndex * iH) / iH;
             let position: "above" | "below" | "inside";
-            if (positionInItem < 0.15) {
+            if (positionInItem < 0.25) {
                 position = "above";
-            } else if (positionInItem > 0.85) {
+            } else if (positionInItem > 0.75) {
                 position = "below";
             } else {
                 position = "inside";
             }
 
+            // --- Determine if "inside" drop is allowed for this target ---
+            const canDropInsideTarget = (() => {
+                // canNodeHaveChildren: structural constraint
+                if (canNodeHaveChildrenRef.current && !canNodeHaveChildrenRef.current(targetNode)) {
+                    return false;
+                }
+                // maxDepth: the dragged subtree at (targetLevel + 1) must not exceed maxDepth
+                if (maxDepthRef.current !== undefined) {
+                    const targetLevel = targetNode.level ?? 0;
+                    const deepest = targetLevel + 1 + draggedSubtreeDepthRef.current;
+                    if (deepest > maxDepthRef.current) return false;
+                }
+                return true;
+            })();
+
+            // If "inside" is not allowed, convert to nearest zone
+            if (position === "inside" && !canDropInsideTarget) {
+                position = positionInItem < 0.5 ? "above" : "below";
+            }
+
             // --- Horizontal control at level cliffs ---
             // At the boundary between nodes at different depths, the user's
             // horizontal finger position decides the drop level:
@@ -378,7 +493,7 @@ export function useDragDrop<ID>(
             let logicalPosition: "above" | "below" | "inside" | null = null;
             let visualDropLevel: number | null = null;
 
-            if (position === "below" || position === "inside") {
+            if (position === "below") {
                 const currentLevel = targetNode.level ?? 0;
                 let isCliff = false;
                 let shallowLevel = 0;
@@ -397,10 +512,9 @@ export function useDragDrop<ID>(
                 }
 
                 if (isCliff) {
-                    // Generous threshold: midpoint of the two levels + 2× indent buffer
-                    const threshold =
-                        ((currentLevel + shallowLevel) / 2) * indentationMultiplier
-                        + indentationMultiplier * 2;
+                    // Midpoint of the item's visible content area
+                    const itemLeftEdge = currentLevel * indentationMultiplierRef.current;
+                    const threshold = itemLeftEdge + (containerWidthRef.current - itemLeftEdge) * 0.3;
 
                     if (fingerLocalX < threshold) {
                         // User wants the shallow level
@@ -434,10 +548,8 @@ export function useDragDrop<ID>(
                 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;
+                    const itemLeftEdge = prevLevel * indentationMultiplierRef.current;
+                    const threshold = itemLeftEdge + (containerWidthRef.current - itemLeftEdge) * 0.3;
 
                     if (fingerLocalX >= threshold) {
                         clampedIndex = clampedIndex - 1;
@@ -447,25 +559,15 @@ export function useDragDrop<ID>(
                 }
             }
 
-            // --- 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") {
+            // --- Suppress "below" when it's semantically confusing ---
+            // For expanded parents, "below" visually sits at the parent/child
+            // junction but semantically inserts as a sibling after the entire
+            // subtree. Convert to "inside" which is clearer.
+            if (position === "below" && canDropInsideTarget) {
                 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" ---
@@ -500,9 +602,24 @@ export function useDragDrop<ID>(
             const store = getTreeViewStore<ID>(storeId);
             const { invalidDragTargetIds, draggedNodeId, expanded } =
                 store.getState();
+
+            // maxDepth check for above/below (sibling) positions
+            let maxDepthValid = true;
+            if (maxDepthRef.current !== undefined && (position === "above" || position === "below")) {
+                const targetLevel = targetNode.level ?? 0;
+                const deepest = targetLevel + draggedSubtreeDepthRef.current;
+                if (deepest > maxDepthRef.current) maxDepthValid = false;
+            }
+
             const isValid =
                 targetNode.id !== draggedNodeId &&
-                !invalidDragTargetIds.has(targetNode.id);
+                !invalidDragTargetIds.has(targetNode.id) &&
+                maxDepthValid &&
+                (!canDropRef.current || canDropRef.current(
+                    draggedNodeRef.current!,
+                    targetNode,
+                    position
+                ));
 
             // --- Auto-expand: if hovering "inside" a collapsed expandable node ---
             if (isValid && position === "inside" && targetNode.children?.length && !expanded.has(targetNode.id)) {
@@ -513,9 +630,9 @@ export function useDragDrop<ID>(
                     autoExpandTimerRef.current = setTimeout(() => {
                         autoExpandTimerRef.current = null;
                         // Expand the node and track it
-                        handleToggleExpand(storeId, targetNode.id);
+                        expandNodes(storeId, [targetNode.id]);
                         autoExpandedDuringDragRef.current.add(targetNode.id);
-                    }, autoExpandDelay);
+                    }, autoExpandDelayRef.current);
                 }
             } else {
                 // Not hovering inside a collapsed expandable node - cancel timer
@@ -547,7 +664,7 @@ export function useDragDrop<ID>(
                 // then spring to 0 for a smooth "magnetic snap" transition.
                 if (prevLevel !== effectiveLevel) {
                     overlayX.setValue(
-                        (prevLevel - effectiveLevel) * indentationMultiplier
+                        (prevLevel - effectiveLevel) * indentationMultiplierRef.current
                     );
                     Animated.spring(overlayX, {
                         toValue: 0,
@@ -599,7 +716,7 @@ export function useDragDrop<ID>(
                 return newTarget;
             });
         },
-        [storeId, autoExpandDelay, cancelAutoExpandTimer, indentationMultiplier, overlayX]
+        [storeId, cancelAutoExpandTimer, overlayX]
     );
 
     // --- Handle drag end ---
@@ -673,32 +790,25 @@ export function useDragDrop<ID>(
                     newTreeData: newData,
                 });
 
-                // 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) 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);
+                // Auto-scroll to the dropped node unless disabled by the user.
+                const scrollOpts = autoScrollToDroppedNode;
+                const scrollEnabled = scrollOpts === undefined || scrollOpts === true
+                    || (typeof scrollOpts === "object" && scrollOpts.enabled !== false);
+
+                if (scrollEnabled) {
+                    const custom = typeof scrollOpts === "object" ? scrollOpts : {};
+                    setTimeout(() => {
+                        scrollToNodeHandlerRef.current?.scrollToNodeID({
+                            nodeId: droppedNodeId,
+                            animated: custom.animated ?? true,
+                            viewPosition: custom.viewPosition ?? 0.5,
+                            viewOffset: custom.viewOffset,
+                        });
+                    }, 0);
+                }
+            } else if (droppedNodeId !== null) {
+                // Drag ended without a valid drop - notify consumer
+                onDragCancelRef.current?.({ draggedNodeId: droppedNodeId });
             }
 
             // Collapse auto-expanded nodes that aren't ancestors of the drop target
@@ -791,7 +901,7 @@ export function useDragDrop<ID>(
 
                 // Update overlay position (with configurable offset)
                 const overlayLocalY =
-                    fingerLocalY - grabOffsetYRef.current + dragOverlayOffset * itemHeightRef.current;
+                    fingerLocalY - grabOffsetYRef.current + (dragOverlayOffsetRef.current + PLATFORM_OVERLAY_Y_CORRECTION) * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
                 // Calculate drop target (horizontal position used at level cliffs)