@sberbusiness/triplex-next-mcp-server 0.36.0-beta0 → 1.41.0-beta

package/bundle/components/Title.md

@@ -0,0 +1,296 @@
+---
+component: Title
+category: Typography
+related: [Text, Caption, 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/Title.stories.tsx
+version: "1.0"
+---
+
+# Title
+
+## Назначение
+
+Заголовок (типографика). Рендерит семантический heading `<h1>`–`<h3>` (тег по умолчанию совпадает со значением `size`) со шрифтом SBSansDisplay и цветом из палитры `EFontType`. `margin` у заголовков обнулён — отступы задаёт layout потребителя.
+
+Используй когда: нужен заголовок страницы, секции, карточки или модального окна.
+
+Не используй когда:
+- Нужен обычный текст интерфейса — используй `Text`.
+- Нужна крупная цифра/показатель (32px), не являющаяся заголовком — используй `Caption` с размером `D1`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `size` | `ETitleSize` | Размер заголовка: `H1` (28/36px), `H2` (24/32px), `H3` (20/28px). В скобках — font-size/line-height. Значения enum — строки `"h1"`/`"h2"`/`"h3"`. |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `weight` | `EFontWeightTitle` | `SEMIBOLD` | Начертание: `REGULAR` / `MEDIUM` (500) / `SEMIBOLD` (600) / `BOLD` (700). Каждому соответствует своё семейство SBSansDisplay*. |
+| `type` | `EFontType` | `PRIMARY` | Цвет текста из общей палитры типографики (11 базовых + 11 `*_INVERT`). |
+| `underline` | `boolean` | — | Подчёркивание. Совместим со `strikethrough` (оба сразу — `underline line-through`). |
+| `strikethrough` | `boolean` | — | Зачёркивание. |
+| `tag` | `string` | значение `size` | HTML-тег корневого элемента. По умолчанию равен значению `size` (`"h1"`/`"h2"`/`"h3"`) — визуальный размер и уровень heading связаны. Передай `tag` явно, чтобы развязать их (например, `size={ETitleSize.H1} tag="h2"`). |
+
+Компонент типизирован как `TTitleProps<T extends keyof JSX.IntrinsicElements>` и принимает все атрибуты соответствующего HTML-элемента через spread.
+
+### Ограничения
+
+- Внешний тип `forwardRef<HTMLElement, TTitleProps<keyof JSX.IntrinsicElements>>` «растворяет» дженерик: TypeScript не сужает атрибуты под конкретный `tag`. Известное ограничение публичного API, не исправлять без обсуждения (breaking).
+- Дефолт `` tag = `${size}` `` — намеренный трюк (значения `ETitleSize` совпадают с именами тегов); при изменении значений enum сломается и дефолтный тег — ещё одна причина не трогать значения.
+- `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/Title.module.less` (токенов для них нет).
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен, `ref` пробрасывается на корневой heading-элемент.
+- **Значения enum** `ETitleSize` (строки `"h1"`/`"h2"`/`"h3"`), `EFontWeightTitle`, `EFontType` — публичный API из barrel. Изменение — breaking change; значения `ETitleSize` дополнительно используются как дефолтный `tag`.
+- **`TTitleProps`**, **`ITypographyProps`** — публичные типы.
+- **`displayName = "Title"`** — не убирать.
+- `margin: 0` на `h1`–`h3` в `Title.module.less` — контракт: отступы вокруг заголовка задаёт потребитель.
+- Классы собираются только через `clsx`.
+
+---
+
+## Accessibility
+
+- По умолчанию рендерится настоящий heading (`<h1>`–`<h3>`) — уровень в accessibility-дереве определяется `size`. Следи за иерархией заголовков страницы; если визуальный размер не совпадает с нужным уровнем — задай `tag` явно.
+- Компонент не интерактивный: focus management и keyboard navigation не применимы.
+- Цвет (`type`) не передаёт семантику для screen reader'ов.
+
+---
+
+## Связанные компоненты
+
+- `Text` — основной текст интерфейса (B1–B4, SBSansText).
+- `Caption` — мелкие подписи и крупный показатель D1.
+- `CodeText` — моноширинный текст.
+
+---
+
+## Stories
+
+Основные истории: `stories/Typography/Title.stories.tsx`
+Файлы примеров: `stories/Typography/examples/Title/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль props `size`, `weight`, `type`, `tag`, `underline`, `strikethrough` |
+| `Default` | `Default.tsx` | Минимальное использование |
+| `Sizes` | `Sizes.tsx` | Размеры H1 / H2 / H3 |
+| `Weights` | `Weights.tsx` | Начертания REGULAR / MEDIUM / SEMIBOLD / BOLD |
+| `Types` | `Types.tsx` | Все значения `EFontType`: базовые + инвертированные на тёмной подложке |
+| `Decorations` | `Decorations.tsx` | `underline`, `strikethrough` и их комбинация |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-07-20 | Создан документ. AI-рефакторинг: decoration-логика вынесена во внутренний хелпер `getTextDecorationClassName` (`utils.ts`), комментарии переведены в JSDoc, unit-тесты расширены (все значения `ETitleSize`/`EFontWeightTitle`, дефолтные heading-теги). Stories переведены на modern pattern (`examples/Title/`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Typography/examples/Title/Default.tsx`
+
+```tsx
+import React from "react";
+import { Title, ETitleSize } from "@sberbusiness/triplex-next";
+
+export const Default = () => <Title size={ETitleSize.H1}>Заголовок страницы</Title>;
+```
+
+### Sizes
+
+`stories/Typography/examples/Title/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Title, ETitleSize } from "@sberbusiness/triplex-next";
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Title size={ETitleSize.H1}>Заголовок H1</Title>
+        <Title size={ETitleSize.H2}>Заголовок H2</Title>
+        <Title size={ETitleSize.H3}>Заголовок H3</Title>
+    </div>
+);
+```
+
+### Weights
+
+`stories/Typography/examples/Title/Weights.tsx`
+
+```tsx
+import React from "react";
+import { Title, ETitleSize, EFontWeightTitle } from "@sberbusiness/triplex-next";
+
+export const Weights = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Title size={ETitleSize.H2} weight={EFontWeightTitle.REGULAR}>
+            Regular - Обычный вес
+        </Title>
+        <Title size={ETitleSize.H2} weight={EFontWeightTitle.MEDIUM}>
+            Medium - Средний вес
+        </Title>
+        <Title size={ETitleSize.H2} weight={EFontWeightTitle.SEMIBOLD}>
+            Semibold - Полужирный
+        </Title>
+        <Title size={ETitleSize.H2} weight={EFontWeightTitle.BOLD}>
+            Bold - Жирный
+        </Title>
+    </div>
+);
+```
+
+### Types
+
+`stories/Typography/examples/Title/Types.tsx`
+
+```tsx
+import React from "react";
+import { Title, ETitleSize, EFontType } from "@sberbusiness/triplex-next";
+
+export const Types = () => (
+    <div style={{ display: "flex", gap: "16px" }}>
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+            <Title size={ETitleSize.H2} type={EFontType.PRIMARY}>
+                Primary
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.COMPLEMENTARY}>
+                Complementary
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SECONDARY}>
+                Secondary
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.TERTIARY}>
+                Tertiary
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.BRAND}>
+                Brand
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.INFO}>
+                Info
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SUCCESS}>
+                Success
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.WARNING}>
+                Warning
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.ERROR}>
+                Error
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.DISABLED}>
+                Disabled
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SYSTEM}>
+                System
+            </Title>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: "16px", backgroundColor: "#1F1F22" }}>
+            <Title size={ETitleSize.H2} type={EFontType.PRIMARY_INVERT}>
+                Primary Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.COMPLEMENTARY_INVERT}>
+                Complementary Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SECONDARY_INVERT}>
+                Secondary Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.TERTIARY_INVERT}>
+                Tertiary Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.BRAND_INVERT}>
+                Brand Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.INFO_INVERT}>
+                Info Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SUCCESS_INVERT}>
+                Success Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.WARNING_INVERT}>
+                Warning Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.ERROR_INVERT}>
+                Error Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.DISABLED_INVERT}>
+                Disabled Invert
+            </Title>
+            <Title size={ETitleSize.H2} type={EFontType.SYSTEM_INVERT}>
+                System Invert
+            </Title>
+        </div>
+    </div>
+);
+```
+
+### Decorations
+
+`stories/Typography/examples/Title/Decorations.tsx`
+
+```tsx
+import React from "react";
+import { Title, ETitleSize } from "@sberbusiness/triplex-next";
+
+export const Decorations = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Title size={ETitleSize.H2}>Заголовок без декораций</Title>
+        <Title size={ETitleSize.H2} underline>
+            Заголовок с подчеркиванием
+        </Title>
+        <Title size={ETitleSize.H2} strikethrough>
+            Заголовок с зачеркиванием
+        </Title>
+        <Title size={ETitleSize.H2} underline strikethrough>
+            Заголовок с подчеркиванием и зачеркиванием
+        </Title>
+    </div>
+);
+```
+