@cloud-ru/ds-list 1.0.0

package/src/components/Lists/index.ts

@@ -0,0 +1,5 @@
+export * from './Droplist';
+export * from './List';
+export * from './ListPrivate';
+export * from './types';
+export * from './contexts';

package/src/components/Lists/styles.module.scss

@@ -0,0 +1,95 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+
+.listContainer {
+  display: flex;
+  flex-direction: column;
+
+  height: 100%;
+  margin: 0;
+  padding: 0;
+
+  &:focus-visible {
+    border: none;
+    outline: none;
+
+    &[data-active] {
+      outline: base.$sn-theme-color-available-complementary solid base.$sn-primitive-strokeWeight-strokeSemiBold;
+      outline-offset: calc(0px - base.$sn-primitive-strokeWeight-strokeSemiBold);
+
+      * {
+        cursor: inherit;
+      }
+    }
+  }
+
+  li,
+  ul {
+    list-style-type: none;
+  }
+
+  // Сброс нативных стилей ссылки для полиморфных item'ов (itemWrapRender → <a>):
+  // строка-ссылка наследует вид пункта списка, без link-цвета и подчёркивания.
+  // text-decoration сбрасываем на самом <a> — потомок не может убрать подчёркивание предка.
+  a {
+    color: inherit;
+    text-decoration: none;
+
+    &:hover,
+    &:focus,
+    &:active,
+    &:visited {
+      color: inherit;
+      text-decoration: none;
+    }
+  }
+}
+
+.wrapper {
+  position: relative;
+
+  overflow: hidden;
+  display: block;
+
+  box-sizing: border-box;
+  height: 100%;
+
+  &:has(.listContainer:focus-visible) {
+    outline: base.$sn-theme-color-available-complementary solid base.$sn-primitive-strokeWeight-strokeSemiBold;
+    outline-offset: calc(0px - base.$sn-primitive-strokeWeight-strokeSemiBold);
+  }
+
+  li,
+  ul {
+    list-style-type: none;
+  }
+}
+
+// scrollContainer heights: исходно 256/320/384px (kратные 8 * 32/40/48)
+// Специфичность выше, чем у `.scroll { height: 100% }` из @cloud-ru/ds-scroll — иначе max-height
+// не срабатывает и дроплист растягивается на всю высоту контента.
+.scrollContainerS,
+.scrollContainerM,
+.scrollContainerL {
+  &:global(.osThemeSnack) {
+    height: auto;
+    min-height: 0;
+  }
+}
+
+.scrollContainerS {
+  &:global(.osThemeSnack) {
+    max-height: calc(base.$sn-primitive-dimension-8 * 32); // 256px
+  }
+}
+
+.scrollContainerM {
+  &:global(.osThemeSnack) {
+    max-height: calc(base.$sn-primitive-dimension-8 * 40); // 320px
+  }
+}
+
+.scrollContainerL {
+  &:global(.osThemeSnack) {
+    max-height: calc(base.$sn-primitive-dimension-8 * 48); // 384px
+  }
+}

package/src/components/Lists/types.ts

@@ -0,0 +1,231 @@
+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';
+import { ScrollProps, SearchState } from '../../types';
+import { FlattenBaseItem, Item, ItemId, ReorderItem } from '../Items';
+import { CollapseState, PublicListContextType, SelectionState } from './contexts';
+
+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[];
+};

package/src/components/Lists/utils.ts

@@ -0,0 +1,32 @@
+import { arrayMove } from '@dnd-kit/sortable';
+
+import { isGroupItem, ItemId, ReorderItem, SimpleGroupItem } from '../Items';
+
+/**
+ * Переупорядочивание reorder-дерева (`onItemsReorder`). Перестановка допускается только среди
+ * «братьев» одного уровня: сначала проверяется верхний уровень (строки без группы), затем — строки
+ * внутри каждой группы. Если `activeId` и `overId` лежат в разных контейнерах (в разных группах
+ * либо строка-vs-группа), дерево возвращается без изменений — перенос между группами не поддержан.
+ */
+export function reorderItems(items: ReorderItem[], activeId: ItemId, overId: ItemId): ReorderItem[] {
+  // Верхний уровень: строки без группы и сами группы лежат здесь как «братья» — `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<SimpleGroupItem>(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/src/components/index.ts

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

package/src/constants.ts

@@ -0,0 +1,53 @@
+export const ITEM_PREFIXES = {
+  default: '~main',
+  pinTop: '~pinTop',
+  pinBottom: '~pinBottom',
+  footer: '~footer',
+  search: '~search',
+  dropFocus: '~dropFocus',
+} as const;
+
+export const SIZE = {
+  S: 's',
+  M: 'm',
+  L: 'l',
+} as const;
+
+export const DEFAULT_SIZE = SIZE.M;
+
+export const MODE = {
+  None: 'none',
+  Single: 'single',
+  Multiple: 'multiple',
+} as const;
+
+export const ITEM_TYPE = {
+  NextList: 'next-list',
+  Collapse: 'collapse',
+  Group: 'group',
+  GroupSelect: 'group-select',
+  Simple: 'simple',
+} as const;
+
+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',
+} as const;

package/src/helperComponents/CollapseBlockPrivate/CollapseBlockPrivate.tsx

@@ -0,0 +1,32 @@
+import { extractSupportProps, WithSupportProps } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { ReactNode } from 'react';
+
+import styles from './styles.module.scss';
+
+export type CollapseBlockPrivateProps = WithSupportProps<{
+  children: ReactNode;
+  header: ReactNode;
+  expanded: boolean;
+  className?: string;
+}>;
+
+// Раскрытие без анимации высоты: подход из Accordion/Tree (transition по max-height)
+// не работает внутри Scroll-контейнера, поэтому контент монтируется/размонтируется напрямую.
+export function CollapseBlockPrivate({ children, expanded, className, header, ...rest }: CollapseBlockPrivateProps) {
+  return (
+    <div
+      className={cn(styles.accordion, className)}
+      role='menuitem'
+      aria-haspopup
+      aria-expanded={expanded}
+      {...extractSupportProps(rest)}
+    >
+      {header}
+
+      <div className={styles.contentWrapper} aria-hidden={!expanded}>
+        <div className={styles.content}>{expanded && children}</div>
+      </div>
+    </div>
+  );
+}

package/src/helperComponents/CollapseBlockPrivate/index.ts

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

package/src/helperComponents/CollapseBlockPrivate/styles.module.scss

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