@astral/ui 4.100.0 → 4.101.0

package/components/InfiniteTreeList/TreeItem/ParentSlot/ParentSlot.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useLayoutEffect, useRef } from 'react';
+import { infiniteTreeListClassnames } from '../../constants';
+import { InfiniteTreeListContext } from '../../InfiniteTreeListContext';
+import { Host } from './styles';
+/**
+ * Слот строки родительского узла списка
+ */
+export const ParentSlot = ({ itemId }) => {
+    const { acquireParentSlot, enterAnimation } = useContext(InfiniteTreeListContext);
+    const hostRef = useRef(null);
+    useLayoutEffect(() => {
+        const host = hostRef.current;
+        const slot = acquireParentSlot(itemId);
+        if (!host || !slot) {
+            return;
+        }
+        host.appendChild(slot);
+        const row = slot.firstElementChild;
+        if (row instanceof HTMLElement) {
+            // Без снятия узел вернулся бы в список с анимацией исчезновения от
+            // прошлого сворачивания ветки
+            row.classList.remove(infiniteTreeListClassnames.rowRemoveAnimation);
+            const { shouldAnimate, delayIndex } = enterAnimation.read(itemId);
+            row.classList.toggle(infiniteTreeListClassnames.rowAddAnimation, shouldAnimate);
+            if (shouldAnimate && delayIndex !== undefined) {
+                row.style.setProperty('--sibling-index', String(delayIndex));
+            }
+        }
+        enterAnimation.claim(itemId);
+        // Контейнер не удаляется, а открепляется: строка остаётся смонтированной и
+        // ждёт следующего появления узла на экране
+        return () => {
+            slot.remove();
+        };
+    }, [itemId, acquireParentSlot, enterAnimation]);
+    return _jsx(Host, { ref: hostRef });
+};

package/components/InfiniteTreeList/TreeItem/ParentSlot/index.d.ts

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

package/components/InfiniteTreeList/TreeItem/ParentSlot/index.js

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

package/components/InfiniteTreeList/TreeItem/ParentSlot/styles.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="react" />
+/**
+ * Место строки узла в скролле. Своего box не создаёт: отступы и раскладка
+ * перенесённой строки считаются так же, как если бы она была здесь всегда
+ */
+export declare const Host: import("../../../styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme | undefined;
+    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/components/InfiniteTreeList/TreeItem/ParentSlot/styles.js

@@ -0,0 +1,8 @@
+import { styled } from '../../../styled';
+/**
+ * Место строки узла в скролле. Своего box не создаёт: отступы и раскладка
+ * перенесённой строки считаются так же, как если бы она была здесь всегда
+ */
+export const Host = styled.div `
+  display: contents;
+`;

package/components/InfiniteTreeList/TreeItem/ParentSlot/types.d.ts

@@ -0,0 +1,6 @@
+export type ParentSlotProps = {
+    /**
+     * Id узла, чей контейнер занимает строка
+     */
+    itemId: string;
+};

package/components/InfiniteTreeList/TreeItem/ParentSlot/types.js

@@ -0,0 +1 @@
+export {};

package/components/InfiniteTreeList/TreeItem/TreeItem.d.ts

@@ -1,3 +1,6 @@
-import type { InfiniteTreeListData } from '../types';
 import { type TreeItemProps } from './types';
-export declare const TreeItem: <TData extends InfiniteTreeListData<TData>>(props: TreeItemProps<TData>) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Строка виртуализации: обёртка, которую `Virtuoso` рендерит вокруг элемента.
+ * Ставит контекст строки, css-переменные уровня и каскада, classname анимации
+ */
+export declare const TreeItem: ({ children, ...props }: TreeItemProps) => import("react/jsx-runtime").JSX.Element;

package/components/InfiniteTreeList/TreeItem/TreeItem.js

@@ -1,8 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { cva } from '../../utils/cva';
+import { infiniteTreeListClassnames } from '../constants';
+import { TreeListItemContextProvider } from '../InfiniteTreeListItem';
+import { ChildrenPlaceholder } from './ChildrenPlaceholder';
+import { CustomItemWrapper } from './CustomItemWrapper';
+import { ParentSlot } from './ParentSlot';
 import { Wrapper } from './styles';
 import { useLogic } from './useLogic';
-export const TreeItem = (props) => {
-    const { item, renderItem, classname, onAnimationEnd } = useLogic(props);
-    const { nodeId, level, siblingIndex } = item.meta;
-    return (_jsx(Wrapper, { id: nodeId, className: classname, "$level": level, "$siblingIndex": siblingIndex, onAnimationEnd: onAnimationEnd, children: renderItem(item) }));
+const treeItemCva = cva(infiniteTreeListClassnames.row, {
+    variants: {
+        isSpinner: {
+            true: infiniteTreeListClassnames.rowSpinner,
+        },
+        hasAddAnimation: {
+            true: infiniteTreeListClassnames.rowAddAnimation,
+        },
+    },
+});
+/**
+ * Строка виртуализации: обёртка, которую `Virtuoso` рендерит вокруг элемента.
+ * Ставит контекст строки, css-переменные уровня и каскада, classname анимации
+ */
+export const TreeItem = ({ children, ...props }) => {
+    const { item, renderItem, onToggle, memoizedItemProps, cssVars, isSpinner, hasAddAnimation, } = useLogic(props);
+    const { nodeId, isChildrenAsync } = item.meta;
+    // Строку узла с подгружаемыми дочерними элементами рисует не список,
+    // а постоянный слой: сюда она приезжает готовым DOM-узлом. Иначе store,
+    // заведённый потребителем внутри renderParent, умирал бы на каждом уходе
+    // строки со скролла
+    if (isChildrenAsync && !item.placeholderKind) {
+        return (_jsx("div", { ...memoizedItemProps, children: _jsx(ParentSlot, { itemId: item.id }) }));
+    }
+    return (_jsx("div", { ...memoizedItemProps, children: _jsx(TreeListItemContextProvider, { item: item, onToggle: onToggle, children: _jsx(Wrapper, { id: nodeId, className: treeItemCva({ isSpinner, hasAddAnimation }), style: cssVars, children: item.placeholderKind ? (_jsx(ChildrenPlaceholder, { item: item })) : (_jsx(CustomItemWrapper, { item: item, renderItem: renderItem })) }) }) }));
 };

package/components/InfiniteTreeList/TreeItem/constants.d.ts

@@ -1 +1,4 @@
+/**
+ * Задержка каскадной анимации между соседними строками, мс
+ */
 export declare const ANIMATION_DELAY = 30;

package/components/InfiniteTreeList/TreeItem/constants.js

@@ -1,2 +1,4 @@
-// Задержка для каскадной анимации элементов в ms
+/**
+ * Задержка каскадной анимации между соседними строками, мс
+ */
 export const ANIMATION_DELAY = 30;

package/components/InfiniteTreeList/TreeItem/styles.d.ts

@@ -2,7 +2,4 @@
 export declare const Wrapper: import("../../styled").StyledComponent<{
     theme?: import("@emotion/react").Theme | undefined;
     as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
-} & {
-    $level: number;
-    $siblingIndex?: number | undefined;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/components/InfiniteTreeList/TreeItem/styles.js

@@ -3,6 +3,9 @@ import { tooltipClassnames } from '../../Tooltip';
 import { infiniteTreeListClassnames } from '../constants';
 import { ANIMATION_DELAY } from './constants';
 export const Wrapper = styled.div `
+  --level: 0;
+  --sibling-index: 0;
+
   @keyframes slide-in-from-left {
     0% {
       transform: translateX(-16px);
@@ -39,21 +42,33 @@ export const Wrapper = styled.div `
 
   min-height: 60px;
   margin-top: ${({ theme }) => theme.spacing(1)};
-  margin-left: ${({ $level }) => `calc(${$level} * 20px)`};
+  margin-left: calc(var(--level) * ${({ theme }) => theme.spacing(5)});
 
   border: 1px solid ${({ theme }) => theme.palette.components.border.default};
   border-radius: ${({ theme }) => theme.shape.medium};
-  
-  &.${infiniteTreeListClassnames.addAnimation} {
-    animation: slide-in-from-left ${({ theme }) => theme.transitions.duration.short}ms ease-out;
+
+  &.${infiniteTreeListClassnames.rowAddAnimation} {
+    animation: slide-in-from-left
+      ${({ theme }) => theme.transitions.duration.short}ms ease-out;
     animation-fill-mode: both;
-    animation-delay: ${({ $siblingIndex = 0 }) => $siblingIndex * ANIMATION_DELAY}ms;
+    animation-delay: calc(var(--sibling-index) * ${ANIMATION_DELAY}ms);
   }
 
-  &.${infiniteTreeListClassnames.removeAnimation} {
-    animation: slide-out-to-left ${({ theme }) => theme.transitions.duration.shorter}ms ease-in forwards;
+  &.${infiniteTreeListClassnames.rowRemoveAnimation} {
+    animation: slide-out-to-left
+      ${({ theme }) => theme.transitions.duration.shorter}ms ease-in forwards;
     animation-fill-mode: both;
-    animation-delay: ${({ $siblingIndex = 0 }) => $siblingIndex * ANIMATION_DELAY}ms;
+    animation-delay: calc(var(--sibling-index) * ${ANIMATION_DELAY}ms);
+  }
+
+  &.${infiniteTreeListClassnames.rowSpinner} {
+    justify-content: center;
+
+    width: 100%;
+    min-height: 64px;
+
+    background: transparent;
+    border: none;
   }
 
   & > .${tooltipClassnames.contentWrapper} {

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

@@ -1,9 +1,4 @@
-import type { ReactNode, RefObject } from 'react';
-import { type FlattenTree, type InfiniteTreeItemMeta, type InfiniteTreeListData } from '../types';
-export type TreeItemProps<TData extends InfiniteTreeListData<TData>> = {
-    item: FlattenTree<TData>;
-    renderItem: (item: TData & {
-        meta: InfiniteTreeItemMeta;
-    }) => ReactNode;
-    recentlyExpandedIds: RefObject<Set<string>>;
-};
+import type { ContextProp, ItemProps as VirtuosoItemProps } from 'react-virtuoso';
+import { type ListFooterContext } from '../ListFooter';
+import type { FlattenTree, InfiniteTreeListData } from '../types';
+export type TreeItemProps = VirtuosoItemProps<FlattenTree<InfiniteTreeListData>> & ContextProp<ListFooterContext>;

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

@@ -1,11 +1,31 @@
-/// <reference types="react" />
-import type { InfiniteTreeListData } from '../../types';
+import { type CSSProperties } from 'react';
 import { type TreeItemProps } from '../types';
-export declare const useLogic: <TData extends InfiniteTreeListData<TData>>({ item, renderItem, recentlyExpandedIds, }: TreeItemProps<TData>) => {
-    item: import("../../types").FlattenTree<TData>;
-    renderItem: (item: TData & {
-        meta: import("../../types").InfiniteTreeItemMeta;
-    }) => import("react").ReactNode;
-    classname: string;
-    onAnimationEnd: () => void;
+type UseLogicParams = Omit<TreeItemProps, 'children'>;
+/**
+ * Логика строки виртуализации: регистрирует хвост ветки в реестре, один раз
+ * на mount читает метку enter-анимации и считает css-переменные строки.
+ *
+ * Про хвост: `Virtuoso` виртуализирует плоский список, и его `endReached` —
+ * это конец всего списка, то есть корневая пагинация. У вложенной пагинации
+ * свой признак конца: последний загруженный дочерний элемент раскрытой
+ * ветки. Такая строка пишет себя в `tailRegistry`, а `useListScroll` на смене
+ * видимого диапазона зовёт `checkRange` — попал хвост в кадр, ветка просит
+ * `onLoadMore(parentId)`. Отдельного элемента-sentinel в разметке для
+ * этого нет
+ */
+export declare const useLogic: ({ item, context, ...itemProps }: UseLogicParams) => {
+    item: import("../../types").FlattenTree<import("../../types").InfiniteTreeListData>;
+    renderItem: (item: import("../../types").FlattenTree<import("../../types").InfiniteTreeListData>) => import("react").ReactNode;
+    onToggle: (item: import("../../types").InfiniteTreeListData) => void;
+    memoizedItemProps: {
+        style?: CSSProperties | undefined;
+        'data-index': number;
+        'data-item-group-index'?: number | undefined;
+        'data-item-index': number;
+        'data-known-size': number;
+    };
+    cssVars: CSSProperties;
+    isSpinner: boolean;
+    hasAddAnimation: boolean;
 };
+export {};

package/components/InfiniteTreeList/TreeItem/useLogic/useLogic.js

@@ -1,24 +1,66 @@
-import { useEffect, useMemo } from 'react';
-import { infiniteTreeListClassnames } from '../../constants';
-export const useLogic = ({ item, renderItem, recentlyExpandedIds, }) => {
-    const deleteRecentlyExpandedId = () => {
-        item.meta.parentId &&
-            recentlyExpandedIds.current?.delete(item.meta.parentId);
-    };
+// cspell:ignore виртуализирует
+import { useContext, useEffect, useMemo, useRef, } from 'react';
+import { InfiniteTreeListContext } from '../../InfiniteTreeListContext';
+/**
+ * Логика строки виртуализации: регистрирует хвост ветки в реестре, один раз
+ * на mount читает метку enter-анимации и считает css-переменные строки.
+ *
+ * Про хвост: `Virtuoso` виртуализирует плоский список, и его `endReached` —
+ * это конец всего списка, то есть корневая пагинация. У вложенной пагинации
+ * свой признак конца: последний загруженный дочерний элемент раскрытой
+ * ветки. Такая строка пишет себя в `tailRegistry`, а `useListScroll` на смене
+ * видимого диапазона зовёт `checkRange` — попал хвост в кадр, ветка просит
+ * `onLoadMore(parentId)`. Отдельного элемента-sentinel в разметке для
+ * этого нет
+ */
+export const useLogic = ({ item, context, ...itemProps }) => {
+    const { renderItem, onToggle, nodePaginationMap, onLoadMore, enterAnimation, tailRegistry, } = useContext(InfiniteTreeListContext);
+    const memoizedItemProps = useMemo(() => itemProps, [itemProps.style]);
+    const { parentId, siblingIndex, level } = item.meta;
+    const parentPagination = parentId ? nodePaginationMap[parentId] : undefined;
+    const isLastChild = parentPagination?.lastChildId === item.id;
+    const shouldRegister = Boolean(isLastChild &&
+        parentId &&
+        !parentPagination?.isEndReached &&
+        !parentPagination?.isChildrenLoading &&
+        !parentPagination?.isChildrenError);
+    // Решение об анимации принимается один раз, на mount строки. Чтение метки
+    // не меняет состояние, поэтому отброшенный рендер ничего не ломает
+    const enterState = useRef(null);
+    if (!enterState.current) {
+        enterState.current = enterAnimation.read(item.id);
+    }
+    const { shouldAnimate, delayIndex } = enterState.current;
+    // Метка забирается после коммита: повторный mount строки при скролле
+    // виртуализации анимации уже не получит
+    useEffect(() => {
+        enterAnimation.claim(item.id);
+    }, []);
     useEffect(() => {
+        if (!shouldRegister || !parentId) {
+            return;
+        }
+        const registeredParentId = parentId;
+        const registeredItemId = item.id;
+        tailRegistry.register(registeredParentId, registeredItemId, () => onLoadMore(registeredParentId));
         return () => {
-            deleteRecentlyExpandedId();
+            tailRegistry.unregister(registeredParentId, registeredItemId);
         };
-    }, []);
-    const onAnimationEnd = () => {
-        deleteRecentlyExpandedId();
+    }, [shouldRegister, parentId, item.id, tailRegistry, onLoadMore]);
+    const isSpinner = item.placeholderKind === 'spinner';
+    // Уровень вложенности и индекс каскада — динамические значения, поэтому
+    // передаются в стили через css vars, а не через styled props
+    const cssVars = {
+        '--level': level,
+        '--sibling-index': delayIndex ?? siblingIndex,
+    };
+    return {
+        item,
+        renderItem,
+        onToggle,
+        memoizedItemProps,
+        cssVars,
+        isSpinner,
+        hasAddAnimation: !isSpinner && shouldAnimate,
     };
-    const classname = useMemo(() => {
-        if (item?.meta.parentId &&
-            recentlyExpandedIds.current?.has(item?.meta.parentId)) {
-            return infiniteTreeListClassnames.addAnimation;
-        }
-        return '';
-    }, [item.id]);
-    return { item, renderItem, classname, onAnimationEnd };
 };

package/components/InfiniteTreeList/constants.d.ts

@@ -1,6 +1,18 @@
 export declare const VIRTUOSO_CONTAINER_ID = "virtuoso-container";
 export declare const OVERSCAN = 30;
+/**
+ * Окно ожидания mount строки, помеченной для enter-анимации.
+ * Virtuoso монтирует видимые дочерние строки в следующем кадре после смены
+ * data, поэтому `useLayoutEffect` снимает метку слишком рано
+ */
+export declare const ENTER_ANIMATION_MOUNT_WINDOW_MS = 100;
+export declare const CHILDREN_SKELETON_COUNT = 3;
+export declare const CHILDREN_NO_DATA_MSG = "\u041D\u0435\u0442 \u0434\u0430\u043D\u043D\u044B\u0445";
 export declare const infiniteTreeListClassnames: {
-    addAnimation: string;
-    removeAnimation: string;
+    row: string;
+    rowAddAnimation: string;
+    rowRemoveAnimation: string;
+    rowSpinner: string;
+    scrollToTopButton: string;
+    visibleScrollToTopButton: string;
 };

package/components/InfiniteTreeList/constants.js

@@ -1,7 +1,19 @@
 import { createUIKitClassname } from '../utils/createUIKitClassname';
 export const VIRTUOSO_CONTAINER_ID = 'virtuoso-container';
 export const OVERSCAN = 30;
+/**
+ * Окно ожидания mount строки, помеченной для enter-анимации.
+ * Virtuoso монтирует видимые дочерние строки в следующем кадре после смены
+ * data, поэтому `useLayoutEffect` снимает метку слишком рано
+ */
+export const ENTER_ANIMATION_MOUNT_WINDOW_MS = 100;
+export const CHILDREN_SKELETON_COUNT = 3;
+export const CHILDREN_NO_DATA_MSG = 'Нет данных';
 export const infiniteTreeListClassnames = {
-    addAnimation: createUIKitClassname('infinite-tree-list_add-animation'),
-    removeAnimation: createUIKitClassname('infinite-tree-list_remove-animation'),
+    row: createUIKitClassname('infinite-tree-list__row'),
+    rowAddAnimation: createUIKitClassname('infinite-tree-list__row_add-animation'),
+    rowRemoveAnimation: createUIKitClassname('infinite-tree-list__row_remove-animation'),
+    rowSpinner: createUIKitClassname('infinite-tree-list__row_spinner'),
+    scrollToTopButton: createUIKitClassname('infinite-tree-list__scroll-to-top-button'),
+    visibleScrollToTopButton: createUIKitClassname('infinite-tree-list__scroll-to-top-button_visible'),
 };

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

@@ -0,0 +1,5 @@
+export * from './useChildrenState';
+export * from './useEnterAnimation';
+export * from './useExpandNotifier';
+export * from './useFlatTree';
+export * from './useListScroll';

package/components/InfiniteTreeList/hooks/index.js

@@ -0,0 +1,5 @@
+export * from './useChildrenState';
+export * from './useEnterAnimation';
+export * from './useExpandNotifier';
+export * from './useFlatTree';
+export * from './useListScroll';

package/components/InfiniteTreeList/hooks/useChildrenState/index.d.ts

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

package/components/InfiniteTreeList/hooks/useChildrenState/index.js

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

package/components/InfiniteTreeList/hooks/useChildrenState/types.d.ts

@@ -0,0 +1,43 @@
+import type { RefObject } from 'react';
+import type { FlattenTree, InfiniteTreeListData } from '../../types';
+import type { EnterAnimationResult } from '../useEnterAnimation';
+export type UseChildrenStateParams<TData extends InfiniteTreeListData<TData>> = {
+    /**
+     * Данные списка
+     */
+    items: TData[];
+    /**
+     * Плоский список строк
+     */
+    flatList: FlattenTree<TData>[];
+    /**
+     * Список для синхронного чтения
+     */
+    flatListRef: RefObject<FlattenTree<TData>[]>;
+    /**
+     * Набор раскрытых узлов
+     */
+    expandedIds: Set<string>;
+    /**
+     * Набор раскрытых узлов для синхронного чтения
+     */
+    expandedIdsRef: RefObject<Set<string>>;
+    /**
+     * Контроллер enter-анимации: метит новые дочерние элементы
+     * и skeleton-узлы
+     */
+    enterAnimation: EnterAnimationResult;
+    /**
+     * Вставляет дочерние элементы узла в плоский список
+     */
+    insertChildren: (parentId: string, childrenData: TData[]) => void;
+    /**
+     * Функция управления placeholder ветки родителя
+     */
+    syncChildrenPlaceholders: (parentId: string, isChildrenLoading: boolean, skeletonCount: number, isChildrenError?: boolean, isChildrenNoData?: boolean) => void;
+    skeletonCount: number;
+    /**
+     * Выбрасывает контейнер строки узла, которого больше нет в данных
+     */
+    releaseParentSlot: (itemId: string) => void;
+};

package/components/InfiniteTreeList/hooks/useChildrenState/types.js

@@ -0,0 +1 @@
+export {};

package/components/InfiniteTreeList/hooks/useChildrenState/useChildrenState.d.ts

@@ -0,0 +1,20 @@
+import type { NodePagination } from '../../InfiniteTreeListContext';
+import type { FlattenTree, InfiniteTreeChildrenPagination, InfiniteTreeListData } from '../../types';
+import type { UseChildrenStateParams } from './types';
+/**
+ * Сводит данные дочерних элементов раскрытых узлов в плоский список:
+ * вставляет их, ставит заглушки ветки, собирает пагинацию узлов и метит новые
+ * строки для enter-анимации. Дочерние элементы отдаёт строка узла
+ * (`childItems`, `isLoading`, `isError`), не props списка.
+ *
+ * Дочерние элементы смонтированными хук не держит — их строки живут
+ * по правилам виртуализации. Строки узлов с подгружаемыми дочерними
+ * элементами, наоборот, монтируются один раз и живут, пока жив список:
+ * их состояние не должно умирать ни от ухода строки со скролла,
+ * ни от сворачивания ветки
+ */
+export declare const useChildrenState: <TData extends InfiniteTreeListData<TData>>({ items, flatList, flatListRef, expandedIds, expandedIdsRef, enterAnimation, insertChildren, syncChildrenPlaceholders, skeletonCount, releaseParentSlot, }: UseChildrenStateParams<TData>) => {
+    registerChildren: (itemId: string, childrenState: InfiniteTreeChildrenPagination) => void;
+    nodePaginationMap: Record<string, NodePagination>;
+    parentItems: FlattenTree<TData>[];
+};

package/components/InfiniteTreeList/hooks/useChildrenState/useChildrenState.js

@@ -0,0 +1,115 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { checkHasSkeletonPlaceholders, checkIsNoDataChildren, checkIsSameChildren, countDirectChildren, getChildrenPlaceholderIds, getEnteringChildren, getIdsToKeep, } from '../../utils';
+/**
+ * Сводит данные дочерних элементов раскрытых узлов в плоский список:
+ * вставляет их, ставит заглушки ветки, собирает пагинацию узлов и метит новые
+ * строки для enter-анимации. Дочерние элементы отдаёт строка узла
+ * (`childItems`, `isLoading`, `isError`), не props списка.
+ *
+ * Дочерние элементы смонтированными хук не держит — их строки живут
+ * по правилам виртуализации. Строки узлов с подгружаемыми дочерними
+ * элементами, наоборот, монтируются один раз и живут, пока жив список:
+ * их состояние не должно умирать ни от ухода строки со скролла,
+ * ни от сворачивания ветки
+ */
+export const useChildrenState = ({ items, flatList, flatListRef, expandedIds, expandedIdsRef, enterAnimation, insertChildren, syncChildrenPlaceholders, skeletonCount, releaseParentSlot, }) => {
+    const [childrenStateMap, setChildrenStateMap] = useState({});
+    const childrenStateMapRef = useRef(childrenStateMap);
+    // Синхронизация после коммита: запись в ref во время рендера — side effect,
+    // отброшенный рендер оставил бы в ref значение из дерева, которое
+    // не попало в коммит
+    useEffect(() => {
+        childrenStateMapRef.current = childrenStateMap;
+    });
+    const loadedOnceIdsRef = useRef(new Set());
+    const registerChildren = useCallback((itemId, childrenState) => {
+        const nextChildren = childrenState;
+        setChildrenStateMap((prev) => {
+            if (checkIsSameChildren(prev[itemId], nextChildren)) {
+                return prev;
+            }
+            return { ...prev, [itemId]: nextChildren };
+        });
+    }, []);
+    const resolveNoData = useCallback((parentId, childrenState) => {
+        const hasLoadedOnce = loadedOnceIdsRef.current.has(parentId);
+        if (childrenState.isLoading) {
+            loadedOnceIdsRef.current.add(parentId);
+        }
+        return checkIsNoDataChildren(childrenState, hasLoadedOnce);
+    }, []);
+    const syncChildren = useCallback((parentId, childrenState) => {
+        const existingDirectCount = countDirectChildren(flatListRef.current, parentId);
+        const hasSkeletons = checkHasSkeletonPlaceholders(flatListRef.current, parentId);
+        insertChildren(parentId, childrenState.data);
+        syncChildrenPlaceholders(parentId, Boolean(childrenState.isLoading), skeletonCount, childrenState.isError, resolveNoData(parentId, childrenState));
+        if (childrenState.isLoading) {
+            // Первая загрузка необходима для skeleton-элементов
+            const firstLoading = existingDirectCount === 0 && !hasSkeletons;
+            if (firstLoading) {
+                enterAnimation.schedule(getChildrenPlaceholderIds(parentId, skeletonCount));
+            }
+            return;
+        }
+        if (childrenState.isError ||
+            childrenState.data.length <= existingDirectCount) {
+            return;
+        }
+        const { itemIds, startDelayIndex } = getEnteringChildren(childrenState.data.map((item) => item.id), existingDirectCount, hasSkeletons ? skeletonCount : 0);
+        enterAnimation.schedule(itemIds, startDelayIndex);
+    }, [
+        enterAnimation,
+        flatListRef,
+        insertChildren,
+        resolveNoData,
+        skeletonCount,
+        syncChildrenPlaceholders,
+    ]);
+    useEffect(() => {
+        Object.entries(childrenStateMap).forEach(([parentId, childrenState]) => {
+            if (expandedIdsRef.current.has(parentId)) {
+                syncChildren(parentId, childrenState);
+            }
+        });
+    }, [childrenStateMap, expandedIds]);
+    const nodePaginationMap = useMemo(() => Object.entries(childrenStateMap).reduce((acc, [parentId, childrenState]) => {
+        acc[parentId] = {
+            lastChildId: childrenState.data[childrenState.data.length - 1]?.id,
+            isEndReached: childrenState.isEndReached,
+            isChildrenLoading: childrenState.isLoading,
+            isChildrenError: childrenState.isError,
+        };
+        return acc;
+    }, {}), [childrenStateMap]);
+    const parentItemsRef = useRef(new Map());
+    const parentItems = useMemo(() => {
+        flatList.forEach((item) => {
+            if (item.meta.isChildrenAsync) {
+                parentItemsRef.current.set(item.id, item);
+            }
+        });
+        return [...parentItemsRef.current.values()];
+    }, [flatList]);
+    useEffect(() => {
+        const idsToKeep = getIdsToKeep(items, childrenStateMapRef.current);
+        parentItemsRef.current.forEach((_, itemId) => {
+            if (!idsToKeep.has(itemId)) {
+                parentItemsRef.current.delete(itemId);
+                releaseParentSlot(itemId);
+            }
+        });
+        loadedOnceIdsRef.current.forEach((itemId) => {
+            if (!idsToKeep.has(itemId)) {
+                loadedOnceIdsRef.current.delete(itemId);
+            }
+        });
+        setChildrenStateMap((prev) => {
+            const entriesToKeep = Object.entries(prev).filter(([itemId]) => idsToKeep.has(itemId));
+            if (entriesToKeep.length === Object.keys(prev).length) {
+                return prev;
+            }
+            return Object.fromEntries(entriesToKeep);
+        });
+    }, [items, releaseParentSlot]);
+    return { registerChildren, nodePaginationMap, parentItems };
+};

package/components/InfiniteTreeList/hooks/useEnterAnimation/index.d.ts

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

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

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

package/components/InfiniteTreeList/hooks/useEnterAnimation/types.d.ts

@@ -0,0 +1,29 @@
+export type EnterAnimationState = {
+    /**
+     * Строка должна появиться с enter-анимацией
+     */
+    shouldAnimate: boolean;
+    /**
+     * Индекс каскадной задержки анимации
+     */
+    delayIndex?: number;
+};
+export type EnterAnimationResult = {
+    /**
+     * Планирует появление элементов с enter-анимацией.
+     * Порядок id задаёт каскад, `startDelayIndex` сдвигает его начало
+     */
+    schedule: (itemIds: string[], startDelayIndex?: number) => void;
+    /**
+     * Возвращает состояние анимации, не изменяя метку. Безопасно для рендера
+     */
+    read: (itemId: string) => EnterAnimationState;
+    /**
+     * Забирает метку элемента: повторный mount при скролле анимации не получит
+     */
+    claim: (itemId: string) => void;
+    /**
+     * Сбрасывает все метки
+     */
+    reset: () => void;
+};