@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/Spoiler.md

@@ -0,0 +1,121 @@
+---
+component: Spoiler
+category: Disclosure
+figma-node: ""
+figma-file: ""
+related: [AccordionBase, Button]
+tokens: []
+stories: stories/Spoiler/Spoiler.stories.tsx
+version: "1.0"
+---
+
+# Spoiler
+
+## Назначение
+
+Раскрывающаяся область с link-кнопкой-триггером сверху. Текст триггера
+переключается между `labelExpand` / `labelCollapse`, содержимое скрывается
+CSS-классом (`hidden`) — DOM не размонтируется.
+
+Используй когда: нужно показать/скрыть блок вспомогательной информации
+через простой inline-триггер (не секцию-«аккордеон»).
+Не используй когда: нужна секционированная навигация с несколькими
+панелями — используй `AccordionBase`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Spoiler/
+├── Spoiler.tsx       # forwardRef<HTMLDivElement, TSpoilerProps>
+├── index.ts
+└── styles/Spoiler.module.less
+```
+
+---
+
+## Варианты и props
+
+`TSpoilerProps = ISpoilerControlledProps | ISpoilerUncontrolledProps`.
+
+### Общие (`ISpoilerBaseProps`)
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `labelExpand` | `string` | — | Текст кнопки в свернутом состоянии. |
+| `labelCollapse?` | `string` | — | Текст кнопки в раскрытом состоянии. Если не задан — кнопка показывает `labelExpand` всегда. |
+| `onToggle?` | `(expanded: boolean) => void` | — | Колбэк изменения состояния. Вызывается ВСЕГДА (и в controlled, и в uncontrolled). |
+| `rightBlock?` | `ReactNode` | — | Доп. контент справа от триггера в шапке. |
+| `size?` | `EComponentSize` | `MD` | `SM` → icon-16, `MD`/`LG` → icon-20. |
+| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корень. |
+
+### Controlled (`ISpoilerControlledProps`)
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `expanded` | `boolean` | Контролируемое состояние. |
+| `toggle` | `(next: boolean) => void` | Контролирующий handler. Обязателен если передан `expanded`. |
+
+### Uncontrolled (`ISpoilerUncontrolledProps`)
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `expanded` | `never` | Запрещено. |
+| `toggle` | `never` | Запрещено. |
+
+Различение controlled/uncontrolled — по `expanded !== undefined` внутри компонента.
+
+---
+
+## Иконка
+
+| Size | Icon |
+|---|---|
+| `SM` | `CaretdownStrokeSrvIcon16` (paletteIndex=5) |
+| `MD` | `CaretdownStrokeSrvIcon20` (paletteIndex=5) |
+| `LG` | `CaretdownStrokeSrvIcon20` (paletteIndex=5) |
+
+Поворот иконки — через CSS (`styles.opened` на root применяет transform к `.caretIcon`).
+
+---
+
+## Инварианты
+
+- **`forwardRef<HTMLDivElement>`** — не убирать.
+- **Триггер — `Button` с `theme={EButtonTheme.LINK}`** и размером `size` из props. Замена на `ButtonIcon` / `Link` — breaking change.
+- **Контент не размонтируется** при сворачивании — скрывается классом `styles.hidden`. Это сохраняет state детей между раскрытиями; потребитель должен учитывать, что скрытый контент остаётся в DOM (focusability, форм-валидация).
+- **`aria-expanded` на Button, `aria-controls` → id контента, `id` контента** — генерируется через `uniqueId()` один раз в `useRef`. Не переопределять.
+- **`onToggle` вызывается всегда** — даже в controlled варианте (удобно для аналитики рядом с `toggle`).
+- **`labelCollapse` опционален** — если не задан, открытое состояние покажет `labelExpand`. Это допустимо, но нетипично.
+
+---
+
+## Accessibility
+
+- `aria-expanded={open}` и `aria-controls={instanceId}` связывают триггер-кнопку с контентом.
+- Контент получает `id={instanceId.current}` — уникальный per-instance.
+- Триггер — нативная `<button>` (через `Button` → `theme=LINK`), стандартные keyboard-обработчики (Enter/Space).
+- Скрытый контент остаётся в DOM (не `display:none` → `hidden` класс; точная CSS-имплементация — в `Spoiler.module.less`). Проверь перед изменением, не должен ли контент быть недоступен для screen reader'а.
+
+---
+
+## Связанные компоненты
+
+- `AccordionBase` — многосекционный аккордеон.
+- `Button` — триггер (LINK theme).
+
+---
+
+## Stories
+
+`stories/Spoiler/Spoiler.stories.tsx`
+Примеры: `stories/Spoiler/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/StatusTracker.md

@@ -0,0 +1,151 @@
+---
+component: StatusTracker
+category: Data Display
+figma-node: ""
+figma-file: ""
+related: [MarkerStatus, Alert, Card]
+tokens:
+  - --triplex-next-StatusTracker-Approved_Background
+  - --triplex-next-StatusTracker-Approved_Color
+  - --triplex-next-StatusTracker-Rejected_Background
+  - --triplex-next-StatusTracker-Rejected_Color
+  - --triplex-next-StatusTracker-Waiting_Background
+  - --triplex-next-StatusTracker-Waiting_Color
+  - --triplex-next-StatusTracker-Warning_Background
+  - --triplex-next-StatusTracker-Draft_Background
+  - --triplex-next-StatusTracker-Border_Color
+stories: stories/StatusTracker/StatusTracker.stories.tsx
+version: "1.0"
+---
+
+# StatusTracker
+
+## Назначение
+
+Карточка статуса документа с цветной отметкой (бекграунд слева) соответствующей
+типу. Композитный компонент: `Media` (иконка/превью) + `Header` (заголовок/
+сумма/описание) + `Body` (статус/алерт) + `Footer` (кнопки/описание).
+
+Используй когда: нужно показать state документа/заявки с акцентированной
+цветовой меткой (типовой виджет списка документов).
+Не используй когда: нужна просто инлайн-отметка статуса — возьми `MarkerStatus`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/StatusTracker/
+├── StatusTracker.tsx                      # корневой + композиция (Media/Header/Body/Footer)
+├── enums.ts                               # EStatusTrackerType, EStatusTrackerVerticalAlign
+├── components/
+│   ├── StatusTrackerMedia.tsx
+│   ├── StatusTrackerHeader.tsx            # + Title, Sum, Description
+│   ├── StatusTrackerBody.tsx              # + Alert, Status
+│   ├── StatusTrackerFooter.tsx            # + Button, Description
+│   ├── StatusTrackerTitle.tsx
+│   ├── StatusTrackerSum.tsx
+│   ├── StatusTrackerDescription.tsx
+│   ├── StatusTrackerStatus.tsx
+│   ├── StatusTrackerAlert.tsx
+│   └── StatusTrackerButton.tsx
+├── styles/
+└── index.ts
+```
+
+---
+
+## Slot-композиция
+
+```
+<StatusTracker type verticalAlign?>
+  <StatusTracker.Media>...</StatusTracker.Media>
+  <StatusTracker.Header>
+    <StatusTracker.Header.Title>...</Title>
+    <StatusTracker.Header.Sum>...</Sum>
+    <StatusTracker.Header.Description>...</Description>
+  </StatusTracker.Header>
+  <StatusTracker.Body>
+    <StatusTracker.Body.Status>...</Status>
+    <StatusTracker.Body.Alert>...</Alert>
+  </StatusTracker.Body>
+  <StatusTracker.Footer>
+    <StatusTracker.Footer.Button>...</Button>
+    <StatusTracker.Footer.Description>...</Description>
+  </StatusTracker.Footer>
+</StatusTracker>
+```
+
+Все slot'ы — `forwardRef<HTMLDivElement>` и прокидывают `HTMLAttributes<HTMLDivElement>`.
+
+---
+
+## Варианты и props
+
+### `IStatusTrackerProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `type` | `EStatusTrackerType` | — | Цветовой тип метки (DRAFT, WAITING, WARNING, REJECTED, APPROVED). |
+| `verticalAlign?` | `EStatusTrackerVerticalAlign` | `TOP` | Вертикальное выравнивание children: TOP/MIDDLE/BOTTOM. |
+| `...HTMLAttributes<HTMLDivElement>` | — | — | Стандартные атрибуты корня. |
+
+### `EStatusTrackerType`
+
+| Value | Поведение |
+|---|---|
+| `DRAFT` | Нейтральный draft-фон (`--StatusTracker-Draft_Background`). В `typeToClassNameMap` **не маппится** — цветная метка не рендерится (background остаётся базовым). |
+| `WAITING` | Жёлто-серый. |
+| `WARNING` | Оранжевый (только background). |
+| `REJECTED` | Красный. |
+| `APPROVED` | Зелёный. |
+
+### `EStatusTrackerVerticalAlign`
+
+| Value | Поведение |
+|---|---|
+| `TOP` | Default — выравнивание сверху (класс не применяется). |
+| `MIDDLE` | `styles.verticalAlignMiddle`. |
+| `BOTTOM` | `styles.verticalAlignBottom`. |
+
+---
+
+## Инварианты
+
+- **`forwardRef<HTMLDivElement>`** на корне и каждом slot'е — не убирать.
+- **Все slot'ы используют один CSS-класс `statusTrackerChild`** — они взаимозаменяемы на уровне layout, порядок в DOM определяет порядок рендера.
+- **Двухслойный background (`statusTrackerBackground` + `statusTrackerColor`)** — нужен для анимации перехода между типами (ключ `key={type}` на background-div ре-монтирует слой при смене type → анимация). При изменении анимации учти `key`.
+- **`DRAFT` не имеет цветовой модификации** в `typeToClassNameMap` — draft = базовый стиль wrapper'а, без цветной полосы.
+- **Композиция через `Object.assign`** — slot'ы выставляются на корневом forwardRef. Не менять форму `StatusTracker.Header.Title` и пр.
+- **Публичные enum'ы** (`EStatusTrackerType`, `EStatusTrackerVerticalAlign`) — изменение имён значений = breaking change.
+
+---
+
+## Accessibility
+
+- Без собственных ARIA-атрибутов — это визуальный layout.
+- Рекомендуется: передать `role="article"` или `role="region"` с `aria-label` на корневой `<div>`, если компонент используется как самостоятельная карточка; либо обернуть в `<li>` внутри списка документов.
+- Цвет статуса — не единственный канал передачи информации; `StatusTracker.Body.Status` обычно содержит текст с названием статуса.
+
+---
+
+## Связанные компоненты
+
+- `MarkerStatus` — инлайн-маркер статуса.
+- `Alert` — слот `StatusTrackerAlert` внутри.
+- `Card` — схожая layout-обёртка для произвольного контента.
+
+---
+
+## Stories
+
+Основные истории: `stories/StatusTracker/StatusTracker.stories.tsx`
+Примеры: `stories/StatusTracker/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Step.md

@@ -0,0 +1,121 @@
+---
+component: Step
+category: Navigation
+figma-node: ""
+figma-file: ""
+related: [Stepper, Tooltip]
+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: ""
+version: "1.0"
+---
+
+# Step
+
+## Назначение
+
+Визуальный «кружок с номером шага» для stepper-интерфейсов. Показывает статус
+(`default`/`active`/`done`/`warning`/`error`/`disabled`) через цветовой стейт.
+Опционально оборачивается в `Tooltip` (hover), если передан `children`.
+
+Используй когда: нужен отдельный индикатор шага (например, внутри кастомного
+stepper-а). Для готового пошагового виджета — `Stepper`.
+Не используй когда: нужен текстовый label шага — добавь его рядом, `Step`
+отрисовывает только номер в кружке.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Step/
+├── Step.tsx          # FC
+├── enums.ts          # EStepStatus, EStepPosition
+├── index.ts
+└── styles/Step.module.less
+```
+
+Также экспортируется утилита `calcPosition(stepCount, i)` — вычисляет
+`EStepPosition` (первый/последний/в середине) для списка шагов.
+
+---
+
+## Варианты и props
+
+### `IStepProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `step` | `number` | — | Число, отображаемое внутри кружка. |
+| `status` | `EStepStatus` | — | Цветовой стейт (см. ниже). |
+| `position?` | `EStepPosition` | `Default` | Влияет на `alignTip` опционального Tooltip'а. |
+| `children?` | `ReactNode` | — | Контент Tooltip'а. Если не передан — Tooltip не рендерится. |
+| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корневой `<div>`. |
+
+### `EStepStatus`
+
+`DEFAULT` / `DONE` / `ACTIVE` / `ERROR` / `WARNING` / `DISABLED`.
+
+Маппинг на CSS-классы 1-к-1 через `statusToClassNameMap`.
+
+### `EStepPosition`
+
+| Value | Поведение (alignTip) |
+|---|---|
+| `XFirst` | `ETooltipAlign.START` |
+| `Default` | `ETooltipAlign.CENTER` |
+| `XLast` | `ETooltipAlign.END` |
+
+`calcPosition(total, i)` возвращает `XFirst`/`XLast`/`Default` для удобства
+сборки списка шагов.
+
+---
+
+## Инварианты
+
+- **Рендер числа через `<Text size=B1 weight=SEMIBOLD>`** — фикс типографики для совпадения с дизайном.
+- **Tooltip рендерится только при наличии `children`** — без children компонент возвращает голый `<div>`.
+- **Tooltip: `toggleType="hover"`, `size=SM`** — не менять без согласования.
+- **Step — `FC`**, ref не пробрасывается (корневой div доступен только через обёртку Tooltip — по-разному в двух ветках рендера).
+- **Публичные enums** (`EStepStatus`, `EStepPosition`) + функция `calcPosition` — часть публичного API.
+
+---
+
+## Accessibility
+
+- Компонент — чисто визуальный (`<div>` с числом); сам по себе ARIA-ролью не наделён.
+- В составе stepper-а потребитель обязан обеспечить семантику (`role="list"` / `role="listitem"` / `aria-current="step"` на активном шаге). См. `Stepper-AI`.
+- Tooltip показывается только на hover — для пользователей клавиатуры текст подсказки недоступен. Если содержимое tooltip важно, дублируй его видимым лейблом рядом со Step.
+
+---
+
+## Связанные компоненты
+
+- `Stepper` — готовый виджет пошаговой навигации, использует Step внутри через `StepperStep` / `StepperStepIcon`.
+- `Tooltip` — оборачивает Step при наличии children.
+- `Typography.Text` — используется для рендера номера.
+
+---
+
+## Stories
+
+Отдельных stories нет (используется внутри stories `Stepper`).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Stepper.md

@@ -0,0 +1,163 @@
+---
+component: Stepper
+category: Navigation
+figma-node: ""
+figma-file: ""
+related: [Step, CarouselExtended, ButtonIcon]
+tokens: []
+stories: stories/Stepper/Stepper.stories.tsx
+version: "1.0"
+---
+
+# Stepper
+
+## Назначение
+
+Горизонтальный список шагов оформления с активным шагом, пройденными и
+непройденными. Обёрнут в `CarouselExtended` — при overflow добавляются
+кнопки-скроллеры и авто-прокрутка к выбранному шагу (с адаптивом по
+breakpoint `SM_MAX`: scroll-to-center vs scroll-to-edge).
+
+Используй когда: нужна готовая пошаговая навигация (например, оформление
+заявки). Для ручной сборки из шагов без карусели — `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/
+```
+
+---
+
+## Публичный API
+
+### `Stepper` — готовый виджет
+
+| 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 }
+```
+
+### `StepperExtended` — без карусели
+
+Для ручной сборки (напр. в вертикальном layout).
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size?` | `EStepperSize` | `SM` | Прокидывается в Context. |
+| `selectedStepId?` | `string` | — | Id активного шага. |
+| `onSelectStep` | `(id: string) => void` | — | Колбэк. |
+| `forwardedRef?` | `Ref<HTMLOListElement>` | — | Ref на `<ol role="tablist">`. |
+| `children` | `ReactNode` | — | `StepperExtended.Step` (`StepperStep`). |
+
+### `StepperStep` (`Stepper.Step` / `StepperExtended.Step`)
+
+| 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`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `EStepperStepIconType` | `FILLED` / `SUCCESS` / `ERROR` / `WARNING` / `WAIT`. |
+
+### `Stepper.Wrapper` / `StepperExtended.Wrapper`
+
+Простой `<div>` с `className="stepperWrapper"` — layout-контейнер для размещения Stepper в шапке/панели.
+
+---
+
+## Контекст (`StepperExtendedContext`)
+
+Хранит `selectedId`, `size`, `onSelectStep`. `StepperStep` — потребитель этого контекста.
+
+---
+
+## Логика выравнивания в Stepper
+
+При смене `selectedStepId`:
+1. `getBoundingClientRect` для carousel и шага.
+2. На узких экранах (`max-width: SM_MAX`) → scroll по центру выбранного шага.
+3. На широких → scroll к краю (left/right) с паддингом `32px` (`paddingLeft/Right`).
+
+Кнопки scroll'а рендерятся через `CarouselExtended.buttonPrev/Next` с `aria-label="Прокрутить назад" / "Прокрутить вперёд"`.
+
+---
+
+## Инварианты
+
+- **`<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-некомпатибельно по-строгому, но принятая конвенция проекта).
+
+---
+
+## 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`) — не полагаться на номер.
+
+---
+
+## Связанные компоненты
+
+- `Step` — отдельный кружок шага (не используется внутри Stepper).
+- `CarouselExtended` — обёртка в `Stepper`.
+- `ButtonIcon`, `IconWrapper` — UI.
+
+---
+
+## Stories
+
+Основные истории: `stories/Stepper/Stepper.stories.tsx`
+Примеры: `stories/Stepper/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |