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

package/bundle/components/ListItemTable.md

@@ -0,0 +1,390 @@
+---
+component: ListItemTable
+category: List
+related: [ListItem, ListItemSelectable, ListItemControls, ListItemControlsButton, SwipeableArea]
+tokens:
+  - --triplex-next-ListItem-Background
+  - --triplex-next-ListItem-Background_Selected
+stories: stories/List/ListItemTable.stories.tsx
+version: "1.0"
+---
+
+# ListItemTable
+
+## Назначение
+
+Высокоуровневая обёртка `<li>` для табличных строк. Объединяет `ListItem` +
+`SwipeableArea` + опциональный `ListItemSelectable`. Автоматически рисует
+правый «хвост» (`ListItemTailRight`) и контейнер для swipe-actions
+(`ListItemControls`).
+
+Используй `ListItemTable` когда: нужна готовая строка с поддержкой swipe и
+выбора. Не нужен — собирай руками из `ListItem` + `ListItemContent` +
+`SwipeableArea` + `ListItemSelectable`.
+
+---
+
+## Варианты и props
+
+`ListItemTable` имеет **discriminated union** API: либо без выбора (`onSelect`/`selected` запрещены типом), либо selectable (оба обязательны).
+
+### Общие опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `controlButtons` | `React.ReactNode` | — | Кнопки действий, оборачиваются в `<ListItemControls>` и подключаются как `rightSwipeableArea` у `SwipeableArea` |
+| `onClickItem` | `(event: React.MouseEvent<HTMLDivElement>) => void` | — | Передаётся как `onClick` на контейнер контента (`ListItemContent`). Не вызывается при клике на чекбокс или swipe-actions |
+| `swipeableAreaRef` | `React.Ref<ISwipeableAreaRef>` | — | Ref на внутренний `SwipeableArea` (для программного открытия/закрытия swipe-области, например в `WithSwipeEmulation`-сторе) |
+| `children` | `React.ReactNode` | — | Содержимое строки (рендерится внутри `ListItemContent`) |
+
+### Selectable-вариант (оба prop'а обязательны вместе)
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `selected` | `boolean` | Состояние «выбран» — управляется снаружи |
+| `onSelect` | `(selected: boolean) => void` | Вызывается при изменении состояния чекбокса |
+
+В non-selectable варианте оба prop'а имеют тип `never` — TypeScript запрещает их передачу.
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-ListItem-Background          // фон строки
+--triplex-next-ListItem-Background_Selected // фон выбранной строки (через ListItemSelectable + ListItemContent)
+```
+
+Применяются в подкомпонентах `ListItemContent`/`ListItemSelectable`. Сам
+`ListItemTable.module.less` задаёт только `margin-bottom: 4px` и
+`border-radius: 8px` для `swipeableArea`.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, target — `HTMLLIElement`. Не убирать.
+- **Discriminated union** `IListItemTableProps | IListItemTableSelectableProps` — selectable определяется наличием **обоих** prop'ов `onSelect` и `selected`. Не делай частичную проверку.
+- **Корневой элемент `<li>`** — не менять.
+- **`SwipeableArea`** всегда оборачивает контент, даже без `controlButtons` — нужно для свайп-жестов на мобильных.
+
+---
+
+## Связанные компоненты
+
+- `ListItem` — базовый `<li>`, используется внутри.
+- `ListItemContent` — контейнер контента, получает `onClick = onClickItem`.
+- `ListItemSelectable` — добавляется автоматически, если переданы `selected` + `onSelect`.
+- `ListItemControls` — обёртка для `controlButtons`, подключается как `rightSwipeableArea`.
+- `ListItemTailRight` — декоративный «хвост» в правой части (всегда отрисовывается).
+- `SwipeableArea` — внешняя зависимость, обеспечивает swipe-жесты.
+
+---
+
+## Stories
+
+Основные истории: `stories/List/ListItemTable.stories.tsx`
+Файлы примеров: `stories/List/examples/ListItemTable/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль |
+| `Default` | `Default.tsx` | Базовая табличная строка с `controlButtons` |
+| `Selectable` | `Selectable.tsx` | Selectable-вариант с чекбоксом |
+| `WithSwipeEmulation` | `WithSwipeEmulation.tsx` | Программное управление swipe через `swipeableAreaRef` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-29 | Создан документ |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/List/examples/ListItemTable/Default.tsx`
+
+```tsx
+import React from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFontWeightText,
+    EMarkerStatus,
+    ETextSize,
+    List,
+    ListItemControlsButton,
+    ListItemControlsButtonDropdown,
+    ListItemTable,
+    MarkerStatus,
+    Text,
+} from "@sberbusiness/triplex-next";
+import { AttachmentStrokeSrvIcon20, DotshorizontalStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const Default = () => {
+    const options = [
+        {
+            id: "button-dropdown-card-option-1",
+            label: "Текст пункта меню 1",
+            onSelect: () => {},
+        },
+        {
+            id: "button-dropdown-card-option-2",
+            label: "Текст пункта меню 2",
+            onSelect: () => {},
+        },
+        {
+            id: "button-dropdown-card-option-3",
+            label: "Текст пункта меню 3",
+            onSelect: () => {},
+        },
+    ];
+
+    return (
+        <div style={{ maxWidth: "500px" }}>
+            <List>
+                <ListItemTable
+                    onClickItem={() => {}}
+                    controlButtons={
+                        <>
+                            <ListItemControlsButton icon={<AttachmentStrokeSrvIcon20 paletteIndex={5} />}>
+                                Скачать
+                            </ListItemControlsButton>
+                            <ListItemControlsButtonDropdown
+                                icon={<DotshorizontalStrokeSrvIcon20 paletteIndex={5} />}
+                                options={options}
+                            >
+                                Действия
+                            </ListItemControlsButtonDropdown>
+                        </>
+                    }
+                >
+                    <Text size={ETextSize.B2} weight={EFontWeightText.SEMIBOLD}>
+                        1 220 000 000 RUB
+                    </Text>
+
+                    <Text size={ETextSize.B3} tag="div">
+                        №1 ООО Голубая Роза Голубая
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div">
+                        Длинное назначение платежа
+                    </Text>
+                    <Text size={ETextSize.B3} type={EFontType.SECONDARY} tag="div">
+                        НДС не облагается
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div" type={EFontType.SECONDARY}>
+                        40702 810 2 0527 5000000 от 09.04.24
+                    </Text>
+                    <MarkerStatus status={EMarkerStatus.SUCCESS} size={EComponentSize.LG}>
+                        Status text
+                    </MarkerStatus>
+                </ListItemTable>
+            </List>
+        </div>
+    );
+};
+```
+
+### Selectable
+
+`stories/List/examples/ListItemTable/Selectable.tsx`
+
+```tsx
+import React from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFontWeightText,
+    EMarkerStatus,
+    ETextSize,
+    List,
+    ListItemControlsButton,
+    ListItemControlsButtonDropdown,
+    ListItemTable,
+    MarkerStatus,
+    Text,
+} from "@sberbusiness/triplex-next";
+import { AttachmentStrokeSrvIcon20, DotshorizontalStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const Selectable = () => {
+    const options = [
+        {
+            id: "button-dropdown-card-with-selectable-option-1",
+            label: "Текст пункта меню 1",
+            onSelect: () => alert("Выбран пункт меню 1."),
+        },
+        {
+            id: "button-dropdown-card-with-selectable-option-2",
+            label: "Текст пункта меню 2",
+            onSelect: () => alert("Выбран пункт меню 2."),
+        },
+        {
+            id: "button-dropdown-card-with-selectable-option-3",
+            label: "Текст пункта меню 3",
+            onSelect: () => alert("Выбран пункт меню 3."),
+        },
+    ];
+
+    const [selected, setSelected] = React.useState(false);
+
+    return (
+        <div style={{ maxWidth: "500px" }}>
+            <List>
+                <ListItemTable
+                    selected={selected}
+                    onSelect={setSelected}
+                    onClickItem={() => console.log("Клик по карточке.")}
+                    controlButtons={
+                        <>
+                            <ListItemControlsButton icon={<AttachmentStrokeSrvIcon20 paletteIndex={5} />}>
+                                Скачать
+                            </ListItemControlsButton>
+                            <ListItemControlsButtonDropdown
+                                icon={<DotshorizontalStrokeSrvIcon20 paletteIndex={5} />}
+                                options={options}
+                            >
+                                Действия
+                            </ListItemControlsButtonDropdown>
+                        </>
+                    }
+                >
+                    <Text size={ETextSize.B2} weight={EFontWeightText.SEMIBOLD}>
+                        1 220 000 000 RUB
+                    </Text>
+
+                    <Text size={ETextSize.B3} tag="div">
+                        №1 ООО Голубая Роза Голубая
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div">
+                        Длинное назначение платежа
+                    </Text>
+                    <Text size={ETextSize.B3} type={EFontType.SECONDARY} tag="div">
+                        НДС не облагается
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div" type={EFontType.SECONDARY}>
+                        40702 810 2 0527 5000000 от 09.04.24
+                    </Text>
+                    <MarkerStatus status={EMarkerStatus.SUCCESS} size={EComponentSize.LG}>
+                        Status text
+                    </MarkerStatus>
+                </ListItemTable>
+            </List>
+        </div>
+    );
+};
+```
+
+### WithSwipeEmulation
+
+`stories/List/examples/ListItemTable/WithSwipeEmulation.tsx`
+
+```tsx
+import React from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFontWeightText,
+    EMarkerStatus,
+    ETextSize,
+    ISwipeableAreaRef,
+    List,
+    ListItemControlsButton,
+    ListItemControlsButtonDropdown,
+    ListItemTable,
+    MarkerStatus,
+    Text,
+} from "@sberbusiness/triplex-next";
+import { AttachmentStrokeSrvIcon20, DotshorizontalStrokeSrvIcon20 } from "@sberbusiness/icons-next";
+
+export const WithSwipeEmulation = () => {
+    const options = [
+        {
+            id: "button-dropdown-swipe-emulation-option-1",
+            label: "Текст пункта меню 1",
+            onSelect: () => alert("Выбран пункт меню 1."),
+        },
+        {
+            id: "button-dropdown-swipe-emulation-card-option-2",
+            label: "Текст пункта меню 2",
+            onSelect: () => alert("Выбран пункт меню 2."),
+        },
+        {
+            id: "button-dropdown-swipe-emulation-card-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>
+                <ListItemTable
+                    swipeableAreaRef={ref}
+                    onClickItem={() => console.log("Клик по карточке.")}
+                    controlButtons={
+                        <>
+                            <ListItemControlsButton icon={<AttachmentStrokeSrvIcon20 paletteIndex={5} />}>
+                                Скачать
+                            </ListItemControlsButton>
+                            <ListItemControlsButtonDropdown
+                                icon={<DotshorizontalStrokeSrvIcon20 paletteIndex={5} />}
+                                options={options}
+                            >
+                                Действия
+                            </ListItemControlsButtonDropdown>
+                        </>
+                    }
+                >
+                    <Text size={ETextSize.B2} weight={EFontWeightText.SEMIBOLD}>
+                        1 220 000 000 RUB
+                    </Text>
+
+                    <Text size={ETextSize.B3} tag="div">
+                        №1 ООО Голубая Роза Голубая
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div">
+                        Длинное назначение платежа
+                    </Text>
+                    <Text size={ETextSize.B3} type={EFontType.SECONDARY} tag="div">
+                        НДС не облагается
+                    </Text>
+                    <Text size={ETextSize.B3} tag="div" type={EFontType.SECONDARY}>
+                        40702 810 2 0527 5000000 от 09.04.24
+                    </Text>
+                    <MarkerStatus status={EMarkerStatus.SUCCESS} size={EComponentSize.LG}>
+                        Status text
+                    </MarkerStatus>
+                </ListItemTable>
+            </List>
+        </div>
+    );
+};
+```
+