@sberbusiness/triplex-next-mcp-server 1.40.0-beta → 1.41.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>
+);
+```
+