llms.txt

List

Пакет @cloud-ru/ds-list собирает списочный UI дизайн-системы: плоские и вложенные списки, списки с выбором (single / multiple), группы с раскрытием, поиск, закреплённые элементы, виртуализацию и Droplist — тот же список в popover.

Состав пакета

  • List — основной компонент. Принимает items (+ pinTop / pinBottom / footer), управляет выбором через selection, раскрытием групп через collapse, поиском через search. Поддерживает виртуализацию для 1000+ элементов.
  • Droplist — тот же список в popover. Оборачивает children-триггер и открывает список рядом с ним. Передаёт почти все пропсы List.
  • ReorderableList — список с drag&drop-переупорядочиванием строк через @dnd-kit (плюс ReorderableDroplist — то же в поповере).
  • ItemContent — каноничная разметка содержимого item: label (заголовок), caption (мета справа), description (подпись снизу). Используется как значение item.content.

Когда использовать

ЗадачаКак решить
Навигация/меню/settings sidebarList с items
Выбор из коллекции (радио-группа/чекбоксы)List + selection={{ mode: 'single' | 'multiple', ... }}
Выпадашка-селектор у кнопки/поляDroplist с children-триггером
Группы с раскрытием (inbox/starred/folders)items типа { type: 'collapse', items: [...] } + collapse
Длинный список (1k+)virtualized на List
Закреплённые действия сверху/снизуpinTop / pinBottom

Когда не нужен List:

  • Простой набор из 2–4 кнопок — используйте Button + layout.
  • Табличные данные с сортировкой/фильтрацией — используйте Table.
  • Многошаговая форма — используйте Stepper.

Установка

pnpm add @cloud-ru/ds-list
import { List, Droplist, ItemContent } from '@cloud-ru/ds-list'
import '@cloud-ru/ds-list/style.css'

Общие принципы

  • Contract первый, стайлинг второй. Элементы описываются как данные (items: Item[]), а не как JSX. Это даёт стабильную клавиатурную навигацию, selection и поиск «из коробки».
  • ItemContent — единый слот контента. Разметку внутри элемента задаёт не потребитель, а ItemContent — чтобы заголовок / caption / description выравнивались одинаково во всех пакетах.
  • Controlled/uncontrolled симметричны. У selection, collapse и search одинаковая форма: defaultValue / value + onChange. Выбирайте по тому, где должен жить state.
  • Виртуализация — осознанный выбор. Включайте virtualized только при 1k+ элементов. На коротких списках виртуализация ломает layout-assumptions (динамическая высота, focus-into-view).

Figma

Все три компонента живут в одном Figma-файле «Состояния для list / tab / toggles». Ссылки на конкретные узлы — на страницах компонентов.