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

package/bundle/components/Overlay.md

@@ -1,237 +1,338 @@
 ---
 component: Overlay
-category: Overlays
-figma-node: ""
-figma-file: ""
-related: [SideOverlay, ModalWindow, LightBox]
-tokens: [triplex-next-Overlay-Panel_Background]
+category: Overlay
+related: [OverlayBase, OverlayMask, OverlayPanel, LightBox, TopOverlay, ModalWindow, DropdownMobile]
+tokens: [--triplex-next-Overlay-Background, --triplex-next-Overlay-Panel_Background]
 stories: stories/Overlay/Overlay.stories.tsx
-version: "1.0"
+version: "1.34.0"
 ---
 
 # Overlay
 
 ## Назначение
 
-Низкоуровневый строительный блок для всплывающих панелей с CSS-анимацией
-выезда из четырёх направлений (top/right/bottom/left). Сам компонент —
-**stage manager** жизненного цикла (opening → opened → closing → closed)
-и контейнер с position absolute/fixed; визуальная панель и затемнение —
-`Overlay.Panel` и `Overlay.Mask`, рендерятся через render-prop'ы.
+Затемняющий слой с выезжающей из выбранной стороны панелью контента. Применяется
+для отображения дополнительного контента поверх элемента (`absolute`, по
+умолчанию) или поверх всей страницы (`fixed`). Анимация открытия/закрытия —
+CSS-transition панели (`transform`) и маски (`opacity`).
 
-Используй когда: строишь свой нестандартный overlay (drawer, side-sheet)
-и нужны хуки на фазах жизненного цикла. Для готовых решений —
-`SideOverlay` (на основе Overlay), `ModalWindow`, `LightBox`.
+Компонент построен как семейство: корневой `Overlay` (контейнер + управление
+жизненным циклом через `OverlayBase`) со статическими `Overlay.Mask`
+(кликабельный фон) и `Overlay.Panel` (выезжающая панель). Контент задаётся
+render-функцией `children`, которая получает состояние оверлея.
 
----
-
-## Файловая структура
-
-```text
-src/components/Overlay/
-├── Overlay.tsx       # FC + slots; контейнер-обёртка, локальный closing для css-класса
-├── OverlayBase.tsx   # FC; render-prop, lifecycle (opening/closing), enum direction
-├── OverlayMask.tsx   # forwardRef; полупрозрачный фон
-├── OverlayPanel.tsx  # forwardRef; выезжающая панель + onTransitionEnd
-├── index.ts          # Barrel: Overlay, OverlayBase, OverlayMask, OverlayPanel + enum
-└── styles/Overlay.module.less
-```
+Используй когда: нужна выезжающая боковая/верхняя/нижняя панель (drawer,
+off-canvas) над контейнером или страницей.
+Не используй когда: нужно модальное окно по центру — используй `ModalWindow`;
+нужен полноэкранный слой просмотра — `LightBox`.
 
 ---
 
-## Compound-структура (через render-prop)
-
-```tsx
-<Overlay
-    direction={EOverlayDirection.RIGHT}
-    opened={opened}
-    setOpened={setOpened}
-    onOpen={...}
-    onClose={...}
-    fixed
->
-    {(provided) => (
-        <>
-            <Overlay.Mask opened={provided.opened} onClick={() => provided.setOpened(false)} />
-            <Overlay.Panel {...provided}>
-                {/* контент */}
-            </Overlay.Panel>
-        </>
-    )}
-</Overlay>
-```
-
-`Overlay.children` — **функция**, не ReactNode. Получает `IOverlayChildrenProvideProps`.
+## Варианты и props
 
----
+### `Overlay` — обязательные props
 
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `direction` | `EOverlayDirection` | Сторона, из которой выезжает панель: `RIGHT` / `LEFT` / `TOP` / `BOTTOM`. По умолчанию в `OverlayBase` — `RIGHT` |
+| `opened` | `boolean` | Управляемое состояние открытости. Изменение запускает анимацию открытия/закрытия |
+| `setOpened` | `(opened: boolean) => void` | Сеттер `opened`, прокидывается в `provideProps` для управления изнутри панели |
+| `children` | `(provideProps) => React.ReactElement` | Render-функция контента. См. «provideProps» ниже |
 
-### Overlay — `IOverlayProps extends IOverlayBaseProps, Omit<HTMLAttributes<HTMLDivElement>, "children">`
+### `Overlay` — опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `direction` | `EOverlayDirection` | (default `RIGHT` в `OverlayBase`) | Направление выезда. |
-| `opened` | `boolean` | — | Контролируемое состояние открытия. |
-| `setOpened` | `(opened: boolean) => void` | — | Сеттер `opened` (передаётся в render-prop). |
-| `fixed` | `boolean` | `false` | `position: fixed` (на всю страницу) vs `absolute` (поверх родителя). |
-| `onOpening` / `onOpen` / `onClosing` / `onClose` | `() => void` | — | Lifecycle-callback'и (см. ниже). |
-| `children` | `(props) => ReactElement` | — | render-prop. |
-| `...HTMLAttributes` | — | — | На корневой `<div>`. |
+| `fixed` | `boolean` | `false` | `position: fixed` (на всю страницу) вместо `absolute` (поверх родителя) |
+| `onOpening` | `() => void` | — | Вызывается в начале открытия |
+| `onOpen` | `() => void` | — | Вызывается по завершении анимации открытия |
+| `onClosing` | `() => void` | — | Вызывается в начале закрытия |
+| `onClose` | `() => void` | — | Вызывается по завершении анимации закрытия |
+| `...HTMLDivAttributes` | — | — | Стандартные атрибуты корневого `<div>` (кроме `children`) |
 
-### OverlayBase — `IOverlayBaseProps`
+### provideProps (аргумент render-функции `children`)
 
-То же подмножество, что и Overlay (без `fixed` и без HTML-атрибутов). Можно использовать **без** wrapper'а Overlay, если не нужна обёртка-`<div>`.
+Передаются из `OverlayBase` в `children` и далее пробрасываются в `Overlay.Panel`
+через `{...provideProps}`:
 
-### `IOverlayChildrenProvideProps`
-
-```ts
-{
-    direction: EOverlayDirection;
-    opened: boolean;
-    setOpened: (opened: boolean) => void;
-    closing: boolean;
-    opening: boolean;
-    setClosing: (closing: boolean) => void;
-    setOpening: (opening: boolean) => void;
-}
-```
+| Поле | Тип | Описание |
+|---|---|---|
+| `direction` | `EOverlayDirection` | Текущее направление |
+| `opened` | `boolean` | Текущее состояние открытости |
+| `opening` | `boolean` | Идёт анимация открытия |
+| `closing` | `boolean` | Идёт анимация закрытия |
+| `setOpened` | `(boolean) => void` | Сеттер `opened` |
+| `setOpening` | `(boolean) => void` | Сеттер флага `opening` |
+| `setClosing` | `(boolean) => void` | Сеттер флага `closing` |
 
-### EOverlayDirection
+### `Overlay.Mask` (`OverlayMask`)
 
-`BOTTOM | LEFT | RIGHT | TOP`.
+Кликабельный полупрозрачный фон между контейнером и панелью. Props: `opened`
+(управляет классом `overlayOpened` → `opacity`), плюс `...HTMLDivAttributes`
+(обычно `onClick` для закрытия). `forwardRef` → `HTMLDivElement`.
 
-### OverlayMask — `IOverlayMaskProps extends Pick<IOverlayChildrenProvideProps, "opened">, HTMLAttributes<HTMLDivElement>`
+### `Overlay.Panel` (`OverlayPanel`)
 
-- `opened: boolean` — управляет CSS-классом `overlayOpened` (тригерит fade-in).
-- `forwardRef<HTMLDivElement>`.
-- Не реагирует на клик сам — потребитель вешает `onClick` для закрытия.
+Выезжающая панель с контентом. Принимает весь `provideProps` (через спред) плюс
+`direction`, `children` и `...HTMLDivAttributes`. По `onTransitionEnd` своего
+корневого элемента сбрасывает `closing`/`opening` (отсекая bubbling от потомков
+через сравнение `target === currentTarget`). `forwardRef` → `HTMLDivElement`.
 
-### OverlayPanel — `IOverlayPanelProps extends HTMLAttributes<HTMLDivElement>, IOverlayChildrenProvideProps`
+### `OverlayBase`
 
-- `forwardRef<HTMLDivElement>`.
-- Внутренний `onTransitionEnd` сбрасывает `closing`/`opening` в `false` **только если** `event.target === currentTarget` (защита от вложенных transitions).
-- Контент оборачивается в `<div className={overlayContent}>`.
+Низкоуровневый headless-компонент (render-prop, **без** `forwardRef` — ничего не
+рендерит сам, возвращает `children(provideProps)`). Единый источник истины по
+флагам `opened`/`opening`/`closing` и оркестратор колбэков жизненного цикла.
+Использует `useLayoutEffect` (не `useEffect`) при смене `opened`, чтобы избежать
+мерцания при закрытии.
 
 ---
 
-## Ключевые особенности реализации
-
-### Lifecycle: `opening` → `opened` → `closing` → `closed`
-
-```ts
-useLayoutEffect(() => {
-    if (prevOpened.current && !opened) { setClosing(true); onClosing?.(); }
-    else if (!prevOpened.current && opened) { setOpening(true); onOpening?.(); }
-    prevOpened.current = opened;
-}, [opened]);
+## Дизайн-токены
 
-useEffect(() => { closing ? onClosing?.() : onClose?.(); }, [closing]);
-useEffect(() => { opening ? onOpening?.() : onOpen?.(); }, [opening]);
+```
+--triplex-next-Overlay-Background        // фон маски (OverlayMask)
+--triplex-next-Overlay-Panel_Background  // фон панели (OverlayPanel)
 ```
 
-- **`useLayoutEffect`** при смене `opened` — намеренно (комментарий в коде: «иначе в браузере может быть мигание при закрытии»).
-- `closing` / `opening` сбрасываются в `false` через `onTransitionEnd` в `OverlayPanel` → тогда вызывается `onClose` / `onOpen`.
-- **`onClosing` / `onOpening`** вызывается **дважды** в начале (явно из `useLayoutEffect` + из `useEffect` на `closing`/`opening`). Известный нюанс — потребитель должен быть идемпотентен.
-
-### Двойной слой `closing` (Overlay + OverlayBase)
+Box-shadow панели и тайминги transition (`0.3s ease-in-out`) заданы константами в
+`styles/Overlay.module.less` — токенов не имеют.
 
-- `Overlay` хранит свой `closing` для CSS-класса `styles.closing` (виден до окончания анимации).
-- `OverlayBase` хранит свой `closing` для render-prop'ов.
-- **Причина**: `OverlayBase` без обёртки не имеет доступа к корневому `<div>` — нужно дублировать.
+---
 
-### `fixed` vs `absolute`
+## Инварианты
 
-```less
-.overlay { position: absolute; ... &.fixed { position: fixed; } }
-```
+- **`forwardRef`** обязателен на `Overlay` (target — корневой `HTMLDivElement`),
+  `Overlay.Mask` и `Overlay.Panel`. Не убирать. `OverlayBase` — render-prop,
+  `forwardRef` к нему неприменим.
+- **Статические `Overlay.Mask` / `Overlay.Panel`** — часть публичного API
+  (составной компонент). Навешиваются на `forwardRef`-объект через `Object.assign`
+  (как `Badge.Dot`), тип компонента выводится автоматически — отдельный `*FC`-тип
+  не нужен.
+- **Значения `EOverlayDirection`** (`"right"`/`"left"`/`"top"`/`"bottom"`) —
+  публичный API, не переименовывать.
+- **Единый источник истины по `closing`/`opening`/`opened`** — `OverlayBase`.
+  Корневой `div` `Overlay` рендерится внутри render-prop и читает `closing` из
+  `provideProps` — не дублировать локальным `useState` в `Overlay`.
+- **`provideProps` нужно пробрасывать в `Overlay.Panel`** — без них панель не
+  получит direction/флаги и не сбросит `closing`/`opening` по `transitionEnd`.
+- **CSS-классы `bottom`/`left`/`right`/`top`/`opened`/`closing`/`fixed`/
+  `overlayOpened`** управляют анимацией — переименование ломает визуальные
+  переходы и покрыто unit-тестами.
+- **React 17-совместимость** (ветка `release-0`): без `useId` и других React
+  18-only API.
+
+### Гарантия однократного вызова lifecycle-колбэков
+
+`OverlayBase` вызывает каждый из `onOpening` / `onClosing` / `onOpen` / `onClose`
+**ровно один раз** за переход. `useLayoutEffect([opened])` только выставляет
+флаги `opening` / `closing`, а сами колбэки вызываются исключительно в
+`useEffect([opening])` / `useEffect([closing])`. Однократность закреплена
+unit-тестами (`toHaveBeenCalledTimes(1)`).
+
+> Ранее (до 2026-06-17) колбэки `onOpening` / `onClosing` вызывались дважды
+> за переход — прямой вызов из `useLayoutEffect` дублировал эффект-driven вызов.
+> Исправлено: прямые вызовы из layout-эффекта удалены.
 
-- По умолчанию — `absolute` (поверх родителя). `fixed` — на весь viewport.
+---
 
-### `left: -10000px; visibility: hidden` для closed-state
+## Accessibility
 
-```less
-.overlay {
-    left: -10000px;
-    visibility: hidden;
-    &.closing, &.opened { visibility: visible; left: 0; right: 0; }
-}
-```
+- `Overlay.Mask` кликабелен для закрытия — потребитель навешивает `onClick`
+  (`setOpened(false)`); компонент текст/aria не хардкодит (библиотека
+  мультиязычная). При необходимости потребитель сам задаёт `aria-label`.
+- Скрытый оверлей выведен за пределы экрана (`left: -10000px`) и `visibility:
+  hidden`, чтобы его содержимое не получало фокус, пока он закрыт.
+- Роль диалога (`role="dialog"`/`aria-modal`), захват и возврат фокуса, обработка
+  `Escape` — **не реализованы** в самом `Overlay`; при необходимости их
+  обеспечивает потребитель или обёртка (`LightBox`, `ModalWindow`).
 
-- Закрытый overlay уезжает за viewport, чтобы:
-  - Анимация при закрытии не была обрезана `display: none`.
-  - Внутренние элементы не получали focus (через `visibility: hidden`).
+---
 
-### Transform-based анимация в Panel
+## Связанные компоненты
 
-```less
-.overlayPanel { transition: transform 0.3s ease-in-out; }
-.right { transform: translateX(100%); ... &.opened { transform: translateX(0); } }
-```
+- `OverlayBase` — headless-ядро (render-prop), управляет флагами и колбэками
+  жизненного цикла. Экспортируется из barrel, отдельного AI.md не имеет (описан
+  здесь).
+- `OverlayMask` (`Overlay.Mask`) — кликабельный фон.
+- `OverlayPanel` (`Overlay.Panel`) — выезжающая панель.
+- `LightBox`, `TopOverlay` — построены поверх механики оверлея.
+- `ModalWindow` — альтернатива для центрированных модальных окон.
 
-- Каждое направление — свой `translate` (100% начальное, 0 открытое).
-- **Длительность 300ms** — захардкожена.
-- **`box-shadow`** — захардкожен (`rgba(0,0,0,0.14)` 13px-blur 17px), не из токенов.
+---
 
-### Mask — отдельный компонент, не часть Panel
+## Stories
 
-- Потребитель сам решает, нужна ли маска и как она реагирует на клик. Это даёт гибкость: можно сделать non-modal overlay (без затемнения).
+Основные истории: `stories/Overlay/Overlay.stories.tsx`
+Файлы примеров: `stories/Overlay/examples/`
 
-### Render-prop, не Context
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `direction` / `fixed` / `opened`, маска и кнопки открытия/закрытия |
+| `Default` | `Default.tsx` | Минимальный оверлей (RIGHT, не fixed) |
+| `Directions` | `Directions.tsx` | Все 4 направления выезда панели |
+| `Fixed` | `Fixed.tsx` | Fixed-оверлей на всю страницу |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: `play` открывает панели всех направлений |
 
-- API через render-prop, а не Context, чтобы дочерние Mask/Panel могли быть переданы по-разному в каждом случае.
-- Минус: верстать вложенные компоненты сложнее (handler'ы внутри замыкания).
+Visual baseline для `components-overlay--visual-tests` генерируется только в CI
+(Linux) через `GitHub Actions → Update Visual Snapshots`.
 
 ---
 
-## Инварианты
+## История изменений
 
-- **`children` — render-prop** (`(props) => ReactElement`), не ReactNode. Изменение API — breaking.
-- **`direction` default `RIGHT`** в `OverlayBase`, в `Overlay` — без default'а (пробрасывается как-есть).
-- **`closing`/`opening` сбрасываются через `onTransitionEnd`** на `OverlayPanel` — если потребитель не использует `OverlayPanel` или ломает transition, lifecycle зависнет.
-- **`onClosing`/`onOpening` вызываются дважды** на каждое открытие/закрытие. Делай идемпотентным.
-- **Двойной `closing` state** (Overlay + OverlayBase) — не упрощать без миграции CSS.
-- **`fixed` — `position: fixed`** на корневой `<div>`, иначе `absolute`. Не работает в transformed-родителях (фундаментальный CSS).
-- **300ms transition** — захардкожена, не настраивается.
-- **CSS-переменная `--triplex-next-Overlay-Panel_Background`** — публичный токен.
-- **Mask и Panel — `forwardRef`**, Overlay/OverlayBase — `FC`.
-- **Overlay slots — `Object.assign`-style** (`Overlay.Mask = OverlayMask`) — но через property assignment.
+| Дата | Изменение |
+|---|---|
+| 2026-06-17 | Создан документ. `Overlay` переведён на `forwardRef` (ref → корневой `div`, аддитивно, release notes 1.34.0). Дедуплицирован флаг `closing` (единый источник — `OverlayBase`). Codestyle/JSDoc cleanup в 4 файлах. Добавлены 4 unit-тест-файла. Исправлен двойной вызов `onClosing`/`onOpening` за переход — теперь ровно один раз (закреплено `toHaveBeenCalledTimes(1)`). |
 
 ---
 
-## Accessibility
+## Примеры использования
 
-- **Нет встроенного focus management / focus trap** — потребитель должен реализовать сам (или использовать SideOverlay/ModalWindow поверх).
-- **Нет ESC-обработчика** — закрытие зависит от `setOpened` через клик по Mask или явный close-button.
-- **Нет `role="dialog"` / `aria-modal`** — overlay семантически нейтрален. Потребитель должен добавить через `...htmlDivAttributes`.
-- `visibility: hidden` в closed-state — корректно убирает focusable-элементы из tab-последовательности.
-- Mask — `<div>`, не интерактивный по умолчанию; клик-обработчик потребитель добавляет сам.
+### Default
 
----
+`stories/Overlay/examples/Default.tsx`
 
-## Дизайн-токены
-
-- `--triplex-next-Overlay-Panel_Background` — фон панели.
-- `box-shadow` — захардкожен, не из токенов (тех-долг).
+```tsx
+import React, { useState } from "react";
+import { Overlay, EOverlayDirection } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [opened, setOpened] = useState(false);
+
+    return (
+        <div
+            style={{
+                position: "relative",
+                width: 320,
+                height: 200,
+                border: "1px dashed #D0D4D9",
+                padding: 12,
+            }}
+        >
+            <button type="button" onClick={() => setOpened(true)} style={{ padding: "6px 12px" }}>
+                Открыть оверлей
+            </button>
+            <Overlay direction={EOverlayDirection.RIGHT} opened={opened} setOpened={setOpened}>
+                {(provideProps) => (
+                    <>
+                        <Overlay.Mask opened={opened} onClick={() => setOpened(false)} aria-label="Закрыть оверлей" />
+                        <Overlay.Panel
+                            {...provideProps}
+                            direction={EOverlayDirection.RIGHT}
+                            aria-label="Панель оверлея"
+                        >
+                            <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+                                <div>Содержимое оверлея</div>
+                                <button type="button" onClick={() => setOpened(false)}>
+                                    Закрыть
+                                </button>
+                            </div>
+                        </Overlay.Panel>
+                    </>
+                )}
+            </Overlay>
+        </div>
+    );
+};
+```
 
----
+### Directions
 
-## Связанные компоненты
+`stories/Overlay/examples/Directions.tsx`
 
-- `SideOverlay` — высокоуровневая обёртка (Overlay + Mask + ESC + focus + контент).
-- `ModalWindow` — модал на отдельном механизме (Portal + CSSTransition).
-- `LightBox` — full-screen viewer на отдельном механизме.
+```tsx
+import React, { useState } from "react";
+import { Overlay, EOverlayDirection } from "@sberbusiness/triplex-next";
 
----
+interface IDirectionItemProps {
+    direction: EOverlayDirection;
+    title: string;
+}
 
-## Stories
+const DirectionItem = ({ direction, title }: IDirectionItemProps) => {
+    const [opened, setOpened] = useState(false);
+
+    return (
+        <div
+            style={{
+                position: "relative",
+                width: 320,
+                height: 200,
+                border: "1px dashed #D0D4D9",
+                padding: 12,
+            }}
+        >
+            <div style={{ marginBottom: 8 }}>{title}</div>
+            <button type="button" onClick={() => setOpened(true)} style={{ padding: "6px 12px" }}>
+                Открыть
+            </button>
+            <Overlay direction={direction} opened={opened} setOpened={setOpened}>
+                {(provideProps) => (
+                    <>
+                        <Overlay.Mask opened={opened} onClick={() => setOpened(false)} aria-label="Закрыть оверлей" />
+                        <Overlay.Panel {...provideProps} direction={direction} aria-label="Панель оверлея">
+                            <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+                                <div>Панель ({title})</div>
+                                <button type="button" onClick={() => setOpened(false)}>
+                                    Закрыть
+                                </button>
+                            </div>
+                        </Overlay.Panel>
+                    </>
+                )}
+            </Overlay>
+        </div>
+    );
+};
+
+export const Directions = () => (
+    <div style={{ display: "grid", gridTemplateColumns: "repeat(2, 1fr)", gap: 16 }}>
+        <DirectionItem direction={EOverlayDirection.RIGHT} title="RIGHT" />
+        <DirectionItem direction={EOverlayDirection.LEFT} title="LEFT" />
+        <DirectionItem direction={EOverlayDirection.TOP} title="TOP" />
+        <DirectionItem direction={EOverlayDirection.BOTTOM} title="BOTTOM" />
+    </div>
+);
+```
 
-`stories/Overlay/Overlay.stories.tsx`
+### Fixed
 
----
+`stories/Overlay/examples/Fixed.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import { Overlay, EOverlayDirection } from "@sberbusiness/triplex-next";
+
+export const Fixed = () => {
+    const [opened, setOpened] = useState(false);
+
+    return (
+        <div>
+            <button type="button" onClick={() => setOpened(true)} style={{ padding: "6px 12px" }}>
+                Открыть fixed оверлей
+            </button>
+            <Overlay fixed direction={EOverlayDirection.RIGHT} opened={opened} setOpened={setOpened}>
+                {(provideProps) => (
+                    <>
+                        <Overlay.Mask opened={opened} onClick={() => setOpened(false)} aria-label="Закрыть оверлей" />
+                        <Overlay.Panel
+                            {...provideProps}
+                            direction={EOverlayDirection.RIGHT}
+                            aria-label="Панель оверлея"
+                        >
+                            <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+                                <div>Оверлей на всю страницу (fixed)</div>
+                                <button type="button" onClick={() => setOpened(false)}>
+                                    Закрыть
+                                </button>
+                            </div>
+                        </Overlay.Panel>
+                    </>
+                )}
+            </Overlay>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |