@astral/ui 4.100.0 → 4.101.0

package/node/components/InfiniteTreeList/hooks/useEnterAnimation/useEnterAnimation.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useEnterAnimation = void 0;
+const react_1 = require("react");
+const constants_1 = require("../../constants");
+const NO_ANIMATION = { shouldAnimate: false };
+/**
+ * Управляет enter-анимацией строк дерева: метка живёт до первого mount строки
+ * и потребляется им
+ */
+const useEnterAnimation = () => {
+    const delayIndexes = (0, react_1.useRef)(new Map());
+    const resetTimer = (0, react_1.useRef)(undefined);
+    const reset = (0, react_1.useCallback)(() => {
+        clearTimeout(resetTimer.current);
+        delayIndexes.current.clear();
+    }, []);
+    const schedule = (0, react_1.useCallback)((itemIds, startDelayIndex = 0) => {
+        if (!itemIds.length) {
+            return;
+        }
+        itemIds.forEach((itemId, index) => delayIndexes.current.set(itemId, startDelayIndex + index));
+        clearTimeout(resetTimer.current);
+        resetTimer.current = setTimeout(reset, constants_1.ENTER_ANIMATION_MOUNT_WINDOW_MS);
+    }, [reset]);
+    const read = (0, react_1.useCallback)((itemId) => {
+        const delayIndex = delayIndexes.current.get(itemId);
+        if (delayIndex === undefined) {
+            return NO_ANIMATION;
+        }
+        return { shouldAnimate: true, delayIndex };
+    }, []);
+    const claim = (0, react_1.useCallback)((itemId) => {
+        delayIndexes.current.delete(itemId);
+    }, []);
+    (0, react_1.useEffect)(() => () => clearTimeout(resetTimer.current), []);
+    return (0, react_1.useMemo)(() => ({ schedule, read, claim, reset }), [schedule, read, claim, reset]);
+};
+exports.useEnterAnimation = useEnterAnimation;

package/node/components/InfiniteTreeList/hooks/useExpandNotifier/index.d.ts

@@ -0,0 +1 @@
+export * from './useExpandNotifier';

package/node/components/InfiniteTreeList/hooks/useExpandNotifier/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./useExpandNotifier"), exports);

package/node/components/InfiniteTreeList/hooks/useExpandNotifier/useExpandNotifier.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Блокирует повторные вызовы `onOpen`: узел сообщает о раскрытии один
+ * раз, пока ветка не свёрнута
+ */
+export declare const useExpandNotifier: () => {
+    notifyExpand: (itemId: string, onOpen?: () => void) => void;
+    resetExpandNotification: (itemIds: string[]) => void;
+};

package/node/components/InfiniteTreeList/hooks/useExpandNotifier/useExpandNotifier.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useExpandNotifier = void 0;
+const react_1 = require("react");
+/**
+ * Блокирует повторные вызовы `onOpen`: узел сообщает о раскрытии один
+ * раз, пока ветка не свёрнута
+ */
+const useExpandNotifier = () => {
+    const notifiedIdsRef = (0, react_1.useRef)(new Set());
+    const notifyExpand = (0, react_1.useCallback)((itemId, onOpen) => {
+        if (notifiedIdsRef.current.has(itemId)) {
+            return;
+        }
+        notifiedIdsRef.current.add(itemId);
+        onOpen?.();
+    }, []);
+    const resetExpandNotification = (0, react_1.useCallback)((itemIds) => {
+        itemIds.forEach((itemId) => notifiedIdsRef.current.delete(itemId));
+    }, []);
+    return { notifyExpand, resetExpandNotification };
+};
+exports.useExpandNotifier = useExpandNotifier;

package/node/components/InfiniteTreeList/hooks/useFlatTree/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './useFlatTree';

package/node/components/InfiniteTreeList/hooks/useFlatTree/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./useFlatTree"), exports);

package/node/components/InfiniteTreeList/hooks/useFlatTree/types.d.ts

@@ -0,0 +1,20 @@
+import type { InfiniteTreeListData } from '../../types';
+import type { EnterAnimationResult } from '../useEnterAnimation';
+export type UseFlatTreeParams<TData extends InfiniteTreeListData<TData>> = {
+    /**
+     * Дерево элементов из props списка
+     */
+    items: TData[];
+    /**
+     * Уровень раскрытия дерева по умолчанию
+     */
+    initialExpandedLevel?: number;
+    /**
+     * Контроллер enter-анимации: раскрытие узла помечает новые строки
+     */
+    enterAnimation: EnterAnimationResult;
+    /**
+     * Вызывается со списком свёрнутых узлов после анимации закрытия ветки
+     */
+    onCollapse: (itemIds: string[]) => void;
+};

package/node/components/InfiniteTreeList/hooks/useFlatTree/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/node/components/InfiniteTreeList/hooks/useFlatTree/useFlatTree.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="react" />
+import type { FlattenTree, InfiniteTreeListData } from '../../types';
+import type { UseFlatTreeParams } from './types';
+/**
+ * Управляет плоским списком строк и набором раскрытых узлов
+ */
+export declare const useFlatTree: <TData extends InfiniteTreeListData<TData>>({ items, initialExpandedLevel, enterAnimation, onCollapse, }: UseFlatTreeParams<TData>) => {
+    flatList: FlattenTree<TData>[];
+    flatListRef: import("react").RefObject<FlattenTree<TData>[]>;
+    expandedIds: Set<string>;
+    expandedIdsRef: import("react").RefObject<Set<string>>;
+    insertChildren: (parentId: string, childrenData: TData[]) => void;
+    syncChildrenPlaceholders: (parentId: string, isChildrenLoading: boolean, skeletonCount: number, isChildrenError?: boolean, isChildrenNoData?: boolean) => void;
+    onToggle: ({ id: itemId }: InfiniteTreeListData) => void;
+};

package/node/components/InfiniteTreeList/hooks/useFlatTree/useFlatTree.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFlatTree = void 0;
+const react_1 = require("react");
+const hooks_1 = require("../../../theme/hooks");
+const useSet_1 = require("../../../useSet");
+const utils_1 = require("../../utils");
+/**
+ * Управляет плоским списком строк и набором раскрытых узлов
+ */
+const useFlatTree = ({ items, initialExpandedLevel, enterAnimation, onCollapse, }) => {
+    const theme = (0, hooks_1.useTheme)();
+    const [expandedIds, { add: addExpandedId, remove: removeExpandedId }] = (0, useSet_1.useSet)(new Set());
+    const [flatList, setFlatList] = (0, react_1.useState)(() => (0, utils_1.flattenTree)(items, new Set()));
+    const expandedIdsRef = (0, react_1.useRef)(expandedIds);
+    const flatListRef = (0, react_1.useRef)(flatList);
+    // Синхронизация после коммита: запись в ref во время рендера — side effect,
+    // отброшенный рендер оставил бы в ref значение из дерева, которое
+    // не попало в коммит.
+    // Эффект объявлен первым, поэтому эффекты ниже по списку хуков читают из ref
+    // актуальные значения
+    (0, react_1.useEffect)(() => {
+        expandedIdsRef.current = expandedIds;
+        flatListRef.current = flatList;
+    });
+    const collapseTimersRef = (0, react_1.useRef)([]);
+    (0, react_1.useEffect)(() => () => {
+        collapseTimersRef.current.forEach(clearTimeout);
+    }, []);
+    (0, react_1.useEffect)(() => {
+        const next = (0, utils_1.getInitialExpandedIds)(expandedIdsRef.current, items, initialExpandedLevel);
+        next.forEach(addExpandedId);
+        expandedIdsRef.current = next;
+        setFlatList((0, utils_1.flattenTree)(items, next));
+    }, [items]);
+    const insertChildren = (0, react_1.useCallback)((parentId, childrenData) => {
+        setFlatList((prev) => (0, utils_1.insertChildren)(prev, parentId, childrenData, expandedIdsRef.current));
+    }, []);
+    const syncChildrenPlaceholders = (0, react_1.useCallback)((parentId, isChildrenLoading, skeletonCount, isChildrenError, isChildrenNoData) => {
+        setFlatList((prev) => (0, utils_1.syncChildrenPlaceholders)(prev, parentId, isChildrenLoading, skeletonCount, isChildrenError, isChildrenNoData));
+    }, []);
+    const expandNode = (0, react_1.useCallback)((itemId) => {
+        const staticChildren = flatListRef.current.find((item) => item.id === itemId)?.children;
+        enterAnimation.schedule(staticChildren?.map((child) => child.id) ?? []);
+        addExpandedId(itemId);
+        expandedIdsRef.current = new Set(expandedIdsRef.current).add(itemId);
+        setFlatList((prev) => {
+            const withExpanded = prev.map((item) => item.id === itemId
+                ? { ...item, meta: { ...item.meta, isExpanded: true } }
+                : item);
+            if (!staticChildren?.length) {
+                return withExpanded;
+            }
+            return (0, utils_1.insertChildren)(withExpanded, itemId, staticChildren, expandedIdsRef.current);
+        });
+    }, [addExpandedId, enterAnimation]);
+    const collapseNode = (0, react_1.useCallback)((itemId) => {
+        const nestedItems = (0, utils_1.sortCollapsed)((0, utils_1.getNestedItems)(flatListRef.current, itemId));
+        nestedItems.forEach(({ meta }) => (0, utils_1.startRemoveAnimation)(meta.nodeId));
+        // Ветка уходит из данных только после анимации закрытия
+        const timerId = setTimeout(() => {
+            collapseTimersRef.current = collapseTimersRef.current.filter((id) => id !== timerId);
+            const collapsedIds = [itemId, ...nestedItems.map(({ id }) => id)];
+            const nextExpanded = new Set(expandedIdsRef.current);
+            collapsedIds.forEach((collapsedId) => {
+                removeExpandedId(collapsedId);
+                nextExpanded.delete(collapsedId);
+            });
+            expandedIdsRef.current = nextExpanded;
+            onCollapse(collapsedIds);
+            setFlatList((prev) => (0, utils_1.removeChildren)(prev, itemId));
+        }, theme.transitions.duration.shorter);
+        collapseTimersRef.current.push(timerId);
+    }, [onCollapse, removeExpandedId, theme]);
+    const onToggle = (0, react_1.useCallback)(({ id: itemId }) => {
+        if (expandedIdsRef.current.has(itemId)) {
+            collapseNode(itemId);
+            return;
+        }
+        expandNode(itemId);
+    }, [collapseNode, expandNode]);
+    return {
+        flatList,
+        flatListRef,
+        expandedIds,
+        expandedIdsRef,
+        insertChildren,
+        syncChildrenPlaceholders,
+        onToggle,
+    };
+};
+exports.useFlatTree = useFlatTree;

package/node/components/InfiniteTreeList/hooks/useListScroll/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './useListScroll';

package/node/components/InfiniteTreeList/hooks/useListScroll/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./useListScroll"), exports);

package/node/components/InfiniteTreeList/hooks/useListScroll/types.d.ts

@@ -0,0 +1,25 @@
+import type { RefObject } from 'react';
+import type { FlattenTree, InfiniteTreeListData } from '../../types';
+import type { EnterAnimationResult } from '../useEnterAnimation';
+export type UseListScrollParams<TData extends InfiniteTreeListData<TData>> = {
+    /**
+     * Ref на контейнер, в котором должен быть скролл
+     */
+    scrollRef: RefObject<HTMLElement | null>;
+    /**
+     * Флаг достижения конца списка
+     */
+    isEndReached?: boolean;
+    /**
+     * Обработчик подгрузки данных
+     */
+    onLoadMore?: () => void;
+    /**
+     * Плоский список: реестр хвостов ищет в нём позицию строки
+     */
+    flatListRef: RefObject<FlattenTree<TData>[]>;
+    /**
+     * Контроллер enter-анимации: скролл снимает метки со строк
+     */
+    enterAnimation: EnterAnimationResult;
+};

package/node/components/InfiniteTreeList/hooks/useListScroll/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/node/components/InfiniteTreeList/hooks/useListScroll/useListScroll.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="react" />
+import type { ListRange, VirtuosoHandle } from 'react-virtuoso';
+import type { InfiniteTreeListData } from '../../types';
+import { type TailRegistry } from '../../utils';
+import type { UseListScrollParams } from './types';
+/**
+ * Скролл-обвязка списка: props для `Virtuoso`, кнопка «наверх» и реестр хвостов
+ * вложенных веток. Хвосты регистрируют сами строки, хук создаёт реестр и на
+ * смене видимого диапазона проверяет, попал ли хвост в кадр
+ */
+export declare const useListScroll: <TData extends InfiniteTreeListData<TData>>({ scrollRef, isEndReached, onLoadMore, flatListRef, enterAnimation, }: UseListScrollParams<TData>) => {
+    scrollParent: HTMLElement | null;
+    tailRegistry: TailRegistry;
+    isEndReachedWithScroll: boolean | undefined;
+    virtuosoProps: {
+        id: string;
+        ref: import("react").RefObject<VirtuosoHandle | null>;
+        overscan: number;
+        rangeChanged: (range: ListRange) => void;
+        endReached: () => void;
+        totalListHeightChanged: () => void;
+        isScrolling: (isScrolling: boolean) => void;
+    };
+    onTopButtonProps: {
+        buttonRef: import("react").RefObject<HTMLButtonElement | null>;
+        handleScrollToTop: () => void;
+        scrollRef: import("react").RefObject<HTMLElement | null>;
+    };
+};

package/node/components/InfiniteTreeList/hooks/useListScroll/useListScroll.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useListScroll = void 0;
+const react_1 = require("react");
+const useScrollManagement_1 = require("../../../useScrollManagement");
+const constants_1 = require("../../constants");
+const utils_1 = require("../../utils");
+/**
+ * Скролл-обвязка списка: props для `Virtuoso`, кнопка «наверх» и реестр хвостов
+ * вложенных веток. Хвосты регистрируют сами строки, хук создаёт реестр и на
+ * смене видимого диапазона проверяет, попал ли хвост в кадр
+ */
+const useListScroll = ({ scrollRef, isEndReached, onLoadMore, flatListRef, enterAnimation, }) => {
+    const virtuosoRef = (0, react_1.useRef)(null);
+    const scrollToTopButtonRef = (0, react_1.useRef)(null);
+    const tailRegistryRef = (0, react_1.useRef)(null);
+    if (!tailRegistryRef.current) {
+        tailRegistryRef.current = (0, utils_1.createTailRegistry)();
+    }
+    const tailRegistry = tailRegistryRef.current;
+    const { scrollParent, recalculateVerticalScroll, handleEndReach, isEndReachedWithScroll, } = (0, useScrollManagement_1.useScrollManagement)({
+        scrollRef,
+        isEndReached,
+        onLoadMore,
+        virtuosoId: constants_1.VIRTUOSO_CONTAINER_ID,
+    });
+    // Скролл виртуализации монтирует строки, которые появлением не считаются
+    const handleScrollingChange = (0, react_1.useCallback)((isScrolling) => {
+        if (isScrolling) {
+            enterAnimation.reset();
+        }
+    }, [enterAnimation]);
+    const handleRangeChanged = (0, react_1.useCallback)((range) => {
+        scrollToTopButtonRef.current?.classList.toggle(constants_1.infiniteTreeListClassnames.visibleScrollToTopButton, range.startIndex > 2);
+        tailRegistry.checkRange(range.endIndex, (itemId) => flatListRef.current.findIndex((item) => item.id === itemId));
+    }, [flatListRef, tailRegistry]);
+    const handleScrollToTop = (0, react_1.useCallback)(() => {
+        if (scrollRef.current) {
+            scrollRef.current.style.scrollBehavior = 'auto';
+        }
+        virtuosoRef.current?.scrollToIndex(0);
+    }, [scrollRef]);
+    return {
+        scrollParent,
+        tailRegistry,
+        isEndReachedWithScroll,
+        virtuosoProps: {
+            id: constants_1.VIRTUOSO_CONTAINER_ID,
+            ref: virtuosoRef,
+            overscan: constants_1.OVERSCAN,
+            rangeChanged: handleRangeChanged,
+            endReached: handleEndReach,
+            totalListHeightChanged: recalculateVerticalScroll,
+            isScrolling: handleScrollingChange,
+        },
+        onTopButtonProps: {
+            buttonRef: scrollToTopButtonRef,
+            handleScrollToTop,
+            scrollRef,
+        },
+    };
+};
+exports.useListScroll = useListScroll;

package/node/components/InfiniteTreeList/index.d.ts

@@ -1,4 +1,4 @@
 export { InfiniteTreeList } from './InfiniteTreeList';
-export type { InfiniteTreeListProps } from './types';
+export type { InfiniteTreeChildrenPagination, InfiniteTreeItemMeta, InfiniteTreeListProps, } from './types';
 export { InfiniteTreeListItem, type InfiniteTreeListItemProps, } from './InfiniteTreeListItem';
 export { type InfiniteTreeListActionProps, InfiniteTreeListActions, } from './InfiniteTreeListActions';

package/node/components/InfiniteTreeList/public.d.ts

@@ -1,4 +1,4 @@
 export { InfiniteTreeList } from './InfiniteTreeList';
 export { type InfiniteTreeListActionProps, InfiniteTreeListActions, } from './InfiniteTreeListActions';
 export { InfiniteTreeListItem, type InfiniteTreeListItemProps, } from './InfiniteTreeListItem';
-export type { InfiniteTreeListProps } from './types';
+export type { InfiniteTreeChildrenPagination, InfiniteTreeItemMeta, InfiniteTreeListProps, } from './types';

package/node/components/InfiniteTreeList/types.d.ts

@@ -1,34 +1,56 @@
 import type { ReactNode, RefObject } from 'react';
-/**
- * Базовый тип элемента дерева для InfiniteTreeList
- */
 export type InfiniteTreeListDataBase = {
     /**
      * Уникальный идентификатор элемента
      */
     id: string;
     /**
-     * Дополнительные  поля
+     * Дочерние элементы узла подгружаются отдельно: список раскрывает такой узел,
+     * показывает skeleton-строки и ждёт их из props строки (`childItems`).
+     *
+     * Статическое дерево описывается полем `children` и флага не требует
+     */
+    hasChildren?: boolean;
+    /**
+     * Дополнительные поля
      */
     [key: string]: unknown;
 };
-/**
- * Тип элемента дерева с возможными дочерними элементами
- */
 export type InfiniteTreeListData<TData extends InfiniteTreeListData<TData> = InfiniteTreeListDataBase> = InfiniteTreeListDataBase & {
     children?: TData[];
 };
+/**
+ * Состояние пагинации дочерних элементов узла
+ */
+export type InfiniteTreeChildrenPagination<TData extends InfiniteTreeListData<TData> = InfiniteTreeListDataBase> = {
+    /**
+     * Загруженные дочерние элементы узла
+     */
+    data: TData[];
+    /**
+     * Дочерние элементы загружаются
+     */
+    isLoading?: boolean;
+    /**
+     * Загрузка дочерних элементов завершилась ошибкой
+     */
+    isError?: boolean;
+    /**
+     * Все дочерние элементы узла загружены
+     */
+    isEndReached?: boolean;
+};
 export type InfiniteTreeListProps<TData extends InfiniteTreeListData<TData> = InfiniteTreeListDataBase> = {
     /**
      * Список элементов дерева
      */
     items: TData[];
     /**
-     * Если true, будет отображаться лоадер
+     * Список в состоянии загрузки
      */
     isLoading?: boolean;
     /**
-     * Если `true`, компонент будет отображаться в состоянии ошибки
+     * Список в состоянии ошибки
      */
     isError?: boolean;
     /**
@@ -48,11 +70,11 @@ export type InfiniteTreeListProps<TData extends InfiniteTreeListData<TData> = In
      */
     onLoadMore?: () => void;
     /**
-     * Реф на контейнер, в котором должен быть скролл
+     * Ref на контейнер, в котором должен быть скролл
      */
     scrollRef: RefObject<HTMLElement | null>;
     /**
-     * Рендер-функция элемента списка
+     * Рендер-функция строки без пагинации дочерних элементов.
      *
      * @example
      * renderItem={(item) => (
@@ -66,7 +88,29 @@ export type InfiniteTreeListProps<TData extends InfiniteTreeListData<TData> = In
         meta: InfiniteTreeItemMeta;
     }) => ReactNode;
     /**
-     * Уровень раскрытия дерева по умолчанию
+     * Рендер-функция строки узла с подгружаемыми дочерними элементами (`hasChildren`).
+     * Без `renderParent` такие узлы рендерит `renderItem`.
+     *
+     * @example
+     * renderParent={(item) => (
+     *                 <InfiniteTreeListItem
+     *                   isLoading={childrenState?.isLoading}
+     *                   isError={childrenState?.isError}
+     *                   isEndReached={childrenState?.isEndReached}
+     *                   childItems={childrenState?.data}
+     *                   onOpen={() => loadChildren(item.id)}
+     *                   onLoadMore={() => loadChildren(item.id)}
+     *                 >
+     *                   <Avatar>{item.avatarName}</Avatar>
+     *                   <Typography>{item.organization}</Typography>
+     *                 </InfiniteTreeListItem>
+     *               )}
+     */
+    renderParent?: (item: TData & {
+        meta: InfiniteTreeItemMeta;
+    }) => ReactNode;
+    /**
+     * Уровень раскрытия дерева по умолчанию.
      */
     initialExpandedLevel?: number;
     /**
@@ -74,7 +118,7 @@ export type InfiniteTreeListProps<TData extends InfiniteTreeListData<TData> = In
      */
     endOfScrollMsg?: string;
     /**
-     * Скелетон для элемента в состоянии загрузки
+     * Строка в состоянии загрузки.
      */
     itemSkeleton?: ReactNode;
     /**
@@ -93,7 +137,7 @@ export type InfiniteTreeItemMeta = {
      */
     level: number;
     /**
-     * Путь до элемента (массив id родителей)
+     * Путь до элемента: id всех родителей от корня и id самого элемента
      */
     path: string[];
     /**
@@ -101,22 +145,44 @@ export type InfiniteTreeItemMeta = {
      */
     parentId?: string;
     /**
-     * Индекс элемента среди siblings (для каскадной анимации)
+     * Индекс элемента среди соседей (siblings) для каскадной анимации
      */
     siblingIndex: number;
     /**
-     * Флаг имеет ли элемент вложенных потомков
+     * У элемента есть вложенные элементы: строка получает Chevron
      */
     hasNested: boolean;
+    /**
+     * Дочерние элементы узла подгружаются, а не лежат в `children`
+     */
+    isChildrenAsync: boolean;
     /**
      * Флаг раскрытия узла
      */
     isExpanded: boolean;
     /**
-     * Id Node элемента. Используется для анимации закрытия
+     * Id DOM-узла строки. Используется для анимации закрытия
      */
     nodeId: string;
 };
+/**
+ * Вид строки-заглушки, которой список замещает дочерние элементы раскрытого
+ * родителя:
+ * - `skeleton` — первая загрузка ветки, дочерних элементов ещё нет;
+ * - `spinner` — догрузка следующей порции под уже показанными дочерними
+ *   элементами;
+ * - `no-data` — ветка загрузилась пустой;
+ * - `error` — загрузка ветки упала
+ */
+export type ChildrenPlaceholderKind = 'skeleton' | 'spinner' | 'no-data' | 'error';
 export type FlattenTree<TData extends InfiniteTreeListData<TData>> = TData & {
     meta: InfiniteTreeItemMeta;
+    /**
+     * Вид строки-заглушки. У строк с данными потребителя поля нет
+     */
+    placeholderKind?: ChildrenPlaceholderKind;
+};
+export type FlattenTreeParent = {
+    id: string;
+    meta: Pick<InfiniteTreeItemMeta, 'path' | 'level'>;
 };

package/node/components/InfiniteTreeList/useLogic/useLogic.d.ts

@@ -1,38 +1,48 @@
 /// <reference types="react" />
 import { type ContentStateProps } from '../../ContentState';
-import type { FlattenTree, InfiniteTreeListData, InfiniteTreeListProps } from '../types';
+import type { ListFooterContext } from '../ListFooter';
+import type { InfiniteTreeListData, InfiniteTreeListProps } from '../types';
 type UseLogicParams<TData extends InfiniteTreeListData<TData>> = InfiniteTreeListProps<TData>;
-export declare const useLogic: <TData extends InfiniteTreeListData<TData>>({ initialExpandedLevel, items, onRetry, errorMsg, isError, isLoading, scrollRef, isEndReached, onLoadMore, renderItem, itemSkeleton, endOfScrollMsg, noDataImgSrc, errorImgSrc, }: UseLogicParams<TData>) => {
-    flatList: FlattenTree<TData>[];
+/**
+ * Логика списка: сводит плоский список, данные дочерних элементов, скролл
+ * и анимацию появления строк в props для `Virtuoso` и дочерних компонентов
+ */
+export declare const useLogic: <TData extends InfiniteTreeListData<TData>>({ initialExpandedLevel, items, onRetry, errorMsg, isError, isLoading, scrollRef, isEndReached, onLoadMore, renderItem, renderParent, itemSkeleton, endOfScrollMsg, noDataImgSrc, errorImgSrc, }: UseLogicParams<TData>) => {
+    flatList: import("../types").FlattenTree<TData>[];
     onToggle: ({ id: itemId }: InfiniteTreeListData) => void;
+    nodePaginationMap: Record<string, import("../InfiniteTreeListContext").NodePagination>;
+    registerChildren: (itemId: string, childrenState: import("../types").InfiniteTreeChildrenPagination) => void;
+    notifyExpand: (itemId: string, onOpen?: (() => void) | undefined) => void;
+    parentItems: import("../types").FlattenTree<TData>[];
+    acquireParentSlot: (itemId: string) => HTMLDivElement | null;
     contentStateProps: Omit<ContentStateProps, "children">;
     scrollParent: HTMLElement | null;
     virtuosoProps: {
         id: string;
         ref: import("react").RefObject<import("react-virtuoso").VirtuosoHandle | null>;
+        overscan: number;
         rangeChanged: (range: import("react-virtuoso").ListRange) => void;
         endReached: () => void;
         totalListHeightChanged: () => void;
+        isScrolling: (isScrolling: boolean) => void;
     };
-    footerProps: {
-        isError: boolean | undefined;
-        isLoading: boolean | undefined;
-        isEndReached: boolean | undefined;
-    };
+    footerContext: ListFooterContext;
     onTopButtonProps: {
-        isActive: boolean;
+        buttonRef: import("react").RefObject<HTMLButtonElement | null>;
         handleScrollToTop: () => void;
         scrollRef: import("react").RefObject<HTMLElement | null>;
     };
-    endOfScrollMsg: string | undefined;
     itemSkeleton: import("react").ReactNode;
     renderItem: (item: TData & {
         meta: import("../types").InfiniteTreeItemMeta;
     }) => import("react").ReactNode;
+    renderParent: (item: TData & {
+        meta: import("../types").InfiniteTreeItemMeta;
+    }) => import("react").ReactNode;
     items: TData[];
-    onLoadMore: (() => void) | undefined;
     onRetry: () => void;
     noDataImgSrc: string | undefined;
-    recentlyExpandedIds: import("react").RefObject<Set<string>>;
+    enterAnimation: import("../hooks").EnterAnimationResult;
+    tailRegistry: import("../utils").TailRegistry;
 };
 export {};