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

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,270 @@ 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>` или `<ListTableItem>`) |
+| `...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` |
+| `WithActionItems` | `WithActionItems.tsx` | Список из кликабельных строк `ListActionItem` |
+| `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`** — сохранить.
-
----
-
-## 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`).
+### 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>
+    );
+};
+```
 
-- `ListMaster` — master-detail layout на базе List.
-- `Table` — табличный вид с колонками.
-- `TreeView` — древовидный список.
-- `Checkbox` — используется в `ListItemSelectable`.
-- `LoaderScreen` — overlay для loading.
-- `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/modifiers` — DnD-инфраструктура.
+### WithActionItems
 
----
+`stories/List/examples/List/WithActionItems.tsx`
 
-## Stories
+```tsx
+import React from "react";
+import { List, ListActionItem } from "@sberbusiness/triplex-next";
+
+export const WithActionItems = () => (
+    <div style={{ maxWidth: "500px" }}>
+        <List>
+            {Array.from({ length: 5 }, (_, index) => (
+                <ListActionItem
+                    key={index}
+                    listItemContentProps={{ onClick: () => alert(`Клик по элементу списка ${index}`) }}
+                >
+                    Элемент списка {index}
+                </ListActionItem>
+            ))}
+        </List>
+    </div>
+);
+```
 
-- `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 | Создан документ |

package/bundle/components/ListActionItem.md

@@ -0,0 +1,157 @@
+---
+component: ListActionItem
+category: List
+related: [ListItem, ListItemContent, ListSortableItem]
+tokens:
+  - --triplex-next-ListItem-Background_Hover
+  - --triplex-next-ListItem-BorderColor_Focus
+stories: stories/List/ListItem.stories.tsx
+version: "1.0"
+---
+
+# ListActionItem
+
+## Назначение
+
+Самодостаточный интерактивный элемент списка. Сам рендерит `ListItem` и
+`ListItemContent` (по аналогии с тем, как `ListSortableItem` рендерит внутри себя
+`ListItem`), поэтому потребителю не нужно вручную составлять композицию. Добавляет
+hover-подсветку, focus-обводку по Tab и активацию по клику / Enter / Space.
+
+Ключевая идея: интерактивные атрибуты (`role`, `tabIndex`, обработчики) и класс
+`styles.listActionItem` навешиваются на сам `ListItemContent`, поэтому фоном
+управляет один элемент — базовый фон приходит из `.listItemContent`, а hover-фон
+из `.listActionItem:hover` на том же узле. Нет перекрытия фона между обёрткой и
+контентом.
+
+Используй `ListActionItem` когда: строка целиком кликабельна (навигация, открытие
+деталей, выбор из списка без чекбокса). Не используй внутри `ListTableItem` —
+там `onClickItem` вешается напрямую на `ListItemContent` без hover/focus/keyboard.
+
+Распределение пропсов:
+
+- **собственные пропсы `ListActionItem`** (`extends React.LiHTMLAttributes<HTMLLIElement>`)
+  уходят на корневой `<li>` (`ListItem`) — `className`, `style`, `id`, `data-*` строки;
+- **`listItemContentProps`** — на интерактивный `ListItemContent`: `onClick`,
+  `onKeyDown`, переопределение `role` / `tabIndex`, `className` контента и т.д.
+
+Типичная композиция:
+
+```tsx
+<List>
+    <ListActionItem listItemContentProps={{ onClick: handleClick }}>Текст строки</ListActionItem>
+</List>
+```
+
+---
+
+## Варианты и props
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Содержимое строки (рендерится внутри `ListItemContent`) |
+| `listItemContentProps` | `React.HTMLAttributes<HTMLDivElement>` | — | Пропсы интерактивного слоя (`ListItemContent`): `onClick`, `onKeyDown`, `role`, `tabIndex`, `className` контента и т.д. |
+| `className` | `string` | — | CSS-класс корневого `<li>` (`ListItem`) |
+| `...HTMLLIAttributes` | — | — | Остальные атрибуты `<li>` спредятся на внутренний `ListItem` |
+
+### Пропсы внутри `listItemContentProps`
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `onClick` | `(event: React.MouseEvent<HTMLDivElement>) => void` | — | Обработчик клика по всей строке |
+| `onKeyDown` | `(event: React.KeyboardEvent<HTMLDivElement>) => void` | — | Вызывается до внутренней обработки Enter/Space |
+| `className` | `string` | — | Дополнительный CSS-класс, мержится с `styles.listActionItem` на `ListItemContent` |
+| `tabIndex` | `number` | `0` | Фокусируемость по Tab. Можно переопределить (например, `-1`) |
+| `role` | `string` | `"button"` | ARIA-роль. Можно переопределить (например, `"link"`) |
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-ListItem-Background_Hover    // фон при hover (desktop)
+--triplex-next-ListItem-BorderColor_Focus   // цвет focus-обводки (:focus-visible)
+```
+
+Класс `styles.listActionItem` навешивается на сам `ListItemContent`, поэтому весь
+фон живёт на одном элементе: базовый фон и `selected`/`selectable` — из
+`.listItemContent`, а hover-фон (`&:hover`) и focus-обводка (`&:focus-visible`) —
+из `.listActionItem` на том же узле.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLDivElement` (внутренний
+  `ListItemContent`). Не убирать.
+- **Самодостаточная композиция** — компонент сам рендерит `ListItem` →
+  `ListItemContent` (как `ListSortableItem` рендерит `ListItem`). Использовать
+  прямо внутри `List`, не оборачивать вручную в `ListItem`/`ListItemContent`.
+- **Интерактивность на `ListItemContent`** — `role`, `tabIndex`, обработчики и
+  класс `styles.listActionItem` навешиваются на сам `ListItemContent`, а не на
+  отдельную обёртку. Это то, что позволяет одному элементу управлять фоном. Не
+  вводить промежуточный `<div>` между `ListItemContent` и hover-фоном — вернётся
+  перекрытие слоёв.
+- **Разделение пропсов** — собственные пропсы компонента (`extends
+  LiHTMLAttributes`) идут на корневой `ListItem` (`<li>`), интерактивные — только
+  через `listItemContentProps` на `ListItemContent`. Не спредить `...rest` на
+  `ListItemContent`: тогда пропсы `<li>` и контента снова смешаются.
+- **`role="button"` и `tabIndex={0}`** — задаются по умолчанию, но переопределяются
+  через `listItemContentProps` (`{...restListItemContentProps}` идёт после дефолтов). Не
+  убирать дефолты без обновления тестов и a11y-контракта.
+- **Клавиатура** — Enter и Space обрабатываются через `isKey` из
+  `@sberbusiness/triplex-next/utils/keyboard`; Space вызывает `preventDefault()`,
+  затем `event.currentTarget.click()`. Не заменять на прямое сравнение `event.key`.
+- **`data-tx`** — атрибут версии пакета, не убирать.
+
+---
+
+## Accessibility
+
+- Элемент объявлен как `role="button"` и попадает в tab-order (`tabIndex={0}`).
+- Активация: клик мышью, Enter, Space (через программный `click()`).
+- Focus-индикатор — `border-color` на `:focus-visible`, `outline: none`.
+- **`onKeyDown` вызывается до** внутренней обработки Enter/Space.
+- **Не вкладывай другие интерактивные элементы** (кнопки, ссылки, чекбоксы) внутрь
+  `ListActionItem` — получится nested interactive elements. Для выбора с чекбоксом
+  используй `ListItemSelectable` без `ListActionItem`; для клика по всей строке в
+  табличном списке — `ListTableItem` + `onClickItem`.
+- Для навигации по ссылке предпочтительнее нативный `<a>` / роутер-линк, а не
+  `ListActionItem` с `role="link"` — компонент не даёт семантики ссылки из коробки.
+
+---
+
+## Связанные компоненты
+
+- `ListItem` — `<li>`, который `ListActionItem` рендерит сам внутри себя.
+- `ListItemContent` — слой с фоном и padding, который `ListActionItem` рендерит
+  сам и на который навешивает интерактивность. Именно он держит весь фон.
+- `ListSortableItem` — образец паттерна: тоже самодостаточный компонент, рендерит
+  `ListItem` внутри себя.
+- `ListItemSelectable` — альтернатива для multi-select с чекбоксом. Не комбинировать
+  с `ListActionItem` в одной строке без явной a11y-стратегии.
+- `ListTableItem` — использует `onClickItem` на `ListItemContent`, не `ListActionItem`.
+- `CardAction` — аналогичный паттерн интерактивной обёртки в семействе Card.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItem.stories.tsx`
+Файл примера: `stories/List/examples/ListItem/Action.tsx`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Action` | `Action.tsx` | `ListActionItem` напрямую внутри `List` |
+| `WithActionItems` (в `List.stories.tsx`) | `examples/List/WithActionItems.tsx` | Список из нескольких кликабельных строк `ListActionItem` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-07-17 | Добавлена story `WithActionItems` в `List.stories.tsx` — список из нескольких `ListActionItem`. |
+| 2026-07-16 | Создан компонент `ListActionItem` — самодостаточная интерактивная строка (hover, focus по Tab, `onClick` + Enter/Space). Сам рендерит `ListItem` + `ListItemContent`; интерактивность и весь фон живут на одном `ListItemContent`. Пропсы разделены: собственные — на `<li>`, интерактивные — через `listItemContentProps`. |