@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 0.36.0-beta0

package/bundle/components/Page.md

@@ -1,11 +1,9 @@
 ---
 component: Page
-category: Layout
-figma-node: ""
-figma-file: ""
-related: [Header, Body, Footer, Island, LightBox, Spoiler]
+category: Page
+related: [HeaderPage, BodyPage, FooterPage, Island, LightBox]
 tokens: []
-stories: stories/Page/Page.stories.tsx
+stories: stories/Page/Page/Page.stories.tsx
 version: "1.0"
 ---
 
@@ -13,234 +11,333 @@ version: "1.0"
 
 ## Назначение
 
-Layout-компонент **страницы**: контейнер `<div class="global-page">` +
-три compound-слота `Header`, `Body`, `Footer`, каждый из которых
-существует в **двух типах**:
+Каркас страницы. Вертикальный flex-контейнер (`<div>`), в который вкладываются только составные
+части: `Page.Header` (HeaderPage), `Page.Body` (BodyPage) и `Page.Footer` (FooterPage). Сам `Page`
+не задаёт визуальный стиль контента — он лишь раскладывает части по вертикали и задаёт внешние
+отступы страницы.
 
-- **`FIRST`** — заворачивает контент в `Island` (карточка с фоном,
-  скруглением, padding'ом). Используется для типичной layout'ной
-  страницы.
-- **`SECOND`** — оставляет «голый» Header/Body/Footer без `Island` —
-  для случаев, когда фон/обёртка управляется внешним контейнером
-  (например, `LightBox`).
-
-Дополнительно `HeaderPage` / `FooterPage` поддерживают **`sticky`** —
-sticky-позиционирование с **плавным обнулением скруглений углов** при
-прилипании (через `useStickyCornerRadius`).
-
-Используй когда: компонуешь страницу из секций. Если нужен только
-header / footer без всей структуры — используй `Header`/`Footer`/`Body`
-напрямую.
-
----
-
-## Файловая структура
-
-```text
-src/components/Page/
-├── Page.tsx                              # forwardRef + Object.assign({Header, Body, Footer})
-├── components/
-│   ├── HeaderPage.tsx                    # forwardRef; FIRST=Island+Header, SECOND=Header
-│   ├── BodyPage.tsx                      # forwardRef; FIRST=Island+Body, SECOND=Body
-│   ├── FooterPage.tsx                    # forwardRef; FIRST=Island+Footer, SECOND=Footer
-│   ├── enums.ts                          # EHeaderPageType / EBodyPageType / EFooterPageType / EBodyPageVerticalMargin
-│   └── useStickyCornerRadius.ts          # rAF-анимация corner-radius при sticky-прилипании
-├── styles/Page.module.less + BodyPage.module.less
-├── index.ts                              # Barrel: Page + enums
-└── __tests__/
-```
-
----
-
-## Compound-структура
-
-```tsx
-<Page>
-    <Page.Header type={EHeaderPageType.FIRST} sticky size={EComponentSize.MD}>
-        <Page.Header.Title>Заголовок</Page.Header.Title>
-        <Page.Header.Subhead>Подзаголовок</Page.Header.Subhead>
-        <Page.Header.Tabs>...</Page.Header.Tabs>
-    </Page.Header>
-    <Page.Body type={EBodyPageType.FIRST} verticalMargin={EBodyPageVerticalMargin.LARGE}>
-        Контент
-    </Page.Body>
-    <Page.Footer type={EFooterPageType.FIRST} sticky>
-        <Page.Footer.Description>Подпись</Page.Footer.Description>
-        <Button>Действие</Button>
-    </Page.Footer>
-</Page>
-```
-
-`HeaderPage.Title/Subhead/Tabs/LayoutSidebar` — **реэкспорты** `Header.*`. То же — `FooterPage.Description = Footer.Description`.
+Используй когда: нужен типовой каркас страницы — заголовок сверху, контент по центру, футер снизу.
+Чаще всего применяется как содержимое `LightBox`.
+Не используй когда: нужен отдельный блок (карточка, заголовок) без полного каркаса — используй
+`Island`, `Page.Header`/`Page.Body`/`Page.Footer` по отдельности или иной контейнер.
 
 ---
 
 ## Варианты и props
 
-### Page — `IPageProps extends HTMLAttributes<HTMLDivElement>`
+Собственных props у `Page` нет — интерфейс `IPageProps` пуст и расширяет
+`React.HTMLAttributes<HTMLDivElement>`. Вся настройка внешнего вида задаётся через типы дочерних
+частей (`type` у `Page.Header` / `Page.Body` / `Page.Footer`), а не через props самого `Page`.
+
+### Props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `...HTMLAttributes` | — | На корневой `<div>`. |
-| `children` | `ReactNode` | Только Header / Body / Footer (контракт). |
-
-CSS-классы: `styles.page` + **`styles["global-page"]`** (последний — публичный, для глобальных стилей вне модуля).
+| `className` | `string` | Дополнительный класс на корневой `<div>`. Мерджится через `clsx` после базовых классов. |
+| `children` | `React.ReactNode` | Составные части страницы: `Page.Header`, `Page.Body`, `Page.Footer`. |
+| `...rest` | `React.HTMLAttributes<HTMLDivElement>` | Любые стандартные HTML-атрибуты `<div>` пробрасываются на корневой элемент. |
 
-### HeaderPage — `IHeaderPageTypeFirstProps | IHeaderPageTypeSecondProps`
+### Статические свойства (составные части)
 
-| Prop | FIRST | SECOND | Default | Описание |
-|---|---|---|---|---|
-| `type` | `EHeaderPageType.FIRST` | `EHeaderPageType.SECOND` | — (обязателен) | Discriminator. |
-| `sticky` | `boolean` | `never` | — | Sticky к верху. **Только FIRST** и **только внутри LightBox** (по комментарию). |
-| `size` | `EComponentSize` | `never` | — | Размер `Island`. **Только FIRST**. |
-| `...IHeaderProps` | — | — | — | От `Header`. |
-
-- FIRST: `<Island type=TYPE_1 size={size}><Header /></Island>`.
-- SECOND: `<Header className={headerPageTypeSecond} />`.
-- Slots: **`HeaderPage.Title / Subhead / Tabs / LayoutSidebar`** = реэкспорты `Header.*`.
-
-### BodyPage — `IBodyPageTypeFirstProps | IBodyPageTypeSecondProps`
-
-| Prop | FIRST | SECOND | Default | Описание |
-|---|---|---|---|---|
-| `type` | `EBodyPageType.FIRST` | `EBodyPageType.SECOND` | — | Discriminator. |
-| `size` | `EComponentSize` | `never` | — | Размер `Island`. Только FIRST. |
-| `verticalMargin` | `EBodyPageVerticalMargin` | (то же) | `LARGE` | `LARGE` = 24px, `SMALL` = 16px. В LightBox — `SMALL`. |
-| `...IBodyProps` | — | — | — | От `Body`. |
-
-### FooterPage — `IFooterPageTypeFirstProps | IFooterPageTypeSecondProps`
+| Свойство | Компонент | Назначение |
+|---|---|---|
+| `Page.Header` | `HeaderPage` | Заголовок страницы. |
+| `Page.Body` | `BodyPage` | Тело страницы с основным контентом. |
+| `Page.Footer` | `FooterPage` | Футер страницы с действиями. |
 
-| Prop | FIRST | SECOND | Default | Описание |
-|---|---|---|---|---|
-| `type` | `EFooterPageType.FIRST` | `EFooterPageType.SECOND` | — | Discriminator. |
-| `sticky` | `boolean` | `never` | — | Sticky к низу. **Только FIRST внутри LightBox** (по комментарию). |
-| `size` | `EComponentSize` | `never` | — | Размер `Island`. Только FIRST. |
-| `...IFooterProps` | — | — | — | От `Footer`. |
+### Типы частей
 
-- Slots: **`FooterPage.Description`** = `Footer.Description`.
+Каждая часть бывает двух типов (`type`):
 
-### Enums
+- `FIRST` — часть оборачивается в `Island` (карточку с белым фоном и тенью). Применяется в `LightBox`.
+- `SECOND` — часть без карточки (без фона). Применяется в обычном layout.
 
-- `EHeaderPageType.FIRST | SECOND`
-- `EBodyPageType.FIRST | SECOND`
-- `EFooterPageType.FIRST | SECOND`
-- `EBodyPageVerticalMargin.LARGE` (24px) | `SMALL` (16px)
+Детали props частей — в их собственных AI.md: `HeaderPage-ai.md`, `BodyPage-ai.md`, `FooterPage-ai.md`.
 
 ---
 
-## Ключевые особенности реализации
-
-### `useStickyCornerRadius(ref, edge, isEnabled)`
-
-```ts
-useEffect(() => {
-    // Подписка на scroll/resize/transitionend ближайшего scroll-родителя.
-    // ResizeObserver на всех предках до scroller.
-    // На каждом frame: вычисляем расстояние до edge → r = clamp(0, 24, dist).
-    // Пишем в --r-top / --r-bottom (CSS-var) и dataset.stuck = "true" если r ≤ 0.5.
-}, [ref, edge, isEnabled]);
-```
-
-- **Нативный sticky** + **анимированный corner-radius**:
-  - Когда элемент далеко от прилипшей границы → `--r-top: 24px`.
-  - При прилипании → `--r-top: 0px` плавно (через rAF).
-  - `data-stuck="true"` — для подключения тени через CSS.
-- **`getScrollParent`**: ищет ближайший `overflowY: auto/scroll/overlay`. Default — `window`.
-- **`ResizeObserver`** на ВСЕХ предках до scroller — нужен для случая, когда `Spoiler` раскрывается без scroll-события, но меняет высоту контента.
-- **`transitionend` listener** — обновление при завершении анимации `lightBoxSideOverlayContent` (cross-component contract по className!).
-- **`setTimeout(initialize, 100)`** — задержка для совместимости с открытием LightBox (без задержки анимация не работает).
-- **Жёсткие зависимости**: ref, edge, isEnabled — пересоздание подписки при изменении.
-
-### CSS-переменные `--r-top`, `--r-bottom`
-
-- Публичный контракт: устанавливаются JS, читаются в LESS (`border-radius: var(--r-top, 24px) var(--r-top, 24px) 0 0` или подобное).
-- При `isEnabled=false` или unmount — переменная удаляется через `style.removeProperty`.
+## Дизайн-токены
 
-### Cross-component className-зависимость: `lightBoxSideOverlayContent`
+Собственных CSS-переменных дизайн-токенов у `Page` нет. Внешние отступы и брейкпоинты заданы
+LESS-переменными в `styles/Page.module.less` (`@page-padding-*`, `@screen-sm-max`). Sticky-стили
+для прилипающих Header/Footer (классы `.headerPageTypeFirst.sticky`, `.footerPageTypeFirst.sticky`)
+используют токены соответствующих компонентов (`--triplex-next-HeaderPage-StickyShadow`,
+`--triplex-next-FooterPage-StickyShadow`) — они описаны в AI.md этих компонентов.
 
-```ts
-event.target.classList.contains("lightBoxSideOverlayContent")
-```
+---
 
-- Hardcoded substring matching на className из `LightBox` package. **При переименовании в LightBox — sticky-corner для page внутри SideOverlay перестанет реагировать на анимацию**. Тех-долг.
+## Инварианты
 
-### `setIslandRef` — мерж forwardRef + локального ref
+- `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой `<div>`.
+- `displayName = "Page"` — не менять.
+- `Page` собран через `Object.assign(forwardRef(...), { Body, Header, Footer })` — статические
+  свойства `Header` / `Body` / `Footer` должны сохраняться.
+- Корневые классы `page` и `global-page` на корневом `<div>` — не переименовывать (используются
+  в стилях, в т.ч. в sticky-селекторах `.global-LB-more-media-point-0`).
+- Экспорты `Page`, `IPageProps` идут в barrel `src/components/Page/index.ts` — сохранять.
+  Там же реэкспортируются части и их enum'ы (`EHeaderPageType`, `EFooterPageType`, `EBodyPageType`,
+  `EBodyPageVerticalMargin`).
 
-```ts
-const setIslandRef = (instance) => {
-    islandRef.current = instance;
-    if (typeof ref === "function") ref(instance);
-    else if (ref) ref.current = instance;
-};
-```
+---
 
-- Стандартный паттерн merge. Используется в HeaderPage и FooterPage.
+## Accessibility
 
-### Discriminated union по `type`
+Особого a11y-поведения нет — это структурный контейнер без интерактивности и без хардкода
+aria-атрибутов. Семантику задаёт потребитель через проброшенные HTML-атрибуты (`...rest`).
+Интерактивность обеспечивают вложенные элементы внутри `Page.Header` / `Page.Footer`
+(кнопки, ссылки, табы).
 
-- TypeScript обеспечивает: `sticky` / `size` доступны только при `FIRST`. При `SECOND` — `never`.
-- Discriminator обязателен на потребителе: `<Page.Header type={EHeaderPageType.FIRST} ...>`.
+---
 
-### `Island type=TYPE_1` — фиксирован
+## Связанные компоненты
 
-- При `FIRST` Island всегда `TYPE_1` (нельзя сменить на `TYPE_2`).
+- `HeaderPage` (`Page.Header`), `BodyPage` (`Page.Body`), `FooterPage` (`Page.Footer`) — составные
+  части страницы. Каждая имеет собственный AI.md.
+- `Island` — карточка-обёртка для частей типа `FIRST`.
+- `LightBox` — типичное место использования `Page`.
 
-### `Page.tsx` — `global-page` className
+---
 
-- Кроме CSS-Modules класса `styles.page` добавляется `styles["global-page"]` (это композитный класс, не глобальный селектор `:global` — но имя зарезервированное). Используется для cross-component хуков.
+## Stories
 
----
+Основные истории: `stories/Page/Page/Page.stories.tsx`
+Файлы примеров: `stories/Page/Page/examples/`
 
-## Инварианты
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль типов `Page.Header` / `Page.Footer` и `verticalMargin` у `Page.Body` |
+| `Default` | `Default.tsx` | Базовая страница: header FIRST, body SECOND, footer FIRST (типичная Page для LightBox) |
+| `WithIslands` | `WithIslands.tsx` | Все части типа FIRST — острова (карточки); для LightBox |
+| `WithoutIslands` | `WithoutIslands.tsx` | Все части типа SECOND — без островов; для layout |
 
-- **Page может содержать только Header / Body / Footer** (контракт документации; типы шире).
-- **Discriminated union по `type`** — `EHeaderPageType.FIRST | SECOND` (то же для Body/Footer). Несовместимо с runtime-вычисляемым type без cast'а.
-- **`sticky` — только FIRST**, и **только внутри LightBox** (по комментарию в коде; вне LightBox поведение не специфицировано).
-- **`useStickyCornerRadius`** жёстко завязан на:
-  - className `lightBoxSideOverlayContent` (cross-package contract).
-  - CSS-переменные `--r-top` / `--r-bottom` (публичный контракт со стилями).
-- **`maxRadius = 24`** — захардкожен в JS.
-- **`Island type=TYPE_1`** при FIRST — фиксирован.
-- **`verticalMargin` default `LARGE` (24px)**, в LightBox — `SMALL` (16px).
-- **HeaderPage slots = `Header.*`** (Title/Subhead/Tabs/LayoutSidebar) — реэкспорты, не свои реализации.
-- **FooterPage slots = `Footer.Description`** — реэкспорт.
-- **ForwardRef** на всех уровнях.
-- **`global-page` className** на Page — публичное имя.
+`Default`, `WithIslands` и `WithoutIslands` участвуют в скриншот-тестах (покрывают
+комбинации типов `FIRST` / `SECOND` у частей). `Playground` интерактивен и исключён
+(`testRunner: { skip: true }`).
 
 ---
 
-## Accessibility
+## История изменений
 
-- Базовая семантика наследуется от `Header`, `Body`, `Footer` (заголовки h1/h2 — внутри `Header.Title`).
-- `Page` сам — нейтральный `<div>`, не landmark. Если нужен `<main>` — потребитель должен обернуть/передать `role`.
-- Sticky-поведение — клавиатурно нормально (sticky == native CSS), screen readers видят корректный flow.
+| Дата | Изменение |
+|---|---|
+| 2026-06-24 | Создан документ. AI-рефакторинг (JSDoc на компоненте и `IPageProps`), unit-тесты (className-merge, статические части), миграция stories на modern pattern. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-Нет собственных. Цвета/spacing — от `Island`, `Header`, `Body`, `Footer`. CSS-переменные `--r-top` / `--r-bottom` — управляющие, не токены.
+### Default
 
----
+`stories/Page/Page/examples/Default.tsx`
 
-## Связанные компоненты
+```tsx
+import React from "react";
+import {
+    Page,
+    EHeaderPageType,
+    EBodyPageType,
+    EFooterPageType,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Title,
+    Text,
+    ETitleSize,
+    ETextSize,
+    EFontType,
+    Gap,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Page>
+        <Page.Header type={EHeaderPageType.FIRST}>
+            <Page.Header.Title>
+                <Page.Header.Title.Content>
+                    <Title tag="h1" size={ETitleSize.H1}>
+                        Title text
+                    </Title>
+                    <Gap size={8} />
+                    <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                        Optional description about the page
+                    </Text>
+                </Page.Header.Title.Content>
+                <Page.Header.Title.Controls>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </Page.Header.Title.Controls>
+            </Page.Header.Title>
+        </Page.Header>
+
+        <Page.Body type={EBodyPageType.SECOND}>
+            <Text tag="div" size={ETextSize.B3}>
+                Page content
+            </Text>
+        </Page.Body>
+
+        <Page.Footer type={EFooterPageType.FIRST}>
+            <Page.Footer.Description>
+                <Page.Footer.Description.Content>
+                    <Text size={ETextSize.B3}>Footer page text</Text>
+                </Page.Footer.Description.Content>
+                <Page.Footer.Description.Controls>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY}>
+                        Button text
+                    </Button>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
+                        Button text
+                    </Button>
+                </Page.Footer.Description.Controls>
+            </Page.Footer.Description>
+        </Page.Footer>
+    </Page>
+);
+```
 
-- `Header`, `Body`, `Footer` — нижележащие компоненты (FIRST оборачивает в Island).
-- `Island` (TYPE_1) — карточка-обёртка для FIRST.
-- `LightBox` — типичный контекст для `type=SECOND` и `sticky`.
-- `Spoiler` — потребитель ResizeObserver (срабатывание sticky-corner при раскрытии).
+### WithIslands
 
----
+`stories/Page/Page/examples/WithIslands.tsx`
 
-## Stories
+```tsx
+import React from "react";
+import {
+    Page,
+    EHeaderPageType,
+    EBodyPageType,
+    EFooterPageType,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Title,
+    Text,
+    ETitleSize,
+    ETextSize,
+    EFontType,
+    Gap,
+} from "@sberbusiness/triplex-next";
+
+// Header, Body и Footer типа FIRST — каждый блок оборачивается в Island (карточку). Используется в LightBox.
+export const WithIslands = () => (
+    <Page>
+        <Page.Header type={EHeaderPageType.FIRST}>
+            <Page.Header.Title>
+                <Page.Header.Title.Content>
+                    <Title tag="h1" size={ETitleSize.H1}>
+                        Title text
+                    </Title>
+                    <Gap size={8} />
+                    <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                        Optional description about the page
+                    </Text>
+                </Page.Header.Title.Content>
+                <Page.Header.Title.Controls>
+                    <Button theme={EButtonTheme.SECONDARY} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </Page.Header.Title.Controls>
+            </Page.Header.Title>
+        </Page.Header>
+
+        <Page.Body type={EBodyPageType.FIRST}>
+            <Text tag="div" size={ETextSize.B3}>
+                Page content
+            </Text>
+        </Page.Body>
+
+        <Page.Footer type={EFooterPageType.FIRST}>
+            <Page.Footer.Description>
+                <Page.Footer.Description.Content>
+                    <Text size={ETextSize.B3}>Footer page text</Text>
+                </Page.Footer.Description.Content>
+                <Page.Footer.Description.Controls>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY}>
+                        Button text
+                    </Button>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
+                        Button text
+                    </Button>
+                </Page.Footer.Description.Controls>
+            </Page.Footer.Description>
+        </Page.Footer>
+    </Page>
+);
+```
 
-`stories/Page/Page.stories.tsx`
-Примеры: `stories/Page/examples/`
+### WithoutIslands
 
----
+`stories/Page/Page/examples/WithoutIslands.tsx`
 
-## История изменений
+```tsx
+import React from "react";
+import {
+    Page,
+    EHeaderPageType,
+    EBodyPageType,
+    EFooterPageType,
+    Button,
+    EButtonTheme,
+    EComponentSize,
+    Title,
+    Text,
+    ETitleSize,
+    ETextSize,
+    EFontType,
+    Gap,
+} from "@sberbusiness/triplex-next";
+
+// Header, Body и Footer типа SECOND — без Island (без карточек). Используется в layout, а не в LightBox.
+export const WithoutIslands = () => (
+    <Page>
+        <Page.Header type={EHeaderPageType.SECOND}>
+            <Page.Header.Title>
+                <Page.Header.Title.Content>
+                    <Title tag="h1" size={ETitleSize.H1}>
+                        Title text
+                    </Title>
+                    <Gap size={8} />
+                    <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                        Optional description about the page
+                    </Text>
+                </Page.Header.Title.Content>
+                <Page.Header.Title.Controls>
+                    <Button theme={EButtonTheme.SECONDARY_LIGHT} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                    <Button theme={EButtonTheme.GENERAL} size={EComponentSize.MD}>
+                        Button text
+                    </Button>
+                </Page.Header.Title.Controls>
+            </Page.Header.Title>
+        </Page.Header>
+
+        <Page.Body type={EBodyPageType.SECOND}>
+            <Text tag="div" size={ETextSize.B3}>
+                Page content
+            </Text>
+        </Page.Body>
+
+        <Page.Footer type={EFooterPageType.SECOND}>
+            <Page.Footer.Description>
+                <Page.Footer.Description.Content>
+                    <Text size={ETextSize.B3}>Footer page text</Text>
+                </Page.Footer.Description.Content>
+                <Page.Footer.Description.Controls>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY_LIGHT}>
+                        Button text
+                    </Button>
+                    <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
+                        Button text
+                    </Button>
+                </Page.Footer.Description.Controls>
+            </Page.Footer.Description>
+        </Page.Footer>
+    </Page>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |