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

package/bundle/components/Caption.md

@@ -0,0 +1,291 @@
+---
+component: Caption
+category: Typography
+related: [Text, Title, CodeText]
+tokens:
+  - --triplex-next-Typography-Primary_Color
+  - --triplex-next-Typography-PrimaryInvert_Color
+  - --triplex-next-Typography-Complementary_Color
+  - --triplex-next-Typography-ComplementaryInvert_Color
+  - --triplex-next-Typography-Secondary_Color
+  - --triplex-next-Typography-SecondaryInvert_Color
+  - --triplex-next-Typography-Tertiary_Color
+  - --triplex-next-Typography-TertiaryInvert_Color
+  - --triplex-next-Typography-Disabled_Color
+  - --triplex-next-Typography-DisabledInvert_Color
+  - --triplex-next-Typography-Brand_Color
+  - --triplex-next-Typography-BrandInvert_Color
+  - --triplex-next-Typography-Info_Color
+  - --triplex-next-Typography-InfoInvert_Color
+  - --triplex-next-Typography-Success_Color
+  - --triplex-next-Typography-SuccessInvert_Color
+  - --triplex-next-Typography-Warning_Color
+  - --triplex-next-Typography-WarningInvert_Color
+  - --triplex-next-Typography-Error_Color
+  - --triplex-next-Typography-ErrorInvert_Color
+  - --triplex-next-Typography-System_Color
+  - --triplex-next-Typography-SystemInvert_Color
+stories: stories/Typography/Caption.stories.tsx
+version: "1.0"
+---
+
+# Caption
+
+## Назначение
+
+Подпись (типографика). Рендерит инлайновый `<span>` (тег настраивается через `tag`) для крайних значений типографической шкалы: очень мелкие подписи `C1` (10px) и `C2` (8px) либо крупный акцентный показатель `D1` (32px, шрифт SBSansDisplay).
+
+Используй когда: нужна сверхмелкая техническая подпись (сноска, копирайт, метка) или крупная цифра/показатель, не являющаяся заголовком (сумма на дашборде, KPI).
+
+Не используй когда:
+- Нужен обычный текст 12–18px — используй `Text` (B1–B4).
+- Крупный текст является заголовком секции — используй `Title` (семантические `h1`–`h3`).
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `ECaptionSize` | Размер: `C1` (10/12px), `C2` (8/10px), `D1` (32/40px). В скобках — font-size/line-height. |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `weight` | `EFontWeightCaption` | `REGULAR` | Начертание: `REGULAR` или `SEMIBOLD` (600). Для `C1`/`C2` — семейство SBSansText*, для `D1` — SBSansDisplay*. |
+| `type` | `EFontType` | `PRIMARY` | Цвет текста из общей палитры типографики (11 базовых + 11 `*_INVERT`). |
+| `underline` | `boolean` | — | Подчёркивание. Совместим со `strikethrough` (оба сразу — `underline line-through`). |
+| `strikethrough` | `boolean` | — | Зачёркивание. |
+| `tag` | `string` | `"span"` | HTML-тег корневого элемента. |
+
+Компонент типизирован как `TCaptionProps<T extends keyof JSX.IntrinsicElements>` и принимает все атрибуты соответствующего HTML-элемента через spread.
+
+### Ограничения
+
+- Внешний тип `forwardRef<HTMLElement, TCaptionProps<keyof JSX.IntrinsicElements>>` «растворяет» дженерик: TypeScript не сужает атрибуты под конкретный `tag`. Известное ограничение публичного API, не исправлять без обсуждения (breaking).
+- `EFontWeightCaption` дублирует значения `EFontWeightText` — это два независимых публичных enum, объединять нельзя (breaking).
+- `EFontType.BRAND` дополнительно задаёт `user-select: none` (особенность стилей `Typography.module.less`).
+
+---
+
+## Дизайн-токены
+
+Цвета — общие CSS-переменные семейства Typography (см. frontmatter): `--triplex-next-Typography-{Type}_Color` и `--triplex-next-Typography-{Type}Invert_Color`.
+
+Размеры шрифта и line-height — фиксированные пиксельные значения в `styles/Caption.module.less` (токенов для них нет).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, `ref` пробрасывается на корневой элемент.
+- **Значения enum** `ECaptionSize`, `EFontWeightCaption`, `EFontType` — публичный API из barrel. Изменение — breaking change.
+- **`TCaptionProps`**, **`ITypographyProps`** — публичные типы.
+- **`displayName = "Caption"`** — не убирать.
+- `D1` переключает семейство шрифта на SBSansDisplay* — контракт стилей: крупный показатель визуально согласован с заголовками.
+- Классы собираются только через `clsx`.
+
+---
+
+## Accessibility
+
+- Компонент не интерактивный: focus management и keyboard navigation не применимы.
+- Семантика определяется через `tag` (по умолчанию нейтральный `<span>`).
+- Размеры `C1`/`C2` (10/8px) ниже комфортного порога читаемости — используй только для второстепенной информации, не для основного контента.
+- Цвет (`type`) не передаёт семантику для screen reader'ов.
+
+---
+
+## Связанные компоненты
+
+- `Text` — основной текст интерфейса (B1–B4).
+- `Title` — заголовки `h1`–`h3`.
+- `CodeText` — моноширинный текст.
+
+---
+
+## Stories
+
+Основные истории: `stories/Typography/Caption.stories.tsx`
+Файлы примеров: `stories/Typography/examples/Caption/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль props `size`, `weight`, `type`, `tag`, `underline`, `strikethrough` |
+| `Default` | `Default.tsx` | Минимальное использование |
+| `Sizes` | `Sizes.tsx` | Размеры C1 / C2 / D1 |
+| `Weights` | `Weights.tsx` | Начертания REGULAR / SEMIBOLD |
+| `Types` | `Types.tsx` | Все значения `EFontType`: базовые + инвертированные на тёмной подложке |
+| `Decorations` | `Decorations.tsx` | `underline`, `strikethrough` и их комбинация |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-07-20 | Создан документ. AI-рефакторинг: decoration-логика вынесена во внутренний хелпер `getTextDecorationClassName` (`utils.ts`), комментарии переведены в JSDoc, unit-тесты расширены (все значения `ECaptionSize`/`EFontWeightCaption`, дефолты). Stories переведены на modern pattern (`examples/Caption/`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Typography/examples/Caption/Default.tsx`
+
+```tsx
+import React from "react";
+import { Caption, ECaptionSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => <Caption size={ECaptionSize.C1}>Вспомогательная подпись</Caption>;
+```
+
+### Sizes
+
+`stories/Typography/examples/Caption/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Caption, ECaptionSize } from "@sberbusiness/triplex-next";
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Caption size={ECaptionSize.C1}>C1 - Подпись малого размера (10px)</Caption>
+        <Caption size={ECaptionSize.C2}>C2 - Подпись очень малого размера (8px)</Caption>
+        <Caption size={ECaptionSize.D1}>D1 - Подпись большого размера (32px)</Caption>
+    </div>
+);
+```
+
+### Weights
+
+`stories/Typography/examples/Caption/Weights.tsx`
+
+```tsx
+import React from "react";
+import { Caption, ECaptionSize, EFontWeightCaption } from "@sberbusiness/triplex-next";
+
+export const Weights = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Caption size={ECaptionSize.C1} weight={EFontWeightCaption.REGULAR}>
+            Regular - Обычный вес подписи
+        </Caption>
+        <Caption size={ECaptionSize.C1} weight={EFontWeightCaption.SEMIBOLD}>
+            Semibold - Полужирная подпись
+        </Caption>
+    </div>
+);
+```
+
+### Types
+
+`stories/Typography/examples/Caption/Types.tsx`
+
+```tsx
+import React from "react";
+import { Caption, ECaptionSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Types = () => (
+    <div style={{ display: "flex", gap: "16px" }}>
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+            <Caption size={ECaptionSize.C1} type={EFontType.PRIMARY}>
+                Primary
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.COMPLEMENTARY}>
+                Complementary
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SECONDARY}>
+                Secondary
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.TERTIARY}>
+                Tertiary
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.BRAND}>
+                Brand
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.INFO}>
+                Info
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SUCCESS}>
+                Success
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.WARNING}>
+                Warning
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.ERROR}>
+                Error
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.DISABLED}>
+                Disabled
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SYSTEM}>
+                System
+            </Caption>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", backgroundColor: "#1F1F22" }}>
+            <Caption size={ECaptionSize.C1} type={EFontType.PRIMARY_INVERT}>
+                Primary Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.COMPLEMENTARY_INVERT}>
+                Complementary Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SECONDARY_INVERT}>
+                Secondary Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.TERTIARY_INVERT}>
+                Tertiary Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.BRAND_INVERT}>
+                Brand Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.INFO_INVERT}>
+                Info Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SUCCESS_INVERT}>
+                Success Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.WARNING_INVERT}>
+                Warning Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.ERROR_INVERT}>
+                Error Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.DISABLED_INVERT}>
+                Disabled Invert
+            </Caption>
+            <Caption size={ECaptionSize.C1} type={EFontType.SYSTEM_INVERT}>
+                System Invert
+            </Caption>
+        </div>
+    </div>
+);
+```
+
+### Decorations
+
+`stories/Typography/examples/Caption/Decorations.tsx`
+
+```tsx
+import React from "react";
+import { Caption, ECaptionSize } from "@sberbusiness/triplex-next";
+
+export const Decorations = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Caption size={ECaptionSize.C1}>Подпись без декораций</Caption>
+        <Caption size={ECaptionSize.C1} underline>
+            Подпись с подчеркиванием
+        </Caption>
+        <Caption size={ECaptionSize.C1} strikethrough>
+            Подпись с зачеркиванием
+        </Caption>
+        <Caption size={ECaptionSize.C1} underline strikethrough>
+            Подпись с подчеркиванием и зачеркиванием
+        </Caption>
+    </div>
+);
+```
+

package/bundle/components/Checkbox.md

@@ -1,8 +1,6 @@
 ---
 component: Checkbox
 category: Inputs
-figma-node: ""
-figma-file: ""
 related: [CheckboxXGroup, CheckboxYGroup, CheckboxTree, CheckboxTreeExtended]
 tokens:
   - --triplex-next-Checkbox-Background_Default
@@ -26,7 +24,8 @@ version: "1.0"
 # Checkbox
 
 ## Назначение
-Нативный чекбокс в обертке `<label>`, который поддерживает визуальные состояния (default/checked/disabled/focus) и режим частичного выбора через `bulk`.
+
+Нативный чекбокс в обёртке `<label>`, который поддерживает визуальные состояния (default / checked / disabled / focus) и режим частичного выбора через `bulk`.
 
 Используй когда: нужен чекбокс с текстовой подписью (`children`) и стандартным поведением `<input type="checkbox">`.
 Не используй когда: нужен сложный многошаговый выбор или компонент с нестандартной семантикой (тогда лучше другой control).
@@ -34,95 +33,95 @@ version: "1.0"
 ---
 
 ## Варианты и props
+
+### Обязательные props
+
+Обязательных custom-props нет.
+
 ### Опциональные props
+
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
 | `checked` | `boolean` | — | Состояние чекбокса (controlled). Передаётся через стандартные props `<input>`. |
 | `defaultChecked` | `boolean` | — | Состояние чекбокса (uncontrolled). Передаётся через стандартные props `<input>`. |
 | `disabled` | `boolean` | `false` | Блокирует взаимодействие и меняет визуальное состояние. |
-| `bulk` | `boolean` | `false` | Влияет на отображаемую иконку (используется bulk-иконка), при этом видимость checkmark всё равно определяется состоянием `checked`. |
+| `bulk` | `boolean` | `false` | Влияет на отображаемую иконку (используется bulk-иконка). Видимость checkmark всё равно определяется состоянием `checked`. |
 | `size` | `EComponentSize` | `EComponentSize.MD` | Размер: `SM` / `MD` / `LG`. |
 | `children` | `React.ReactNode` | — | Контент лейбла рядом с чекбоксом. Если `children` нет — класс `.nonempty` не применяется. |
 | `labelAttributes` | `React.LabelHTMLAttributes<HTMLLabelElement>` | — | Дополнительные HTML-атрибуты для корневого `<label>` (например, `className`, `onFocus`). |
-| `...inputAttributes` | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size">` | — | Все стандартные атрибуты `<input type="checkbox">` (включая `name`, `onChange`, `aria-label` и т.д.). |
+| `...inputAttributes` | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" \| "size">` | — | Все стандартные атрибуты `<input type="checkbox">` (включая `name`, `onChange`, `aria-label` и т.д.). |
 
----
-
-## Ключевые особенности реализации
-### Ref forwarding
-`ref` прокидывается на внутренний `<input type="checkbox">`.
-
-### Иконка
-- `bulk=false` — отрисовывается обычная checkmark-иконка.
-- `bulk=true` — отрисовывается bulk-иконка.
+### Ограничения использования
 
-### Структура DOM
-Компонент рендерит:
-1. корневой `<label>`
-2. `<input type="checkbox">`
-3. декоративные `<span>`/`svg` для отрисовки фона и галочки
+- DOM-структура фиксирована: корневой `<label>` → `<input type="checkbox">` → декоративные `<span>` / `<svg>` для отрисовки фона и галочки.
+- `ref` прокидывается на внутренний `<input type="checkbox">`.
 
 ---
 
-## Accessibility
-Компонент использует нативный `<input type="checkbox">`, поэтому поддерживает стандартную клавиатурную навигацию (Tab + Space) и семантику формы.
+## Дизайн-токены
 
-Библиотека мультиязычная: текст `aria-label`/`title` не захардкожен в компоненте. При необходимости потребитель передаёт `aria-*` через `...inputAttributes`.
+```
+--triplex-next-Checkbox-Background_Default
+--triplex-next-Checkbox-BorderColor_Default
+--triplex-next-Checkbox-Checkmark_Fill_Default
+--triplex-next-Checkbox-Background_Hover
+--triplex-next-Checkbox-BorderColor_Hover
+--triplex-next-Checkbox-Background_Checked_Default
+--triplex-next-Checkbox-BorderColor_Checked_Default
+--triplex-next-Checkbox-Background_Disabled
+--triplex-next-Checkbox-BorderColor_Disabled
+--triplex-next-Checkbox-Background_Checked_Disabled
+--triplex-next-Checkbox-BorderColor_Checked_Disabled
+--triplex-next-Checkbox-Checkmark_Fill_Disabled
+--triplex-next-Checkbox-BorderColor_Focus
+--triplex-next-Checkbox-Background_Checked_Hover
+```
 
 ---
 
 ## Инварианты
+
 - `forwardRef` на компоненте обязателен и должен указывать на `<input>`.
 - Корневой DOM-элемент компонента — `<label>`, внутри которого находится `<input>`.
 - `className` и `size` — публичные части внешнего контрактного API: не менять семантику без согласования.
 
 ---
 
-## Дизайн-токены
-Компонент использует CSS-переменные:
-`--triplex-next-Checkbox-Background_Default`,
-`--triplex-next-Checkbox-BorderColor_Default`,
-`--triplex-next-Checkbox-Checkmark_Fill_Default`,
-`--triplex-next-Checkbox-Background_Hover`,
-`--triplex-next-Checkbox-BorderColor_Hover`,
-`--triplex-next-Checkbox-Background_Checked_Default`,
-`--triplex-next-Checkbox-BorderColor_Checked_Default`,
-`--triplex-next-Checkbox-Background_Disabled`,
-`--triplex-next-Checkbox-BorderColor_Disabled`,
-`--triplex-next-Checkbox-Background_Checked_Disabled`,
-`--triplex-next-Checkbox-BorderColor_Checked_Disabled`,
-`--triplex-next-Checkbox-Checkmark_Fill_Disabled`,
-`--triplex-next-Checkbox-BorderColor_Focus`,
-`--triplex-next-Checkbox-Background_Checked_Hover`.
+## Accessibility
+
+- Компонент использует нативный `<input type="checkbox">`, поэтому поддерживает стандартную клавиатурную навигацию (Tab + Space) и семантику формы.
+- Библиотека мультиязычная: текст `aria-label` / `title` не захардкожен в компоненте. При необходимости потребитель передаёт `aria-*` через `...inputAttributes`.
 
 ---
 
 ## Связанные компоненты
+
 - `CheckboxXGroup` — группировка чекбоксов по оси X.
 - `CheckboxYGroup` — группировка чекбоксов по оси Y.
-- `CheckboxTree` — декларативное дерево чекбоксов (обертка над `CheckboxTreeExtended`), поддерживает bulk-логику и распространение состояния checked по родителям/детям.
-- `CheckboxTreeExtended` — расширенное дерево чекбоксов на базе `CollapsableTree` с Node/Checkbox подкомпонентами (использует нативный `Checkbox` внутри для каждого узла).
+- `CheckboxTree` — декларативное дерево чекбоксов (обёртка над `CheckboxTreeExtended`), поддерживает bulk-логику и распространение состояния checked по родителям/детям.
+- `CheckboxTreeExtended` — расширенное дерево чекбоксов на базе `CollapsibleTreeExtended` с `Node` / `Checkbox` подкомпонентами (использует нативный `Checkbox` внутри для каждого узла).
 
 ---
 
 ## Stories
-`stories/Checkbox/Checkbox.stories.tsx`
+
+Основные истории: `stories/Checkbox/Checkbox.stories.tsx`
 Файлы примеров: `stories/Checkbox/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
 | `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль основных props |
 | `Default` | `DefaultExample.tsx` | Минимальное использование |
-| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
-| `XGroup` | `XGroupExample.tsx` | Группа по оси X |
-| `YGroup` | `YGroupExample.tsx` | Группа по оси Y |
+| `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` / `LG` |
 
 ---
 
 ## История изменений
+
 | Дата | Изменение |
 |---|---|
 | 2026-04-16 | Приведение `Checkbox` к AI-ready: соблюдены правила `docs/ai/codestyle.md`, добавлена AI-документация и unit-тест на передачу `className` корневому `label`. |
+| 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: убрана секция «Ключевые особенности реализации» (содержимое перенесено в `Ограничения использования`), переставлены секции (Accessibility после Инвариантов), добавлена колонка `Example file`. |
 
 ---
 
@@ -158,81 +157,3 @@ export const SizesExample = () => (
 );
 ```
 
-### XGroup
-
-`stories/Checkbox/examples/XGroupExample.tsx`
-
-```tsx
-import React from "react";
-import { Checkbox, CheckboxXGroup, EComponentSize, Gap } from "@sberbusiness/triplex-next";
-
-export const XGroupExample = () => (
-    <>
-        <CheckboxXGroup indent={16}>
-            {[1, 2, 3].map((value) => (
-                <Checkbox key={value} name="checkbox-x-group" value={value} size={EComponentSize.SM}>
-                    Checkbox text
-                </Checkbox>
-            ))}
-        </CheckboxXGroup>
-        <Gap size={16} />
-        <CheckboxXGroup indent={16}>
-            {[1, 2, 3].map((value) => (
-                <Checkbox key={value} name="checkbox-x-group" value={value}>
-                    Checkbox text
-                </Checkbox>
-            ))}
-        </CheckboxXGroup>
-        <Gap size={16} />
-        <CheckboxXGroup indent={20}>
-            {[1, 2, 3].map((value) => (
-                <Checkbox key={value} name="checkbox-x-group" value={value} size={EComponentSize.LG}>
-                    Checkbox text
-                </Checkbox>
-            ))}
-        </CheckboxXGroup>
-    </>
-);
-```
-
-### YGroup
-
-`stories/Checkbox/examples/YGroupExample.tsx`
-
-```tsx
-import React from "react";
-import { Checkbox, CheckboxYGroup, Col, EComponentSize, Row } from "@sberbusiness/triplex-next";
-
-export const YGroupExample = () => (
-    <Row>
-        <Col size={3}>
-            <CheckboxYGroup aria-labelledby="checkbox-y-group-label">
-                {[1, 2, 3, 4].map((value) => (
-                    <Checkbox key={value} name="checkbox-y-group" value={value} size={EComponentSize.SM}>
-                        Checkbox text
-                    </Checkbox>
-                ))}
-            </CheckboxYGroup>
-        </Col>
-        <Col size={3}>
-            <CheckboxYGroup aria-labelledby="checkbox-y-group-label">
-                {[1, 2, 3, 4].map((value) => (
-                    <Checkbox key={value} name="checkbox-y-group" value={value}>
-                        Checkbox text
-                    </Checkbox>
-                ))}
-            </CheckboxYGroup>
-        </Col>
-        <Col size={3}>
-            <CheckboxYGroup aria-labelledby="checkbox-y-group-label">
-                {[1, 2, 3, 4].map((value) => (
-                    <Checkbox key={value} name="checkbox-y-group" value={value} size={EComponentSize.LG}>
-                        Checkbox text
-                    </Checkbox>
-                ))}
-            </CheckboxYGroup>
-        </Col>
-    </Row>
-);
-```
-