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

package/bundle/components/HeaderPage.md

@@ -0,0 +1,226 @@
+---
+component: HeaderPage
+category: Page
+related: [Page, BodyPage, FooterPage, Header, Island, LightBox]
+tokens: [--triplex-next-HeaderPage-StickyShadow]
+stories: stories/Page/HeaderPage/HeaderPage.stories.tsx
+version: "1.0"
+---
+
+# HeaderPage
+
+## Назначение
+
+Заголовок страницы `Page`. Доступен как статическое свойство `Page.Header`. Верхний блок страницы
+с заголовком, табами и подзаголовком, располагается над `Page.Body`.
+
+Контент строится через составные части `Page.Header`: `Page.Header.Title` (с областями `Content`
+и `Controls`), `Page.Header.Tabs` (с областями `Content` и `Controls`), `Page.Header.Subhead` и
+`Page.Header.LayoutSidebar` (с областями `Content` и `Sidebar`).
+
+Используй когда: нужен верхний блок страницы с заголовком и действиями — как в карточке (Island),
+так и без неё; а также прилипающий к верху заголовок внутри `LightBox`.
+Не используй когда: нужно тело или футер страницы — для этого есть `Page.Body` / `Page.Footer`.
+
+---
+
+## Варианты и props
+
+Публичный API — discriminated union по `type`: `IHeaderPageTypeFirstProps | IHeaderPageTypeSecondProps`.
+Оба интерфейса расширяют `IHeaderProps` (≈ `React.HTMLAttributes<HTMLDivElement>`).
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `EHeaderPageType` | `FIRST` — заголовок оборачивается в `Island` (карточка с белым фоном и тенью). `SECOND` — заголовок без карточки. |
+| `children` | `React.ReactNode` | Контент заголовка страницы. |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `sticky` | `boolean` | `false` | Заголовок прилипает к верхней границе при скролле. **Только для `type=FIRST`** (внутри `LightBox`); для `type=SECOND` типизирован как `never`. |
+| `size` | `EComponentSize` | — | Размер острова (Island). **Доступен только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
+
+### Ограничения по типам
+
+- `size` и `sticky` доступны только при `type=FIRST` (в `SECOND` контент не оборачивается в Island,
+  поэтому оба типизированы как `never`).
+
+---
+
+## Дизайн-токены
+
+| Токен | Назначение |
+|---|---|
+| `--triplex-next-HeaderPage-StickyShadow` | Тень прилипшего заголовка (когда `sticky` и заголовок коснулся верхней границы, `data-stuck="true"`). |
+
+Внешний вид карточки наследуется от `Island` (`EIslandType.TYPE_1`). Радиус верхних углов при
+прилипании плавно обнуляется через CSS-переменную `--r-top` (управляется хуком
+`useStickyCornerRadius` с `edge="top"`).
+
+---
+
+## Инварианты
+
+- `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой элемент
+  (Island для FIRST, Header для SECOND).
+- Ручной merge ref (`setIslandRef`) обязателен: ref нужен одновременно хуку
+  `useStickyCornerRadius` (внутренний `islandRef`) и наружу (проброшенный `ref`). Не упрощать.
+- `displayName = "HeaderPage"` — не менять.
+- `HeaderPage` собран через `Object.assign(forwardRef(...), { LayoutSidebar, Subhead, Tabs, Title })` —
+  статические свойства (= `Header.LayoutSidebar` / `Header.Subhead` / `Header.Tabs` / `Header.Title`)
+  должны сохраняться.
+- Discriminated union по `type` и значения `EHeaderPageType` — часть публичного API, менять нельзя.
+- Экспорты `HeaderPage`, `IHeaderPageTypeFirstProps`, `IHeaderPageTypeSecondProps` идут в barrel
+  `src/components/Page/index.ts` — сохранять.
+
+---
+
+## Accessibility
+
+Особого a11y-поведения нет — это структурный контейнер. Семантику и aria-атрибуты задаёт
+потребитель через проброшенные HTML-атрибуты (`...rest` уходит в `Header`). Интерактивность
+обеспечивают вложенные кнопки/ссылки/табы внутри `Title.Controls` / `Tabs.Controls`.
+
+---
+
+## Связанные компоненты
+
+- `Page` — родитель; `HeaderPage` доступен как `Page.Header`.
+- `BodyPage` (`Page.Body`), `FooterPage` (`Page.Footer`) — соседи внутри `Page`.
+- `Header` — внутренний контейнер заголовка; статика `Page.Header.Title` / `Tabs` / `Subhead` /
+  `LayoutSidebar` берётся из `Header.*`.
+- `Island` — карточка-обёртка для `type=FIRST`.
+- `LightBox` — типичное место использования с `sticky`.
+
+---
+
+## Stories
+
+Основные истории: `stories/Page/HeaderPage/HeaderPage.stories.tsx`
+Файлы примеров: `stories/Page/HeaderPage/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `type` и `size` |
+| `Default` | `Default.tsx` | Минимальный пример (FIRST, заголовок в карточке) |
+| `Types` | `Types.tsx` | Сравнение типов FIRST и SECOND (покрывает скриншот-регрессию) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-06-23 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Page/HeaderPage/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import {
+    Page,
+    EHeaderPageType,
+    EComponentSize,
+    Button,
+    EButtonTheme,
+    Title,
+    ETitleSize,
+    Text,
+    ETextSize,
+    EFontType,
+    Gap,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => (
+    <Page.Header type={EHeaderPageType.FIRST}>
+        <Page.Header.Title>
+            <Page.Header.Title.Content>
+                <Title tag="h1" size={ETitleSize.H1}>
+                    Заголовок страницы
+                </Title>
+                <Gap size={8} />
+                <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                    Дополнительное описание страницы
+                </Text>
+            </Page.Header.Title.Content>
+            <Page.Header.Title.Controls>
+                <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY}>
+                    Отмена
+                </Button>
+                <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
+                    Сохранить
+                </Button>
+            </Page.Header.Title.Controls>
+        </Page.Header.Title>
+    </Page.Header>
+);
+```
+
+### Types
+
+`stories/Page/HeaderPage/examples/Types.tsx`
+
+```tsx
+import React from "react";
+import {
+    Page,
+    EHeaderPageType,
+    EComponentSize,
+    Button,
+    EButtonTheme,
+    Title,
+    ETitleSize,
+    Text,
+    ETextSize,
+    EFontType,
+    Gap,
+} from "@sberbusiness/triplex-next";
+
+const title = (type: EHeaderPageType) => (
+    <Page.Header.Title>
+        <Page.Header.Title.Content>
+            <Title tag="h1" size={ETitleSize.H1}>
+                Заголовок страницы
+            </Title>
+            <Gap size={8} />
+            <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
+                Дополнительное описание страницы
+            </Text>
+        </Page.Header.Title.Content>
+        <Page.Header.Title.Controls>
+            <Button
+                size={EComponentSize.MD}
+                theme={type === EHeaderPageType.FIRST ? EButtonTheme.SECONDARY : EButtonTheme.SECONDARY_LIGHT}
+            >
+                Отмена
+            </Button>
+            <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
+                Сохранить
+            </Button>
+        </Page.Header.Title.Controls>
+    </Page.Header.Title>
+);
+
+export const Types = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>FIRST</div>
+            <Page.Header type={EHeaderPageType.FIRST}>{title(EHeaderPageType.FIRST)}</Page.Header>
+        </div>
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>SECOND</div>
+            <Page.Header type={EHeaderPageType.SECOND}>{title(EHeaderPageType.SECOND)}</Page.Header>
+        </div>
+    </div>
+);
+```
+

package/bundle/components/HelpBox.md

@@ -1,8 +1,6 @@
 ---
 component: HelpBox
 category: HelpBox
-figma-node: ""
-figma-file: ""
 related: [Tooltip, ButtonIcon, MobileView, FocusTrap]
 tokens: []
 stories: stories/HelpBox/HelpBox.stories.tsx
@@ -13,25 +11,10 @@ version: "1.0"
 
 ## Назначение
 
-Иконка "?" (`QuestioncircleFilledSrvIcon16`) с всплывающей подсказкой (Tooltip).
-Объединяет ButtonIcon-триггер, Tooltip и FocusTrap в одном компоненте.
+Иконка «?» (`QuestioncircleFilledSrvIcon16`) с всплывающей подсказкой (`Tooltip`). Объединяет `ButtonIcon`-триггер, `Tooltip` и `FocusTrap` в одном компоненте.
 
 Используй когда: нужна контекстная подсказка рядом с элементом интерфейса.
-Не используй когда: нужен полноценный попап с формой или сложным контентом — используй Dropdown или Modal.
-
----
-
-## Файловая структура
-
-```text
-src/components/HelpBox/
-├── HelpBox.tsx                   # Основной компонент
-├── index.ts                      # Barrel export
-├── styles/
-│   └── HelpBox.module.less       # Минимальные стили (position, vertical-align)
-└── __tests__/
-    └── HelpBox.test.tsx          # Unit-тесты
-```
+Не используй когда: нужен полноценный попап с формой или сложным контентом — используй `Dropdown` или `Modal`.
 
 ---
 
@@ -48,7 +31,7 @@ src/components/HelpBox/
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `isOpen` | `boolean` | `undefined` | Управляемое состояние открытия тултипа |
+| `isOpen` | `boolean` | — | Управляемое состояние открытия тултипа |
 | `toggle` | `(open: boolean) => void` | — | Callback при открытии/закрытии |
 | `onShow` | `(node: HTMLDivElement) => void` | — | Callback при появлении тултипа в DOM |
 | `preferPlace` | `ETooltipPreferPlace` | — | Предпочтительное расположение: `ABOVE`, `BELOW`, `LEFT`, `RIGHT` |
@@ -61,46 +44,11 @@ src/components/HelpBox/
 | `className` | `string` | — | CSS-класс, пробрасывается на кнопку-триггер |
 | `...rest` | `React.HTMLAttributes<HTMLButtonElement>` | — | Все стандартные атрибуты `<button>`, включая `aria-label`, пробрасываются на кнопку-триггер |
 
-### Controlled / Uncontrolled
+### Ограничения использования
 
-- **Uncontrolled** (по умолчанию): `isOpen` не передан — компонент сам управляет `openState`.
-- **Controlled**: передай `isOpen` + `toggle` — компонент не меняет внутреннее состояние.
-
----
-
-## Ключевые особенности реализации
-
-### Композиция внутренних компонентов
-
-HelpBox — обёртка над несколькими внутренними компонентами:
-- `ButtonIcon` (shape=CIRCLE) — кнопка-триггер с иконкой `QuestioncircleFilledSrvIcon16`
-- `Tooltip` (toggleType="hover", role="dialog") — всплывающая подсказка
-- `FocusTrap` (только desktop, через `MobileView`) — ловушка фокуса при открытом тултипе
-- `TooltipMobileHeader` — заголовок мобильной версии (рендерится только при наличии `mobileHeaderContent`)
-
-### FocusTrap
-
-Ловушка фокуса активируется только на desktop (через `MobileView` fallback). При открытии:
-- `initialFocus` — элемент Tooltip (по ID)
-- `clickOutsideDeactivates: true` — клик за пределами закрывает
-- `preventScroll: true`
-
-Потребитель может расширить настройки через `focusTrapProps.focusTrapOptions`.
-
-### Ref forwarding
-
-`forwardRef` пробрасывает ref на внутренний `ButtonIcon` (кнопку-триггер). Внутренний `buttonRef` используется для позиционирования Tooltip через `targetRef`.
-
----
-
-## Accessibility
-
-- Кнопка-триггер — нативный `<button>` через `ButtonIcon`, shape `CIRCLE`.
-- **`aria-label` триггера** — не захардкожен. Потребитель **обязан** передать `aria-label` через `...rest` (например, `aria-label="Подсказка"`). Библиотека мультиязычная, текст не хардкодится.
-- **`aria-label` кнопки закрытия** — передаётся через `tooltipXButtonProps={{ "aria-label": "Закрыть" }}`. Потребитель **обязан** указать значение на своём языке.
-- Tooltip открывается с `role="dialog"`, `tabIndex={-1}`.
-- FocusTrap удерживает фокус внутри открытого тултипа на desktop.
-- `tooltipAriaAttributes` позволяет добавить aria-атрибуты к контейнеру Tooltip.
+- **Controlled / Uncontrolled**: если `isOpen` не передан — компонент сам управляет `openState`. При передаче `isOpen` обязательно передавать `toggle`, иначе компонент не сможет переключать состояние.
+- `forwardRef` пробрасывает `ref` на внутренний `ButtonIcon` (кнопку-триггер). Внутренний `buttonRef` используется для позиционирования Tooltip через `targetRef`.
+- HelpBox — обёртка над несколькими внутренними компонентами: `ButtonIcon` (`shape=CIRCLE`), `Tooltip` (`toggleType="hover"`, `role="dialog"`), `FocusTrap` (только desktop) и опциональный `TooltipMobileHeader` (рендерится только при наличии `mobileHeaderContent`).
 
 ---
 
@@ -120,30 +68,41 @@ HelpBox — обёртка над несколькими внутренними
 
 ---
 
+## Accessibility
+
+- Кнопка-триггер — нативный `<button>` через `ButtonIcon`, `shape=CIRCLE`.
+- **`aria-label` триггера** — не захардкожен. Потребитель **обязан** передать `aria-label` через `...rest` (например, `aria-label="Подсказка"`). Библиотека мультиязычная, текст не хардкодится.
+- **`aria-label` кнопки закрытия** — передаётся через `tooltipXButtonProps={{ "aria-label": "Закрыть" }}`. Потребитель **обязан** указать значение на своём языке.
+- Tooltip открывается с `role="dialog"`, `tabIndex={-1}`.
+- FocusTrap удерживает фокус внутри открытого тултипа на desktop. При активации: `initialFocus` — элемент Tooltip (по ID), `clickOutsideDeactivates: true` — клик за пределами закрывает, `preventScroll: true`. Потребитель может расширить настройки через `focusTrapProps.focusTrapOptions`.
+- `tooltipAriaAttributes` позволяет добавить aria-атрибуты к контейнеру Tooltip.
+
+---
+
 ## Связанные компоненты
 
-- `Tooltip` (`src/components/Tooltip/`) — всплывающая подсказка, основной визуальный элемент
-- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — кнопка-триггер
-- `MobileView` (`src/components/MobileView/`) — переключение desktop/mobile поведения
-- `FocusTrap` (npm: `focus-trap-react`) — ловушка фокуса для desktop
+- `Tooltip` (`src/components/Tooltip/`) — всплывающая подсказка, основной визуальный элемент.
+- `ButtonIcon` (`src/components/Button/ButtonIcon.tsx`) — кнопка-триггер.
+- `MobileView` (`src/components/MobileView/`) — переключение desktop/mobile поведения.
+- `FocusTrap` (npm: `focus-trap-react`) — ловушка фокуса для desktop.
 
 ---
 
 ## Stories
 
-`stories/HelpBox/HelpBox.stories.tsx`
+Основные истории: `stories/HelpBox/HelpBox.stories.tsx`
 Файлы примеров: `stories/HelpBox/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | — | Интерактивный контроль всех props (inline в `*.stories.tsx`) |
-| `Default` | `DefaultExample.tsx` | Минимальное использование |
-| `Sizes` | `SizesExample.tsx` | Размеры тултипа SM / LG |
-| `Placement` | `PlacementExample.tsx` | Расположение: above, below, left, right |
-| `WithMobileHeader` | `WithMobileHeaderExample.tsx` | Мобильный заголовок |
-| `Controlled` | `ControlledExample.tsx` | Управляемое состояние (isOpen + toggle) |
-| `ChangeIconProps` | `ChangeIconPropsExample.tsx` | Кастомизация иконки через iconProps |
-| `VisualTests` | — | Скриншот-тест с открытым тултипом (inline в `*.stories.tsx`) |
+| `Playground` | — | Интерактивный контроль всех props |
+| `Default` | `Default.tsx` | Минимальное использование |
+| `Sizes` | `Sizes.tsx` | Размеры тултипа `SM` / `LG` |
+| `Placement` | `Placement.tsx` | Расположение: above, below, left, right |
+| `WithMobileHeader` | `WithMobileHeader.tsx` | Мобильный заголовок |
+| `Controlled` | `Controlled.tsx` | Управляемое состояние (`isOpen` + `toggle`) |
+| `ChangeIconProps` | `ChangeIconProps.tsx` | Кастомизация иконки через `iconProps` |
+| `VisualTests` | — | Скриншот-тест с открытым тултипом |
 
 ---
 
@@ -152,6 +111,8 @@ HelpBox — обёртка над несколькими внутренними
 | Дата | Изменение |
 |---|---|
 | 2026-04-08 | Создан документ. Добавлен `forwardRef`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убраны секции «Файловая структура» и «Ключевые особенности реализации», их содержимое перенесено в `Ограничения использования` и `Accessibility`, переставлены секции, добавлена колонка `Example file`. |
+| 2026-07-08 | Актуализирована колонка `Example file`: имена файлов примеров приведены к фактическим (без постфикса `Example`). |
 
 ---
 
@@ -159,13 +120,13 @@ HelpBox — обёртка над несколькими внутренними
 
 ### Default
 
-`stories/HelpBox/examples/DefaultExample.tsx`
+`stories/HelpBox/examples/Default.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const DefaultExample = () => (
+export const Default = () => (
     <div style={{ padding: 50 }}>
         <HelpBox tooltipSize={ETooltipSize.SM} aria-label="Подсказка" tooltipXButtonProps={{ "aria-label": "Закрыть" }}>
             Подсказка по элементу интерфейса
@@ -176,13 +137,13 @@ export const DefaultExample = () => (
 
 ### Sizes
 
-`stories/HelpBox/examples/SizesExample.tsx`
+`stories/HelpBox/examples/Sizes.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const SizesExample = () => (
+export const Sizes = () => (
     <div style={{ padding: 50, display: "flex", gap: 100 }}>
         <div>
             <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
@@ -212,13 +173,13 @@ export const SizesExample = () => (
 
 ### Placement
 
-`stories/HelpBox/examples/PlacementExample.tsx`
+`stories/HelpBox/examples/Placement.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const PlacementExample = () => (
+export const Placement = () => (
     <div style={{ padding: 50, display: "grid", gridTemplateColumns: "repeat(2, minmax(120px, 1fr))", gap: 32 }}>
         <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
             <span style={{ width: 150 }}>above</span>
@@ -270,13 +231,13 @@ export const PlacementExample = () => (
 
 ### WithMobileHeader
 
-`stories/HelpBox/examples/WithMobileHeaderExample.tsx`
+`stories/HelpBox/examples/WithMobileHeader.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const WithMobileHeaderExample = () => (
+export const WithMobileHeader = () => (
     <div style={{ padding: 50 }}>
         <HelpBox
             tooltipSize={ETooltipSize.SM}
@@ -292,13 +253,13 @@ export const WithMobileHeaderExample = () => (
 
 ### Controlled
 
-`stories/HelpBox/examples/ControlledExample.tsx`
+`stories/HelpBox/examples/Controlled.tsx`
 
 ```tsx
 import React, { useState } from "react";
 import { HelpBox, ETooltipSize, ETooltipPreferPlace } from "@sberbusiness/triplex-next";
 
-export const ControlledExample = () => {
+export const Controlled = () => {
     const [open, setOpen] = useState(false);
 
     const handleToggle = (nextOpen: boolean) => setOpen(nextOpen);
@@ -330,13 +291,13 @@ export const ControlledExample = () => {
 
 ### ChangeIconProps
 
-`stories/HelpBox/examples/ChangeIconPropsExample.tsx`
+`stories/HelpBox/examples/ChangeIconProps.tsx`
 
 ```tsx
 import React from "react";
 import { HelpBox, ETooltipSize } from "@sberbusiness/triplex-next";
 
-export const ChangeIconPropsExample = () => (
+export const ChangeIconProps = () => (
     <div style={{ padding: 50 }}>
         <HelpBox
             tooltipSize={ETooltipSize.SM}