@sberbusiness/triplex-next-mcp-server 1.40.0-beta → 1.41.0-beta

package/bundle/components/KeyDownListener.md

@@ -1,11 +1,9 @@
 ---
 component: KeyDownListener
-category: Utilities
-figma-node: ""
-figma-file: ""
-related: [ComposedKeyDownListener, WindowResizeListener]
+category: KeyDownListener
+related: [ComposedKeyDownListener, TriggerClickOnKeyDownEvent, SelectExtendedField, SliderExtended]
 tokens: []
-stories: ""
+stories: stories/KeyDownListener/KeyDownListener.stories.tsx
 version: "1.0"
 ---
 
@@ -13,145 +11,260 @@ version: "1.0"
 
 ## Назначение
 
-Невизуальный компонент-слушатель `keydown` на `window`. При совпадении
-кода нажатой клавиши с `eventKeyCode` (одно значение или массив) вызывает
-`onMatch(event)`. Рендерит `children` как есть (или `null`) — не добавляет
-обёртку в DOM.
+Сервисный headless-компонент. Пока смонтирован, слушает `keydown` на `window` и
+вызывает `onMatch`, если числовой код нажатой клавиши (`event.keyCode`) совпал с
+`eventKeyCode`. Собственной разметки не рендерит: `children` выводятся как есть,
+без обёртки; без `children` не рендерит ничего.
 
-Используй когда: нужно отреагировать на глобальное нажатие клавиш
-(Escape для закрытия модалки, Tab/ArrowKey для навигации в кастомных
-виджетах), но не привязываться к конкретному focus-target'у.
+Используй когда: нужна глобальная (документная) горячая клавиша, работающая
+независимо от того, где находится фокус — закрытие оверлея по `Esc`, стрелки для
+управления слайдером/ползунком, подтверждение по `Enter`.
 
-Для нескольких параллельных слушателей используй `ComposedKeyDownListener` —
-принимает массив конфигов и композитит их в иерархию.
-
----
-
-## Файловая структура
-
-```text
-src/components/KeyDownListener/
-├── KeyDownListener.tsx           # React.Component (class) с window-keydown
-├── ComposedKeyDownListener.tsx   # FC, сворачивает массив listener'ов в tree
-└── index.ts                      # Barrel: оба компонента
-```
-
-Нет styles, stories, tests.
+Не используй когда:
+- Клавиша должна обрабатываться только внутри конкретного элемента — навесь
+  `onKeyDown` на сам элемент, иначе обработчик сработает при вводе в другое поле
+  на странице.
+- Нужно кликнуть по конкретной кнопке по нажатию клавиши — есть готовый
+  `TriggerClickOnKeyDownEvent`.
+- Нужно несколько разных клавиш с разными обработчиками — используй
+  `ComposedKeyDownListener` (см. «Связанные компоненты»).
 
 ---
 
 ## Варианты и props
 
-### KeyDownListener — `IKeyDownListenerProps`
+### Обязательные props
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `eventKeyCode` | `number \| number[]` | Да | Код клавиши (число — это `KeyboardEvent.keyCode`, не `key`). Один код или массив. |
-| `onMatch` | `(event: KeyboardEvent) => void` | Да | Вызывается при совпадении кода. |
-| `children` | `React.ReactNode` | Нет | Рендерятся "прозрачно" (компонент не оборачивает в DOM). |
-
-Тип кода: `keyCode = (typeof EVENT_KEY_CODES)[keyof typeof EVENT_KEY_CODES]`
-(числа из `@sberbusiness/triplex-next/utils/keyboard`): `ENTER=13`, `ESCAPE=27`,
-`TAB=9`, `ARROW_*=37-40`, и т.д.
+| Prop | Тип | Описание |
+|---|---|---|
+| `eventKeyCode` | `number \| number[]` | Код клавиши из `EVENT_KEY_CODES` или массив кодов. Массив — «любая из перечисленных клавиш»; различить нажатую можно по `event.keyCode` внутри `onMatch` |
+| `onMatch` | `(event: KeyboardEvent) => void` | Вызывается при совпадении. Получает нативный `KeyboardEvent` (не React SyntheticEvent) |
 
-### ComposedKeyDownListener — `IKeyDownListenerManagerProps`
+### Опциональные props
 
-| Prop | Тип | Обязателен | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `keyDownListeners` | `IKeyDownListenerProps[]` | Да | Массив конфигов. Для каждого создаётся свой `KeyDownListener`. |
-| `children` | `React.ReactNode` | Нет | Обёрнуты всеми listener'ами в иерархию (последний в массиве — самый внешний). |
+| `children` | `React.ReactNode` | — | Рендерится как есть. Компонент не оборачивает содержимое и никак на него не влияет — вложение нужно только для читаемости кода |
+
+### Особенности поведения
+
+- Слушатель навешивается на `window` в `componentDidMount` и снимается в
+  `componentWillUnmount`. Компонент не вызывает `preventDefault` и не
+  останавливает всплытие — это ответственность `onMatch`.
+- Сравнение идёт по устаревшему `event.keyCode`, а не по `event.key`. Коды
+  берутся из `EVENT_KEY_CODES` (`@sberbusiness/triplex-next`); не хардкодь числа.
+- `onMatch` и `eventKeyCode` читаются из `this.props` в момент события, поэтому
+  свежие значения после rerender применяются без переподписки.
+- Несколько смонтированных `KeyDownListener` на одну клавишу срабатывают все —
+  порядок соответствует порядку монтирования.
+- Компонент не проверяет, где находится фокус: `Esc` сработает и во время ввода
+  в поле. Если это нежелательно, фильтруй в `onMatch` по `event.target`.
 
 ---
 
-## Ключевые особенности реализации
-
-### `KeyDownListener` — class component
+## Дизайн-токены
 
-```tsx
-export class KeyDownListener extends React.Component<IKeyDownListenerProps> {
-    public componentDidMount() { window.addEventListener("keydown", this.handleKeyDown); }
-    public componentWillUnmount() { window.removeEventListener("keydown", this.handleKeyDown); }
-    public render() { return this.props.children || null; }
-}
-```
+Собственных стилей и CSS-переменных нет — компонент не рендерит разметку.
 
-- **Сохранён как class**, хотя весь остальной код библиотеки — функциональные компоненты. Миграция на `useEffect` возможна, но class сохраняет идентичность listener'а через reference handler'а — аналог можно сделать через `useEffect` + стабильный handler (через ref на `onMatch`).
-- Не `forwardRef` — компонент не имеет своего DOM.
+---
 
-### Использование `keyCode`, а не `key` / `code`
+## Инварианты
 
-```ts
-if (typeof eventKeyCode === "number") {
-    eventKeyCode === event.keyCode && onMatch(event);
-} else if (eventKeyCode.includes(event.keyCode)) {
-    onMatch(event);
-}
-```
+- **`KeyDownListener` — class-компонент**, и это часть публичного контракта:
+  `ref` указывает на инстанс класса, метод `handleKeyDown` публичный. Не
+  переписывать на функциональный компонент.
+- **Без `forwardRef` — осознанное исключение** из общего правила библиотеки:
+  компонент не рендерит собственный host-элемент, форвардить ref некуда.
+- **Имена props `children`, `eventKeyCode`, `onMatch`** и интерфейс
+  `IKeyDownListenerProps` (экспортируется из barrel) — публичное API, не менять.
+  `IKeyDownListenerProps` переиспользуется в `TriggerClickOnKeyDownEvent`
+  (`Pick<IKeyDownListenerProps, "eventKeyCode">`) и в props
+  `ComposedKeyDownListener`.
+- **Сравнение по `event.keyCode`** — не мигрировать на `event.key` без отдельной
+  задачи: у `EVENT_KEYS.SPACE` значения `["Spacebar", "Space"]` не совпадают с
+  современным `event.key === " "`, и миграция изменит наблюдаемое поведение у
+  потребителей.
+- **`render` возвращает `this.props.children || null`** — falsy-`children`
+  (`0`, `""`) осознанно дают `null`. Не заменять на `??`.
+- Реализация остаётся React 17-совместимой (класс, без хуков и React 18-only
+  API): код синхронизируется в `release-0`.
 
-- `event.keyCode` — **deprecated** в современном вебе (замена: `event.key` или `event.code`). Компонент и набор `EVENT_KEY_CODES` сохранили legacy-подход.
-- Числовые константы (13, 27, 40, ...) должны использоваться через `EVENT_KEY_CODES.ENTER` / `.ESCAPE` и т.д., не литерально.
-- Для новых компонентов предпочитать `isKey(event.key, "ENTER")` из `utils/keyboard` — она поддерживает `key`-strings и legacy-fallback.
+---
 
-### `onMatch` не кешируется в class state
+## Accessibility
 
-Каждый keydown вытаскивает `this.props.onMatch` актуальный — замыкание не устаревает. При миграции на hooks это поведение нужно воспроизвести через ref.
+- Собственной ARIA-семантики нет — компонент прозрачен для accessibility-дерева
+  и не рендерит фокусируемых элементов.
+- Горячая клавиша глобальная: она перехватывается независимо от позиции фокуса и
+  не анонсируется screen reader'ом. Если клавиша дублирует видимое действие,
+  оставь пользователю и обычный путь (кнопку) — клавиатурный шорткат не должен
+  быть единственным способом выполнить действие.
+- `Esc` для закрытия оверлеев — ожидаемое поведение; возврат фокуса на триггер
+  после закрытия компонент не делает, это ответственность потребителя.
 
-### `ComposedKeyDownListener` — reduce-вариант через цикл
+---
 
-```tsx
-let accumulatedElement = children as JSX.Element;
-for (let i = 0; i < keyDownListeners.length; i++) {
-    accumulatedElement = <KeyDownListener {...}>{accumulatedElement}</KeyDownListener>;
-}
-```
+## Связанные компоненты
 
-- Последний listener в массиве → самый внешний wrapper в tree.
-- Порядок не влияет на результат (все listener'ы слушают `window` независимо), но Reactу важен для reconciliation — не менять порядок без нужды.
-- **Внимание:** ключи не проставляются. При рендере одного и того же конфига это ок, но при динамическом изменении массива React может ломать состояние child'ов — используй stable ordering.
+### `ComposedKeyDownListener` (`src/components/KeyDownListener/ComposedKeyDownListener.tsx`)
+
+Композитор: оборачивает `children` в `KeyDownListener` по одному на каждый
+элемент `keyDownListeners`. Экспортируется из того же barrel вместе со своим
+интерфейсом props `IComposedKeyDownListenerProps` — публичное API, не менять.
+
+Собственного AI.md пока не имеет — вся его логика описана здесь. По правилу
+`docs/ai/CONTEXT.md` § «Когда создавать `{ComponentName}-ai.md`» он его
+заслуживает (оба условия выполнены: barrel-экспорт + собственный prop
+`keyDownListeners`), но по scope задачи TRI-48 соседние экспортируемые
+компоненты выносятся в отдельные задачи. Компонент добавлен отдельной строкой в
+`docs/ai/ROADMAP.md`, документ будет заведён своей задачей. Следствие, о котором
+нужно знать до тех пор: `scripts/generateMcpData.ts` собирает записи по файлам
+`src/components/*/*-ai.md`, поэтому отдельной записи в `mcp-data.json` у
+`ComposedKeyDownListener` нет — агент найдёт его только через этот документ.
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `keyDownListeners` | `IKeyDownListenerProps[]` | Конфигурация слушателей. Используются только `eventKeyCode` и `onMatch`, поле `children` каждого элемента игнорируется |
+| `children` | `React.ReactNode` | Содержимое. Рендерится как есть; при пустом `keyDownListeners` — просто `children` |
+
+Первый элемент массива оказывается самым внутренним слушателем. На порядок
+срабатывания это влияет слабо — все слушатели подписаны на `window` независимо
+друг от друга, а порядок вызова совпадает с порядком элементов массива.
+
+**Ограничение: длина `keyDownListeners` должна быть стабильной между рендерами.**
+Глубина вложенности равна длине массива, поэтому при её изменении на позиции,
+где раньше были `children`, React монтирует новый `KeyDownListener`, а сами
+`children` уезжают на уровень ниже и перемонтируются: DOM-узлы пересоздаются,
+введённые значения инпутов, фокус и текущие анимации теряются. Если набор
+слушателей динамический — держи массив постоянной длины (например, с
+`onMatch`-заглушками) или используй `KeyDownListener` напрямую.
+
+### Потребители внутри библиотеки
+
+- `TriggerClickOnKeyDownEvent` (`src/components/Triggers/`) — по нажатию клавиши
+  вызывает `click` на элементе из `targetRef`.
+- `SelectExtendedField` — закрывает выпадающий список по `Esc`.
+- `SliderExtendedDot`, `SliderExtendedTrack` — стрелки для перемещения ползунка,
+  слушатели монтируются только когда элемент в фокусе.
 
 ---
 
-## Инварианты
+## Stories
+
+Основные истории: `stories/KeyDownListener/KeyDownListener.stories.tsx`
+Файлы примеров: `stories/KeyDownListener/examples/`
 
-- **`eventKeyCode` — `number | number[]`** (не `string`/`KeyboardEvent["key"]`). Публичный контракт. При смене на `key`-строки — breaking change.
-- **`onMatch(event: KeyboardEvent)`** — получает нативное событие, не синтетическое React-событие. Не менять тип на `React.KeyboardEvent`.
-- **Class component** — сохранить при рефакторинге; миграция на FC допустима, но должна воспроизвести `componentWillUnmount`-очистку и актуальный `onMatch`.
-- **`window.addEventListener`** — listener на окне, не на document. Не менять без согласования (влияет на порядок обработки событий с портальными элементами).
-- **`children` рендерятся без обёртки** — компонент "прозрачный" в DOM. Не добавлять `<div>`/`<Fragment>` без нужды.
-- **`ComposedKeyDownListener`** — простой композитор. Не усложнять (например, не добавлять `useMemo`/контексты) без реальной нужды.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный выбор `eventKeyCode` и счётчик срабатываний `onMatch` |
+| `Default` | `Default.tsx` | Слушатель одной клавиши: панель скрывается по `Esc` |
+| `WithMultipleKeys` | `WithMultipleKeys.tsx` | Массив кодов в `eventKeyCode`; нажатая клавиша различается по `event.keyCode` |
+| `Example` | `Example.tsx` | `ComposedKeyDownListener`: `Enter` подтверждает, `Esc` отменяет |
+| `VisualTests` | — | Состояние после срабатывания слушателя: `play` диспатчит на `window` `keydown` с `keyCode` клавиши `Esc` |
 
 ---
 
-## Accessibility
+## История изменений
 
-- Компонент работает на уровне окна, перехватывает keydown до того, как фокусируемый элемент получит шанс обработать — при использовании **в составе интерактивных виджетов** учитывай, что нативный `onKeyDown` на inputе/кнопке сработает **после** глобального listener'а (из-за bubbling), но глобальный listener активен всегда, даже если фокус в другом месте.
-- Не подменяй focus management'ом. Для Escape в модалках предпочитай `focus trap` + `onKeyDown` на overlay'е.
-- Listener активен даже в скрытом state компонента-родителя, если сам KeyDownListener не размонтирован. Контролируй монтирование через условный рендеринг.
+| Дата | Изменение |
+|---|---|
+| 2026-08-04 | По ревью PR #502: интерфейс props `IComposedKeyDownListenerProps` стал экспортируемым — публичная поверхность пакета расширена аддитивно. `ComposedKeyDownListener` добавлен отдельной строкой в `docs/ai/ROADMAP.md`, собственный AI.md вынесен в отдельную задачу. |
+| 2026-08-04 | Создан документ. AI-рефакторинг (TRI-48): JSDoc на props `IKeyDownListenerProps` и `ComposedKeyDownListener`, ветвление в `handleKeyDown` сведено к одной проверке (снят `eslint-disable`), в `ComposedKeyDownListener` убран `as JSX.Element` и добавлен `displayName`, unit-тесты (16 кейсов на оба компонента), stories по modern pattern. Публичный API не менялся; компонент остаётся class-компонентом, `forwardRef` осознанно отсутствует. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-Нет.
+### Default
 
----
+`stories/KeyDownListener/examples/Default.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import { KeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [visible, setVisible] = useState(true);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+            <KeyDownListener eventKeyCode={EVENT_KEY_CODES.ESCAPE} onMatch={() => setVisible(false)} />
+            <div>Нажмите Esc, чтобы скрыть панель.</div>
+            {visible && (
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    Панель скрывается по нажатию Esc в любом месте страницы.
+                </div>
+            )}
+        </div>
+    );
+};
+```
 
-- `ComposedKeyDownListener` — обёртка для нескольких listener'ов.
-- `WindowResizeListener` — аналогичный паттерн для resize.
-- `@sberbusiness/triplex-next/utils/keyboard` — `EVENT_KEY_CODES`, `EVENT_KEYS`, `isKey`.
+### WithMultipleKeys
 
----
+`stories/KeyDownListener/examples/WithMultipleKeys.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import { KeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const WithMultipleKeys = () => {
+    const [value, setValue] = useState(0);
+
+    const handleMatch = (event: KeyboardEvent) => {
+        setValue((prevValue) => (event.keyCode === EVENT_KEY_CODES.ARROW_LEFT ? prevValue - 1 : prevValue + 1));
+    };
+
+    return (
+        <KeyDownListener eventKeyCode={[EVENT_KEY_CODES.ARROW_LEFT, EVENT_KEY_CODES.ARROW_RIGHT]} onMatch={handleMatch}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>Один слушатель реагирует на несколько клавиш: стрелка влево и стрелка вправо.</div>
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    Значение: {value}
+                </div>
+            </div>
+        </KeyDownListener>
+    );
+};
+```
 
-Нет.
+### Example
 
----
+`stories/KeyDownListener/examples/Example.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { ComposedKeyDownListener, EVENT_KEY_CODES } from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [result, setResult] = useState<string | null>(null);
+
+    const keyDownListeners = [
+        { eventKeyCode: EVENT_KEY_CODES.ENTER, onMatch: () => setResult("Подтверждено по Enter") },
+        { eventKeyCode: EVENT_KEY_CODES.ESCAPE, onMatch: () => setResult("Отменено по Esc") },
+    ];
+
+    if (result !== null) {
+        return (
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>{result}</div>
+                <button type="button" onClick={() => setResult(null)}>
+                    Показать панель снова
+                </button>
+            </div>
+        );
+    }
+
+    return (
+        <ComposedKeyDownListener keyDownListeners={keyDownListeners}>
+            <div style={{ display: "flex", flexDirection: "column", gap: "16px", maxWidth: "400px" }}>
+                <div>Панель с горячими клавишами: Enter подтверждает, Esc отменяет.</div>
+                <div style={{ border: "1px dashed rgb(125, 131, 138)", borderRadius: "4px", padding: "16px" }}>
+                    Ожидание нажатия клавиши.
+                </div>
+            </div>
+        </ComposedKeyDownListener>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |

package/bundle/components/LoaderMiddle.md

@@ -0,0 +1,265 @@
+---
+component: LoaderMiddle
+category: Loaders
+related: [LoaderSmall, LoaderScreen, TableBasic]
+tokens:
+  - --triplex-next-Loader-Middle_Background_Default
+  - --triplex-next-Loader-Element_Background_Brand
+stories: stories/Loaders/LoaderMiddle/LoaderMiddle.stories.tsx
+version: "1.0"
+---
+
+# LoaderMiddle
+
+## Назначение
+
+Квадратный индикатор загрузки фиксированного размера 64×64 px: четыре точки по углам
+внутренней области и линия, обегающая их по периметру. Все состояния анимации задаются CSS —
+у компонента нет ни props, ни внутреннего состояния.
+
+Используй когда: нужно показать, что грузится целая область или страница, а место под
+индикатор заведомо есть (плитка, пустая таблица, оверлей поверх контента).
+
+Не используй когда:
+- Индикатор должен встраиваться в строку текста, кнопку или узкий элемент управления —
+  возьми `LoaderSmall` (горизонтальный, с темами и размерами `SM` / `MD` / `LG`).
+- Нужен индикатор с подложкой, подписью и кнопками отмены — возьми `LoaderScreen`
+  (`type="middle"` рендерит внутри себя именно `LoaderMiddle`).
+- Нужно управлять размером, цветом или темой — LoaderMiddle не настраивается, см. «Инварианты».
+
+---
+
+## Варианты и props
+
+У компонента **нет props**. Публичный тип — `React.FC` без параметров: `<LoaderMiddle />` —
+единственная допустимая форма вызова.
+
+Следствия, важные при интеграции:
+
+- `className` и произвольные HTML-атрибуты **не принимаются** — обернуть в свой контейнер и
+  стилизовать его. Так поступает `WithAnimationExample` в stories: сбрасывает фон через
+  внешний класс-обёртку, а не через prop.
+- `ref` на корневой `<div>` **не пробрасывается** — компонент не обёрнут в `forwardRef`.
+  Если нужен доступ к DOM, измеряй элемент-обёртку.
+- Размер (64×64), геометрия точек (12×12) и тайминги анимаций (цикл 3 s) заданы в
+  `styles/LoaderMiddle.module.less` и снаружи не настраиваются.
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-Loader-Middle_Background_Default
+--triplex-next-Loader-Element_Background_Brand
+```
+
+- `Middle_Background_Default` — фон квадратной подложки (`ColorNeutral.80` в светлой теме,
+  `ColorDarkNeutral.50` в тёмной).
+- `Element_Background_Brand` — цвет точек и обегающей линии.
+
+Оба токена объявлены в `src/components/DesignTokens/components/Loader.ts` и общие для
+семейства Loader (`Element_Background_Brand` используется также в `LoaderSmall`).
+
+---
+
+## Инварианты
+
+- **Публичный контракт — компонент без props.** Добавление `className`, `...rest` или обёртка
+  в `forwardRef` меняет публичный тип компонента и требует отдельной задачи и записи в release
+  notes. По той же схеме объявлен сосед `LoaderSmall` (`React.FC`, без `forwardRef`).
+- **Корневой элемент — `<div role="status">`.** На эту связку опираются unit-тесты компонента и
+  тесты потребителей (`LoaderScreen.test.tsx`, `TableBasic.test.tsx`), которые ищут лоадер через
+  `getByRole("status", { name: "loading" })`. Имена CSS-классов снаружи не используются —
+  тесты потребителей намеренно опираются только на роль и доступное имя.
+- **Разметка внутренностей фиксирована:** контейнер `.loaderMiddleDots`, один `.line` и ровно
+  четыре точки `.dot` с модификаторами `.dot1`–`.dot4`. Порядок и количество завязаны на
+  keyframes (`lineCycle`, `dotCycleMiddle`) и на задержки анимации; удаление или перестановка
+  ломает визуальную последовательность.
+- **`displayName = "LoaderMiddle"`** — используется в React DevTools.
+- **Токены `Loader-*` общие для семейства** — переименование ломает темизацию у потребителей и
+  затрагивает `LoaderSmall`.
+
+---
+
+## Accessibility
+
+- Корневой элемент имеет `role="status"` — это неявная `aria-live="polite"` область: скринридер
+  сообщит о появлении лоадера, не прерывая текущее чтение.
+- `aria-label="loading"` захардкожен в компоненте. Это отступление от общего правила библиотеки
+  «не хардкодить язык в aria-атрибутах», унаследованное от `LoaderSmall`; менять его нельзя без
+  согласования — строка входит в доступное имя, по которому лоадер находят тесты потребителей.
+  Локализация доступного имени — предмет отдельной задачи по всему семейству Loader.
+- Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру и не содержит текста.
+  Если загрузку нужно подписать для пользователя — используй `LoaderScreen` с `description`.
+- Анимация непрерывная и не отключается по `prefers-reduced-motion` — известное ограничение
+  семейства Loader.
+
+---
+
+## Связанные компоненты
+
+- `LoaderSmall` (`src/components/Loader/LoaderSmall/LoaderSmall.tsx`) — горизонтальный вариант из
+  трёх точек с props `theme` (`ELoaderSmallTheme`) и `size` (`EComponentSize`). Экспортируется из
+  того же barrel `src/components/Loader/index.ts`.
+- `LoaderScreen` (`src/components/LoaderScreen/LoaderScreen.tsx`) — оверлей-подложка с лоадером по
+  центру, подписью и кнопками; при `type="middle"` рендерит `LoaderMiddle` без обёрток.
+- `TableBasic` (`src/components/Table/TableBasic/TableBasic.tsx`) — показывает `LoaderMiddle` в
+  футере таблицы при догрузке данных на пустом состоянии.
+
+---
+
+## Stories
+
+Основные истории: `stories/Loaders/LoaderMiddle/LoaderMiddle.stories.tsx`
+Файлы примеров: `stories/Loaders/LoaderMiddle/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` | `DefaultExample.tsx` | Единственная форма вызова — `<LoaderMiddle />` без props |
+| `WithAnimation` | `WithAnimationExample.tsx` | Замена лоадера на Lottie-анимацию результата (success / fail / warning / waiting) с подгонкой размера точек |
+| `VisualTests` | — | Скриншот-регрессия, анимации заглушены декоратором |
+
+Стори `Default` и `WithAnimation` исключены из скриншот-тестов (`testRunner: { skip: true }`):
+первая визуально идентична `VisualTests`, вторая завязана на проигрывание Lottie и давала бы
+нестабильный снимок. Playground не создаётся — у компонента нет настраиваемых props
+(`docs/ai/stories-guide.md` → «Когда не создавать Playground»).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-05 | Создан документ. AI-рефакторинг: JSDoc на компоненте, порядок импортов приведён к codestyle, в LESS объединены дублирующиеся базовые стили `.dot` и `.line`, unit-тесты расширены с 1 до 2 кейсов (роль корневого элемента, количество точек и линии). В stories `controls: { disable: true }` перенесён на верхний уровень `parameters` (внутри `docs` не применялся). Публичный API, DOM и визуальное поведение не изменены. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Loaders/LoaderMiddle/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderMiddle } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => <LoaderMiddle />;
+```
+
+### WithAnimation
+
+`stories/Loaders/LoaderMiddle/examples/WithAnimationExample.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { Player } from "@lottiefiles/react-lottie-player";
+import { Button, EButtonTheme, EComponentSize, LoaderMiddle } from "@sberbusiness/triplex-next";
+import "./WithAnimationExample.less";
+
+const successSignAnimation = new URL("../lottie_animations/successSign.json", import.meta.url).href;
+const failSignAnimation = new URL("../lottie_animations/failSign.json", import.meta.url).href;
+const warningSignAnimation = new URL("../lottie_animations/warningSign.json", import.meta.url).href;
+const waitingSignAnimation = new URL("../lottie_animations/waitingSign.json", import.meta.url).href;
+
+/** Размер стороны LoaderMiddle */
+const loaderMiddleSize = 64;
+/** Диаметр dots в LoaderMiddle */
+const loaderMiddleDotSize = 12;
+
+/** Размер стороны Lottie */
+const lottieSize = 85;
+/** Диаметр dots в Lottie - изначальный диаметр 12×12, под transform scale [80,80] */
+const lottieDotSize = 12 * 0.8;
+
+/** Диаметр dots в Lottie после вписывания Lottie в LoaderMiddle */
+const lottieDotSizeWhenFitted = (lottieDotSize / lottieSize) * loaderMiddleSize;
+/** Масштаб dots в Lottie после вписывания Lottie в LoaderMiddle */
+const lottieDotSizeScale = loaderMiddleDotSize / lottieDotSizeWhenFitted;
+
+/** Целевой размер стороны Lottie, при котором dots в Lottie совпадают с dots в LoaderMiddle. */
+const lottieViewportSize = loaderMiddleSize * lottieDotSizeScale;
+
+type TStatus = "success" | "fail" | "warning" | "waiting";
+
+const STATUS_TO_ANIMATION_MAP: Record<TStatus, string> = {
+    success: successSignAnimation,
+    fail: failSignAnimation,
+    warning: warningSignAnimation,
+    waiting: waitingSignAnimation,
+};
+
+export const WithAnimationExample = () => {
+    const [lottieStarted, setLottieStarted] = useState(false);
+    const [isLottiePlay, setIsLottiePlay] = useState(false);
+
+    const handleChange = () => {
+        if (lottieStarted) {
+            setLottieStarted(false);
+            setIsLottiePlay(false);
+            return;
+        }
+
+        setLottieStarted(true);
+        setIsLottiePlay(true);
+    };
+
+    const renderContent = (status: TStatus) => {
+        return (
+            <div
+                style={{
+                    width: loaderMiddleSize,
+                    height: loaderMiddleSize,
+                    position: "relative",
+                    margin: "32px 0 0 32px",
+                }}
+            >
+                {!lottieStarted ? (
+                    <div className="withAnimationExample">
+                        <LoaderMiddle />
+                    </div>
+                ) : (
+                    <div
+                        style={{
+                            position: "absolute",
+                            top: "50%",
+                            left: "50%",
+                            width: lottieViewportSize,
+                            height: lottieViewportSize,
+                            transform: "translate(-50%, -50%)",
+                        }}
+                    >
+                        <Player
+                            autoplay={isLottiePlay}
+                            loop={false}
+                            keepLastFrame
+                            src={STATUS_TO_ANIMATION_MAP[status]}
+                            onEvent={(event) => {
+                                if (event === "complete") {
+                                    setIsLottiePlay(false);
+                                }
+                            }}
+                        />
+                    </div>
+                )}
+            </div>
+        );
+    };
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 16, alignItems: "flex-start" }}>
+            <Button theme={EButtonTheme.GENERAL} size={EComponentSize.SM} onClick={handleChange}>
+                {lottieStarted ? "Start Loading" : "Stop Loading"}
+            </Button>
+
+            <div style={{ display: "flex", gap: 24 }}>
+                {renderContent("success")}
+                {renderContent("fail")}
+                {renderContent("warning")}
+                {renderContent("waiting")}
+            </div>
+        </div>
+    );
+};
+```
+