@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 0.36.0-beta0

package/bundle/components/List.md

@@ -1,9 +1,7 @@
 ---
 component: List
-category: Data Display
-figma-node: ""
-figma-file: ""
-related: [ListMaster, Table, TreeView, Checkbox, LoaderScreen]
+category: List
+related: [ListSortable, ListItem, ListEmptyState, ListItemLoading, LoaderScreen]
 tokens: []
 stories: stories/List/List.stories.tsx
 version: "1.0"
@@ -13,235 +11,245 @@ version: "1.0"
 
 ## Назначение
 
-Семейство компонентов для списков (`<ul>` / `<li>`) с набором слотов
-для строк: контент, правый контролы-блок, хвосты слева/справа, чекбокс-
-выбор, вложенный DropdownButton, drag-and-drop. Поддерживает loading-overlay
-на уровне списка.
+Контейнер `<ul>` для набора элементов списка. Управляет состоянием загрузки
+через prop `loading` (показывает overlay-спиннер `LoaderScreen` поверх
+содержимого).
 
-Используй когда: нужен табличный список с повторяющимися строками и
-фиксированной визуальной структурой. Для таблиц с колонками — `Table`,
-для древовидных — `TreeView`, для master-detail интерфейсов — `ListMaster`.
-
----
-
-## Файловая структура
-
-```text
-src/components/List/
-├── List.tsx                                       # <ul>, loading-overlay
-├── ListSortable.tsx                               # DnD обёртка (dnd-kit)
-├── index.ts                                       # Barrel всех слотов
-├── components/
-│   ├── ListItem.tsx                               # <li> + Provider ListItemContext
-│   ├── ListItemContext.ts                         # { selected, setSelected }
-│   ├── ListItemContent.tsx                        # Основной контент строки
-│   ├── ListItemControls.tsx                       # Правый блок кнопок
-│   ├── ListItemControlsButton.tsx                 # Стилизованная кнопка в Controls
-│   ├── ListItemControlsButtonDropdown.tsx         # Кнопка с выпадающим меню
-│   ├── ListItemSelectable.tsx                     # Обёртка с Checkbox, пишет selected в Context
-│   ├── ListItemTable.tsx                          # Табличный вид строки
-│   ├── ListItemTailLeft.tsx                       # Левый хвост (иконка, аватар)
-│   ├── ListItemTailRight.tsx                      # Правый хвост
-│   ├── ListItemLoading.tsx                        # Placeholder-строка при loading
-│   ├── ListEmptyState.tsx                         # Пустое состояние
-│   ├── ListSortableItem.tsx                       # <li> с useSortable (DnD)
-│   ├── ListSortableItemControls.tsx               # DnD-handle control (drag)
-│   └── ListSortableItemTarget.tsx                 # Цель сортировки
-└── styles/*.module.less
-```
+Используй `List` когда: нужен стандартный список с произвольным контентом.
+Используй `ListSortable` когда: нужна сортировка элементов через drag-and-drop.
 
 ---
 
 ## Варианты и props
 
-### List — `IListProps extends HTMLAttributes<HTMLUListElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `loading` | `boolean` | — | Накладывает `LoaderScreen type="middle"` поверх списка. |
-| `...ulAttributes` | — | — | Стандартные `<ul>`-атрибуты. |
+| `loading` | `boolean` | `false` | Показывает `LoaderScreen` поверх содержимого. Используется при обновлении текущего списка новыми данными (например, после применения фильтра) |
+| `children` | `React.ReactNode` | — | Элементы списка (обычно `<ListItem>` или `<ListItemTable>`) |
+| `...HTMLUListElementAttributes` | — | — | Все стандартные атрибуты `<ul>` |
 
-### ListItem — `IListItemProps extends LiHTMLAttributes<HTMLLIElement>`
-
-Создаёт собственный `ListItemContext` с `{ selected, setSelected }`. Подкомпоненты (`ListItemSelectable`) пишут в него.
-
-### ListItemSelectable — `IListItemSelectableProps extends Omit<HTMLDivAttributes, "onSelect">`
-
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `selected` | `boolean` | Да | Управляемое состояние выбора. |
-| `onSelect` | `(selected: boolean) => void` | Да | Callback при изменении. |
-
-- Внутри — `<Checkbox>` + `useEffect(() => setSelected(selected))` — синхронизирует с `ListItemContext`, чтобы сиблинги (например, стили строки) могли реагировать на выбор.
-- `<span className={styles.checkboxLabelClickArea} />` — растягивающаяся область клика (не только на чекбокс).
-
-### ListItemContent — базовый слот для текста/описания строки.
-
-### ListItemControls / ListItemControlsButton / …ButtonDropdown
+---
 
-| Компонент | Назначение |
-|---|---|
-| `ListItemControls` | Контейнер для кнопок справа. |
-| `ListItemControlsButton` | Стилизованная кнопка-иконка. |
-| `ListItemControlsButtonDropdown` | Кнопка + вложенное выпадающее меню. |
+## Инварианты
 
-### ListItemTailLeft / ListItemTailRight — хвосты (иконки, аватары, статусы) по краям строки.
+- **`forwardRef`** — обязателен, target — `HTMLUListElement`. Не убирать.
+- **Корневой элемент `<ul>`** — не менять. Семантика списка важна для accessibility.
+- `loading` — overlay-стратегия (содержимое не размонтируется), не путать с `ListItemLoading` (отдельный элемент-спиннер для пагинации).
+- **`.listLoaderScreen` — `z-index: @z-index-step`**. Понижает z-index относительно глобального `@z-index-loader-screen` у `LoaderScreen`, чтобы спиннер перекрывал только содержимое списка, а не `LightBox` / `ModalWindow`. Не повышать без проверки наложения на модальные слои.
 
-### ListItemTable
+---
 
-Табличный вид строки: внутренняя сетка для выравнивания колонок между строками.
+## Связанные компоненты
 
-### ListItemLoading — скелетон-строка, показывается во время загрузки.
+- `ListItem` — базовый элемент списка, провайдер контекста для `selected`-состояния.
+- `ListSortable` — тот же `<ul>`, но с DnD-обвязкой через `@dnd-kit`.
+- `ListEmptyState` — отображается вместо элементов, когда данных нет (например, после фильтра).
+- `ListItemLoading` — элемент-спиннер для подгрузки следующей страницы (пагинация).
+- `LoaderScreen` — используется внутри `List` для состояния `loading`.
 
-### ListEmptyState — рендерится, когда `items.length === 0`, параметры для заголовка/описания/иконки.
+---
 
-### ListSortable<T extends { id: string }> — `IListSortableProps<T>`
+## Stories
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `items` | `T[]` | Да | Массив элементов, у каждого должно быть поле `id`. |
-| `onItemsChange` | `(items: T[]) => void` | Да | Callback после перестановки. |
-| `...IListProps` | — | — | Проброс на `<List>`. |
+Основные истории: `stories/List/List.stories.tsx`
+Файлы примеров: `stories/List/examples/List/`
 
-- Обёртка над `@dnd-kit/core` + `@dnd-kit/sortable`.
-- Modifiers: `restrictToParentElement` + `restrictToVerticalAxis` — нельзя перетащить в другой родитель или по горизонтали.
-- Внутри использует `AdvancedMouseSensor` / `AdvancedTouchSensor` — расширенные sensor'ы.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `loading` |
+| `Default` | `Default.tsx` | Базовый список |
+| `Loading` | `Loading.tsx` | Состояние загрузки (overlay) |
+| `EmptyState` | `EmptyState.tsx` | Использование `ListEmptyState` |
+| `Virtualized` | `Virtualized.tsx` | Виртуализированный список (большие наборы данных) |
+| `Sortable` | `Sortable.tsx` | DnD-сортировка через `ListSortable` + `ListSortableItem` |
+| `SortableWithInteractiveElements` | `SortableWithInteractiveElements.tsx` | DnD с интерактивными элементами внутри строк (`data-draggable="false"`) |
 
-### ListSortableItem — `IListSortableItemProps extends Omit<LiHTMLAttributes, "children">`
+---
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `id` | `string` | Да | Уникальный идентификатор, должен совпадать с `items[i].id`. |
-| `disabled` | `boolean` | Нет | Блокирует drag. |
-| `children` | `ReactNode \| (provideProps) => ReactNode` | — | **Render-props или обычные children**. Provide-props: `{ dragging, disabled, listeners, setActivatorNodeRef }`. |
+## История изменений
 
-- Использует `useSortable` из dnd-kit, применяет `transform` стиль.
-- Render-props позволяют **селективно назначать drag handle** (через `listeners` + `setActivatorNodeRef`), а не делать перетаскиваемым всю строку.
-- `ListSortableItem.Target` (Object.assign) — подкомпонент `ListSortableItemTarget`.
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+| 2026-06-17 | `List.module.less`: локальный `z-index: @z-index-step` на `.listLoaderScreen` — исправлено перекрытие `LoaderScreen` поверх `LightBox` / `ModalWindow` |
 
 ---
 
-## Ключевые особенности реализации
+## Примеры использования
 
-### `AdvancedMouseSensor` / `AdvancedTouchSensor` — `data-draggable="false"` escape hatch
-
-```ts
-while (element !== null) {
-    if (element.dataset?.draggable === "false") return false;
-    element = element.parentElement;
-}
-```
+### Default
 
-- Любой потомок с `data-draggable="false"` **блокирует инициализацию drag'а**. Используется для кнопок/ссылок внутри строки — иначе клик по ним случайно запускает перетаскивание.
-- `MouseSensor`: игнорирует правую кнопку (`button === 2`).
-- `TouchSensor`: игнорирует мультитач (`touches.length > 1`).
-
-### `ListItemContext` — связь выбора и стилей сиблингов
+`stories/List/examples/List/Default.tsx`
 
 ```tsx
-<ListItemContext.Provider value={{ selected, setSelected }}>
-    <li>{children}</li>
-</ListItemContext.Provider>
+import React from "react";
+import { List, ListItem } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <div style={{ width: "500px" }}>
+        <List>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+        </List>
+    </div>
+);
 ```
 
-- `ListItemSelectable` пишет `selected` в контекст через `useEffect`.
-- Другие подкомпоненты (например, `ListItemContent`) могут подписаться и изменить стиль.
-- **Паттерн "выбор известен всей строке"** — без prop-drilling.
+### Loading
 
-### `loading` на уровне `List`
+`stories/List/examples/List/Loading.tsx`
 
 ```tsx
-<ul>
-  {children}
-  {loading ? <LoaderScreen type="middle" /> : null}
-</ul>
+import React from "react";
+import { List, ListItem } from "@sberbusiness/triplex-next";
+
+export const Loading = () => (
+    <div style={{ width: "150px" }}>
+        <List loading>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+            <ListItem>Элемент списка</ListItem>
+        </List>
+    </div>
+);
 ```
 
-LoaderScreen рендерится **внутри `<ul>`**, но позиционируется абсолютно (overlay). Структурно `<ul>` содержит `<li>` и невалидный для семантики элемент — это сознательный trade-off в пользу простоты позиционирования.
-
-### `data-tx={process.env.npm_package_version}` на `<ul>` и `<li>`
-
-Версия библиотеки в DOM для отладки. Сохранять при изменениях.
+### EmptyState
 
-### ListSortable — vertical-axis only
+`stories/List/examples/List/EmptyState.tsx`
 
-```ts
-modifiers: [restrictToParentElement, restrictToVerticalAxis]
+```tsx
+import React from "react";
+import {
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    EFontWeightTitle,
+    ETextSize,
+    ETitleSize,
+    Gap,
+    ListEmptyState,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+import { EmptytableSysIcon96 } from "@sberbusiness/icons-next";
+
+export const EmptyState = () => (
+    <ListEmptyState>
+        <div style={{ display: "flex", justifyContent: "center" }}>
+            <EmptytableSysIcon96 />
+        </div>
+
+        <Gap size={16} />
+
+        <Title size={ETitleSize.H3} weight={EFontWeightTitle.REGULAR}>
+            Title text
+        </Title>
+
+        <Gap size={8} />
+
+        <Text size={ETextSize.B3}>Нет данных, но можно предложить какие-то действия для заполнения таблицы.</Text>
+
+        <Gap size={24} />
+
+        <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.SM}>
+            Button Name
+        </Button>
+        <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM}>
+            Button Name
+        </Button>
+    </ListEmptyState>
+);
 ```
 
-- Список только вертикальный. Для горизонтальных списков — нужен отдельный компонент (сейчас не реализован).
+### Virtualized
 
-### ListSortableItem render-props
+`stories/List/examples/List/Virtualized.tsx`
 
 ```tsx
-<ListSortableItem id="1">
-    {({ listeners, setActivatorNodeRef }) => (
-        <>
-            <ListSortableItem.Target ref={setActivatorNodeRef} {...listeners}>
-                ≡
-            </ListSortableItem.Target>
-            {/* остальной контент — не перетаскиваемый */}
-        </>
-    )}
-</ListSortableItem>
+import React from "react";
+import { FixedSizeList } from "react-window";
+import { List, ListItem } from "@sberbusiness/triplex-next";
+
+const itemData = Array.from({ length: 100 }).map((_, index) => `List item ${index}`);
+
+export const Virtualized = () => (
+    <FixedSizeList
+        itemData={itemData}
+        itemCount={itemData.length}
+        itemSize={20}
+        width="100%"
+        height={200}
+        innerElementType={List}
+    >
+        {({ data, index, style }) => <ListItem style={style}>{data[index]}</ListItem>}
+    </FixedSizeList>
+);
 ```
 
-Стандартный паттерн dnd-kit. `setActivatorNodeRef` задаёт элемент-триггер перетаскивания (handle), `listeners` — события.
-
----
-
-## Инварианты
-
-- **`<ul>` + `<li>`** семантика — не заменять на `<div>`.
-- **`ListItemContext` shape** (`selected`, `setSelected`) — публичная точка расширения для сторонних кастомных подкомпонентов.
-- **`data-draggable="false"`** — атрибут-escape-hatch для ListSortable. Потребители в product-коде могут опираться на него, не менять семантику.
-- **`ListSortable` требует `items[].id: string`** — id как в React key, так и в dnd-kit. Переход на number/symbol — breaking.
-- **`arrayMove` от dnd-kit** — не собственная реализация. При смене DnD-библиотеки переписать.
-- **`IListSortableItemProps.children` — `ReactNode` или функция** — публичный render-props API.
-- **`LoaderScreen` внутри `<ul>`** — визуальное решение, не менять без согласования.
-- **ForwardRef** на всех компонентах; `ListSortable` — generic через `as <T>(props) => ...` cast.
-- **`Object.assign` на `ListSortableItem` → `Target`** — сохранить.
-
----
+### Sortable
 
-## Accessibility
-
-- Семантика списка `<ul>`/`<li>` — правильная. Screen reader'ы объявляют "list, N items".
-- `ListItemSelectable` — `<Checkbox>` внутри: нативная клавиатурная навигация, label через расширяющую clickable-область.
-- `ListItemControlsButton` / `ListItemControlsButtonDropdown` — проверь, что `aria-label` проставлен (иконки без текста).
-- **DnD не доступен с клавиатуры** из коробки (dnd-kit поддерживает `KeyboardSensor`, но здесь не подключён). Known debt.
-- Loader'овый overlay скрывает контент — добавь `aria-busy="true"` на `<ul>` через `...rest` на время загрузки.
-
----
-
-## Дизайн-токены
-
-Нет прямых — визуал строки зависит от подкомпонентов (`ListItemSelectable`, `ListItemControls` используют собственные стили в `styles/*.module.less`).
-
----
+`stories/List/examples/List/Sortable.tsx`
 
-## Связанные компоненты
-
-- `ListMaster` — master-detail layout на базе List.
-- `Table` — табличный вид с колонками.
-- `TreeView` — древовидный список.
-- `Checkbox` — используется в `ListItemSelectable`.
-- `LoaderScreen` — overlay для loading.
-- `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/modifiers` — DnD-инфраструктура.
-
----
-
-## Stories
+```tsx
+import React, { useState } from "react";
+import { ListSortable, ListSortableItem } from "@sberbusiness/triplex-next";
+
+export const Sortable = () => {
+    const [items, setItems] = useState(
+        Array.from({ length: 10 }, (_, index) => ({ id: `list-sortable-item-0-${index}`, index })),
+    );
+
+    return (
+        <ListSortable items={items} onItemsChange={setItems}>
+            {items.map(({ id, index }) => (
+                <ListSortableItem key={id} id={id}>
+                    {({ listeners, dragging, setActivatorNodeRef }) => (
+                        <ListSortableItem.Target {...listeners} dragging={dragging} ref={setActivatorNodeRef}>
+                            List item {index}
+                        </ListSortableItem.Target>
+                    )}
+                </ListSortableItem>
+            ))}
+        </ListSortable>
+    );
+};
+```
 
-- `stories/List/List.stories.tsx`
-- `stories/List/ListItem.stories.tsx`
-- `stories/List/ListItemControls.stories.tsx`
-- Примеры: `stories/List/examples/`
+### SortableWithInteractiveElements
 
----
+`stories/List/examples/List/SortableWithInteractiveElements.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { Checkbox, ListSortable, ListSortableItem, ListSortableItemControls } from "@sberbusiness/triplex-next";
+
+export const SortableWithInteractiveElements = () => {
+    const [items, setItems] = useState(
+        Array.from({ length: 10 }, (_, index) => ({ id: `list-sortable-item-1-${index}`, index })),
+    );
+
+    return (
+        <ListSortable items={items} onItemsChange={setItems}>
+            {items.map(({ id, index }) => (
+                <ListSortableItem key={id} id={id}>
+                    {({ listeners, dragging, setActivatorNodeRef }) => (
+                        <ListSortableItem.Target {...listeners} dragging={dragging} ref={setActivatorNodeRef}>
+                            <ListSortableItemControls>
+                                <Checkbox>List item {index}</Checkbox>
+                            </ListSortableItemControls>
+                        </ListSortableItem.Target>
+                    )}
+                </ListSortableItem>
+            ))}
+        </ListSortable>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |