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

package/src/components/NodeList.tsx

@@ -9,8 +9,11 @@ import {
     View,
     StyleSheet,
     TouchableOpacity,
+    Platform,
     type NativeSyntheticEvent,
     type NativeScrollEvent,
+    type GestureResponderEvent,
+    type LayoutChangeEvent,
 } from "react-native";
 import { FlashList } from "@shopify/flash-list";
 
@@ -19,7 +22,6 @@ import type {
     DropIndicatorStyleProps,
     NodeListProps,
     NodeProps,
-    TreeNode,
 } from "../types/treeView.types";
 
 import { useTreeViewStore } from "../store/treeView.store";
@@ -37,6 +39,7 @@ import { DragOverlay } from "./DragOverlay";
 import type { DropPosition } from "../types/dragDrop.types";
 import {
     defaultIndentationMultiplier,
+    defaultItemHeight,
     listHeaderFooterPadding
 } from "../constants/treeView.constants";
 import { useShallow } from "zustand/react/shallow";
@@ -74,18 +77,25 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
         longPressDuration = 400,
         autoScrollThreshold = 60,
         autoScrollSpeed = 1.0,
-        dragOverlayOffset = -4,
+        dragOverlayOffset = -2,
+        overlayYCorrection,
         autoExpandDelay = 800,
+        autoExpand = true,
+        magneticSnap = true,
         customizations: dragDropCustomizations,
         canDrop: canDropCallback,
         maxDepth,
         canNodeHaveChildren,
         canDrag,
+        autoScrollToDroppedNode,
     } = dragAndDrop ?? {};
 
-    // When the dragAndDrop prop is provided, drag is enabled by default.
-    // Users can still toggle it off with enabled: false at runtime.
-    const dragEnabled = dragAndDrop ? (_dragEnabled ?? true) : false;
+    // When the dragAndDrop prop is provided, drag is enabled by default on native
+    // (iOS/Android). On web it defaults OFF because the PanResponder-based drag is
+    // still a work in progress there - consumers can opt in with `enabled: true`.
+    const dragEnabled = dragAndDrop
+        ? (_dragEnabled ?? Platform.OS !== "web")
+        : false;
 
     const {
         expanded,
@@ -105,15 +115,32 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
 
     const flashListRef = useRef<FlashList<__FlattenedTreeNode__<ID>> | null>(null);
     const containerRef = useRef<View>(null);
-    const internalDataRef = useRef<TreeNode<ID>[] | null>(null);
     const measuredItemHeightRef = useRef(0);
-
-    const handleItemLayout = useCallback((height: number) => {
-        if (measuredItemHeightRef.current === 0 && height > 0) {
-            measuredItemHeightRef.current = height;
+    const contentHeightRef = useRef(0);
+    // Measured row heights keyed by stable node id (NOT flattened index, which is
+    // reused by different nodes across expand/collapse/filter/reorder). Used for
+    // accurate drop targeting with variable-height rows when the whole list is
+    // rendered. Keying by id means a stale entry can never satisfy the
+    // "all current rows measured" gate in useDragDrop.
+    const itemHeightsRef = useRef<Map<ID, number>>(new Map());
+
+    const handleItemLayout = useCallback((id: ID, height: number) => {
+        if (height > 0) {
+            itemHeightsRef.current.set(id, height);
+            // First measured height seeds the uniform fallback used while
+            // virtualization keeps some rows unmeasured.
+            if (measuredItemHeightRef.current === 0) {
+                measuredItemHeightRef.current = height;
+            }
         }
     }, []);
 
+    // Measured heights of removed nodes would otherwise accumulate forever on
+    // dynamic trees; clear on structural change and let rows re-measure on layout.
+    useEffect(() => {
+        itemHeightsRef.current.clear();
+    }, [initialTreeViewData]);
+
     const [initialScrollIndex, setInitialScrollIndex] = useState<number>(-1);
 
     // First we filter the tree as per the search term and keys
@@ -155,11 +182,10 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
         overlayX,
         isDragging,
         draggedNode,
-        effectiveDropLevel,
         handleNodeTouchStart,
         handleNodeTouchEnd,
-        cancelLongPressTimer,
-        scrollOffsetRef,
+        handleScroll: dragHandleScroll,
+        containerHeightRef,
     } = useDragDrop<ID>({
         storeId,
         flattenedNodes: flattenedFilteredNodes,
@@ -172,27 +198,44 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
         longPressDuration,
         autoScrollThreshold,
         autoScrollSpeed,
-        internalDataRef,
         measuredItemHeightRef,
+        contentHeightRef,
+        itemHeightsRef,
         dragOverlayOffset,
+        overlayYCorrection,
         autoExpandDelay,
+        autoExpand,
+        magneticSnap,
         indentationMultiplier: effectiveIndentationMultiplier,
         canDrop: canDropCallback,
         maxDepth,
         canNodeHaveChildren,
         canDrag,
+        scrollToNodeHandlerRef,
+        autoScrollToDroppedNode,
     });
 
-    // Combined onScroll handler
+    // The hook owns scroll-offset bookkeeping (single-writer during drag,
+    // long-press cancellation); this wrapper just forwards to the user's onScroll.
     const handleScroll = useCallback((
         event: NativeSyntheticEvent<NativeScrollEvent>
     ) => {
-        scrollOffsetRef.current = event.nativeEvent.contentOffset.y;
-        // Cancel long press timer if user is scrolling
-        cancelLongPressTimer();
-        // Forward to user's onScroll
+        dragHandleScroll(event);
         treeFlashListProps?.onScroll?.(event as any);
-    }, [scrollOffsetRef, cancelLongPressTimer, treeFlashListProps]);
+    }, [dragHandleScroll, treeFlashListProps]);
+
+    // Track total content height so auto-scroll during drag can clamp to the
+    // scrollable range.
+    const handleContentSizeChange = useCallback((width: number, height: number) => {
+        contentHeightRef.current = height;
+        treeFlashListProps?.onContentSizeChange?.(width, height);
+    }, [contentHeightRef, treeFlashListProps]);
+
+    // Keep the container height fresh on resize (orientation change, keyboard, split
+    // view) so auto-scroll edge detection and clamping don't go stale mid-session.
+    const handleContainerLayout = useCallback((e: LayoutChangeEvent) => {
+        containerHeightRef.current = e.nativeEvent.layout.height;
+    }, [containerHeightRef]);
 
     const nodeRenderer = useCallback((
         { item, index }: { item: __FlattenedTreeNode__<ID>; index: number; }
@@ -237,14 +280,17 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
         handleItemLayout,
     ]);
 
-    // Extract FlashList props but exclude onScroll (we provide our own combined handler)
+    // Extract FlashList props but exclude onScroll / onContentSizeChange (we provide
+    // our own combined handlers that still forward to the user's callbacks)
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { onScroll: _userOnScroll, ...restFlashListProps } = treeFlashListProps ?? {};
+    const { onScroll: _userOnScroll, onContentSizeChange: _userOnContentSizeChange, ...restFlashListProps } = treeFlashListProps ?? {};
 
     const flashListElement = (
         <FlashList
             ref={flashListRef}
-            estimatedItemSize={36}
+            // estimatedItemSize is used by FlashList v1; v2 auto-measures and ignores
+            // it. Consumers can override via treeFlashListProps (spread below).
+            estimatedItemSize={defaultItemHeight}
             initialScrollIndex={initialScrollIndex}
             removeClippedSubviews={true}
             keyboardShouldPersistTaps="handled"
@@ -253,6 +299,7 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
             ListFooterComponent={<HeaderFooterView />}
             {...restFlashListProps}
             onScroll={handleScroll}
+            onContentSizeChange={handleContentSizeChange}
             scrollEnabled={isDragging ? false : (restFlashListProps?.scrollEnabled ?? true)}
             data={flattenedFilteredNodes}
             renderItem={nodeRenderer}
@@ -265,6 +312,7 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
                 <View
                     ref={containerRef}
                     style={styles.dragContainer}
+                    onLayout={handleContainerLayout}
                     {...panResponder.panHandlers}
                 >
                     {flashListElement}
@@ -274,7 +322,10 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
                             overlayY={overlayY}
                             overlayX={overlayX}
                             node={draggedNode}
-                            level={effectiveDropLevel}
+                            /* Constant for the whole drag: the level shift toward the
+                               drop target is expressed via the overlayX translate, not
+                               a re-render (which caused visible indent flicker). */
+                            level={draggedNode.level ?? 0}
                             indentationMultiplier={effectiveIndentationMultiplier}
                             CheckboxComponent={CheckboxComponent}
                             ExpandCollapseIconComponent={ExpandCollapseIconComponent}
@@ -372,7 +423,7 @@ function _Node<ID>(props: NodeProps<ID>) {
         toggleCheckboxes(storeId, [node.id]);
     }, [storeId, node.id]);
 
-    const handleTouchStart = useCallback((e: any) => {
+    const handleTouchStart = useCallback((e: GestureResponderEvent) => {
         wasDraggedRef.current = false;
         if (!onNodeTouchStart) return;
         const { pageY, locationY } = e.nativeEvent;
@@ -385,7 +436,7 @@ function _Node<ID>(props: NodeProps<ID>) {
 
     // Determine opacity for drag state (separate values for dragged node vs invalid targets).
     // When CustomNodeRowComponent is used, hand off all visual control
-    // (including drag opacity) to the custom component — it receives
+    // (including drag opacity) to the custom component - it receives
     // isDraggedNode / isInvalidDropTarget / isDragging props.
     const draggedOpacity = dragDropCustomizations?.draggedNodeOpacity ?? 0.3;
     const invalidOpacity = dragDropCustomizations?.invalidTargetOpacity ?? 0.3;
@@ -395,9 +446,9 @@ function _Node<ID>(props: NodeProps<ID>) {
             ? (isBeingDragged ? draggedOpacity : isDragInvalid ? invalidOpacity : 1.0)
             : 1.0;
 
-    const handleLayout = useCallback((e: any) => {
-        onItemLayout?.(e.nativeEvent.layout.height);
-    }, [onItemLayout]);
+    const handleLayout = useCallback((e: LayoutChangeEvent) => {
+        onItemLayout?.(node.id, e.nativeEvent.layout.height);
+    }, [onItemLayout, node.id]);
 
     const touchHandlers = dragEnabled ? {
         onTouchStart: handleTouchStart,
@@ -486,6 +537,8 @@ function NodeDropIndicator({ position, level, indentationMultiplier, styleProps
     const circleSize = styleProps?.circleSize ?? 10;
     const highlightColor = styleProps?.highlightColor ?? "rgba(0, 120, 255, 0.15)";
     const highlightBorderColor = styleProps?.highlightBorderColor ?? "rgba(0, 120, 255, 0.5)";
+    const highlightBorderWidth = styleProps?.highlightBorderWidth ?? 2;
+    const highlightBorderRadius = styleProps?.highlightBorderRadius ?? 4;
 
     // Indent the line to match the node's nesting level so users can
     // visually distinguish drops at different tree depths.
@@ -501,6 +554,8 @@ function NodeDropIndicator({ position, level, indentationMultiplier, styleProps
                         left: leftOffset,
                         backgroundColor: highlightColor,
                         borderColor: highlightBorderColor,
+                        borderWidth: highlightBorderWidth,
+                        borderRadius: highlightBorderRadius,
                     },
                 ]}
             />

package/src/constants/treeView.constants.ts

@@ -1,4 +1,9 @@
 export const defaultIndentationMultiplier = 15;
 
 /** Padding used by the FlashList header/footer component. Total header height = 2 * this value. */
-export const listHeaderFooterPadding = 5;
+export const listHeaderFooterPadding = 5;
+
+/** Estimated/default row height in px. Used as FlashList's estimatedItemSize and as
+ *  the drag-and-drop fallback height before a row has been measured (kept in one
+ *  place so the two never silently diverge). */
+export const defaultItemHeight = 36;

package/src/helpers/moveTreeNode.helper.ts

@@ -1,5 +1,9 @@
 import type { TreeNode } from "../types/treeView.types";
 import type { DropPosition } from "../types/dragDrop.types";
+import { getTreeViewStore } from "../store/treeView.store";
+import { initializeNodeMaps } from "./treeNode.helper";
+import { recalculateCheckedStates } from "./toggleCheckbox.helper";
+import { expandNodes } from "./expandCollapse.helper";
 
 /**
  * Move a node within a tree structure. Returns a new tree (no mutation).
@@ -35,65 +39,176 @@ export function moveTreeNode<ID>(
     return cloned;
 }
 
+/**
+ * Commit the result of a `moveTreeNode` to the store: swap in the new tree,
+ * rebuild the node maps, recalculate parent checked/indeterminate states, and
+ * expand whatever is needed to make the moved node visible ("inside" drops
+ * expand the target; ancestors of the moved node are always expanded).
+ *
+ * Shared by the interactive drag commit (useDragDrop.handleDragEnd) and the
+ * programmatic `TreeViewRef.moveNode` so the two paths cannot drift.
+ */
+export function applyMoveToStore<ID>(
+    storeId: string,
+    newData: TreeNode<ID>[],
+    movedNodeId: ID,
+    targetNodeId: ID,
+    position: DropPosition
+): void {
+    const store = getTreeViewStore<ID>(storeId);
+    store.getState().updateInitialTreeViewData(newData);
+    initializeNodeMaps(storeId, newData);
+    recalculateCheckedStates<ID>(storeId);
+    if (position === "inside") {
+        expandNodes(storeId, [targetNodeId]);
+    }
+    expandNodes(storeId, [movedNodeId], true);
+}
+
+/**
+ * Locate a node within a tree, returning its parent id (null at root) and its
+ * index within that parent's children (or the root array). Returns null if the
+ * node is not found. Iterative (stack-based) DFS.
+ *
+ * Used to build the lightweight `MoveResult` delta (previous/new parent + index)
+ * without exposing a full tree copy.
+ */
+export function findNodePosition<ID>(
+    data: TreeNode<ID>[],
+    nodeId: ID
+): { parentId: ID | null; index: number; } | null {
+    const stack: Array<{ nodes: TreeNode<ID>[]; parentId: ID | null; }> = [
+        { nodes: data, parentId: null }
+    ];
+    while (stack.length > 0) {
+        const { nodes, parentId } = stack.pop()!;
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i]!;
+            if (node.id === nodeId) return { parentId, index: i };
+            if (node.children?.length) {
+                stack.push({ nodes: node.children, parentId: node.id });
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * `findNodePosition` for a node that is still in the store's CURRENT tree:
+ * uses the already-built childToParentMap/nodeMap for O(depth + siblings)
+ * instead of a full-tree DFS. Only valid while the maps match `data` (i.e.
+ * before the move mutates the tree).
+ */
+export function findNodePositionFromMaps<ID>(
+    data: TreeNode<ID>[],
+    nodeMap: Map<ID, TreeNode<ID>>,
+    childToParentMap: Map<ID, ID>,
+    nodeId: ID
+): { parentId: ID | null; index: number; } | null {
+    const parentId = childToParentMap.get(nodeId);
+    const siblings = parentId !== undefined
+        ? nodeMap.get(parentId)?.children
+        : data;
+    if (!siblings) return null;
+    const index = siblings.findIndex((n) => n.id === nodeId);
+    return index === -1 ? null : { parentId: parentId ?? null, index };
+}
+
 /**
  * Check if `candidateDescendantId` is a descendant of `ancestorId` in the tree.
+ * Iterative (stack-based) DFS to avoid call-stack limits on deep trees.
  */
 function isDescendant<ID>(
     nodes: TreeNode<ID>[],
     ancestorId: ID,
     candidateDescendantId: ID,
 ): boolean {
-    for (const node of nodes) {
+    const stack: TreeNode<ID>[] = [...nodes];
+    while (stack.length > 0) {
+        const node = stack.pop()!;
         if (node.id === ancestorId) {
-            // Found the ancestor — search its subtree for the candidate
+            // Found the ancestor - search its subtree for the candidate.
+            // IDs are unique, so the first match is the only ancestor to check.
             return containsNode(node.children ?? [], candidateDescendantId);
         }
-        if (node.children && isDescendant(node.children, ancestorId, candidateDescendantId)) {
-            return true;
+        if (node.children) {
+            for (const child of node.children) stack.push(child);
         }
     }
     return false;
 }
 
-/** Check if a node with the given ID exists anywhere in the subtree. */
+/**
+ * Check if a node with the given ID exists anywhere in the subtree.
+ * Iterative (stack-based) DFS to avoid call-stack limits on deep trees.
+ */
 function containsNode<ID>(nodes: TreeNode<ID>[], nodeId: ID): boolean {
-    for (const node of nodes) {
+    const stack: TreeNode<ID>[] = [...nodes];
+    while (stack.length > 0) {
+        const node = stack.pop()!;
         if (node.id === nodeId) return true;
-        if (node.children && containsNode(node.children, nodeId)) return true;
+        if (node.children) {
+            for (const child of node.children) stack.push(child);
+        }
     }
     return false;
 }
 
-/** Deep clone a tree structure so mutations don't affect the original. */
+/**
+ * Deep clone a tree structure so mutations don't affect the original.
+ * Iterative (stack-based) clone to avoid call-stack limits on deep trees.
+ * Preserves the original shape: every node carries a `children` key
+ * (`undefined` for leaves, a cloned array - possibly empty - otherwise).
+ */
 function deepCloneTree<ID>(nodes: TreeNode<ID>[]): TreeNode<ID>[] {
-    return nodes.map(node => ({
-        ...node,
-        children: node.children ? deepCloneTree(node.children) : undefined,
-    }));
+    const root: TreeNode<ID>[] = nodes.map(node => ({ ...node, children: undefined }));
+    const stack: Array<{ src: TreeNode<ID>[]; dst: TreeNode<ID>[]; }> = [
+        { src: nodes, dst: root }
+    ];
+    while (stack.length > 0) {
+        const { src, dst } = stack.pop()!;
+        for (let i = 0; i < src.length; i++) {
+            const children = src[i]!.children;
+            if (children) {
+                const clonedChildren: TreeNode<ID>[] =
+                    children.map(child => ({ ...child, children: undefined }));
+                dst[i]!.children = clonedChildren;
+                stack.push({ src: children, dst: clonedChildren });
+            }
+        }
+    }
+    return root;
 }
 
 /**
  * Remove a node by ID from the tree. Mutates the cloned tree in-place.
  * Returns the removed node, or null if not found.
+ * Iterative (stack-based) DFS to avoid call-stack limits on deep trees.
  */
 function removeNodeById<ID>(
     nodes: TreeNode<ID>[],
     nodeId: ID,
 ): TreeNode<ID> | null {
-    for (let i = 0; i < nodes.length; i++) {
-        if (nodes[i]!.id === nodeId) {
-            const [removed] = nodes.splice(i, 1);
-            return removed!;
-        }
-        const children = nodes[i]!.children;
-        if (children) {
-            const removed = removeNodeById(children, nodeId);
-            if (removed) {
-                // Clean up empty children arrays
-                if (children.length === 0) {
-                    nodes[i] = { ...nodes[i]!, children: undefined };
+    // Each frame carries the array being scanned plus the node that owns it
+    // (null at the root) so an emptied children array can be detached.
+    const stack: Array<{ nodes: TreeNode<ID>[]; parent: TreeNode<ID> | null; }> = [
+        { nodes, parent: null }
+    ];
+    while (stack.length > 0) {
+        const { nodes: level, parent } = stack.pop()!;
+        for (let i = 0; i < level.length; i++) {
+            const node = level[i]!;
+            if (node.id === nodeId) {
+                const [removed] = level.splice(i, 1);
+                // Clean up an emptied children array on the owning parent
+                // (matches the original shape: leaves carry children: undefined).
+                if (parent && level.length === 0) {
+                    parent.children = undefined;
                 }
-                return removed;
+                return removed ?? null;
+            }
+            if (node.children?.length) {
+                stack.push({ nodes: node.children, parent: node });
             }
         }
     }
@@ -103,6 +218,7 @@ function removeNodeById<ID>(
 /**
  * Insert a node relative to a target node. Mutates the cloned tree in-place.
  * Returns true if insertion was successful.
+ * Iterative (stack-based) DFS to avoid call-stack limits on deep trees.
  */
 function insertNode<ID>(
     nodes: TreeNode<ID>[],
@@ -110,28 +226,29 @@ function insertNode<ID>(
     targetId: ID,
     position: DropPosition,
 ): boolean {
-    for (let i = 0; i < nodes.length; i++) {
-        if (nodes[i]!.id === targetId) {
-            if (position === "above") {
-                nodes.splice(i, 0, nodeToInsert);
-            } else if (position === "below") {
-                nodes.splice(i + 1, 0, nodeToInsert);
-            } else {
-                // "inside" - add as first child
-                const target = nodes[i]!;
-                if (target.children) {
-                    target.children.unshift(nodeToInsert);
+    const stack: TreeNode<ID>[][] = [nodes];
+    while (stack.length > 0) {
+        const level = stack.pop()!;
+        for (let i = 0; i < level.length; i++) {
+            const node = level[i]!;
+            if (node.id === targetId) {
+                if (position === "above") {
+                    level.splice(i, 0, nodeToInsert);
+                } else if (position === "below") {
+                    level.splice(i + 1, 0, nodeToInsert);
                 } else {
-                    nodes[i] = { ...target, children: [nodeToInsert] };
+                    // "inside" - add as first child
+                    if (node.children) {
+                        node.children.unshift(nodeToInsert);
+                    } else {
+                        node.children = [nodeToInsert];
+                    }
                 }
-            }
-            return true;
-        }
-        const children = nodes[i]!.children;
-        if (children) {
-            if (insertNode(children, nodeToInsert, targetId, position)) {
                 return true;
             }
+            if (node.children?.length) {
+                stack.push(node.children);
+            }
         }
     }
     return false;

package/src/helpers/toggleCheckbox.helper.ts

@@ -1,5 +1,6 @@
 import type { CheckboxValueType, TreeNode } from "../types/treeView.types";
 import { getTreeViewStore } from "../store/treeView.store";
+import { getNodeDepthFromParentMap } from "./treeNode.helper";
 
 /** Derive the tri-state checkbox value from checked and indeterminate booleans. */
 export function getCheckboxValue(
@@ -255,19 +256,11 @@ export function recalculateCheckedStates<ID>(storeId: string) {
     // Sort by depth descending (deepest first) for correct bottom-up propagation
     const nodeDepths = new Map<ID, number>();
     function getDepth(nodeId: ID): number {
-        if (nodeDepths.has(nodeId)) return nodeDepths.get(nodeId)!;
-        let depth = 0;
-        let currentId: ID | undefined = nodeId;
-        while (currentId) {
-            const parentId = childToParentMap.get(currentId);
-            if (parentId) {
-                depth++;
-                currentId = parentId;
-            } else {
-                break;
-            }
+        let depth = nodeDepths.get(nodeId);
+        if (depth === undefined) {
+            depth = getNodeDepthFromParentMap(childToParentMap, nodeId);
+            nodeDepths.set(nodeId, depth);
         }
-        nodeDepths.set(nodeId, depth);
         return depth;
     }
 
@@ -276,7 +269,7 @@ 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 */
+        /* 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;
         updateParentCheckState(parentId, node.children, tempChecked, tempIndeterminate);
     }

package/src/helpers/treeNode.helper.ts

@@ -41,4 +41,55 @@ export function initializeNodeMaps<ID>(storeId: string, initialData: TreeNode<ID
     // Batch update the store with both maps at once
     updateNodeMap(nodeMap);
     updateChildToParentMap(childToParentMap);
-}
+}
+
+/**
+ * Compute the maximum depth of a node's subtree (0 for a leaf node).
+ * Uses an iterative stack-based DFS to avoid call-stack limits on deep trees.
+ *
+ * @param nodeMap - Map of node ID to node (from `initializeNodeMaps`).
+ * @param nodeId - The root of the subtree to measure.
+ */
+export function getSubtreeDepthFromMap<ID>(
+    nodeMap: Map<ID, TreeNode<ID>>,
+    nodeId: ID
+): number {
+    const root = nodeMap.get(nodeId);
+    if (!root?.children?.length) return 0;
+
+    let maxDepth = 0;
+    const stack: Array<{ node: TreeNode<ID>; depth: number; }> = [
+        { node: root, depth: 0 }
+    ];
+
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop()!;
+        if (node.children?.length) {
+            for (const child of node.children) {
+                if (depth + 1 > maxDepth) maxDepth = depth + 1;
+                stack.push({ node: child, depth: depth + 1 });
+            }
+        }
+    }
+
+    return maxDepth;
+}
+
+/**
+ * Compute a node's depth (its level, 0 for root) by walking the child-to-parent map.
+ *
+ * @param childToParentMap - Map of child ID to parent ID (from `initializeNodeMaps`).
+ * @param nodeId - The node whose depth to compute.
+ */
+export function getNodeDepthFromParentMap<ID>(
+    childToParentMap: Map<ID, ID>,
+    nodeId: ID
+): number {
+    let depth = 0;
+    let currentId: ID | undefined = nodeId;
+    while (currentId !== undefined && childToParentMap.has(currentId)) {
+        currentId = childToParentMap.get(currentId);
+        depth++;
+    }
+    return depth;
+}