@snack-uikit/tree 0.10.3 → 0.11.1-preview-c3fee040.0

package/src/hooks/__tests__/useSearchableTree.spec.ts

@@ -0,0 +1,200 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { type DependencyList, useEffect, useRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { SearchableTreeDataLoadResult, TreeNodeProps } from '../../types';
+import { SearchResult, useSearchableTree } from '../useSearchableTree';
+
+vi.mock('@siberiacancode/reactuse', () => ({
+  useDebounceValue: (value: string) => value,
+  useDidUpdate: (effect: () => void, deps: DependencyList) => {
+    const isFirstRenderRef = useRef(true);
+
+    useEffect(() => {
+      if (isFirstRenderRef.current) {
+        isFirstRenderRef.current = false;
+        return;
+      }
+
+      effect();
+    }, [deps, effect]);
+  },
+  useRefState: <TValue>(initialValue: TValue) => useRef<TValue>(initialValue),
+}));
+
+type TreeRecord = {
+  label: string;
+};
+
+const createLeaf = (id: string): TreeNodeProps => ({
+  id,
+  title: id,
+});
+
+const createParent = (id: string, nested: TreeNodeProps[]): TreeNodeProps => ({
+  id,
+  title: id,
+  nested,
+});
+
+const mapNodeToRecordItem = (node: TreeNodeProps): TreeRecord => ({
+  label: String(node.title),
+});
+
+describe('useSearchableTree', () => {
+  it('should initialize tree and treeItemsRecord from initTree', () => {
+    const initTree = [createLeaf('node-1'), createParent('node-2', [createLeaf('node-2-1')])];
+
+    const { result } = renderHook(() =>
+      useSearchableTree<TreeRecord, TreeNodeProps>({
+        initTree,
+        onPreloadNode: vi.fn(),
+        onPreloadNodes: vi.fn(),
+        onSearch: vi.fn(),
+        mapNodeToRecordItem,
+      }),
+    );
+
+    expect(result.current.tree.current).toEqual(initTree);
+    expect(result.current.treeItemsRecord.current).toEqual({
+      'node-1': { label: 'node-1' },
+      'node-2': { label: 'node-2' },
+      'node-2-1': { label: 'node-2-1' },
+    });
+  });
+
+  it('should update expandedNodes on onExpand call', () => {
+    const { result } = renderHook(() =>
+      useSearchableTree<TreeRecord, TreeNodeProps>({
+        initTree: [createLeaf('root')],
+        onPreloadNode: vi.fn(),
+        onPreloadNodes: vi.fn(),
+        onSearch: vi.fn(),
+        mapNodeToRecordItem,
+      }),
+    );
+
+    act(() => {
+      result.current.onExpand(['root', 'child']);
+    });
+
+    expect(result.current.expandedNodes.current).toEqual(['root', 'child']);
+  });
+
+  it('should preload node children and update tree and record on onDataLoad', async () => {
+    const initTree = [createParent('root', [])];
+    const preloadedChildren = [createLeaf('child-1'), createLeaf('child-2')];
+    const onPreloadNode = vi.fn().mockResolvedValue(preloadedChildren);
+
+    const { result } = renderHook(() =>
+      useSearchableTree<TreeRecord, TreeNodeProps>({
+        initTree,
+        onPreloadNode,
+        onPreloadNodes: vi.fn(),
+        onSearch: vi.fn(),
+        mapNodeToRecordItem,
+      }),
+    );
+
+    let loadResult: SearchableTreeDataLoadResult<TreeNodeProps, TreeRecord> | undefined;
+
+    await act(async () => {
+      loadResult = await result.current.onDataLoad(createParent('root', []));
+    });
+
+    expect(onPreloadNode).toHaveBeenCalledWith(createParent('root', []));
+    expect(loadResult).toEqual({
+      preloadedChildren,
+      updatedTree: [createParent('root', preloadedChildren)],
+      newTreeItemsRecord: {
+        root: { label: 'root' },
+        'child-1': { label: 'child-1' },
+        'child-2': { label: 'child-2' },
+      },
+    });
+    expect(result.current.tree.current).toEqual([createParent('root', preloadedChildren)]);
+    expect(result.current.treeItemsRecord.current).toEqual({
+      root: { label: 'root' },
+      'child-1': { label: 'child-1' },
+      'child-2': { label: 'child-2' },
+    });
+  });
+
+  it('should run search and preload required nodes', async () => {
+    const searchedTree = [createParent('expandable-root', []), createLeaf('leaf')];
+    const onSearch = vi.fn(
+      async (): Promise<SearchResult<TreeNodeProps>> => ({
+        tree: searchedTree,
+        needPreloadNodes: ['expandable-root', 'external-root'],
+      }),
+    );
+    const onPreloadNodes = vi.fn(async (nodeIds: string[]) => ({
+      'expandable-root': [createLeaf('expandable-child')],
+      'external-root': [createLeaf('external-child')],
+      ...Object.fromEntries(
+        nodeIds.filter(id => id !== 'expandable-root' && id !== 'external-root').map(id => [id, []]),
+      ),
+    }));
+
+    const { result } = renderHook(() =>
+      useSearchableTree<TreeRecord, TreeNodeProps>({
+        initTree: [createParent('init-root', [])],
+        onPreloadNode: vi.fn(),
+        onPreloadNodes,
+        onSearch,
+        mapNodeToRecordItem,
+      }),
+    );
+
+    act(() => {
+      result.current.onExpand(['expandable-root']);
+      result.current.search.onChange('query');
+    });
+
+    await waitFor(() => {
+      expect(onSearch).toHaveBeenCalledWith({ search: 'query' }, expect.any(AbortSignal));
+      expect(onPreloadNodes).toHaveBeenCalledWith(['expandable-root', 'external-root'], expect.any(AbortSignal));
+    });
+    expect(result.current.tree.current).toEqual([
+      createParent('expandable-root', [createLeaf('expandable-child')]),
+      createLeaf('leaf'),
+    ]);
+    expect(result.current.treeItemsRecord.current).toEqual({
+      'expandable-root': { label: 'expandable-root' },
+      'expandable-child': { label: 'expandable-child' },
+      leaf: { label: 'leaf' },
+    });
+  });
+
+  it('should update tree and record from search result without preloading', async () => {
+    const onSearch = vi.fn(async () => ({
+      tree: [createParent('root-node', [createLeaf('child-node')])],
+      needPreloadNodes: [],
+    }));
+
+    const { result } = renderHook(() =>
+      useSearchableTree<TreeRecord, TreeNodeProps>({
+        initTree: [createLeaf('initial')],
+        onPreloadNode: vi.fn(),
+        onPreloadNodes: vi.fn(),
+        onSearch,
+        mapNodeToRecordItem,
+      }),
+    );
+
+    act(() => {
+      result.current.search.onChange('query');
+    });
+
+    await waitFor(() => {
+      expect(onSearch).toHaveBeenCalledWith({ search: 'query' }, expect.any(AbortSignal));
+      expect(result.current.tree.current).toEqual([createParent('root-node', [createLeaf('child-node')])]);
+    });
+
+    expect(result.current.expandedNodes.current).toEqual([]);
+    expect(result.current.treeItemsRecord.current).toEqual({
+      'root-node': { label: 'root-node' },
+      'child-node': { label: 'child-node' },
+    });
+  });
+});

package/src/hooks/__tests__/useTreeMultiSelection.spec.ts

@@ -0,0 +1,165 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ParentTreeNode, TreeNodeProps } from '../../types';
+import { useTreeMultiSelection } from '../useTreeMultiSelection';
+
+const createLeaf = (id: string): TreeNodeProps => ({
+  id,
+  title: id,
+});
+
+const createParent = (id: string, nested: TreeNodeProps[]): ParentTreeNode => ({
+  id,
+  title: id,
+  nested,
+});
+
+describe('useTreeMultiSelection', () => {
+  it('should keep selected state uncontrolled by default', async () => {
+    const { result } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad: vi.fn(async () => ({ preloadedChildren: [], updatedTree: [] })),
+        onSelect: () => ({ added: ['a'], removed: [] }),
+      }),
+    );
+
+    expect(result.current.selected).toEqual([]);
+
+    await act(async () => {
+      await result.current.onSelect(['a'], createLeaf('a'));
+    });
+
+    expect(result.current.selected).toEqual(['a']);
+  });
+
+  it('should call onChangeSelected when selection updates', async () => {
+    const onChangeSelected = vi.fn();
+
+    const { result } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad: vi.fn(async () => ({ preloadedChildren: [], updatedTree: [] })),
+        onSelect: () => ({ added: ['a'], removed: [] }),
+        onChangeSelected,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.onSelect(['a'], createLeaf('a'));
+    });
+
+    expect(onChangeSelected).toHaveBeenCalledWith(['a']);
+  });
+
+  it('should treat selected prop as controlled', async () => {
+    const onChangeSelected = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ selected }: { selected: string[] }) =>
+        useTreeMultiSelection<TreeNodeProps>({
+          onDataLoad: vi.fn(async () => ({ preloadedChildren: [], updatedTree: [] })),
+          onSelect: () => ({ added: ['b'], removed: [] }),
+          selected,
+          onChangeSelected,
+        }),
+      { initialProps: { selected: ['a'] } },
+    );
+
+    expect(result.current.selected).toEqual(['a']);
+
+    await act(async () => {
+      await result.current.onSelect(['a', 'b'], createLeaf('b'));
+    });
+
+    // controlled value does not change until parent updates it
+    expect(result.current.selected).toEqual(['a']);
+    expect(onChangeSelected).toHaveBeenCalledWith(['a', 'b']);
+
+    rerender({ selected: ['a', 'b'] });
+    expect(result.current.selected).toEqual(['a', 'b']);
+  });
+
+  it('should preload children when selecting empty parent node and pass cloned node to onSelect', async () => {
+    const node = createParent('parent', []);
+    const preloadedChildren = [createLeaf('child-1'), createLeaf('child-2')];
+
+    const onDataLoad = vi.fn(async () => ({
+      preloadedChildren,
+      updatedTree: [createParent('parent', preloadedChildren)],
+    }));
+    const onSelect = vi.fn(() => ({ added: ['parent', 'child-1', 'child-2'], removed: [] }));
+
+    const { result } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad,
+        onSelect,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.onSelect(['parent'], node);
+    });
+
+    expect(onDataLoad).toHaveBeenCalledWith(node);
+    expect(onSelect).toHaveBeenCalledWith({
+      selectedKeys: ['parent'],
+      node: createParent('parent', preloadedChildren),
+      isSelected: true,
+    });
+    expect(result.current.selected.sort()).toEqual(['child-1', 'child-2', 'parent']);
+  });
+
+  it('should not preload when parent node already has children', async () => {
+    const node = createParent('parent', [createLeaf('child')]);
+    const onDataLoad = vi.fn(async () => ({
+      preloadedChildren: [],
+      updatedTree: [],
+    }));
+    const onSelect = vi.fn(() => ({ added: ['parent'], removed: [] }));
+
+    const { result } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad,
+        onSelect,
+      }),
+    );
+
+    await act(async () => {
+      await result.current.onSelect(['parent'], node);
+    });
+
+    expect(onDataLoad).not.toHaveBeenCalled();
+    expect(onSelect).toHaveBeenCalledWith({
+      selectedKeys: ['parent'],
+      node,
+      isSelected: true,
+    });
+  });
+
+  it('should add and remove ids from selection without duplicates', async () => {
+    const { result } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad: vi.fn(async () => ({ preloadedChildren: [], updatedTree: [] })),
+        onSelect: () => ({ added: ['a', 'a', 'b'], removed: [] }),
+      }),
+    );
+
+    await act(async () => {
+      await result.current.onSelect(['a'], createLeaf('a'));
+    });
+
+    expect(result.current.selected.sort()).toEqual(['a', 'b']);
+
+    const { result: result2 } = renderHook(() =>
+      useTreeMultiSelection<TreeNodeProps>({
+        onDataLoad: vi.fn(async () => ({ preloadedChildren: [], updatedTree: [] })),
+        onSelect: () => ({ added: [], removed: ['a'] }),
+        selected: ['a', 'b'],
+      }),
+    );
+
+    await act(async () => {
+      await result2.current.onSelect(['b'], createLeaf('a'));
+    });
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useSearchableTree';
+export * from './useTreeMultiSelection';

package/src/hooks/useSearchableTree.ts

@@ -0,0 +1,163 @@
+import { useDebounceValue, useDidUpdate, useRefState } from '@siberiacancode/reactuse';
+import { cancelable, CancelablePromise } from 'cancelable-promise';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { collectEmptyNestedNodesInExpanded, setChildrenOfTreeNode, traverse } from '../helpers';
+import type { SearchableTreeDataLoadResult, TreeNodeProps } from '../types';
+
+export type SearchResult<TTreeNode extends TreeNodeProps> = {
+  tree: TTreeNode[];
+  needPreloadNodes: string[];
+};
+
+export type SearchParams = {
+  search: string;
+};
+
+type UseSearchableTreeParams<TRecordValue, TTreeNode extends TreeNodeProps> = {
+  initTree: TTreeNode[];
+  onPreloadNode: (node: TreeNodeProps) => Promise<TTreeNode[]>;
+  onPreloadNodes: (nodes: string[], signal?: AbortSignal) => Promise<Record<string, TTreeNode[]>>;
+  onSearch: (params: SearchParams, signal?: AbortSignal) => Promise<SearchResult<TTreeNode>>;
+  mapNodeToRecordItem: (node: TTreeNode) => TRecordValue;
+};
+
+export function useSearchableTree<TRecordValue, TTreeNode extends TreeNodeProps>({
+  initTree,
+  onPreloadNode,
+  onPreloadNodes,
+  onSearch,
+  mapNodeToRecordItem,
+}: UseSearchableTreeParams<TRecordValue, TTreeNode>) {
+  const tree = useRefState<TTreeNode[]>(initTree);
+  const treeItemsRecord = useRefState<Record<string, TRecordValue>>({});
+
+  const expandedNodes = useRefState<string[]>([]);
+
+  const [search, setSearch] = useState<string>('');
+  const debouncedSearch = useDebounceValue(search, 500);
+
+  const [loading, setLoading] = useState(false);
+  const searchPromiseRef = useRef<CancelablePromise<SearchResult<TTreeNode>> | null>(null);
+  const searchAbortControllerRef = useRef<AbortController | null>(null);
+
+  const buildTreeItemsRecord = useCallback(
+    (nodes: TTreeNode[]): Record<string, TRecordValue> => {
+      const record: Record<string, TRecordValue> = {};
+
+      traverse<TTreeNode>(nodes, node => {
+        record[node.id] = mapNodeToRecordItem(node);
+      });
+
+      return record;
+    },
+    [mapNodeToRecordItem],
+  );
+
+  const onExpand = useCallback(
+    (nodes: string[]) => {
+      expandedNodes.current = nodes;
+    },
+    [expandedNodes],
+  );
+
+  const onDataLoad = useCallback(
+    async (node: TreeNodeProps): Promise<SearchableTreeDataLoadResult<TTreeNode, TRecordValue>> => {
+      const preloadedChildren = await onPreloadNode(node);
+      const updatedTree = setChildrenOfTreeNode(tree.current, node.id, preloadedChildren);
+      tree.current = updatedTree;
+
+      const newTreeItemsRecord: Record<string, TRecordValue> = { ...treeItemsRecord.current };
+      traverse<TTreeNode>(preloadedChildren, child => {
+        newTreeItemsRecord[child.id] = mapNodeToRecordItem(child);
+      });
+      treeItemsRecord.current = newTreeItemsRecord;
+
+      return { preloadedChildren, updatedTree, newTreeItemsRecord };
+    },
+    [mapNodeToRecordItem, onPreloadNode, tree, treeItemsRecord],
+  );
+
+  const handleSearch = useCallback(
+    async (searchQuery: string) => {
+      searchPromiseRef.current?.cancel();
+      searchAbortControllerRef.current?.abort();
+
+      setLoading(true);
+      const abortController = new AbortController();
+      searchAbortControllerRef.current = abortController;
+
+      const searchPromise = cancelable(onSearch({ search: searchQuery }, abortController.signal));
+      searchPromiseRef.current = searchPromise;
+
+      try {
+        const { tree: searchedTree, needPreloadNodes } = await searchPromise;
+        if (!searchPromise.isCanceled()) {
+          tree.current = searchedTree;
+          treeItemsRecord.current = buildTreeItemsRecord(searchedTree);
+
+          const expandedSet = new Set(expandedNodes.current);
+          const toPreloadExpandableNodes = collectEmptyNestedNodesInExpanded(searchedTree, expandedSet);
+          const collectedNodesForPreload = Array.from(
+            new Set([...toPreloadExpandableNodes.map(node => node.id), ...needPreloadNodes]),
+          );
+
+          if (!collectedNodesForPreload.length) {
+            return;
+          }
+
+          const preloadedNodes = await onPreloadNodes(collectedNodesForPreload, abortController.signal);
+
+          if (searchPromiseRef.current !== searchPromise) {
+            return;
+          }
+
+          let tmpTree = [...searchedTree];
+          for (const [nodeId, children] of Object.entries(preloadedNodes)) {
+            tmpTree = setChildrenOfTreeNode(tmpTree, nodeId, children);
+          }
+
+          tree.current = tmpTree;
+          treeItemsRecord.current = buildTreeItemsRecord(tmpTree);
+        }
+      } finally {
+        if (searchPromiseRef.current === searchPromise) {
+          setLoading(false);
+          searchPromiseRef.current = null;
+          searchAbortControllerRef.current = null;
+        }
+      }
+    },
+    [buildTreeItemsRecord, expandedNodes, onPreloadNodes, onSearch, tree, treeItemsRecord],
+  );
+
+  useDidUpdate(() => {
+    handleSearch(debouncedSearch);
+  }, [debouncedSearch, handleSearch]);
+
+  useEffect(() => {
+    tree.current = initTree;
+    treeItemsRecord.current = buildTreeItemsRecord(initTree);
+  }, [buildTreeItemsRecord, initTree, tree, treeItemsRecord]);
+
+  useEffect(
+    () => () => {
+      searchPromiseRef.current?.cancel();
+      searchAbortControllerRef.current?.abort();
+    },
+    [],
+  );
+
+  return {
+    tree,
+    expandedNodes,
+    loading,
+    treeItemsRecord,
+    search: {
+      value: search,
+      onChange: setSearch,
+    },
+    onExpand,
+    onDataLoad,
+  };
+}

package/src/hooks/useTreeMultiSelection.ts

@@ -0,0 +1,61 @@
+import { useCallback } from 'react';
+
+import { useValueControl } from '@snack-uikit/utils';
+
+import { PreloadNodeHandler, SelectHandler, TreeNodeProps } from '../types';
+
+type UseTreeMultiSelectionParams<TTreeNode extends TreeNodeProps> = {
+  onDataLoad: PreloadNodeHandler<TTreeNode>;
+  onSelect: SelectHandler;
+  selected?: string[];
+  onChangeSelected?: (newSelected: string[]) => void;
+};
+
+const getNewSelectedIds = (selectedIds: string[], added: string[], removed: string[]): string[] => {
+  const result = new Set(selectedIds);
+
+  added.forEach(id => {
+    result.add(id);
+  });
+
+  removed.forEach(id => {
+    result.delete(id);
+  });
+
+  return Array.from(result);
+};
+
+export function useTreeMultiSelection<TTreeNode extends TreeNodeProps>({
+  onDataLoad,
+  onSelect: onSelectProp,
+  selected,
+  onChangeSelected,
+}: UseTreeMultiSelectionParams<TTreeNode>) {
+  const [selectedIds = [], setSelectedIds] = useValueControl<string[]>({
+    value: selected,
+    defaultValue: [],
+    onChange: onChangeSelected,
+  });
+
+  const onSelect = useCallback(
+    async (selectedKeys: string[], node: TreeNodeProps) => {
+      const isSelected = selectedKeys.includes(node.id);
+      const clonedNode = structuredClone(node);
+
+      if (node.nested && !node.nested.length) {
+        const { preloadedChildren } = await onDataLoad(node as TTreeNode);
+        clonedNode.nested = preloadedChildren;
+      }
+
+      const { added, removed } = onSelectProp({ selectedKeys, node: clonedNode, isSelected });
+      const updatedSelectedIds = getNewSelectedIds(selectedIds, added, removed);
+      setSelectedIds(updatedSelectedIds);
+    },
+    [onDataLoad, onSelectProp, selectedIds, setSelectedIds],
+  );
+
+  return {
+    selected: selectedIds,
+    onSelect,
+  };
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './components';
-export type { OnNodeClick, TreeNodeId, TreeNodeProps } from './types';
+export type { OnNodeClick, TreeNodeId, TreeNodeProps, ExtendedTreeNodeProps } from './types';
 export { setNonce } from '@snack-uikit/list';
+export * from './helpers';

package/src/types.ts

@@ -118,3 +118,18 @@ export type TreeBaseProps = TreeView | TreeMultiSelect | TreeSingleSelect;
 export type ExtendedTreeNodeProps = TreeNodeProps & {
   getTitle?(): void;
 };
+
+export type PreloadNodeHandler<TTreeNode extends TreeNodeProps> = (
+  node: TreeNodeProps,
+) => Promise<{ preloadedChildren: TTreeNode[]; updatedTree: TTreeNode[] }>;
+
+export type SearchableTreeDataLoadResult<TTreeNode extends TreeNodeProps, TRecordValue> = {
+  preloadedChildren: TTreeNode[];
+  updatedTree: TTreeNode[];
+  newTreeItemsRecord: Record<string, TRecordValue>;
+};
+
+export type SelectHandler = (props: { selectedKeys: string[]; node: TreeNodeProps; isSelected: boolean }) => {
+  added: string[];
+  removed: string[];
+};