@sberbusiness/triplex-next-mcp-server 0.36.0-beta0 → 1.41.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>
+);
+```
+