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

package/bundle/components/KeyDownListener.md

@@ -108,36 +108,9 @@ version: "1.0"
 
 ### `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` напрямую.
+Композитор: рендерит по одному `KeyDownListener` на элемент `keyDownListeners`.
+Используй, когда нужно несколько разных клавиш с разными обработчиками.
+Документация — `src/components/KeyDownListener/ComposedKeyDownListener-ai.md`.
 
 ### Потребители внутри библиотеки
 
@@ -159,8 +132,13 @@ version: "1.0"
 | `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` |
+
+Набор целиком исключён из скриншот-тестов (`testRunner: { skip: true }` в `meta`):
+собственной разметки компонент не рендерит, на скриншот попадала бы только
+обвязка примеров. Поведение слушателя покрыто unit-тестами.
+
+Примеры `ComposedKeyDownListener` живут в собственном наборе stories —
+`stories/ComposedKeyDownListener/`.
 
 ---
 
@@ -168,6 +146,7 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-08-11 | TRI-112: у `ComposedKeyDownListener` появились собственный `ComposedKeyDownListener-ai.md` и набор stories `stories/ComposedKeyDownListener/`; раздел «Связанные компоненты» сокращён до ссылки, story `Example` (демонстрация композитора) перенесена в новый набор. Ограничение на стабильную длину `keyDownListeners` снято — композитор рендерит слушателей соседями к `children`. Набор stories `KeyDownListener` исключён из скриншот-тестов, story `VisualTests` и baseline удалены — визуального интерфейса у компонента нет. Реализация самого `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` осознанно отсутствует. |
 
@@ -228,43 +207,3 @@ export const WithMultipleKeys = () => {
 };
 ```
 
-### 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>
-    );
-};
-```
-

package/bundle/components/LightBox.md

@@ -126,6 +126,11 @@ version: "1.0"
   последнего (при переключении роутов второй лайтбокс может смонтироваться раньше, чем
   размонтируется первый). Аналогичный счётчик в `LightBoxViewManager` управляет классами
   mount-ноды (`LightBoxMountNodeViewManager`, `LB-*`).
+- **Локальные z-index внутри лайтбокса** (стековый контекст создаёт `.lightBox`): контролы и
+  sticky-шапка/футер `Page` — 100/101, лоадеры `LightBox.Content` и `LightBox.SideOverlay` — 201,
+  `TopOverlay` — 500. `LoaderScreen` приходит с глобальным `@z-index-loader-screen` (10100), поэтому
+  обе обёртки лоадера обязаны переопределять его локальным значением — иначе лоадер перекрывает
+  `TopOverlay`.
 - Баррел `index.ts` реэкспортирует `LightBox`, `enums`, `LightBoxSideOverlay` — сохранять.
 - React 17 совместимость (синхронизация в release-0): React 18-only API не использовать.
 
@@ -194,6 +199,7 @@ version: "1.0"
 | 2026-07-22 | Создан документ (Phase 1 AI-Ready). В том же изменении — AI-рефакторинг: JSDoc на props, общий `LightBoxArrow` для Prev/Next, хук `useLightBoxSidebarVisibility` для сайдбаров, устранение eslint-подавлений; публичный API не менялся |
 | 2026-07-22 | Добавлен `export` к props-интерфейсам `ILightBoxControlsProps`, `ILightBoxCloseProps`, `ILightBoxPrevProps`, `ILightBoxNextProps`, `ILightBoxSideOverlayLoaderProps` (аддитивно, для консистентности с остальными интерфейсами компонента) |
 | 2026-07-22 | Багфиксы по ревью PR #474: клавиатурные триггеры контролов целятся в видимую кнопку (стрелки не работали на desktop, Esc — на mobile); таймер-хак блокировки скролла заменён счётчиком смонтированных лайтбоксов; `LightBoxViewManager` снимает классы mount-ноды при размонтировании последнего менеджера |
+| 2026-08-17 | Исправлено: `LightBox.TopOverlay` перекрывался лоадером `LightBox.Content`. У `.loadingContentOverlay` теперь локальный z-index (201) — выше sticky-шапки и футера `Page`, но ниже `TopOverlay` (500); раньше `LoaderScreen` шёл с глобальным `@z-index-loader-screen` (10100) |
 
 ---
 

package/bundle/components/LoaderSmall.md

@@ -0,0 +1,230 @@
+---
+component: LoaderSmall
+category: Loaders
+related: [LoaderMiddle, LoaderScreen, Button, Dropdown, ListItemLoading, SuggestField, SelectExtendedField]
+tokens:
+  - --triplex-next-Loader-Element_Background_Brand
+  - --triplex-next-Loader-Element_Background_Neutral
+stories: stories/Loaders/LoaderSmall/LoaderSmall.stories.tsx
+version: "1.0"
+---
+
+# LoaderSmall
+
+## Назначение
+
+Компактный индикатор загрузки: три точки в ряд, гаснущие по очереди. Размер задаётся
+общим для библиотеки `EComponentSize` (16 / 24 / 32 px по стороне), цвет — темой
+(`ELoaderSmallTheme`). Анимация целиком на CSS, внутреннего состояния у компонента нет.
+
+Используй когда: нужно показать загрузку внутри уже существующего элемента управления —
+кнопки, поля с подсказками, выпадающего списка, строки списка.
+
+Не используй когда:
+- Грузится целая область или страница и место под крупный индикатор есть — возьми
+  `LoaderMiddle` (квадрат 64×64).
+- Нужны подложка поверх контента, подпись и кнопки отмены — возьми `LoaderScreen`
+  (`type="small"` рендерит внутри себя именно `LoaderSmall`).
+
+---
+
+## Варианты и props
+
+Компонент расширяет `React.HTMLAttributes<HTMLSpanElement>`: любой стандартный атрибут
+`<span>` (`id`, `data-*`, `style`, обработчики) уходит на корневой элемент через `...rest`.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `theme` | `ELoaderSmallTheme` | `BRAND` — брендовый цвет точек для светлых поверхностей; `NEUTRAL` — светлые точки для тёмных и цветных поверхностей (тёмная кнопка, цветной блок) |
+| `size` | `EComponentSize` | `SM` — 16×16 (точки 4px), `MD` — 24×24 (6px), `LG` — 32×32 (8px) |
+
+Оба props обязательны — значений по умолчанию нет, вызов `<LoaderSmall />` не типизируется.
+Как правило `size` пробрасывается из размера родительского контрола: так делают `Button`,
+`Dropdown`, `SuggestField`, `SelectExtendedField`.
+
+### Опциональные props
+
+Собственных опциональных props нет. `className` объединяется с базовыми классами
+(`clsx`), а не заменяет их.
+
+### Особенности API
+
+- `ref` на корневой `<span>` **не пробрасывается** — компонент объявлен как `React.FC`
+  без `forwardRef`. Так же объявлен сосед `LoaderMiddle`. Если нужен доступ к DOM,
+  измеряй элемент-обёртку.
+- Из barrel экспортируется enum `ELoaderSmallSize` (`sm` / `md` / `lg`). Компонентом он
+  **не используется** — размер задаётся `EComponentSize`. Enum остаётся в публичном API
+  ради обратной совместимости; в новом коде не применяй.
+
+---
+
+## Дизайн-токены
+
+```text
+--triplex-next-Loader-Element_Background_Brand
+--triplex-next-Loader-Element_Background_Neutral
+```
+
+- `Element_Background_Brand` — цвет точек темы `BRAND` (`ColorBrand.50` в обеих темах).
+- `Element_Background_Neutral` — цвет точек темы `NEUTRAL` (`ColorNeutralAlpha.0`).
+
+Токены объявлены в `src/components/DesignTokens/components/Loader.ts` и общие для семейства
+Loader: `Element_Background_Brand` использует также `LoaderMiddle`. Геометрия (размеры,
+`gap`, радиус) и тайминги анимации (цикл 0.9s, сдвиг фазы 0.15s) заданы в
+`styles/LoaderSmall.module.less` и снаружи не настраиваются.
+
+---
+
+## Инварианты
+
+- **Публичный контракт — `React.FC` без `forwardRef`.** Добавление ref-проброса расширяет
+  публичный API и требует отдельной задачи и записи в release notes.
+- **Корневой элемент — `<span role="status" aria-label="loading">`.** На эту связку опираются
+  `LoaderSmall.test.tsx` и `LoaderScreen.test.tsx` (кейсы `type="small"`) через
+  `getByRole("status", { name: "loading" })`, а `Button.test.tsx` — через
+  `getByRole("status")` без фильтра по имени.
+- **Разметка внутренностей фиксирована:** ровно три `<span class="dot dot1|dot2|dot3">`.
+  Порядок и количество завязаны на задержки анимации (`.dot2` — 0.15s, `.dot3` — 0.3s);
+  удаление или перестановка ломают визуальную последовательность.
+- **`...rest` разливается после `role` и `aria-label`** — потребитель может их переопределить.
+  Порядок атрибутов в JSX менять не нужно: это осознанная точка расширения.
+- **`displayName = "LoaderSmall"`** — используется в React DevTools.
+- **Значения `ELoaderSmallTheme`** (`brand` / `neutral`) и наличие `ELoaderSmallSize` в barrel —
+  часть публичного API, удаление или переименование — breaking change.
+- **`ILoaderSmallProps` — не только props этого компонента.** `DropdownMobileLoader` строит из
+  него свой публичный интерфейс: `IDropownMobileLoaderProps extends Omit<ILoaderSmallProps,
+  "theme" | "size">` (`src/components/Dropdown/mobile/DropdownMobileLoader.tsx:8`). Любое
+  изменение формы `ILoaderSmallProps` автоматически меняет публичный API и этого компонента.
+- **Токены `Loader-*` общие для семейства** — переименование ломает темизацию у потребителей
+  и затрагивает `LoaderMiddle`.
+
+---
+
+## Accessibility
+
+- Корневой элемент имеет `role="status"` — неявная `aria-live="polite"` область: скринридер
+  сообщит о появлении лоадера, не прерывая текущее чтение.
+- `aria-label="loading"` захардкожен в компоненте. Это отступление от общего правила
+  библиотеки «не хардкодить язык в aria-атрибутах»; менять нельзя без согласования — строка
+  входит в доступное имя, по которому лоадер находят тесты потребителей. Локализация
+  доступного имени — предмет отдельной задачи по всему семейству Loader. Потребитель может
+  перекрыть значение, передав свой `aria-label` (уйдёт в `...rest`).
+- Компонент неинтерактивен: не получает фокус, не обрабатывает клавиатуру, текста не содержит.
+  Подпись к загрузке даёт родитель (например `LoaderScreen` через `description`).
+- Анимация непрерывная и не отключается по `prefers-reduced-motion` — известное ограничение
+  семейства Loader.
+
+---
+
+## Связанные компоненты
+
+- `LoaderMiddle` (`src/components/Loader/LoaderMiddle/LoaderMiddle.tsx`) — крупный квадратный
+  вариант без props, из того же barrel `src/components/Loader/index.ts`.
+- `LoaderScreen` (`src/components/LoaderScreen/LoaderScreen.tsx`) — оверлей с лоадером,
+  подписью и кнопками; при `type="small"` рендерит `LoaderSmall` с темой `BRAND`.
+- `Button` (`src/components/Button/Button.tsx`) — рендерит `LoaderSmall` **всегда**, а вне
+  состояния `loading` прячет обёртку классом (`Button.tsx:156`), поэтому `role="status"`
+  доступен и у обычной кнопки — не пиши тест вида `queryByRole("status")` → `null`.
+  Тему выбирает по теме кнопки (`SECONDARY` / `SECONDARY_LIGHT` → `BRAND`,
+  остальные → `NEUTRAL`), размер — по размеру кнопки.
+- `Dropdown` (`DropdownList`, `DropdownMobileList`, `DropdownMobileLoader`), `SuggestField`,
+  `ChipSuggest`, `SelectExtendedField`, `ListItemLoading` — показывают `LoaderSmall` с темой
+  `BRAND` во время подгрузки данных.
+
+---
+
+## Stories
+
+Основные истории: `stories/Loaders/LoaderSmall/LoaderSmall.stories.tsx`
+Файлы примеров: `stories/Loaders/LoaderSmall/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный подбор `theme` и `size` |
+| `Default` | `DefaultExample.tsx` | Минимальный вызов: тема `BRAND`, размер `MD` |
+| `Themes` | `ThemesExample.tsx` | `BRAND` на светлом фоне и `NEUTRAL` на тёмной подложке |
+| `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` / `LG` в обеих темах |
+| `VisualTests` | — | Скриншот-регрессия: сетка размеров × тем, анимации заглушены декоратором |
+
+Файлы примеров сохраняют исторический постфикс `Example` (`DefaultExample.tsx`) —
+переименование ломало бы ссылки на них без пользы, миграция именования не входит в задачу
+(`docs/ai/stories-guide.md`).
+
+Стори `Default`, `Themes` и `Sizes` исключены из скриншот-тестов (`testRunner: { skip: true }`):
+их содержимое целиком повторяется в `VisualTests`, дублирующие снимки не нужны. Скриншоты
+снимаются только со стори `VisualTests` (`loaders-loadersmall--visual-tests--xs|xl.png`).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-06 | Создан документ. AI-рефакторинг: JSDoc на компоненте, props и значениях `ELoaderSmallTheme`, документирован неиспользуемый `ELoaderSmallSize`, порядок импортов приведён к codestyle, константы-маппинги переименованы в `THEME_TO_CLASS_NAME_MAP` / `SIZE_TO_CLASS_NAME_MAP`, в стилях объединено дублирующееся объявление анимации точек — сама анимация задана один раз на `.dot`, а у `.dot1` / `.dot2` / `.dot3` осталась только `animation-delay` (правило `.dot1` с нулевой задержкой обязательно: без него класс исчезнет из CSS-модуля и из разметки), unit-тесты расширены с 3 до 6 кейсов. В stories `controls: { disable: true }` перенесён на верхний уровень `parameters` — внутри `docs` он не применялся. Публичный API, DOM и визуальное поведение не изменены. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Loaders/LoaderSmall/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderSmall, ELoaderSmallTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => <LoaderSmall theme={ELoaderSmallTheme.BRAND} size={EComponentSize.MD} />;
+```
+
+### Themes
+
+`stories/Loaders/LoaderSmall/examples/ThemesExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderSmall, ELoaderSmallTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const ThemesExample = () => (
+    <div style={{ display: "flex", gap: "32px", alignItems: "center" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>BRAND</div>
+            <LoaderSmall theme={ELoaderSmallTheme.BRAND} size={EComponentSize.MD} />
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>NEUTRAL</div>
+            <div style={{ display: "inline-flex", padding: "8px", borderRadius: "8px", background: "#1C1C1E" }}>
+                <LoaderSmall theme={ELoaderSmallTheme.NEUTRAL} size={EComponentSize.MD} />
+            </div>
+        </div>
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Loaders/LoaderSmall/examples/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderSmall, ELoaderSmallTheme, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        {SIZES.map((size) => (
+            <div key={size} style={{ display: "flex", alignItems: "center", gap: "32px" }}>
+                <div style={{ width: "32px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+                <LoaderSmall theme={ELoaderSmallTheme.BRAND} size={size} />
+                <div style={{ display: "inline-flex", padding: "8px", borderRadius: "8px", background: "#1C1C1E" }}>
+                    <LoaderSmall theme={ELoaderSmallTheme.NEUTRAL} size={size} />
+                </div>
+            </div>
+        ))}
+    </div>
+);
+```
+