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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +10 -0
  2. package/bundle/components/BodyPage.md +186 -0
  3. package/bundle/components/Button.md +90 -85
  4. package/bundle/components/ButtonDropdown.md +28 -70
  5. package/bundle/components/ButtonIcon.md +35 -48
  6. package/bundle/components/Checkbox.md +43 -122
  7. package/bundle/components/CheckboxXGroup.md +109 -46
  8. package/bundle/components/CheckboxYGroup.md +77 -49
  9. package/bundle/components/CollapsibleTree.md +581 -0
  10. package/bundle/components/CollapsibleTreeExtended.md +418 -0
  11. package/bundle/components/EmptyView.md +14 -15
  12. package/bundle/components/FooterPage.md +203 -0
  13. package/bundle/components/Gap.md +115 -57
  14. package/bundle/components/HeaderPage.md +226 -0
  15. package/bundle/components/HelpBox.md +45 -84
  16. package/bundle/components/ImageGallery.md +423 -0
  17. package/bundle/components/ImageGalleryExtended.md +606 -0
  18. package/bundle/components/List.md +194 -186
  19. package/bundle/components/ListItem.md +251 -0
  20. package/bundle/components/ListItemControlsButton.md +103 -0
  21. package/bundle/components/ListItemControlsButtonDropdown.md +107 -0
  22. package/bundle/components/ListItemSelectable.md +99 -0
  23. package/bundle/components/ListItemTable.md +390 -0
  24. package/bundle/components/ListMaster.md +877 -156
  25. package/bundle/components/ListMasterFooter.md +80 -0
  26. package/bundle/components/ListMasterHeader.md +86 -0
  27. package/bundle/components/ListSortable.md +153 -0
  28. package/bundle/components/ListSortableItem.md +175 -0
  29. package/bundle/components/ModalWindow.md +427 -237
  30. package/bundle/components/MonthYearField.md +145 -109
  31. package/bundle/components/Notification.md +625 -155
  32. package/bundle/components/Overlay.md +271 -170
  33. package/bundle/components/Page.md +283 -186
  34. package/bundle/components/Pagination.md +206 -229
  35. package/bundle/guides/codestyle.md +38 -11
  36. package/bundle/guides/commits.md +1 -2
  37. package/bundle/guides/context.md +34 -30
  38. package/bundle/guides/stories.md +110 -40
  39. package/bundle/guides/template.md +3 -7
  40. package/bundle/guides/tests.md +6 -2
  41. package/bundle/manifest.json +194 -24
  42. package/bundle/release-notes/1.26.0.mdx +33 -2
  43. package/bundle/release-notes/1.27.0.mdx +43 -0
  44. package/bundle/release-notes/1.28.0.mdx +25 -0
  45. package/bundle/release-notes/1.29.0.mdx +47 -0
  46. package/bundle/release-notes/1.30.0.mdx +56 -0
  47. package/bundle/release-notes/1.31.0.mdx +52 -0
  48. package/bundle/release-notes/1.32.0.mdx +35 -0
  49. package/bundle/release-notes/1.33.0.mdx +61 -0
  50. package/bundle/release-notes/1.34.0.mdx +35 -0
  51. package/bundle/release-notes/1.35.0.mdx +21 -0
  52. package/bundle/release-notes/1.35.1.mdx +11 -0
  53. package/bundle/release-notes/1.36.0.mdx +21 -0
  54. package/bundle/release-notes/1.37.0.mdx +30 -0
  55. package/package.json +1 -1
@@ -0,0 +1,203 @@
1
+ ---
2
+ component: FooterPage
3
+ category: Page
4
+ related: [Page, HeaderPage, BodyPage, Footer, Island, LightBox]
5
+ tokens: [--triplex-next-FooterPage-StickyShadow]
6
+ stories: stories/Page/FooterPage/FooterPage.stories.tsx
7
+ version: "1.0"
8
+ ---
9
+
10
+ # FooterPage
11
+
12
+ ## Назначение
13
+
14
+ Футер страницы `Page`. Доступен как статическое свойство `Page.Footer`. Нижний блок страницы
15
+ с контентом и управляющими элементами (кнопки, ссылки), располагается под `Page.Body`.
16
+
17
+ Контент обычно строится через составной `Page.Footer.Description` с областями
18
+ `Page.Footer.Description.Content` и `Page.Footer.Description.Controls`.
19
+
20
+ Используй когда: нужен нижний блок страницы с действиями — как в карточке (Island), так и без неё;
21
+ а также прилипающий к низу футер внутри `LightBox`.
22
+ Не используй когда: нужен заголовок или тело страницы — для этого есть `Page.Header` / `Page.Body`.
23
+
24
+ ---
25
+
26
+ ## Варианты и props
27
+
28
+ Публичный API — discriminated union по `type`: `IFooterPageTypeFirstProps | IFooterPageTypeSecondProps`.
29
+ Оба интерфейса расширяют `IFooterProps` (≈ `React.HTMLAttributes<HTMLDivElement>`).
30
+
31
+ ### Обязательные props
32
+
33
+ | Prop | Тип | Описание |
34
+ |---|---|---|
35
+ | `type` | `EFooterPageType` | `FIRST` — футер оборачивается в `Island` (карточка с белым фоном и тенью). `SECOND` — футер без карточки. |
36
+ | `children` | `React.ReactNode` | Контент футера страницы. |
37
+
38
+ ### Опциональные props
39
+
40
+ | Prop | Тип | По умолчанию | Описание |
41
+ |---|---|---|---|
42
+ | `sticky` | `boolean` | `false` | Футер прилипает к нижней границе при скролле. **Только для `type=FIRST`** (внутри `LightBox`); для `type=SECOND` типизирован как `never`. |
43
+ | `size` | `EComponentSize` | — | Размер острова (Island). **Доступен только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
44
+
45
+ ### Ограничения по типам
46
+
47
+ - `size` и `sticky` доступны только при `type=FIRST` (в `SECOND` контент не оборачивается в Island,
48
+ поэтому оба типизированы как `never`).
49
+
50
+ ---
51
+
52
+ ## Дизайн-токены
53
+
54
+ | Токен | Назначение |
55
+ |---|---|
56
+ | `--triplex-next-FooterPage-StickyShadow` | Тень прилипшего футера (когда `sticky` и футер коснулся нижней границы, `data-stuck="true"`). |
57
+
58
+ Внешний вид карточки наследуется от `Island` (`EIslandType.TYPE_1`). Радиус нижних углов при
59
+ прилипании плавно обнуляется через CSS-переменную `--r-bottom` (управляется хуком
60
+ `useStickyCornerRadius`).
61
+
62
+ ---
63
+
64
+ ## Инварианты
65
+
66
+ - `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой элемент
67
+ (Island для FIRST, Footer для SECOND).
68
+ - Ручной merge ref (`setFooterRef`) обязателен: ref нужен одновременно хуку
69
+ `useStickyCornerRadius` (внутренний `footerRef`) и наружу (проброшенный `ref`). Не упрощать.
70
+ - `displayName = "FooterPage"` — не менять.
71
+ - `FooterPage` собран через `Object.assign(forwardRef(...), { Description })` — статическое
72
+ свойство `Description` (= `Footer.Description`) должно сохраняться.
73
+ - Discriminated union по `type` и значения `EFooterPageType` — часть публичного API, менять нельзя.
74
+ - Экспорты `FooterPage`, `IFooterPageTypeFirstProps`, `IFooterPageTypeSecondProps` идут в barrel
75
+ `src/components/Page/index.ts` — сохранять.
76
+
77
+ ---
78
+
79
+ ## Accessibility
80
+
81
+ Особого a11y-поведения нет — это структурный контейнер. Семантику и aria-атрибуты задаёт
82
+ потребитель через проброшенные HTML-атрибуты (`...rest` уходит в `Footer`). Интерактивность
83
+ обеспечивают вложенные кнопки/ссылки внутри `Description.Controls`.
84
+
85
+ ---
86
+
87
+ ## Связанные компоненты
88
+
89
+ - `Page` — родитель; `FooterPage` доступен как `Page.Footer`.
90
+ - `HeaderPage` (`Page.Header`), `BodyPage` (`Page.Body`) — соседи внутри `Page`.
91
+ - `Footer` — внутренний контейнер футера; `Page.Footer.Description` = `Footer.Description`.
92
+ - `Island` — карточка-обёртка для `type=FIRST`.
93
+ - `LightBox` — типичное место использования с `sticky`.
94
+
95
+ ---
96
+
97
+ ## Stories
98
+
99
+ Основные истории: `stories/Page/FooterPage/FooterPage.stories.tsx`
100
+ Файлы примеров: `stories/Page/FooterPage/examples/`
101
+
102
+ | Story | Example file | Что демонстрирует |
103
+ |---|---|---|
104
+ | `Playground` | `Playground.tsx` | Интерактивный контроль `type`, `size` |
105
+ | `Default` | `Default.tsx` | Минимальный пример (FIRST, футер в карточке) |
106
+ | `Types` | `Types.tsx` | Сравнение типов FIRST и SECOND (покрывает скриншот-регрессию) |
107
+
108
+ ---
109
+
110
+ ## История изменений
111
+
112
+ | Дата | Изменение |
113
+ |---|---|
114
+ | 2026-06-19 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
115
+
116
+ ---
117
+
118
+ ## Примеры использования
119
+
120
+ ### Default
121
+
122
+ `stories/Page/FooterPage/examples/Default.tsx`
123
+
124
+ ```tsx
125
+ import React from "react";
126
+ import {
127
+ Page,
128
+ EFooterPageType,
129
+ EComponentSize,
130
+ Button,
131
+ EButtonTheme,
132
+ Text,
133
+ ETextSize,
134
+ } from "@sberbusiness/triplex-next";
135
+
136
+ export const Default = () => (
137
+ <Page.Footer type={EFooterPageType.FIRST}>
138
+ <Page.Footer.Description>
139
+ <Page.Footer.Description.Content>
140
+ <Text size={ETextSize.B3}>Контент футера страницы</Text>
141
+ </Page.Footer.Description.Content>
142
+ <Page.Footer.Description.Controls>
143
+ <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY}>
144
+ Отмена
145
+ </Button>
146
+ <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
147
+ Сохранить
148
+ </Button>
149
+ </Page.Footer.Description.Controls>
150
+ </Page.Footer.Description>
151
+ </Page.Footer>
152
+ );
153
+ ```
154
+
155
+ ### Types
156
+
157
+ `stories/Page/FooterPage/examples/Types.tsx`
158
+
159
+ ```tsx
160
+ import React from "react";
161
+ import {
162
+ Page,
163
+ EFooterPageType,
164
+ EComponentSize,
165
+ Button,
166
+ EButtonTheme,
167
+ Text,
168
+ ETextSize,
169
+ } from "@sberbusiness/triplex-next";
170
+
171
+ const controls = (type: EFooterPageType) => (
172
+ <Page.Footer.Description>
173
+ <Page.Footer.Description.Content>
174
+ <Text size={ETextSize.B3}>Контент футера страницы</Text>
175
+ </Page.Footer.Description.Content>
176
+ <Page.Footer.Description.Controls>
177
+ <Button
178
+ size={EComponentSize.MD}
179
+ theme={type === EFooterPageType.FIRST ? EButtonTheme.SECONDARY : EButtonTheme.SECONDARY_LIGHT}
180
+ >
181
+ Отмена
182
+ </Button>
183
+ <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
184
+ Сохранить
185
+ </Button>
186
+ </Page.Footer.Description.Controls>
187
+ </Page.Footer.Description>
188
+ );
189
+
190
+ export const Types = () => (
191
+ <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
192
+ <div>
193
+ <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>FIRST</div>
194
+ <Page.Footer type={EFooterPageType.FIRST}>{controls(EFooterPageType.FIRST)}</Page.Footer>
195
+ </div>
196
+ <div>
197
+ <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>SECOND</div>
198
+ <Page.Footer type={EFooterPageType.SECOND}>{controls(EFooterPageType.SECOND)}</Page.Footer>
199
+ </div>
200
+ </div>
201
+ );
202
+ ```
203
+
@@ -1,9 +1,7 @@
1
1
  ---
2
2
  component: Gap
3
3
  category: Layout
4
- figma-node: ""
5
- figma-file: ""
6
- related: [Row, Col, Divider]
4
+ related: [Divider, Col, Row]
7
5
  tokens: []
8
6
  stories: stories/Gap/Gap.stories.tsx
9
7
  version: "1.0"
@@ -13,96 +11,78 @@ version: "1.0"
13
11
 
14
12
  ## Назначение
15
13
 
16
- Вертикальный разделитель-пустота: пустой `<div>` фиксированной высоты для
17
- отступа между блоками по вертикали. Принципиально ограничен дискретным
18
- набором размеров из дизайн-системы.
14
+ Вертикальный отступ-разделитель фиксированной высоты между блоками. Рендерит пустой `<div>` с `role="presentation"` без визуального контента — только пространство.
19
15
 
20
- Используй когда: нужен вертикальный spacer, а переиспользовать margin/padding
21
- родителя неудобно (например, между двумя независимыми секциями).
22
- Не используй когда: можешь задать отступ через `gap` flex-контейнера или
23
- margin соседа — это семантически предпочтительнее.
16
+ Используй когда: нужно добавить вертикальный отступ между двумя соседними блоками из заранее заданной шкалы значений дизайн-системы (4, 8, 12, 16, 24, 32, 64, 128 px).
24
17
 
25
- ---
26
-
27
- ## Файловая структура
28
-
29
- ```text
30
- src/components/Gap/
31
- ├── Gap.tsx # forwardRef, <div role="presentation">, height из size
32
- ├── index.ts # Barrel
33
- └── __tests__/Gap.test.tsx
34
- ```
18
+ Не используй когда:
19
+ - Нужен горизонтальный отступ — управляй им через `margin`/`padding` родителя или через `Col`/`Row` сетки.
20
+ - Нужна визуальная линия-разделитель — используй `Divider`.
21
+ - Нужен отступ произвольной величины (не из шкалы) — задай его через стили родителя, не вводи новое значение `TGapSize`.
35
22
 
36
23
  ---
37
24
 
38
25
  ## Варианты и props
39
26
 
40
- ### `IGapProps extends Omit<HTMLAttributes<HTMLDivElement>, "children">`
27
+ ### Обязательные props
41
28
 
42
- | Prop | Тип | Обязателен | Описание |
43
- |---|---|---|---|
44
- | `size` | `TGapSize` | Да | Высота в пикселях. **Разрешённые значения строго**: `4 \| 8 \| 12 \| 16 \| 24 \| 32 \| 64 \| 128`. |
45
- | `className`, `style`, `...HTMLDivAttributes` | — | — | `style.height` перезаписывается через `${size}px`. |
29
+ | Prop | Тип | Описание |
30
+ |---|---|---|
31
+ | `size` | `TGapSize` | Высота отступа в пикселях. Один из значений шкалы: `4 \| 8 \| 12 \| 16 \| 24 \| 32 \| 64 \| 128`. |
46
32
 
47
- `children` специально исключён — Gap это пустой разделитель.
33
+ ### Опциональные props
48
34
 
49
- ---
35
+ Компонент расширяет `Omit<React.HTMLAttributes<HTMLDivElement>, "children">`, поэтому принимает все стандартные атрибуты `<div>` (включая `className`, `style`, `aria-*`, `data-*`) кроме `children` — пробрасывание содержимого внутрь Gap запрещено типом.
50
36
 
51
- ## Ключевые особенности реализации
37
+ ### Ограничения
52
38
 
53
- Реализация — одна строка JSX:
54
- ```tsx
55
- <div style={{ height: `${size}px`, ...style }} role="presentation" {...restProps} ref={ref} />
56
- ```
57
-
58
- - `role="presentation"` — скринридер игнорирует элемент.
59
- - `style={{ height, ...style }}` — позволяет перекрыть `height` через props, но порядок такой, что `style` из props идёт **после** и может затереть высоту. Это поведение сохранить (намеренная свобода для кастомных кейсов).
60
- - Нет собственного `className`/стилей — только inline height.
39
+ - `children` исключён из props — Gap не должен оборачивать контент, только разделять его. Если нужно — используй другой контейнер.
40
+ - Прокидываемый снаружи `style.height` переопределит высоту, заданную CSS-классом (более высокая специфичность inline-style). Это допустимо для крайних случаев, но штатно высоту задаёт `size`.
61
41
 
62
42
  ---
63
43
 
64
- ## Инварианты
44
+ ## Дизайн-токены
65
45
 
66
- - **`TGapSize` union** — публичный API. Добавлять новые значения можно, существующие
67
- (4/8/12/16/24/32/64/128) удалять нельзя (breaking change).
68
- - **`forwardRef`** — не убирать.
69
- - **`role="presentation"`** — не менять без причины (a11y-контракт: spacer не объявляется).
70
- - **Вертикальный (`height`) только**. Для горизонтального spacing используй `gap`
71
- flex-контейнера или `Col`. Не добавляй prop `direction`, пока не появится явный запрос.
72
- - **Без `children`** — тип `Omit<..., "children">` запрещает передачу через TS.
46
+ Компонент не использует собственных CSS-переменных. Высота задаётся фиксированными значениями в пикселях из CSS-модуля `styles/Gap.module.less` (классы `.size4`, `.size8`, ..., `.size128`).
73
47
 
74
48
  ---
75
49
 
76
- ## Accessibility
50
+ ## Инварианты
77
51
 
78
- - `role="presentation"` — элемент скрыт от скринридеров.
79
- - Tab-навигация через Gap не проходит (нет фокусируемых детей).
52
+ - **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<div>`.
53
+ - **`TGapSize`** — публичный union type, экспортируется из barrel. Изменение перечня значений (добавление/удаление чисел) — breaking change.
54
+ - **`IGapProps`** имя интерфейса и `Gap` имя компонента — часть публичного API.
55
+ - **`role="presentation"`** на корневом `<div>` — компонент семантически невидим для assistive technologies.
56
+ - **`Omit<..., "children">`** в `IGapProps` — публичный контракт, что Gap не принимает потомков.
57
+ - **CSS-классы `size4`...`size128`** в `Gap.module.less` — camelCase согласно `docs/ai/codestyle.md`. Могут использоваться в тестах, переименование требует синхронного обновления тестов.
80
58
 
81
59
  ---
82
60
 
83
- ## Дизайн-токены
61
+ ## Accessibility
84
62
 
85
- Нет. Размеры заданы литералами в `TGapSize` — это часть контракта, а не CSS-токены.
63
+ - Корневой `<div>` имеет `role="presentation"` — Gap не несёт смысловой нагрузки и игнорируется screen reader'ами.
64
+ - Потребитель может передать дополнительные `aria-*` атрибуты через spread (например, `aria-hidden="true"`), но штатно `role="presentation"` уже исключает компонент из accessibility-дерева.
65
+ - Компонент не интерактивный — keyboard navigation и focus management не применимы.
86
66
 
87
67
  ---
88
68
 
89
69
  ## Связанные компоненты
90
70
 
91
- - `Row` / `Col` — обычно предпочтительнее, если есть полноценный flex-layout.
92
- - `Divider` — визуальный разделитель (с линией), а не пустой отступ.
71
+ - `Divider` (`src/components/Divider/`) — горизонтальная линия-разделитель с собственными отступами `marginTopSize`/`marginBottomSize`. Используй вместо Gap, когда нужно визуально разделить блоки линией.
72
+ - `Col`, `Row` (`src/components/Col/`, `src/components/Row/`) — компоненты сетки. Управляют отступами через систему columns/offsets, а не через явный разделитель.
93
73
 
94
74
  ---
95
75
 
96
76
  ## Stories
97
77
 
98
- `stories/Gap/Gap.stories.tsx`
99
- Примеры: `stories/Gap/examples/`
78
+ Основные истории: `stories/Gap/Gap.stories.tsx`
79
+ Файлы примеров: `stories/Gap/examples/`
100
80
 
101
81
  | Story | Example file | Что демонстрирует |
102
82
  |---|---|---|
103
- | `Playground` | — | Интерактивный выбор `size`. |
104
- | `Default` | `DefaultExample.tsx` | Базовое использование. |
105
- | `Sizes` | `SizesExample.tsx` | Все значения `TGapSize`. |
83
+ | `Playground` | — | Интерактивный контроль `size` через select со всеми значениями `TGapSize` |
84
+ | `Default` | `DefaultExample.tsx` | Минимальное использование с `size={16}` между двумя блоками |
85
+ | `Sizes` | `SizesExample.tsx` | Все 8 значений `TGapSize`: 4, 8, 12, 16, 24, 32, 64, 128 px |
106
86
 
107
87
  ---
108
88
 
@@ -110,4 +90,82 @@ src/components/Gap/
110
90
 
111
91
  | Дата | Изменение |
112
92
  |---|---|
113
- | 2026-04-18 | Создан документ |
93
+ | 2026-05-20 | Создан документ. AI-рефакторинг: inline-`style` высоты заменён на CSS-классы из `Gap.module.less`, добавлены JSDoc на `Gap`, `TGapSize`, `IGapProps.size`, расширены unit-тесты (forwardRef, все значения `size`, `role="presentation"`). |
94
+
95
+ ---
96
+
97
+ ## Примеры использования
98
+
99
+ ### Default
100
+
101
+ `stories/Gap/examples/DefaultExample.tsx`
102
+
103
+ ```tsx
104
+ import React from "react";
105
+ import { Gap } from "@sberbusiness/triplex-next";
106
+
107
+ export const DefaultExample = () => (
108
+ <div>
109
+ <div
110
+ style={{
111
+ padding: "16px",
112
+ textAlign: "center",
113
+ backgroundColor: "rgb(255, 217, 160)",
114
+ }}
115
+ >
116
+ Sample Text Above
117
+ </div>
118
+
119
+ <Gap size={16} />
120
+
121
+ <div
122
+ style={{
123
+ padding: "16px",
124
+ textAlign: "center",
125
+ backgroundColor: "rgb(255, 217, 160)",
126
+ }}
127
+ >
128
+ Sample Text Below
129
+ </div>
130
+ </div>
131
+ );
132
+ ```
133
+
134
+ ### Sizes
135
+
136
+ `stories/Gap/examples/SizesExample.tsx`
137
+
138
+ ```tsx
139
+ import React from "react";
140
+ import { Gap, TGapSize } from "@sberbusiness/triplex-next";
141
+
142
+ const SIZES: TGapSize[] = [4, 8, 12, 16, 24, 32, 64, 128];
143
+
144
+ const blockStyle: React.CSSProperties = {
145
+ padding: "16px",
146
+ textAlign: "center",
147
+ backgroundColor: "rgb(255, 217, 160)",
148
+ };
149
+
150
+ interface ISizeItemProps {
151
+ size: TGapSize;
152
+ }
153
+
154
+ const SizeItem = ({ size }: ISizeItemProps) => (
155
+ <div>
156
+ <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size}px</div>
157
+ <div style={blockStyle}>Above</div>
158
+ <Gap size={size} />
159
+ <div style={blockStyle}>Below</div>
160
+ </div>
161
+ );
162
+
163
+ export const SizesExample = () => (
164
+ <div style={{ display: "flex", flexDirection: "column", gap: "24px", maxWidth: "300px" }}>
165
+ {SIZES.map((size) => (
166
+ <SizeItem key={size} size={size} />
167
+ ))}
168
+ </div>
169
+ );
170
+ ```
171
+
@@ -0,0 +1,226 @@
1
+ ---
2
+ component: HeaderPage
3
+ category: Page
4
+ related: [Page, BodyPage, FooterPage, Header, Island, LightBox]
5
+ tokens: [--triplex-next-HeaderPage-StickyShadow]
6
+ stories: stories/Page/HeaderPage/HeaderPage.stories.tsx
7
+ version: "1.0"
8
+ ---
9
+
10
+ # HeaderPage
11
+
12
+ ## Назначение
13
+
14
+ Заголовок страницы `Page`. Доступен как статическое свойство `Page.Header`. Верхний блок страницы
15
+ с заголовком, табами и подзаголовком, располагается над `Page.Body`.
16
+
17
+ Контент строится через составные части `Page.Header`: `Page.Header.Title` (с областями `Content`
18
+ и `Controls`), `Page.Header.Tabs` (с областями `Content` и `Controls`), `Page.Header.Subhead` и
19
+ `Page.Header.LayoutSidebar` (с областями `Content` и `Sidebar`).
20
+
21
+ Используй когда: нужен верхний блок страницы с заголовком и действиями — как в карточке (Island),
22
+ так и без неё; а также прилипающий к верху заголовок внутри `LightBox`.
23
+ Не используй когда: нужно тело или футер страницы — для этого есть `Page.Body` / `Page.Footer`.
24
+
25
+ ---
26
+
27
+ ## Варианты и props
28
+
29
+ Публичный API — discriminated union по `type`: `IHeaderPageTypeFirstProps | IHeaderPageTypeSecondProps`.
30
+ Оба интерфейса расширяют `IHeaderProps` (≈ `React.HTMLAttributes<HTMLDivElement>`).
31
+
32
+ ### Обязательные props
33
+
34
+ | Prop | Тип | Описание |
35
+ |---|---|---|
36
+ | `type` | `EHeaderPageType` | `FIRST` — заголовок оборачивается в `Island` (карточка с белым фоном и тенью). `SECOND` — заголовок без карточки. |
37
+ | `children` | `React.ReactNode` | Контент заголовка страницы. |
38
+
39
+ ### Опциональные props
40
+
41
+ | Prop | Тип | По умолчанию | Описание |
42
+ |---|---|---|---|
43
+ | `sticky` | `boolean` | `false` | Заголовок прилипает к верхней границе при скролле. **Только для `type=FIRST`** (внутри `LightBox`); для `type=SECOND` типизирован как `never`. |
44
+ | `size` | `EComponentSize` | — | Размер острова (Island). **Доступен только для `type=FIRST`**; для `type=SECOND` типизирован как `never`. |
45
+
46
+ ### Ограничения по типам
47
+
48
+ - `size` и `sticky` доступны только при `type=FIRST` (в `SECOND` контент не оборачивается в Island,
49
+ поэтому оба типизированы как `never`).
50
+
51
+ ---
52
+
53
+ ## Дизайн-токены
54
+
55
+ | Токен | Назначение |
56
+ |---|---|
57
+ | `--triplex-next-HeaderPage-StickyShadow` | Тень прилипшего заголовка (когда `sticky` и заголовок коснулся верхней границы, `data-stuck="true"`). |
58
+
59
+ Внешний вид карточки наследуется от `Island` (`EIslandType.TYPE_1`). Радиус верхних углов при
60
+ прилипании плавно обнуляется через CSS-переменную `--r-top` (управляется хуком
61
+ `useStickyCornerRadius` с `edge="top"`).
62
+
63
+ ---
64
+
65
+ ## Инварианты
66
+
67
+ - `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой элемент
68
+ (Island для FIRST, Header для SECOND).
69
+ - Ручной merge ref (`setIslandRef`) обязателен: ref нужен одновременно хуку
70
+ `useStickyCornerRadius` (внутренний `islandRef`) и наружу (проброшенный `ref`). Не упрощать.
71
+ - `displayName = "HeaderPage"` — не менять.
72
+ - `HeaderPage` собран через `Object.assign(forwardRef(...), { LayoutSidebar, Subhead, Tabs, Title })` —
73
+ статические свойства (= `Header.LayoutSidebar` / `Header.Subhead` / `Header.Tabs` / `Header.Title`)
74
+ должны сохраняться.
75
+ - Discriminated union по `type` и значения `EHeaderPageType` — часть публичного API, менять нельзя.
76
+ - Экспорты `HeaderPage`, `IHeaderPageTypeFirstProps`, `IHeaderPageTypeSecondProps` идут в barrel
77
+ `src/components/Page/index.ts` — сохранять.
78
+
79
+ ---
80
+
81
+ ## Accessibility
82
+
83
+ Особого a11y-поведения нет — это структурный контейнер. Семантику и aria-атрибуты задаёт
84
+ потребитель через проброшенные HTML-атрибуты (`...rest` уходит в `Header`). Интерактивность
85
+ обеспечивают вложенные кнопки/ссылки/табы внутри `Title.Controls` / `Tabs.Controls`.
86
+
87
+ ---
88
+
89
+ ## Связанные компоненты
90
+
91
+ - `Page` — родитель; `HeaderPage` доступен как `Page.Header`.
92
+ - `BodyPage` (`Page.Body`), `FooterPage` (`Page.Footer`) — соседи внутри `Page`.
93
+ - `Header` — внутренний контейнер заголовка; статика `Page.Header.Title` / `Tabs` / `Subhead` /
94
+ `LayoutSidebar` берётся из `Header.*`.
95
+ - `Island` — карточка-обёртка для `type=FIRST`.
96
+ - `LightBox` — типичное место использования с `sticky`.
97
+
98
+ ---
99
+
100
+ ## Stories
101
+
102
+ Основные истории: `stories/Page/HeaderPage/HeaderPage.stories.tsx`
103
+ Файлы примеров: `stories/Page/HeaderPage/examples/`
104
+
105
+ | Story | Example file | Что демонстрирует |
106
+ |---|---|---|
107
+ | `Playground` | `Playground.tsx` | Интерактивный контроль `type` и `size` |
108
+ | `Default` | `Default.tsx` | Минимальный пример (FIRST, заголовок в карточке) |
109
+ | `Types` | `Types.tsx` | Сравнение типов FIRST и SECOND (покрывает скриншот-регрессию) |
110
+
111
+ ---
112
+
113
+ ## История изменений
114
+
115
+ | Дата | Изменение |
116
+ |---|---|
117
+ | 2026-06-23 | Создан документ. AI-рефакторинг (clsx order, JSDoc на props, displayName), unit-тесты, миграция stories на modern pattern. |
118
+
119
+ ---
120
+
121
+ ## Примеры использования
122
+
123
+ ### Default
124
+
125
+ `stories/Page/HeaderPage/examples/Default.tsx`
126
+
127
+ ```tsx
128
+ import React from "react";
129
+ import {
130
+ Page,
131
+ EHeaderPageType,
132
+ EComponentSize,
133
+ Button,
134
+ EButtonTheme,
135
+ Title,
136
+ ETitleSize,
137
+ Text,
138
+ ETextSize,
139
+ EFontType,
140
+ Gap,
141
+ } from "@sberbusiness/triplex-next";
142
+
143
+ export const Default = () => (
144
+ <Page.Header type={EHeaderPageType.FIRST}>
145
+ <Page.Header.Title>
146
+ <Page.Header.Title.Content>
147
+ <Title tag="h1" size={ETitleSize.H1}>
148
+ Заголовок страницы
149
+ </Title>
150
+ <Gap size={8} />
151
+ <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
152
+ Дополнительное описание страницы
153
+ </Text>
154
+ </Page.Header.Title.Content>
155
+ <Page.Header.Title.Controls>
156
+ <Button size={EComponentSize.MD} theme={EButtonTheme.SECONDARY}>
157
+ Отмена
158
+ </Button>
159
+ <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
160
+ Сохранить
161
+ </Button>
162
+ </Page.Header.Title.Controls>
163
+ </Page.Header.Title>
164
+ </Page.Header>
165
+ );
166
+ ```
167
+
168
+ ### Types
169
+
170
+ `stories/Page/HeaderPage/examples/Types.tsx`
171
+
172
+ ```tsx
173
+ import React from "react";
174
+ import {
175
+ Page,
176
+ EHeaderPageType,
177
+ EComponentSize,
178
+ Button,
179
+ EButtonTheme,
180
+ Title,
181
+ ETitleSize,
182
+ Text,
183
+ ETextSize,
184
+ EFontType,
185
+ Gap,
186
+ } from "@sberbusiness/triplex-next";
187
+
188
+ const title = (type: EHeaderPageType) => (
189
+ <Page.Header.Title>
190
+ <Page.Header.Title.Content>
191
+ <Title tag="h1" size={ETitleSize.H1}>
192
+ Заголовок страницы
193
+ </Title>
194
+ <Gap size={8} />
195
+ <Text tag="div" size={ETextSize.B3} type={EFontType.SECONDARY}>
196
+ Дополнительное описание страницы
197
+ </Text>
198
+ </Page.Header.Title.Content>
199
+ <Page.Header.Title.Controls>
200
+ <Button
201
+ size={EComponentSize.MD}
202
+ theme={type === EHeaderPageType.FIRST ? EButtonTheme.SECONDARY : EButtonTheme.SECONDARY_LIGHT}
203
+ >
204
+ Отмена
205
+ </Button>
206
+ <Button size={EComponentSize.MD} theme={EButtonTheme.GENERAL}>
207
+ Сохранить
208
+ </Button>
209
+ </Page.Header.Title.Controls>
210
+ </Page.Header.Title>
211
+ );
212
+
213
+ export const Types = () => (
214
+ <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
215
+ <div>
216
+ <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>FIRST</div>
217
+ <Page.Header type={EHeaderPageType.FIRST}>{title(EHeaderPageType.FIRST)}</Page.Header>
218
+ </div>
219
+ <div>
220
+ <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: 700 }}>SECOND</div>
221
+ <Page.Header type={EHeaderPageType.SECOND}>{title(EHeaderPageType.SECOND)}</Page.Header>
222
+ </div>
223
+ </div>
224
+ );
225
+ ```
226
+