react-native-tree-multi-select 3.0.0-beta.2 → 3.0.0-beta.4

package/src/hooks/useDragDrop.ts

@@ -1,4 +1,11 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+    MutableRefObject,
+    RefObject,
+    useCallback,
+    useEffect,
+    useRef,
+    useState
+} from "react";
 import {
     Animated,
     PanResponder,
@@ -7,27 +14,44 @@ import {
 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 { 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";
 
 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;
+    /** Callback to determine if a node can be dragged. */
+    canDrag?: (node: TreeNode<ID>) => boolean;
 }
 
 interface UseDragDropReturn<ID> {
@@ -46,8 +70,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 +83,9 @@ export function useDragDrop<ID>(
         flashListRef,
         containerRef,
         dragEnabled,
+        onDragStart,
         onDragEnd,
+        onDragCancel,
         longPressDuration,
         autoScrollThreshold,
         autoScrollSpeed,
@@ -68,6 +94,10 @@ export function useDragDrop<ID>(
         dragOverlayOffset,
         autoExpandDelay,
         indentationMultiplier,
+        canDrop: canDropCallback,
+        maxDepth,
+        canNodeHaveChildren,
+        canDrag,
     } = params;
 
     // --- Refs for mutable state (no stale closures in PanResponder) ---
@@ -107,15 +137,42 @@ export function useDragDrop<ID>(
     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);
+
+    // 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);
@@ -123,7 +180,7 @@ export function useDragDrop<ID>(
     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 ---
@@ -157,6 +214,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) => {
@@ -187,12 +260,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 +279,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 +294,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 * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
                 // Reset magnetic overlay
@@ -238,6 +309,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 +323,7 @@ export function useDragDrop<ID>(
             containerRef,
             flashListRef,
             getDescendantIds,
+            getSubtreeDepth,
             overlayY,
         ]
     );
@@ -258,6 +333,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 +362,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 +383,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 +400,7 @@ export function useDragDrop<ID>(
                 autoScrollSpeedRef.current = 0;
             }
         },
-        [autoScrollThreshold, autoScrollSpeed]
+        []
     );
 
     // --- Cancel auto-expand timer ---
@@ -365,6 +446,26 @@ export function useDragDrop<ID>(
                 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:
@@ -391,16 +492,17 @@ export function useDragDrop<ID>(
                         shallowLevel = nextLevel;
                     }
                 } else if (currentLevel > 0) {
-                    // Last item in the list — treat as cliff to root level
+                    // 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 indent = indentationMultiplierRef.current;
                     const threshold =
-                        ((currentLevel + shallowLevel) / 2) * indentationMultiplier
-                        + indentationMultiplier * 2;
+                        ((currentLevel + shallowLevel) / 2) * indent
+                        + indent * 2;
 
                     if (fingerLocalX < threshold) {
                         // User wants the shallow level
@@ -434,10 +536,11 @@ export function useDragDrop<ID>(
                 const prevLevel = prevNode?.level ?? 0;
                 const currentLevel = targetNode.level ?? 0;
                 if (prevNode && prevLevel > currentLevel) {
-                    // Level cliff above — same generous threshold
+                    // Level cliff above - same generous threshold
+                    const indent = indentationMultiplierRef.current;
                     const threshold =
-                        ((prevLevel + currentLevel) / 2) * indentationMultiplier
-                        + indentationMultiplier * 2;
+                        ((prevLevel + currentLevel) / 2) * indent
+                        + indent * 2;
 
                     if (fingerLocalX >= threshold) {
                         clampedIndex = clampedIndex - 1;
@@ -450,7 +553,8 @@ 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") {
+            // Only convert to "inside" if inside drops are allowed for this target.
+            if (position === "below" && canDropInsideTarget) {
                 const expandedSet = getTreeViewStore<ID>(storeId).getState().expanded;
 
                 // (a) Expanded parent: "below" visually sits at the parent/child junction
@@ -485,10 +589,10 @@ export function useDragDrop<ID>(
                     const lowerLevel = nodes[lowerIdx]?.level ?? 0;
 
                     if (upperLevel === lowerLevel) {
-                        // Same level — pure visual hysteresis, keep previous
+                        // Same level - pure visual hysteresis, keep previous
                         return;
                     }
-                    // Level cliff — horizontal control already resolved this,
+                    // Level cliff - horizontal control already resolved this,
                     // let the result pass through.
                 }
             }
@@ -500,14 +604,29 @@ 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)) {
                 if (autoExpandTargetRef.current !== targetNode.id) {
-                    // New hover target — start timer
+                    // New hover target - start timer
                     cancelAutoExpandTimer();
                     autoExpandTargetRef.current = targetNode.id;
                     autoExpandTimerRef.current = setTimeout(() => {
@@ -515,10 +634,10 @@ export function useDragDrop<ID>(
                         // Expand the node and track it
                         handleToggleExpand(storeId, targetNode.id);
                         autoExpandedDuringDragRef.current.add(targetNode.id);
-                    }, autoExpandDelay);
+                    }, autoExpandDelayRef.current);
                 }
             } else {
-                // Not hovering inside a collapsed expandable node — cancel timer
+                // Not hovering inside a collapsed expandable node - cancel timer
                 if (autoExpandTargetRef.current !== null) {
                     cancelAutoExpandTimer();
                 }
@@ -547,7 +666,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 +718,7 @@ export function useDragDrop<ID>(
                 return newTarget;
             });
         },
-        [storeId, autoExpandDelay, cancelAutoExpandTimer, indentationMultiplier, overlayX]
+        [storeId, cancelAutoExpandTimer, overlayX]
     );
 
     // --- Handle drag end ---
@@ -673,18 +792,35 @@ 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);
+            } 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
@@ -777,13 +913,13 @@ export function useDragDrop<ID>(
 
                 // Update overlay position (with configurable offset)
                 const overlayLocalY =
-                    fingerLocalY - grabOffsetYRef.current + dragOverlayOffset * itemHeightRef.current;
+                    fingerLocalY - grabOffsetYRef.current + dragOverlayOffsetRef.current * itemHeightRef.current;
                 overlayY.setValue(overlayLocalY);
 
                 // 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);

package/src/{handlers/ScrollToNodeHandler.tsx → hooks/useScrollToNode.ts}

@@ -1,7 +1,7 @@
 /**
- * ScrollToNodeHandler Component
+ * useScrollToNode Hook
  *
- * This component provides an imperative handle to scroll to a specified node within a tree view.
+ * Provides an imperative handle to scroll to a specified node within a tree view.
  * The scrolling action is orchestrated via a two-step "milestone" mechanism that ensures the target
  * node is both expanded in the tree and that the rendered list reflects this expansion before the scroll
  * is performed.
@@ -32,22 +32,23 @@
  * in the UI, thus preventing issues with attempting to scroll to an element that does not exist yet.
  */
 
-import React from "react";
+import {
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type Dispatch,
+  type MutableRefObject,
+  type RefObject,
+  type SetStateAction,
+} from "react";
 import { expandNodes } from "../helpers/expandCollapse.helper";
 import { useTreeViewStore } from "../store/treeView.store";
 import { useShallow } from "zustand/react/shallow";
 import { type __FlattenedTreeNode__ } from "../types/treeView.types";
-import { typedMemo } from "../utils/typedMemo";
 import { fastIsEqual } from "fast-is-equal";
 
-interface Props<ID> {
-  storeId: string;
-  flashListRef: React.MutableRefObject<any>;
-  flattenedFilteredNodes: __FlattenedTreeNode__<ID>[];
-  setInitialScrollIndex: React.Dispatch<React.SetStateAction<number>>;
-  initialScrollNodeID: ID | undefined;
-}
-
 export interface ScrollToNodeParams<ID> {
   nodeId: ID;
   expandScrolledNode?: boolean;
@@ -57,27 +58,34 @@ export interface ScrollToNodeParams<ID> {
   viewPosition?: number;
 }
 
+export interface ScrollToNodeHandlerRef<ID> {
+  scrollToNodeID: (params: ScrollToNodeParams<ID>) => void;
+}
+
 // Enum representing the two milestones needed before scrolling
 enum ExpandQueueAction {
   EXPANDED,
   RENDERED,
 }
 
-export interface ScrollToNodeHandlerRef<ID> {
-  scrollToNodeID: (params: ScrollToNodeParams<ID>) => void;
+interface UseScrollToNodeParams<ID> {
+  storeId: string;
+  scrollToNodeHandlerRef: RefObject<ScrollToNodeHandlerRef<ID>>;
+  flashListRef: MutableRefObject<any>;
+  flattenedFilteredNodes: __FlattenedTreeNode__<ID>[];
+  setInitialScrollIndex: Dispatch<SetStateAction<number>>;
+  initialScrollNodeID: ID | undefined;
 }
 
-function _innerScrollToNodeHandler<ID>(
-  props: Props<ID>,
-  ref: React.ForwardedRef<ScrollToNodeHandlerRef<ID>>
-) {
+export function useScrollToNode<ID>(params: UseScrollToNodeParams<ID>) {
   const {
     storeId,
+    scrollToNodeHandlerRef,
     flashListRef,
     flattenedFilteredNodes,
     setInitialScrollIndex,
     initialScrollNodeID
-  } = props;
+  } = params;
 
   const { expanded, childToParentMap } = useTreeViewStore<ID>(storeId)(useShallow(
     state => ({
@@ -86,9 +94,16 @@ function _innerScrollToNodeHandler<ID>(
     })
   ));
 
-  React.useImperativeHandle(ref, () => ({
-    scrollToNodeID: (params: ScrollToNodeParams<ID>) => {
-      queuedScrollToNodeParams.current = params;
+  // Ref to store the scroll parameters for the queued action.
+  const queuedScrollToNodeParams = useRef<ScrollToNodeParams<ID> | null>(null);
+
+  // State to track progression: first the expansion is triggered, then the list is rendered.
+  const [expandAndScrollToNodeQueue, setExpandAndScrollToNodeQueue]
+    = useState<ExpandQueueAction[]>([]);
+
+  useImperativeHandle(scrollToNodeHandlerRef, () => ({
+    scrollToNodeID: (scrollParams: ScrollToNodeParams<ID>) => {
+      queuedScrollToNodeParams.current = scrollParams;
       // Mark that expansion is initiated.
       setExpandAndScrollToNodeQueue([ExpandQueueAction.EXPANDED]);
       // Trigger expansion logic (this may update the store and subsequently re-render the list).
@@ -100,18 +115,11 @@ function _innerScrollToNodeHandler<ID>(
     }
   }), [storeId]);
 
-  // Ref to store the scroll parameters for the queued action.
-  const queuedScrollToNodeParams = React.useRef<ScrollToNodeParams<ID> | null>(null);
-
-  // State to track progression: first the expansion is triggered, then the list is rendered.
-  const [expandAndScrollToNodeQueue, setExpandAndScrollToNodeQueue]
-    = React.useState<ExpandQueueAction[]>([]);
-
-  const latestFlattenedFilteredNodesRef = React.useRef(flattenedFilteredNodes);
+  const latestFlattenedFilteredNodesRef = useRef(flattenedFilteredNodes);
 
   /* When the rendered node list changes, update the ref.
   If an expansion was triggered, mark that the list is now rendered. */
-  React.useEffect(() => {
+  useEffect(() => {
     setExpandAndScrollToNodeQueue(prevQueue => {
       if (prevQueue.includes(ExpandQueueAction.EXPANDED)) {
         latestFlattenedFilteredNodesRef.current = flattenedFilteredNodes;
@@ -127,7 +135,7 @@ function _innerScrollToNodeHandler<ID>(
 
   /* Once the target node is expanded and the list is updated (milestones reached),
   perform the scroll using the latest node list. */
-  React.useLayoutEffect(() => {
+  useLayoutEffect(() => {
     if (queuedScrollToNodeParams.current === null)
       return;
 
@@ -146,12 +154,16 @@ function _innerScrollToNodeHandler<ID>(
         parentId = childToParentMap.get(queuedScrollToNodeParams.current.nodeId) as ID;
       }
 
-      // Ensure if the parent is expanded before proceeding to scroll to the node
+      // Ensure if the parent is expanded before proceeding to scroll to the node.
+      // This fires transiently during the milestone system — the layout effect runs
+      // before the expansion has propagated to the store, then retries on next render.
+      /* istanbul ignore next -- async timing guard: expansion not yet propagated to store */
       if (parentId && !expanded.has(parentId))
         return;
     }
     // If node is set to expand
     else {
+      /* istanbul ignore next -- async timing guard: node expansion not yet propagated */
       if (!expanded.has(queuedScrollToNodeParams.current.nodeId))
         return;
     }
@@ -177,6 +189,7 @@ function _innerScrollToNodeHandler<ID>(
           viewPosition
         });
       } else {
+        /* istanbul ignore next -- __DEV__ is false in test/production */
         if (__DEV__) {
           console.info("Cannot find the item of the mentioned id to scroll in the rendered tree view list data!");
         }
@@ -193,8 +206,8 @@ function _innerScrollToNodeHandler<ID>(
   ////////////////////////////// Handle Initial Scroll /////////////////////////////
   /* On first render, if an initial scroll target is provided, determine its index.
   This is done only once. */
-  const initialScrollDone = React.useRef(false);
-  React.useLayoutEffect(() => {
+  const initialScrollDone = useRef(false);
+  useLayoutEffect(() => {
     if (initialScrollDone.current) return;
 
     const index = flattenedFilteredNodes.findIndex(
@@ -209,14 +222,4 @@ function _innerScrollToNodeHandler<ID>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [flattenedFilteredNodes, initialScrollNodeID]);
   /////////////////////////////////////////////////////////////////////////////////
-
-  return null;
 }
-
-const _ScrollToNodeHandler = React.forwardRef(_innerScrollToNodeHandler) as <ID>(
-  props: Props<ID> & { ref?: React.ForwardedRef<ScrollToNodeHandlerRef<ID>>; }
-) => ReturnType<typeof _innerScrollToNodeHandler>;
-
-export const ScrollToNodeHandler = typedMemo<
-  typeof _ScrollToNodeHandler
->(_ScrollToNodeHandler);