@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Suggest.md

@@ -0,0 +1,160 @@
+---
+component: Suggest
+category: Form Controls (base)
+figma-node: ""
+figma-file: ""
+related: [SuggestField, SelectField, Dropdown]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Suggest
+
+## Назначение
+
+Headless-примитив для построения autocomplete/suggest-полей. Управляет
+состоянием `inputValue`, `dropdownOpen`, `activeDescendant`, синхронизацией
+с внешним `value`, обработкой ESC и outside-click. Рендер UI — полностью на
+потребителе через children + Context.
+
+Используй когда: нужен кастомный autocomplete поверх базовой логики.
+Для готового UI-компонента — `SuggestField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Suggest/
+├── Suggest.tsx                       # forwardRef, корень + Provider
+├── SuggestContext.ts
+├── types.ts                          # ISuggestProps, ISuggestOption, ISuggestTargetProps...
+├── useSuggest.ts                     # весь state + колбэки
+├── SuggestMobileDropdownContent.tsx  # mobile-вариант списка
+├── index.ts
+└── styles/
+```
+
+---
+
+## Публичный API
+
+### `Suggest<T extends ISuggestOption>` (forwardRef)
+
+Generic по типу опции. Корневой `<div>` с `onKeyDown` и ref.
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `T \| undefined` | Выбранная опция. |
+| `options` | `T[]` | Список опций. |
+| `size` | `EComponentSize` | Размер (прокидывается детям). |
+| `onSelect` | `(value: T \| undefined) => void` | Колбэк выбора. Вызывается после `closeDropdown`. |
+| `onFilter` | `(value: string) => void` | Колбэк ввода в input. |
+| `onScrollEnd?` | `() => void` | Вызов при скролле до конца списка (пагинация). |
+| `placeholder?` | `string` | Передаётся в Context. |
+| `noOptionsText?` | `string` | Текст «ничего не найдено». |
+| `loading?` | `boolean` | Флаг загрузки корневого уровня. |
+| `dropdownListLoading?` | `boolean` | Флаг загрузки списка (пагинация). |
+| `tooltipOpen?` | `boolean` | Контролируемое открытие Tooltip (в потребителях). |
+| `clearInputOnFocus?` | `boolean` | Очищать input при focus. |
+| `children` | `ReactNode` | Слои UI (Target/Dropdown потребителя). |
+| `...HTMLAttributes<HTMLDivElement>` | — | Прокидываются на корневой div (кроме `onSelect`). |
+
+### `ISuggestOption`
+
+```ts
+{ id: string; label: string; content?: ReactNode; showNotificationIcon?: boolean }
+```
+
+`label` используется как текст в inputValue по умолчанию.
+
+---
+
+## Хук `useSuggest`
+
+Вся логика. Выставляет в контекст:
+- `inputValue`, `setInputValue`
+- `activeDescendant`, `setActiveDescendant`
+- `dropdownOpen`, `setDropdownOpen`
+- `dropdownListId` (уникальный `dropdown-list-<n>`)
+- `closeDropdown(newInputValue?)` — закрытие с восстановлением значения из `latestValueRef`
+- `onSelect` — вызывает `closeDropdown(label)` + `props.onSelect`
+- `onFilter` — вызывает `setInputValue` + `props.onFilter`
+- `onKeyDown` — Escape закрывает dropdown (с `stopPropagation`), остальные — прокидывает в props.onKeyDown.
+
+### Синхронизация value → inputValue
+
+```
+if (value !== prevValue) {
+    setPrevValue(value);
+    setInputValue(value?.label || "");
+}
+```
+
+Синхронизация через «derived state pattern» (сравнение в render'е, не в useEffect).
+
+### `latestValueRef`
+
+`useLayoutEffect` обновляет ref после каждого рендера — чтобы `closeDropdown`
+(создаваемый в useCallback один раз) всегда читал актуальный `value`
+при восстановлении `inputValue`.
+
+---
+
+## Context (`SuggestContext`)
+
+Полное расширение возврата useSuggest + публичные props:
+`value`, `options`, `placeholder`, `noOptionsText`, `loading`, `dropdownListLoading`,
+`tooltipOpen`, `clearInputOnFocus`, `onScrollEnd`, `suggestRef`, `dropdownRef` + state/колбэки из useSuggest.
+
+---
+
+## Поведение outside-click
+
+`useEffect` на `dropdownOpen`: вешает `mousedown`-listener на `document`,
+закрывает dropdown, если клик не попал ни в `suggestRef`, ни в `dropdownRef`.
+
+`dropdownRef` — заполняется потребителем (например, `SuggestField` прокидывает ref на Dropdown-контейнер).
+
+---
+
+## Инварианты
+
+- **`forwardRef<HTMLDivElement>`** + **generic `<T extends ISuggestOption>`** — сохранять оба. Тип результата — кастомный через `as` cast из-за generic'а.
+- **`SuggestContext` — единственный источник состояния** для детей. Не создавать параллельные useState в target/dropdown компонентах потребителя.
+- **ESC закрывает dropdown с `stopPropagation()`** — чтобы не всплывало в `Overlay`/`Modal`.
+- **Синхронизация `value` → `inputValue`** через render-сравнение (`value !== prevValue`). Не переписывать на `useEffect` без обсуждения — появятся «мерцания».
+- **`closeDropdown` использует `latestValueRef`, не `value`** — чтобы closure в listener'ах отдавал актуальное значение.
+- **`dropdownListId` — один на инстанс** (через `uniqueId()` в `useState` initializer).
+- **`onSelect(undefined)`** — допустимо (сбрасывает выбор). Потребитель должен это учесть.
+
+---
+
+## Accessibility
+
+- Компонент не навязывает ARIA — роли (`combobox`, `listbox`, `option`), `aria-controls`, `aria-expanded`, `aria-activedescendant` задаёт потребитель (напр. `SuggestField`).
+- `dropdownListId` доступен через контекст — потребитель должен повесить его на `<ul role="listbox">` и использовать как `aria-controls` на input'е.
+- Escape-handling реализован на корневом div — потребитель не должен дублировать его на input.
+
+---
+
+## Связанные компоненты
+
+- `SuggestField` — готовый UI поверх Suggest.
+- `Dropdown` — используется внутри SuggestField для выпадающего списка.
+- `SelectField` — для статического списка без фильтрации.
+
+---
+
+## Stories
+
+Отдельных stories нет — демонстрируется через `SuggestField`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/SuggestField.md

@@ -0,0 +1,157 @@
+---
+component: SuggestField
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [Suggest, SelectField, Dropdown, TextField, MobileView, FormFieldInput]
+tokens: []
+stories: stories/SuggestField/SuggestField.stories.tsx
+version: "1.0"
+---
+
+# SuggestField
+
+## Назначение
+
+Поле autocomplete: input + dropdown с фильтрацией опций. Адаптивное
+переключение desktop/mobile через `MobileView` — desktop показывает Dropdown,
+mobile — полноэкранный лист с hint. Поддерживает render-функции
+(`renderInput`, `renderDropdown`, `renderDropdownList`, `renderDropdownListItem`)
+для кастомизации.
+
+Используй когда: нужен готовый UX autocomplete-поля с label/tooltip/loading/
+noOptionsText. Для headless-логики — `Suggest` (+ свой UI).
+Для статического dropdown без фильтрации — `SelectField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/SuggestField/
+├── SuggestField.tsx                  # корневой — MobileView switcher
+├── types.ts                          # ISuggestFieldProps, ISuggestFieldOption
+├── desktop/
+│   ├── SuggestFieldDesktop.tsx
+│   ├── SuggestFieldDesktopDropdown.tsx
+│   └── types.ts
+├── mobile/
+│   ├── SuggestFieldMobile.tsx
+│   ├── SuggestFieldMobileDropdown.tsx
+│   ├── SuggestFieldMobileDropdownHint.tsx
+│   └── types.ts
+└── index.ts
+```
+
+**Примечание:** в `SuggestFieldDesktop.tsx` — TODO «переписать через useSuggest».
+Desktop-вариант дублирует логику из `useSuggest` (свой state). Mobile тоже.
+
+---
+
+## Публичный API
+
+### `SuggestField<T extends ISuggestFieldOption>`
+
+Generic. Корневой компонент-switcher.
+
+Props = `Omit<ITextFieldProps, "onSelect"> & DataAttributes` + поля ниже:
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `value` | `T \| undefined` | Выбранная опция. |
+| `options` | `T[]` | Список опций. |
+| `label?` | `string` | Лейбл над полем. |
+| `placeholder?` | `string` | Подсказка в пустом поле. |
+| `tooltipHint` | `string` | Текст Tooltip (обязателен). |
+| `tooltipOpen` | `boolean` | Контроль видимости Tooltip (обязателен). |
+| `loading?` | `boolean` | Общий loading. |
+| `dropdownListLoading?` | `boolean` | Loading хвоста списка (при пагинации). |
+| `clearInputOnFocus?` | `boolean` | Очищать input при focus. |
+| `onSelect` | `(value: T \| undefined) => void` | Колбэк выбора. |
+| `onFilter` | `(value: string) => void` | Колбэк ввода. |
+| `onScrollEnd?` | `() => void` | Пагинация. |
+| `onClear?` | `MouseEventHandler<HTMLButtonElement>` | Колбэк кнопки очистки. |
+| `renderInput?` | `(props: IFormFieldInputProps) => JSX.Element` | Кастомный input. |
+| `inputProps` | `IFormFieldInputProps` | Обязателен (наследовано из `TextField`). |
+
+Desktop дополнительно принимает `renderDropdown`, `renderDropdownList`, `renderDropdownListItem`.
+
+### `ISuggestFieldOption`
+
+```ts
+{ id: string; label: string; content?: ReactNode; showNotificationIcon?: boolean }
+```
+
+### `SuggestField.Input`
+
+Re-export `FormFieldInput` — для удобства доступа.
+
+---
+
+## Поведение
+
+### Desktop
+
+- Собственный state: `inputValue`, `inputFocused`, `dropdownOpen`, `ignoreAutoOpen`, `activeDescendant`, `dropdownListId`.
+- `ignoreAutoOpen` — предотвращает немедленное переоткрытие dropdown сразу после выбора (иначе селектнутый item → focus остаётся на input → dropdown открывается снова).
+- Синхронизация `value?.id !== prevValue?.id` → `setInputValue(value?.label)`.
+- `clearInputOnFocus` + focus с непустым input → `setInputValue("")` + `onFilter("")`.
+- `activeDescendant` — id подсвеченного элемента списка (для `aria-activedescendant`).
+
+### Mobile (`SuggestFieldMobile`)
+
+- Открывает полноэкранный лист с input'ом и списком.
+- `SuggestFieldMobileDropdownHint` — текст-подсказка над списком.
+- Рендерится только внутри `MobileView` (viewport <= SM).
+
+### `MobileView`
+
+Корневой `SuggestField.tsx` рендерит `<MobileView fallback={SuggestFieldDesktop}>SuggestFieldMobile</MobileView>` — выбор по media query.
+
+---
+
+## Инварианты
+
+- **Generic `<T extends ISuggestFieldOption>`** — сохранять. `SuggestField.Input = FormFieldInput`.
+- **`tooltipHint` и `tooltipOpen` — обязательные** (не опциональные, как может казаться). Tooltip — часть UX.
+- **Синхронизация `value` → `inputValue`** через render-сравнение (по `id`, не по ссылке).
+- **`inputProps` обязателен** (прокидывается в `FormFieldInput`) — наследство из `TextField`. Не default'ить на `{}` без причины.
+- **`onSelect(undefined)`** допустимо (сбрасывает).
+- **Два разных state-дерева** (desktop и mobile) — не объединять без refactor'а под `useSuggest`.
+- **`MobileView` определяет ветку по media-query** — не по прямому props. Для force desktop/mobile в тестах — имитировать viewport.
+
+---
+
+## Accessibility
+
+- `role="combobox"` / `aria-controls` / `aria-expanded` / `aria-activedescendant` проставляются в Desktop-реализации (`SuggestFieldDesktop`) на input'е.
+- `dropdownListId` передаётся в `DropdownList` (`role="listbox"`) и используется как `aria-controls`.
+- Escape закрывает dropdown (`isKey(event.key, "ESCAPE")`).
+- Mobile: полноэкранный лист с явным focus management на input.
+- `onClear` — опционально; если передан, рисуется `FormFieldClear` кнопка с осмысленной ariaLabel (переопределяется через `inputProps`).
+
+---
+
+## Связанные компоненты
+
+- `Suggest` — headless-основа (TODO: SuggestField должен переехать на него).
+- `SelectField` — статический dropdown.
+- `Dropdown` / `DropdownList` / `DropdownListItem` — UI списка.
+- `TextField` — родительский тип props.
+- `MobileView` — адаптивная обёртка.
+- `FormFieldInput`, `FormFieldClear`, `Tooltip`, `LoaderSmall` — внутренние зависимости.
+
+---
+
+## Stories
+
+Основные истории: `stories/SuggestField/SuggestField.stories.tsx`
+Примеры: `stories/SuggestField/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/SwipeableArea.md

@@ -0,0 +1,144 @@
+---
+component: SwipeableArea
+category: Mobile / Layout
+figma-node: ""
+figma-file: ""
+related: [MobileView]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# SwipeableArea
+
+## Назначение
+
+Мобильный контейнер с поддержкой horizontal-swipe: при свайпе влево открывается
+`rightSwipeableArea` (обычно — action-панель), при свайпе вправо —
+`leftSwipeableArea`. Основной контент смещается `transform: translateX`.
+Работает только через touch-события (нет mouse drag).
+
+Используй когда: нужен iOS-подобный swipe-to-reveal в списке (удалить/
+архивировать и т.п.) на мобильных устройствах.
+Не используй когда: нужен desktop drag — `SwipeableArea` не обрабатывает
+mouse events.
+
+---
+
+## Файловая структура
+
+```text
+src/components/SwipeableArea/
+├── SwipeableArea.tsx    # forwardRef<ISwipeableAreaRef, ISwipeableAreaProps>
+├── index.ts
+└── styles/SwipeableArea.module.less
+```
+
+---
+
+## Варианты и props
+
+### `ISwipeableAreaProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `children` | `ReactNode` | Основной контент карточки. |
+| `leftSwipeableArea?` | `ReactNode` | Контент, появляющийся при свайпе вправо. Если не задан — свайп вправо игнорируется. |
+| `rightSwipeableArea?` | `ReactNode` | Контент, появляющийся при свайпе влево. Если не задан — свайп влево игнорируется. |
+| `...HTMLAttributes<HTMLDivElement>` | — | Прокидываются на корневой div. |
+
+### `ISwipeableAreaRef` (imperative API)
+
+```ts
+interface ISwipeableAreaRef {
+    closeSwipe(): void;    // закрыть любую открытую панель
+    swipeLeft(): void;     // открыть rightSwipeableArea (свайп влево)
+    swipeRight(): void;    // открыть leftSwipeableArea (свайп вправо)
+}
+```
+
+Доступ через `React.useRef<ISwipeableAreaRef>` + `ref={...}`.
+
+---
+
+## Логика
+
+### Константы
+
+| Имя | Значение | Назначение |
+|---|---|---|
+| `SWIPE_MIN_DISTANCE` | `24` (px) | Порог, ниже которого свайп считается «недотянутым» и контент возвращается в исходное положение. |
+
+### Определение направления (scroll vs swipe)
+
+При первом `touchmove`:
+- `|deltaY| > |deltaX|` → `dragType = vertical` (скролл), свайп не обрабатывается.
+- иначе → `horizontal` (свайп), контент двигается.
+
+При отпускании (`touchend` на document) — сброс `dragType`.
+
+### Завершение свайпа (`handleSwipe`)
+
+Запускается в `useEffect` при `dragType → undefined && contentTranslateX !== start`.
+Логика зависит от начального состояния:
+- Было закрыто, сдвиг > порога → открыть соответствующую панель (translateX = ±width).
+- Было закрыто, сдвиг < порога → вернуть к 0.
+- Было открыто — если сдвиг в сторону закрытия превышает порог → закрыть, иначе — вернуть к открытому состоянию.
+
+### Opacity side-панелей
+
+`opacity = |contentTranslateX| / panelWidth` — плавное появление.
+
+### Outside-touch
+
+`document.addEventListener("touchstart")` закрывает swipe при tap'е вне контейнера.
+
+### Анимация
+
+CSS-класс `swipeAnimationFinish` (`animating = true`) → CSS transition.
+`animating = false` в `onTransitionEnd`.
+
+Во время горизонтального drag:
+- `disableScroll` класс → не скроллится страница.
+- `disablePointerEvents` класс → элементы внутри контента не реагируют на клик.
+
+---
+
+## Инварианты
+
+- **`forwardRef<ISwipeableAreaRef>`** — ref отдаёт imperative API, НЕ DOM-элемент. Это нестандартно, не менять без миграции потребителей.
+- **Только touch-события** — mouse drag не поддерживается намеренно (компонент только для mobile).
+- **`SWIPE_MIN_DISTANCE = 24`** — менять с проверкой UX на реальных устройствах.
+- **`dragType === vertical`** → свайп игнорируется до конца жеста (пока пользователь не отпустит палец). Это предотвращает «дребезг» при диагональных движениях.
+- **`leftSwipeableArea` / `rightSwipeableArea` рендерятся ТОЛЬКО если переданы** (`typeof ... !== "undefined"`) — не оставлять пустые div'ы.
+- **`useImperativeHandle` переопределяет ref-форму** — потребитель не получит HTMLDivElement.
+- **Outside-tap закрывает swipe** (listener на document) — не отключать, это часть UX.
+- **`disablePointerEvents` активен, пока `contentTranslateX !== 0`** — дети не ловят клики при открытой side-панели. Взаимодействие идёт через кнопки в самой side-панели.
+
+---
+
+## Accessibility
+
+- Компонент не добавляет ARIA — это чисто-тактильный жест.
+- Для screen-reader пользователей side-панели должны быть доступны альтернативным способом (обычно — через action button в самом контенте, `overlayMenu` и т.п.).
+- Imperative API (`swipeLeft`/`swipeRight`) — используется для программного открытия (например, onboarding-туториал).
+
+---
+
+## Связанные компоненты
+
+- `MobileView` — оборачивает SwipeableArea для условного рендера только на мобильных viewport'ах.
+
+---
+
+## Stories
+
+Отдельных stories нет (mobile-only компонент, тестируется в составе mobile-экранов).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Table.md

@@ -0,0 +1,199 @@
+---
+component: Table
+category: Data Display
+figma-node: ""
+figma-file: ""
+related: [List, ListSortable, Pagination, FilterPanel]
+tokens: []
+stories: stories/Table/Table.stories.tsx
+version: "1.0"
+---
+
+# Table (MasterTable)
+
+## Назначение
+
+Набор компонентов для построения таблицы данных: `MasterTable` — корневая
+обёртка с контекстом, внутри рендерятся панели (`FilterPanel`, `TabsLinePanel`,
+`PaginationPanel`), сама таблица (`TableBasic`), настройки колонок
+(`TableBasicSettings`), футер (`TableFooter`). `MasterTable` — композитный,
+дочерние компоненты доступны и как самостоятельные (`export { TableBasic }`
+и т.д.).
+
+Используй когда: нужен полноценный data-grid с фильтрами, сортировкой и пагинацией.
+Для простой таблицы без панелей — `MasterTable.TableBasic` в одиночку.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Table/
+├── MasterTable.tsx                # Root FC + Provider
+├── MasterTableContext.ts          # { columns, loading, setColumns }
+├── FilterPanel.tsx
+├── TabsLinePanel.tsx
+├── TabsLinePanelLinks.tsx
+├── PaginationPanel.tsx
+├── NoColumns.tsx
+├── TableBasic/
+│   ├── TableBasic.tsx
+│   ├── enums.ts                   # EOrderDirection, EHorizontalAlign, EVerticalAlign, ECellType
+│   ├── types.ts                   # ITableBasicColumn, ITableBasicRow, ITableBasicProps, IMasterTableProps...
+│   ├── components/                # TableBasicHeader, TableBasicBody, ...
+│   └── styles/
+├── TableBasicSettings/
+│   ├── TableBasicSettings.tsx
+│   └── components/ColumnSettings/
+├── TableFooter/
+├── utils.ts
+├── styles/
+└── index.ts
+```
+
+---
+
+## Композиция
+
+```tsx
+<MasterTable loading={loading}>
+    <MasterTable.FilterPanel>...</MasterTable.FilterPanel>
+    <MasterTable.TabsLinePanel>...</MasterTable.TabsLinePanel>
+    <MasterTable.TableBasic
+        columns={columns}
+        data={rows}
+        renderNoData={() => <EmptyView ... />}
+        onOrderBy={handleOrderBy}
+    />
+    <MasterTable.PaginationPanel>
+        <Pagination ... />
+    </MasterTable.PaginationPanel>
+    <MasterTable.TableFooter>...</MasterTable.TableFooter>
+    <MasterTable.TableBasicSettings linkTitle="Настройки">
+        <ColumnSettings>{...}</ColumnSettings>
+    </MasterTable.TableBasicSettings>
+</MasterTable>
+```
+
+Все подкомпоненты также экспортируются напрямую: `TableBasic`, `TableFooter`,
+`FilterPanel`, `TabsLinePanel`, `PaginationPanel`, `TableBasicSettings`,
+`ColumnSettings`, `NoColumns`.
+
+---
+
+## Ключевые типы
+
+### `IMasterTableProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `loading?` | `boolean` | `false` | Прокидывается в Context → `TableBasic` рендерит loader-оверлей. |
+| `...HTMLAttributes<HTMLDivElement>` | — | — | На корневой div. |
+
+### `ITableBasicProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `columns` | `ITableBasicColumn[]` | Колонки. Запись в MasterTableContext через `useEffect` (сравнение по `isEqual`). |
+| `data` | `ITableBasicRow[]` | Строки. Пустой массив → рендерится `renderNoData()`. |
+| `renderNoData` | `() => JSX.Element` | **Обязателен**. Обычно `<EmptyView>`. |
+| `renderNoColumns?` | `() => ReactNode` | Если ВСЕ columns имеют `hidden: true`. |
+| `onOrderBy?` | `(order: ISortOrder) => void` | Колбэк сортировки (из header'а). |
+| `onClickRow?` | `(rowKey: string) => void` | Клик по строке. |
+| `highlightRowOnHover?` | `boolean` | Подсветка hover. |
+| `headless?` | `boolean` | Скрыть header. |
+| `...HTMLAttributes<HTMLTableElement>` | — | На `<table>`. |
+
+### `ITableBasicColumn`
+
+Поля: `fieldKey` (id колонки и sort key), `label`, `title`, `orderDirection`,
+`horizontalAlign`, `verticalAlign`, `cellType` (`TEXT`/`COMPONENTS`/`CHECKBOX`),
+`width`, `hidden`, `renderCell`, `dataAttributes`, `ariaAttributes`.
+
+### `ITableBasicRow`
+
+```ts
+{
+    rowKey: string;
+    rowData: any;                                   // TODO — типизация не зафиксирована
+    rowLayout?: Record<string, { rowSpan?; colSpan? }>;
+    selected?: boolean;
+    dataAttributes?; ariaAttributes?;
+}
+```
+
+### Enums (`TableBasic/enums.ts`)
+
+- `EOrderDirection`: `NONE` / `ASC` / `DESC`
+- `EHorizontalAlign`: `LEFT` / `RIGHT` / `CENTER`
+- `EVerticalAlign`: `BASELINE` / `SUB` / `SUPER` / `TEXT_TOP` / `TEXT_BOTTOM` / `MIDDLE` / `TOP` / `BOTTOM`
+- `ECellType`: `TEXT` / `COMPONENTS` / `CHECKBOX`
+
+---
+
+## Контекст (`MasterTableContext`)
+
+```ts
+{ columns: ITableBasicColumn[]; loading: boolean; setColumns: (cols) => void; }
+```
+
+`TableBasic` пишет свои columns в Context через `useEffect`; потребители
+(`TableBasicSettings` / `ColumnSettings`) читают их для настройки видимости/
+порядка колонок.
+
+---
+
+## Loading
+
+`MasterTable` передаёт `loading` в Context. `TableBasic` рендерит:
+- `loading && empty` → overlay + LoaderMiddle поверх `renderNoData`
+- `!loading && empty` → `renderNoData()`
+- `loading && !empty` → `LoaderScreen` (`middle` type) поверх реальной таблицы
+- иначе — таблица без loader'а
+
+---
+
+## Инварианты
+
+- **`renderNoData` обязателен** — компонент намеренно не добавляет дефолтный empty-state.
+- **`columns` сравниваются по `isEqual`** (deep) перед записью в Context — не мутировать массив in-place, менять ссылку.
+- **`MasterTable` — FC + композиция через присваивания** (`MasterTable.TableBasic = TableBasic` и т.д.).
+- **`TableBasic` — не forwardRef** (деструктурируется, ref попадает в `...htmlTableAttributes`, но не прокидывается явно).
+- **Все enum'ы (`EOrderDirection`, `EHorizontalAlign`, `EVerticalAlign`, `ECellType`)** — часть публичного API.
+- **`rowData: any`** — намеренно (`TODO` в коде). Не типизировать без координации.
+- **`TableBasicSettings` принимает `linkTitle: string`** — обязательный.
+- **Все компоненты из `index.ts` экспортируются отдельно** — используются напрямую в legacy-коде.
+
+---
+
+## Accessibility
+
+- `<table>` — семантический. Заголовок через `<thead>` / `<th>` в `TableBasicHeader`.
+- `aria-sort` на `<th>` выставляется `TableBasicHeader` по `orderDirection`.
+- `ariaAttributes` на колонке и строке — потребитель может добавить custom aria.
+- Footer (loading/empty) — чисто визуальный, без aria-live (добавить при необходимости в потребителе).
+
+---
+
+## Связанные компоненты
+
+- `Pagination` / `Ellipsis` — используются внутри `PaginationPanel`.
+- `TabsLine` — внутри `TabsLinePanel`.
+- `ButtonDropdownExtended` — основа `TableBasicSettings`.
+- `List` / `ListSortable` — основа `ColumnSettings` для управления колонками.
+- `EmptyView` — типичный `renderNoData`.
+
+---
+
+## Stories
+
+Основные истории: `stories/Table/Table.stories.tsx`
+Примеры: `stories/Table/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |