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

package/bundle/components/ListItem.md

@@ -0,0 +1,276 @@
+---
+component: ListItem
+category: List
+related: [List, ListItemContent, ListActionItem, ListItemSelectable, ListTableItem, ListSortableItem]
+tokens:
+  - --triplex-next-ListItem-Background
+  - --triplex-next-ListItem-Background_Selected
+  - --triplex-next-ListItem-Background_Hover
+  - --triplex-next-ListItem-BorderColor_Focus
+stories: stories/List/ListItem.stories.tsx
+version: "1.0"
+---
+
+# ListItem
+
+## Назначение
+
+Базовый элемент списка `<li>` — обёртка вокруг произвольного содержимого
+(`ListItemContent`, `ListItemSelectable`, `SwipeableArea` и т.п.). Создаёт
+React-контекст `ListItemContext` с состояниями `selected` и `selectable`:
+`selected` управляет подсветкой `ListItemContent`, `selectable` сообщает
+дочернему `ListItemContent`, что элемент выбираемый — для применения скругления
+углов (`border-radius`). Оба флага пишутся `ListItemSelectable` через `useEffect`.
+
+Используй `ListItem` когда: нужен произвольный layout строки списка.
+Используй `ListTableItem` когда: нужна готовая табличная строка с support'ом
+swipe-actions и selectable.
+
+---
+
+## Варианты и props
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Содержимое строки |
+| `...HTMLLIElementAttributes` | — | — | Все стандартные атрибуты `<li>` |
+
+---
+
+## Дизайн-токены
+
+Сами стили `ListItem.tsx` пустые — токены применяются в подкомпонентах
+(`ListItemContent`, `ListItemSelectable`, `ListActionItem`):
+
+```text
+--triplex-next-ListItem-Background          // фон по умолчанию (ListItemContent)
+--triplex-next-ListItem-Background_Selected // фон, когда selected=true (ListItemContent)
+--triplex-next-ListItem-Background_Hover    // фон при hover на desktop (ListActionItem на ListItemContent)
+--triplex-next-ListItem-BorderColor_Focus   // цвет focus-обводки на desktop (ListActionItem)
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLLIElement`. Не убирать.
+- **`ListItemContext`** — провайдер на каждом `ListItem`. Не выносить наружу — context используется парой `ListItemSelectable` (writer для `selected` и `selectable`) ↔ `ListItemContent` (reader) внутри одной строки.
+- **Поля контекста `selected` / `selectable`** — оба `boolean`, дефолт `false`. `selectable` всегда выставляется в `true` из `ListItemSelectable` (через `useEffect`), `selected` синхронизируется с одноимённым prop'ом `ListItemSelectable`. Сеттеры (`setSelected`, `setSelectable`) предназначены только для внутренних консьюмеров.
+- **Корневой элемент `<li>`** — не менять. Семантика важна для accessibility.
+
+---
+
+## Связанные компоненты
+
+- `ListItemContent` — внутренняя обёртка для контента, читает `selected` из контекста.
+- `ListActionItem` — самодостаточный интерактивный элемент: сам рендерит `ListItem` + `ListItemContent` (hover, focus по Tab, клик по всей строке — `onClick`, Enter/Space). Используется напрямую внутри `List`. Другие компоненты семейства его не используют.
+- `ListItemSelectable` — добавляет чекбокс выбора, синхронизирует `selected` в контекст через `useEffect`.
+- `ListItemLoading` — элемент-спиннер для пагинации (используется как последний элемент).
+- `ListItemControls`, `ListItemControlsButton`, `ListItemControlsButtonDropdown` — кнопки действий, обычно внутри `SwipeableArea.rightSwipeableArea`.
+- `ListItemTailLeft` / `ListItemTailRight` — декоративные хвосты для `SwipeableArea`.
+- `ListTableItem` — комбинированная высокоуровневая обёртка.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItem.stories.tsx`
+Файлы примеров: `stories/List/examples/ListItem/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` | `Default.tsx` | Базовый элемент с произвольным контентом |
+| `Action` | `Action.tsx` | Использование `ListActionItem`  |
+| `Loading` | `Loading.tsx` | `ListItemLoading` как последний элемент при пагинации |
+| `Selectable` | `Selectable.tsx` | Использование `ListItemSelectable` внутри `ListItem` |
+| `Swipeable` | `Swipeable.tsx` | `ListItem` внутри `SwipeableArea` с `ListItemControls` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+| 2026-05-21 | `ListItemContext` расширен полями `selectable` / `setSelectable`. Исправлен цвет токена `Background_Selected` в тёмной теме (`ColorDarkNeutral.10` → `ColorDarkNeutral.60`). |
+| 2026-07-16 | Добавлен самодостаточный компонент `ListActionItem` (сам рендерит `ListItem` + `ListItemContent`; hover, focus по Tab, `onClick` + Enter/Space). Координация фона через контекст не понадобилась — `ListItemContext` без изменений. Другие компоненты семейства его не используют. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/List/examples/ListItem/Default.tsx`
+
+```tsx
+import React from "react";
+import { List, ListItem, ListItemContent } from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <div style={{ maxWidth: "500px" }}>
+        <List>
+            <ListItem>
+                <ListItemContent>Элемент списка</ListItemContent>
+            </ListItem>
+        </List>
+    </div>
+);
+```
+
+### Action
+
+`stories/List/examples/ListItem/Action.tsx`
+
+```tsx
+import React from "react";
+import { List, ListActionItem } from "@sberbusiness/triplex-next";
+
+export const Action = () => (
+    <div style={{ maxWidth: "500px" }}>
+        <List>
+            <ListActionItem listItemContentProps={{ onClick: () => alert("Клик по элементу списка") }}>
+                Элемент списка
+            </ListActionItem>
+        </List>
+    </div>
+);
+```
+
+### Loading
+
+`stories/List/examples/ListItem/Loading.tsx`
+
+```tsx
+import React from "react";
+import { List, ListItem, ListItemLoading } from "@sberbusiness/triplex-next";
+
+export const Loading = () => (
+    <div style={{ maxWidth: "500px" }}>
+        <List>
+            <ListItem>
+                <ListItemLoading />
+            </ListItem>
+        </List>
+    </div>
+);
+```
+
+### Selectable
+
+`stories/List/examples/ListItem/Selectable.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { List, ListItem, ListItemContent, ListItemSelectable } from "@sberbusiness/triplex-next";
+
+export const Selectable = () => {
+    const [selected, setSelected] = useState(false);
+
+    return (
+        <div style={{ maxWidth: "500px" }}>
+            <List>
+                <ListItem>
+                    <ListItemSelectable selected={selected} onSelect={setSelected}>
+                        <ListItemContent>Элемент списка</ListItemContent>
+                    </ListItemSelectable>
+                </ListItem>
+            </List>
+        </div>
+    );
+};
+```
+
+### Swipeable
+
+`stories/List/examples/ListItem/Swipeable.tsx`
+
+```tsx
+import React from "react";
+import {
+    ISwipeableAreaRef,
+    List,
+    ListItem,
+    ListItemContent,
+    ListItemControls,
+    ListItemControlsButton,
+    ListItemControlsButtonDropdown,
+    ListItemTailRight,
+    SwipeableArea,
+} from "@sberbusiness/triplex-next";
+import { DefaulticonStrokePrdIcon20 } from "@sberbusiness/icons-next";
+
+export const Swipeable = () => {
+    const options = [
+        {
+            id: "list-item-swipe-controls-dropdown-option-1",
+            label: "Текст пункта меню 1",
+            onSelect: () => alert("Выбран пункт меню 1."),
+        },
+        {
+            id: "list-item-swipe-controls-dropdown-option-2",
+            label: "Текст пункта меню 2",
+            onSelect: () => alert("Выбран пункт меню 2."),
+        },
+        {
+            id: "list-item-swipe-controls-dropdown-option-3",
+            label: "Текст пункта меню 3",
+            onSelect: () => alert("Выбран пункт меню 3."),
+        },
+    ];
+
+    const ref = React.useRef<ISwipeableAreaRef>(null);
+
+    return (
+        <div style={{ maxWidth: "500px" }}>
+            <button
+                onClick={() => {
+                    if (ref.current) {
+                        ref.current.swipeLeft();
+                    }
+                }}
+            >
+                swipe
+            </button>
+            <button
+                onClick={() => {
+                    if (ref.current) {
+                        ref.current.closeSwipe();
+                    }
+                }}
+            >
+                close
+            </button>
+            <br />
+
+            <List>
+                <ListItem>
+                    <SwipeableArea
+                        ref={ref}
+                        rightSwipeableArea={
+                            <ListItemControls>
+                                <ListItemControlsButton icon={<DefaulticonStrokePrdIcon20 paletteIndex={0} />}>
+                                    Button name
+                                </ListItemControlsButton>
+                                <ListItemControlsButtonDropdown
+                                    icon={<DefaulticonStrokePrdIcon20 paletteIndex={0} />}
+                                    options={options}
+                                >
+                                    Button name
+                                </ListItemControlsButtonDropdown>
+                            </ListItemControls>
+                        }
+                    >
+                        <ListItemTailRight />
+                        {/* Минимальная высота, из-за блока Action с кнопками при свайпе. */}
+                        <ListItemContent style={{ minHeight: "56px" }}>Свайп влево</ListItemContent>
+                    </SwipeableArea>
+                </ListItem>
+            </List>
+        </div>
+    );
+};
+```
+

package/bundle/components/ListItemControlsButton.md

@@ -0,0 +1,103 @@
+---
+component: ListItemControlsButton
+category: List
+related: [ListItemControls, ListItemControlsButtonDropdown, IconWrapper]
+tokens:
+  - --triplex-next-ListItemControlsButton-Background_Default
+  - --triplex-next-ListItemControlsButton-Background_Hover
+  - --triplex-next-ListItemControlsButton-Background_Active
+  - --triplex-next-ListItemControlsButton-Color_Default
+  - --triplex-next-ListItemControlsButton-Color_Hover
+  - --triplex-next-ListItemControlsButton-Color_Active
+stories: stories/List/ListItemControls.stories.tsx
+version: "1.0"
+---
+
+# ListItemControlsButton
+
+## Назначение
+
+Кнопка действия для области под свайпом списка. Рендерит вертикальную
+композицию `icon` + `children` (текст), оборачивает их в `IconWrapper`,
+который автоматически меняет цвет иконки/текста в hover/active состоянии.
+
+Используй `ListItemControlsButton` когда: нужно одно действие в swipe-actions.
+Используй `ListItemControlsButtonDropdown` когда: нужен выбор из нескольких
+действий через dropdown.
+
+---
+
+## Варианты и props
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `icon` | `React.ReactNode` | — | Иконка, отображается над текстом. Добавляет класс `withIcon` |
+| `children` | `React.ReactNode` | — | Текст кнопки (рендерится через `<Text size={B4} weight={SEMIBOLD}>`). Добавляет класс `withText` |
+| `disabled` | `boolean` | — | Стандартный атрибут `<button>`. Передаётся в `IconWrapper.disabled` |
+| `aria-expanded` | `boolean` | — | Стандартный ARIA-атрибут. Если `true` — `IconWrapper` получает класс `active` (визуальное состояние «нажато») |
+| `...HTMLButtonAttributes` | — | — | Все стандартные атрибуты `<button>`. `type` по умолчанию `"button"` |
+
+---
+
+## Дизайн-токены
+
+Паттерн: `--triplex-next-ListItemControlsButton-{Property}_{State}`
+
+```text
+--triplex-next-ListItemControlsButton-Background_Default
+--triplex-next-ListItemControlsButton-Background_Hover
+--triplex-next-ListItemControlsButton-Background_Active   // применяется при :active или классе .expanded (если выставлен снаружи)
+--triplex-next-ListItemControlsButton-Color_Default
+--triplex-next-ListItemControlsButton-Color_Hover
+--triplex-next-ListItemControlsButton-Color_Active
+```
+
+Цвет лейбла переопределяет токен `Color_*` через `!important`, потому что
+`<Text>` имеет свой `color`-стиль.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLButtonElement`. Не убирать.
+- **`type="button"`** по умолчанию — не убирать, иначе кнопка внутри `<form>` будет сабмитить.
+- **Классы `withIcon` / `withText`** — выставляются автоматически по наличию `icon` / `children`. Не передавать вручную.
+- **Лейбл оборачивается в `<Text>`** — не заменять на `<span>`, иначе сломается типографика и переопределение цвета через токены.
+
+---
+
+## Accessibility
+
+- Нативный `<button>` — полная поддержка клавиатуры (Tab, Enter, Space).
+- **Иконочный режим** (без `children`) — потребитель **обязан** передать `aria-label` через `...rest`. Библиотека мультиязычная, текст не хардкодится.
+- **`aria-expanded`** — используется когда кнопка является триггером dropdown (см. `ListItemControlsButtonDropdown`); визуально активирует подсветку иконки/текста через `IconWrapper.active`.
+
+---
+
+## Связанные компоненты
+
+- `ListItemControls` — обёртка-контейнер для группы `ListItemControlsButton`.
+- `ListItemControlsButtonDropdown` — расширение, добавляющее dropdown.
+- `IconWrapper` — обёртка для иконки, управляет цветом через `hoverable` / `active` / `disabled`.
+- `Text` — типографический компонент для лейбла.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItemControls.stories.tsx`
+Файл примера: `stories/List/examples/ListItemControls/Default.tsx`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` | `Default.tsx` | Несколько кнопок (icon-only, text-only, icon+text) и `ListItemControlsButtonDropdown` внутри `ListItemControls` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |

package/bundle/components/ListItemControlsButtonDropdown.md

@@ -0,0 +1,107 @@
+---
+component: ListItemControlsButtonDropdown
+category: List
+related: [ListItemControlsButton, ButtonDropdownExtended, Dropdown]
+tokens:
+  - --triplex-next-ListItemControlsButton-Background_Default
+  - --triplex-next-ListItemControlsButton-Background_Hover
+  - --triplex-next-ListItemControlsButton-Background_Active
+  - --triplex-next-ListItemControlsButton-Color_Default
+  - --triplex-next-ListItemControlsButton-Color_Hover
+  - --triplex-next-ListItemControlsButton-Color_Active
+stories: stories/List/ListItemControls.stories.tsx
+version: "1.0"
+---
+
+# ListItemControlsButtonDropdown
+
+## Назначение
+
+Кнопка-триггер для dropdown-меню в swipe-actions списка. Использует
+`ListItemControlsButton` как кнопку и `ButtonDropdownExtended` для
+выпадающего списка опций. На мобильном — bottom sheet, на десктопе — обычный
+dropdown.
+
+Используй когда: в swipe-actions нужно несколько действий, объединённых под
+одной кнопкой (обычно «Действия» / «Ещё»).
+
+---
+
+## Варианты и props
+
+Тип props: `Omit<IButtonDropdownProps, "size"> & Pick<IListItemControlsButtonProps, "icon">`
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `options` | `IButtonDropdownOption[]` | Список опций dropdown. Каждая опция: `{ id, label, onSelect?, ...IDropdownListItemProps }` |
+| `children` | `React.ReactNode` | Текст кнопки (становится заголовком mobile-bottom-sheet) |
+
+### Опциональные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `icon` | `React.ReactNode` | Иконка кнопки (как в `ListItemControlsButton`) |
+| `selected` | `IButtonDropdownOption` | Текущая выбранная опция (отмечается в dropdown) |
+| `disabled` | `boolean` | Блокирует кнопку и открытие dropdown |
+| `buttonAttributes` | `React.ButtonHTMLAttributes<HTMLButtonElement>` | Атрибуты, пробрасываемые на `<button>` |
+| `...HTMLDivAttributes` | — | Атрибуты внешнего `<div>` контейнера |
+
+---
+
+## Дизайн-токены
+
+Использует те же токены, что и `ListItemControlsButton`. Дополнительно — стиль
+`.buttonDropdownMenuItem` для опций dropdown (ellipsis для длинных лейблов).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLButtonElement` (на саму кнопку, не на контейнер).
+- **`aria-haspopup="menu"`, `aria-controls={instanceId}`** — выставляются автоматически. `aria-expanded` синхронизируется с состоянием `opened`.
+- **`closeOnTab`** — включён всегда (Tab закрывает dropdown).
+- **`uniqueId` для `instanceId`** — используется `lodash-es/uniqueId` через `useRef(uniqueId())`. **Не** мигрировать на `useId()` — ветка `release-0` поддерживает React 17, см. `docs/ai/ai-refactoring.md`.
+
+---
+
+## Accessibility
+
+- **Клавиатура:**
+  - `Space`, `ArrowUp`, `ArrowDown` — `preventDefault` (не скроллит страницу).
+  - `ArrowUp` / `ArrowDown` в закрытом состоянии — открывают dropdown.
+  - `Escape` / `Tab` — закрывают dropdown (через `ButtonDropdownExtended`).
+- **`aria-haspopup="menu"`** — указывает на наличие меню.
+- **`aria-expanded`** — синхронизирован с `opened` (true/false).
+- **`aria-controls`** — связывает кнопку с id dropdown.
+- **`aria-activedescendant`** — управляется через `DropdownListContext`, указывает на текущий выделенный элемент.
+
+---
+
+## Связанные компоненты
+
+- `ListItemControlsButton` — используется как сама кнопка-триггер.
+- `ButtonDropdownExtended` — обвязка для кастомных кнопок + dropdown.
+- `Dropdown`, `DropdownList` (desktop) — выпадающий список на десктопе.
+- `DropdownMobileBody`, `DropdownMobileList`, `DropdownMobileListItem`, `DropdownMobileHeader`, `DropdownMobileClose` — bottom-sheet на мобильном.
+- `DropdownListContext` — управление `activeDescendant`.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItemControls.stories.tsx`
+Файл примера: `stories/List/examples/ListItemControls/Default.tsx`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` | `Default.tsx` | `ListItemControlsButtonDropdown` рядом с `ListItemControlsButton` внутри `ListItemControls` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |

package/bundle/components/ListItemSelectable.md

@@ -0,0 +1,99 @@
+---
+component: ListItemSelectable
+category: List
+related: [ListItem, ListItemContent, Checkbox]
+tokens:
+  - --triplex-next-ListItem-Background
+  - --triplex-next-ListItem-Background_Selected
+stories: stories/List/ListItem.stories.tsx
+version: "1.0"
+---
+
+# ListItemSelectable
+
+## Назначение
+
+Контейнер выбора элемента списка. Рендерит контент + чекбокс справа.
+Управляется снаружи (`selected` + `onSelect`). Через `useEffect` записывает
+в `ListItemContext` два флага: `selected` — для подсветки фона дочернего
+`ListItemContent` (`background_selected`); `selectable: true` — для
+применения скругления углов (`border-radius`) в `ListItemContent`.
+
+Используй `ListItemSelectable` когда: нужен выбор отдельного элемента списка
+с собственным чекбоксом (multi-select).
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `selected` | `boolean` | Состояние «выбран». Управляется снаружи |
+| `onSelect` | `(selected: boolean) => void` | Вызывается при изменении состояния чекбокса |
+
+### Опциональные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `disabled` | `boolean` | Блокирует встроенный `Checkbox` (передаётся в `Checkbox` как есть) |
+| `children` | `React.ReactNode` | Контент строки (рендерится в `<div className="childrenWrapper">`) |
+| `...HTMLDivAttributes` | — | Все атрибуты `<div>`, кроме конфликтующего `onSelect` (исключён через `Omit`) |
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-ListItem-Background          // фон по умолчанию
+--triplex-next-ListItem-Background_Selected // фон, когда selected=true
+```
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLDivElement`. Не убирать.
+- **Контракт `onSelect: (boolean) => void`** — не путать с нативным `onSelect: SelectionEvent` от `<div>`. Тип специально перекрывает нативный через `Omit<..., "onSelect">`.
+- **Два `useEffect`** — синхронизируют `ListItemContext`:
+  - `[selected, setSelected]` → запись `selected` (для подсветки `ListItemContent`).
+  - `[setSelectable]` → запись `selectable = true` при монтировании и cleanup в `false` при размонтировании (для скругления углов `ListItemContent`). Не убирать запись — иначе у выбираемого элемента не появится `border-radius`. Не убирать cleanup — иначе при условном размонтировании `ListItemSelectable` внутри живого `ListItem` состояние «прилипнет» в `true`.
+- **Использование внутри `ListItem`** — `setSelected` / `setSelectable` берутся из `ListItemContext`. Если рендерить `ListItemSelectable` без родительского `ListItem`, контекст вернёт no-op сеттеры.
+
+---
+
+## Accessibility
+
+- Чекбокс — встроенный `<Checkbox>` из библиотеки, имеет нативный `<input type="checkbox">`.
+- Клик по любой части `.childrenWrapper` **не** переключает чекбокс — только клик по самому чекбоксу или его расширенной области (`.checkboxLabelClickArea`, `+4px` со всех сторон).
+- Если нужен клик по всей строке — оборачивай в `<label>` или используй `ListTableItem` + `onClickItem`.
+
+---
+
+## Связанные компоненты
+
+- `ListItem` — родительский `<li>`, провайдер `ListItemContext`.
+- `ListItemContent` — потребитель `ListItemContext.selected` для применения класса `selected`.
+- `Checkbox` — встроенный чекбокс выбора.
+- `ListTableItem` — использует `ListItemSelectable` автоматически в selectable-варианте.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItem.stories.tsx`
+Файл примера: `stories/List/examples/ListItem/Selectable.tsx`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Selectable` | `Selectable.tsx` | Использование `ListItemSelectable` внутри `ListItem` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+| 2026-05-21 | Добавлен опциональный prop `disabled` (пробрасывается в `Checkbox`). Компонент пишет в `ListItemContext` флаг `selectable = true` при монтировании. |