react-native-tree-multi-select 1.8.0 → 1.9.0-beta.1

package/src/TreeView.tsx

@@ -1,210 +1,240 @@
-import React, { useMemo } from 'react';
+import React from 'react';
 import { InteractionManager } from 'react-native';
 import type {
-  TreeNode,
-  TreeViewProps,
-  TreeViewRef
+	TreeNode,
+	TreeViewProps,
+	TreeViewRef
 } from './types/treeView.types';
 import NodeList from './components/NodeList';
 import {
-  selectAll,
-  selectAllFiltered,
-  unselectAll,
-  unselectAllFiltered,
-  initializeNodeMaps,
-  expandAll,
-  collapseAll,
-  toggleCheckboxes,
-  expandNodes,
-  collapseNodes
+	selectAll,
+	selectAllFiltered,
+	unselectAll,
+	unselectAllFiltered,
+	initializeNodeMaps,
+	expandAll,
+	collapseAll,
+	toggleCheckboxes,
+	expandNodes,
+	collapseNodes
 } from './helpers';
-import { useTreeViewStore } from './store/treeView.store';
+import { getTreeViewStore, useTreeViewStore } from './store/treeView.store';
 import usePreviousState from './utils/usePreviousState';
 import { useShallow } from "zustand/react/shallow";
 import uuid from "react-native-uuid";
 import useDeepCompareEffect from "./utils/useDeepCompareEffect";
 import { typedMemo } from './utils/typedMemo';
+import {
+	ScrollToNodeHandlerRef,
+	ScrollToNodeParams
+} from "./handlers/ScrollToNodeHandler";
+
+function _innerTreeView<ID>(
+	props: TreeViewProps<ID>,
+	ref: React.ForwardedRef<TreeViewRef<ID>>
+) {
+	const {
+		data,
 
-function _innerTreeView<ID>(props: TreeViewProps<ID>, ref: React.ForwardedRef<TreeViewRef<ID>>) {
-    const {
-      data,
+		onCheck,
+		onExpand,
 
-      onCheck,
-      onExpand,
+		selectionPropagation,
 
-      selectionPropagation,
+		preselectedIds = [],
 
-      preselectedIds = [],
+		preExpandedIds = [],
 
-      preExpandedIds = [],
+		initialScrollNodeID,
 
-      treeFlashListProps,
-      checkBoxViewStyleProps,
-      indentationMultiplier,
+		treeFlashListProps,
+		checkBoxViewStyleProps,
+		indentationMultiplier,
 
-      CheckboxComponent,
-      ExpandCollapseIconComponent,
-      ExpandCollapseTouchableComponent,
+		CheckboxComponent,
+		ExpandCollapseIconComponent,
+		ExpandCollapseTouchableComponent,
 
-      CustomNodeRowComponent,
-    } = props;
+		CustomNodeRowComponent,
+	} = props;
 
-    const storeId = useMemo(() => uuid.v4(), []);
+	const storeId = React.useMemo(() => uuid.v4(), []);
 
-    const {
-      expanded,
-      updateExpanded,
+	const {
+		expanded,
+		updateExpanded,
 
-      initialTreeViewData,
-      updateInitialTreeViewData,
+		initialTreeViewData,
+		updateInitialTreeViewData,
 
-      searchText,
-      updateSearchText,
+		searchText,
+		updateSearchText,
 
-      updateSearchKeys,
+		updateSearchKeys,
 
-      checked,
-      indeterminate,
+		checked,
+		indeterminate,
 
-      setSelectionPropagation,
+		setSelectionPropagation,
 
-      cleanUpTreeViewStore,
-    } = useTreeViewStore<ID>(storeId)(useShallow(
-      state => ({
-        expanded: state.expanded,
-        updateExpanded: state.updateExpanded,
+		cleanUpTreeViewStore,
+	} = useTreeViewStore<ID>(storeId)(useShallow(
+		state => ({
+			expanded: state.expanded,
+			updateExpanded: state.updateExpanded,
 
-        initialTreeViewData: state.initialTreeViewData,
-        updateInitialTreeViewData: state.updateInitialTreeViewData,
+			initialTreeViewData: state.initialTreeViewData,
+			updateInitialTreeViewData: state.updateInitialTreeViewData,
 
-        searchText: state.searchText,
-        updateSearchText: state.updateSearchText,
+			searchText: state.searchText,
+			updateSearchText: state.updateSearchText,
 
-        updateSearchKeys: state.updateSearchKeys,
+			updateSearchKeys: state.updateSearchKeys,
 
-        checked: state.checked,
-        indeterminate: state.indeterminate,
+			checked: state.checked,
+			indeterminate: state.indeterminate,
 
-        setSelectionPropagation: state.setSelectionPropagation,
+			setSelectionPropagation: state.setSelectionPropagation,
 
-        cleanUpTreeViewStore: state.cleanUpTreeViewStore,
-      })
-    ));
+			cleanUpTreeViewStore: state.cleanUpTreeViewStore,
+		})
+	));
 
-    React.useImperativeHandle(ref, () => ({
-      selectAll: () => selectAll(storeId),
-      unselectAll: () => unselectAll(storeId),
+	React.useImperativeHandle(ref, () => ({
+		selectAll: () => selectAll(storeId),
+		unselectAll: () => unselectAll(storeId),
 
-      selectAllFiltered: () => selectAllFiltered(storeId),
-      unselectAllFiltered: () => unselectAllFiltered(storeId),
+		selectAllFiltered: () => selectAllFiltered(storeId),
+		unselectAllFiltered: () => unselectAllFiltered(storeId),
 
-      expandAll: () => expandAll(storeId),
-      collapseAll: () => collapseAll(storeId),
+		expandAll: () => expandAll(storeId),
+		collapseAll: () => collapseAll(storeId),
 
-      expandNodes: (ids: ID[]) => expandNodes(storeId, ids),
-      collapseNodes: (ids: ID[]) => collapseNodes(storeId, ids),
+		expandNodes: (ids: ID[]) => expandNodes(storeId, ids),
+		collapseNodes: (ids: ID[]) => collapseNodes(storeId, ids),
 
-      selectNodes: (ids: ID[]) => selectNodes(ids),
-      unselectNodes: (ids: ID[]) => unselectNodes(ids),
+		selectNodes: (ids: ID[]) => selectNodes(ids),
+		unselectNodes: (ids: ID[]) => unselectNodes(ids),
 
-      setSearchText
-    }));
+		setSearchText,
 
-    const prevSearchText = usePreviousState(searchText);
+		scrollToNodeID,
 
-    useDeepCompareEffect(() => {
-      cleanUpTreeViewStore();
+		getChildToParentMap
+	}));
 
-      updateInitialTreeViewData(data);
+	const scrollToNodeHandlerRef = React.useRef<ScrollToNodeHandlerRef<ID>>(null);
+	const prevSearchText = usePreviousState(searchText);
 
-      if (selectionPropagation)
-        setSelectionPropagation(selectionPropagation);
+	useDeepCompareEffect(() => {
+		cleanUpTreeViewStore();
 
-      initializeNodeMaps(storeId, data);
+		updateInitialTreeViewData(data);
 
-      // Check any pre-selected nodes
-      toggleCheckboxes(storeId, preselectedIds, true);
+		if (selectionPropagation)
+			setSelectionPropagation(selectionPropagation);
 
-      // Expand pre-expanded nodes
-      expandNodes(storeId, preExpandedIds);
-    }, [data]);
+		initializeNodeMaps(storeId, data);
 
-    function selectNodes(ids: ID[]) {
-      toggleCheckboxes(storeId, ids, true);
-    }
+		// Check any pre-selected nodes
+		toggleCheckboxes(storeId, preselectedIds, true);
 
-    function unselectNodes(ids: ID[]) {
-      toggleCheckboxes(storeId, ids, false);
-    }
+		// Expand pre-expanded nodes
+		expandNodes(storeId, [
+			...preExpandedIds,
+			...(initialScrollNodeID ? [initialScrollNodeID] : [])
+		]);
+	}, [data]);
 
-    function setSearchText(text: string, keys: string[] = ["name"]) {
-      updateSearchText(text);
-      updateSearchKeys(keys);
-    }
+	function selectNodes(ids: ID[]) {
+		toggleCheckboxes(storeId, ids, true);
+	}
 
-    const getIds = React.useCallback((node: TreeNode<ID>): ID[] => {
-      if (!node.children || node.children.length === 0) {
-        return [node.id];
-      } else {
-        return [node.id, ...node.children.flatMap((item) => getIds(item))];
-      }
-    }, []);
+	function unselectNodes(ids: ID[]) {
+		toggleCheckboxes(storeId, ids, false);
+	}
 
-    React.useEffect(() => {
-      onCheck?.(Array.from(checked), Array.from(indeterminate));
-    }, [onCheck, checked, indeterminate]);
+	function setSearchText(text: string, keys: string[] = ["name"]) {
+		updateSearchText(text);
+		updateSearchKeys(keys);
+	}
 
-    React.useEffect(() => {
-      onExpand?.(Array.from(expanded));
-    }, [onExpand, expanded]);
+	function scrollToNodeID(params: ScrollToNodeParams<ID>) {
+		scrollToNodeHandlerRef.current?.scrollToNodeID(params);
+	}
 
-    React.useEffect(() => {
-      if (searchText) {
-        InteractionManager.runAfterInteractions(() => {
-          updateExpanded(new Set(initialTreeViewData.flatMap(
-            (item) => getIds(item)
-          )));
-        });
-      }
-      else if (prevSearchText && prevSearchText !== "") {
-        /* Collapse all nodes only if previous search query was non-empty: this is
-        done to prevent node collapse on first render if preExpandedIds is provided */
-        InteractionManager.runAfterInteractions(() => {
-          updateExpanded(new Set());
-        });
-      }
-    }, [
-      getIds,
-      initialTreeViewData,
-      prevSearchText,
-      searchText,
-      updateExpanded
-    ]);
-
-    React.useEffect(() => {
-      return () => {
-        cleanUpTreeViewStore();
-      };
-    }, [cleanUpTreeViewStore]);
-
-    return (
-      <NodeList
-        storeId={storeId}
-
-        treeFlashListProps={treeFlashListProps}
-        checkBoxViewStyleProps={checkBoxViewStyleProps}
-        indentationMultiplier={indentationMultiplier}
-
-        CheckboxComponent={CheckboxComponent}
-        ExpandCollapseIconComponent={ExpandCollapseIconComponent}
-        ExpandCollapseTouchableComponent={ExpandCollapseTouchableComponent}
-
-        CustomNodeRowComponent={CustomNodeRowComponent}
-      />
-    );
+	function getChildToParentMap() {
+		const treeViewStore = getTreeViewStore<ID>(storeId);
+		return treeViewStore.getState().childToParentMap;
+	}
+
+	const getIds = React.useCallback((node: TreeNode<ID>): ID[] => {
+		if (!node.children || node.children.length === 0) {
+			return [node.id];
+		} else {
+			return [node.id, ...node.children.flatMap((item) => getIds(item))];
+		}
+	}, []);
+
+	React.useEffect(() => {
+		onCheck?.(Array.from(checked), Array.from(indeterminate));
+	}, [onCheck, checked, indeterminate]);
+
+	React.useEffect(() => {
+		onExpand?.(Array.from(expanded));
+	}, [onExpand, expanded]);
+
+	React.useEffect(() => {
+		if (searchText) {
+			InteractionManager.runAfterInteractions(() => {
+				updateExpanded(new Set(initialTreeViewData.flatMap(
+					(item) => getIds(item)
+				)));
+			});
+		}
+		else if (prevSearchText && prevSearchText !== "") {
+			/* Collapse all nodes only if previous search query was non-empty: this is
+			done to prevent node collapse on first render if preExpandedIds is provided */
+			InteractionManager.runAfterInteractions(() => {
+				updateExpanded(new Set());
+			});
+		}
+	}, [
+		getIds,
+		initialTreeViewData,
+		prevSearchText,
+		searchText,
+		updateExpanded
+	]);
+
+	React.useEffect(() => {
+		return () => {
+			cleanUpTreeViewStore();
+		};
+	}, [cleanUpTreeViewStore]);
+
+	return (
+		<NodeList
+			storeId={storeId}
+
+			scrollToNodeHandlerRef={scrollToNodeHandlerRef}
+			initialScrollNodeID={initialScrollNodeID}
+
+			treeFlashListProps={treeFlashListProps}
+			checkBoxViewStyleProps={checkBoxViewStyleProps}
+			indentationMultiplier={indentationMultiplier}
+
+			CheckboxComponent={CheckboxComponent}
+			ExpandCollapseIconComponent={ExpandCollapseIconComponent}
+			ExpandCollapseTouchableComponent={ExpandCollapseTouchableComponent}
+
+			CustomNodeRowComponent={CustomNodeRowComponent}
+		/>
+	);
 }
+
 const _TreeView = React.forwardRef(_innerTreeView) as <ID>(
-  props: TreeViewProps<ID> & { ref?: React.ForwardedRef<TreeViewRef<ID>> }
+	props: TreeViewProps<ID> & { ref?: React.ForwardedRef<TreeViewRef<ID>>; }
 ) => ReturnType<typeof _innerTreeView>;
 
 export const TreeView = typedMemo<typeof _TreeView>(_TreeView);

package/src/components/NodeList.tsx

@@ -27,6 +27,7 @@ import { CustomExpandCollapseIcon } from "./CustomExpandCollapseIcon";
 import { defaultIndentationMultiplier } from "../constants/treeView.constants";
 import { useShallow } from 'zustand/react/shallow';
 import { typedMemo } from "../utils/typedMemo";
+import { ScrollToNodeHandler } from "../handlers/ScrollToNodeHandler";
 
 const NodeList = typedMemo(_NodeList);
 export default NodeList;
@@ -35,6 +36,9 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
     const {
         storeId,
 
+        scrollToNodeHandlerRef,
+        initialScrollNodeID,
+
         treeFlashListProps,
         checkBoxViewStyleProps,
         indentationMultiplier,
@@ -61,6 +65,10 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
         })
     ));
 
+    const flashListRef = React.useRef<FlashList<__FlattenedTreeNode__<ID>> | null>(null);
+
+    const [initialScrollIndex, setInitialScrollIndex] = React.useState<number>(-1);
+
     // First we filter the tree as per the search term and keys
     const filteredTree = React.useMemo(() => getFilteredTreeData<ID>(
         initialTreeViewData,
@@ -112,17 +120,29 @@ function _NodeList<ID>(props: NodeListProps<ID>) {
     ]);
 
     return (
-        <FlashList
-            estimatedItemSize={36}
-            removeClippedSubviews={true}
-            keyboardShouldPersistTaps="handled"
-            drawDistance={50}
-            ListHeaderComponent={<HeaderFooterView />}
-            ListFooterComponent={<HeaderFooterView />}
-            {...treeFlashListProps}
-            data={flattenedFilteredNodes}
-            renderItem={nodeRenderer}
-        />
+        <>
+            <ScrollToNodeHandler
+                ref={scrollToNodeHandlerRef}
+                storeId={storeId}
+                flashListRef={flashListRef}
+                flattenedFilteredNodes={flattenedFilteredNodes}
+                setInitialScrollIndex={setInitialScrollIndex}
+                initialScrollNodeID={initialScrollNodeID} />
+
+            <FlashList
+                ref={flashListRef}
+                estimatedItemSize={36}
+                initialScrollIndex={initialScrollIndex}
+                removeClippedSubviews={true}
+                keyboardShouldPersistTaps="handled"
+                drawDistance={50}
+                ListHeaderComponent={<HeaderFooterView />}
+                ListFooterComponent={<HeaderFooterView />}
+                {...treeFlashListProps}
+                data={flattenedFilteredNodes}
+                renderItem={nodeRenderer}
+            />
+        </>
     );
 };
 

package/src/handlers/ScrollToNodeHandler.tsx

@@ -0,0 +1,222 @@
+/**
+ * ScrollToNodeHandler Component
+ *
+ * This component 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.
+ *
+ * The two key milestones tracked by the `expandAndScrollToNodeQueue` state are:
+ * 1. EXPANDED: Indicates that the expansion logic for the target node has been initiated.
+ * 2. RENDERED: Indicates that the list has re-rendered with the expanded node included.
+ *
+ * When the `scrollToNodeID` method is called:
+ * - The scroll parameters (target node ID, animation preferences, view offset/position) are stored in a ref.
+ * - The target node's expansion is triggered via the `expandNodes` helper.
+ * - The `expandAndScrollToNodeQueue` state is updated to mark that expansion has begun.
+ *
+ * As the component re-renders (e.g., after the node expansion changes the rendered list):
+ * - A useEffect monitors changes to the list, and once it detects the expansion has occurred,
+ *   it updates the queue to include the RENDERED milestone.
+ *
+ * A layout effect then waits for both conditions to be met:
+ * - The target node is confirmed to be in the expanded set.
+ * - The `expandAndScrollToNodeQueue` exactly matches the expected milestones ([EXPANDED, RENDERED]).
+ *
+ * Once both conditions are satisfied:
+ * - The index of the target node is determined within the latest flattened node list.
+ * - The flash list is scrolled to that index.
+ * - The queued scroll parameters and milestone queue are reset.
+ *
+ * This design ensures that the scroll action is performed only after the target node is fully present
+ * in the UI, thus preventing issues with attempting to scroll to an element that does not exist yet.
+ */
+
+import React from "react";
+import { expandNodes } from "../helpers/expandCollapse.helper";
+import { useTreeViewStore } from "../store/treeView.store";
+import { useShallow } from "zustand/react/shallow";
+import { __FlattenedTreeNode__ } from "../types/treeView.types";
+import { typedMemo } from "../utils/typedMemo";
+import { isEqual } from "lodash";
+
+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;
+
+  animated?: boolean;
+  viewOffset?: number;
+  viewPosition?: number;
+}
+
+// Enum representing the two milestones needed before scrolling
+enum ExpandQueueAction {
+  EXPANDED,
+  RENDERED,
+}
+
+export interface ScrollToNodeHandlerRef<ID> {
+  scrollToNodeID: (params: ScrollToNodeParams<ID>) => void;
+}
+
+function _innerScrollToNodeHandler<ID>(
+  props: Props<ID>,
+  ref: React.ForwardedRef<ScrollToNodeHandlerRef<ID>>
+) {
+  const {
+    storeId,
+    flashListRef,
+    flattenedFilteredNodes,
+    setInitialScrollIndex,
+    initialScrollNodeID
+  } = props;
+
+  const { expanded, childToParentMap } = useTreeViewStore<ID>(storeId)(useShallow(
+    state => ({
+      expanded: state.expanded,
+      childToParentMap: state.childToParentMap
+    })
+  ));
+
+  React.useImperativeHandle(ref, () => ({
+    scrollToNodeID: (params: ScrollToNodeParams<ID>) => {
+      queuedScrollToNodeParams.current = params;
+      // Mark that expansion is initiated.
+      setExpandAndScrollToNodeQueue([ExpandQueueAction.EXPANDED]);
+      // Trigger expansion logic (this may update the store and subsequently re-render the list).
+      expandNodes(
+        storeId,
+        [queuedScrollToNodeParams.current.nodeId],
+        !queuedScrollToNodeParams.current.expandScrolledNode
+      );
+    }
+  }), [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);
+
+  /* When the rendered node list changes, update the ref.
+  If an expansion was triggered, mark that the list is now rendered. */
+  React.useEffect(() => {
+    setExpandAndScrollToNodeQueue(prevQueue => {
+      if (prevQueue.includes(ExpandQueueAction.EXPANDED)) {
+        latestFlattenedFilteredNodesRef.current = flattenedFilteredNodes;
+        return [
+          ExpandQueueAction.EXPANDED,
+          ExpandQueueAction.RENDERED
+        ];
+      } else {
+        return prevQueue;
+      }
+    });
+  }, [flattenedFilteredNodes]);
+
+  /* Once the target node is expanded and the list is updated (milestones reached),
+  perform the scroll using the latest node list. */
+  React.useLayoutEffect(() => {
+    if (queuedScrollToNodeParams.current === null)
+      return;
+
+    if (!isEqual(
+      expandAndScrollToNodeQueue,
+      [ExpandQueueAction.EXPANDED, ExpandQueueAction.RENDERED]
+    )) {
+      return;
+    }
+
+    // If node is set to not expand
+    if (!queuedScrollToNodeParams.current.expandScrolledNode) {
+      let parentId: ID | undefined;
+      // Get the parent's id of the node to scroll to
+      if (childToParentMap.has(queuedScrollToNodeParams.current.nodeId)) {
+        parentId = childToParentMap.get(queuedScrollToNodeParams.current.nodeId) as ID;
+      }
+
+      // Ensure if the parent is expanded before proceeding to scroll to the node
+      if (parentId && !expanded.has(parentId))
+        return;
+    }
+    // If node is set to expand
+    else {
+      if (!expanded.has(queuedScrollToNodeParams.current.nodeId))
+        return;
+    }
+
+    const {
+      nodeId,
+      animated,
+      viewOffset,
+      viewPosition
+    } = queuedScrollToNodeParams.current!;
+
+    function scrollToItem() {
+      const index = latestFlattenedFilteredNodesRef.current.findIndex(
+        item => item.id === nodeId
+      );
+
+      if (index !== -1 && flashListRef.current) {
+        // Scroll to the target index.
+        flashListRef.current.scrollToIndex({
+          index,
+          animated,
+          viewOffset,
+          viewPosition
+        });
+      } else {
+        if (__DEV__) {
+          console.info("Cannot find the item of the mentioned id to scroll in the rendered tree view list data!");
+        }
+      }
+
+      // Clear the queued parameters and reset the expansion/render queue.
+      queuedScrollToNodeParams.current = null;
+      setExpandAndScrollToNodeQueue([]);
+    }
+
+    scrollToItem();
+  }, [childToParentMap, expanded, flashListRef, expandAndScrollToNodeQueue]);
+
+  ////////////////////////////// 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(() => {
+    if (initialScrollDone.current) return;
+
+    const index = flattenedFilteredNodes.findIndex(
+      item => item.id === initialScrollNodeID
+    );
+
+    setInitialScrollIndex(index);
+
+    if (index !== -1) {
+      initialScrollDone.current = true;
+    }
+    // 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);