@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/ModalWindow.md

@@ -1,14 +1,10 @@
 ---
 component: ModalWindow
-category: Overlays
-figma-node: ""
-figma-file: ""
-related: [LightBox, Portal, Island, Page, TriggerClickOnKeyDownEvent, Button]
+category: ModalWindow
+related: [ModalWindowContent, ModalWindowHeader, ModalWindowBody, ModalWindowFooter, ModalWindowClose, ModalWindowViewManager, Portal, FocusTrap, Page, HeaderPage, FooterPage, Island, LoaderScreen]
 tokens:
-  - --modalWindow-screen-left
-  - --modalWindow-screen-width
-  - --modalWindow-screen-top
-  - --modal-window-top
+  - --triplex-next-ModalWindow-Backdrop_Background
+  - --triplex-next-ModalWindow-Background
 stories: stories/ModalWindow/ModalWindow.stories.tsx
 version: "1.0"
 ---
@@ -17,292 +13,486 @@ version: "1.0"
 
 ## Назначение
 
-Модальный диалог средних размеров — контент по центру экрана, backdrop-маска,
-focus-trap, Escape-close, анимированное появление/исчезновение (CSSTransition).
-Подкомпоненты: `Header` (на базе `HeaderPage`), `Body` (на базе `Island`),
-`Footer` (на базе `FooterPage`), `Content` (scroll-container с Page внутри),
-`Close` (Button с Escape-handler), и `ViewManager` (вычисляет CSS-переменные
-позиционирования).
+Модальное окно поверх контента страницы с затемнённым backdrop, ловушкой фокуса и блокировкой скролла `body`. Рендерится через `Portal` в собственный wrapper (`#ufs-modal-window-wrapper`), позиционируется по координатам, которые вычисляет вспомогательный `ModalWindowViewManager` (CSS-переменные `--modalWindow-screen-*`).
 
-Используй когда: нужен стандартный диалог (подтверждение, мастер, форма).
-Для полноэкранного — `LightBox`. Для поповера — `Overlay`.
+Используй когда: нужно вывести критичный контент (форму, подтверждение, мастер-форму), который должен прервать взаимодействие со страницей и удержать фокус.
 
 ---
 
-## Файловая структура
-
-```text
-src/components/ModalWindow/
-├── ModalWindow.tsx                           # forwardRef, Portal + CSSTransition + FocusTrap
-├── index.ts                                  # Barrel всех подкомпонентов
-├── components/
-│   ├── ModalWindowHeader.tsx                 # Обёртка над HeaderPage type=FIRST, + .Title
-│   ├── ModalWindowBody.tsx                   # Обёртка над Island TYPE_1, MD
-│   ├── ModalWindowContent.tsx                # <div> + <Page> + optional LoaderScreen
-│   ├── ModalWindowFooter.tsx                 # Обёртка над FooterPage type=FIRST, + .Description
-│   ├── ModalWindowClose.tsx                  # Button + TriggerClickOnKeyDownEvent(ESCAPE)
-│   └── ModalWindowViewManager.tsx            # CSS-переменные --modalWindow-screen-*
-└── styles/*.module.less
-```
-
----
-
-## Compound-структура
-
-```tsx
-<ModalWindow
-    isOpen={isOpen}
-    closeButton={<ModalWindow.Close onClick={onClose} />}
-    size={EComponentSize.MD}
-    onExited={onAnimationClose}
->
-    <ModalWindow.Content isLoading={loading}>
-        <ModalWindow.Header>
-            <ModalWindow.Header.Title>Заголовок</ModalWindow.Header.Title>
-        </ModalWindow.Header>
-
-        <ModalWindow.Body>
-            Основной контент...
-        </ModalWindow.Body>
-
-        <ModalWindow.Footer>
-            <ModalWindow.Footer.Description>Подпись</ModalWindow.Footer.Description>
-            <Button>ОК</Button>
-        </ModalWindow.Footer>
-    </ModalWindow.Content>
-</ModalWindow>
-```
+## Варианты и props
 
-**Важно:** сами подкомпоненты (`ModalWindowHeader`, `ModalWindowBody`,
-`ModalWindowContent`, `ModalWindowFooter`, `ModalWindowClose`) экспортируются
-из barrel, но **не навешаны** на `ModalWindow` через `Object.assign`. Нужно
-импортировать их **именованно**: `import { ModalWindow, ModalWindowHeader } from ...`.
+`ModalWindow` принимает все стандартные `React.HTMLAttributes<HTMLDivElement>` (они пробрасываются на корневой `role="dialog"` элемент) плюс собственные props.
 
----
+### Обязательные props
 
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `isOpen` | `boolean` | Открыто ли окно. Управляет монтированием Portal и анимацией `CSSTransition`. |
+| `children` | `React.ReactElement` | Контент окна. Обычно — `ModalWindowContent` с вложенными `ModalWindowHeader`, `ModalWindowBody`, `ModalWindowFooter`. |
+| `closeButton` | `React.ReactNode` | Кнопка закрытия (обычно `ModalWindowClose`). Рендерится внутри корневого dialog-элемента поверх контента. |
 
-### ModalWindow — `IModalWindowProps extends HTMLAttributes<HTMLDivElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `isOpen` | `boolean` | — (обязателен) | Управляемое состояние. |
-| `children` | `ReactElement` | — | Один корневой элемент (обычно `ModalWindowContent`). |
-| `closeButton` | `ReactNode` | — (обязателен) | Кнопка закрыть, вставляется рядом с `children`. Обычно `<ModalWindowClose onClick={onClose} />`. |
-| `focusTrapProps` | `FocusTrapProps` | — | Переопределение параметров `focus-trap-react`. |
-| `onExited` | `() => void` | — | Callback после завершения анимации закрытия. |
-| `size` | `EComponentSize` | `MD` | Размер модалки (ширина). |
-| `topPosition` | `number` | `100` | Отступ сверху в px. Пишется в CSS-переменную `--modal-window-top`. |
-| `containerClassName` | `string` | — | className внешнего контейнера (с backdrop'ом). |
-| `className`, `...HTMLDivAttributes` | — | — | Стандартные, идут на `div[role="dialog"]`. |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер окна: `SM` / `MD` / `LG`. Определяет `max-width` контента и `min-height` body. |
+| `topPosition` | `number` | `100` | Отступ от верхней границы экрана, px. Прокидывается в CSS-переменную `--modal-window-top`. |
+| `containerClassName` | `string` | — | Кастомный класс на контейнер (внешний `div` с `position: fixed`, который содержит backdrop и dialog). |
+| `className` | `string` | — | Кастомный класс на корневой `role="dialog"` элемент. |
+| `focusTrapProps` | `FocusTrapProps` | — | Свойства `focus-trap-react`. Внутренние `allowOutsideClick: true` и `preventScroll: true` мерджатся с пользовательскими `focusTrapOptions`. |
+| `onExited` | `() => void` | — | Callback после завершения анимации закрытия (`CSSTransition.onExited`). |
 
-### ModalWindowClose — `IModalWindowCloseProps extends Omit<IButtonSecondaryProps, "size" | "theme" | "icon">`
+### Ограничения использования
 
-- Кнопка с иконкой `CrossStrokeSrvIcon20` в правом-верхнем углу модалки.
-- **Автоматически триггерит клик по Escape** через `TriggerClickOnKeyDownEvent` (eventKeyCode=ESCAPE).
-- `size=MD` и `theme=SECONDARY` захардкожены — не переопределить.
-- **Title "Закрыть"** — хардкод русского, i18n-debt.
+- **Controlled-only.** Состояние открытия полностью контролируется потребителем через `isOpen`. Компонент сам не закрывается на клик по backdrop'у — обработчик `Escape` живёт в `ModalWindowClose`, не в `ModalWindow`.
+- **`children` — единый `React.ReactElement`.** Это требование `CSSTransition` для анимирования одного дочернего узла. Не передавай массив или фрагмент — оборачивай контент в `ModalWindowContent`.
+- **Rendering lifecycle.** При первом рендере синхронно создаётся локальный `mountNode` под `#ufs-modal-window-wrapper` (через `useState` lazy initializer) — это нужно, чтобы `FocusTrap` нашёл tabbable-узлы при активации. Сама модалка показывается/скрывается через `CSSTransition` (`mountOnEnter` / `unmountOnExit`); body-классы `modal-open` + `no-hash-overflow-hidden` ставятся в `onEnter` и снимаются в `onExited` (≈300ms на анимацию). При unmount-е компонента `mountNode` отвязывается от DOM.
+- **`ModalWindowViewManager` рендерится всегда** рядом с Portal — он отвечает за вычисление координат рамки, в которой живёт окно (через `useResizeDetector`), и инжектит `<style>` с CSS-переменными `--modalWindow-screen-{left,top,width}` в `:root`. Не пытайся убрать его из дерева.
 
-### ModalWindowHeader — `IModalWindowHeaderProps extends Omit<IHeaderPageTypeFirstProps, "children" | "type">`
-
-- Обёртка над `<HeaderPage type={FIRST}>`.
-- Статический `.Title = HeaderPage.Title`.
+---
 
-### ModalWindowBody — `IModalWindowBodyProps extends IIslandProps`
+## Дизайн-токены
 
-- Обёртка над `<Island type={TYPE_1} size={MD}>` с дополнительным классом `modalWindowBody`.
-- **Хардкод TYPE_1/MD** — если нужен другой тип/размер Island, текущий API не позволяет.
+```text
+--triplex-next-ModalWindow-Backdrop_Background
+--triplex-next-ModalWindow-Background
+```
 
-### ModalWindowContent — `IModalWindowContentProps extends HTMLAttributes<HTMLDivElement>`
+Помимо токенов, компонент инжектит и читает несколько runtime CSS-переменных, не относящихся к дизайн-системе:
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `isLoading` | `boolean` | Показывает `LoaderScreen type="middle"` над содержимым. |
-| `loadingTitle` | `ReactNode` | Подпись под спиннером. |
-
-Внутри — обёртывает `children` в `<Page>`. Scroll-контейнер.
+```text
+--modalWindow-screen-left   # координата слева, выставляется ModalWindowViewManager
+--modalWindow-screen-top    # высота шапки лайаута, выставляется ModalWindowViewManager
+--modalWindow-screen-width  # ширина области, выставляется ModalWindowViewManager
+--modal-window-top          # отступ контента от верхней границы окна (= prop topPosition)
+```
 
-### ModalWindowFooter — `IModalWindowFooterProps extends Omit<IFooterPageTypeFirstProps, "children" | "type">`
+Имена этих переменных — публичный контракт для лайаута приложения, не переименовывать без согласования.
 
-- Обёртка над `<FooterPage type={FIRST}>`.
-- Статический `.Description = FooterPage.Description`.
+---
 
-### ModalWindowViewManager
+## Инварианты
 
-Рендерится автоматически внутри `ModalWindow`. Отдельно использовать не нужно (но экспортирован для nuance-сценариев).
+- **`forwardRef`** на `ModalWindow` пробрасывает ref на корневой `role="dialog"` `<div>` — не убирать.
+- **`role="dialog"` + `aria-modal="true"`** на корневом dialog-элементе — не менять.
+- **Body-классы `modal-open` + `no-hash-overflow-hidden`** добавляются при открытии и убираются при закрытии и unmount. Имена согласованы с внешним лайаутом сббола, не переименовывать.
+- **Portal-wrapper id `ufs-modal-window-wrapper`** и класс `ufs-modal-window-portal-node` — публичный контракт, на него могут опираться e2e-тесты и внешние стили.
+- **`ModalWindowViewManager` node id `modalWindowViewManagerNodeId` (`"modalWindowViewManagerNodeId"`)** — публичный контракт лайаута: контейнер `<div id="modalWindowViewManagerNodeId">` создаётся вне React-дерева приложения и используется как граница позиционирования.
+- **Animation timeout 300ms** (`animationExitTime`) — синхронизирован с CSS-анимацией `modalWindowContentAnimationOnExit` и `keyframes-fadeOut`. Менять только синхронно с less-стилями.
+- **Barrel export в `src/components/ModalWindow/index.ts`** — все семь экспортов (`ModalWindow`, `ModalWindowBody`, `ModalWindowClose`, `ModalWindowContent`, `ModalWindowFooter`, `ModalWindowHeader`, `ModalWindowViewManager`) — публичный API.
+- **`displayName = "ModalWindow"`** и displayName всех субкомпонентов — публичный API React DevTools/snapshot-тестов.
 
 ---
 
-## Ключевые особенности реализации
+## Accessibility
 
-### Два DOM-контейнера: `#ufs-modal-window-wrapper` + свой `portal-node`
+- **Роль и aria.** Корневой dialog-элемент рендерится с `role="dialog"` и `aria-modal="true"`. Дополнительные aria-атрибуты (`aria-label`, `aria-labelledby`, `aria-describedby`) потребитель **обязан** передать сам через `...rest` — компонент не хардкодит текст, библиотека мультиязычная.
+- **Focus trap.** Активная ловушка фокуса (`focus-trap-react`) включается синхронно с `isOpen`. По умолчанию: `allowOutsideClick: true` (клик за пределами не сбрасывает trap, но не блокируется), `preventScroll: true` (фокус не скроллит layout), `fallbackFocus` указывает на сам `role="dialog"` узел (у него `tabIndex={-1}`). Расширить настройки можно через `focusTrapProps.focusTrapOptions`.
+- **Почему нужен `fallbackFocus`.** Ловушка активируется синхронно при открытии. Если в этот момент внутри dialog ещё нет ни одного tabbable-узла (контент грузится асинхронно, показан лоадер, `closeButton` отрисуется тиком позже), `focus-trap` без fallback падает с `"must have at least one container with at least one tabbable node"`. `fallbackFocus` на dialog снимает это падение — фокус временно встаёт на сам контейнер.
+- **Закрытие по Escape.** Обработчик ESC живёт в `ModalWindowClose` (через `TriggerClickOnKeyDownEvent` + `KeyDownListener` на window keydown). Если `closeButton` заменён на кастомный — потребитель сам реализует ESC-handler.
+- **Возврат фокуса.** За возврат фокуса на триггер при закрытии отвечает `focus-trap-react` (стандартное поведение). Если триггер был внутри другой ловушки фокуса — настрой `returnFocusOnDeactivate` через `focusTrapProps`.
+- **Блокировка фоновой страницы.** Body-классы `modal-open` + `no-hash-overflow-hidden` блокируют скролл страницы. Это визуальная блокировка, не aria — для технологий screen-reader полагаемся на `aria-modal="true"`.
 
-```ts
-let wrapperNode = document.querySelector<HTMLDivElement>(`#${modalNodeName}-wrapper`);
-if (!wrapperNode) { /* create & append to body */ }
+---
 
-mountNode.current = document.createElement("div");
-mountNode.current.className = `${modalNodeName}-portal-node`;
-wrapperNode.appendChild(mountNode.current);
-```
+## Связанные компоненты
 
-- **Каждая открытая ModalWindow создаёт свой `.portal-node`** внутри общего `#ufs-modal-window-wrapper`. Это позволяет держать несколько модалок параллельно (хотя обычно одна).
-- При закрытии portal-node удаляется, wrapper — остаётся (для повторного использования).
-- **ID wrapper'а `ufs-modal-window-wrapper`** — известная "точка привязки" для интеграции с Layout'ом (сббол).
+Все экспортируются из `@sberbusiness/triplex-next` через barrel `src/components/ModalWindow/index.ts`:
 
-### Body-классы `modal-open` + `no-hash-overflow-hidden`
+- **`ModalWindowContent`** — контейнер контента. Оборачивает дочерние секции в `Page` (`triplex-next/Page`). Имеет `isLoading?: boolean` и `loaderScreenProps?: ILoaderScreenMiddleProps` — при `isLoading` поверх контента показывается `LoaderScreen` типа `middle`; кастомизация лоадера (текст, кнопки и др.) передаётся через `loaderScreenProps`. Свой `displayName`. Свои props через интерфейс `IModalWindowContentProps` — экспортируется.
+- **`ModalWindowHeader`** — заголовок. Тривиальная обёртка над `HeaderPage` с фиксированным `type=FIRST` и доп. отступом справа под кнопку закрытия (через less). Экспонирует статическое поле `Title = HeaderPage.Title`. Тип `IModalWindowHeaderProps` (Omit `children`/`type` от `IHeaderPageTypeFirstProps`).
+- **`ModalWindowBody`** — тело. Тривиальная обёртка над `Island` с фиксированными `type=TYPE_1` и `size=MD`. Тип `IModalWindowBodyProps extends IIslandProps`.
+- **`ModalWindowFooter`** — футер. Тривиальная обёртка над `FooterPage` с фиксированным `type=FIRST`. Экспонирует статическое поле `Description = FooterPage.Description`.
+- **`ModalWindowClose`** — кнопка закрытия. Обёртка над `Button` (`theme=SECONDARY`, `size=MD`, иконка `CrossStrokeSrvIcon20`) внутри `TriggerClickOnKeyDownEvent` с `EVENT_KEY_CODES.ESCAPE`. **Текст `title` не имеет дефолта внутри компонента** — библиотека мультиязычная, локализованную подсказку (например, `title="Закрыть"`) передаёт потребитель через props. Тип `IModalWindowCloseProps` (Omit `size`/`theme`/`icon` от `IButtonSecondaryProps`).
+- **`ModalWindowViewManager`** — невидимый компонент-сенсор. Создаёт DOM-ноду `<div id="modalWindowViewManagerNodeId">` (если её нет в `body`) и рендерит туда через `Portal` resize-сенсор + `<style>`-инжект CSS-переменных `--modalWindow-screen-*` в `:root`. Подключается автоматически из `ModalWindow`; экспортируется отдельно для случая, когда лайаут хочет позиционировать ноду вручную (например, рисовать модалку только в области рабочей зоны без шапки).
 
-```ts
-const bodyClassNameModalOpen = ["modal-open", "no-hash-overflow-hidden"];
-```
+---
 
-- При открытии — **добавляются на `body`** (не на `documentElement`, в отличие от LightBox).
-- Класс `modal-open` — от внешнего Layout (сббол), блюрит фоновый контент.
-- Снимаются при закрытии/unmount.
+## Stories
 
-### Animation — `CSSTransition` + `appear` + `unmountOnExit`
+Основные истории: `stories/ModalWindow/ModalWindow.stories.tsx`
+Файлы примеров: `stories/ModalWindow/examples/`
 
-```tsx
-<CSSTransition
-    in={isOpen}
-    timeout={animationExitTime} // 300
-    classNames="global-modalWindowTransition"
-    appear enter exit
-    onEnter={handleOpenModal}       // добавить body-классы
-    onExited={handleCloseModal}     // удалить body-классы + unmount portal + onExited()
-    mountOnEnter
-    unmountOnExit
->
-```
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | — | Интерактивный контроль `isLoading` и `size`; кнопки эмитят `action()` |
+| `Default` | `Default.tsx` | Минимальный пример: открытие/закрытие, заголовок, body, футер |
+| `Sizes` | `Sizes.tsx` | Размеры `SM` / `MD` / `LG`, для каждого — отдельный триггер |
+| `WithLongContent` | `WithLongContent.tsx` | Длинный контент с прилипающими header/footer |
+| `LoadingState` | `LoadingState.tsx` | Состояние загрузки (`isLoading=true` + `loaderScreenProps`) |
 
-- **classNames `global-modalWindowTransition`** — строка, не CSS-Modules. Соответствующие CSS-правила живут в глобальных стилях/index.less.
-- `appear` — чтобы `onEnter` сработал на самой первой анимации.
-- `unmountOnExit` — DOM-элемент удаляется после анимации, `renderPortal` сбрасывается в false.
+Все стори, кроме скриншотных проверок, исключены из визуальных тестов на уровне `meta.parameters.testRunner: { skip: true }` — модалка анимируется и реализована через Portal вне Storybook canvas, скриншоты были бы пустыми.
 
-### `renderPortal` state и двойное монтирование
+---
 
-```ts
-const [renderPortal, setRenderPortal] = useState(false);
-useEffect(() => { if (isOpen) { mountPortalNode(); setRenderPortal(true); } }, [isOpen]);
-```
+## История изменений
 
-- До открытия `renderPortal=false` → ранний return `null` → Portal не рендерится.
-- При `isOpen=true` — создаётся mountNode (imperatively), ставится `renderPortal=true` — затем react рендерит Portal.
-- **На повторные открытия** — state остаётся true после закрытия (handleCloseModal сбрасывает в false), и при следующем `isOpen=true` — снова создаётся mountNode.
+| Дата | Изменение |
+|---|---|
+| 2026-05-04 | Создан документ. AI-рефакторинг: добавлены JSDoc на компоненты и props, экспортирован `IModalWindowContentProps`, унифицированы импорты в `ModalWindowClose`, добавлен `displayName` субкомпонентам. Stories мигрированы в modern pattern (папка `examples/`, `?raw`, публичные импорты). Добавлены unit-тесты на `ModalWindowContent`, `ModalWindowClose`, `ModalWindowBody`, `ModalWindowHeader`, `ModalWindowFooter`. |
+| 2026-05-06 | Возвращён `forwardRef` в `ModalWindowContent` и `ModalWindowViewManager` (обязательный инвариант проекта). Удалён захардкоженный `title="Закрыть"` из `ModalWindowClose` — для мультиязычной библиотеки текст подсказки должен приходить от потребителя. **Breaking:** теперь `title` не подставляется автоматически. |
+| 2026-06-25 | Fix: устранено падение `focus-trap` `"must have at least one container with at least one tabbable node"` при открытии модалки без tabbable-узлов (асинхронный контент/лоадер). Добавлены `fallbackFocus` на dialog-узел и `tabIndex={-1}` на `role="dialog"`. Регрессия проявилась после синхронной активации ловушки в рефакторинге 1.28.0. Добавлен интеграционный тест на реальном `focus-trap`. |
+| 2026-06-30 | Fix: модалка не отображалась под React 18 `StrictMode`. На искусственном unmount/mount-цикле cleanup в `useEffect` открепляет портальный `mountNode`, а инициализатор `useState` повторно не вызывается — узел оставался вне DOM. Теперь `useEffect` при (повторном) mount возвращает узел в wrapper, если тот откреплён. Wrapper вынесен в `getOrCreateWrapperNode`. Добавлен регрессионный тест на реальном `Portal` (`ModalWindow.strictMode.test.tsx`). |
 
-### `topPosition` через CSS-переменную
+---
 
-```tsx
-const topPositionStyle = { "--modal-window-top": `${topPosition}px` };
-```
+## Примеры использования
 
-- Default 100px. Команды могут переопределять, передавая `topPosition`.
-- CSS-переменная именно `--modal-window-top` (kebab с дефисами), **не в naming-convention `--triplex-next-*`**. Это исторический паттерн, не переименовывать.
+### Default
 
-### ModalWindowClose с Escape-handler
+`stories/ModalWindow/examples/Default.tsx`
 
 ```tsx
-<TriggerClickOnKeyDownEvent eventKeyCode={EVENT_KEY_CODES.ESCAPE} targetRef={ref}>
-    <Button ref={ref} icon={<CrossIcon />} ... />
-</TriggerClickOnKeyDownEvent>
+import React, { useState } from "react";
+import {
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    ETextSize,
+    ETitleSize,
+    Gap,
+    ModalWindow,
+    ModalWindowBody,
+    ModalWindowClose,
+    ModalWindowContent,
+    ModalWindowFooter,
+    ModalWindowHeader,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleOpen = () => setIsOpen(true);
+    const handleClose = () => setIsOpen(false);
+
+    return (
+        <div>
+            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleOpen}>
+                Открыть модальное окно
+            </Button>
+
+            <ModalWindow
+                isOpen={isOpen}
+                size={EComponentSize.MD}
+                closeButton={<ModalWindowClose onClick={handleClose} title="Закрыть" />}
+                onExited={() => {}}
+            >
+                <ModalWindowContent>
+                    <ModalWindowHeader>
+                        <ModalWindowHeader.Title>
+                            <ModalWindowHeader.Title.Content>
+                                <Title tag="h1" size={ETitleSize.H1}>
+                                    Заголовок окна
+                                </Title>
+                            </ModalWindowHeader.Title.Content>
+                        </ModalWindowHeader.Title>
+                    </ModalWindowHeader>
+
+                    <ModalWindowBody>
+                        <Text tag="div" size={ETextSize.B2}>
+                            Содержимое модального окна. Здесь может быть любой контент: формы, текст, изображения и
+                            другие элементы интерфейса.
+                        </Text>
+                        <Gap size={16} />
+                        <Text tag="div" size={ETextSize.B2}>
+                            Фокус автоматически удерживается внутри окна, нажатие Escape закрывает его.
+                        </Text>
+                    </ModalWindowBody>
+
+                    <ModalWindowFooter>
+                        <ModalWindowFooter.Description>
+                            <ModalWindowFooter.Description.Controls>
+                                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                            </ModalWindowFooter.Description.Controls>
+                        </ModalWindowFooter.Description>
+                    </ModalWindowFooter>
+                </ModalWindowContent>
+            </ModalWindow>
+        </div>
+    );
+};
 ```
 
-- Escape нажатие → имитирует click на кнопку → `onClick` → закрытие.
-- Кнопка **обязательно должна быть в дереве** (не опциональна). Если `closeButton` не передан — TS ошибка (prop обязателен).
+### Sizes
 
-### `ModalWindowViewManager` — CSS-переменные позиционирования
+`stories/ModalWindow/examples/Sizes.tsx`
 
-Аналогично `LightBoxViewManager`: пишет в `:root` (именно в `:root`, а не на `lightBoxMountNode`):
-
-```css
-:root {
-    --modalWindow-screen-left: ...;
-    --modalWindow-screen-width: ...;
-    --modalWindow-screen-top: ...;
+```tsx
+import React, { useState } from "react";
+import {
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    ETextSize,
+    ETitleSize,
+    MobileView,
+    ModalWindow,
+    ModalWindowBody,
+    ModalWindowClose,
+    ModalWindowContent,
+    ModalWindowFooter,
+    ModalWindowHeader,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: EComponentSize;
+    label: string;
 }
-```
-
-- Default id `modalWindowViewManagerNodeId` создаётся в body. Используется для позиционирования относительно окна (если есть глобальный sidebar, Layout может переопределить эту node).
-- **Отличие от LightBox**: переменные в `:root` — глобальные; любая ModalWindow подстраивается.
-
-### `focus-trap-react` v11 (используется `FocusTrap` как default, не `.FocusTrap`)
 
-```ts
-import { FocusTrap, FocusTrapProps } from "focus-trap-react";
+const SizeItem = ({ size, label }: ISizeItemProps) => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleOpen = () => setIsOpen(true);
+    const handleClose = () => setIsOpen(false);
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>{label}</div>
+            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleOpen}>
+                Открыть {label}
+            </Button>
+
+            <ModalWindow
+                isOpen={isOpen}
+                size={size}
+                closeButton={<ModalWindowClose onClick={handleClose} title="Закрыть" />}
+            >
+                <ModalWindowContent>
+                    <ModalWindowHeader>
+                        <ModalWindowHeader.Title>
+                            <ModalWindowHeader.Title.Content>
+                                <MobileView
+                                    fallback={
+                                        <Title tag="h1" size={ETitleSize.H1}>
+                                            Размер {label}
+                                        </Title>
+                                    }
+                                >
+                                    <Title tag="h2" size={ETitleSize.H2}>
+                                        Размер {label}
+                                    </Title>
+                                </MobileView>
+                            </ModalWindowHeader.Title.Content>
+                        </ModalWindowHeader.Title>
+                    </ModalWindowHeader>
+
+                    <ModalWindowBody>
+                        <Text tag="div" size={ETextSize.B2}>
+                            Пример модального окна размера {label}.
+                        </Text>
+                    </ModalWindowBody>
+
+                    <ModalWindowFooter>
+                        <ModalWindowFooter.Description>
+                            <ModalWindowFooter.Description.Controls>
+                                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                            </ModalWindowFooter.Description.Controls>
+                        </ModalWindowFooter.Description>
+                    </ModalWindowFooter>
+                </ModalWindowContent>
+            </ModalWindow>
+        </div>
+    );
+};
+
+export const Sizes = () => (
+    <div style={{ display: "flex", gap: 16, flexWrap: "wrap" }}>
+        <SizeItem size={EComponentSize.SM} label="SM" />
+        <SizeItem size={EComponentSize.MD} label="MD" />
+        <SizeItem size={EComponentSize.LG} label="LG" />
+    </div>
+);
 ```
 
-**Внимание**: старые версии использовали default-import. Не ломать.
+### WithLongContent
 
-### ModalWindowBody хардкодит Island type=TYPE_1, size=MD
+`stories/ModalWindow/examples/WithLongContent.tsx`
 
 ```tsx
-<Island type={EIslandType.TYPE_1} size={EComponentSize.MD} {...islandProps}>
+import React, { useState } from "react";
+import {
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    ETextSize,
+    ETitleSize,
+    Gap,
+    MobileView,
+    ModalWindow,
+    ModalWindowBody,
+    ModalWindowClose,
+    ModalWindowContent,
+    ModalWindowFooter,
+    ModalWindowHeader,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+const PARAGRAPHS = Array.from({ length: 10 }, (_, i) => i + 1);
+
+export const WithLongContent = () => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleOpen = () => setIsOpen(true);
+    const handleClose = () => setIsOpen(false);
+
+    return (
+        <div>
+            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleOpen}>
+                Открыть с длинным контентом
+            </Button>
+
+            <ModalWindow
+                isOpen={isOpen}
+                size={EComponentSize.MD}
+                closeButton={<ModalWindowClose onClick={handleClose} title="Закрыть" />}
+            >
+                <ModalWindowContent>
+                    <ModalWindowHeader>
+                        <ModalWindowHeader.Title>
+                            <ModalWindowHeader.Title.Content>
+                                <MobileView
+                                    fallback={
+                                        <Title tag="h1" size={ETitleSize.H1}>
+                                            Длинный контент
+                                        </Title>
+                                    }
+                                >
+                                    <Title tag="h2" size={ETitleSize.H2}>
+                                        Длинный контент
+                                    </Title>
+                                </MobileView>
+                            </ModalWindowHeader.Title.Content>
+                        </ModalWindowHeader.Title>
+                    </ModalWindowHeader>
+
+                    <ModalWindowBody>
+                        {PARAGRAPHS.map((n, i) => (
+                            <React.Fragment key={n}>
+                                <Text tag="div" size={ETextSize.B2}>
+                                    Параграф {n}. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
+                                    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+                                    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+                                </Text>
+                                {i < PARAGRAPHS.length - 1 && <Gap size={16} />}
+                            </React.Fragment>
+                        ))}
+                    </ModalWindowBody>
+
+                    <ModalWindowFooter>
+                        <ModalWindowFooter.Description>
+                            <ModalWindowFooter.Description.Controls>
+                                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                            </ModalWindowFooter.Description.Controls>
+                        </ModalWindowFooter.Description>
+                    </ModalWindowFooter>
+                </ModalWindowContent>
+            </ModalWindow>
+        </div>
+    );
+};
 ```
 
-`...islandProps` идут **после** `type`/`size` — потребитель теоретически может переопределить через props. Но это не публичная часть API (not документированная). Не полагайся.
-
----
-
-## Инварианты
-
-- **`isOpen` управляемый, `children` — один `ReactElement`, `closeButton` — обязателен** — публичный контракт.
-- **ID DOM-контейнеров: `ufs-modal-window-wrapper`, `modalWindowViewManagerNodeId`** — **интеграционные** точки с внешним Layout'ом. Не переименовывать.
-- **Body-классы `modal-open`, `no-hash-overflow-hidden`** — контракт с внешним Layout; изменение — регрессия фонового блюра.
-- **Escape → closeButton click** через `TriggerClickOnKeyDownEvent` — поведенческий контракт `ModalWindowClose`.
-- **CSS-переменная `--modal-window-top`** (kebab-case, не `--triplex-next-ModalWindow-Top`) — публичная, исторический naming.
-- **`CSSTransition classNames="global-modalWindowTransition"`** — строковый класс, нет в CSS-Modules. Стили в глобальном файле.
-- **`ModalWindowHeader/Footer` — обёртки над HeaderPage/FooterPage type=FIRST** — не поддерживают TYPE_2/TYPE_3.
-- **`ModalWindowBody` хардкодит Island TYPE_1/MD** — кастомизация через props не публична.
-- **`ModalWindow.Close` title="Закрыть" + `TriggerClickOnKeyDownEvent` eventKeyCode=ESCAPE** — i18n-debt (rus-hardcode).
-- **`forwardRef<HTMLDivElement>`** — корневая node (dialog), но **подкомпоненты не являются слотами через Object.assign**.
-- **ViewManager пишет в `:root`**, не в scoped-элемент — глобально влияет на любой ModalWindow.
-
----
-
-## Accessibility
-
-- `role="dialog"` + `aria-modal="true"` — есть на корне.
-- `FocusTrap` активен пока `isOpen` — фокус удерживается внутри.
-- `allowOutsideClick: true` — outside click не ломает trap; закрытие делается **только через `closeButton`** или Escape.
-- **Нет `aria-labelledby`/`aria-describedby` по умолчанию** — потребитель должен добавить через `...rest` или передать `aria-label`.
-- `ModalWindowClose` — Button с `title="Закрыть"` (рус), tabIndex нормальный.
-- Escape обрабатывается через TriggerClickOnKeyDownEvent — глобально на window (см. `KeyDownListener-AI`).
-
----
+### LoadingState
 
-## Дизайн-токены
+`stories/ModalWindow/examples/LoadingState.tsx`
 
-Runtime CSS-переменные:
-```
---modalWindow-screen-left, --modalWindow-screen-width, --modalWindow-screen-top  — от ViewManager
---modal-window-top                                                                — от topPosition prop
+```tsx
+import React, { useState } from "react";
+import {
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    ETextSize,
+    ETitleSize,
+    MobileView,
+    ModalWindow,
+    ModalWindowBody,
+    ModalWindowClose,
+    ModalWindowContent,
+    ModalWindowFooter,
+    ModalWindowHeader,
+    Text,
+    Title,
+} from "@sberbusiness/triplex-next";
+
+export const LoadingState = () => {
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleOpen = () => setIsOpen(true);
+    const handleClose = () => setIsOpen(false);
+
+    return (
+        <div>
+            <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleOpen}>
+                Открыть с загрузкой
+            </Button>
+
+            <ModalWindow
+                isOpen={isOpen}
+                size={EComponentSize.MD}
+                closeButton={<ModalWindowClose onClick={handleClose} title="Закрыть" />}
+            >
+                <ModalWindowContent isLoading loaderScreenProps={{ description: "Загрузка данных..." }}>
+                    <ModalWindowHeader>
+                        <ModalWindowHeader.Title>
+                            <ModalWindowHeader.Title.Content>
+                                <MobileView
+                                    fallback={
+                                        <Title tag="h1" size={ETitleSize.H1}>
+                                            Загрузка
+                                        </Title>
+                                    }
+                                >
+                                    <Title tag="h2" size={ETitleSize.H2}>
+                                        Загрузка
+                                    </Title>
+                                </MobileView>
+                            </ModalWindowHeader.Title.Content>
+                        </ModalWindowHeader.Title>
+                    </ModalWindowHeader>
+
+                    <ModalWindowBody>
+                        <Text tag="div" size={ETextSize.B2}>
+                            Этот контент скрыт под индикатором загрузки.
+                        </Text>
+                    </ModalWindowBody>
+
+                    <ModalWindowFooter>
+                        <ModalWindowFooter.Description>
+                            <ModalWindowFooter.Description.Controls>
+                                <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                                <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD} onClick={handleClose}>
+                                    Button text
+                                </Button>
+                            </ModalWindowFooter.Description.Controls>
+                        </ModalWindowFooter.Description>
+                    </ModalWindowFooter>
+                </ModalWindowContent>
+            </ModalWindow>
+        </div>
+    );
+};
 ```
 
-Визуал — от `Island` (внутри Body) и ThemeProvider scope (scopeClassName на контейнере).
-
----
-
-## Связанные компоненты
-
-- `LightBox` — полноэкранный аналог.
-- `Portal` — используется для render'а.
-- `Island` / `Page` / `HeaderPage` / `FooterPage` — базовые примитивы для Body/Content/Header/Footer.
-- `Button` — в ModalWindowClose.
-- `TriggerClickOnKeyDownEvent` — для Escape handling.
-- `LoaderScreen` — loader в Content.
-- `focus-trap-react`, `react-transition-group` — внешние зависимости.
-
----
-
-## Stories
-
-`stories/ModalWindow/ModalWindow.stories.tsx`
-Примеры: `stories/ModalWindow/examples/`
-
----
-
-## История изменений
-
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |