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

package/bundle/components/EmptyView.md

@@ -1,8 +1,6 @@
 ---
 component: EmptyView
 category: Feedback
-figma-node: "80-48"
-figma-file: "https://www.figma.com/design/lpkxmWZ512mG2OJyDvGtHD/-W--LIB-DSN-01-Components-DCB-Next-v.1.3.0"
 related: [Button]
 tokens:
   - --triplex-next-Typography-Primary_Color
@@ -28,22 +26,22 @@ version: "1.0"
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `size` | `EEmptyViewSize` | Размер: SM / MD |
+| `size` | `EEmptyViewSize` | Размер: `SM` / `MD` |
 
 ### Опциональные props
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `icon` | `ReactNode` | — | Иконка (96px для SM, 128px для MD) |
+| `icon` | `ReactNode` | — | Иконка (96px для `SM`, 128px для `MD`) |
 | `title` | `ReactNode` | — | Заголовок |
 | `description` | `ReactNode` | — | Текст описания |
 | `caption` | `ReactNode` | — | Подпись |
 | `buttons` | `ReactNode` | — | Кнопки действий |
 
-### Поведение описания
+### Ограничения по темам
 
-- Если `title` задан: описание отображается вторичным цветом (Secondary)
-- Если `title` не задан: описание становится основным текстом (Primary)
+- Если `title` задан — описание отображается вторичным цветом (Secondary).
+- Если `title` не задан — описание становится основным текстом (Primary).
 
 ---
 
@@ -58,22 +56,22 @@ version: "1.0"
 
 ## Инварианты
 
-- `forwardRef` на компоненте — не убирать
-- `EEmptyViewSize` — публичный enum, менять значения нельзя
-- CSS-классы `emptyView`, `hasTitle` используются в тестах
+- `forwardRef` на компоненте — не убирать.
+- `EEmptyViewSize` — публичный enum, менять значения нельзя.
+- CSS-классы `emptyView`, `hasTitle` используются в тестах.
 
 ---
 
 ## Accessibility
 
-- Компонент не требует обязательных aria-атрибутов
-- Потребитель может передать `role`, `aria-label` и другие атрибуты через spread
+- Компонент не требует обязательных aria-атрибутов.
+- Потребитель может передать `role`, `aria-label` и другие атрибуты через spread.
 
 ---
 
 ## Связанные компоненты
 
-- `Button` — используется в `buttons` для действий
+- `Button` — используется в `buttons` для действий.
 
 ---
 
@@ -86,7 +84,7 @@ version: "1.0"
 |---|---|---|
 | `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
 | `Default` | `DefaultExample.tsx` | Минимальное состояние с title, description и caption |
-| `Sizes` | `SizesExample.tsx` | Размеры SM / MD |
+| `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` |
 | `WithoutTitle` | `WithoutTitleExample.tsx` | Вариант без заголовка |
 | `WithButtons` | `WithButtonsExample.tsx` | Вариант с кнопками действий |
 
@@ -96,7 +94,8 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-09 | Создан компонент и документ |
+| 2026-04-09 | Создан компонент и документ. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: добавлена колонка `Example file`, переименована подсекция «Поведение описания» в «Ограничения по темам». |
 
 ---
 

package/bundle/components/FooterPage.md

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

package/bundle/components/Gap.md

@@ -1,9 +1,7 @@
 ---
 component: Gap
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Row, Col, Divider]
+related: [Divider, Col, Row]
 tokens: []
 stories: stories/Gap/Gap.stories.tsx
 version: "1.0"
@@ -13,96 +11,78 @@ version: "1.0"
 
 ## Назначение
 
-Вертикальный разделитель-пустота: пустой `<div>` фиксированной высоты для
-отступа между блоками по вертикали. Принципиально ограничен дискретным
-набором размеров из дизайн-системы.
+Вертикальный отступ-разделитель фиксированной высоты между блоками. Рендерит пустой `<div>` с `role="presentation"` без визуального контента — только пространство.
 
-Используй когда: нужен вертикальный spacer, а переиспользовать margin/padding
-родителя неудобно (например, между двумя независимыми секциями).
-Не используй когда: можешь задать отступ через `gap` flex-контейнера или
-margin соседа — это семантически предпочтительнее.
+Используй когда: нужно добавить вертикальный отступ между двумя соседними блоками из заранее заданной шкалы значений дизайн-системы (4, 8, 12, 16, 24, 32, 64, 128 px).
 
----
-
-## Файловая структура
-
-```text
-src/components/Gap/
-├── Gap.tsx     # forwardRef, <div role="presentation">, height из size
-├── index.ts    # Barrel
-└── __tests__/Gap.test.tsx
-```
+Не используй когда:
+- Нужен горизонтальный отступ — управляй им через `margin`/`padding` родителя или через `Col`/`Row` сетки.
+- Нужна визуальная линия-разделитель — используй `Divider`.
+- Нужен отступ произвольной величины (не из шкалы) — задай его через стили родителя, не вводи новое значение `TGapSize`.
 
 ---
 
 ## Варианты и props
 
-### `IGapProps extends Omit<HTMLAttributes<HTMLDivElement>, "children">`
+### Обязательные props
 
-| Prop | Тип | Обязателен | Описание |
-|---|---|---|---|
-| `size` | `TGapSize` | Да | Высота в пикселях. **Разрешённые значения строго**: `4 \| 8 \| 12 \| 16 \| 24 \| 32 \| 64 \| 128`. |
-| `className`, `style`, `...HTMLDivAttributes` | — | — | `style.height` перезаписывается через `${size}px`. |
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `TGapSize` | Высота отступа в пикселях. Один из значений шкалы: `4 \| 8 \| 12 \| 16 \| 24 \| 32 \| 64 \| 128`. |
 
-`children` специально исключён — Gap это пустой разделитель.
+### Опциональные props
 
----
+Компонент расширяет `Omit<React.HTMLAttributes<HTMLDivElement>, "children">`, поэтому принимает все стандартные атрибуты `<div>` (включая `className`, `style`, `aria-*`, `data-*`) кроме `children` — пробрасывание содержимого внутрь Gap запрещено типом.
 
-## Ключевые особенности реализации
+### Ограничения
 
-Реализация — одна строка JSX:
-```tsx
-<div style={{ height: `${size}px`, ...style }} role="presentation" {...restProps} ref={ref} />
-```
-
-- `role="presentation"` — скринридер игнорирует элемент.
-- `style={{ height, ...style }}` — позволяет перекрыть `height` через props, но порядок такой, что `style` из props идёт **после** и может затереть высоту. Это поведение сохранить (намеренная свобода для кастомных кейсов).
-- Нет собственного `className`/стилей — только inline height.
+- `children` исключён из props — Gap не должен оборачивать контент, только разделять его. Если нужно — используй другой контейнер.
+- Прокидываемый снаружи `style.height` переопределит высоту, заданную CSS-классом (более высокая специфичность inline-style). Это допустимо для крайних случаев, но штатно высоту задаёт `size`.
 
 ---
 
-## Инварианты
+## Дизайн-токены
 
-- **`TGapSize` union** — публичный API. Добавлять новые значения можно, существующие
-  (4/8/12/16/24/32/64/128) удалять нельзя (breaking change).
-- **`forwardRef`** — не убирать.
-- **`role="presentation"`** — не менять без причины (a11y-контракт: spacer не объявляется).
-- **Вертикальный (`height`) только**. Для горизонтального spacing используй `gap`
-  flex-контейнера или `Col`. Не добавляй prop `direction`, пока не появится явный запрос.
-- **Без `children`** — тип `Omit<..., "children">` запрещает передачу через TS.
+Компонент не использует собственных CSS-переменных. Высота задаётся фиксированными значениями в пикселях из CSS-модуля `styles/Gap.module.less` (классы `.size4`, `.size8`, ..., `.size128`).
 
 ---
 
-## Accessibility
+## Инварианты
 
-- `role="presentation"` — элемент скрыт от скринридеров.
-- Tab-навигация через Gap не проходит (нет фокусируемых детей).
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<div>`.
+- **`TGapSize`** — публичный union type, экспортируется из barrel. Изменение перечня значений (добавление/удаление чисел) — breaking change.
+- **`IGapProps`** имя интерфейса и `Gap` имя компонента — часть публичного API.
+- **`role="presentation"`** на корневом `<div>` — компонент семантически невидим для assistive technologies.
+- **`Omit<..., "children">`** в `IGapProps` — публичный контракт, что Gap не принимает потомков.
+- **CSS-классы `size4`...`size128`** в `Gap.module.less` — camelCase согласно `docs/ai/codestyle.md`. Могут использоваться в тестах, переименование требует синхронного обновления тестов.
 
 ---
 
-## Дизайн-токены
+## Accessibility
 
-Нет. Размеры заданы литералами в `TGapSize` — это часть контракта, а не CSS-токены.
+- Корневой `<div>` имеет `role="presentation"` — Gap не несёт смысловой нагрузки и игнорируется screen reader'ами.
+- Потребитель может передать дополнительные `aria-*` атрибуты через spread (например, `aria-hidden="true"`), но штатно `role="presentation"` уже исключает компонент из accessibility-дерева.
+- Компонент не интерактивный — keyboard navigation и focus management не применимы.
 
 ---
 
 ## Связанные компоненты
 
-- `Row` / `Col` — обычно предпочтительнее, если есть полноценный flex-layout.
-- `Divider` — визуальный разделитель (с линией), а не пустой отступ.
+- `Divider` (`src/components/Divider/`) — горизонтальная линия-разделитель с собственными отступами `marginTopSize`/`marginBottomSize`. Используй вместо Gap, когда нужно визуально разделить блоки линией.
+- `Col`, `Row` (`src/components/Col/`, `src/components/Row/`) — компоненты сетки. Управляют отступами через систему columns/offsets, а не через явный разделитель.
 
 ---
 
 ## Stories
 
-`stories/Gap/Gap.stories.tsx`
-Примеры: `stories/Gap/examples/`
+Основные истории: `stories/Gap/Gap.stories.tsx`
+Файлы примеров: `stories/Gap/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | — | Интерактивный выбор `size`. |
-| `Default` | `DefaultExample.tsx` | Базовое использование. |
-| `Sizes` | `SizesExample.tsx` | Все значения `TGapSize`. |
+| `Playground` | — | Интерактивный контроль `size` через select со всеми значениями `TGapSize` |
+| `Default` | `DefaultExample.tsx` | Минимальное использование с `size={16}` между двумя блоками |
+| `Sizes` | `SizesExample.tsx` | Все 8 значений `TGapSize`: 4, 8, 12, 16, 24, 32, 64, 128 px |
 
 ---
 
@@ -110,4 +90,82 @@ src/components/Gap/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-05-20 | Создан документ. AI-рефакторинг: inline-`style` высоты заменён на CSS-классы из `Gap.module.less`, добавлены JSDoc на `Gap`, `TGapSize`, `IGapProps.size`, расширены unit-тесты (forwardRef, все значения `size`, `role="presentation"`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Gap/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { Gap } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <div>
+        <div
+            style={{
+                padding: "16px",
+                textAlign: "center",
+                backgroundColor: "rgb(255, 217, 160)",
+            }}
+        >
+            Sample Text Above
+        </div>
+
+        <Gap size={16} />
+
+        <div
+            style={{
+                padding: "16px",
+                textAlign: "center",
+                backgroundColor: "rgb(255, 217, 160)",
+            }}
+        >
+            Sample Text Below
+        </div>
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Gap/examples/SizesExample.tsx`
+
+```tsx
+import React from "react";
+import { Gap, TGapSize } from "@sberbusiness/triplex-next";
+
+const SIZES: TGapSize[] = [4, 8, 12, 16, 24, 32, 64, 128];
+
+const blockStyle: React.CSSProperties = {
+    padding: "16px",
+    textAlign: "center",
+    backgroundColor: "rgb(255, 217, 160)",
+};
+
+interface ISizeItemProps {
+    size: TGapSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => (
+    <div>
+        <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size}px</div>
+        <div style={blockStyle}>Above</div>
+        <Gap size={size} />
+        <div style={blockStyle}>Below</div>
+    </div>
+);
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px", maxWidth: "300px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+