@cloud-ru/ds-list 1.0.0

package/dist/esm/components/Lists/types.d.ts

@@ -0,0 +1,200 @@
+import { DragEndEvent } from '@dnd-kit/core';
+import { DropdownProps } from '@cloud-ru/ds-dropdown';
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+import { FocusEvent, KeyboardEvent, ReactNode, RefObject } from 'react';
+import { EmptyStateProps } from '../../helperComponents/index.js';
+import { ScrollProps, SearchState } from '../../types.js';
+import { FlattenBaseItem, Item, ItemId, ReorderItem } from '../Items/index.js';
+import { CollapseState, PublicListContextType, SelectionState } from './contexts/index.js';
+export type EmptyState = {
+    /** Текущий пустой список — результат поиска/фильтра: показывается `noResultsState` вместо `noDataState` */
+    dataFiltered?: boolean;
+    /** Загрузка данных завершилась ошибкой: показывается `errorDataState` */
+    dataError?: boolean;
+    /** Экран при отсутствии данных */
+    noDataState?: EmptyStateProps;
+    /** Экран при отсутствии результатов поиска или фильтров */
+    noResultsState?: EmptyStateProps;
+    /** Экран при ошибке запроса */
+    errorDataState?: EmptyStateProps;
+};
+type ListPropsCommon = WithSupportProps<{
+    /** Элементы списка, закрепленные сверху */
+    pinTop?: Item[];
+    /** Элементы списка, закрепленные снизу */
+    pinBottom?: Item[];
+    /**
+     * Кастомизируемый элемент в конце списка
+     * @type ReactNode;
+     */
+    footer?: ReactNode;
+    /**
+     * Кастомизируемый элемент в начале списка — Figma `dropdownContainer.topBar`.
+     * Подходит для заголовка / справочного блока над поиском.
+     * @type ReactNode;
+     */
+    header?: ReactNode;
+    /** Показывать divider между header и body (Figma `dropdownContainer.dividerWrapper` сверху) */
+    headerDivider?: boolean;
+    /** Показывать divider между body и footer (Figma `dropdownContainer.dividerWrapper` снизу) */
+    footerDivider?: boolean;
+    /** Список ссылок на кастомные элементы, помещенные в специальную секцию внизу списка  */
+    footerActiveElementsRefs?: RefObject<HTMLElement>[];
+    /** Ссылка на управление навигацией листа с клавиатуры  */
+    keyboardNavigationRef?: RefObject<{
+        focusItem(id: ItemId): void;
+    }>;
+    /** Настройки поисковой строки */
+    search?: SearchState;
+    /** `tabIndex` корневого элемента списка (для управления порядком фокуса) */
+    tabIndex?: number;
+    /** Настройки раскрытия элементов */
+    collapse?: CollapseState;
+    /** CSS-класс */
+    className?: string;
+    /** Флаг, отвечающий за состояние загрузки списка */
+    loading?: boolean;
+    /** Обработчик события по нажатию клавиш */
+    onKeyDown?(e: KeyboardEvent<HTMLElement>): void;
+    /** Флаг, отвечающий за включение самого родительского контейнера листа в цепочку фокусирующихся элементов */
+    hasListInFocusChain?: boolean;
+    /** Флаг, отвечающий за прокручивание до выбранного элемента */
+    scrollToSelectedItem?: boolean;
+    /** CSS-класс для scroll обертки основного списка айтемов */
+    scrollContainerClassName?: string;
+    /** Ограничить максимальную высоту скролл-контейнера в зависимости от `size` */
+    limitedScrollHeight?: boolean;
+} & SelectionState & Omit<PublicListContextType, 'virtualized'> & ScrollProps & EmptyState>;
+/** Props `List` — список обычных айтемов (все виды: base / collapse / group / next-list). */
+export type ListProps = ListPropsCommon & {
+    /** Основные элементы списка */
+    items: Item[];
+    /** Включить виртуализацию элементов списка. Рекомендуется при количестве элементов от 1000. */
+    virtualized?: boolean;
+};
+/**
+ * Props `ReorderableList` — список с drag&drop-переупорядочиванием строк за ручку.
+ *
+ * Отдельный компонент, а не режим `List`: модель айтемов другая (`ReorderItem` — плоская строка
+ * либо группа с заголовком, без `collapse`/`next-list`/`group-select`), а виртуализация здесь
+ * невозможна в принципе — `@dnd-kit` и виртуализатор применяют к строке свой `transform`.
+ */
+export type ReorderableListProps = ListPropsCommon & {
+    /**
+     * Основные элементы списка: строки `SimpleItem` и/или группы с заголовком `SimpleGroupItem`
+     * (`type: 'group'` + `label` + сортируемые `items`).
+     */
+    items: ReorderItem[];
+    /**
+     * Колбек по завершению drag&drop-переупорядочивания элементов списка. Список остаётся
+     * управляемым: сам не хранит порядок, а отдаёт наружу целиком обновлённое дерево `items` —
+     * потребитель обновляет свой стейт этим значением. Переупорядочивание работает только среди
+     * «братьев» одного уровня (строки без группы либо строки внутри одной группы; перенос между
+     * группами не поддерживается).
+     */
+    onItemsReorder(items: ReorderItem[]): void;
+};
+/**
+ * @internal Props общей реализации `List`/`ReorderableList` — принимает обе модели айтемов сразу.
+ * Наружу не отдаётся: публичные `ListProps`/`ReorderableListProps` плоские, потому что union в
+ * публичном props-типе ломает `react-docgen-typescript` (`props.json` схлопывается в `alias`),
+ * вывод `Meta`/`StoryObj` и narrowing при spread'е.
+ */
+export type ListImplProps = ListPropsCommon & {
+    items: Item[] | ReorderItem[];
+    virtualized?: boolean;
+    onItemsReorder?(items: ReorderItem[]): void;
+};
+/** Собственные props дроплиста — всё, что не приходит из `List`. */
+type DroplistOwnProps = {
+    /** Ссылка на элемент-триггер для дроплиста */
+    triggerElemRef?: RefObject<HTMLElement>;
+    /**
+     * Контейнер портала (ref). Переопределяет `PortalContext` для этого дроплиста
+     * (по аналогии с `container` у Modal/Drawer). По умолчанию — из `PortalContextProvider`.
+     */
+    container?: RefObject<HTMLElement | null>;
+    /** Ссылка на элемент выпадающего списка */
+    listRef?: RefObject<HTMLElement>;
+    /**
+     * Закрывать выпадающий список после клика на базовый айтем.
+     *
+     * Работает в режимах selection: 'none' | 'single'
+     *
+     * @default false
+     */
+    closeDroplistOnItemClick?: boolean;
+    /** Триггер для дроплиста
+     * @type ReactNode | ({onKeyDown}) => ReactNode
+     *
+     * Рендер функция принимает аргументы `onKeyDown` - хендлер ввода, для поддержки управления с клавиатуры
+     */
+    children: ReactNode | ((params: {
+        onKeyDown?: (e: KeyboardEvent<HTMLElement>) => void;
+    }) => ReactNode);
+} & Pick<DropdownProps, 'trigger' | 'placement' | 'widthStrategy' | 'open' | 'onOpenChange' | 'triggerClassName' | 'closeOnPopstate'>;
+/** Props списка, которые дроплист пробрасывает в `List` (навигацией управляет он сам). */
+type DroplistListProps<T> = Omit<T, 'tabIndex' | 'onKeyDown' | 'hasListInFocusChain' | 'keyboardNavigationRef'>;
+/** Базовые props дроплиста: собственные + props обычного `List`. */
+export type BaseDroplistProps = DroplistOwnProps & DroplistListProps<ListProps>;
+/** Базовые props дроплиста с drag&drop-переупорядочиванием: собственные + props `ReorderableList`. */
+export type ReorderableBaseDroplistProps = DroplistOwnProps & DroplistListProps<ReorderableListProps>;
+/**
+ * @internal Props общей реализации дроплиста (`DesktopDroplist`/`MobileDroplist`) — принимает обе
+ * модели айтемов. Публичные `DroplistProps`/`ReorderableDroplistProps` плоские, см. `ListImplProps`.
+ */
+export type DesktopDroplistProps = DroplistOwnProps & DroplistListProps<ListImplProps>;
+/** Только mobile (`BottomSheet`)-слоты адаптивного `Droplist`. */
+type DroplistMobileSlots = {
+    /** Только mobile (`BottomSheet`): заголовок шапки. */
+    label?: string;
+    /** Только mobile (`BottomSheet`): action-кнопка справа в шапке. */
+    actionButton?: ReactNode;
+    /** Только mobile (`BottomSheet`): slot справа от заголовка. */
+    slotAfterTitle?: ReactNode;
+    /** Только mobile (`BottomSheet`): callback back-кнопки. */
+    onBackButtonClick?(): void;
+};
+/**
+ * Props адаптивного `Droplist` (дефолтный droplist): базовые props + mobile-слоты `BottomSheet`.
+ * Раскладку берёт из `AdaptiveProvider` (контекст): на `mobile` рендерит `MobileDroplist`
+ * (список size `l` в `BottomSheet`), иначе — `DesktopDroplist` (анкорный popover). Mobile-слоты
+ * применяются только на mobile.
+ */
+export type DroplistProps = BaseDroplistProps & DroplistMobileSlots;
+/**
+ * Props адаптивного `ReorderableDroplist`: props `ReorderableList` + popover/mobile-обвязка
+ * `Droplist`. Отдельный компонент по той же причине, что и `ReorderableList`.
+ */
+export type ReorderableDroplistProps = ReorderableBaseDroplistProps & DroplistMobileSlots;
+/** @internal Props общей реализации адаптивного дроплиста: реализация + mobile-слоты. */
+export type DroplistImplProps = DesktopDroplistProps & DroplistMobileSlots;
+/**
+ * @internal Props mobile-реализации (`BottomSheet`): реализация дроплиста без popover-пропов
+ * + mobile-слоты.
+ */
+export type MobileDroplistProps = Omit<DesktopDroplistProps, 'trigger' | 'placement' | 'widthStrategy' | 'triggerElemRef' | 'listRef' | 'triggerClassName'> & DroplistMobileSlots;
+export type ListPrivateProps = Omit<ListImplProps, 'pinTop' | 'pinBottom' | 'items' | 'hasListInFocusChain' | 'onItemsReorder' | 'virtualized'> & {
+    nested?: boolean;
+    active?: boolean;
+    tabIndex?: number;
+    virtualized?: boolean;
+    onFocus?(e: FocusEvent<HTMLElement>): void;
+    onBlur?(e: FocusEvent<HTMLElement>): void;
+    onKeyDown?(e: KeyboardEvent<HTMLElement>): void;
+    limitedScrollHeight?: boolean;
+    searchItem?: FlattenBaseItem;
+    pinTop?: ItemId[];
+    items: ItemId[];
+    pinBottom?: ItemId[];
+    /**
+     * @internal Обработчик завершения drag&drop-переупорядочивания (см. публичный `onItemsReorder`
+     * у `List`/`Droplist`) — вычисляется в `useListItemsModel` и оперирует исходным (не плоским)
+     * деревом `items`. Наличие принудительно включает невиртуализированный рендер и оборачивает айтемы в
+     * `DndContext`/`SortableContext`.
+     */
+    onDragEnd?(event: DragEndEvent): void;
+    /** @internal Плоский список id всех сортируемых элементов (все уровни) для `SortableContext` */
+    sortableIds?: ItemId[];
+};
+export {};

package/dist/esm/components/Lists/types.js

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

package/dist/esm/components/Lists/utils.d.ts

@@ -0,0 +1,8 @@
+import { ItemId, ReorderItem } from '../Items/index.js';
+/**
+ * Переупорядочивание reorder-дерева (`onItemsReorder`). Перестановка допускается только среди
+ * «братьев» одного уровня: сначала проверяется верхний уровень (строки без группы), затем — строки
+ * внутри каждой группы. Если `activeId` и `overId` лежат в разных контейнерах (в разных группах
+ * либо строка-vs-группа), дерево возвращается без изменений — перенос между группами не поддержан.
+ */
+export declare function reorderItems(items: ReorderItem[], activeId: ItemId, overId: ItemId): ReorderItem[];

package/dist/esm/components/Lists/utils.js

@@ -0,0 +1,28 @@
+import { arrayMove } from '@dnd-kit/sortable';
+import { isGroupItem } from '../Items/index.js';
+/**
+ * Переупорядочивание reorder-дерева (`onItemsReorder`). Перестановка допускается только среди
+ * «братьев» одного уровня: сначала проверяется верхний уровень (строки без группы), затем — строки
+ * внутри каждой группы. Если `activeId` и `overId` лежат в разных контейнерах (в разных группах
+ * либо строка-vs-группа), дерево возвращается без изменений — перенос между группами не поддержан.
+ */
+export function reorderItems(items, activeId, overId) {
+    // Верхний уровень: строки без группы и сами группы лежат здесь как «братья» — `id` обязателен у
+    // обеих сущностей, поэтому группа находится по нему наравне со строкой и переставляется целиком.
+    const topActiveIndex = items.findIndex(item => 'id' in item && item.id === activeId);
+    const topOverIndex = items.findIndex(item => 'id' in item && item.id === overId);
+    if (topActiveIndex !== -1 && topOverIndex !== -1) {
+        return arrayMove(items, topActiveIndex, topOverIndex);
+    }
+    // Иначе ищется группа, внутри которой обе строки — «братья», и перестановка идёт только там.
+    return items.map(item => {
+        if (isGroupItem(item)) {
+            const activeIndex = item.items.findIndex(child => child.id === activeId);
+            const overIndex = item.items.findIndex(child => child.id === overId);
+            if (activeIndex !== -1 && overIndex !== -1) {
+                return { ...item, items: arrayMove(item.items, activeIndex, overIndex) };
+            }
+        }
+        return item;
+    });
+}

package/dist/esm/components/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Lists/index.js';
+export * from './Items/index.js';

package/dist/esm/components/index.js

@@ -0,0 +1,2 @@
+export * from './Lists/index.js';
+export * from './Items/index.js';

package/dist/esm/constants.d.ts

@@ -0,0 +1,48 @@
+export declare const ITEM_PREFIXES: {
+    readonly default: "~main";
+    readonly pinTop: "~pinTop";
+    readonly pinBottom: "~pinBottom";
+    readonly footer: "~footer";
+    readonly search: "~search";
+    readonly dropFocus: "~dropFocus";
+};
+export declare const SIZE: {
+    readonly S: "s";
+    readonly M: "m";
+    readonly L: "l";
+};
+export declare const DEFAULT_SIZE: "m";
+export declare const MODE: {
+    readonly None: "none";
+    readonly Single: "single";
+    readonly Multiple: "multiple";
+};
+export declare const ITEM_TYPE: {
+    readonly NextList: "next-list";
+    readonly Collapse: "collapse";
+    readonly Group: "group";
+    readonly GroupSelect: "group-select";
+    readonly Simple: "simple";
+};
+export declare const TEST_IDS: {
+    readonly root: "list";
+    readonly loader: "list__loader";
+    readonly noData: "list__no-data";
+    readonly noResults: "list__no-results";
+    readonly error: "list__error";
+    readonly baseItem: "list__base-item";
+    readonly baseItemMarker: "list__base-item-marker";
+    readonly baseItemCheckbox: "list__base-item-checkbox";
+    readonly baseItemSwitch: "list__base-item-switch";
+    readonly baseItemLabel: "list__base-item-label";
+    readonly baseItemDescription: "list__base-item-description";
+    readonly searchItem: "list__search-item";
+    readonly bulkSelectButton: "list__bulk-select-button";
+    readonly pinTopGroupItem: "list__pin-top-group-item";
+    readonly pinBottomGroupItem: "list__pin-bottom-group-item";
+    readonly accordionItem: "list__accordion-item";
+    readonly groupIndicator: "list__group-indicator";
+    readonly dragHandle: "list__drag-handle";
+    readonly mobileDroplistRoot: "list__mobile-droplist-root";
+    readonly mobileDroplistTrigger: "list__mobile-droplist-trigger";
+};

package/dist/esm/constants.js

@@ -0,0 +1,48 @@
+export const ITEM_PREFIXES = {
+    default: '~main',
+    pinTop: '~pinTop',
+    pinBottom: '~pinBottom',
+    footer: '~footer',
+    search: '~search',
+    dropFocus: '~dropFocus',
+};
+export const SIZE = {
+    S: 's',
+    M: 'm',
+    L: 'l',
+};
+export const DEFAULT_SIZE = SIZE.M;
+export const MODE = {
+    None: 'none',
+    Single: 'single',
+    Multiple: 'multiple',
+};
+export const ITEM_TYPE = {
+    NextList: 'next-list',
+    Collapse: 'collapse',
+    Group: 'group',
+    GroupSelect: 'group-select',
+    Simple: 'simple',
+};
+export const TEST_IDS = {
+    root: 'list',
+    loader: 'list__loader',
+    noData: 'list__no-data',
+    noResults: 'list__no-results',
+    error: 'list__error',
+    baseItem: 'list__base-item',
+    baseItemMarker: 'list__base-item-marker',
+    baseItemCheckbox: 'list__base-item-checkbox',
+    baseItemSwitch: 'list__base-item-switch',
+    baseItemLabel: 'list__base-item-label',
+    baseItemDescription: 'list__base-item-description',
+    searchItem: 'list__search-item',
+    bulkSelectButton: 'list__bulk-select-button',
+    pinTopGroupItem: 'list__pin-top-group-item',
+    pinBottomGroupItem: 'list__pin-bottom-group-item',
+    accordionItem: 'list__accordion-item',
+    groupIndicator: 'list__group-indicator',
+    dragHandle: 'list__drag-handle',
+    mobileDroplistRoot: 'list__mobile-droplist-root',
+    mobileDroplistTrigger: 'list__mobile-droplist-trigger',
+};

package/dist/esm/helperComponents/CollapseBlockPrivate/CollapseBlockPrivate.d.ts

@@ -0,0 +1,9 @@
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+import { ReactNode } from 'react';
+export type CollapseBlockPrivateProps = WithSupportProps<{
+    children: ReactNode;
+    header: ReactNode;
+    expanded: boolean;
+    className?: string;
+}>;
+export declare function CollapseBlockPrivate({ children, expanded, className, header, ...rest }: CollapseBlockPrivateProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/helperComponents/CollapseBlockPrivate/CollapseBlockPrivate.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { extractSupportProps } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import styles from './styles.module.css';
+// Раскрытие без анимации высоты: подход из Accordion/Tree (transition по max-height)
+// не работает внутри Scroll-контейнера, поэтому контент монтируется/размонтируется напрямую.
+export function CollapseBlockPrivate({ children, expanded, className, header, ...rest }) {
+    return (_jsxs("div", { className: cn(styles.accordion, className), role: 'menuitem', "aria-haspopup": true, "aria-expanded": expanded, ...extractSupportProps(rest), children: [header, _jsx("div", { className: styles.contentWrapper, "aria-hidden": !expanded, children: _jsx("div", { className: styles.content, children: expanded && children }) })] }));
+}

package/dist/esm/helperComponents/CollapseBlockPrivate/index.d.ts

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

package/dist/esm/helperComponents/CollapseBlockPrivate/index.js

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

package/dist/esm/helperComponents/CollapseBlockPrivate/styles.module.css

@@ -0,0 +1,27 @@
+.accordion{
+  display:flex;
+  flex-direction:column;
+  box-sizing:border-box;
+  transition:gap 300ms;
+}
+.accordion::-webkit-scrollbar{
+  width:0;
+}
+.accordion[aria-expanded=false]{
+  gap:0;
+}
+
+.content{
+  position:relative;
+  display:none;
+  box-sizing:border-box;
+  width:100%;
+}
+
+.contentWrapper{
+  box-sizing:border-box;
+  width:100%;
+}
+.contentWrapper[aria-hidden=false] > .content{
+  display:block;
+}

package/dist/esm/helperComponents/DesktopDroplist/DesktopDroplist.d.ts

@@ -0,0 +1,7 @@
+import { DesktopDroplistProps } from '../../components/Lists/types.js';
+/**
+ * Desktop-поверхность `Droplist`: анкорный popover (`Dropdown`) со списком. Internal — наружу
+ * не реэкспортится; рендерится адаптивным `Droplist` на не-mobile раскладке. Так как вызывается
+ * только на desktop-раскладке, внутренний адаптивный `Dropdown` всегда рендерит popover.
+ */
+export declare function DesktopDroplist({ items: itemsProp, search, pinBottom: pinBottomProp, pinTop: pinTopProp, footerActiveElementsRefs, children, trigger, placement, widthStrategy, triggerElemRef: triggerElemRefProp, container, open: openProp, onOpenChange, collapse, triggerClassName, selection, contentRender, size, marker, closeDroplistOnItemClick, className, listRef: listRefProp, untouchableScrollbars, virtualized, closeOnPopstate, header, headerDivider, footer, footerDivider, onItemsReorder, ...props }: DesktopDroplistProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/helperComponents/DesktopDroplist/DesktopDroplist.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Dropdown } from '@cloud-ru/ds-dropdown';
+import { focusWithoutScroll, preventScrollOnVerticalArrows, useValueControl } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import mergeRefs from 'merge-refs';
+import { cloneElement, isValidElement, useCallback, useEffect, useMemo, useRef } from 'react';
+import { SearchItem } from '../../components/Items/index.js';
+import { CollapseContext, FocusListContext, NewListContextProvider, OpenListContext, SelectionProvider, } from '../../components/Lists/contexts/index.js';
+import { DEFAULT_FALLBACK_PLACEMENTS, DEFAULT_SIZE, FOCUS_DEFERRAL_TIMEOUT, } from '../../components/Lists/Droplist/constants.js';
+import { useListItemsModel, useNewKeyboardNavigation } from '../../components/Lists/hooks.js';
+import { ListPrivate } from '../../components/Lists/ListPrivate/index.js';
+import styles from '../../components/Lists/styles.module.css';
+/**
+ * Desktop-поверхность `Droplist`: анкорный popover (`Dropdown`) со списком. Internal — наружу
+ * не реэкспортится; рендерится адаптивным `Droplist` на не-mobile раскладке. Так как вызывается
+ * только на desktop-раскладке, внутренний адаптивный `Dropdown` всегда рендерит popover.
+ */
+export function DesktopDroplist({ items: itemsProp, search, pinBottom: pinBottomProp = [], pinTop: pinTopProp = [], footerActiveElementsRefs, children, trigger, placement, widthStrategy, triggerElemRef: triggerElemRefProp, container, open: openProp, onOpenChange, collapse = {}, triggerClassName, selection, contentRender, size = DEFAULT_SIZE, marker = true, closeDroplistOnItemClick = false, className, listRef: listRefProp, untouchableScrollbars = false, virtualized = false, closeOnPopstate, header, headerDivider, footer, footerDivider, onItemsReorder, ...props }) {
+    const { hasSearch, openCollapseItems, toggleOpenCollapseItem, searchItem, flattenItems, focusFlattenItems, memorizedItems, ids, expandedIds, firstItemId, onDragEnd, sortableIds, } = useListItemsModel({
+        items: itemsProp,
+        pinTop: pinTopProp,
+        pinBottom: pinBottomProp,
+        search,
+        collapse,
+        selectionMode: selection?.mode,
+        footerActiveElementsRefs,
+        onItemsReorder,
+    });
+    const [open = false, setOpen] = useValueControl({
+        value: openProp,
+        defaultValue: false,
+        onChange: onOpenChange,
+    });
+    const triggerElemRef = useRef(null);
+    const listRef = useRef(null);
+    const { handleListKeyDownFactory, resetActiveItemId, activeItemId, forceUpdateActiveItemId } = useNewKeyboardNavigation({
+        mainRef: triggerElemRefProp ?? triggerElemRef,
+        focusFlattenItems,
+        hasListInFocusChain: true,
+        firstItemId,
+    });
+    const handleListKeyDown = useCallback((e) => handleListKeyDownFactory(ids, expandedIds)(e), [handleListKeyDownFactory, ids, expandedIds]);
+    // Закрытие по Escape должно вернуть фокус на триггер (a11y). Закрытие
+    // outside-click'ом фокус не отбирает (пользователь намеренно ушёл в другое место),
+    // поэтому различаем источник: флаг ставится Escape-обработчиком на контенте дроплиста.
+    const closedByKeyboardRef = useRef(false);
+    // Возврат фокуса откладывается на следующий тик (после размонтирования портала).
+    // Храним id таймера, чтобы отменить его при размонтировании компонента.
+    const focusTriggerTimerRef = useRef();
+    useEffect(() => () => {
+        clearTimeout(focusTriggerTimerRef.current);
+    }, []);
+    const handleOpenChange = useCallback((open) => {
+        resetActiveItemId();
+        if (!open && closedByKeyboardRef.current) {
+            const triggerEl = (triggerElemRefProp ?? triggerElemRef).current;
+            focusTriggerTimerRef.current = setTimeout(() => triggerEl?.focus(), FOCUS_DEFERRAL_TIMEOUT);
+        }
+        closedByKeyboardRef.current = false;
+        setOpen(open);
+    }, [resetActiveItemId, setOpen, triggerElemRefProp]);
+    const handleContentKeyDown = useCallback((e) => {
+        if (e.key === 'Escape') {
+            closedByKeyboardRef.current = true;
+        }
+    }, []);
+    const onKeyDown = useCallback((e, cb) => {
+        // Up/Down открывают/закрывают дроплист — гасим их нативный скролл страницы. Только
+        // вертикальные: триггером может быть текстовое поле, где Left/Right двигают каретку.
+        preventScrollOnVerticalArrows(e);
+        if (e.key === 'ArrowDown') {
+            setOpen(true);
+            focusTriggerTimerRef.current = setTimeout(() => {
+                resetActiveItemId();
+                focusWithoutScroll(listRef.current);
+            }, FOCUS_DEFERRAL_TIMEOUT);
+        }
+        if (e.key === 'ArrowUp') {
+            setOpen(false);
+        }
+        cb?.(e);
+    }, [resetActiveItemId, setOpen]);
+    const isValid = useMemo(() => isValidElement(children), [children]);
+    const triggerElem = useMemo(() => {
+        if (isValidElement(children)) {
+            const props = typeof children.props === 'object' ? children.props : {};
+            return cloneElement(children, {
+                ...props,
+                onKeyDown: (e) => {
+                    onKeyDown(e, children.props?.onKeyDown);
+                },
+            });
+        }
+        if (typeof children === 'function') {
+            return children({ onKeyDown });
+        }
+        return children;
+    }, [onKeyDown, children]);
+    // search и footer вынесены из `<ul>` в слоты шапки/футера dropdown. Т.к. их события
+    // клавиатуры больше не всплывают на `<ul>`-onKeyDown, навигацию по списку им отдаём
+    // явно через `handleListKeyDown` (тот же factory). Фокус-хэндофф идёт через общие
+    // refs (searchItem.itemRef / footerActiveElementsRefs), уже зарегистрированные в `ids`.
+    const searchNode = hasSearch ? (_jsx(SearchItem, { search: search, itemRef: searchItem.itemRef, inTopBar: true, onNavKeyDown: handleListKeyDown, onFocus: () => forceUpdateActiveItemId?.(searchItem.id) })) : undefined;
+    const footerNode = footer ? (
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+    _jsx("div", { onKeyDown: handleListKeyDown, children: footer })) : undefined;
+    const collapseContextValue = useMemo(() => ({ openCollapseItems, toggleOpenCollapseItem }), [openCollapseItems, toggleOpenCollapseItem]);
+    const focusListContextValue = useMemo(() => ({ activeItemId, handleListKeyDownFactory, forceUpdateActiveItemId }), [activeItemId, handleListKeyDownFactory, forceUpdateActiveItemId]);
+    const closeDroplist = useCallback(() => {
+        setOpen(false);
+        resetActiveItemId();
+        (triggerElemRefProp ?? triggerElemRef).current?.focus();
+    }, [setOpen, resetActiveItemId, triggerElemRefProp]);
+    const openListContextValue = useMemo(() => ({ closeDroplistOnItemClick, closeDroplist }), [closeDroplistOnItemClick, closeDroplist]);
+    // virtualized-список не имеет собственной ширины: строки `position:absolute; width:100%`,
+    // контейнер `width:100%` — под `auto` вся цепочка `100%` от «ничего» схлопывается в 0.
+    // Поэтому для virtualized и дефолт (`undefined`), и явный `auto` поднимаем до `gte`
+    // (ширина ≥ триггера). Узкую ширину такой список получает не через `auto`, а явным
+    // `width` (например, `dropDownClassName` у ChipChoice — сам он не virtualized).
+    const effectiveWidthStrategy = virtualized && (widthStrategy === undefined || widthStrategy === 'auto') ? 'gte' : widthStrategy;
+    return (_jsx(NewListContextProvider, { flattenItems: flattenItems, focusFlattenItems: focusFlattenItems, contentRender: contentRender, size: size, marker: marker, firstItemId: firstItemId, virtualized: virtualized, children: _jsx(SelectionProvider, { ...selection, children: _jsx(CollapseContext.Provider, { value: collapseContextValue, children: _jsx(FocusListContext.Provider, { value: focusListContextValue, children: _jsx(OpenListContext.Provider, { value: openListContextValue, children: _jsx(Dropdown, { content: 
+                            // onKeyDown — пассивный детектор Escape для возврата фокуса на триггер
+                            // (см. handleContentKeyDown). Контейнер презентационный, не интерактивный.
+                            // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+                            _jsx("div", { className: cn(styles.wrapper, className), onKeyDown: handleContentKeyDown, children: _jsx(ListPrivate, { ...props, items: memorizedItems.items.focusCloseChildIds, pinTop: memorizedItems.pinTop.focusCloseChildIds, pinBottom: memorizedItems.pinBottom.focusCloseChildIds, virtualized: virtualized, onKeyDown: handleListKeyDown, tabIndex: 0, ref: mergeRefs(listRef, listRefProp), dataFiltered: props.dataFiltered ?? Boolean(search?.value), onFocus: e => {
+                                        e.stopPropagation();
+                                        forceUpdateActiveItemId?.(ids[0]);
+                                    }, limitedScrollHeight: true, untouchableScrollbars: untouchableScrollbars, onDragEnd: onDragEnd, sortableIds: sortableIds }) }), bodyPadding: false, title: header, 
+                            // Divider под topBar рисуется, если явно запрошен header'ом либо когда в topBar
+                            // есть поиск: строка поиска визуально отделяется от тела списка (как в PinTopGroupItem
+                            // у inline-List). @cloud-ru/ds-dropdown рисует один divider на весь topBar (headline + search).
+                            headerDivider: headerDivider || hasSearch, search: searchNode, footer: footerNode, footerDivider: footerDivider, container: container, outsideClick: true, triggerClassName: triggerClassName, fallbackPlacements: DEFAULT_FALLBACK_PLACEMENTS, trigger: trigger, placement: placement, widthStrategy: effectiveWidthStrategy, triggerRef: !triggerElemRefProp ? triggerElemRef : (isValid && triggerElemRefProp) || undefined, open: open, onOpenChange: handleOpenChange, closeOnPopstate: closeOnPopstate, 
+                            // dnd-kit (`MouseSensor`/`TouchSensor`) слушает `mouseup`/`touchend` на document
+                            // в bubble-фазе — гашение этих хендлеров на floating ломает завершение drag.
+                            stopPropagation: onItemsReorder ? { onMouseUp: false, onTouchEnd: false } : undefined, children: triggerElem }) }) }) }) }) }));
+}

package/dist/esm/helperComponents/DesktopDroplist/index.d.ts

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

package/dist/esm/helperComponents/DesktopDroplist/index.js

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

package/dist/esm/helperComponents/HiddenTabButton/HiddenTabButton.d.ts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+type HiddenTabButtonProps = {
+    listRef: RefObject<HTMLElement>;
+    tabIndex?: number;
+};
+export declare const HiddenTabButton: import("react").ForwardRefExoticComponent<HiddenTabButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/esm/helperComponents/HiddenTabButton/HiddenTabButton.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useCallback } from 'react';
+import { stopPropagation } from '../../utils.js';
+import styles from './styles.module.css';
+export const HiddenTabButton = forwardRef(({ listRef, tabIndex }, ref) => {
+    const handleFocus = useCallback((e) => {
+        if (e.relatedTarget !== listRef.current) {
+            listRef.current?.focus();
+        }
+        e.preventDefault();
+        e.stopPropagation();
+    }, [listRef]);
+    return (_jsx("button", { type: 'button', "aria-hidden": true, ref: ref, onKeyDown: stopPropagation, onFocus: handleFocus, className: styles.hiddenBtn, tabIndex: tabIndex }));
+});

package/dist/esm/helperComponents/HiddenTabButton/index.d.ts

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

package/dist/esm/helperComponents/HiddenTabButton/index.js

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

package/dist/esm/helperComponents/HiddenTabButton/styles.module.css

@@ -0,0 +1,9 @@
+.hiddenBtn{
+  position:absolute;
+  width:0;
+  height:0;
+  margin:0;
+  padding:0;
+  border:none;
+  outline:none;
+}

package/dist/esm/helperComponents/ItemContent/ItemContent.d.ts

@@ -0,0 +1,17 @@
+import { TruncateStringProps } from '@cloud-ru/ds-truncate-string';
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+type TruncateProps = {
+    label?: number;
+    description?: number;
+    variant?: TruncateStringProps['variant'];
+};
+export type ItemContentProps = WithSupportProps<{
+    label: string | number;
+    caption?: string;
+    description?: string;
+    truncate?: TruncateProps;
+    disabled?: boolean;
+    className?: string;
+}>;
+export declare function ItemContent({ truncate: truncateProp, caption, description, label, className, disabled, ...rest }: ItemContentProps): import("react/jsx-runtime").JSX.Element;
+export {};