@astral/ui 4.105.0 → 4.106.0

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

@@ -4,24 +4,38 @@ exports.useListScroll = void 0;
 const react_1 = require("react");
 const useScrollManagement_1 = require("../../../useScrollManagement");
 const constants_1 = require("../../constants");
-const utils_1 = require("../../utils");
+const hooks_1 = require("./hooks");
+const utils_1 = require("./utils");
 /**
- * Скролл-обвязка списка: props для `Virtuoso`, кнопка «наверх» и реестр хвостов
- * вложенных веток. Хвосты регистрируют сами строки, хук создаёт реестр и на
- * смене видимого диапазона проверяет, попал ли хвост в кадр
+ * Скролл-обвязка списка: props для `Virtuoso`, переход между уровнями
+ * и сборка кнопки «наверх», реестра хвостов и памяти уровней
  */
-const useListScroll = ({ scrollRef, isEndReached, onLoadMore, flatListRef, enterAnimation, }) => {
+const useListScroll = ({ scrollRef, isEndReached, onLoadMore, displayedList, enterAnimation, isRootLevel, levelKey, activeLevelKeys, }) => {
     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 listRef = (0, react_1.useRef)(null);
+    const pendingLevelRef = (0, react_1.useRef)(null);
+    const pinnedHeightRef = (0, react_1.useRef)(null);
+    const heldHeightRef = (0, react_1.useRef)(null);
+    const { tailRegistry, trackRange } = (0, hooks_1.useTailWatcher)({
+        displayedList,
+        levelKey,
+    });
+    const { updateVisibility: updateTopButtonVisibility, onTopButtonProps } = (0, hooks_1.useScrollToTopButton)({ scrollRef, virtuosoRef });
+    const { rememberLevel, forgetLevel, getLevelPosition, levelState } = (0, hooks_1.useLevelSnapshots)({ levelKey, activeLevelKeys, virtuosoRef });
+    const isRootLevelRef = (0, react_1.useRef)(isRootLevel);
+    (0, react_1.useEffect)(() => {
+        isRootLevelRef.current = isRootLevel;
+    }, [isRootLevel]);
+    const handleListLoadMore = (0, react_1.useCallback)(() => {
+        if (!isRootLevelRef.current) {
+            return;
+        }
+        onLoadMore?.();
+    }, [onLoadMore]);
     const { scrollParent, recalculateVerticalScroll, handleEndReach, isEndReachedWithScroll, } = (0, useScrollManagement_1.useScrollManagement)({
         scrollRef,
         isEndReached,
-        onLoadMore,
+        onLoadMore: handleListLoadMore,
         virtuosoId: constants_1.VIRTUOSO_CONTAINER_ID,
     });
     // Скролл виртуализации монтирует строки, которые появлением не считаются
@@ -31,33 +45,183 @@ const useListScroll = ({ scrollRef, isEndReached, onLoadMore, flatListRef, enter
         }
     }, [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]);
+        updateTopButtonVisibility(range);
+        trackRange(range);
+    }, [updateTopButtonVisibility, trackRange]);
+    const getListTop = (0, react_1.useCallback)(() => {
+        const listElement = listRef.current;
+        if (!scrollParent || !listElement) {
+            return null;
+        }
+        return Math.max((0, utils_1.getOffsetTop)(listElement, scrollParent), 0);
+    }, [scrollParent]);
+    const saveLevelSnapshot = (0, react_1.useCallback)(() => {
+        const listTop = getListTop();
+        if (!scrollParent || listTop === null) {
+            return;
+        }
+        rememberLevel(scrollParent.scrollTop - listTop);
+        // Высота уходящего уровня держит список, пока новый не доехал
+        heldHeightRef.current = listRef.current?.offsetHeight ?? null;
+    }, [scrollParent, getListTop, rememberLevel]);
+    // Заданная высота снимается, когда строки уровня доехали и держат позицию сами
+    const releaseListHeight = (0, react_1.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 = (0, react_1.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 = (0, react_1.useRef)(null);
+    const transitionTimerRef = (0, react_1.useRef)(null);
+    const stopWatchingLevelContent = (0, react_1.useCallback)(() => {
+        heightObserverRef.current?.disconnect();
+        heightObserverRef.current = null;
+    }, []);
+    // Переход открывает список и возвращает контейнеру `scroll-behavior: smooth`
+    const finishLevelTransition = (0, react_1.useCallback)(() => {
+        if (transitionTimerRef.current !== null) {
+            clearTimeout(transitionTimerRef.current);
+            transitionTimerRef.current = null;
+        }
+        listRef.current?.classList.remove(constants_1.infiniteTreeListClassnames.levelTransition);
+        scrollParent?.style.removeProperty('scroll-behavior');
+    }, [scrollParent]);
+    const settleLevelTransition = (0, react_1.useCallback)(() => {
+        applyLevelPosition();
+        releaseListHeight();
+        if (pendingLevelRef.current || pinnedHeightRef.current !== null) {
+            return;
+        }
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [
+        applyLevelPosition,
+        releaseListHeight,
+        stopWatchingLevelContent,
+        finishLevelTransition,
+    ]);
+    const forceLevelTransitionEnd = (0, react_1.useCallback)(() => {
+        applyLevelPosition();
+        releaseListHeight();
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [
+        applyLevelPosition,
+        releaseListHeight,
+        stopWatchingLevelContent,
+        finishLevelTransition,
+    ]);
+    const startLevelTransition = (0, react_1.useCallback)(() => {
+        const listElement = listRef.current;
+        finishLevelTransition();
+        listElement?.classList.add(constants_1.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, constants_1.LEVEL_TRANSITION_TIMEOUT_MS);
+    }, [finishLevelTransition, forceLevelTransitionEnd, scrollParent]);
+    const watchLevelContent = (0, react_1.useCallback)(() => {
+        if (heightObserverRef.current) {
+            return;
+        }
+        const contentElement = listRef.current?.querySelector(`#${constants_1.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]);
+    (0, react_1.useEffect)(() => () => {
+        stopWatchingLevelContent();
+        finishLevelTransition();
+    }, [stopWatchingLevelContent, finishLevelTransition]);
+    const shownLevelRef = (0, react_1.useRef)(levelKey);
+    // Позиция выставляется до отрисовки кадра: из обычного эффекта уровень успел
+    // бы показаться с чужой позиции, и переход читался бы как прокрутка
+    (0, react_1.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: constants_1.VIRTUOSO_CONTAINER_ID,
             ref: virtuosoRef,
             overscan: constants_1.OVERSCAN,
+            restoreStateFrom: levelState,
+            // Из снимка нужны только высоты строк: позицию уровня список выставляет
+            // сам. Иначе `Virtuoso` уводит скролл в начало и возвращается к
+            // сохранённому месту собственной прокруткой
+            initialTopMostItemIndex: 0,
             rangeChanged: handleRangeChanged,
             endReached: handleEndReach,
             totalListHeightChanged: recalculateVerticalScroll,
             isScrolling: handleScrollingChange,
         },
-        onTopButtonProps: {
-            buttonRef: scrollToTopButtonRef,
-            handleScrollToTop,
-            scrollRef,
-        },
+        onTopButtonProps,
     };
 };
 exports.useListScroll = useListScroll;

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

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

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOffsetTop = void 0;
+/**
+ * Смещение элемента внутри скролл-контейнера
+ */
+const getOffsetTop = (element, scroller) => element.getBoundingClientRect().top -
+    scroller.getBoundingClientRect().top +
+    scroller.scrollTop;
+exports.getOffsetTop = getOffsetTop;

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

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

package/node/components/InfiniteTreeList/hooks/useListScroll/utils/getOffsetTop/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("./getOffsetTop"), exports);

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

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

package/node/components/InfiniteTreeList/hooks/useListScroll/utils/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("./getOffsetTop"), exports);

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

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

package/node/components/InfiniteTreeList/hooks/useNodeTitleValidation/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("./useNodeTitleValidation"), exports);

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

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

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

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

package/node/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/node/components/InfiniteTreeList/hooks/useNodeTitleValidation/useNodeTitleValidation.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useNodeTitleValidation = void 0;
+const react_1 = require("react");
+/**
+ * Проверяет, что у узла, содержимое которого отображается, задан `title`
+ */
+const useNodeTitleValidation = ({ isMobile, currentNodeId, title, }) => {
+    const warnedNodeIdsRef = (0, react_1.useRef)(new Set());
+    (0, react_1.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]);
+};
+exports.useNodeTitleValidation = useNodeTitleValidation;

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

@@ -0,0 +1,5 @@
+/// <reference types="react" />
+export declare const InfiniteTreeListWrapper: import("@emotion/styled/dist/declarations/src/types").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/node/components/InfiniteTreeList/styles.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InfiniteTreeListWrapper = void 0;
+const styled_1 = require("../styled");
+const constants_1 = require("./constants");
+exports.InfiniteTreeListWrapper = styled_1.styled.div `
+  /* Убираем якорь на android устройствах */
+  /* stylelint-disable-next-line plugin/no-unsupported-browser-features */
+  overflow-anchor: none;
+
+  ${({ theme }) => theme.breakpoints.up('mobile')} {
+    &.${constants_1.infiniteTreeListClassnames.loading},
+    &.${constants_1.infiniteTreeListClassnames.error},
+    &.${constants_1.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};
+
+    &.${constants_1.infiniteTreeListClassnames.loading},
+    &.${constants_1.infiniteTreeListClassnames.error},
+    &.${constants_1.infiniteTreeListClassnames.noData} {
+      height: ${({ theme }) => `calc(100% - ${theme.spacing(4)})`};
+    }
+
+    /* Смена уровня пересоздаёт список: строки нового уровня встают на место
+       не в том же кадре, поэтому до их появления виден фон обёртки.
+       Высоту на это время держит min-height от самого списка */
+    &.${constants_1.infiniteTreeListClassnames.levelTransition} {
+      #${constants_1.VIRTUOSO_CONTAINER_ID} {
+        visibility: hidden;
+      }
+    }
+  }
+`;

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

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

package/node/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;