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

package/bundle/components/LoaderScreen.md

@@ -1,11 +1,11 @@
 ---
 component: LoaderScreen
-category: Feedback
-figma-node: ""
-figma-file: ""
-related: [Loader, Skeleton, LightBox, List]
-tokens: []
-stories: stories/Loaders/LoaderScreen
+category: Loaders
+related: [LoaderSmall, LoaderMiddle, Gap, Text, ModalWindowContent, LightBoxContent, LightBoxSideOverlay, List, TableBasic, MultiselectField]
+tokens:
+  - --triplex-next-LoaderScreen-Small_Backdrop_Default
+  - --triplex-next-LoaderScreen-Middle_Backdrop_Default
+stories: stories/Loaders/LoaderScreen/LoaderScreen.stories.tsx
 version: "1.0"
 ---
 
@@ -13,117 +13,168 @@ version: "1.0"
 
 ## Назначение
 
-Контейнер-оверлей, рендерящий `LoaderSmall` или `LoaderMiddle` с полупрозрачным
-бэкдропом — поверх блока/экрана, пока идёт загрузка. Centered по `flexbox`
-внутри относительно расположенного родителя (наружный элемент должен иметь
-`position: relative` или быть самим "экраном").
-
-Используй когда: нужно закрыть контент оверлеем на время загрузки
-(в Island'е, Modal'е, Content-wrapper'е). Для inline-спиннера в кнопке —
-`LoaderSmall` напрямую. Для skeleton-загрузки известной структуры — `Skeleton`.
+Виджет-загрузчик: абсолютно позиционированный `<div>`, который перекрывает область ближайшего
+позиционированного родителя полупрозрачной подложкой и показывает по её центру лоадер
+(`LoaderSmall` или `LoaderMiddle`), опциональное описание и опциональные кнопки.
+
+Используй когда: нужно закрыть уже отрисованный блок на время загрузки — тело модального окна,
+контент LightBox, список, таблицу, выпадающий список поля. Так пользователь видит, какая именно
+часть интерфейса перезагружается, и не теряет контекст страницы.
+
+Не используй когда:
+- Нужен просто индикатор загрузки без перекрытия контента — возьми `LoaderSmall` или `LoaderMiddle`
+  напрямую.
+- Нужен полноэкранный лоадер приложения — LoaderScreen перекрывает только своего позиционированного
+  родителя, а не вьюпорт.
+- Нужно заблокировать взаимодействие со страницей — LoaderScreen не ловушка фокуса и не модальный
+  оверлей, см. «Accessibility». Для блокирующего сценария возьми `ModalWindowContent` или
+  `LightBoxContent` с их встроенным `isLoading` — prop объявлен именно на контентных
+  субкомпонентах, а не на корневых `ModalWindow` / `LightBox`. У `LightBox` есть свой `isLoading`,
+  но он только отключает focus trap (`active={!isLoading}`) и лоадер не рендерит.
 
 ---
 
-## Файловая структура
-
-```text
-src/components/LoaderScreen/
-├── LoaderScreen.tsx                    # FC, <div> + lоадер
-├── index.ts                            # Barrel
-├── styles/LoaderScreen.module.less
-└── __tests__/LoaderScreen.test.tsx
-```
+## Варианты и props
 
----
+### Обязательные props
 
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `"small" \| "middle"` | Какой лоадер рендерится внутри и какой токен подложки используется. `small` → `LoaderSmall` с темой `ELoaderSmallTheme.BRAND`, `middle` → `LoaderMiddle` |
 
-### `ILoaderScreenProps extends HTMLAttributes<HTMLDivElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `type` | `"small" \| "middle"` | — (обязателен) | Тип лоадера внутри. `small` — LoaderSmall, `middle` — LoaderMiddle. |
-| `theme` | `ELoaderSmallTheme` | `BRAND` | Только для `type="small"`. Игнорируется для `middle`. |
-| `size` | `EComponentSize` | `MD` | Только для `type="small"`. Игнорируется для `middle`. |
-| `className`, `...HTMLDivAttributes` | — | — | Стандартные. |
-
-**`type` — строковый литерал**, не enum. Публичный API. Не смешивать с `ELoaderSmallTheme`.
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер лоадера. **Учитывается только при `type="small"`** — `LoaderMiddle` размеров не имеет и prop молча игнорируется |
+| `description` | `React.ReactNode` | — | Текст под лоадером. Оборачивается в `Text` (`tag="div"`, `size={ETextSize.B2}`) с выравниванием по центру |
+| `controls` | `React.ReactNode` | — | Кнопки под лоадером (например, «Отмена»). Рендерятся в простом `<div>` без раскладки — flex/gap задаёт потребитель |
+
+Компонент расширяет `React.HTMLAttributes<HTMLDivElement>` — все стандартные атрибуты `<div>`
+(`className`, `style`, `role`, `aria-*`, `data-*`, обработчики событий) попадают на корневой элемент.
+
+### `ILoaderScreenMiddleProps`
+
+`Omit<ILoaderScreenProps, "type" | "size">` — экспортируемый тип для компонентов, которые встраивают
+LoaderScreen и сами фиксируют `type="middle"`. Потребителю остаются `description`, `controls`,
+`className` и остальные атрибуты `<div>`. Используется в `ModalWindowContent`, `LightBoxContent`,
+`LightBoxSideOverlay` как тип prop'а `loaderScreenProps`.
+
+### Ограничения раскладки
+
+- **Родитель обязан быть позиционированным** (`position: relative` / `absolute` / `fixed`).
+  Сам LoaderScreen — `position: absolute` с `left/top/right/bottom: 0`; при статическом родителе он
+  растянется по ближайшему позиционированному предку выше или по initial containing block.
+  Во всех stories и примерах обёртка явно получает `position: relative`.
+- **Ширина контента ограничена 380px** (`.loaderContent`), содержимое центрируется по обеим осям.
+  Длинное `description` переносится, а не расширяет блок.
+- **Отступы фиксированы:** `Gap size={24}` между лоадером и описанием и между описанием и кнопками.
+  Настроить их через props нельзя.
+- **`z-index: @z-index-loader-screen`** (10100 из `src/helpers/less/z-indexes.less`). Значение выше
+  тултипа; `ModalWindowClose` намеренно поднимается ещё выше (`@z-index-loader-screen + 50`), чтобы
+  крестик оставался кликабельным поверх лоадера.
+  В обратную сторону: потребители `List` (`List.module.less`) и `TableBasic`
+  (`TableBasic.module.less`) **понижают** `z-index` до `@z-index-step` через собственный класс
+  (`.list .listLoaderScreen`, `.tableBasic .spinnerWrapper .tableLoaderScreen`), чтобы лоадер
+  перекрывал только своё содержимое, а не `LightBox` / `ModalWindow`. Держится это на специфичности
+  вложенного селектора (0,2,0 и выше против 0,1,0 у `.loaderScreen`) — **не повышай специфичность правил
+  `.loaderScreen`** в `LoaderScreen.module.less`, иначе оба потребителя молча сломаются, и
+  unit-тесты этого не поймают (ловит только visual regression).
 
 ---
 
-## Ключевые особенности реализации
-
-### Два backdrop-класса по типу
+## Дизайн-токены
 
-```tsx
-{
-    [styles.loaderSmallBackdrop]: type === "small",
-    [styles.loaderMiddleBackdrop]: type === "middle",
-}
 ```
-
-- **`loaderSmallBackdrop`** и **`loaderMiddleBackdrop`** задают разную прозрачность/цвет бэкдропа. Middle обычно более явный (полноценный overlay), Small — лёгкий полупрозрачный.
-
-### Middle обёрнут в дополнительный `<div>`
-
-```tsx
-<div className={styles.loaderMiddleBackground}>
-    <LoaderMiddle />
-</div>
+--triplex-next-LoaderScreen-Small_Backdrop_Default    (подложка при type="small")
+--triplex-next-LoaderScreen-Middle_Backdrop_Default   (подложка при type="middle")
 ```
 
-Внутренний `background`-wrapper — для "карточки" вокруг точек LoaderMiddle.
-LoaderSmall — просто инлайн-элемент по центру.
-
-### Игнорирование `theme`/`size` для `type="middle"`
+Определены в `src/components/DesignTokens/components/LoaderScreen.ts`. Оба ссылаются на
+`ColorNeutralAlpha.30` (в тёмной теме — `ColorDarkNeutralAlpha.30`), то есть визуально совпадают, но
+разведены по типам намеренно — чтобы дизайн мог развести их независимо.
 
-`LoaderMiddle` API-less, так что `theme` и `size` принимаются, но не
-используются при `type === "middle"`. Не выкидывать их — потребители
-могут переключать `type` динамически без очистки props.
+Там же объявлен третий токен `--triplex-next-LoaderScreen-Middle_Background_Default`, который стилями
+LoaderScreen **не используется**: фон плашки `LoaderMiddle` берётся из
+`--triplex-next-Loader-Middle_Background_Default`, а точки — из
+`--triplex-next-Loader-Element_Background_Brand`. Токен остаётся в публичном наборе (его удаление —
+breaking change для темизации), но опираться на него не нужно.
 
-### Не forwardRef
-
-Компонент — `React.FC`, не `forwardRef`. Это отступление от общего правила
-библиотеки (`forwardRef обязателен`). Известный legacy-момент; для нового
-API-использования нужен ref — оборачивай снаружи.
+Собственных цветов текста у компонента нет — они приходят из `Text` (`Typography`).
 
 ---
 
 ## Инварианты
 
-- **`type: "small" | "middle"`** — строковый литерал. Не заменять на enum без breaking-change.
-- **`theme` / `size` применяются только при `type="small"`** — не разворачивать на `middle` без изменения Loader.
-- **`FC`, без forwardRef** — технический долг. Исправлять — breaking (меняется тип).
-- **Centered через flex внутри оверлея** — родитель должен иметь `position: relative` (или LoaderScreen должен использоваться на фоне самостоятельного блока).
-- **Бэкдроп встроен в LoaderScreen** — отдельно менять прозрачность нельзя, только переопределением CSS-переменной/через `className`.
+- **`forwardRef`** — обязателен, `ref` идёт на корневой `<div>` подложки (не на внутренний лоадер).
+- **Публичный API:** `LoaderScreen`, `ILoaderScreenProps`, `ILoaderScreenMiddleProps` экспортируются
+  через `src/components/LoaderScreen/index.ts`. `type` — строковый union `"small" | "middle"`,
+  а не enum; замена на enum — breaking change.
+- **`ILoaderScreenMiddleProps` не мёртвый тип** — на нём держатся `loaderScreenProps` в
+  `ModalWindowContent`, `LightBoxContent` и `LightBoxSideOverlay`. Удалять нельзя.
+- **`type` управляет и лоадером, и подложкой одновременно.** Разделять их на два props без задачи
+  не нужно: `TYPE_TO_BACKDROP_CLASS_NAME_MAP` в `LoaderScreen.tsx` держит это соответствие в одном месте.
+- **Тема `LoaderSmall` захардкожена как `ELoaderSmallTheme.BRAND`** — `NEUTRAL` через LoaderScreen
+  недоступна. Пробрасывание темы наружу — расширение публичного API.
+- **CSS-классы `loaderScreen`, `loaderSmallBackdrop`, `loaderMiddleBackdrop`** проверяются в
+  unit-тестах — переименование поймается прогоном. `loaderContent` и `description` тестами не
+  покрыты: они задают раскладку (ограничение ширины 380px и центрирование текста, см.
+  «Ограничения раскладки»), их переименование безопасно, но требует синхронной правки
+  `LoaderScreen.module.less`. `className` потребителя добавляется последним и базовые классы
+  не затирает.
+- **Корневой элемент — `<div>`**: смена тега ломает абсолютное позиционирование потребителей.
 
 ---
 
 ## Accessibility
 
-- `role="status"` и `aria-label="loading"` приходят от вложенных `LoaderSmall`/`LoaderMiddle` — LoaderScreen сам ARIA-атрибутов не добавляет.
-- `<div>`-оверлей **не блокирует клики** по контенту под ним — потребитель должен либо расположить LoaderScreen над блоком с `pointer-events`, либо использовать его в модалках/LightBox, где фокус и клики уже контролируются.
-- Для правильной семантики при глобальной загрузке — ставь `aria-busy="true"` на родительский контейнер.
-
----
-
-## Дизайн-токены
-
-Нет публичных переменных — цвета бэкдропа в `styles/LoaderScreen.module.less`.
+- **Роль `status` живёт на внутреннем лоадере**, а не на корневом `<div>`: `LoaderSmall` и
+  `LoaderMiddle` сами выставляют `role="status"` и `aria-label="loading"`. Корневая подложка —
+  презентационный контейнер без роли.
+- **`aria-label="loading"` захардкожен в компонентах семейства Loader** — это отклонение от правила
+  «не хардкодь aria-текст» (`docs/ai/codestyle.md`). Локализовать его через LoaderScreen нельзя;
+  фикс относится к `src/components/Loader/`.
+- **Фокус не перехватывается и не возвращается.** LoaderScreen не focus trap: элементы под подложкой
+  остаются в tab-порядке и доступны с клавиатуры, хотя визуально закрыты. Если взаимодействие нужно
+  запретить по-настоящему — делай это на уровне потребителя (`disabled`, `inert`, снятие контента
+  из DOM) или используй модальные компоненты.
+- **Мышь блокируется, клавиатура — нет.** Подложка перекрывает клики по контенту под собой просто
+  потому, что лежит сверху и имеет фон.
+- Потребитель может передать `role`, `aria-live`, `aria-busy` и другие атрибуты через spread на
+  корневой `<div>` — компонент их не переопределяет.
+- Анимация лоадеров непрерывная; `prefers-reduced-motion` семейством Loader не обрабатывается.
 
 ---
 
 ## Связанные компоненты
 
-- `Loader` (`LoaderSmall`, `LoaderMiddle`) — вложенные компоненты.
-- `ELoaderSmallTheme`, `EComponentSize` — enum'ы пропсов.
-- `List`, `LightBox`, `ModalWindow` — типовые потребители (оверлей над контентом).
+- `LoaderSmall` — рендерится при `type="small"` с темой `BRAND` и переданным `size`.
+- `LoaderMiddle` — рендерится при `type="middle"`; своих props не имеет.
+- `Gap` — фиксированные отступы 24px между лоадером, описанием и кнопками.
+- `Text` (`Typography`) — обёртка `description` (`ETextSize.B2`, выравнивание по центру).
+- `ModalWindowContent` — `isLoading` + `loaderScreenProps?: ILoaderScreenMiddleProps`.
+- `LightBoxContent`, `LightBoxSideOverlay` — то же через свои `loaderScreenProps`.
+- `List` — при `loading` кладёт `LoaderScreen type="middle"` поверх списка.
+- `TableBasic` — лоадер поверх тела таблицы.
+- `MultiselectField` — `LoaderScreen type="small"` внутри выпадающего списка.
 
 ---
 
 ## Stories
 
-`stories/Loaders/LoaderScreen/` — stories для обоих типов.
+Основные истории: `stories/Loaders/LoaderScreen/LoaderScreen.stories.tsx`
+Файлы примеров: `stories/Loaders/LoaderScreen/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контроль `type`, `size`, `description` и наличия кнопок |
+| `Default` | `DefaultExample.tsx` | Минимальный вариант: `type="small"`, `size="md"` в relative-обёртке |
+| `Types` | `TypesExample.tsx` | `small` и `middle` рядом |
+| `VisualTests` | — | Скриншот-состояния: `small` без текста, `middle` с описанием и кнопками, `middle` только с кнопками (анимации отключены) |
+
+`VisualTests` помечена `tags: ["!autodocs", "!dev"]` — скрыта из docs и из сайдбара, как у
+`LoaderMiddle` и `LoaderSmall`. Story ID (`loaders-loaderscreen--visual-tests`) при этом сохраняется,
+скриншот-регрессия по ней продолжает прогоняться.
 
 ---
 
@@ -131,4 +182,50 @@ API-использования нужен ref — оборачивай снар
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-08-06 | Создан документ. AI-рефакторинг: порядок импортов по `codestyle.md`, JSDoc на компоненте, props и `ILoaderScreenMiddleProps` (включая значение по умолчанию для `size`), подложка вынесена в `TYPE_TO_BACKDROP_CLASS_NAME_MAP`, `className` в `clsx` перенесён в конец. Unit-тесты расширены: все значения `EComponentSize`, игнорирование `size` при `type="middle"`, класс подложки по типу, отсутствие `description` / `controls`, мердж `className`, spread rest-props, `forwardRef`. Публичный API, DOM и стили не изменены. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Loaders/LoaderScreen/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderScreen, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <div style={{ position: "relative", height: "200px", width: "300px" }}>
+        <LoaderScreen type="small" size={EComponentSize.MD} />
+    </div>
+);
+```
+
+### Types
+
+`stories/Loaders/LoaderScreen/examples/TypesExample.tsx`
+
+```tsx
+import React from "react";
+import { LoaderScreen, EComponentSize } from "@sberbusiness/triplex-next";
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", gap: "32px", flexWrap: "wrap" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>small</div>
+            <div style={{ position: "relative", height: "200px", width: "300px" }}>
+                <LoaderScreen type="small" size={EComponentSize.MD} />
+            </div>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>middle</div>
+            <div style={{ position: "relative", height: "200px", width: "300px" }}>
+                <LoaderScreen type="middle" />
+            </div>
+        </div>
+    </div>
+);
+```
+

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>
+);
+```
+