@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/ListMasterFooter.md

@@ -0,0 +1,80 @@
+---
+component: ListMasterFooter
+category: List
+related: [ListMaster, ListMasterFooterDescription, ListMasterFooterControls]
+tokens:
+  - --triplex-next-ListMaster-Footer_Background
+  - --triplex-next-ListMaster-Footer_Shadow
+stories: stories/ListMaster/ListMaster.stories.tsx
+version: "1.0"
+---
+
+# ListMasterFooter
+
+## Назначение
+
+Sticky-футер `ListMaster`. Используется обычно при выделении ≥1 элемента
+списка для показа агрегатов (например, суммы выбранных) и действий по
+выбранному. По умолчанию имеет `display: flex; justify-content: space-between;
+align-items: center` — слева текст (`FooterDescription`), справа кнопки
+(`FooterControls`).
+
+Используется как `<ListMaster.Footer>` или импортируется напрямую.
+
+---
+
+## Варианты и props
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `sticky` | `boolean` | `true` | Sticky-позиционирование (`bottom: 0`). При `false` футер ведёт себя как обычный блок |
+| `children` | `React.ReactNode` | — | Содержимое футера (обычно пара `FooterDescription` + `FooterControls`) |
+| `...HTMLDivAttributes` | — | — | Все атрибуты `<div>` |
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-ListMaster-Footer_Background  // фон футера
+--triplex-next-ListMaster-Footer_Shadow      // тень сверху
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLDivElement`. Не убирать.
+- **Внутренний layout `flex / space-between`** — публичный визуальный контракт. `FooterDescription` и `FooterControls` не делают `justify-content` сами — это задача футера.
+- **Корневой DOM** — `<div>`. Не менять.
+- В отличие от `ListMasterHeader`, scroll-компенсации НЕТ — футер не сдвигает контент при появлении.
+
+---
+
+## Связанные компоненты
+
+- **`ListMaster`** — родительский compound. `ListMasterFooter` доступен как `ListMaster.Footer`.
+- **`ListMasterFooterDescription`** (`ListMaster.FooterDescription`) — левая текстовая часть. Тривиальный wrapper, описан в `ListMaster-ai.md`.
+- **`ListMasterFooterControls`** (`ListMaster.FooterControls`) — правый контейнер кнопок. Тривиальный wrapper, описан в `ListMaster-ai.md`.
+- **`ListMasterHeader`** — симметричная sticky-шапка.
+
+---
+
+## Stories
+
+Демонстрируется в общей story `Default` компонента `ListMaster` — появляется,
+когда `selectedListItemIds.length > 0`. Отдельных stories нет.
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` (в `ListMaster.stories.tsx`) | `Default.tsx` | Sticky-футер с суммой выбранных (`FooterDescription`) и действиями `ButtonDropdown` + `Button` (`FooterControls`) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ. Уточнён JSDoc по дефолтному значению `sticky`. Добавлены unit-тесты. |

package/bundle/components/ListMasterHeader.md

@@ -0,0 +1,86 @@
+---
+component: ListMasterHeader
+category: List
+related: [ListMaster, SelectionControls]
+tokens:
+  - --triplex-next-ListMaster-Header_Background
+  - --triplex-next-ListMaster-Header_Shadow
+stories: stories/ListMaster/ListMaster.stories.tsx
+version: "1.0"
+---
+
+# ListMasterHeader
+
+## Назначение
+
+Sticky-шапка `ListMaster`. Показывается обычно при выделении ≥1 элемента
+списка (для отображения selection controls). При монтировании компенсирует
+свою высоту через `window.scrollTo`, чтобы появление шапки не сдвигало
+содержимое визуально вниз; при размонтировании — откатывает скролл.
+
+Используется как `<ListMaster.Header>` или импортируется напрямую — оба
+варианта поддерживаются barrel'ом.
+
+---
+
+## Варианты и props
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `sticky` | `boolean` | `true` | Sticky-позиционирование (`top: 0`, `z-index: 1`). При `false` шапка ведёт себя как обычный блок |
+| `children` | `React.ReactNode` | — | Содержимое шапки (обычно `<ListMaster.SelectionControls>`) |
+| `...HTMLDivAttributes` | — | — | Все атрибуты `<div>` |
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-ListMaster-Header_Background  // фон шапки
+--triplex-next-ListMaster-Header_Shadow      // тень снизу
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLDivElement`. Не убирать.
+- **`useEffect` со scroll-компенсацией** — публичное наблюдаемое поведение, на котором завязан UX (контент не «прыгает» при появлении шапки). Не удалять без согласования с дизайнером.
+- **`z-index: 1`** в sticky-режиме — нужен чтобы шапка перекрывала `ListMasterBody`. Не уменьшать.
+- **Корневой DOM** — `<div>`. Не менять.
+
+---
+
+## Accessibility
+
+- Семантика — обычный `<div>`. Если используется как landmark, потребитель должен передать `role="banner"` или обернуть в `<header>` через `as`-паттерн (сейчас не поддерживается, см. барьер: компонент рендерит `<div>` хардкодом).
+- Содержимое (selection-controls) обычно содержит `<button>`-ы — их accessibility — задача потребителя.
+
+---
+
+## Связанные компоненты
+
+- **`ListMaster`** — родительский compound. `ListMasterHeader` доступен как `ListMaster.Header`.
+- **`SelectionControls`** (`ListMaster.SelectionControls`) — flex-контейнер для типичного контента шапки (выбрать все / счётчик / сбросить).
+- **`ListMasterFooter`** — симметричный sticky-футер.
+
+---
+
+## Stories
+
+Демонстрируется в общей story `Default` компонента `ListMaster` — появляется,
+когда `selectedListItemIds.length > 0`. Отдельных stories нет.
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` (в `ListMaster.stories.tsx`) | `Default.tsx` | Sticky-шапка с `SelectionControls` (Выбрать все / счётчик / Сбросить) при наличии выделенных элементов |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ. Уточнён JSDoc по `useEffect`-логике компенсации скролла. Добавлены unit-тесты. |

package/bundle/components/ListSortable.md

@@ -0,0 +1,153 @@
+---
+component: ListSortable
+category: List
+related: [List, ListSortableItem, ListSortableItemTarget, ListSortableItemControls]
+tokens: []
+stories: stories/List/List.stories.tsx
+version: "1.0"
+---
+
+# ListSortable
+
+## Назначение
+
+`<ul>`-контейнер с поддержкой drag-and-drop сортировки на основе `@dnd-kit`.
+Принимает массив `items` (каждый объект должен иметь `id: string`) и
+callback `onItemsChange`, в который пробрасывает результат `arrayMove` после
+успешного перетаскивания.
+
+Используй `ListSortable` когда: нужна сортировка элементов мышью/тачем.
+Иначе используй обычный `List`.
+
+---
+
+## Варианты и props
+
+`ListSortable<T extends { id: string }>` — generic.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `items` | `T[]` | Текущий упорядоченный список элементов. У каждого должен быть уникальный `id: string` |
+| `onItemsChange` | `(items: T[]) => void` | Вызывается с новым порядком после drag-and-drop |
+
+### Опциональные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `loading` | `boolean` | Передаётся во внутренний `<List>` (overlay-спиннер) |
+| `children` | `React.ReactNode` | Обычно `items.map(item => <ListSortableItem id={item.id}>...)` |
+| `...HTMLUListElementAttributes` | — | Прокидываются во внутренний `<ul>` |
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLUListElement` (внутренний `<List>`). Не убирать.
+- **Generic `T extends { id: string }`** — обязательно, иначе `arrayMove` + `findIndex` сломаются.
+- **`AdvancedMouseSensor` / `AdvancedTouchSensor`** — экспортируются из barrel, переименовывать или удалять — breaking change.
+- **`isDraggableTarget`** (из `src/components/List/utils.ts`) — общий хелпер для обоих сенсоров; проверяет цепочку `data-draggable="false"` вверх по DOM. Используй `ListSortableItemControls` или вручную выставляй `data-draggable="false"`, чтобы исключить элемент из drag-area (см. `SortableWithInteractiveElements`-стори).
+- **`measuring.droppable.frequency: WhileDragging`** — нужен для корректной перерисовки виртуализированных списков; не менять без причины.
+
+---
+
+## Accessibility
+
+- DnD на `@dnd-kit` поддерживает клавиатурную навигацию через `KeyboardSensor`, но в текущей конфигурации он **не включён** — добавляется потребителем при необходимости.
+- Сенсоры реагируют только на клик левой кнопкой мыши (правая кнопка `event.button === 2` отбрасывается).
+- Touch — отбрасывается мульти-тач (`event.touches.length > 1`).
+
+---
+
+## Связанные компоненты
+
+- `List` — внутренний `<ul>`-контейнер; `ListSortable` оборачивает его в `DndContext` + `SortableContext`.
+- `ListSortableItem` — элемент с `useSortable`-обвязкой; обычно используется как непосредственный child.
+- `ListSortableItemTarget` — визуальная «карточка» элемента с drag-индикатором.
+- `ListSortableItemControls` — обёртка для интерактивных элементов внутри строки (`data-draggable="false"`).
+
+---
+
+## Stories
+
+Основные истории: `stories/List/List.stories.tsx`
+Файлы примеров: `stories/List/examples/List/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Sortable` | `Sortable.tsx` | Базовая DnD-сортировка |
+| `SortableWithInteractiveElements` | `SortableWithInteractiveElements.tsx` | Сортировка с интерактивными элементами внутри строк (`data-draggable="false"` через `ListSortableItemControls`) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+
+---
+
+## Примеры использования
+
+### Sortable
+
+`stories/List/examples/List/Sortable.tsx`
+
+```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>
+    );
+};
+```
+
+### 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>
+    );
+};
+```
+

package/bundle/components/ListSortableItem.md

@@ -0,0 +1,175 @@
+---
+component: ListSortableItem
+category: List
+related: [ListSortable, ListSortableItemTarget, ListSortableItemControls, ListItem]
+tokens:
+  - --triplex-next-ListItem-Background
+  - --triplex-next-ListItem-Background_Selected
+  - --triplex-next-ListItem-Background_Dragging
+  - --triplex-next-ListItem-Shadow_Dragging
+stories: stories/List/List.stories.tsx
+version: "1.0"
+---
+
+# ListSortableItem
+
+## Назначение
+
+Элемент `<li>` с обвязкой `useSortable` из `@dnd-kit/sortable` — даёт ему
+transform/transition для анимации перетаскивания и активирует drag-handle.
+Имеет статический подкомпонент `Target` (`ListSortableItem.Target`) для
+визуальной «карточки» с drag-индикатором.
+
+Используй `ListSortableItem` внутри `ListSortable` для элементов, которые
+надо перетаскивать. Может принимать render-prop children — это даёт доступ к
+`dragging`/`disabled`/`listeners`/`setActivatorNodeRef` для случаев, когда
+drag-handle нужно вынести в отдельный элемент.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Уникальный идентификатор. Должен совпадать с `id` в массиве `items` родительского `ListSortable` |
+
+### Опциональные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `disabled` | `boolean` | Запрещает drag для конкретного элемента |
+| `children` | `React.ReactNode \| ((provideProps) => React.ReactNode)` | Контент или render-prop. Render-prop принимает `{ disabled, dragging, listeners, setActivatorNodeRef }` |
+| `style` | `React.CSSProperties` | Дополняется автоматическими `transform`/`transition` от `useSortable` |
+| `...HTMLLIElementAttributes` | — | Прокидываются на корневой `<li>` через `ListItem` |
+
+### Статический подкомпонент
+
+| Имя | Описание |
+|---|---|
+| `ListSortableItem.Target` | `ListSortableItemTarget` — стандартная карточка с drag-индикатором (`DragdotsStrokeSrvIcon24`) |
+
+---
+
+## Дизайн-токены
+
+Сам `ListSortableItem` не использует токены (только z-index при `dragging`).
+Токены применяются в `ListSortableItem.Target`:
+
+```text
+--triplex-next-ListItem-Background           // фон по умолчанию
+--triplex-next-ListItem-Background_Selected  // фон при hover
+--triplex-next-ListItem-Background_Dragging  // фон во время drag
+--triplex-next-ListItem-Shadow_Dragging      // тень во время drag
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLLIElement`. Объявлен через `Object.assign` с `Target` в качестве static-свойства, чтобы `displayName` работал корректно.
+- **`Object.assign({...forwardRef}, { Target })`** — паттерн compound-component. Не разворачивай в отдельный экспорт, иначе сломается DX (`<ListSortableItem.Target>`).
+- **`transition: { duration: 300, easing: "ease-out" }`** — фиксированное значение, согласовано с дизайнером. Не менять без согласования.
+- **Render-prop children** — публичный API, потребитель может полагаться на сигнатуру `IListSortableItemChildrenProvideProps`.
+
+---
+
+## Accessibility
+
+- Drag-handle по умолчанию — вся карточка (`<li>`-элемент). Если нужно вынести handle — используй render-prop и `setActivatorNodeRef`.
+- В нативном виде — поддержка только мыши/тача (см. ограничения `ListSortable`).
+
+---
+
+## Связанные компоненты
+
+- `ListSortable` — родительский контекст DnD; без него `useSortable` не работает.
+- `ListSortableItemTarget` (= `ListSortableItem.Target`) — стандартная визуальная «карточка».
+- `ListSortableItemControls` — обёртка с `data-draggable="false"` для интерактивных элементов внутри строки (кнопки, чекбоксы), которые не должны инициировать drag.
+- `ListItem` — внутренний `<li>`-контейнер.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/List.stories.tsx`
+Файлы примеров: `stories/List/examples/List/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Sortable` | `Sortable.tsx` | Простой случай — `ListSortableItem` с `ListSortableItem.Target` |
+| `SortableWithInteractiveElements` | `SortableWithInteractiveElements.tsx` | Render-prop children + `ListSortableItemControls` для исключения интерактивных элементов из drag-области |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+
+---
+
+## Примеры использования
+
+### Sortable
+
+`stories/List/examples/List/Sortable.tsx`
+
+```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>
+    );
+};
+```
+
+### 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>
+    );
+};
+```
+