@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.46.0-beta

package/bundle/components/MasterTable.md

@@ -0,0 +1,602 @@
+---
+component: MasterTable
+category: Table
+related:
+  - TableBasic
+  - Pagination
+tokens: []
+stories: stories/MasterTable/MasterTable.stories.tsx
+version: "1.0"
+---
+
+# MasterTable
+
+## Назначение
+
+Контейнер таблицы. Сам рисует только позиционирующую обёртку (`<div>` с `position: relative`), а его настоящая работа — собрать вокруг таблицы панели (фильтры, чипы, настройки колонок, подвал, пагинацию) и раздать им общее состояние через `MasterTableContext`: признак загрузки и текущую структуру колонок.
+
+Используй когда: строишь табличный экран из нескольких частей — над таблицей фильтры, под ней подвал с массовыми действиями и пагинация, а состояние загрузки должно синхронно блокировать всё это.
+
+Не используй когда: нужна только таблица без обвязки — тогда достаточно `TableBasic` (он работает и вне `MasterTable`, читая значения контекста по умолчанию). Для простых списков без колонок бери `List`.
+
+---
+
+## Варианты и props
+
+`MasterTable` — контейнер, а не управляющий компонент: он не хранит данные, страницы и фильтры. Единственное собственное состояние — массив колонок, который в него записывает `MasterTable.TableBasic`.
+
+### Props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `loading` | `boolean` | `false` | Состояние загрузки. Не рисуется на самом контейнере, а раздаётся потомкам через контекст. |
+| `children` | `React.ReactNode` | — | Панели и таблица. Порядок в разметке = порядок на экране, компонент ничего не переставляет. |
+| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Прокидывается на корневой `<div>`. `className` объединяется с собственным классом. |
+
+Интерфейс props — `IMasterTableProps` в `src/components/Table/TableBasic/types.ts` (там же живут интерфейсы остальных частей семейства).
+
+### Статические субкомпоненты
+
+Публичный API строится через статические свойства. Те же компоненты доступны и напрямую из barrel `src/components/Table/index.ts` — статики нужны для читаемой композиции.
+
+| Субкомпонент | Роль |
+|---|---|
+| `MasterTable.FilterPanel` | Панель под элементы фильтрации над таблицей. |
+| `MasterTable.ChipPanel` | Панель чипов активных фильтров; `.Links` — блок ссылок справа. |
+| `MasterTable.TableBasicSettings` | Выпадающие настройки таблицы (видимость и порядок колонок). |
+| `MasterTable.TableBasic` | Сама таблица. |
+| `MasterTable.NoColumns` | Заглушка для случая, когда пользователь скрыл все колонки. |
+| `MasterTable.TableFooter` | Подвал: `.Summary` (подытоги, выбор всех) и `.Controls` (кнопки). |
+| `MasterTable.PaginationPanel` | Панель под пагинацию. |
+
+### Что раздаёт контекст
+
+`MasterTableContext` (`src/components/Table/MasterTableContext.ts`) — единственный канал связи между частями:
+
+| Поле | Кто пишет | Кто читает |
+|---|---|---|
+| `loading` | `MasterTable` из props | `TableBasic` — лоадер поверх таблицы; `PaginationNavigationButton`, `PaginationPageButton`, `PaginationSelect` — блокировка элементов пагинации |
+| `columns` | `TableBasic` в `useEffect`, из своего props `columns` | `ColumnSettings` — список колонок для настройки видимости |
+| `setColumns` | — | `TableBasic` |
+
+Из этого следует неочевидное: `ColumnSettings` показывает колонки, **только если** внутри того же `MasterTable` отрисован `TableBasic` — до его первого эффекта контекст пуст.
+
+---
+
+## Дизайн-токены
+
+Собственных токенов нет. `MasterTable.module.less` задаёт только `position: relative` — контекст позиционирования для лоадера, который `TableBasic` кладёт поверх таблицы. Визуал целиком приходит от вложенных частей (`TableBasic`, `TableFooter`, `Pagination`, `Typography`).
+
+---
+
+## Инварианты
+
+- `forwardRef` на компоненте — не убирать. Ref идёт на корневой `<div>` (`HTMLDivElement`).
+- Все семь статических субкомпонентов (`NoColumns`, `FilterPanel`, `ChipPanel`, `TableBasic`, `TableBasicSettings`, `TableFooter`, `PaginationPanel`) — часть публичного API. Ни переименовывать, ни удалять, ни менять их набор.
+- `displayName` — `"MasterTable"`.
+- Корневой элемент — `<div>`. `data-tx` выставляется **после** спреда `...rest`, поэтому потребитель не может его переопределить — это осознанное поведение, общее для семейства (`FilterPanel`, `PaginationPanel`).
+- Все обёртки семейства (`FilterPanel`, `ChipPanel`, `ChipPanelLinks`, `NoColumns`, `PaginationPanel`, `TableFooter`, `TableBasicSettings`) пробрасывают `ref` на свой корневой элемент — не убирать. У составных (`ChipPanel`, `TableFooter`, `TableBasicSettings`) статики объявлены через `Object.assign` с явным интерфейсом: при добавлении или удалении статики интерфейс нужно править синхронно, иначе TypeScript промолчит.
+- Собственный класс `styles.masterTable` объединяется с пользовательским `className` через `clsx`, а не затирается им.
+- Значение контекста мемоизировано (`useMemo` по `columns` и `loading`) — не откатывать: возврат к новому объекту на каждый рендер снова заставит `useEffect` в `TableBasic` перезапускаться на каждый рендер контейнера.
+- Колонки потребитель обязан заменять иммутабельно (`map`/спред, а не мутация на месте): эффект в `TableBasic` сравнивает `isEqual(columns, context.columns)`, а после первой синхронизации в контексте лежит **та же ссылка**, что пришла в props, — поэтому мутация на месте до `ColumnSettings` не доходит. К мемоизации это отношения не имеет, ограничение существовало и до неё; откат `useMemo` мутации не «починит».
+- Статики перечислены в `IMasterTableStatics` вручную. Явная аннотация типа снимает проверку лишних свойств у `Object.assign`, поэтому набор в интерфейсе и в `Object.assign` правится синхронно — иначе новая статика не попадёт в публичный тип.
+- `IMasterTableProps` объявлен в `src/components/Table/TableBasic/types.ts`, а не рядом с компонентом. Расположение историческое; перенос — breaking change для тех, кто импортирует тип по глубокому пути.
+- Компонент React 17-совместим: никакого `useId`/`useSyncExternalStore` — код синхронизируется в ветку `release-0`.
+
+---
+
+## Accessibility
+
+Собственной семантики контейнер не добавляет: это `<div>` без роли, вся доступность живёт в частях (таблица — `<table>` с заголовками, пагинация — `<nav>` со списком, настройки — `aria-haspopup`/`aria-expanded` на ссылке-триггере).
+
+Что важно для потребителя:
+
+- `loading` — визуальное и функциональное состояние, но не объявляемое: скринридер о начале загрузки не узнает. Если это критично, добавь свой `aria-live`-регион рядом с таблицей.
+- Роль и подпись контейнера (`role`, `aria-label`) не хардкодятся — библиотека мультиязычная, передавай их сам через `...rest`, если экран того требует.
+
+---
+
+## Связанные компоненты
+
+- `TableBasic` — сама таблица; единственная часть, которая пишет в контекст (`columns`). Работает и вне `MasterTable`, но тогда `loading` всегда `false`.
+- `Pagination` — обычно кладётся в `MasterTable.PaginationPanel`. Её кнопки и селект читают `MasterTableContext.loading` и блокируются в загрузке; это опора на деталь `MasterTable`, поэтому связь зафиксирована с обеих сторон.
+- `FilterPanel`, `ChipPanel` (`.Links`), `PaginationPanel`, `NoColumns` — тривиальные обёртки: `clsx(className)` + спред + собственный класс, без своей логики. Отличаются только стилями и тем, что `FilterPanel` и `PaginationPanel` выставляют `data-tx`. Все пробрасывают `ref` на свой корневой `<div>`; отдельных строк в `docs/ai/ROADMAP.md` у них нет — состояние учитывается здесь.
+- `TableFooter` — подвал поверх `FooterDescription`; `.Summary` даёт `.SelectedCount`, `.SelectAllButton` и `.Amount`, `.Controls` — это `FooterDescriptionControls` из семейства `Footer`.
+- `TableBasicSettings` — выпадающие настройки поверх `ButtonDropdownExtended`; внутри `ColumnSettings` читает `columns` из контекста и поддерживает children-функцию `({ columns }) => ...`. Его `ref` идёт на корневой `<div>`, который рисует `ButtonDropdownExtended`, — поэтому `forwardRef` пришлось добавить и туда.
+
+---
+
+## Stories
+
+Основные истории: `stories/MasterTable/MasterTable.stories.tsx`
+Файлы примеров: `stories/MasterTable/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `loading` и набора панелей (фильтры, подвал, пагинация, пустая таблица) |
+| `Default` | `Default.tsx` | Минимальная композиция: контейнер + `MasterTable.TableBasic` |
+| `Loading` | `Loading.tsx` | `loading` — лоадер поверх заполненной таблицы |
+| `NoData` | `NoData.tsx` | Пустой `data` — таблица показывает `renderNoData` |
+| `NoColumns` | `NoColumns.tsx` | Все колонки с `hidden` — таблица показывает `renderNoColumns` с `MasterTable.NoColumns` |
+| `Example` | `Example.tsx` | Production-like композиция: фильтры, настройки колонок, сортировка, выбор строк, подвал с подытогом, пагинация |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: загрузка поверх пустой таблицы, выделенная строка, пагинация, заблокированная загрузкой |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-31 | Обёртки семейства (`FilterPanel`, `ChipPanel` + `.Links`, `NoColumns`, `PaginationPanel`, `TableFooter`, `TableBasicSettings`) переведены с `React.FC` на `forwardRef`, у составных статики — через `Object.assign`. Добавлены smoke-тесты на каждую. Ради `TableBasicSettings` `forwardRef` добавлен и в `ButtonDropdownExtended`. Набор props и DOM не изменились. |
+| 2026-08-27 | Создан документ. Компонент переведён с `React.FC` на `Object.assign(forwardRef(...), {...})` — теперь пробрасывает `ref` на корневой `<div>`; значение контекста мемоизировано. Публичный API не изменился. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/MasterTable/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { EHorizontalAlign, ITableBasicColumn, ITableBasicRow, MasterTable } from "@sberbusiness/triplex-next";
+
+const columns: ITableBasicColumn[] = [
+    { fieldKey: "docNumber", label: "Номер", width: "15%" },
+    { fieldKey: "recipient", label: "Получатель", width: "45%" },
+    { fieldKey: "status", label: "Статус", width: "20%" },
+    { fieldKey: "sum", label: "Сумма", width: "20%", horizontalAlign: EHorizontalAlign.RIGHT },
+];
+
+const data: ITableBasicRow[] = [
+    {
+        rowKey: "1350",
+        rowData: { docNumber: "1350", recipient: "ООО Ромашка", status: "Создан", sum: "12 500,00 ₽" },
+    },
+    {
+        rowKey: "1351",
+        rowData: { docNumber: "1351", recipient: "ИП Иванов Иван Иванович", status: "Подписан", sum: "8 300,00 ₽" },
+    },
+    {
+        rowKey: "1352",
+        rowData: { docNumber: "1352", recipient: "ООО Василёк", status: "Оплачен", sum: "145 000,00 ₽" },
+    },
+];
+
+export const Default = () => (
+    <MasterTable>
+        <MasterTable.TableBasic columns={columns} data={data} renderNoData={() => <div>Нет данных</div>} />
+    </MasterTable>
+);
+```
+
+### Loading
+
+`stories/MasterTable/examples/Loading.tsx`
+
+```tsx
+import React from "react";
+import { EHorizontalAlign, ITableBasicColumn, ITableBasicRow, MasterTable } from "@sberbusiness/triplex-next";
+
+const columns: ITableBasicColumn[] = [
+    { fieldKey: "docNumber", label: "Номер", width: "15%" },
+    { fieldKey: "recipient", label: "Получатель", width: "45%" },
+    { fieldKey: "status", label: "Статус", width: "20%" },
+    { fieldKey: "sum", label: "Сумма", width: "20%", horizontalAlign: EHorizontalAlign.RIGHT },
+];
+
+const data: ITableBasicRow[] = [
+    {
+        rowKey: "1350",
+        rowData: { docNumber: "1350", recipient: "ООО Ромашка", status: "Создан", sum: "12 500,00 ₽" },
+    },
+    {
+        rowKey: "1351",
+        rowData: { docNumber: "1351", recipient: "ИП Иванов Иван Иванович", status: "Подписан", sum: "8 300,00 ₽" },
+    },
+    {
+        rowKey: "1352",
+        rowData: { docNumber: "1352", recipient: "ООО Василёк", status: "Оплачен", sum: "145 000,00 ₽" },
+    },
+];
+
+/**
+ * Свойство loading раздаётся дочерним компонентам через MasterTableContext:
+ * таблица закрывается лоадером.
+ */
+export const Loading = () => (
+    <MasterTable loading>
+        <MasterTable.TableBasic columns={columns} data={data} renderNoData={() => <div>Нет данных</div>} />
+    </MasterTable>
+);
+```
+
+### NoData
+
+`stories/MasterTable/examples/NoData.tsx`
+
+```tsx
+import React from "react";
+import { EmptytableSysIcon96 } from "@sberbusiness/icons-next";
+import {
+    EComponentSize,
+    EFontType,
+    EFontWeightTitle,
+    EHorizontalAlign,
+    ETextSize,
+    ETitleSize,
+    Button,
+    EButtonTheme,
+    Gap,
+    ITableBasicColumn,
+    MasterTable,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+const columns: ITableBasicColumn[] = [
+    { fieldKey: "docNumber", label: "Номер", width: "15%" },
+    { fieldKey: "recipient", label: "Получатель", width: "45%" },
+    { fieldKey: "status", label: "Статус", width: "20%" },
+    { fieldKey: "sum", label: "Сумма", width: "20%", horizontalAlign: EHorizontalAlign.RIGHT },
+];
+
+/** Заглушка, которую таблица показывает вместо строк, когда data пустой. */
+const renderNoData = () => (
+    <>
+        <EmptytableSysIcon96 />
+        <Gap size={8} />
+        <Title size={ETitleSize.H3} weight={EFontWeightTitle.REGULAR}>
+            Здесь пока пусто
+        </Title>
+        <Gap size={12} />
+        <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+            Создайте первый документ, и он появится в таблице.
+        </Text>
+        <Gap size={24} />
+        <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+            Создать документ
+        </Button>
+    </>
+);
+
+export const NoData = () => (
+    <MasterTable>
+        <MasterTable.TableBasic columns={columns} data={[]} renderNoData={renderNoData} />
+    </MasterTable>
+);
+```
+
+### NoColumns
+
+`stories/MasterTable/examples/NoColumns.tsx`
+
+```tsx
+import React from "react";
+import {
+    EComponentSize,
+    EFontType,
+    EFontWeightTitle,
+    EHorizontalAlign,
+    ETextSize,
+    ETitleSize,
+    Button,
+    EButtonTheme,
+    Gap,
+    ITableBasicColumn,
+    ITableBasicRow,
+    MasterTable,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+/** Все колонки скрыты — пользователь снял их в настройках таблицы. */
+const columns: ITableBasicColumn[] = [
+    { fieldKey: "docNumber", label: "Номер", width: "15%", hidden: true },
+    { fieldKey: "recipient", label: "Получатель", width: "45%", hidden: true },
+    { fieldKey: "status", label: "Статус", width: "20%", hidden: true },
+    { fieldKey: "sum", label: "Сумма", width: "20%", horizontalAlign: EHorizontalAlign.RIGHT, hidden: true },
+];
+
+const data: ITableBasicRow[] = [
+    {
+        rowKey: "1350",
+        rowData: { docNumber: "1350", recipient: "ООО Ромашка", status: "Создан", sum: "12 500,00 ₽" },
+    },
+    {
+        rowKey: "1351",
+        rowData: { docNumber: "1351", recipient: "ИП Иванов Иван Иванович", status: "Подписан", sum: "8 300,00 ₽" },
+    },
+];
+
+/** Заглушка, которую таблица показывает вместо разметки, когда каждая колонка имеет hidden. */
+const renderNoColumns = () => (
+    <MasterTable.NoColumns>
+        <Title size={ETitleSize.H3} weight={EFontWeightTitle.REGULAR}>
+            Все колонки таблицы скрыты
+        </Title>
+        <Gap size={12} />
+        <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+            Выберите нужные вам для отображения колонки в настройках таблицы.
+        </Text>
+        <Gap size={24} />
+        <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+            Сбросить настройки
+        </Button>
+    </MasterTable.NoColumns>
+);
+
+export const NoColumns = () => (
+    <MasterTable>
+        <MasterTable.TableBasic
+            columns={columns}
+            data={data}
+            renderNoColumns={renderNoColumns}
+            renderNoData={() => <div>Нет данных</div>}
+        />
+    </MasterTable>
+);
+```
+
+### Example
+
+`stories/MasterTable/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { EmptytableSysIcon96 } from "@sberbusiness/icons-next";
+import {
+    Amount,
+    Button,
+    Checkbox,
+    ColumnSettings,
+    ECellType,
+    EButtonTheme,
+    EComponentSize,
+    EFontType,
+    EFontWeightTitle,
+    EHorizontalAlign,
+    EOrderDirection,
+    ETextSize,
+    ETitleSize,
+    Gap,
+    ISelectFieldOption,
+    ISortOrder,
+    ITableBasicColumn,
+    ITableBasicRow,
+    MasterTable,
+    Pagination,
+    Text,
+    TextField,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+/** Документы таблицы. Данные захардкожены, чтобы пример был воспроизводимым. */
+const DOCUMENTS = [
+    { docNumber: "1350", recipient: "ООО Ромашка", status: "Создан", sum: "12500.00" },
+    { docNumber: "1351", recipient: "ИП Иванов Иван Иванович", status: "Подписан", sum: "8300.00" },
+    { docNumber: "1352", recipient: "ООО Василёк", status: "Оплачен", sum: "145000.00" },
+    { docNumber: "1353", recipient: "ООО Ромашка", status: "Создан", sum: "3200.00" },
+];
+
+const PAGE_SIZE_OPTIONS: ISelectFieldOption[] = [
+    { id: "2", value: "2", label: "2" },
+    { id: "4", value: "4", label: "4" },
+];
+
+const INITIAL_COLUMNS: ITableBasicColumn[] = [
+    { fieldKey: "selection", label: "", width: "48px", cellType: ECellType.CHECKBOX },
+    { fieldKey: "docNumber", label: "Номер", width: "15%", orderDirection: EOrderDirection.NONE },
+    { fieldKey: "recipient", label: "Получатель", width: "40%" },
+    { fieldKey: "status", label: "Статус", width: "20%" },
+    {
+        fieldKey: "sum",
+        label: "Сумма",
+        width: "20%",
+        horizontalAlign: EHorizontalAlign.RIGHT,
+        orderDirection: EOrderDirection.NONE,
+        renderCell: (value) => <Amount value={String(value)} currency="RUB" />,
+    },
+];
+
+const renderNoData = () => (
+    <>
+        <EmptytableSysIcon96 />
+        <Gap size={8} />
+        <Title size={ETitleSize.H3} weight={EFontWeightTitle.REGULAR}>
+            Здесь пока пусто
+        </Title>
+        <Gap size={12} />
+        <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+            Измените параметры фильтрации, чтобы увидеть документы.
+        </Text>
+    </>
+);
+
+export const Example = () => {
+    const [columns, setColumns] = useState<ITableBasicColumn[]>(INITIAL_COLUMNS);
+    const [selectedKeys, setSelectedKeys] = useState<string[]>(["1351"]);
+    const [settingsOpened, setSettingsOpened] = useState(false);
+    const [recipientFilter, setRecipientFilter] = useState("");
+    const [sortOrder, setSortOrder] = useState<ISortOrder | null>(null);
+    const [pageSize, setPageSize] = useState(PAGE_SIZE_OPTIONS[1]);
+    const [currentPage, setCurrentPage] = useState(1);
+
+    const toggleRow = (rowKey: string) =>
+        setSelectedKeys((keys) => (keys.includes(rowKey) ? keys.filter((key) => key !== rowKey) : [...keys, rowKey]));
+
+    const toggleColumn = (fieldKey: string, visible: boolean) =>
+        setColumns((current) =>
+            current.map((column) => (column.fieldKey === fieldKey ? { ...column, hidden: !visible } : column)),
+        );
+
+    const handleOrderBy = ({ fieldKey, direction }: ISortOrder) => {
+        setSortOrder(direction === EOrderDirection.NONE ? null : { fieldKey, direction });
+        setCurrentPage(1);
+        setColumns((current) =>
+            current.map((column) =>
+                column.fieldKey === fieldKey
+                    ? { ...column, orderDirection: direction }
+                    : { ...column, orderDirection: column.orderDirection ? EOrderDirection.NONE : undefined },
+            ),
+        );
+    };
+
+    const handlePageSizeChange = (option: ISelectFieldOption) => {
+        setPageSize(option);
+        setCurrentPage(1);
+    };
+
+    const handleFilterChange = (value: string) => {
+        setRecipientFilter(value);
+        setCurrentPage(1);
+    };
+
+    // Фильтрация, сортировка и постраничная нарезка — работа потребителя: таблица только отображает то, что ей передали.
+    const filtered = DOCUMENTS.filter((document) =>
+        document.recipient.toLowerCase().includes(recipientFilter.trim().toLowerCase()),
+    );
+
+    const sorted = sortOrder
+        ? [...filtered].sort((left, right) => {
+              const comparison = String(left[sortOrder.fieldKey as keyof typeof left]).localeCompare(
+                  String(right[sortOrder.fieldKey as keyof typeof right]),
+                  "ru",
+                  { numeric: true },
+              );
+
+              return sortOrder.direction === EOrderDirection.DESC ? -comparison : comparison;
+          })
+        : filtered;
+
+    const selectedSum = DOCUMENTS.filter((document) => selectedKeys.includes(document.docNumber))
+        .reduce((total, document) => total + Number(document.sum), 0)
+        .toFixed(2);
+
+    const rowsPerPage = Number(pageSize.value);
+    const totalPages = Math.max(1, Math.ceil(sorted.length / rowsPerPage));
+    const pageDocuments = sorted.slice((currentPage - 1) * rowsPerPage, currentPage * rowsPerPage);
+
+    const data: ITableBasicRow[] = pageDocuments.map((document) => ({
+        rowKey: document.docNumber,
+        selected: selectedKeys.includes(document.docNumber),
+        rowData: {
+            ...document,
+            selection: (
+                <Checkbox
+                    checked={selectedKeys.includes(document.docNumber)}
+                    onChange={() => toggleRow(document.docNumber)}
+                    aria-label={`Выбрать документ ${document.docNumber}`}
+                />
+            ),
+        },
+    }));
+
+    return (
+        <MasterTable>
+            <MasterTable.FilterPanel>
+                <TextField
+                    size={EComponentSize.MD}
+                    label="Получатель"
+                    inputProps={{
+                        value: recipientFilter,
+                        onChange: (event: React.ChangeEvent<HTMLInputElement>) =>
+                            handleFilterChange(event.target.value),
+                    }}
+                />
+            </MasterTable.FilterPanel>
+
+            <MasterTable.ChipPanel>
+                <MasterTable.ChipPanel.Links>
+                    <MasterTable.TableBasicSettings
+                        linkTitle={settingsOpened ? "Скрыть настройки" : "Настройки"}
+                        opened={settingsOpened}
+                        setOpened={setSettingsOpened}
+                    >
+                        <MasterTable.TableBasicSettings.Header>Показать столбцы</MasterTable.TableBasicSettings.Header>
+                        <MasterTable.TableBasicSettings.Body>
+                            <ColumnSettings>
+                                {({ columns: contextColumns }) =>
+                                    contextColumns
+                                        .filter((column) => column.fieldKey !== "selection")
+                                        .map((column) => (
+                                            <Checkbox
+                                                key={column.fieldKey}
+                                                checked={column.hidden !== true}
+                                                onChange={(event) =>
+                                                    toggleColumn(column.fieldKey, event.target.checked)
+                                                }
+                                            >
+                                                {column.label}
+                                            </Checkbox>
+                                        ))
+                                }
+                            </ColumnSettings>
+                        </MasterTable.TableBasicSettings.Body>
+                        <MasterTable.TableBasicSettings.Footer>
+                            <Button
+                                theme={EButtonTheme.LINK}
+                                size={EComponentSize.MD}
+                                onClick={() => {
+                                    setColumns(INITIAL_COLUMNS);
+                                    setSortOrder(null);
+                                }}
+                            >
+                                Сбросить настройки
+                            </Button>
+                        </MasterTable.TableBasicSettings.Footer>
+                    </MasterTable.TableBasicSettings>
+                </MasterTable.ChipPanel.Links>
+            </MasterTable.ChipPanel>
+
+            <MasterTable.TableBasic
+                columns={columns}
+                data={data}
+                highlightRowOnHover
+                onOrderBy={handleOrderBy}
+                renderNoData={renderNoData}
+            />
+
+            <MasterTable.TableFooter>
+                <MasterTable.TableFooter.Summary>
+                    <MasterTable.TableFooter.Summary.SelectedCount>
+                        Выбрано {selectedKeys.length} из {DOCUMENTS.length}
+                    </MasterTable.TableFooter.Summary.SelectedCount>
+                    <MasterTable.TableFooter.Summary.SelectAllButton
+                        onClick={() => setSelectedKeys(DOCUMENTS.map((document) => document.docNumber))}
+                    >
+                        Выбрать все
+                    </MasterTable.TableFooter.Summary.SelectAllButton>
+                    <MasterTable.TableFooter.Summary.Amount label="Сумма" sum={selectedSum} currency="RUB" />
+                </MasterTable.TableFooter.Summary>
+                <MasterTable.TableFooter.Controls>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Скачать
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Подписать
+                    </Button>
+                </MasterTable.TableFooter.Controls>
+            </MasterTable.TableFooter>
+
+            <MasterTable.PaginationPanel>
+                <Pagination
+                    paginationSelectProps={{
+                        paginationLabel: "Показывать по",
+                        options: PAGE_SIZE_OPTIONS,
+                        value: pageSize,
+                        onChange: handlePageSizeChange,
+                    }}
+                    paginationNavigationProps={{
+                        currentPage,
+                        totalPages,
+                        onCurrentPageChange: setCurrentPage,
+                    }}
+                />
+            </MasterTable.PaginationPanel>
+        </MasterTable>
+    );
+};
+```
+

package/bundle/components/ModalWindow.md

@@ -3,8 +3,8 @@ component: ModalWindow
 category: ModalWindow
 related: [ModalWindowContent, ModalWindowHeader, ModalWindowBody, ModalWindowFooter, ModalWindowClose, ModalWindowViewManager, Portal, FocusTrap, Page, HeaderPage, FooterPage, Island, LoaderScreen]
 tokens:
-  - --triplex-next-ModalWindow-Backdrop_Background
-  - --triplex-next-ModalWindow-Background
+  - ModalWindow.Backdrop_Background
+  - ModalWindow.Background
 stories: stories/ModalWindow/ModalWindow.stories.tsx
 version: "1.0"
 ---
@@ -53,9 +53,12 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/ModalWindow.ts`.
+
 ```text
---triplex-next-ModalWindow-Backdrop_Background
---triplex-next-ModalWindow-Background
+ModalWindow.Backdrop_Background
+ModalWindow.Background
 ```
 
 Помимо токенов, компонент инжектит и читает несколько runtime CSS-переменных, не относящихся к дизайн-системе:

package/bundle/components/MonthYearField.md

@@ -1,7 +1,7 @@
 ---
 component: MonthYearField
 category: Date components
-related: [DatePickerExtended, MonthYearRange, TextField, Calendar]
+related: [DatePickerExtended, MonthYearRange, ChipMonthYearPicker, TextField, Calendar]
 tokens: []
 stories: stories/MonthYearField/MonthYearField.stories.tsx
 version: "1.0"
@@ -80,6 +80,7 @@ version: "1.0"
 
 - `DatePickerExtended` — родительский компонент выпадающего календаря; `MonthYearField` конфигурирует его в режим `MONTH_YEAR` через render-props.
 - `MonthYearRange` — выбор диапазона месяцев; использует `MonthYearField` как поля «от» и «до».
+- `ChipMonthYearPicker` — тот же выбор месяца в виде чипса-фильтра: наследует `IMonthYearFieldProps` и утилиты `MonthYearPickerUtils`, но вместо поля формы рендерит `Chip`.
 - `TextField` — внутреннее поле-триггер.
 - `MonthYearFieldTarget` (внутренний, не в barrel) — рендерит `TextField` с иконкой календаря и кнопкой очистки, обрабатывает клик/клавиатуру для открытия дропдауна. Описан здесь, отдельного AI.md не имеет.
 - `MonthYearFieldContext` (внутренний, не в barrel) — прокидывает `onChange` в target; тривиальный контекст без своей логики.
@@ -110,6 +111,7 @@ version: "1.0"
 |---|---|
 | 2026-06-16 | Создан документ. AI-рефакторинг (JSDoc-фиксы), unit-тесты для `utils.ts`, story `VisualTests` и включение скриншот-тестов |
 | 2026-06-16 | Добавлена story `VisualTestsOpen` — скриншот раскрытого dropdown с календарём (через `play`) |
+| 2026-09-07 | В «Связанные компоненты» добавлен `ChipMonthYearPicker` — чипс-вариант того же выбора месяца |
 
 ---