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

package/bundle/components/Stepper.md

@@ -1,10 +1,24 @@
 ---
 component: Stepper
-category: Navigation
-figma-node: ""
-figma-file: ""
-related: [Step, CarouselExtended, ButtonIcon]
-tokens: []
+category: Stepper
+related: [StepperExtended, Step, CarouselExtended, ButtonIcon]
+tokens:
+  - Stepper.ButtonWrapper_Background_Next
+  - Stepper.ButtonWrapper_Background_Prev
+  - Stepper.Step_Background_Default
+  - Stepper.Step_Background_Disabled
+  - Stepper.Step_Background_Error
+  - Stepper.Step_Background_Error_Hover
+  - Stepper.Step_Background_Hover
+  - Stepper.Step_Background_Warning
+  - Stepper.Step_Background_Warning_Hover
+  - Stepper.Step_BorderColor_Error
+  - Stepper.Step_BorderColor_Focus
+  - Stepper.Step_BorderColor_Success
+  - Stepper.Step_BorderColor_Warning
+  - Stepper.Step_Color_Default
+  - Stepper.Step_Color_Disabled
+  - Stepper.Step_Color_Hover
 stories: stories/Stepper/Stepper.stories.tsx
 version: "1.0"
 ---
@@ -13,146 +27,138 @@ version: "1.0"
 
 ## Назначение
 
-Горизонтальный список шагов оформления с активным шагом, пройденными и
-непройденными. Обёрнут в `CarouselExtended` — при overflow добавляются
-кнопки-скроллеры и авто-прокрутка к выбранному шагу (с адаптивом по
-breakpoint `SM_MAX`: scroll-to-center vs scroll-to-edge).
+Лента шагов-стрелок поверх `StepperExtended` и `CarouselExtended`: компонент принимает массив шагов, сам собирает разметку, сам рендерит кнопки прокрутки для не поместившихся шагов и сам подводит выбранный шаг в видимую область.
 
-Используй когда: нужна готовая пошаговая навигация (например, оформление
-заявки). Для ручной сборки из шагов без карусели — `StepperExtended`.
-Для отдельного кружка шага — `Step`.
+Используй когда: нужно показать прохождение многошагового сценария и дать переключаться между шагами — это первый выбор для обычной задачи.
+Не используй когда:
 
----
-
-## Файловая структура
-
-```text
-src/components/Stepper/
-├── Stepper.tsx              # FC, оборачивает StepperExtended в CarouselExtended
-├── StepperExtended.tsx      # FC + Provider (tablist), без карусели
-├── StepperStep.tsx          # FC + StepperStep.Icon; li role=button
-├── StepperStepIcon.tsx
-├── StepperWrapper.tsx       # статичная обёртка
-├── StepperExtendedContext.ts
-├── RightBorderArrow.tsx     # угловой «стрелочный» separator между шагами
-├── enums.ts                 # EStepperSize, EStepperStepType, EStepperStepIconType
-└── styles/
-```
+- содержимое шага нестандартное (своя разметка внутри шага, свои кнопки прокрутки) — бери `StepperExtended`, `Stepper` собран поверх него;
+- нужен нумерованный индикатор шагов с подписью и тултипом вместо ленты-стрелок — бери `Step`;
+- шаги не переключаются пользователем и нужен только статус процесса — это не задача компонента.
 
 ---
 
-## Публичный API
+## Варианты и props
 
-### `Stepper` — готовый виджет
+`IStepperProps` расширяет `Omit<IStepperExtendedProps, "children">` (а тот — `React.HTMLAttributes<HTMLOListElement>`).
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `steps` | `IStepperStep[]` | — | Массив шагов: `id`, `type`, `icon?`, `disabled?`, `label?`. |
-| `size?` | `EStepperSize` | `SM` | SM / MD / LG. |
-| `selectedStepId?` | `string` | — | Id выбранного шага. |
-| `onSelectStep` | `(id: string) => void` | — | Колбэк выбора. |
-| `children` | `never` | — | Запрещено — шаги передаются через `steps`. |
-
-`IStepperStep`:
-```ts
-{ id: string; type: EStepperStepType; label?: ReactNode; icon?: ReactNode; disabled?: boolean }
-```
+**Куда что уходит.** Компонент вынимает из props только `className`, `steps`, `size` и `selectedStepId`. `className` мерджится в корневой `<div>` карусели, а **все остальные props** уходят на `<ol role="tablist">` внутри неё. Это разные элементы: `aria-label`, `data-*`, `style`, `id`, `onClick` и прочее оказываются на списке шагов, а не на корне. В частности, `className` и `style` попадают на **разные** элементы: `<Stepper style={{width: 400}} />` задаёт ширину `<ol>`, а не корня.
 
-### `StepperExtended` — без карусели
+### Обязательные props
 
-Для ручной сборки (напр. в вертикальном layout).
+| Prop | Тип | Описание |
+|---|---|---|
+| `steps` | `Array<IStepperStep>` | Состав ленты. Порядок массива = порядок прохождения: шаги до выбранного считаются пройденными, после — непройденными |
+| `onSelectStep` | `(id: string) => void` | Запрос на смену выбранного шага. Вызывается кликом и клавишами `Enter` / `Space`, в том числе на уже выбранном шаге |
 
-| Prop | Тип | Default | Описание |
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `size?` | `EStepperSize` | `SM` | Прокидывается в Context. |
-| `selectedStepId?` | `string` | — | Id активного шага. |
-| `onSelectStep` | `(id: string) => void` | — | Колбэк. |
-| `forwardedRef?` | `Ref<HTMLOListElement>` | — | Ref на `<ol role="tablist">`. |
-| `children` | `ReactNode` | — | `StepperExtended.Step` (`StepperStep`). |
+| `size` | `EComponentSize` | `MD` | Один prop на весь компонент: задаёт и высоту шагов, и размер кнопок прокрутки |
+| `selectedStepId` | `string` | — | `id` текущего шага. Компонент полностью управляемый: своего состояния выбора у него нет |
+| `forwardedRef` | `React.Ref<HTMLOListElement>` | — | Ссылка на `<ol>` со списком шагов. Единственный ref-контракт компонента — см. «Инварианты» |
 
-### `StepperStep` (`Stepper.Step` / `StepperExtended.Step`)
+### Поля элемента `steps` (`IStepperStep`)
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `id` | `string` | Уникальный id (матчится с `selectedStepId`). |
-| `type` | `EStepperStepType` | `NEUTRAL` / `ERROR` / `WARNING` (применяет цветовой модификатор, если !disabled). |
-| `disabled?` | `boolean` | Блокирует выбор. |
-| `icon?` | `ReactNode` | Обычно `<StepperStep.Icon type={EStepperStepIconType} />`. |
-| `isInActiveStep?` | `boolean` | Непройденный шаг (индекс > selectedIndex). В `Stepper` выставляется автоматически. |
-| `forwardedRef?` | `Ref<HTMLLIElement>` | Ref на `<li>`. В `Stepper` используется для авто-скролла. |
-| `children` | `ReactNode` | Лейбл шага. |
-
-Статус шага определяется композицией:
-- `active` = `id === selectedId`
-- `inactive` = `isInActiveStep`
-- `completed` = `!active && !inactive`
-- `error`/`warning` применяются поверх, когда `!disabled`.
-
-### `StepperStep.Icon`
+`IStepperStep` расширяет `IStepperStepProps`, то есть принимает и HTML-атрибуты `<li>`-элемента шага.
 
-| Prop | Тип | Описание |
+| Поле | Тип | Описание |
 |---|---|---|
-| `type` | `EStepperStepIconType` | `FILLED` / `SUCCESS` / `ERROR` / `WARNING` / `WAIT`. |
+| `id` | `string` | Обязательное. Сопоставляется с `selectedStepId`, приходит в `onSelectStep`, служит React-ключом |
+| `type` | `EStepperStepType` | Обязательное. `NEUTRAL` — обычный шаг, `ERROR` / `WARNING` подсвечивают шаг цветом. У отключённого шага тип не применяется |
+| `label` | `React.ReactNode` | Содержимое шага. Единственное поле, которое не уходит в HTML-атрибуты `<li>` |
+| `icon` | `React.ReactNode` | Иконка статуса слева от `label`, обычно `StepperStepIcon`. Гасится вместе с шагом при `disabled` |
+| `disabled` | `boolean` | Шаг не реагирует на клик и клавиатуру и выпадает из таб-порядка |
 
-### `Stepper.Wrapper` / `StepperExtended.Wrapper`
+### Ограничения
 
-Простой `<div>` с `className="stepperWrapper"` — layout-контейнер для размещения Stepper в шапке/панели.
+- `isInActiveStep` компонент вычисляет сам по индексу шага относительно выбранного и перетирает значение, переданное в элементе `steps`.
+- `forwardedRef` в элементе `steps`, наоборот, перетирает внутреннюю ссылку `Stepper` на шаг — после этого лента перестаёт подводить выбранный шаг в видимую область. Ссылки на шаги нужны компоненту для прокрутки; если нужен доступ к узлу шага, бери его через `forwardedRef` самого `Stepper` и DOM-обход.
+- `id` шагов должны быть уникальными: по ним идёт сопоставление с `selectedStepId`, React-ключи и внутренняя карта ссылок на узлы.
+- Пустой массив `steps` допустим — рендерится пустой `<ol>`.
+- Если `selectedStepId` не задан или не найден в `steps`, пройденных шагов нет: вся лента отображается как непройденная.
 
 ---
 
-## Контекст (`StepperExtendedContext`)
+## Дизайн-токены
 
-Хранит `selectedId`, `size`, `onSelectStep`. `StepperStep` — потребитель этого контекста.
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Stepper.ts`.
 
----
-
-## Логика выравнивания в Stepper
+Семейство `Stepper.Step_*` общее для `Stepper`, `StepperExtended` и шага `StepperStep` — оформление самих шагов приходит оттуда. Собственные стили `Stepper` — только подложка под кнопками прокрутки (`ButtonWrapper_*`), она растушёвывает край ленты градиентом.
 
-При смене `selectedStepId`:
-1. `getBoundingClientRect` для carousel и шага.
-2. На узких экранах (`max-width: SM_MAX`) → scroll по центру выбранного шага.
-3. На широких → scroll к краю (left/right) с паддингом `32px` (`paddingLeft/Right`).
-
-Кнопки scroll'а рендерятся через `CarouselExtended.buttonPrev/Next` с `aria-label="Прокрутить назад" / "Прокрутить вперёд"`.
+```text
+Stepper.ButtonWrapper_Background_Prev
+Stepper.ButtonWrapper_Background_Next
+Stepper.Step_Background_Default
+Stepper.Step_Background_Hover
+Stepper.Step_Background_Disabled
+Stepper.Step_Background_Error
+Stepper.Step_Background_Error_Hover
+Stepper.Step_Background_Warning
+Stepper.Step_Background_Warning_Hover
+Stepper.Step_BorderColor_Focus
+Stepper.Step_BorderColor_Error
+Stepper.Step_BorderColor_Warning
+Stepper.Step_BorderColor_Success
+Stepper.Step_Color_Default
+Stepper.Step_Color_Hover
+Stepper.Step_Color_Disabled
+```
 
 ---
 
 ## Инварианты
 
-- **`<ol role="tablist">`** на StepperExtended, **`<li role="button">`** на StepperStep — ARIA-роли.
-- **`aria-current`** применяется только к активному шагу (`progress ? true : undefined`). Для неактивных — должен быть `undefined`, не `false`.
-- **`tabIndex={disabled ? -1 : 0}`** на `<li>` — не ронять.
-- **Keyboard: Enter/Space** выбирают шаг. `Space` — с `preventDefault()` чтобы страница не скроллилась.
-- **`Stepper.children: never`** — API через `steps`.
-- **Публичные enums** (`EStepperSize`, `EStepperStepType`, `EStepperStepIconType`) — breaking change.
-- **`Stepper.Wrapper === StepperWrapper`** и **`Stepper.Step === StepperStep`** — дублируются на `Stepper` и `StepperExtended`, не удалять.
-- **`RightBorderArrow`** рендерится после контента каждого шага — визуальный separator. Не заменять inline-псевдоэлементом без проверки нарезки.
-- **Корневой `<ol>` — не кнопка**; клик открывается на `<li>` через `role="button"` (W3C-некомпатибельно по-строгому, но принятая конвенция проекта).
+- **Ref-контракт — prop `forwardedRef`, а не `ref`.** `Stepper` объявлен как `React.FC`: `React.forwardRef` ему не добавляли осознанно. `CarouselExtended` отдаёт наружу ссылку на прокручиваемую ленту, а не на корневой `<div>`, а сам `Stepper` держит эту ссылку для прокрутки — поэтому `ref` пришлось бы вести на другой DOM-узел, чем уже задокументированный `forwardedRef` (`<ol>`), и получилось бы два ref-контракта на разные элементы. Добавление `forwardRef` требует сначала научить `CarouselExtended` отдавать корневой элемент.
+- Публичные имена `Stepper`, `IStepperProps`, `IStepperStep`, `EStepperStepType`, `EStepperStepIconType` и barrel `src/components/Stepper/index.ts` — часть публичного API.
+- `Stepper.Step = StepperStep` — статическое свойство, часть публичного API (тот же компонент, что `StepperExtended.Step`).
+- Компонент строится на `CarouselExtended` и передаёт ему `stepPrev` / `stepNext` — величину прокрутки одним кликом, равную 30% ширины видимой области ленты. Величина пересчитывается `ResizeObserver` и до первого измерения равна нулю.
+- Состояние шага кодируется взаимоисключающими классами `completed` / `active` / `inactive` и вычисляется по индексу относительно выбранного шага. Зафиксировано unit-тестами.
+- Класс размера (`sm` / `md` / `lg`) вешается и на корневой `<div>` карусели, и на каждый шаг: от него зависят и высота шага, и размер кнопки прокрутки.
+- Кнопки прокрутки исключены из таб-порядка (`tabIndex = -1`) и скрыты на экранах уже 768px — прокрутка всё равно доступна колесом, жестом и обходом шагов по `Tab`.
+- Подводка выбранного шага в видимую область (`alignStep`) — функции модульного уровня в `Stepper.tsx` (читают геометрию DOM через `getBoundingClientRect`, проверяют `window.matchMedia` и прокручивают ленту), зафиксированы unit-тестами: на узких экранах шаг центрируется, на широких — прижимается к ближайшему краю вместе с соседним шагом.
 
 ---
 
 ## Accessibility
 
-- `role="tablist"` / `role="button"` (`<li>` не tab — сделано по-проектному).
-- `aria-disabled={disabled}`, `aria-current={progress ? true : undefined}`.
-- Keyboard: Enter/Space — выбор шага. Стрелки — **не обрабатываются** (используется carousel-прокрутка). Переход Tab-ом: по одному шагу.
-- Авто-прокрутка при `selectedStepId` может сбить фокус визуально — но focus на `<li>` сохраняется, шаг всегда будет в видимой области.
-- Потребитель должен обеспечить осмысленные labels шагов (`label` или `children`) — не полагаться на номер.
+- Разметка приходит из `StepperExtended` и `StepperStep`: корневой список — `<ol role="tablist">`, каждый шаг — `<li role="button">`. Выбранный шаг помечается `aria-current="true"`, отключённый — `aria-disabled="true"` и `tabIndex = -1`.
+- **Известное расхождение с WAI-ARIA:** дети `role="tablist"` имеют `role="button"`, а не `role="tab"`. Это текущее публичное поведение, зафиксированное тестами; смена ролей — отдельная задача с записью в release notes.
+- **Клавиатура:** `Enter` и `Space` на шаге вызывают `onSelectStep`, для `Space` дополнительно вызывается `preventDefault`, чтобы страница не скроллилась. Других клавиш компонент не перехватывает: между шагами ходят обычным `Tab` — каждый доступный шаг находится в таб-порядке.
+- `:focus-visible` эмулируется вручную: класс подсветки ставится, только если фокус пришёл не после `mousedown`, — клик по шагу рамку не рисует.
+- Кнопки прокрутки компонент рендерит сам и текста не хардкодит: доступного имени у них нет, поэтому они исключены из таб-порядка и не должны быть единственным способом добраться до шага.
+- При смене `selectedStepId` лента прокручивается плавно (анимация по кадрам, `prefers-reduced-motion` не учитывается).
 
 ---
 
 ## Связанные компоненты
 
-- `Step` — отдельный кружок шага (не используется внутри Stepper).
-- `CarouselExtended` — обёртка в `Stepper`.
-- `ButtonIcon`, `IconWrapper` — UI.
+- `StepperExtended` — база: `Stepper` рендерит его и наследует его интерфейс (`IStepperProps extends Omit<IStepperExtendedProps, "children">`). Туда же уходят, когда нужен нестандартный состав шага.
+- `StepperStep` — шаг ленты, доступен как `Stepper.Step` и `StepperExtended.Step`. Отдельного AI.md нет: через `Stepper` он настраивается полями элемента `steps`, вся его семантика описана выше.
+- `StepperStepIcon` — иконка статуса шага: маппинг значения `EStepperStepIconType` (`FILLED`, `SUCCESS`, `WARNING`, `ERROR`, `WAIT`) в иконку из `@sberbusiness/icons-next`. Отдельного AI.md нет — это тривиальная обёртка с единственным prop `type`.
+- `Step` — альтернативный визуальный паттерн шагов: нумерованный кружок с подписью и тултипом вместо ленты-стрелок.
+- `CarouselExtended` — прокручиваемая лента, которую `Stepper` рендерит сам; ему же передаётся величина прокрутки одним кликом.
+- `ButtonIcon` — кнопки прокрутки ленты, которые `Stepper` рендерит через render-props `buttonPrev` / `buttonNext` карусели.
 
 ---
 
 ## Stories
 
 Основные истории: `stories/Stepper/Stepper.stories.tsx`
-Примеры: `stories/Stepper/examples/`
+Файлы примеров: `stories/Stepper/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль размера, типа текущего шага, количества шагов, иконок и ширины контейнера |
+| `Default` | `Default.tsx` | Минимальный набор: три шага, выбран второй |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Types` | `Types.tsx` | Типы шага `NEUTRAL`, `ERROR`, `WARNING` |
+| `WithIcons` | `WithIcons.tsx` | Все значения `EStepperStepIconType` на шагах |
+| `ManySteps` | `ManySteps.tsx` | Шаги не помещаются в контейнер и прокручиваются |
+| `VisualTests` | `VisualTests.tsx` | Размеры × состояния, отключённый шаг, типы, `:focus-visible` на шаге (через `play`) |
+| `StepperExtendedType` | — | Стори базового `StepperExtended`; живёт в этом файле до отдельной задачи по `StepperExtended` |
 
 ---
 
@@ -160,4 +166,251 @@ src/components/Stepper/
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-24 | Создан документ AI-ready для `Stepper` (TRI-84). |
+| 2026-09-24 | AI-рефакторинг: подводка шага и кнопки прокрутки вынесены в чистые функции и отдельный компонент модульного уровня, величина прокрутки хранится одним числом вместо объекта, ссылки на узлы удалённых шагов больше не удерживаются, JSDoc проставлен на публичных полях `steps` и `size`. Публичный API (имена props, значения enum, barrel-экспорты) и разметка не изменились. Добавлены unit-тесты на состояния шагов, типы, клавиатуру, `forwardedRef`, `...rest` и подводку шага в видимую область; stories переписаны по modern pattern. |
+| 2026-09-25 | Размер по умолчанию изменён с `LG` на `MD` по решению ревью — вместе со `StepperExtended`, чтобы компоненты не разъехались. Изменение наблюдаемое: без явного `size` шаги и кнопки прокрутки становятся меньше, описано в release notes 1.48.0. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Stepper/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { EStepperStepIconType, EStepperStepType, Stepper, StepperStepIcon } from "@sberbusiness/triplex-next";
+
+const STEPS = [
+    {
+        id: "step1",
+        label: "Step 1",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.SUCCESS} />,
+    },
+    {
+        id: "step2",
+        label: "Step 2",
+        type: EStepperStepType.NEUTRAL,
+    },
+    {
+        id: "step3",
+        label: "Step 3",
+        type: EStepperStepType.NEUTRAL,
+    },
+];
+
+export const Default = () => {
+    const [selectedStepId, setSelectedStepId] = useState("step2");
+
+    return <Stepper steps={STEPS} selectedStepId={selectedStepId} onSelectStep={setSelectedStepId} />;
+};
+```
+
+### Sizes
+
+`stories/Stepper/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EComponentSize,
+    EStepperStepIconType,
+    EStepperStepType,
+    Stepper,
+    StepperStepIcon,
+} from "@sberbusiness/triplex-next";
+
+const STEPS = [
+    {
+        id: "step1",
+        label: "Step 1",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.SUCCESS} />,
+    },
+    {
+        id: "step2",
+        label: "Step 2",
+        type: EStepperStepType.NEUTRAL,
+    },
+    {
+        id: "step3",
+        label: "Step 3",
+        type: EStepperStepType.NEUTRAL,
+    },
+];
+
+interface ISizeItemProps {
+    size: EComponentSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [selectedStepId, setSelectedStepId] = useState("step2");
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <Stepper steps={STEPS} size={size} selectedStepId={selectedStepId} onSelectStep={setSelectedStepId} />
+        </div>
+    );
+};
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### Types
+
+`stories/Stepper/examples/Types.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EStepperStepIconType,
+    EStepperStepType,
+    IStepperStep,
+    Stepper,
+    StepperStepIcon,
+} from "@sberbusiness/triplex-next";
+
+/** Набор шагов, в котором второй шаг помечен переданным типом. */
+const getSteps = (type: EStepperStepType, iconType: EStepperStepIconType): Array<IStepperStep> => [
+    {
+        id: "step1",
+        label: "Step 1",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.SUCCESS} />,
+    },
+    {
+        id: "step2",
+        label: "Step 2",
+        type,
+        icon: <StepperStepIcon type={iconType} />,
+    },
+    {
+        id: "step3",
+        label: "Step 3",
+        type: EStepperStepType.NEUTRAL,
+    },
+];
+
+interface ITypeItemProps {
+    caption: string;
+    type: EStepperStepType;
+    iconType: EStepperStepIconType;
+}
+
+const TypeItem = ({ caption, type, iconType }: ITypeItemProps) => {
+    const [selectedStepId, setSelectedStepId] = useState("step2");
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{caption}</div>
+            <Stepper
+                steps={getSteps(type, iconType)}
+                selectedStepId={selectedStepId}
+                onSelectStep={setSelectedStepId}
+            />
+        </div>
+    );
+};
+
+export const Types = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+        <TypeItem caption="NEUTRAL" type={EStepperStepType.NEUTRAL} iconType={EStepperStepIconType.WAIT} />
+        <TypeItem caption="ERROR" type={EStepperStepType.ERROR} iconType={EStepperStepIconType.ERROR} />
+        <TypeItem caption="WARNING" type={EStepperStepType.WARNING} iconType={EStepperStepIconType.WARNING} />
+    </div>
+);
+```
+
+### WithIcons
+
+`stories/Stepper/examples/WithIcons.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { EStepperStepIconType, EStepperStepType, Stepper, StepperStepIcon } from "@sberbusiness/triplex-next";
+
+const STEPS = [
+    {
+        id: "step1",
+        label: "FILLED",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.FILLED} />,
+    },
+    {
+        id: "step2",
+        label: "SUCCESS",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.SUCCESS} />,
+    },
+    {
+        id: "step3",
+        label: "WAIT",
+        type: EStepperStepType.NEUTRAL,
+        icon: <StepperStepIcon type={EStepperStepIconType.WAIT} />,
+    },
+    {
+        id: "step4",
+        label: "ERROR",
+        type: EStepperStepType.ERROR,
+        icon: <StepperStepIcon type={EStepperStepIconType.ERROR} />,
+    },
+    {
+        id: "step5",
+        label: "WARNING",
+        type: EStepperStepType.WARNING,
+        icon: <StepperStepIcon type={EStepperStepIconType.WARNING} />,
+    },
+];
+
+export const WithIcons = () => {
+    const [selectedStepId, setSelectedStepId] = useState("step3");
+
+    return <Stepper steps={STEPS} selectedStepId={selectedStepId} onSelectStep={setSelectedStepId} />;
+};
+```
+
+### ManySteps
+
+`stories/Stepper/examples/ManySteps.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EStepperStepIconType,
+    EStepperStepType,
+    IStepperStep,
+    Stepper,
+    StepperStepIcon,
+} from "@sberbusiness/triplex-next";
+
+const STEPS: Array<IStepperStep> = Array.from({ length: 15 }, (_, index) => ({
+    id: `step${index + 1}`,
+    label: `Step ${index + 1}`,
+    type: EStepperStepType.NEUTRAL,
+    icon: index < 4 ? <StepperStepIcon type={EStepperStepIconType.SUCCESS} /> : undefined,
+}));
+
+export const ManySteps = () => {
+    const [selectedStepId, setSelectedStepId] = useState("step2");
+
+    return (
+        // Контейнер уже ленты шагов: лишние шаги уезжают за край и прокручиваются.
+        // Кнопки прокрутки появляются по наведению на ленту и скрыты на узких экранах.
+        <div style={{ maxWidth: "480px" }}>
+            <Stepper steps={STEPS} selectedStepId={selectedStepId} onSelectStep={setSelectedStepId} />
+        </div>
+    );
+};
+```
+