@astral/ui 4.105.0 → 4.106.0

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

@@ -1,5 +1,5 @@
 // cspell:ignore виртуализирует
-import { useContext, useEffect, useMemo, useRef, } from 'react';
+import { useContext, useEffect, useRef } from 'react';
 import { InfiniteTreeListContext } from '../../InfiniteTreeListContext';
 /**
  * Логика строки виртуализации: регистрирует хвост ветки в реестре, один раз
@@ -14,8 +14,7 @@ import { InfiniteTreeListContext } from '../../InfiniteTreeListContext';
  * этого нет
  */
 export const useLogic = ({ item, context, ...itemProps }) => {
-    const { renderItem, onToggle, nodePaginationMap, onLoadMore, enterAnimation, tailRegistry, } = useContext(InfiniteTreeListContext);
-    const memoizedItemProps = useMemo(() => itemProps, [itemProps.style]);
+    const { renderItem, onToggle, nodePaginationMap, onLoadMore, enterAnimation, tailRegistry, lastRowId, } = useContext(InfiniteTreeListContext);
     const { parentId, siblingIndex, level } = item.meta;
     const parentPagination = parentId ? nodePaginationMap[parentId] : undefined;
     const isLastChild = parentPagination?.lastChildId === item.id;
@@ -48,6 +47,7 @@ export const useLogic = ({ item, context, ...itemProps }) => {
         };
     }, [shouldRegister, parentId, item.id, tailRegistry, onLoadMore]);
     const isSpinner = item.placeholderKind === 'spinner';
+    const isLastRow = item.id === lastRowId;
     // Уровень вложенности и индекс каскада — динамические значения, поэтому
     // передаются в стили через css vars, а не через styled props
     const cssVars = {
@@ -58,9 +58,10 @@ export const useLogic = ({ item, context, ...itemProps }) => {
         item,
         renderItem,
         onToggle,
-        memoizedItemProps,
+        itemProps,
         cssVars,
         isSpinner,
         hasAddAnimation: !isSpinner && shouldAnimate,
+        isLastRow,
     };
 };

package/components/InfiniteTreeList/constants.d.ts

@@ -6,13 +6,34 @@ export declare const OVERSCAN = 30;
  * data, поэтому `useLayoutEffect` снимает метку слишком рано
  */
 export declare const ENTER_ANIMATION_MOUNT_WINDOW_MS = 100;
+/**
+ * Предел, после которого переход между уровнями открывает список принудительно.
+ */
+export declare const LEVEL_TRANSITION_TIMEOUT_MS = 200;
 export declare const CHILDREN_SKELETON_COUNT = 3;
 export declare const CHILDREN_NO_DATA_MSG = "\u041D\u0435\u0442 \u0434\u0430\u043D\u043D\u044B\u0445";
+/**
+ * Ключ корневого уровня в снимках позиции скролла: у корня нет id узла
+ */
+export declare const ROOT_LEVEL_KEY = "root";
+/**
+ * Префикс ключа уровня узла: отделяет id узлов от ключа корневого уровня
+ */
+export declare const NODE_LEVEL_KEY_PREFIX = "node:";
 export declare const infiniteTreeListClassnames: {
+    root: string;
+    loading: string;
+    noData: string;
+    error: string;
+    levelHeader: string;
+    levelHeaderWithBackButton: string;
+    levelHeaderBackButton: string;
+    levelTransition: string;
     row: string;
     rowAddAnimation: string;
     rowRemoveAnimation: string;
     rowSpinner: string;
+    rowLast: string;
     scrollToTopButton: string;
     visibleScrollToTopButton: string;
 };

package/components/InfiniteTreeList/constants.js

@@ -7,13 +7,34 @@ export const OVERSCAN = 30;
  * data, поэтому `useLayoutEffect` снимает метку слишком рано
  */
 export const ENTER_ANIMATION_MOUNT_WINDOW_MS = 100;
+/**
+ * Предел, после которого переход между уровнями открывает список принудительно.
+ */
+export const LEVEL_TRANSITION_TIMEOUT_MS = 200;
 export const CHILDREN_SKELETON_COUNT = 3;
 export const CHILDREN_NO_DATA_MSG = 'Нет данных';
+/**
+ * Ключ корневого уровня в снимках позиции скролла: у корня нет id узла
+ */
+export const ROOT_LEVEL_KEY = 'root';
+/**
+ * Префикс ключа уровня узла: отделяет id узлов от ключа корневого уровня
+ */
+export const NODE_LEVEL_KEY_PREFIX = 'node:';
 export const infiniteTreeListClassnames = {
+    root: createUIKitClassname('infinite-tree-list'),
+    loading: createUIKitClassname('infinite-tree-list_loading'),
+    noData: createUIKitClassname('infinite-tree-list_no-data'),
+    error: createUIKitClassname('infinite-tree-list_error'),
+    levelHeader: createUIKitClassname('infinite-tree-list__level-header'),
+    levelHeaderWithBackButton: createUIKitClassname('infinite-tree-list__level-header_with-back-button'),
+    levelHeaderBackButton: createUIKitClassname('infinite-tree-list__level-header-back-button'),
+    levelTransition: createUIKitClassname('infinite-tree-list_level-transition'),
     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'),
+    rowLast: createUIKitClassname('infinite-tree-list__row_last'),
     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

@@ -2,4 +2,6 @@ export * from './useChildrenState';
 export * from './useEnterAnimation';
 export * from './useExpandNotifier';
 export * from './useFlatTree';
+export * from './useLevelNavigation';
 export * from './useListScroll';
+export * from './useNodeTitleValidation';

package/components/InfiniteTreeList/hooks/index.js

@@ -2,4 +2,6 @@ export * from './useChildrenState';
 export * from './useEnterAnimation';
 export * from './useExpandNotifier';
 export * from './useFlatTree';
+export * from './useLevelNavigation';
 export * from './useListScroll';
+export * from './useNodeTitleValidation';

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

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

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

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

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

@@ -0,0 +1,15 @@
+import type { InfiniteTreeListData } from '../../types';
+export type UseLevelNavigationParams<TData extends InfiniteTreeListData<TData>> = {
+    /**
+     * Список элементов дерева: из него выводится базовый уровень
+     */
+    items: TData[];
+    /**
+     * Флаг мобильного отображения
+     */
+    isMobile: boolean;
+    /**
+     * Функция проверки узла в списке
+     */
+    checkNodeExists: (nodeId: string) => boolean;
+};

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

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

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

@@ -0,0 +1,15 @@
+import type { InfiniteTreeListData } from '../../types';
+import type { UseLevelNavigationParams } from './types';
+/**
+ * Уровень, который список отображает на мобильной ширине: id текущего узла
+ * и стек пройденных узлов.
+ */
+export declare const useLevelNavigation: <TData extends InfiniteTreeListData<TData>>({ items, isMobile, checkNodeExists, }: UseLevelNavigationParams<TData>) => {
+    currentNodeId: string;
+    baseNodeId: string | undefined;
+    activeLevelKeys: string[];
+    hasUpperLevel: boolean;
+    isRootLevel: boolean;
+    enterNode: (itemId: string) => void;
+    leaveNode: () => void;
+};

package/components/InfiniteTreeList/hooks/useLevelNavigation/useLevelNavigation.js

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { checkHasNested, getLevelKey } from '../../utils';
+/**
+ * Уровень, который список отображает на мобильной ширине: id текущего узла
+ * и стек пройденных узлов.
+ */
+export const useLevelNavigation = ({ items, isMobile, checkNodeExists, }) => {
+    const [enteredIds, setEnteredIds] = useState([]);
+    const baseNodeId = useMemo(() => {
+        if (items.length !== 1) {
+            return undefined;
+        }
+        const [rootItem] = items;
+        return checkHasNested(rootItem) ? rootItem.id : undefined;
+    }, [items]);
+    // Смена ширины в обе стороны возвращает список на базовый уровень
+    useEffect(() => {
+        setEnteredIds([]);
+    }, [isMobile]);
+    // Узел мог уйти из данных: показывать его уровень и всё, что ниже, нечем
+    useEffect(() => {
+        const lostIndex = enteredIds.findIndex((itemId) => !checkNodeExists(itemId));
+        if (lostIndex === -1) {
+            return;
+        }
+        setEnteredIds(enteredIds.slice(0, lostIndex));
+    }, [enteredIds, checkNodeExists]);
+    const enterNode = useCallback((itemId) => {
+        setEnteredIds((prev) => [...prev, itemId]);
+    }, []);
+    const leaveNode = useCallback(() => {
+        setEnteredIds((prev) => prev.slice(0, -1));
+    }, []);
+    // Уровни, до которых доберётся возврат
+    const activeLevelKeys = useMemo(() => [
+        getLevelKey(isMobile ? baseNodeId : undefined),
+        ...enteredIds.map((itemId) => getLevelKey(itemId)),
+    ], [isMobile, baseNodeId, enteredIds]);
+    return {
+        currentNodeId: enteredIds[enteredIds.length - 1] ?? baseNodeId,
+        baseNodeId,
+        activeLevelKeys,
+        hasUpperLevel: enteredIds.length > 0,
+        isRootLevel: !isMobile || (enteredIds.length === 0 && baseNodeId === undefined),
+        enterNode,
+        leaveNode,
+    };
+};

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

@@ -0,0 +1,3 @@
+export * from './useLevelSnapshots';
+export * from './useScrollToTopButton';
+export * from './useTailWatcher';

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

@@ -0,0 +1,3 @@
+export * from './useLevelSnapshots';
+export * from './useScrollToTopButton';
+export * from './useTailWatcher';

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

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

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

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

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

@@ -0,0 +1,16 @@
+import type { RefObject } from 'react';
+import type { VirtuosoHandle } from 'react-virtuoso';
+export type UseLevelSnapshotsParams = {
+    /**
+     * Ключ отображаемого уровня
+     */
+    levelKey: string;
+    /**
+     * Ключи уровней, до которых доберётся возврат: снимки остальных не нужны
+     */
+    activeLevelKeys: string[];
+    /**
+     * Ref на список: с него снимаются измеренные высоты строк
+     */
+    virtuosoRef: RefObject<VirtuosoHandle | null>;
+};

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

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

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

@@ -0,0 +1,12 @@
+import type { StateSnapshot } from 'react-virtuoso';
+import type { UseLevelSnapshotsParams } from './types';
+/**
+ * Память уровней: куда был прокручен уровень и какими он намерил свои строки.
+ * Снимки живут, пока до уровня может добраться возврат
+ */
+export declare const useLevelSnapshots: ({ levelKey, activeLevelKeys, virtuosoRef, }: UseLevelSnapshotsParams) => {
+    rememberLevel: (offset: number) => void;
+    forgetLevel: (targetLevelKey: string) => void;
+    getLevelPosition: (targetLevelKey: string) => number | undefined;
+    levelState: StateSnapshot | undefined;
+};

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

@@ -0,0 +1,42 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * Память уровней: куда был прокручен уровень и какими он намерил свои строки.
+ * Снимки живут, пока до уровня может добраться возврат
+ */
+export const useLevelSnapshots = ({ levelKey, activeLevelKeys, virtuosoRef, }) => {
+    // Позиция уровня запоминается смещением скролла внутри списка
+    const levelPositionsRef = useRef(new Map());
+    // Кеш измеренных высот у `Virtuoso` привязан к индексу строки, а не к её id,
+    // поэтому уровни затирают замеры друг друга. Снимок уровня возвращает его
+    // собственные высоты: иначе после возврата список ниже настоящего, и каждая
+    // строка, домеренная при прокрутке вверх, толкает позицию обратно вниз
+    const levelStatesRef = useRef(new Map());
+    const rememberLevel = useCallback((offset) => {
+        levelPositionsRef.current.set(levelKey, offset);
+        virtuosoRef.current?.getState((state) => {
+            levelStatesRef.current.set(levelKey, state);
+        });
+    }, [levelKey, virtuosoRef]);
+    const forgetLevel = useCallback((targetLevelKey) => {
+        levelPositionsRef.current.delete(targetLevelKey);
+        levelStatesRef.current.delete(targetLevelKey);
+    }, []);
+    const getLevelPosition = useCallback((targetLevelKey) => levelPositionsRef.current.get(targetLevelKey), []);
+    // Уровни вне текущего пути возврату недоступны, и их снимки только копятся
+    useEffect(() => {
+        const keptKeys = new Set(activeLevelKeys);
+        levelPositionsRef.current.forEach((_, key) => {
+            if (keptKeys.has(key)) {
+                return;
+            }
+            levelPositionsRef.current.delete(key);
+            levelStatesRef.current.delete(key);
+        });
+    }, [activeLevelKeys]);
+    return {
+        rememberLevel,
+        forgetLevel,
+        getLevelPosition,
+        levelState: levelStatesRef.current.get(levelKey),
+    };
+};

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

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

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

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

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

@@ -0,0 +1,12 @@
+import type { RefObject } from 'react';
+import type { VirtuosoHandle } from 'react-virtuoso';
+export type UseScrollToTopButtonParams = {
+    /**
+     * Ref на контейнер, в котором должен быть скролл
+     */
+    scrollRef: RefObject<HTMLElement | null>;
+    /**
+     * Ref на список: кнопка возвращает его к первой строке
+     */
+    virtuosoRef: RefObject<VirtuosoHandle | null>;
+};

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

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

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

@@ -0,0 +1,15 @@
+/// <reference types="react" />
+import type { ListRange } from 'react-virtuoso';
+import type { UseScrollToTopButtonParams } from './types';
+/**
+ * Кнопка «наверх»: показывается, когда список ушёл от начала, и возвращает
+ * его к первой строке
+ */
+export declare const useScrollToTopButton: ({ scrollRef, virtuosoRef, }: UseScrollToTopButtonParams) => {
+    updateVisibility: (range: ListRange) => void;
+    onTopButtonProps: {
+        buttonRef: import("react").RefObject<HTMLButtonElement | null>;
+        handleScrollToTop: () => void;
+        scrollRef: import("react").RefObject<HTMLElement | null>;
+    };
+};

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

@@ -0,0 +1,27 @@
+import { useCallback, useRef } from 'react';
+import { infiniteTreeListClassnames } from '../../../../constants';
+/**
+ * Кнопка «наверх»: показывается, когда список ушёл от начала, и возвращает
+ * его к первой строке
+ */
+export const useScrollToTopButton = ({ scrollRef, virtuosoRef, }) => {
+    const buttonRef = useRef(null);
+    // Класс переключается мимо рендера: кнопка меняется на каждом кадре скролла
+    const updateVisibility = useCallback((range) => {
+        buttonRef.current?.classList.toggle(infiniteTreeListClassnames.visibleScrollToTopButton, range.startIndex > 2);
+    }, []);
+    const handleScrollToTop = useCallback(() => {
+        if (scrollRef.current) {
+            scrollRef.current.style.scrollBehavior = 'auto';
+        }
+        virtuosoRef.current?.scrollToIndex(0);
+    }, [scrollRef, virtuosoRef]);
+    return {
+        updateVisibility,
+        onTopButtonProps: {
+            buttonRef,
+            handleScrollToTop,
+            scrollRef,
+        },
+    };
+};

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

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

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

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

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

@@ -0,0 +1,11 @@
+import type { FlattenTree, InfiniteTreeListData } from '../../../../types';
+export type UseTailWatcherParams<TData extends InfiniteTreeListData<TData>> = {
+    /**
+     * Строки, отданные `Virtuoso`
+     */
+    displayedList: FlattenTree<TData>[];
+    /**
+     * Ключ отображаемого уровня
+     */
+    levelKey: string;
+};

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

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

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

@@ -0,0 +1,12 @@
+import type { ListRange } from 'react-virtuoso';
+import type { InfiniteTreeListData } from '../../../../types';
+import { type TailRegistry } from '../../../../utils';
+import type { UseTailWatcherParams } from './types';
+/**
+ * Хвосты вложенных веток: строки регистрируют себя сами, хук создаёт реестр
+ * и на смене видимого диапазона проверяет, попал ли хвост в кадр
+ */
+export declare const useTailWatcher: <TData extends InfiniteTreeListData<TData>>({ displayedList, levelKey, }: UseTailWatcherParams<TData>) => {
+    tailRegistry: TailRegistry;
+    trackRange: (range: ListRange) => void;
+};

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

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { createTailRegistry } from '../../../../utils';
+/**
+ * Хвосты вложенных веток: строки регистрируют себя сами, хук создаёт реестр
+ * и на смене видимого диапазона проверяет, попал ли хвост в кадр
+ */
+export const useTailWatcher = ({ displayedList, levelKey, }) => {
+    const tailRegistryRef = useRef(null);
+    if (!tailRegistryRef.current) {
+        tailRegistryRef.current = createTailRegistry();
+    }
+    const tailRegistry = tailRegistryRef.current;
+    const displayedListRef = useRef(displayedList);
+    const lastRangeRef = useRef(null);
+    const checkTails = useCallback(() => {
+        const range = lastRangeRef.current;
+        if (!range) {
+            return;
+        }
+        tailRegistry.checkRange(range.endIndex, (itemId) => displayedListRef.current.findIndex((item) => item.id === itemId));
+    }, [tailRegistry]);
+    // Диапазон прежнего уровня к новому набору строк не относится
+    useEffect(() => {
+        lastRangeRef.current = null;
+        tailRegistry.forgetRange();
+    }, [levelKey, tailRegistry]);
+    useEffect(() => {
+        displayedListRef.current = displayedList;
+        checkTails();
+    }, [displayedList, checkTails]);
+    const trackRange = useCallback((range) => {
+        lastRangeRef.current = range;
+        checkTails();
+    }, [checkTails]);
+    return {
+        tailRegistry,
+        trackRange,
+    };
+};

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

@@ -15,11 +15,23 @@ export type UseListScrollParams<TData extends InfiniteTreeListData<TData>> = {
      */
     onLoadMore?: () => void;
     /**
-     * Плоский список: реестр хвостов ищет в нём позицию строки
+     * Строки, отданные `Virtuoso`
      */
-    flatListRef: RefObject<FlattenTree<TData>[]>;
+    displayedList: FlattenTree<TData>[];
     /**
      * Контроллер enter-анимации: скролл снимает метки со строк
      */
     enterAnimation: EnterAnimationResult;
+    /**
+     * Флаг корневого уровня
+     */
+    isRootLevel: boolean;
+    /**
+     * Ключ отображаемого уровня
+     */
+    levelKey: string;
+    /**
+     * Ключи активных узлов
+     */
+    activeLevelKeys: string[];
 };

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

@@ -1,21 +1,24 @@
 /// <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`, кнопка «наверх» и реестр хвостов
- * вложенных веток. Хвосты регистрируют сами строки, хук создаёт реестр и на
- * смене видимого диапазона проверяет, попал ли хвост в кадр
+ * Скролл-обвязка списка: props для `Virtuoso`, переход между уровнями
+ * и сборка кнопки «наверх», реестра хвостов и памяти уровней
  */
-export declare const useListScroll: <TData extends InfiniteTreeListData<TData>>({ scrollRef, isEndReached, onLoadMore, flatListRef, enterAnimation, }: UseListScrollParams<TData>) => {
+export declare const useListScroll: <TData extends InfiniteTreeListData<TData>>({ scrollRef, isEndReached, onLoadMore, displayedList, enterAnimation, isRootLevel, levelKey, activeLevelKeys, }: UseListScrollParams<TData>) => {
     scrollParent: HTMLElement | null;
-    tailRegistry: TailRegistry;
+    listRef: import("react").RefObject<HTMLDivElement | null>;
+    tailRegistry: import("../../utils").TailRegistry;
     isEndReachedWithScroll: boolean | undefined;
+    saveLevelSnapshot: () => void;
+    dropLevelSnapshot: (targetLevelKey: string) => void;
     virtuosoProps: {
         id: string;
         ref: import("react").RefObject<VirtuosoHandle | null>;
         overscan: number;
+        restoreStateFrom: import("react-virtuoso").StateSnapshot | undefined;
+        initialTopMostItemIndex: number;
         rangeChanged: (range: ListRange) => void;
         endReached: () => void;
         totalListHeightChanged: () => void;