@sberbusiness/triplex-next-mcp-server 1.48.0-beta → 1.50.0-beta

package/bundle/components/Divider.md

@@ -1,10 +1,9 @@
 ---
 component: Divider
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Gap, Row, Col]
-tokens: [Divider_Background]
+related: []
+tokens:
+  - Divider.Background
 stories: stories/Divider/Divider.stories.tsx
 version: "1.0"
 ---
@@ -13,179 +12,91 @@ version: "1.0"
 
 ## Назначение
 
-Горизонтальная линия-разделитель (`<hr>`) высотой 1px с токенизированным
-фоном (`--triplex-next-Divider-Background`) и опциональными top/bottom
-отступами из фиксированной шкалы 4/8/12/16/20/24/28/32 px.
+Визуальный разделитель контента: горизонтальная линия толщиной 1px на всю ширину родителя. Рендерит `<hr>` с собственным цветом из дизайн-токена и опциональными вертикальными отступами из шкалы дизайн-системы.
 
-Используется для визуального разделения секций внутри Card, Island,
-формы и т. п.
+Используй когда: нужно отделить друг от друга смысловые блоки контента видимой линией — пункты списка, секции формы, строки в футере таблицы.
 
-Используй когда: нужна тонкая разделительная линия между блоками.
-Не используй когда: нужен вертикальный разделитель (`Divider` только
-горизонтальный); нужны только отступы без линии — бери `Gap`.
-
----
-
-## Файловая структура
-
-```text
-src/components/Divider/
-├── Divider.tsx                         # FC, НЕ forwardRef
-├── index.ts                            # Barrel
-├── styles/Divider.module.less          # background + each-loop для margin-top/bottom
-└── __tests__/Divider.test.tsx
-```
-
-Особенности:
-- **НЕ `forwardRef`** — FC без ref-форвардинга. Известный debt. Не
-  добавлять точечно.
-- **Рендерит семантичный `<hr>`** (не `<div>`). Это важно для a11y —
-  screen reader'ы объявят как разделитель.
-- **Нет `data-tx`** — не ставит атрибут версии.
-- **Тесты есть** — `Divider.test.tsx` проверяет классы по размерам.
+Не используй когда:
+- Нужен только отступ без линии — используй `Gap`.
+- Нужна вертикальная линия-разделитель: компонент рендерит только горизонтальную линию, вертикальной темы у него нет.
+- Нужна линия как часть границы блока — задай `border` у самого блока, не вставляй `Divider` рядом.
 
 ---
 
 ## Варианты и props
 
-### `IDividerProps extends React.HTMLAttributes<HTMLHRElement>`
-
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `marginTopSize` | `TDividerMarginSize` (4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 28 \| 32) | — | Отступ сверху в px. Если не задан — 0. |
-| `marginBottomSize` | `TDividerMarginSize` | — | Отступ снизу в px. Если не задан — 0. |
-| `className` | `string` | — | Через `clsx`. |
-| `...HTMLHRAttributes` | — | — | Стандартные атрибуты `<hr>`. |
+### Обязательные props
 
-### `TDividerMarginSize = 4 | 8 | 12 | 16 | 20 | 24 | 28 | 32`
+Обязательных props нет — `<Divider />` без props рендерит линию без отступов.
 
-Литерально-числовой union. **Не `number`** — типизация закрывает
-кастомные значения. Если нужно 0 — не передавать пропс. Если нужно 40 —
-не поддерживается, разделитель не ставится туда, где нужен нестандартный
-gap.
+### Опциональные props
 
----
-
-## Ключевые особенности реализации
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `marginTopSize` | `TDividerMarginSize` | — | Отступ сверху в пикселях. Без prop'а `margin-top` остаётся `0`. |
+| `marginBottomSize` | `TDividerMarginSize` | — | Отступ снизу в пикселях. Без prop'а `margin-bottom` остаётся `0`. |
 
-### CSS-классы по размеру через LESS `each` + shape
+Компонент расширяет `Omit<React.HTMLAttributes<HTMLHRElement>, "children">`, поэтому принимает все стандартные атрибуты `<hr>` (`className`, `style`, `aria-*`, `data-*`), кроме `children`; `...rest` и `ref` уходят на корневой `<hr>`.
 
-```less
-@size: 4, 8, 12, 16, 20, 24, 28, 32;
-each(@size, {
-    .marginTopSize-@{value} { margin-top: ~'@{value}px'; }
-    .marginBottomSize-@{value} { margin-bottom: ~'@{value}px'; }
-});
-```
+### Ограничения
 
-**LESS `each`** + **escape-строка** `~'@{value}px'` генерирует по два
-класса на каждый размер (16 классов всего). Если нужен новый размер —
-добавить в `@size` список и в `TDividerMarginSize` TS-литерал.
-**TS-литерал — единственная связь между LESS и TS**: TS проверяет
-что пропс в списке, LESS обеспечивает наличие класса. Если
-рассинхронизировать — получишь `styles[undefined]`.
-
-### Сборка `className` через `clsx`
-
-```ts
-const classNames = clsx(
-    styles.divider,
-    marginTopSize && styles[`marginTopSize-${marginTopSize}`],
-    marginBottomSize && styles[`marginBottomSize-${marginBottomSize}`],
-    className,
-);
-```
+- `TDividerMarginSize` — дискретная шкала `4 | 8 | 12 | 16 | 20 | 24 | 28 | 32`. Произвольное число тип не пропустит: если дизайн требует другой отступ, задай его у родительского блока, а не расширяй шкалу.
+- Отступы задаются только по вертикали. Горизонтальные отступы и ширину линии определяет родитель.
+- Базовый класс сбрасывает браузерный `margin` у `<hr>` в `0`, поэтому вертикальный отступ появляется **только** через `marginTopSize` / `marginBottomSize` (или через собственный `className` потребителя).
+- `<hr>` — void-элемент, поэтому `children` исключён из `IDividerProps` на уровне типа (как у `Gap`): `<Divider>…</Divider>` не соберётся. Оборачивать контент в `Divider` нельзя.
 
-**Дефолт `styles.divider`** задаёт фон + height 1px + `margin: 0` +
-`border: none`. Без `border: none` браузерный `<hr>` имеет свою
-border/margin.
+---
 
-**Если `marginTopSize` undefined/0 — класс не добавляется** (короткое
-замыкание `&&`). 0 не поддерживается, но undefined — да.
+## Дизайн-токены
 
-### Токен `--triplex-next-Divider-Background`
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Divider.ts`.
 
-```less
-.divider {
-    height: 1px;
-    margin: 0;
-    background: var(--triplex-next-Divider-Background);
-    border: none;
-}
+```text
+Divider.Background
 ```
 
-Цвет разделителя задаётся одним токеном (см. компонент Divider в
-`DesignTokens/components/Divider.ts`). В тёмной теме меняется
-автоматически через ThemeProvider.
-
-### Override через `style` / `className`
-
-Потребитель может:
-1. Передать `className` — мержится через clsx.
-2. Передать `style={{margin: ...}}` — перебьёт встроенные margin-классы.
-3. Переопределить `--triplex-next-Divider-Background` в scope.
-
-### `hr` — не `div`
-
-Семантичность: screen reader'ы читают `<hr>` как разделитель
-(`role="separator"` по умолчанию).
+Токен задаёт цвет линии (`background` у элемента высотой 1px, `border` снят). Значения по умолчанию: `ColorNeutral.20` в светлой теме, `ColorDarkNeutral.80` в тёмной.
 
 ---
 
 ## Инварианты
 
-- **Рендерит `<hr>`**, не `<div>`. Не менять — пострадает семантика.
-- **`TDividerMarginSize` фиксирован 4/8/12/16/20/24/28/32** — не
-  расширять без выравнивания с дизайн-системой и LESS-списком.
-- **LESS `@size` и TS-литерал должны совпадать** — иначе классы
-  не сгенерируются для нового размера.
-- **`border: none; margin: 0;`** в base-классе — без них браузерный
-  `<hr>` ломает дизайн.
-- **`--triplex-next-Divider-Background` токен** — единственный способ
-  поменять цвет. Не хардкодить hex.
-- **НЕТ forwardRef** — известный debt.
-- **НЕТ `data-tx`** — наследованный пропуск.
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой `<hr>`.
+- **Корневой элемент — `<hr>`.** Замена на `<div>` сломала бы неявную роль `separator` и запросы `getByRole("separator")` в тестах потребителей.
+- **`TDividerMarginSize`** — публичный union type, экспортируется из barrel. Изменение перечня значений — breaking change.
+- **Имена `Divider`, `IDividerProps`, `TDividerMarginSize`** и экспорт из `src/components/Divider/index.ts` — часть публичного API.
+- **`displayName = "Divider"`** — виден в React DevTools и snapshot-тестах.
+- **Токен `Divider.Background`** — единственный цвет компонента; переименование ломает темизацию у потребителей.
+- **CSS-классы `divider`, `marginTopSize-{N}`, `marginBottomSize-{N}`** в `styles/Divider.module.less`: базовый класс `divider` объявлен обычным правилом, а `marginTopSize-{N}` / `marginBottomSize-{N}` генерируются LESS-циклом `each` по списку `@size`. Все они проверяются в unit-тестах — переименование требует синхронного обновления тестов.
 
 ---
 
 ## Accessibility
 
-- **`<hr>`** — встроенная семантика разделителя (`role="separator"`).
-  Screen reader'ы читают как "separator" / "разделитель".
-- **Не интерактивный** — tabindex не ставится, клавиатурой не
-  взаимодействует.
-- **Если нужен "assistive"-разделитель внутри списка** — оборачивать
-  в `<li role="separator">`. Divider сам этого не делает.
-
----
-
-## Дизайн-токены
-
-- `--triplex-next-Divider-Background` — цвет линии.
-
-Определение в `src/components/DesignTokens/components/Divider.ts`.
+- `<hr>` имеет неявную роль `separator` с `aria-orientation="horizontal"` — screen reader объявляет разделитель секций. Дополнительных ARIA-атрибутов компонент не выставляет.
+- Компонент не интерактивный и не попадает в таб-порядок: focus management и keyboard navigation не применимы.
+- Если линия чисто декоративная и дублирует уже озвученную структуру, потребитель может передать `aria-hidden="true"` через spread.
+- Библиотека мультиязычная, поэтому текстовых подписей (`aria-label`) компонент не хардкодит — при необходимости их передаёт потребитель.
 
 ---
 
 ## Связанные компоненты
 
-- `Gap` (`src/components/Gap`) — отступ без линии.
-- `Row`/`Col` — grid-система (Divider часто между Row'ами).
-- `Card`, `Island`, `Page` — типичные контейнеры с разделителями
-  внутри.
+- `Gap` (`src/components/Gap/`) — вертикальный отступ без видимой линии, та же идея дискретной шкалы размеров. Частая путаница: нужен пробел — `Gap`, нужна линия — `Divider`.
 
 ---
 
 ## Stories
 
-`stories/Divider/Divider.stories.tsx`
-Примеры: `stories/Divider/examples/`
+Основные истории: `stories/Divider/Divider.stories.tsx`
+Файлы примеров: `stories/Divider/examples/`
 
-Типовые stories:
-- `Default` — разделитель без отступов
-- `WithMargins` — разделитель с margin-top/bottom
-- `AllSizes` — таблица всех поддерживаемых размеров
-- `Playground` — интерактив
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `marginTopSize` и `marginBottomSize` через select |
+| `Default` | `DefaultExample.tsx` | Разделение абзацев текста линией с отступами 24/16 |
+| `VisualTests` | `VisualTestsExample.tsx` | Все 8 значений шкалы отступов для скриншот-регрессии |
 
 ---
 
@@ -193,4 +104,40 @@ border/margin.
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-28 | Создан документ. AI-рефакторинг: компонент переведён с `React.FC` на `React.forwardRef` (`ref` идёт на `<hr>`), уточнены JSDoc на `Divider`, `IDividerProps` и `TDividerMarginSize`, unit-тесты расширены на все значения шкалы отступов и проброс `ref`. |
+| 2026-09-29 | Breaking: `children` исключён из `IDividerProps` (`Omit<React.HTMLAttributes<HTMLHRElement>, "children">`), передача потомков в `<hr>` теперь ловится компилятором. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Divider/examples/DefaultExample.tsx`
+
+```tsx
+import React from "react";
+import { Divider, EFontType, ETextSize, Text } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => (
+    <div style={{ maxWidth: 600 }}>
+        <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et
+            dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
+            ea commodo consequat.
+        </Text>
+        <Divider marginTopSize={24} marginBottomSize={16} />
+        <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+            Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+            Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
+            laborum.
+        </Text>
+        <Divider marginTopSize={24} marginBottomSize={16} />
+        <Text size={ETextSize.B3} type={EFontType.PRIMARY}>
+            Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem
+            aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
+        </Text>
+    </div>
+);
+```
+