@astral/ui 4.104.2 → 4.106.0

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

@@ -1,24 +1,38 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
 import { useScrollManagement } from '../../../useScrollManagement';
-import { infiniteTreeListClassnames, OVERSCAN, VIRTUOSO_CONTAINER_ID, } from '../../constants';
-import { createTailRegistry } from '../../utils';
+import { infiniteTreeListClassnames, LEVEL_TRANSITION_TIMEOUT_MS, OVERSCAN, VIRTUOSO_CONTAINER_ID, } from '../../constants';
+import { useLevelSnapshots, useScrollToTopButton, useTailWatcher, } from './hooks';
+import { getOffsetTop } from './utils';
 /**
- * Скролл-обвязка списка: props для `Virtuoso`, кнопка «наверх» и реестр хвостов
- * вложенных веток. Хвосты регистрируют сами строки, хук создаёт реестр и на
- * смене видимого диапазона проверяет, попал ли хвост в кадр
+ * Скролл-обвязка списка: props для `Virtuoso`, переход между уровнями
+ * и сборка кнопки «наверх», реестра хвостов и памяти уровней
  */
-export const useListScroll = ({ scrollRef, isEndReached, onLoadMore, flatListRef, enterAnimation, }) => {
+export const useListScroll = ({ scrollRef, isEndReached, onLoadMore, displayedList, enterAnimation, isRootLevel, levelKey, activeLevelKeys, }) => {
     const virtuosoRef = useRef(null);
-    const scrollToTopButtonRef = useRef(null);
-    const tailRegistryRef = useRef(null);
-    if (!tailRegistryRef.current) {
-        tailRegistryRef.current = createTailRegistry();
-    }
-    const tailRegistry = tailRegistryRef.current;
+    const listRef = useRef(null);
+    const pendingLevelRef = useRef(null);
+    const pinnedHeightRef = useRef(null);
+    const heldHeightRef = useRef(null);
+    const { tailRegistry, trackRange } = useTailWatcher({
+        displayedList,
+        levelKey,
+    });
+    const { updateVisibility: updateTopButtonVisibility, onTopButtonProps } = useScrollToTopButton({ scrollRef, virtuosoRef });
+    const { rememberLevel, forgetLevel, getLevelPosition, levelState } = useLevelSnapshots({ levelKey, activeLevelKeys, virtuosoRef });
+    const isRootLevelRef = useRef(isRootLevel);
+    useEffect(() => {
+        isRootLevelRef.current = isRootLevel;
+    }, [isRootLevel]);
+    const handleListLoadMore = useCallback(() => {
+        if (!isRootLevelRef.current) {
+            return;
+        }
+        onLoadMore?.();
+    }, [onLoadMore]);
     const { scrollParent, recalculateVerticalScroll, handleEndReach, isEndReachedWithScroll, } = useScrollManagement({
         scrollRef,
         isEndReached,
-        onLoadMore,
+        onLoadMore: handleListLoadMore,
         virtuosoId: VIRTUOSO_CONTAINER_ID,
     });
     // Скролл виртуализации монтирует строки, которые появлением не считаются
@@ -28,32 +42,182 @@ export const useListScroll = ({ scrollRef, isEndReached, onLoadMore, flatListRef
         }
     }, [enterAnimation]);
     const handleRangeChanged = useCallback((range) => {
-        scrollToTopButtonRef.current?.classList.toggle(infiniteTreeListClassnames.visibleScrollToTopButton, range.startIndex > 2);
-        tailRegistry.checkRange(range.endIndex, (itemId) => flatListRef.current.findIndex((item) => item.id === itemId));
-    }, [flatListRef, tailRegistry]);
-    const handleScrollToTop = useCallback(() => {
-        if (scrollRef.current) {
-            scrollRef.current.style.scrollBehavior = 'auto';
-        }
-        virtuosoRef.current?.scrollToIndex(0);
-    }, [scrollRef]);
+        updateTopButtonVisibility(range);
+        trackRange(range);
+    }, [updateTopButtonVisibility, trackRange]);
+    const getListTop = useCallback(() => {
+        const listElement = listRef.current;
+        if (!scrollParent || !listElement) {
+            return null;
+        }
+        return Math.max(getOffsetTop(listElement, scrollParent), 0);
+    }, [scrollParent]);
+    const saveLevelSnapshot = useCallback(() => {
+        const listTop = getListTop();
+        if (!scrollParent || listTop === null) {
+            return;
+        }
+        rememberLevel(scrollParent.scrollTop - listTop);
+        // Высота уходящего уровня держит список, пока новый не доехал
+        heldHeightRef.current = listRef.current?.offsetHeight ?? null;
+    }, [scrollParent, getListTop, rememberLevel]);
+    // Заданная высота снимается, когда строки уровня доехали и держат позицию сами
+    const releaseListHeight = useCallback(() => {
+        const listElement = listRef.current;
+        const pinnedHeight = pinnedHeightRef.current;
+        if (!scrollParent || !listElement || pinnedHeight === null) {
+            return;
+        }
+        const keptScrollTop = scrollParent.scrollTop;
+        pinnedHeightRef.current = null;
+        listElement.style.removeProperty('min-height');
+        if (scrollParent.scrollTop < keptScrollTop) {
+            pinnedHeightRef.current = pinnedHeight;
+            listElement.style.minHeight = `${pinnedHeight}px`;
+            scrollParent.scrollTop = keptScrollTop;
+        }
+    }, [scrollParent]);
+    const applyLevelPosition = useCallback(() => {
+        const pendingLevel = pendingLevelRef.current;
+        const listElement = listRef.current;
+        const listTop = getListTop();
+        if (!pendingLevel || !scrollParent || !listElement || listTop === null) {
+            return;
+        }
+        const offset = getLevelPosition(pendingLevel);
+        if (offset === undefined) {
+            pendingLevelRef.current = null;
+            scrollParent.scrollTop = Math.min(scrollParent.scrollTop, listTop);
+            return;
+        }
+        const target = Math.max(listTop + offset, 0);
+        // Строки уровня попадают в список на кадр позже, чем меняется сам уровень.
+        // Пока их нет, страница короткая, и до сохранённой позиции скролл просто
+        // не достаёт
+        if (target > scrollParent.scrollHeight - scrollParent.clientHeight) {
+            const pinnedHeight = Math.max(offset + scrollParent.clientHeight, pinnedHeightRef.current ?? 0);
+            pinnedHeightRef.current = pinnedHeight;
+            listElement.style.minHeight = `${pinnedHeight}px`;
+        }
+        scrollParent.scrollTop = target;
+        if (scrollParent.scrollTop < target) {
+            return;
+        }
+        pendingLevelRef.current = null;
+    }, [scrollParent, getListTop, getLevelPosition]);
+    const heightObserverRef = useRef(null);
+    const transitionTimerRef = useRef(null);
+    const stopWatchingLevelContent = useCallback(() => {
+        heightObserverRef.current?.disconnect();
+        heightObserverRef.current = null;
+    }, []);
+    // Переход открывает список и возвращает контейнеру `scroll-behavior: smooth`
+    const finishLevelTransition = useCallback(() => {
+        if (transitionTimerRef.current !== null) {
+            clearTimeout(transitionTimerRef.current);
+            transitionTimerRef.current = null;
+        }
+        listRef.current?.classList.remove(infiniteTreeListClassnames.levelTransition);
+        scrollParent?.style.removeProperty('scroll-behavior');
+    }, [scrollParent]);
+    const settleLevelTransition = useCallback(() => {
+        applyLevelPosition();
+        releaseListHeight();
+        if (pendingLevelRef.current || pinnedHeightRef.current !== null) {
+            return;
+        }
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [
+        applyLevelPosition,
+        releaseListHeight,
+        stopWatchingLevelContent,
+        finishLevelTransition,
+    ]);
+    const forceLevelTransitionEnd = useCallback(() => {
+        applyLevelPosition();
+        releaseListHeight();
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [
+        applyLevelPosition,
+        releaseListHeight,
+        stopWatchingLevelContent,
+        finishLevelTransition,
+    ]);
+    const startLevelTransition = useCallback(() => {
+        const listElement = listRef.current;
+        finishLevelTransition();
+        listElement?.classList.add(infiniteTreeListClassnames.levelTransition);
+        scrollParent?.style.setProperty('scroll-behavior', 'auto');
+        const heldHeight = heldHeightRef.current;
+        if (listElement && heldHeight !== null) {
+            pinnedHeightRef.current = heldHeight;
+            listElement.style.minHeight = `${heldHeight}px`;
+        }
+        transitionTimerRef.current = setTimeout(forceLevelTransitionEnd, LEVEL_TRANSITION_TIMEOUT_MS);
+    }, [finishLevelTransition, forceLevelTransitionEnd, scrollParent]);
+    const watchLevelContent = useCallback(() => {
+        if (heightObserverRef.current) {
+            return;
+        }
+        const contentElement = listRef.current?.querySelector(`#${VIRTUOSO_CONTAINER_ID}`);
+        if (!contentElement) {
+            settleLevelTransition();
+            return;
+        }
+        const observer = new ResizeObserver(([entry]) => {
+            // Первый замер приходит сразу за `observe`, когда список ещё пуст:
+            // снятый по нему переход показал бы обёртку без строк
+            if (!entry || entry.contentRect.height === 0) {
+                return;
+            }
+            settleLevelTransition();
+        });
+        observer.observe(contentElement);
+        heightObserverRef.current = observer;
+    }, [settleLevelTransition]);
+    useEffect(() => () => {
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [stopWatchingLevelContent, finishLevelTransition]);
+    const shownLevelRef = useRef(levelKey);
+    // Позиция выставляется до отрисовки кадра: из обычного эффекта уровень успел
+    // бы показаться с чужой позиции, и переход читался бы как прокрутка
+    useLayoutEffect(() => {
+        if (shownLevelRef.current === levelKey) {
+            return;
+        }
+        shownLevelRef.current = levelKey;
+        pendingLevelRef.current = levelKey;
+        // Высота, заданная прошлому переходу, к новому уровню не относится
+        pinnedHeightRef.current = null;
+        listRef.current?.style.removeProperty('min-height');
+        startLevelTransition();
+        applyLevelPosition();
+        watchLevelContent();
+    }, [levelKey, applyLevelPosition, watchLevelContent, startLevelTransition]);
     return {
         scrollParent,
+        listRef,
         tailRegistry,
         isEndReachedWithScroll,
+        saveLevelSnapshot,
+        dropLevelSnapshot: forgetLevel,
         virtuosoProps: {
             id: VIRTUOSO_CONTAINER_ID,
             ref: virtuosoRef,
             overscan: OVERSCAN,
+            restoreStateFrom: levelState,
+            // Из снимка нужны только высоты строк: позицию уровня список выставляет
+            // сам. Иначе `Virtuoso` уводит скролл в начало и возвращается к
+            // сохранённому месту собственной прокруткой
+            initialTopMostItemIndex: 0,
             rangeChanged: handleRangeChanged,
             endReached: handleEndReach,
             totalListHeightChanged: recalculateVerticalScroll,
             isScrolling: handleScrollingChange,
         },
-        onTopButtonProps: {
-            buttonRef: scrollToTopButtonRef,
-            handleScrollToTop,
-            scrollRef,
-        },
+        onTopButtonProps,
     };
 };

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

@@ -0,0 +1,4 @@
+/**
+ * Смещение элемента внутри скролл-контейнера
+ */
+export declare const getOffsetTop: (element: HTMLElement, scroller: HTMLElement) => number;

package/components/InfiniteTreeList/hooks/useListScroll/utils/getOffsetTop/getOffsetTop.js

@@ -0,0 +1,6 @@
+/**
+ * Смещение элемента внутри скролл-контейнера
+ */
+export const getOffsetTop = (element, scroller) => element.getBoundingClientRect().top -
+    scroller.getBoundingClientRect().top +
+    scroller.scrollTop;

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+export type UseNodeTitleValidationParams = {
+    /**
+     * Флаг мобильного отображения
+     */
+    isMobile: boolean;
+    /**
+     * Id узла, чей уровень отображается
+     */
+    currentNodeId?: string;
+    /**
+     * Заголовок отображаемого узла из его данных
+     */
+    title?: string;
+};

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

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

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

@@ -0,0 +1,5 @@
+import type { UseNodeTitleValidationParams } from './types';
+/**
+ * Проверяет, что у узла, содержимое которого отображается, задан `title`
+ */
+export declare const useNodeTitleValidation: ({ isMobile, currentNodeId, title, }: UseNodeTitleValidationParams) => void;

package/components/InfiniteTreeList/hooks/useNodeTitleValidation/useNodeTitleValidation.js

@@ -0,0 +1,18 @@
+import { useEffect, useRef } from 'react';
+/**
+ * Проверяет, что у узла, содержимое которого отображается, задан `title`
+ */
+export const useNodeTitleValidation = ({ isMobile, currentNodeId, title, }) => {
+    const warnedNodeIdsRef = useRef(new Set());
+    useEffect(() => {
+        if (!isMobile || !currentNodeId) {
+            return;
+        }
+        if (title || warnedNodeIdsRef.current.has(currentNodeId)) {
+            return;
+        }
+        warnedNodeIdsRef.current.add(currentNodeId);
+        // biome-ignore lint/suspicious/noConsole: Предупреждение для интеграторов
+        console.warn(`InfiniteTreeList: у узла "${currentNodeId}" не задан параметр title`);
+    }, [isMobile, currentNodeId, title]);
+};

package/components/InfiniteTreeList/styles.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="react" />
+export declare const InfiniteTreeListWrapper: 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/styles.js

@@ -0,0 +1,41 @@
+import { styled } from '../styled';
+import { infiniteTreeListClassnames, VIRTUOSO_CONTAINER_ID } from './constants';
+export const InfiniteTreeListWrapper = styled.div `
+  /* Убираем якорь на android устройствах */
+  /* stylelint-disable-next-line plugin/no-unsupported-browser-features */
+  overflow-anchor: none;
+
+  ${({ theme }) => theme.breakpoints.up('mobile')} {
+    &.${infiniteTreeListClassnames.loading},
+    &.${infiniteTreeListClassnames.error},
+    &.${infiniteTreeListClassnames.noData} {
+      height: 100%;
+    }
+  }
+
+  ${({ theme }) => theme.breakpoints.down('mobile')} {
+    overflow: hidden;
+
+    height: auto;
+    margin: ${({ theme }) => theme.spacing(0, 4, 4)};
+
+    background-color: ${({ theme }) => theme.palette.background.default};
+    border: 1px solid ${({ theme }) => theme.palette.components.border.default};
+    border-radius: ${({ theme }) => theme.shape.medium};
+
+    &.${infiniteTreeListClassnames.loading},
+    &.${infiniteTreeListClassnames.error},
+    &.${infiniteTreeListClassnames.noData} {
+      height: ${({ theme }) => `calc(100% - ${theme.spacing(4)})`};
+    }
+
+    /* Смена уровня пересоздаёт список: строки нового уровня встают на место
+       не в том же кадре, поэтому до их появления виден фон обёртки.
+       Высоту на это время держит min-height от самого списка */
+    &.${infiniteTreeListClassnames.levelTransition} {
+      #${VIRTUOSO_CONTAINER_ID} {
+        visibility: hidden;
+      }
+    }
+  }
+`;

package/components/InfiniteTreeList/types.d.ts

@@ -11,6 +11,10 @@ export type InfiniteTreeListDataBase = {
      * Статическое дерево описывается полем `children` и флага не требует
      */
     hasChildren?: boolean;
+    /**
+     * Заголовок узла в шапке уровня на мобильной ширине.
+     */
+    title?: string;
     /**
      * Дополнительные поля
      */

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

@@ -1,26 +1,35 @@
 /// <reference types="react" />
 import { type ContentStateProps } from '../../ContentState';
+import type { LevelHeaderProps } from '../LevelHeader';
 import type { ListFooterContext } from '../ListFooter';
-import type { InfiniteTreeListData, InfiniteTreeListProps } from '../types';
+import type { FlattenTree, InfiniteTreeListData, InfiniteTreeListProps } from '../types';
 type UseLogicParams<TData extends InfiniteTreeListData<TData>> = InfiniteTreeListProps<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;
+    displayedList: FlattenTree<TData>[];
+    levelKey: string;
+    lastRowId: string | undefined;
+    levelHeaderProps: LevelHeaderProps | undefined;
+    onToggle: (item: 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>[];
+    parentItems: FlattenTree<TData>[];
     acquireParentSlot: (itemId: string) => HTMLDivElement | null;
     contentStateProps: Omit<ContentStateProps, "children">;
+    isNoData: boolean;
+    state: "error" | "loading" | "noData" | undefined;
     scrollParent: HTMLElement | null;
+    listRef: import("react").RefObject<HTMLDivElement | null>;
     virtuosoProps: {
         id: string;
         ref: import("react").RefObject<import("react-virtuoso").VirtuosoHandle | null>;
         overscan: number;
+        restoreStateFrom: import("react-virtuoso").StateSnapshot | undefined;
+        initialTopMostItemIndex: number;
         rangeChanged: (range: import("react-virtuoso").ListRange) => void;
         endReached: () => void;
         totalListHeightChanged: () => void;
@@ -39,7 +48,6 @@ export declare const useLogic: <TData extends InfiniteTreeListData<TData>>({ ini
     renderParent: (item: TData & {
         meta: import("../types").InfiniteTreeItemMeta;
     }) => import("react").ReactNode;
-    items: TData[];
     onRetry: () => void;
     noDataImgSrc: string | undefined;
     enterAnimation: import("../hooks").EnterAnimationResult;