@cloud-ru/ds-tree 1.0.0

package/dist/esm/helpers/findAllChildNodeIds.js

@@ -0,0 +1,21 @@
+/**
+ * Собирает id всех недеактивированных узлов в поддереве.
+ *
+ * @param nodes Стартовые узлы обхода.
+ * @returns Массив id всех доступных узлов.
+ * @function findAllChildNodeIds
+ */
+export function findAllChildNodeIds(nodes) {
+    const stack = [...nodes];
+    const ids = [];
+    let node;
+    while ((node = stack.pop())) {
+        if (!node.disabled) {
+            ids.push(node.id);
+            if (node.nested?.length) {
+                stack.push(...node.nested);
+            }
+        }
+    }
+    return ids;
+}

package/dist/esm/helpers/findAllExpandedChildNodeIds.d.ts

@@ -0,0 +1,8 @@
+import { TreeNodeId, TreeNodeProps } from '../types.js';
+/**
+ * Возвращает id узлов в поддереве, проходя только по раскрытым веткам.
+ *
+ * @param nodes Стартовые узлы обхода.
+ * @param expandedNodes Список id раскрытых узлов.
+ */
+export declare function findAllExpandedChildNodeIds(nodes: TreeNodeProps[], expandedNodes: TreeNodeId[]): string[];

package/dist/esm/helpers/findAllExpandedChildNodeIds.js

@@ -0,0 +1,18 @@
+/**
+ * Возвращает id узлов в поддереве, проходя только по раскрытым веткам.
+ *
+ * @param nodes Стартовые узлы обхода.
+ * @param expandedNodes Список id раскрытых узлов.
+ */
+export function findAllExpandedChildNodeIds(nodes, expandedNodes) {
+    const stack = [...nodes];
+    const ids = [];
+    let node;
+    while ((node = stack.shift())) {
+        ids.push(node.id);
+        if (node.nested?.length && expandedNodes.includes(node.id)) {
+            stack.unshift(...node.nested);
+        }
+    }
+    return ids;
+}

package/dist/esm/helpers/getSearchedTreeItems.d.ts

@@ -0,0 +1,23 @@
+import { ExtendedTreeNodeProps } from '../types.js';
+type SearchParams = {
+    /** Корневые узлы дерева, по которым выполняется поиск. */
+    tree: ExtendedTreeNodeProps[];
+    searchOptions?: Partial<{
+        /** Поисковая строка (case-insensitive substring match по `title` узла). */
+        query: string;
+        /**
+         * Если `true` и parent матчит query — в результат попадают **все** его дети
+         * без дополнительной фильтрации. По умолчанию `false`: и parent, и дети
+         * фильтруются независимо.
+         */
+        includeChildrenMatchedParent: boolean;
+    }>;
+};
+/**
+ * Фильтрует дерево по поисковой строке с сохранением иерархии подходящих узлов.
+ *
+ * @param params {@link SearchParams} — дерево и опции поиска.
+ * @returns Новое дерево, содержащее только совпавшие узлы и их путь в иерархии.
+ */
+export declare const getSearchedTreeItems: ({ tree, searchOptions }: SearchParams) => ExtendedTreeNodeProps[];
+export {};

package/dist/esm/helpers/getSearchedTreeItems.js

@@ -0,0 +1,37 @@
+import { extractTreeNodeTitle } from './extractTreeNodeTitle.js';
+const isMatchedTreeItem = (search) => {
+    const searchLower = search.toLocaleLowerCase();
+    return (treeItem) => {
+        const currentValue = extractTreeNodeTitle(treeItem);
+        return currentValue.toLocaleLowerCase().includes(searchLower);
+    };
+};
+/**
+ * Фильтрует дерево по поисковой строке с сохранением иерархии подходящих узлов.
+ *
+ * @param params {@link SearchParams} — дерево и опции поиска.
+ * @returns Новое дерево, содержащее только совпавшие узлы и их путь в иерархии.
+ */
+export const getSearchedTreeItems = ({ tree, searchOptions }) => {
+    if (!searchOptions?.query)
+        return tree;
+    const { query = '', includeChildrenMatchedParent } = searchOptions;
+    const matchFunc = isMatchedTreeItem(query);
+    const searchItems = (treeItems) => treeItems.reduce((acc, item) => {
+        const hasMatchingTitle = matchFunc(item);
+        const needDeepSearch = !(hasMatchingTitle && includeChildrenMatchedParent);
+        const matchedChildren = item.nested && (needDeepSearch ? searchItems(item.nested) : item.nested);
+        if (hasMatchingTitle || matchedChildren?.length) {
+            const newItem = { ...item };
+            if (matchedChildren?.length) {
+                newItem.nested = matchedChildren;
+            }
+            else {
+                delete newItem.nested;
+            }
+            acc.push(newItem);
+        }
+        return acc;
+    }, []);
+    return searchItems(tree);
+};

package/dist/esm/helpers/getSearchedTreeNodeById.d.ts

@@ -0,0 +1,19 @@
+import { ExtendedTreeNodeProps } from '../types.js';
+type ReturnSearch<I, T> = I extends string ? T | null : T[];
+type SearchByIdParams<I, T> = {
+    tree: T[];
+    searchOptions: {
+        id: I;
+        includeNested?: boolean;
+    };
+};
+/**
+ * Ищет узлы дерева по одному id или по массиву id.
+ *
+ * @param params Параметры поиска.
+ * @param params.tree Дерево для поиска.
+ * @param params.searchOptions Опции поиска (id и includeNested).
+ * @returns Для одиночного id возвращает узел или null, для массива id — список узлов.
+ */
+export declare const getSearchedTreeNodeById: <I extends string | string[], T extends ExtendedTreeNodeProps>({ tree, searchOptions: { id, includeNested }, }: SearchByIdParams<I, T>) => ReturnSearch<I, T>;
+export {};

package/dist/esm/helpers/getSearchedTreeNodeById.js

@@ -0,0 +1,31 @@
+/**
+ * Ищет узлы дерева по одному id или по массиву id.
+ *
+ * @param params Параметры поиска.
+ * @param params.tree Дерево для поиска.
+ * @param params.searchOptions Опции поиска (id и includeNested).
+ * @returns Для одиночного id возвращает узел или null, для массива id — список узлов.
+ */
+export const getSearchedTreeNodeById = ({ tree, searchOptions: { id, includeNested = true }, }) => {
+    const isArrayIds = Array.isArray(id);
+    if (!id || (isArrayIds && id.length === 0)) {
+        return (isArrayIds ? [] : null);
+    }
+    const foundItems = [];
+    const searchNodes = (nodes) => {
+        for (const node of nodes) {
+            const matchCondition = isArrayIds ? id.includes(node.id) : node.id === id;
+            if (matchCondition) {
+                foundItems.push(includeNested ? node : { ...node, nested: undefined });
+                if (!isArrayIds) {
+                    return;
+                }
+            }
+            if (node.nested) {
+                searchNodes(node.nested);
+            }
+        }
+    };
+    searchNodes(tree);
+    return (isArrayIds ? foundItems : foundItems[0] || null);
+};

package/dist/esm/helpers/index.d.ts

@@ -0,0 +1,13 @@
+export * from './checkNestedNodesSelection.js';
+export * from './collectEmptyNestedNodesInExpanded.js';
+export * from './collectIds.js';
+export * from './extractTreeNodeTitle.js';
+export * from './findAllChildNodeIds.js';
+export * from './findAllExpandedChildNodeIds.js';
+export * from './getSearchedTreeItems.js';
+export * from './getSearchedTreeNodeById.js';
+export * from './lookupTreeForSelectedNodes.js';
+export * from './sortTreeItemsByTitle.js';
+export * from './traverse.js';
+export * from './traverseWithTarget.js';
+export * from './updateTreeNode.js';

package/dist/esm/helpers/index.js

@@ -0,0 +1,13 @@
+export * from './checkNestedNodesSelection.js';
+export * from './collectEmptyNestedNodesInExpanded.js';
+export * from './collectIds.js';
+export * from './extractTreeNodeTitle.js';
+export * from './findAllChildNodeIds.js';
+export * from './findAllExpandedChildNodeIds.js';
+export * from './getSearchedTreeItems.js';
+export * from './getSearchedTreeNodeById.js';
+export * from './lookupTreeForSelectedNodes.js';
+export * from './sortTreeItemsByTitle.js';
+export * from './traverse.js';
+export * from './traverseWithTarget.js';
+export * from './updateTreeNode.js';

package/dist/esm/helpers/lookupTreeForSelectedNodes.d.ts

@@ -0,0 +1,15 @@
+import { HierarchicalSelectionHandlers } from '@cloud-ru/ds-utils';
+import { ParentNode, TreeNodeId, TreeNodeProps } from '../types.js';
+/**
+ * Пересчитывает выбранные узлы для режима мультивыбора в дереве.
+ * Учитывает потомков текущего узла и корректирует состояние предков.
+ *
+ * @param params Параметры пересчета выделения.
+ * @returns Обновленный список выбранных id.
+ */
+export declare function lookupTreeForSelectedNodes({ node, selectedNodes, parentNode, toggleSelection, }: {
+    node: Pick<TreeNodeProps, 'id' | 'nested' | 'disabled'>;
+    selectedNodes: TreeNodeId[];
+    parentNode?: ParentNode;
+    toggleSelection: HierarchicalSelectionHandlers['toggleSelection'];
+}): string[];

package/dist/esm/helpers/lookupTreeForSelectedNodes.js

@@ -0,0 +1,18 @@
+import { collectHierarchicalAncestors } from './collectHierarchicalAncestors.js';
+import { findAllChildNodeIds } from './findAllChildNodeIds.js';
+/**
+ * Пересчитывает выбранные узлы для режима мультивыбора в дереве.
+ * Учитывает потомков текущего узла и корректирует состояние предков.
+ *
+ * @param params Параметры пересчета выделения.
+ * @returns Обновленный список выбранных id.
+ */
+export function lookupTreeForSelectedNodes({ node, selectedNodes, parentNode, toggleSelection, }) {
+    const descendantIds = node.nested?.length ? findAllChildNodeIds(node.nested) : [];
+    return toggleSelection({
+        nodeId: node.id,
+        descendantIds,
+        selectedIds: selectedNodes,
+        ancestors: collectHierarchicalAncestors(parentNode),
+    });
+}

package/dist/esm/helpers/sortTreeItemsByTitle.d.ts

@@ -0,0 +1,13 @@
+import { ExtendedTreeNodeProps } from '../types.js';
+/**
+ * Сортирует узлы дерева по заголовку в алфавитном порядке.
+ *
+ * @param items Список узлов для сортировки.
+ * @param options Опции сортировки. По умолчанию сортировка чувствительна к регистру.
+ * @returns Новый отсортированный массив.
+ */
+type SortTreeItemsByTitleOptions = {
+    caseSensitive?: boolean;
+};
+export declare const sortTreeItemsByTitle: (items: ExtendedTreeNodeProps[], options?: SortTreeItemsByTitleOptions) => ExtendedTreeNodeProps[];
+export {};

package/dist/esm/helpers/sortTreeItemsByTitle.js

@@ -0,0 +1,10 @@
+import { extractTreeNodeTitle } from './extractTreeNodeTitle.js';
+export const sortTreeItemsByTitle = (items, options) => items &&
+    [...items].sort((itemA, itemB) => {
+        const valueA = extractTreeNodeTitle(itemA);
+        const valueB = extractTreeNodeTitle(itemB);
+        if (options?.caseSensitive ?? true) {
+            return valueA.localeCompare(valueB);
+        }
+        return valueA.toLowerCase().localeCompare(valueB.toLowerCase());
+    });

package/dist/esm/helpers/traverse.d.ts

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

package/dist/esm/helpers/traverse.js

@@ -0,0 +1,21 @@
+/**
+ * Обходит дерево в ширину (BFS) и вызывает callback для каждого узла.
+ *
+ * Очередь — массив с курсором `head`: `shift()` на массиве переиндексирует весь хвост,
+ * а сдвиг курсора — O(1).
+ *
+ * @param nodes Корневые узлы дерева.
+ * @param callback Функция, вызываемая для каждого найденного узла.
+ */
+export const traverse = (nodes, callback) => {
+    const queue = 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, depth: depth + 1 });
+        }
+    }
+};

package/dist/esm/helpers/traverseWithTarget.d.ts

@@ -0,0 +1,14 @@
+import { TreeNodeProps } from '../types.js';
+/**
+ * Обходит дерево в ширину (BFS), передавая каждому узлу список,
+ * в который должен быть добавлен его трансформированный результат.
+ *
+ * Очередь — массив с курсором `head`: `shift()` на массиве переиндексирует весь хвост,
+ * а сдвиг курсора — O(1).
+ *
+ * @param nodes Корневые узлы дерева.
+ * @param rootTargetList Корневой список-приемник для преобразованных узлов.
+ * @param callback Функция обработки узла. Возвращает список для детей
+ * или undefined, если вложенные узлы обходить не нужно.
+ */
+export declare const traverseWithTarget: <T extends TreeNodeProps>(nodes: T[], rootTargetList: T[], callback: (node: T, depth: number, targetList: T[]) => T[] | undefined) => void;

package/dist/esm/helpers/traverseWithTarget.js

@@ -0,0 +1,26 @@
+/**
+ * Обходит дерево в ширину (BFS), передавая каждому узлу список,
+ * в который должен быть добавлен его трансформированный результат.
+ *
+ * Очередь — массив с курсором `head`: `shift()` на массиве переиндексирует весь хвост,
+ * а сдвиг курсора — O(1).
+ *
+ * @param nodes Корневые узлы дерева.
+ * @param rootTargetList Корневой список-приемник для преобразованных узлов.
+ * @param callback Функция обработки узла. Возвращает список для детей
+ * или undefined, если вложенные узлы обходить не нужно.
+ */
+export const traverseWithTarget = (nodes, rootTargetList, callback) => {
+    const queue = 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, depth: depth + 1, targetList: childTargetList });
+            }
+        }
+    }
+};

package/dist/esm/helpers/updateTreeNode.d.ts

@@ -0,0 +1,13 @@
+import { TreeNodeProps } from '../types.js';
+type UpdateTreeNodeData<Node extends TreeNodeProps> = Partial<TreeNodeProps> & {
+    nested?: Node[];
+};
+/**
+ * Возвращает копию дерева, где у узла с указанным id обновляются переданные поля.
+ *
+ * @param tree Исходное дерево.
+ * @param nodeId Идентификатор узла, который нужно обновить.
+ * @param data Частичные данные узла, которые будут применены к найденному элементу.
+ */
+export declare const updateTreeNode: <Node extends TreeNodeProps>(tree: Node[], nodeId: string, data: UpdateTreeNodeData<Node>) => Node[];
+export {};

package/dist/esm/helpers/updateTreeNode.js

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

package/dist/esm/hooks/index.d.ts

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

package/dist/esm/hooks/index.js

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

package/dist/esm/hooks/internalHooks.d.ts

@@ -0,0 +1,4 @@
+import { DependencyList, EffectCallback, MutableRefObject } from 'react';
+export declare function useRefState<T>(initial: T): MutableRefObject<T>;
+export declare function useDebounceValue<T>(value: T, delay: number): T;
+export declare function useDidUpdate(effect: EffectCallback, deps?: DependencyList): void;

package/dist/esm/hooks/internalHooks.js

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

package/dist/esm/hooks/useSearchableTree.d.ts

@@ -0,0 +1,52 @@
+import { SearchableTreeDataLoadResult, TreeNodeProps } from '../types.js';
+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 declare function useSearchableTree<TRecordValue, TTreeNode extends TreeNodeProps>({ initTree, onPreloadNode, onPreloadNodes, onSearch, mapNodeToRecordItem, }: UseSearchableTreeParams<TRecordValue, TTreeNode>): {
+    tree: import("react").MutableRefObject<TTreeNode[]>;
+    expandedNodes: import("react").MutableRefObject<string[]>;
+    loading: boolean;
+    treeItemsRecord: import("react").MutableRefObject<Record<string, TRecordValue>>;
+    search: {
+        value: string;
+        onChange: import("react").Dispatch<import("react").SetStateAction<string>>;
+    };
+    onExpand: (nodes: string[]) => void;
+    onDataLoad: (node: TreeNodeProps) => Promise<SearchableTreeDataLoadResult<TTreeNode, TRecordValue>>;
+};
+export {};

package/dist/esm/hooks/useSearchableTree.js

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { collectEmptyNestedNodesInExpanded, traverse, updateTreeNode } from '../helpers/index.js';
+import { useDebounceValue, useDidUpdate, useRefState } from './internalHooks.js';
+/**
+ * Хук для работы с деревом, поддерживающим поиск и асинхронную подгрузку узлов.
+ *
+ * Возможности:
+ * - хранение актуального дерева и записи элементов (`treeItemsRecord`);
+ * - управление раскрытыми узлами;
+ * - дебаунс-поиск с отменой предыдущего запроса;
+ * - дозагрузка дочерних узлов после поиска или раскрытия.
+ *
+ * @param params Параметры и обработчики для работы с деревом.
+ * @returns Ссылки на состояние дерева, контролы поиска и колбэки для `expand`/`dataLoad`.
+ */
+export function useSearchableTree({ initTree, onPreloadNode, onPreloadNodes, onSearch, mapNodeToRecordItem, }) {
+    const tree = useRefState(initTree);
+    const treeItemsRecord = useRefState({});
+    const expandedNodes = useRefState([]);
+    const [search, setSearch] = useState('');
+    const debouncedSearch = useDebounceValue(search, 500);
+    const [loading, setLoading] = useState(false);
+    // Актуальный запрос поиска. Он же маркер «этот вызов ещё не вытеснен следующим»:
+    // после каждого await сверяемся по идентичности, а не по отдельному флагу отмены.
+    const searchAbortControllerRef = useRef(null);
+    const buildTreeItemsRecord = useCallback((nodes) => {
+        const record = {};
+        traverse(nodes, node => {
+            record[node.id] = mapNodeToRecordItem(node);
+        });
+        return record;
+    }, [mapNodeToRecordItem]);
+    const onExpand = useCallback((nodes) => {
+        expandedNodes.current = nodes;
+    }, [expandedNodes]);
+    const onDataLoad = useCallback(async (node) => {
+        const preloadedChildren = await onPreloadNode(node);
+        const updatedTree = updateTreeNode(tree.current, node.id, { nested: preloadedChildren });
+        tree.current = updatedTree;
+        const newTreeItemsRecord = { ...treeItemsRecord.current };
+        traverse(preloadedChildren, child => {
+            newTreeItemsRecord[child.id] = mapNodeToRecordItem(child);
+        });
+        treeItemsRecord.current = newTreeItemsRecord;
+        return { preloadedChildren, updatedTree, newTreeItemsRecord };
+    }, [mapNodeToRecordItem, onPreloadNode, tree, treeItemsRecord]);
+    const handleSearch = useCallback(async (searchQuery) => {
+        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/dist/esm/hooks/useTreeMultiSelection.d.ts

@@ -0,0 +1,33 @@
+import { PreloadNodeHandler, SelectHandler, TreeNodeProps } from '../types.js';
+/**
+ * Параметры {@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 declare function useTreeMultiSelection<TTreeNode extends TreeNodeProps>({ onDataLoad, onSelect: onSelectProp, selected, onChangeSelected, }: UseTreeMultiSelectionParams<TTreeNode>): {
+    selected: string[];
+    onSelect: (selectedKeys: string[], node: TreeNodeProps) => Promise<void>;
+};
+export {};