@cloud-ru/ds-tree 1.0.0

package/src/helpers/traverse.ts

@@ -0,0 +1,28 @@
+import { TreeNodeProps } from '../types';
+
+type NodeWithDepth<T extends TreeNodeProps> = { node: T; depth: number };
+
+/**
+ * Обходит дерево в ширину (BFS) и вызывает callback для каждого узла.
+ *
+ * Очередь — массив с курсором `head`: `shift()` на массиве переиндексирует весь хвост,
+ * а сдвиг курсора — O(1).
+ *
+ * @param nodes Корневые узлы дерева.
+ * @param callback Функция, вызываемая для каждого найденного узла.
+ */
+export const traverse = <T extends TreeNodeProps>(nodes: T[], callback: (node: T, depth: number) => void) => {
+  const queue: NodeWithDepth<T>[] = nodes.map(node => ({ node, depth: 0 }));
+  let head = 0;
+
+  while (head < queue.length) {
+    const { node, depth } = queue[head];
+    head += 1;
+
+    callback(node, depth);
+
+    for (const child of node.nested ?? []) {
+      queue.push({ node: child as T, depth: depth + 1 });
+    }
+  }
+};

package/src/helpers/traverseWithTarget.ts

@@ -0,0 +1,41 @@
+import { TreeNodeProps } from '../types';
+
+type NodeWithDepthAndTarget<T extends TreeNodeProps> = {
+  node: T;
+  depth: number;
+  targetList: T[];
+};
+
+/**
+ * Обходит дерево в ширину (BFS), передавая каждому узлу список,
+ * в который должен быть добавлен его трансформированный результат.
+ *
+ * Очередь — массив с курсором `head`: `shift()` на массиве переиндексирует весь хвост,
+ * а сдвиг курсора — O(1).
+ *
+ * @param nodes Корневые узлы дерева.
+ * @param rootTargetList Корневой список-приемник для преобразованных узлов.
+ * @param callback Функция обработки узла. Возвращает список для детей
+ * или undefined, если вложенные узлы обходить не нужно.
+ */
+export const traverseWithTarget = <T extends TreeNodeProps>(
+  nodes: T[],
+  rootTargetList: T[],
+  callback: (node: T, depth: number, targetList: T[]) => T[] | undefined,
+) => {
+  const queue: NodeWithDepthAndTarget<T>[] = nodes.map(node => ({ node, depth: 0, targetList: rootTargetList }));
+  let head = 0;
+
+  while (head < queue.length) {
+    const { node, depth, targetList } = queue[head];
+    head += 1;
+
+    const childTargetList = callback(node, depth, targetList);
+
+    if (childTargetList !== undefined && node.nested?.length) {
+      for (const child of node.nested) {
+        queue.push({ node: child as T, depth: depth + 1, targetList: childTargetList });
+      }
+    }
+  }
+};

package/src/helpers/updateTreeNode.ts

@@ -0,0 +1,46 @@
+import { TreeNodeProps } from '../types';
+import { traverseWithTarget } from './traverseWithTarget';
+
+type UpdateTreeNodeData<Node extends TreeNodeProps> = Partial<TreeNodeProps> & {
+  nested?: Node[];
+};
+
+/**
+ * Возвращает копию дерева, где у узла с указанным id обновляются переданные поля.
+ *
+ * @param tree Исходное дерево.
+ * @param nodeId Идентификатор узла, который нужно обновить.
+ * @param data Частичные данные узла, которые будут применены к найденному элементу.
+ */
+export const updateTreeNode = <Node extends TreeNodeProps>(
+  tree: Node[],
+  nodeId: string,
+  data: UpdateTreeNodeData<Node>,
+): Node[] => {
+  const result: Node[] = [];
+
+  traverseWithTarget(tree, result, (source, _depth, targetList) => {
+    const isTarget = source.id === nodeId;
+    const hasNested = Array.isArray(source.nested);
+
+    let newNested: Node[] | undefined;
+
+    if (isTarget) {
+      newNested = data.nested;
+    } else if (hasNested) {
+      newNested = [];
+    }
+
+    const newNode = {
+      ...source,
+      ...(isTarget ? data : {}),
+      ...(newNested !== undefined ? { nested: newNested } : {}),
+    } as Node;
+
+    targetList.push(newNode);
+
+    return !isTarget && hasNested && source.nested?.length ? newNested : undefined;
+  });
+
+  return result;
+};

package/src/hooks/index.ts

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

package/src/hooks/internalHooks.ts

@@ -0,0 +1,30 @@
+import { DependencyList, EffectCallback, MutableRefObject, useEffect, useRef, useState } from 'react';
+
+export function useRefState<T>(initial: T): MutableRefObject<T> {
+  const ref = useRef<T>(initial);
+  return ref;
+}
+
+export function useDebounceValue<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+
+  return debounced;
+}
+
+export function useDidUpdate(effect: EffectCallback, deps?: DependencyList) {
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    return effect();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+}

package/src/hooks/useSearchableTree.ts

@@ -0,0 +1,190 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { collectEmptyNestedNodesInExpanded, traverse, updateTreeNode } from '../helpers';
+import { SearchableTreeDataLoadResult, TreeNodeProps } from '../types';
+import { useDebounceValue, useDidUpdate, useRefState } from './internalHooks';
+
+export type SearchResult<TTreeNode extends TreeNodeProps> = {
+  tree: TTreeNode[];
+  needPreloadNodes: string[];
+};
+
+export type SearchParams = {
+  search: string;
+  expandedNodes: string[];
+};
+
+/**
+ * Параметры {@link useSearchableTree}.
+ *
+ * @typeParam TRecordValue — тип записи в `treeItemsRecord` (по одному элементу на узел).
+ * @typeParam TTreeNode — тип узла дерева.
+ */
+type UseSearchableTreeParams<TRecordValue, TTreeNode extends TreeNodeProps> = {
+  /** Начальное дерево узлов. */
+  initTree: TTreeNode[];
+  /** Подгрузка дочерних узлов для одного узла. */
+  onPreloadNode: (node: TreeNodeProps) => Promise<TTreeNode[]>;
+  /** Пакетная подгрузка детей по id родителей. */
+  onPreloadNodes: (nodes: string[], signal?: AbortSignal) => Promise<Record<string, TTreeNode[]>>;
+  /** Поиск по дереву. */
+  onSearch: (params: SearchParams, signal?: AbortSignal) => Promise<SearchResult<TTreeNode>>;
+  /** Сопоставление узла с элементом записи `treeItemsRecord` (по `node.id`). */
+  mapNodeToRecordItem: (node: TTreeNode) => TRecordValue;
+};
+
+/**
+ * Хук для работы с деревом, поддерживающим поиск и асинхронную подгрузку узлов.
+ *
+ * Возможности:
+ * - хранение актуального дерева и записи элементов (`treeItemsRecord`);
+ * - управление раскрытыми узлами;
+ * - дебаунс-поиск с отменой предыдущего запроса;
+ * - дозагрузка дочерних узлов после поиска или раскрытия.
+ *
+ * @param params Параметры и обработчики для работы с деревом.
+ * @returns Ссылки на состояние дерева, контролы поиска и колбэки для `expand`/`dataLoad`.
+ */
+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);
+  // Актуальный запрос поиска. Он же маркер «этот вызов ещё не вытеснен следующим»:
+  // после каждого await сверяемся по идентичности, а не по отдельному флагу отмены.
+  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 = updateTreeNode(tree.current, node.id, { nested: 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) => {
+      searchAbortControllerRef.current?.abort();
+
+      setLoading(true);
+      const abortController = new AbortController();
+      searchAbortControllerRef.current = abortController;
+
+      try {
+        const { tree: searchedTree, needPreloadNodes } = await onSearch(
+          { search: searchQuery, expandedNodes: expandedNodes.current },
+          abortController.signal,
+        );
+
+        if (!abortController.signal.aborted) {
+          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 (searchAbortControllerRef.current !== abortController) {
+            return;
+          }
+
+          let tmpTree = [...searchedTree];
+          for (const [nodeId, children] of Object.entries(preloadedNodes)) {
+            tmpTree = updateTreeNode(tmpTree, nodeId, { nested: children });
+          }
+
+          tree.current = tmpTree;
+          treeItemsRecord.current = buildTreeItemsRecord(tmpTree);
+        }
+      } catch (error) {
+        // Прерванный запрос — штатный путь: следующий ввод уже вытеснил этот вызов.
+        if (!abortController.signal.aborted) {
+          throw error;
+        }
+      } finally {
+        if (searchAbortControllerRef.current === abortController) {
+          setLoading(false);
+          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(
+    () => () => {
+      searchAbortControllerRef.current?.abort();
+    },
+    [],
+  );
+
+  return {
+    tree,
+    expandedNodes,
+    loading,
+    treeItemsRecord,
+    search: {
+      value: search,
+      onChange: setSearch,
+    },
+    onExpand,
+    onDataLoad,
+  };
+}

package/src/hooks/useTreeMultiSelection.ts

@@ -0,0 +1,67 @@
+import { applySelectionDiff, useValueControl } from '@cloud-ru/ds-utils';
+import { useCallback } from 'react';
+
+import { PreloadNodeHandler, SelectHandler, TreeNodeProps } from '../types';
+
+/**
+ * Параметры {@link useTreeMultiSelection}.
+ *
+ * @typeParam TTreeNode — тип узла дерева.
+ */
+type UseTreeMultiSelectionParams<TTreeNode extends TreeNodeProps> = {
+  /**
+   * Подгрузка дочерних узлов, если у узла есть `nested`, но массив пуст (ленивая загрузка перед выбором).
+   */
+  onDataLoad: PreloadNodeHandler<TTreeNode>;
+  /** Логика мультивыбора: по клику возвращает, какие id добавить и снять. */
+  onSelect: SelectHandler;
+  /** Controlled: текущие выбранные id; без пропа — внутреннее состояние хука. */
+  selected?: string[];
+  /** Вызывается при изменении набора выбранных id (controlled-сценарий). */
+  onChangeSelected?: (newSelected: string[]) => void;
+};
+
+/**
+ * Хук мультивыбора для дерева.
+ *
+ * Выполняет пересчет выбранных id после клика по узлу, поддерживает
+ * controlled/uncontrolled режим (`selected` + `onChangeSelected`) и при необходимости
+ * подгружает детей узла перед вычислением итогового выбора.
+ *
+ * @param params Параметры управления выбором и подгрузкой данных.
+ * @returns Текущий список выбранных id и обработчик выбора узла.
+ */
+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 = { ...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 = applySelectionDiff(selectedIds, added, removed);
+      setSelectedIds(updatedSelectedIds);
+    },
+    [onDataLoad, onSelectProp, selectedIds, setSelectedIds],
+  );
+
+  return {
+    selected: selectedIds,
+    onSelect,
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from './components';
+export * from './constants';
+export { checkNestedNodesSelection } from './helpers/checkNestedNodesSelection';
+export { collectEmptyNestedNodesInExpanded } from './helpers/collectEmptyNestedNodesInExpanded';
+export { collectIds } from './helpers/collectIds';
+export { extractTreeNodeTitle } from './helpers/extractTreeNodeTitle';
+export { findAllChildNodeIds } from './helpers/findAllChildNodeIds';
+export { findAllExpandedChildNodeIds } from './helpers/findAllExpandedChildNodeIds';
+export { getSearchedTreeItems } from './helpers/getSearchedTreeItems';
+export { getSearchedTreeNodeById } from './helpers/getSearchedTreeNodeById';
+export { lookupTreeForSelectedNodes } from './helpers/lookupTreeForSelectedNodes';
+export { sortTreeItemsByTitle } from './helpers/sortTreeItemsByTitle';
+export { traverse } from './helpers/traverse';
+export { traverseWithTarget } from './helpers/traverseWithTarget';
+export { updateTreeNode } from './helpers/updateTreeNode';
+export * from './hooks';
+export * from './types';

package/src/types.ts

@@ -0,0 +1,162 @@
+import { ItemProps } from '@cloud-ru/ds-list';
+import { ValueOf, WithSupportProps } from '@cloud-ru/ds-utils';
+import { MouseEvent, MouseEventHandler, ReactNode } from 'react';
+
+import { SELECTION_MODE, SIZE } from './constants';
+
+export type SelectionMode = ValueOf<typeof SELECTION_MODE>;
+export type Size = ValueOf<typeof SIZE>;
+
+export type TreeNodeId = string;
+
+export type BaseTreeNode = WithSupportProps<{
+  /** Идентификатор элемента */
+  id: TreeNodeId;
+  /** Имя элемента */
+  title: string | ((value: Pick<BaseTreeNode, 'id' | 'disabled'>) => ReactNode);
+  /** Является ли элемент деактивированным */
+  disabled?: boolean;
+  /** Обработчик клика по элементу */
+  onClick?: MouseEventHandler;
+  /** CSS-класс */
+  className?: string;
+  /** Ссылка на элемент */
+  href?: string;
+}>;
+
+export type ChildTreeNode = BaseTreeNode & {
+  /** Иконка дочернего элемента */
+  icon?: ReactNode;
+  nested?: never;
+  expandedIcon?: never;
+  collapsedIcon?: never;
+};
+
+export type ParentTreeNode = BaseTreeNode & {
+  icon?: never;
+  /** Иконка элемента-родителя в открытом состоянии */
+  expandedIcon?: ReactNode;
+  /** Иконка элемента-родителя в закрытом состоянии */
+  collapsedIcon?: ReactNode;
+  /** Вложенные элементы дерева */
+  nested: (ChildTreeNode | ParentTreeNode)[];
+  /** Имя элемента-родителя (расширяет вариант из `BaseTreeNode` — в callback приходят также `nested`-узлы) */
+  title: string | ((value: Pick<ParentTreeNode, 'id' | 'disabled' | 'nested'>) => ReactNode);
+};
+
+export type TreeNodeProps = ChildTreeNode | ParentTreeNode;
+
+export type ParentNode = Pick<TreeNodeProps, 'id' | 'nested'> & { parentNode?: ParentNode };
+
+export type OnNodeClick = (node: TreeNodeProps, e: MouseEvent) => void;
+
+export type TreeCommonProps = {
+  /** Данные для отрисовки */
+  data: TreeNodeProps[];
+  /**
+   * Режим выбора элементов:
+   * <br> - `Single` - одиночный выбор
+   * <br> - `Multi` - множественный выбор
+   * <br> - `undefined` - без выбора
+   */
+  selectionMode?: SelectionMode;
+  /** Обработчик клика по элементу дерева */
+  onNodeClick?: OnNodeClick;
+  /** Состояние для раскрытых элементов */
+  expandedNodes?: TreeNodeId[];
+  /** Колбэк при раскрытии/закрытии элементов */
+  onExpand?(expandedKeys: TreeNodeId[], node: TreeNodeProps): void;
+  /** Состояние для выбранных элементов */
+  selected?: TreeNodeId[] | TreeNodeId;
+  /** Колбэк для асинхронной загрузки данных при раскрытии дерева */
+  onDataLoad?(node: TreeNodeProps): Promise<boolean | unknown>;
+  /** Дополнительные действия для элемента-родителя */
+  parentActions?(node: TreeNodeProps): ItemProps[];
+  /** Дополнительные действия для элемента-потомка */
+  nodeActions?(node: TreeNodeProps): ItemProps[];
+  /**
+   * Флаг отвечающий за отображение иконок у элементов дерева
+   * @default true
+   */
+  showIcons?: boolean;
+  /** Флаг отвечающий за отображение линий вложенности */
+  showLines?: boolean;
+  /**
+   * Размер строк дерева (Figma variant `size`).
+   * @default 'm'
+   */
+  size?: Size;
+  /**
+   * Максимальное число строк заголовка узла до обрезки многоточием.
+   * Значение больше 1 разрешает перенос; строка растёт по высоте.
+   * @default 1
+   */
+  titleMaxLines?: number;
+  /** CSS-класс */
+  className?: string;
+};
+
+export type TreeView = Omit<TreeCommonProps, 'selected' | 'selectionMode'> & {
+  selectionMode?: never;
+  selected?: never;
+  onSelect?: never;
+};
+
+export type TreeSingleSelect = Omit<TreeCommonProps, 'selected'> & {
+  selectionMode: 'single';
+  /** Состояние для выбраного элемента */
+  /** <br> - При <strong>selectionMode</strong>=`Single` - принимает строку */
+  selected?: TreeNodeId;
+  /** <br> - При <strong>selectionMode</strong>=`Single` - возвращает строку */
+  onSelect?(selectedKey: TreeNodeId, node: TreeNodeProps): void;
+  showToggle?: boolean;
+};
+
+export type TreeMultiSelect = Omit<TreeCommonProps, 'selected'> & {
+  selectionMode: 'multiple';
+  /**
+   * Состояние для выбраных элементов:
+   * <br> - При <strong>selectionMode</strong>=`Multiple` - принимает массив строк
+   */
+  selected?: TreeNodeId[];
+  /**
+   * Колбэк при изменении выбраных элементов:
+   * <br> - При <strong>selectionMode</strong>=`Multiple` - возвращает массив строк
+   */
+  onSelect?(selectedKeys: TreeNodeId[], node: TreeNodeProps): void;
+};
+
+export type TreeBaseProps = TreeView | TreeMultiSelect | TreeSingleSelect;
+
+/**
+ * Расширение `TreeNodeProps` для внутренних helper'ов поиска/сортировки.
+ *
+ * Когда `title` — функция (а не строка), helper'ы не могут отсортировать или
+ * отфильтровать узел по содержимому JSX. `getTitle` даёт строковый ключ, по
+ * которому можно сравнивать узлы.
+ */
+export type ExtendedTreeNodeProps = TreeNodeProps & {
+  /** Возвращает строковый ключ узла для сравнения/поиска, когда `title` — ReactNode. */
+  getTitle?(): string;
+};
+
+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>;
+};
+
+/**
+ * Резолвер выделения для multi-select-режима: получает текущий список выбранных
+ * id, целевой узел и его новое состояние, возвращает diff (`added`/`removed`)
+ * относительно входного `selectedKeys`. Используется для кастомных стратегий
+ * каскадирования.
+ */
+export type SelectHandler = (props: { selectedKeys: string[]; node: TreeNodeProps; isSelected: boolean }) => {
+  added: string[];
+  removed: string[];
+};