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

package/bundle/components/Step.md

@@ -1,23 +1,21 @@
 ---
 component: Step
-category: Navigation
-figma-node: ""
-figma-file: ""
-related: [Stepper, Tooltip]
+category: Step
+related: [Stepper, Tooltip, Text]
 tokens:
-  - --triplex-next-Step-Background_Default
-  - --triplex-next-Step-Background_Active
-  - --triplex-next-Step-Background_Done
-  - --triplex-next-Step-Background_Warning
-  - --triplex-next-Step-Background_Error
-  - --triplex-next-Step-Background_Disabled
-  - --triplex-next-Step-Color_Default
-  - --triplex-next-Step-Color_Active
-  - --triplex-next-Step-Color_Done
-  - --triplex-next-Step-Color_Warning
-  - --triplex-next-Step-Color_Error
-  - --triplex-next-Step-Color_Disabled
-stories: ""
+  - Step.Background_Active
+  - Step.Background_Default
+  - Step.Background_Disabled
+  - Step.Background_Done
+  - Step.Background_Error
+  - Step.Background_Warning
+  - Step.Color_Active
+  - Step.Color_Default
+  - Step.Color_Disabled
+  - Step.Color_Done
+  - Step.Color_Error
+  - Step.Color_Warning
+stories: stories/Step/Step.stories.tsx
 version: "1.0"
 ---
 
@@ -25,92 +23,182 @@ version: "1.0"
 
 ## Назначение
 
-Визуальный «кружок с номером шага» для stepper-интерфейсов. Показывает статус
-(`default`/`active`/`done`/`warning`/`error`/`disabled`) через цветовой стейт.
-Опционально оборачивается в `Tooltip` (hover), если передан `children`.
+Круглый индикатор одного шага: номер внутри кружка, цвет фона и цвет номера кодируют статус
+(`DEFAULT` / `DONE` / `ACTIVE` / `ERROR` / `WARNING` / `DISABLED`). Компонент рисует ровно один
+шаг — ряд шагов и связь между ними собирает потребитель. Если передан `children`, кружок
+оборачивается в `Tooltip`, раскрывающийся по наведению.
 
-Используй когда: нужен отдельный индикатор шага (например, внутри кастомного
-stepper-а). Для готового пошагового виджета — `Stepper`.
-Не используй когда: нужен текстовый label шага — добавь его рядом, `Step`
-отрисовывает только номер в кружке.
+Используй когда: нужно показать номер и состояние отдельного шага внутри своей вёрстки
+пошагового сценария — так его использует `IslandAccordion` для нумерации секций.
 
----
-
-## Файловая структура
-
-```text
-src/components/Step/
-├── Step.tsx          # FC
-├── enums.ts          # EStepStatus, EStepPosition
-├── index.ts
-└── styles/Step.module.less
-```
+Не используй когда:
 
-Также экспортируется утилита `calcPosition(stepCount, i)` — вычисляет
-`EStepPosition` (первый/последний/в середине) для списка шагов.
+- Нужен готовый горизонтальный степпер с переключением шагов, подписями и клавиатурной
+  навигацией — возьми `Stepper` (или `StepperExtended` для произвольного состава шагов).
+  `Step` в реализацию `Stepper` не входит: у того собственный `StepperStep`.
+- Нужен кликабельный элемент. `Step` рендерит `<div>` без роли, фокуса и обработчиков —
+  интерактивность придётся навешивать снаружи, вместе с ролью и клавиатурой.
+- Нужно показать статус без номера — возьми `Marker` или `MarkerStatus`.
 
 ---
 
 ## Варианты и props
 
-### `IStepProps`
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `step` | `number` | Номер шага. Рендерится внутри кружка через `Text` (`B1`, semibold). Компонент не форматирует и не ограничивает значение: двузначные номера помещаются, кружок под содержимое не растягивается |
+| `status` | `EStepStatus` | Состояние шага. Определяет **только** пару цветов — фон кружка и цвет номера |
 
-| Prop | Тип | Default | Описание |
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `step` | `number` | — | Число, отображаемое внутри кружка. |
-| `status` | `EStepStatus` | — | Цветовой стейт (см. ниже). |
-| `position?` | `EStepPosition` | `Default` | Влияет на `alignTip` опционального Tooltip'а. |
-| `children?` | `ReactNode` | — | Контент Tooltip'а. Если не передан — Tooltip не рендерится. |
-| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корневой `<div>`. |
+| `size` | `EComponentSize` | `EComponentSize.MD` | Размер кружка. SM и MD дают 28px, LG — 32px |
+| `position` | `EStepPosition` | `EStepPosition.Default` | Позиция шага в ряду. Влияет **только** на выравнивание указателя подсказки и потому имеет смысл лишь вместе с `children` |
+| `children` | `React.ReactNode` | — | Содержимое подсказки. Без него подсказка не создаётся и `Tooltip` не монтируется вовсе |
 
-### `EStepStatus`
+Остальные props — стандартные атрибуты `div`
+(`IStepProps extends React.HTMLAttributes<HTMLDivElement>`), уходят на корневой элемент
+через `...rest`.
 
-`DEFAULT` / `DONE` / `ACTIVE` / `ERROR` / `WARNING` / `DISABLED`.
+### Размер и статус независимы
 
-Маппинг на CSS-классы 1-к-1 через `statusToClassNameMap`.
+Две оси не пересекаются: `size` отвечает за геометрию, `status` — за пару цветов. Любая
+комбинация допустима, поэтому матрицу 3×6 целиком покрывает story `VisualTests`,
+а документационные stories показывают оси по отдельности.
 
-### `EStepPosition`
+### `position` и подсказка
 
-| Value | Поведение (alignTip) |
-|---|---|
-| `XFirst` | `ETooltipAlign.START` |
-| `Default` | `ETooltipAlign.CENTER` |
-| `XLast` | `ETooltipAlign.END` |
+`position` отображается на `alignTip` подсказки: `XFirst` → `START`, `Default` → `CENTER`,
+`XLast` → `END`. Для крайних шагов ряда указатель прижимается к краю, чтобы подсказка
+не выходила за границы ряда. Без `children` prop ни на что не влияет.
+
+Значение для ряда шагов считает экспортируемый хелпер `calcPosition(stepCount, i)`:
+`XFirst` для `i === 0`, `XLast` для последнего, иначе `Default`. Для ряда из одного шага
+возвращает `XFirst` — проверка на первый шаг идёт первой.
+
+---
+
+## Дизайн-токены
 
-`calcPosition(total, i)` возвращает `XFirst`/`XLast`/`Default` для удобства
-сборки списка шагов.
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Step.ts`.
+
+```text
+Step.Background_Default
+Step.Background_Done
+Step.Background_Active
+Step.Background_Error
+Step.Background_Warning
+Step.Background_Disabled
+Step.Color_Default
+Step.Color_Done
+Step.Color_Active
+Step.Color_Error
+Step.Color_Warning
+Step.Color_Disabled
+```
+
+По паре токенов (`Background_*` + `Color_*`) на каждое значение `EStepStatus`; добавление
+статуса означает и два новых токена. Цвет номера задаётся селектором `& > span` — он попадает
+на элемент, который рендерит `Text`.
+
+Размеры (28 / 32px, `border-radius: 50%`) заданы литералами в `styles/Step.module.less` — они
+специфичны для компонента. Брейкпоинт адаптива берётся из LESS-переменной `@screen-sm-max`.
 
 ---
 
 ## Инварианты
 
-- **Рендер числа через `<Text size=B1 weight=SEMIBOLD>`** — фикс типографики для совпадения с дизайном.
-- **Tooltip рендерится только при наличии `children`** — без children компонент возвращает голый `<div>`.
-- **Tooltip: `toggleType="hover"`, `size=SM`** — не менять без согласования.
-- **Step — `FC`**, ref не пробрасывается (корневой div доступен только через обёртку Tooltip — по-разному в двух ветках рендера).
-- **Публичные enums** (`EStepStatus`, `EStepPosition`) + функция `calcPosition` — часть публичного API.
+- `forwardRef<HTMLDivElement>` — не убирать. Ref всегда указывает на корневой `<div class="step">`,
+  и в варианте с подсказкой тоже: внешний ref мерджится с внутренним через
+  `setForwardedRef` (`src/helpers/setForwardedRef.ts`).
+- Внутренний ref на корневой `<div>` обязателен: он уходит в `Tooltip` как `targetRef` —
+  относительно этого узла считается позиция подсказки. Убрать внутренний ref или перевесить
+  его на другой элемент нельзя.
+- Корневой элемент — `<div>`. Кружок центрует содержимое через `display: flex`; смена тега
+  сломает вёрстку и типизацию props.
+- `displayName` — `"Step"`. Не менять.
+- Значения `EStepStatus` (`"default"` / `"done"` / `"active"` / `"error"` / `"warning"` /
+  `"disabled"`) совпадают с именами CSS-классов в `Step.module.less` и с суффиксами токенов
+  `Step.Background_*` / `Step.Color_*`. Переименование значения enum — ломающее изменение
+  сразу в трёх местах.
+- Значения `EStepPosition` — `PascalCase` (`Default` / `XFirst` / `XLast`), в отличие от
+  остальных enum'ов библиотеки. Это часть публичного API, приводить к общему виду нельзя.
+- Подсказка монтируется только при непустом `children`. Оборачивать кружок в `Tooltip`
+  безусловно нельзя: пустая подсказка перехватывала бы наведение.
+- `EStepStatus.DISABLED` — только цвет. Ни `pointer-events`, ни `aria-disabled` компонент
+  не выставляет, подсказка у выключенного шага продолжает работать.
+- Экспорты `Step`, `IStepProps`, `calcPosition`, `EStepStatus` и `EStepPosition` идут в barrel
+  `src/components/Step/index.ts` — сохранять. `calcPosition` внутри компонента не используется,
+  но входит в публичный API: он нужен потребителю, который собирает ряд шагов.
+- `className` деструктурируется из props и мерджится через `clsx`, поэтому в `...rest`
+  его нет и перезатереть базовые классы он не может.
 
 ---
 
 ## Accessibility
 
-- Компонент — чисто визуальный (`<div>` с числом); сам по себе ARIA-ролью не наделён.
-- В составе stepper-а потребитель обязан обеспечить семантику (`role="list"` / `role="listitem"` / `aria-current="step"` на активном шаге). См. `Stepper-AI`.
-- Tooltip показывается только на hover — для пользователей клавиатуры текст подсказки недоступен. Если содержимое tooltip важно, дублируй его видимым лейблом рядом со Step.
+- Собственной ARIA-роли нет: корневой `<div>` — неинтерактивный контейнер, в порядок фокуса
+  не попадает, обработчиков клавиатуры у компонента нет.
+- Номер шага — единственное, что читает скринридер. Смысл шага в разметку не попадает:
+  текст подсказки живёт в `Tooltip`, который раскрывается по наведению или клику мышью
+  и с клавиатуры недоступен. Если шаг должен быть понятен без мыши, опиши его видимым
+  текстом рядом в своей вёрстке.
+- Статус кодируется только цветом. Дублируй его видимым текстом на стороне потребителя.
+- Одного `aria-label` на `Step` недостаточно: корневой `<div>` без роли получает роль
+  `generic`, которой [спецификация HTML-AAM](https://www.w3.org/TR/html-aria/) запрещает
+  доступное имя, — атрибут попадёт в разметку через `...rest`, но скринридер его не
+  озвучит. Если имя нужно именно на шаге, передай вместе с ним роль, допускающую
+  именование: `<Step step={2} status={EStepStatus.ERROR} role="img" aria-label="Шаг 2, ошибка" />`.
+- Ряд шагов семантики списка не создаёт: если нужна структура, оберни шаги в `<ol>`/`<li>`
+  на стороне потребителя.
+- Компонент не хардкодит текстовые строки: содержимое подсказки и любые `aria-label` задаёт
+  потребитель. Библиотека мультиязычная.
 
 ---
 
 ## Связанные компоненты
 
-- `Stepper` — готовый виджет пошаговой навигации, использует Step внутри через `StepperStep` / `StepperStepIcon`.
-- `Tooltip` — оборачивает Step при наличии children.
-- `Typography.Text` — используется для рендера номера.
+- `Stepper` — готовый горизонтальный степпер с подписями, выбором шага и клавиатурной
+  навигацией. Альтернатива, когда нужен весь сценарий целиком, а не отдельный индикатор.
+  Общего кода со `Step` нет: у `Stepper` собственный `StepperStep`.
+- `Tooltip` — рендерится вокруг кружка, когда передан `children`. `Step` фиксирует
+  `size={ETooltipSize.SM}` и `toggleType="hover"`, а из props потребителя прокидывает
+  только выравнивание указателя (`alignTip`) — остальное настроить нельзя. `disableAdaptiveMode`
+  не передаётся, поэтому на экранах до `SM_MAX` включительно подсказка открывается
+  в адаптивном (полноэкранном) режиме.
+- `Text` — рендерит номер шага (`ETextSize.B1`, `EFontWeightText.SEMIBOLD`). Цвет номера
+  задаётся снаружи, селектором `& > span` в стилях `Step`.
+- `IslandAccordion` — потребитель: нумерует секции аккордеона, передавая `Step` номер,
+  статус и `size`. Опирается на то, что `Step` рисует только кружок, без внешних отступов.
 
 ---
 
 ## Stories
 
-Отдельных stories нет (используется внутри stories `Stepper`).
+Основные истории: `stories/Step/Step.stories.tsx`
+Файлы примеров: `stories/Step/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `step`, `status`, `size`, `position` и текста подсказки |
+| `Default` | `Default.tsx` | Минимальный шаг: обязательны только `step` и `status` |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG при одном статусе |
+| `Statuses` | `Statuses.tsx` | Все шесть значений `EStepStatus` при одном размере |
+| `WithTooltip` | `WithTooltip.tsx` | Шаг с подсказкой: `children` становится её содержимым |
+| `Example` | `Example.tsx` | Ряд шагов платёжного сценария, `position` считается через `calcPosition` |
+| `VisualTests` | `VisualTests.tsx` | Матрица размеров × статусов, двузначные номера и раскрытая подсказка (открывается `play`) — для скриншот-тестов |
+
+Из скриншот-тестов исключены (`testRunner: { skip: true }`) `Playground`, `Default` и
+`WithTooltip`: первые два визуально дублируют `Statuses`, а закрытая подсказка
+неотличима от обычного шага — раскрытая снимается в `VisualTests`, где её открывает
+`play`. Не добавляй им скриншоты: это дубли, которые придётся поддерживать.
+
+Story ID участвуют в именах baseline-скриншотов (`step--sizes--xs.png` и т.п.), поэтому
+переименование story требует перегенерации baseline и удаления осиротевших файлов.
 
 ---
 
@@ -118,4 +206,105 @@ src/components/Step/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-24 | Создан документ. AI-рефакторинг: `Step` переведён с `React.FC` на `forwardRef` (внешний ref мерджится с внутренним, который уходит в `Tooltip` как `targetRef`), JSDoc на компоненте и дефолтах props, `renderContent()` заменён на вычисляемый один раз элемент, приведён к порядку LESS. Добавлены unit-тесты (`__tests__/Step.test.tsx`), stories созданы по modern pattern (`stories/Step/`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Step/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Step, EStepStatus } from "@sberbusiness/triplex-next";
+
+export const Default = () => <Step step={1} status={EStepStatus.DEFAULT} />;
+```
+
+### Sizes
+
+`stories/Step/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Step, EComponentSize, EStepStatus } from "@sberbusiness/triplex-next";
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size, index) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Step step={index + 1} status={EStepStatus.ACTIVE} size={size} />
+            </div>
+        ))}
+    </div>
+);
+```
+
+### Statuses
+
+`stories/Step/examples/Statuses.tsx`
+
+```tsx
+import React from "react";
+import { Step, EStepStatus } from "@sberbusiness/triplex-next";
+
+const STATUSES = Object.values(EStepStatus);
+
+export const Statuses = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {STATUSES.map((status, index) => (
+            <div key={status}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
+                <Step step={index + 1} status={status} />
+            </div>
+        ))}
+    </div>
+);
+```
+
+### WithTooltip
+
+`stories/Step/examples/WithTooltip.tsx`
+
+```tsx
+import React from "react";
+import { Step, EStepStatus } from "@sberbusiness/triplex-next";
+
+export const WithTooltip = () => (
+    <Step step={2} status={EStepStatus.ACTIVE}>
+        Заполните реквизиты получателя
+    </Step>
+);
+```
+
+### Example
+
+`stories/Step/examples/Example.tsx`
+
+```tsx
+import React from "react";
+import { Step, calcPosition, EStepStatus } from "@sberbusiness/triplex-next";
+
+const STEPS = [
+    { hint: "Реквизиты получателя заполнены", status: EStepStatus.DONE },
+    { hint: "Проверьте сумму и назначение платежа", status: EStepStatus.ACTIVE },
+    { hint: "Подписание доступно после проверки", status: EStepStatus.DEFAULT },
+    { hint: "Отправка доступна после подписания", status: EStepStatus.DISABLED },
+];
+
+export const Example = () => (
+    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
+        {STEPS.map(({ hint, status }, index) => (
+            <Step key={hint} step={index + 1} status={status} position={calcPosition(STEPS.length, index)}>
+                {hint}
+            </Step>
+        ))}
+    </div>
+);
+```
+