@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Confirm.md

@@ -0,0 +1,343 @@
+---
+component: Confirm
+category: Overlays
+figma-node: ""
+figma-file: ""
+related: [Island, LightBox, SideOverlay, Button, TriggerClickOnKeyDownEvent, Typography]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Confirm
+
+## Назначение
+
+Модальное подтверждение (диалог), встраиваемое **внутрь** уже открытого
+`LightBox` или `SideOverlay`. Не содержит собственного бэкдропа/портала —
+это компонент-контент, который рендерится поверх родительского overlay'а
+и ограничивает свою максимальную ширину так, чтобы визуально помещаться
+в контейнер родителя.
+
+Внутри — `Island type=TYPE_1` с `role="dialog" aria-modal="true"`, секция
+`Island.Body` с контентом (Title, SubTitle, Controls) и абсолютно
+позиционированная кнопка закрытия (справа сверху).
+
+Используй когда: нужно подтвердить действие (закрыть/удалить/отменить)
+поверх уже открытого `LightBox` или `SideOverlay`.
+Не используй как самостоятельный модал (он не создаёт свой overlay/backdrop)
+— для автономных диалогов бери `ModalWindow` или используй `LightBox`
+c `Confirm` внутри.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Confirm/
+├── Confirm.tsx                                  # FC-обёртка над Island, compound FC (Close/Content/Controls)
+├── enums.ts                                     # EConfirmParentComponent
+├── index.ts                                     # Barrel: Confirm + enums
+├── components/
+│   ├── ConfirmClose.tsx                         # FC, условное оборачивание в TriggerClickOnKeyDownEvent (Esc)
+│   ├── ConfirmCloseButton.tsx                   # forwardRef, Button с иконкой крестика
+│   ├── ConfirmContent.tsx                       # FC, compound с Title/SubTitle
+│   ├── ConfirmContentTitle.tsx                  # FC-обёртка Typography Title
+│   └── ConfirmContentSubTitle.tsx               # FC-обёртка Typography Text
+└── styles/Confirm.module.less                   # Max-width по parentComponent, позиционирование кнопки закрытия
+```
+
+Особенности:
+- **Root — FC, не forwardRef.** Ref-форвардинг не реализован (известный
+  AI-ready debt, характерен для compound-обёрток). Ref, если нужен
+  родителю, идёт через `...htmlDivAttributes` в `Island`.
+- **Compound через прямое присваивание:** `Confirm.Close = ConfirmClose;`
+  `Confirm.Content = ConfirmContent;` `Confirm.Controls = ConfirmControls;`
+  Тип `IConfirmFC extends React.FC<IConfirmProps>`.
+- **ConfirmContent — тоже compound** (Title/SubTitle) через тот же паттерн.
+- **Нет `__tests__` и нет `stories`** — документируется косвенно через
+  потребителей `LightBox`/`SideOverlay`.
+- **Нет собственных дизайн-токенов** — все цвета/радиусы берутся из
+  `Island` (type=TYPE_1); ширина — из LESS-переменных родительского
+  overlay (`@sideOverlaySMWidth` etc.).
+
+---
+
+## Варианты и props
+
+### Root: `IConfirmProps extends IIslandProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `parentComponent` | `EConfirmParentComponent` | `LIGHTBOX` | Определяет max-width: в `LightBox` — как у контента LightBox, в `SideOverlay` — как у соответствующей ширины боковой панели. |
+| `children` | `ReactNode` | — | Обычно `Confirm.Close` + `Confirm.Content` + `Confirm.Controls`. |
+| `className` | `string` | — | Добавляется через `clsx` к root-классу `.confirm` и parent-класс map. |
+| `...IIslandProps` | — | — | Все пропсы `Island` (`id`, `onClick`, `data-tx` и др.). |
+
+`role="dialog"` и `aria-modal="true"` проставлены жёстко в реализации и
+не могут быть перебиты через `htmlDivAttributes` (spread идёт до них
+— **неверно**: в реализации spread идёт **после** `role` и `aria-modal`,
+значит пропс потребителя **перебьёт** дефолт). Если нужно — не
+перебивать, семантика диалога обязательна.
+
+### `EConfirmParentComponent` (enum string)
+
+```ts
+enum EConfirmParentComponent {
+    LIGHTBOX = "lightBox",
+    SIDE_OVERLAY_SM = "sideOverlaySM",
+    SIDE_OVERLAY_MD = "sideOverlayMD",
+    SIDE_OVERLAY_LG = "sideOverlayLG",
+}
+```
+
+Соответствие → LESS-классы:
+- `LIGHTBOX` → `.isInLightBox` → `calc(var(--lightBox-content-max-width) - @page-padding-desktop-x*2)`
+- `SIDE_OVERLAY_SM` → `.isInSideOverlaySM` → `calc(@sideOverlaySMWidth - @page-padding-desktop-x*2)`
+- `SIDE_OVERLAY_MD` → `.isInSideOverlayMD` → `calc(@sideOverlayMDWidth - @page-padding-desktop-x*2)`
+- `SIDE_OVERLAY_LG` → `.isInSideOverlayLG` → `calc(@sideOverlayLGWidth - @page-padding-desktop-x*2)`
+
+### Compound: `Confirm.Close` — `IConfirmCloseProps extends IConfirmCloseButtonProps`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `clickByEsc` | `boolean` | Да | Если `true` — оборачивает кнопку в `TriggerClickOnKeyDownEvent` с `ESCAPE`, клик кнопки симулируется при нажатии Esc. |
+| `...IConfirmCloseButtonProps` | — | — | Все пропсы кнопки, кроме `theme/size/icon` (зафиксированы). |
+
+**`IConfirmCloseButtonProps extends Omit<TButtonProps, "theme" \| "size" \| "icon">`:**
+
+- `theme` зафиксирован в `EButtonTheme.SECONDARY`
+- `size` зафиксирован в `EComponentSize.MD`
+- `icon` зафиксирован в `<CrossStrokeSrvIcon20 paletteIndex={0} />`
+- `title` по умолчанию `"Закрыть"`
+- `className` объединяется с `.confirmCloseButton` (абсолютное позиционирование top/right: 24px; 16px на `< screen-sm-max`).
+
+### Compound: `Confirm.Content` — `IConfirmContentProps extends HTMLAttributes<HTMLDivElement>`
+
+Обычный `<div className={clsx(className, styles.confirmContent)}>` с
+`margin-bottom: 24px` (16px на мобильных) и `padding-right: 56px`
+(место под кнопку закрытия).
+
+Compound-подкомпоненты:
+
+**`Confirm.Content.Title` — `IConfirmContentTitleProps extends TTitleProps<"h1">`:**
+- По умолчанию `size={ETitleSize.H3}`
+- `margin-bottom: 12px` через `.confirmContentTitle`
+
+**`Confirm.Content.SubTitle` — `IConfirmContentSubTitleProps extends TTextProps<"div">`:**
+- По умолчанию `size={ETextSize.B2}`
+- Рендерит `<Text tag="div" />`
+
+### Compound: `Confirm.Controls` — `IConfirmControlsProps extends HTMLAttributes<HTMLDivElement>`
+
+Обычный `<div className={clsx(className, styles.confirmControls)}>` —
+стилизован `white-space: nowrap` (чтобы кнопки действий не переносились).
+Внутри обычно два `Button` (подтвердить / отменить).
+
+---
+
+## Ключевые особенности реализации
+
+### Confirm — это Island type=TYPE_1
+
+```tsx
+<Island
+    type={EIslandType.TYPE_1}
+    className={clsx(className, styles.confirm, parentComponentToClassNameMap[parentComponent])}
+    role="dialog"
+    aria-modal="true"
+    {...htmlDivAttributes}
+>
+    <Island.Body>{children}</Island.Body>
+</Island>
+```
+
+**Почему Island, а не чистый div:** Island даёт фирменные радиусы,
+тени и padding. TYPE_1 — "приподнятая" поверхность. Если захочется
+другого типа — это смена визуала Confirm, breaking-change.
+
+**`<Island.Body>` обязателен** — Island ожидает compound-структуру для
+padding'а контента. Без Body контент приклеится к границам.
+
+### `parentComponent` → max-width map
+
+```ts
+const parentComponentToClassNameMap = {
+    [EConfirmParentComponent.LIGHTBOX]: styles.isInLightBox,
+    [EConfirmParentComponent.SIDE_OVERLAY_SM]: styles.isInSideOverlaySM,
+    [EConfirmParentComponent.SIDE_OVERLAY_MD]: styles.isInSideOverlayMD,
+    [EConfirmParentComponent.SIDE_OVERLAY_LG]: styles.isInSideOverlayLG,
+};
+```
+
+Зачем: Confirm рендерится внутри родительского overlay'а и должен
+визуально поместиться в его внутренний контент. `parentComponent`
+сообщает компоненту, какой контейнер его содержит, чтобы он сам
+подсчитал max-width. Если не проставить — дефолт `LIGHTBOX`.
+
+**Если добавить новый parent (например, SIDE_OVERLAY_XL):** нужно
+обновить и enum, и map, и добавить `.isInSideOverlayXL` в LESS.
+
+### `clickByEsc` → обёртка в `TriggerClickOnKeyDownEvent`
+
+```tsx
+if (clickByEsc) {
+    return (
+        <TriggerClickOnKeyDownEvent targetRef={ref} eventKeyCode={EVENT_KEY_CODES.ESCAPE}>
+            <ConfirmCloseButton {...buttonProps} ref={ref} />
+        </TriggerClickOnKeyDownEvent>
+    );
+}
+return <ConfirmCloseButton {...buttonProps} />;
+```
+
+**Важно:** `TriggerClickOnKeyDownEvent` слушает Esc на `document` и
+программно кликает элемент по `ref`. Не вешает hard-bound listener
+на кнопку. Если в родителе уже есть обработчик Escape (LightBox
+обычно закрывается по Esc), появятся **конфликты** — Confirm должен
+останавливать пропагацию или родитель должен учитывать модальную
+вложенность. Это зона ответственности потребителя, не Confirm.
+
+### Кнопка закрытия — absolute позиция
+
+```less
+.confirmCloseButton {
+    position: absolute;
+    top: 24px;
+    right: 24px;
+}
+@media (max-width: @screen-sm-max) {
+    .confirmCloseButton {
+        top: 16px;
+        right: 16px;
+    }
+}
+```
+
+**Абсолютное позиционирование** требует `position: relative` или
+`position: absolute` на ближайшем предке. Island type=TYPE_1
+создаёт этот контекст. Если оборачивать Confirm в произвольный
+контейнер без position — кнопка "улетит" к ближайшему.
+
+### `padding-right: 56px` у Content
+
+`.confirmContent { padding-right: 56px; }` — место под кнопку закрытия,
+чтобы текст Title не перекрывался с крестиком. Значение: ширина кнопки
+(40px для MD) + gap (16px).
+
+### Zero tokens — всё из родителей
+
+В `Confirm.module.less` **нет** CSS-переменных вида
+`--triplex-next-Confirm-*`. Используются:
+- `--lightBox-content-max-width` (токен LightBox)
+- `@lightBox-content-max-width-fallback` (LESS-fallback)
+- `@sideOverlaySMWidth`, `@sideOverlayMDWidth`, `@sideOverlayLGWidth`
+- `@page-padding-desktop-x`, `@screen-sm-max`
+
+**Это осознанное решение**: Confirm — слой-"контент", не независимый
+визуальный блок. Вся пластика — от Island. Размеры — от контейнера.
+
+### `IConfirmFC` — кастомный тип интерфейса
+
+```ts
+export interface IConfirmFC extends React.FC<IConfirmProps> {
+    Close: typeof ConfirmClose;
+    Content: typeof ConfirmContent;
+    Controls: typeof ConfirmControls;
+}
+```
+
+Аналог Badge / AlertProcess / Chip. TS видит `Confirm.Close` типизированно,
+без `as any`.
+
+---
+
+## Инварианты
+
+- **`role="dialog" aria-modal="true"`** — обязательны. Не переопределять
+  через пропсы (spread-order перебьёт, но не надо).
+- **`Island.Body` обёртка** внутри Confirm — обязательна. Не превращать
+  `children` в прямых детей Island.
+- **`parentComponentToClassNameMap` и enum синхронны** — при добавлении
+  нового значения enum обновлять и map, и LESS. Дефолт — `LIGHTBOX`.
+- **`Confirm.Close` с `clickByEsc` должен стоять внутри одного Confirm**
+  — не выносить. `TriggerClickOnKeyDownEvent` работает через document,
+  Esc сработает где угодно.
+- **Кнопка закрытия — absolute относительно Island** — требует
+  `position: relative` на `.confirm`/Island. Island задаёт это сам.
+- **`padding-right: 56px` в `.confirmContent`** — резерв под кнопку.
+  Если убрать кнопку — уменьшить padding.
+- **Нет собственных CSS-токенов** — не добавлять. Все стили делегируются
+  Island и родительскому overlay.
+- **Нет forwardRef на root** — известный debt. Не добавлять точечно.
+
+---
+
+## Accessibility
+
+- **`role="dialog" aria-modal="true"`** — семантика модального диалога.
+  Screen reader объявит как модал и ограничит чтение его содержимым.
+- **Focus management** — **не реализован самим Confirm**. Ожидается,
+  что родительский overlay (LightBox/SideOverlay) уже управляет focus
+  trap'ом, и внутри Confirm фокус сам попадает на первый интерактивный
+  элемент (обычно кнопку закрытия или первый контрол).
+- **Esc handling** — через `clickByEsc` и `TriggerClickOnKeyDownEvent`.
+  Важно: Esc-listener вешается на document, не на Confirm. Если
+  родитель уже закрывается по Esc — возможен двойной trigger.
+- **Label'ы** — Confirm сам `aria-label`/`aria-labelledby` не
+  проставляет. Если нужно явное имя для screen reader'а — передать
+  `aria-labelledby` через пропсы с id `Confirm.Content.Title` или
+  `aria-label` текстом.
+- **Кнопка закрытия** имеет `title="Закрыть"` по умолчанию (becomes
+  tooltip + `aria-label` fallback для `<Button>` — зависит от
+  реализации Button).
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Визуальные токены наследуются от `Island`
+(type=TYPE_1): радиус, фон, тени, внутренние отступы. Layout-переменные
+— LESS (`@sideOverlay*Width`, `@page-padding-desktop-x`, `@screen-sm-max`).
+
+Если нужно кастомизировать Confirm в проекте — переопределять токены
+Island или оборачивать в собственный CSS.
+
+---
+
+## Связанные компоненты
+
+- `Island` (`src/components/Island`) — визуальная основа. Confirm =
+  `Island type=TYPE_1` + позиционирование + label-подкомпоненты.
+- `LightBox` (`src/components/LightBox`) — основной контейнер, в котором
+  Confirm открывается поверх контента.
+- `SideOverlay*` (`src/components/SideOverlay`) — вторичные контейнеры
+  (SM/MD/LG). Размеры задают ширину Confirm через `parentComponent`.
+- `Button` (`src/components/Button`) — кнопка закрытия (SECONDARY, MD,
+  CrossStrokeSrvIcon20) и кнопки действий в `Confirm.Controls`.
+- `TriggerClickOnKeyDownEvent` (`src/components/Triggers`) — механизм
+  Esc → click (`Confirm.Close` при `clickByEsc`).
+- `Typography.Title` / `Typography.Text` — базы для
+  `Confirm.Content.Title` / `Confirm.Content.SubTitle`.
+- `ModalWindow` — автономный диалог (с бэкдропом). Не замена Confirm:
+  разная семантика слоя.
+
+---
+
+## Stories
+
+**Нет собственных stories.** Документируется косвенно через сценарии
+`LightBox`/`SideOverlay`, где Confirm появляется как подтверждение
+закрытия.
+
+Добавлять stories при миграции на AI-ready pattern — stories должны
+эмулировать контекст (мок родительского overlay или использование
+реального `LightBox`/`SideOverlay` с открытым Confirm внутри).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |