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

package/bundle/components/SegmentedControl.md

@@ -1,10 +1,58 @@
 ---
 component: SegmentedControl
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [Tabs, Radio, Checkbox, ButtonBase, IconWrapper]
-tokens: []
+category: SegmentedControl
+related: [Tabs, TabsLine, IconWrapper]
+tokens:
+  - SegmentedControl.General_1_Background
+  - SegmentedControl.General_2_Background
+  - SegmentedControl.Secondary_1_Background
+  - SegmentedControl.Secondary_2_Background
+  - SegmentedControlSegment.BorderColor_Default
+  - SegmentedControlSegment.BorderColor_Focus
+  - SegmentedControlSegment.General_1_Background_Default
+  - SegmentedControlSegment.General_1_Background_Disabled
+  - SegmentedControlSegment.General_1_Background_Hover
+  - SegmentedControlSegment.General_1_Background_Selected_Default
+  - SegmentedControlSegment.General_1_Background_Selected_Disabled
+  - SegmentedControlSegment.General_1_Background_Selected_Hover
+  - SegmentedControlSegment.General_1_Color_Default
+  - SegmentedControlSegment.General_1_Color_Disabled
+  - SegmentedControlSegment.General_1_Color_Hover
+  - SegmentedControlSegment.General_1_Color_Selected_Default
+  - SegmentedControlSegment.General_1_Color_Selected_Disabled
+  - SegmentedControlSegment.General_1_Color_Selected_Hover
+  - SegmentedControlSegment.General_2_Background_Default
+  - SegmentedControlSegment.General_2_Background_Disabled
+  - SegmentedControlSegment.General_2_Background_Hover
+  - SegmentedControlSegment.General_2_Background_Selected_Default
+  - SegmentedControlSegment.General_2_Background_Selected_Disabled
+  - SegmentedControlSegment.General_2_Background_Selected_Hover
+  - SegmentedControlSegment.General_2_Color_Default
+  - SegmentedControlSegment.General_2_Color_Disabled
+  - SegmentedControlSegment.General_2_Color_Hover
+  - SegmentedControlSegment.General_2_Color_Selected_Default
+  - SegmentedControlSegment.General_2_Color_Selected_Disabled
+  - SegmentedControlSegment.General_2_Color_Selected_Hover
+  - SegmentedControlSegment.Secondary_1_Background_Default
+  - SegmentedControlSegment.Secondary_1_Background_Disabled
+  - SegmentedControlSegment.Secondary_1_Background_Hover
+  - SegmentedControlSegment.Secondary_1_Background_Selected_Default
+  - SegmentedControlSegment.Secondary_1_Background_Selected_Disabled
+  - SegmentedControlSegment.Secondary_1_Color_Default
+  - SegmentedControlSegment.Secondary_1_Color_Disabled
+  - SegmentedControlSegment.Secondary_1_Color_Hover
+  - SegmentedControlSegment.Secondary_1_Color_Selected_Default
+  - SegmentedControlSegment.Secondary_1_Color_Selected_Disabled
+  - SegmentedControlSegment.Secondary_2_Background_Default
+  - SegmentedControlSegment.Secondary_2_Background_Disabled
+  - SegmentedControlSegment.Secondary_2_Background_Hover
+  - SegmentedControlSegment.Secondary_2_Background_Selected_Default
+  - SegmentedControlSegment.Secondary_2_Background_Selected_Disabled
+  - SegmentedControlSegment.Secondary_2_Color_Default
+  - SegmentedControlSegment.Secondary_2_Color_Disabled
+  - SegmentedControlSegment.Secondary_2_Color_Hover
+  - SegmentedControlSegment.Secondary_2_Color_Selected_Default
+  - SegmentedControlSegment.Secondary_2_Color_Selected_Disabled
 stories: stories/SegmentedControl/SegmentedControl.stories.tsx
 version: "1.0"
 ---
@@ -13,223 +61,522 @@ version: "1.0"
 
 ## Назначение
 
-Группа «сегментов»-кнопок: выбор **одного** (`SINGLE`) или **нескольких**
-(`MULTIPLE`) вариантов из небольшого набора. Каждый сегмент —
-`<button aria-pressed>`. Похоже на iOS UISegmentedControl. Управление
-выбором — через `value` + `onSelect` снаружи; внутреннее состояние нет.
+Ряд сегментов-кнопок в общей подложке, из которых пользователь выбирает один (`type: SINGLE`)
+или несколько (`type: MULTIPLE`) вариантов. Компонент полностью управляемый: выбранное значение
+приходит в `value`, запрос на смену — через `onSelect`. Состав сегментов задаёт потребитель
+через `children` и составной субкомпонент `SegmentedControl.Segment`; сегменты делят ширину
+контрола поровну (`flex: 1 1 0`).
 
-Используй когда: 2–6 коротких опций (фильтры, переключатели view).
-Для много опций / длинных лейблов — `Tabs` или `SelectField`. Для
-визуально не-кнопочного выбора — `Radio` / `Checkbox` группы.
+Используй когда: вариантов немного (2–5), все они должны быть видны одновременно, и выбор
+переключает режим отображения или фильтр — «день / неделя / месяц», «список / плитка».
 
----
+Не используй когда:
 
-## Файловая структура
-
-```text
-src/components/SegmentedControl/
-├── SegmentedControl.tsx               # forwardRef + Object.assign({Segment})
-├── SegmentedControlSegment.tsx        # FC; ButtonBase + IconWrapper(active=selected)
-├── SegmentedControlContext.ts         # { type, value, disabled, onSegmentSelect }
-├── enums.ts                           # ESegmentedControlType / Theme / Size
-├── types.ts                           # discriminated union по type
-├── styles/SegmentedControl.module.less + SegmentedControlSegment.module.less
-├── index.ts                           # Barrel
-└── __tests__/
-```
+- Выбор переключает **страницы или панели контента** — нужна семантика табов
+  (`role="tablist"`, связка `aria-controls`, навигация стрелками). Возьми `Tabs`
+  или `TabsLine`: `SegmentedControl` этой семантики не даёт (см. Accessibility).
+- Вариантов много или они не влезают в строку — сегменты не переносятся и не скроллятся,
+  а сжимаются, обрезая подписи по `text-overflow: ellipsis`.
+- Нужен выбор из списка внутри формы с лейблом и статусом — возьми `SelectField`
+  или `RadioYGroup`.
+- Нужны сбрасываемые фильтры с крестиком и счётчиком — это `Chip` / `ChipGroup`.
 
 ---
 
-## Compound-структура
+## Варианты и props
 
-```tsx
-<SegmentedControl
-    type={ESegmentedControlType.SINGLE}
-    theme={ESegmentedControlTheme.GENERAL_1}
-    size={ESegmentedControlSize.MD}
-    value={selected}                         // string в SINGLE; string[] в MULTIPLE
-    onSelect={setSelected}
->
-    <SegmentedControl.Segment value="day">День</SegmentedControl.Segment>
-    <SegmentedControl.Segment value="week">Неделя</SegmentedControl.Segment>
-    <SegmentedControl.Segment value="month">Месяц</SegmentedControl.Segment>
-</SegmentedControl>
-```
+`TSegmentedControlProps` — discriminated union по `type`: `ISegmentedControlSingleProps`
+(`type: SINGLE`) и `ISegmentedControlMultipleProps` (`type: MULTIPLE`). Обе ветки расширяют
+`ISegmentedControlCommonProps`, а он — `Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect">`:
+неизвестные компоненту атрибуты уходят на корневой `<div>` через `...rest`.
 
----
+### Обязательные props
 
-## Варианты и props
-
-### SegmentedControl — `TSegmentedControlProps = ISegmentedControlSingleProps | ISegmentedControlMultipleProps`
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `ESegmentedControlType` | Дискриминант союза. `SINGLE` — выбран ровно один сегмент, `MULTIPLE` — любое подмножество. Меняет типы `value` и `onSelect`, а не внешний вид |
+| `value` | `string` при `SINGLE`, `string[]` при `MULTIPLE` | Выбранное значение. Сегмент считает себя выбранным, сравнивая свой `value` с этим (`===` при SINGLE, `includes` при MULTIPLE). Собственного состояния у компонента нет |
+| `onSelect` | `(value: string) => void` при `SINGLE`, `(value: string[]) => void` при `MULTIPLE` | Запрос на смену значения. При `SINGLE` получает `value` нажатого сегмента, при `MULTIPLE` — **новый массив** выбранных значений (компонент сам добавляет или убирает значение) |
+| `theme` | `ESegmentedControlTheme` | Визуальный стиль: пара цветов подложки и сегментов. Выбирается по фону страницы, см. ниже |
+| `size` | `ESegmentedControlSize` | Размер: высота сегмента, размер шрифта, радиусы и паддинги |
 
-#### Общее (`ISegmentedControlCommonProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect">`)
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `theme` | `ESegmentedControlTheme` | — (обязателен) | `GENERAL_1` / `GENERAL_2` / `SECONDARY_1` / `SECONDARY_2`. |
-| `size` | `ESegmentedControlSize` | — (обязателен) | `SM` / `MD` / `LG`. **Собственный enum**, не `EComponentSize`. |
-| `disabled?` | `boolean` | `false` | Дизейблит **все сегменты** (через context). |
-| `...HTMLAttributes` | — | — | На корневой `<div>`. |
+| `disabled` | `boolean` | `false` | Выключает **все** сегменты сразу: значение уходит в контекст, и каждый сегмент ставит `disabled` на свой `<button>`. Выбранный сегмент остаётся визуально выбранным |
+| `children` | `React.ReactNode` | — | Сегменты. Ожидается `SegmentedControl.Segment`; компонент не проверяет и не фильтрует состав `children` |
+
+### Props сегмента (`SegmentedControl.Segment`)
 
-#### SINGLE
+`ISegmentedControlSegmentProps extends IButtonBaseProps` (то есть
+`React.ButtonHTMLAttributes<HTMLButtonElement>`), поэтому сегмент принимает любые атрибуты
+кнопки. Собственный prop один:
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `type` | `ESegmentedControlType.SINGLE` | Discriminator. |
-| `value` | `string` | Текущий выбранный. |
-| `onSelect` | `(value: string) => void` | Передаётся **новый** value. |
+| `value` | `string` | Значение сегмента. Сравнивается со `value` контрола, чтобы определить выбранное состояние, и уходит в `onSelect` при нажатии |
 
-#### MULTIPLE
+Поведение остальных атрибутов кнопки:
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `type` | `ESegmentedControlType.MULTIPLE` | Discriminator. |
-| `value` | `string[]` | Массив выбранных. |
-| `onSelect` | `(value: string[]) => void` | Передаётся **полный новый массив** (не дельта). |
+- `disabled` — выключает **один** сегмент. Складывается с `disabled` контрола по `||`:
+  выключить сегмент можно, включить обратно вопреки контролу — нельзя.
+- `onClick` — вызывается **после** запроса на смену значения, с исходным событием. Не
+  отменяет выбор: `preventDefault()` на выбор не влияет.
+- `title` — если не передан, а `children` сегмента является строкой, эта строка
+  подставляется в `title` автоматически (подсказка для обрезанной подписи). Пустая строка
+  в `title` считается непереданной. Для нестрокового `children` (иконка) `title` не
+  выставляется — передавай его или `aria-label` сам.
+- `className` — мерджится через `clsx` с собственными классами, не затирая их.
 
-### SegmentedControl.Segment — `ISegmentedControlSegmentProps extends IButtonBaseProps`
+### Выбор темы
 
-| Prop | Тип | Описание |
+| Тема | Подложка | Когда |
 |---|---|---|
-| `value` | `string` | Идентификатор сегмента (соответствует `value` SegmentedControl'а). |
-| `disabled?` | от ButtonBase | Локальный disabled (мержится с групповым). |
-| `title?` | `string` | HTML-атрибут tooltip; если пусто и `children` — string, берётся children. |
-| `onClick?` | от ButtonBase | Дополнительный handler (вызывается **после** `onSegmentSelect`). |
-| `children` | `ReactNode` | Контент кнопки. |
-| `...IButtonBaseProps` | — | — |
-
-### Context — `ISegmentedControlContextType`
+| `GENERAL_1` | серая (`ColorNeutral.90`) | базовый вариант на белой странице |
+| `GENERAL_2` | белая (`ColorNeutral.100`) | на затенённой странице или внутри серого блока |
+| `SECONDARY_1` | серая | вторичный, менее акцентный выбранный сегмент |
+| `SECONDARY_2` | белая | вторичный вариант на затенённой странице |
 
-```ts
-{ type, value, disabled, onSegmentSelect: ({ selected, value }) => void }
-```
+Пара `GENERAL` / `SECONDARY` отличается только цветами выбранного сегмента, геометрия
+одинаковая.
 
-### Enums
+### Размер и тема независимы
 
-- `ESegmentedControlType.SINGLE | MULTIPLE`
-- `ESegmentedControlTheme.GENERAL_1 | GENERAL_2 | SECONDARY_1 | SECONDARY_2`
-- `ESegmentedControlSize.SM | MD | LG`
+Оси не пересекаются: в `SegmentedControlSegment.module.less` классы размера (`.sm`, `.md`,
+`.lg`) задают только геометрию (высота 20 / 32 / 40px, размер шрифта, радиус), классы темы —
+только цвета. Любая комбинация допустима, поэтому stories показывают оси по отдельности,
+а матрицу целиком не снимают.
 
 ---
 
-## Ключевые особенности реализации
+## Дизайн-токены
+
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию —
+`src/components/DesignTokens/components/SegmentedControl.ts` и
+`src/components/DesignTokens/components/SegmentedControlSegment.ts`.
 
-### Discriminated union по `type`
+Две группы: `SegmentedControl` — только фон подложки (по одному токену на тему),
+`SegmentedControlSegment` — цвет и фон сегмента в разрезе «тема × выбранность × состояние»
+плюс два токена рамки:
 
-```ts
-type TSegmentedControlProps = ISegmentedControlSingleProps | ISegmentedControlMultipleProps;
+```text
+SegmentedControl.{Theme}_Background
+SegmentedControlSegment.{Theme}_Color_[Selected_]{Default|Hover|Disabled}
+SegmentedControlSegment.{Theme}_Background_[Selected_]{Default|Hover|Disabled}
+SegmentedControlSegment.BorderColor_Default
+SegmentedControlSegment.BorderColor_Focus
 ```
 
-- TS гарантирует: `value: string` ↔ `type: SINGLE`; `value: string[]` ↔ `type: MULTIPLE`. `onSelect` сигнатура соответственно.
-- Discriminator обязателен на потребителе.
+Рамка у сегмента есть всегда (`1px solid BorderColor_Default`) — она резервирует место,
+чтобы фокусная рамка не сдвигала вёрстку. При `:focus-visible` меняется только её цвет
+на `BorderColor_Focus`.
 
-### `handleSegmentSelect` — превращение `(value, selected)` в новый список
+**Известное расхождение (не исправлено осознанно).** В группе `SegmentedControlSegment`
+объявлены, но не используются в стилях четыре токена: `Secondary_1_Color_Selected_Hover`,
+`Secondary_1_Background_Selected_Hover`, `Secondary_2_Color_Selected_Hover`,
+`Secondary_2_Background_Selected_Hover`. У тем `SECONDARY_*` в LESS нет правила
+`&.selected:hover`, поэтому наведение на выбранный сегмент этих тем ничего не меняет,
+хотя значения токенов отличаются от `Selected_Default`. Это pre-existing поведение;
+добавление правила — визуальное изменение, его нужно согласовывать с дизайном и
+перегенерировать baseline-скриншоты.
 
-```ts
-case SINGLE: if (selected) onSelect(newValue);    // selected всегда true в Segment.handleClick для SINGLE
-case MULTIPLE:
-    if (selected) onSelect([...value, newValue])
-    else          onSelect(value.filter(v => v !== newValue));
-```
+---
 
-- В SINGLE: повторный клик **не** снимает выбор (`selected: true` всегда отправляется).
-- В MULTIPLE: клик инвертирует — добавление или удаление из массива.
+## Инварианты
 
-### `Segment.handleClick`
+- `forwardRef<HTMLDivElement>` на `SegmentedControl` — не убирать. Ref указывает на корневую
+  подложку (`<div class="segmentedControl">`).
+- `forwardRef<HTMLButtonElement>` на `SegmentedControlSegment` — не убирать. Ref указывает на
+  `<button>`, который рендерит `ButtonBase`, а не на обёртку `IconWrapper`.
+- Составной API `SegmentedControl.Segment` собирается через `Object.assign(forwardRef(...), { Segment })`.
+  `SegmentedControlSegment` при этом остаётся и самостоятельным barrel-экспортом — оба пути
+  импорта публичные, сохранять нужно оба.
+- Барел `src/components/SegmentedControl/index.ts` экспортирует `enums`, `types`,
+  `SegmentedControlSegment` и `SegmentedControl`. `SegmentedControlContext`,
+  `ISegmentedControlContextType` и `utils.ts` из барела **не** экспортируются — это
+  внутренний слой, менять его можно свободно.
+- `displayName` — `"SegmentedControl"` и `"SegmentedControlSegment"`. Не менять.
+- Значения `ESegmentedControlTheme` (`general_1` / `general_2` / `secondary_1` / `secondary_2`)
+  и `ESegmentedControlType` (`single` / `multiple`) — часть публичного API. Значения темы
+  дополнительно связаны с именами CSS-классов (`.general1` и т.д. — через
+  `themeToClassNameMap`) и с именами токенов `{Theme}_*`.
+- **Значения `ESegmentedControlSize` обязаны совпадать с `EComponentSize`** (`sm` / `md` / `lg`).
+  Классы размера берутся из `createSizeToClassNameMap(styles)`, а он типизирован как
+  `Record<EComponentSize, string>` — индексация `sizeToClassNameMap[size]` работает только
+  потому, что строковые значения обоих enum совпадают. Добавление размера в
+  `ESegmentedControlSize`, которого нет в `EComponentSize`, даст `undefined` вместо класса
+  без ошибки типов.
+- Оба файла стилей лежат в `src/components/SegmentedControl/styles/`, и это важно:
+  `generateScopedName` (`scripts/generate-scoped-name.ts`) хеширует класс по **имени папки
+  компонента** + имени класса + версии. Поэтому `.general1` и `.sm` из
+  `SegmentedControl.module.less` и селекторы `.general1 &` / `.sm &` из
+  `SegmentedControlSegment.module.less` получают одинаковый хеш и сцепляются. Перенос
+  одного из файлов в другую папку компонента молча сломает стилизацию сегментов.
+- При `type: SINGLE` нажатие на уже выбранный сегмент **всё равно вызывает** `onSelect` с его
+  значением (сегмент сообщает `selected: true`). Это наблюдаемое поведение, зафиксировано
+  тестом; отмена выбора при SINGLE не поддерживается.
+- При `type: MULTIPLE` компонент не хранит порядок выбора: новое значение добавляется в
+  конец массива (`[...value, newValue]`), удаление сохраняет исходный порядок остальных.
+- `[...value]` в обработчике MULTIPLE — не избыточный спред, а сужение для TS: `value`
+  внутри деструктурированного союза имеет тип `string | string[]`, и `.filter` у строки нет.
+- Класс `content` на внутреннем `<span>` сегмента отвечает за обрезку подписи
+  (`overflow: hidden`, `text-overflow: ellipsis`) — не удалять и не переименовывать.
 
-```ts
-case SINGLE: onSegmentSelect({ value, selected: true });
-case MULTIPLE: onSegmentSelect({ value, selected: !selected });
-```
+---
 
-### `IconWrapper displayContents disabled active={selected}`
+## Accessibility
 
-```tsx
-<IconWrapper displayContents disabled={...} active={selected}>
-    <ButtonBase aria-pressed={selected} ...>
-        <span className={styles.content}>{children}</span>
-    </ButtonBase>
-</IconWrapper>
-```
+- Каждый сегмент — нативная `<button type="button">` (через `ButtonBase`), поэтому фокус,
+  `Enter` / `Space` и `disabled` работают нативно. Собственных обработчиков клавиатуры
+  компонент не добавляет.
+- Выбранность кодируется `aria-pressed` на каждой кнопке: `true` у выбранных, `false`
+  у остальных. Это модель «группа кнопок-переключателей», а не табов и не радиогруппы.
+- **Корневой `<div>` роли не имеет.** Группа для скринридера не объявлена: ни
+  `role="group"`, ни `role="tablist"`, ни `aria-label` компонент не выставляет. Если группу
+  нужно озвучить, передай атрибуты сам — они уйдут на корневой `<div>` через `...rest`:
+  `<SegmentedControl role="group" aria-label="Период" ...>`. Роль обязательна вместе
+  с именем: `<div>` без роли получает роль `generic`, которой
+  [HTML-AAM](https://www.w3.org/TR/html-aria/) запрещает доступное имя.
+- Навигации стрелками между сегментами нет — обход идёт `Tab`'ом, каждый сегмент
+  отдельная остановка. Если нужна семантика табов с одной остановкой на группу,
+  это `Tabs` / `TabsLine`, а не `SegmentedControl`.
+- Фокус виден только с клавиатуры: цвет рамки меняется по `:focus-visible`.
+- Сегмент с одной иконкой доступного имени не получает: `title` подставляется из `children`
+  только для строкового содержимого. Для иконки передавай `aria-label` (или `title`) сам —
+  компонент не хардкодит текст, библиотека мультиязычная.
+- `disabled` (и на контроле, и на сегменте) ставится нативным атрибутом, поэтому выключенные
+  сегменты выпадают из порядка фокуса и не озвучиваются как активируемые.
 
-- **`displayContents`** — IconWrapper не вводит свой DOM-узел.
-- **`active`/`disabled`** — публичные классы из `@sberbusiness/icons-next`, влияющие на цвет иконок внутри `children`.
-- `aria-pressed` — корректная семантика toggle-button (toggle для MULTIPLE; для SINGLE — тоже технически верно).
+---
 
-### Default-значения context
+## Связанные компоненты
 
-```ts
-{ type: SINGLE, value: "", disabled: false, onSegmentSelect: noop }
-```
+- `Tabs` — альтернатива, когда выбор переключает панели контента: даёт `role="tablist"`,
+  навигацию стрелками и работу с непоместившимися табами. Их легко спутать, потому что
+  `SegmentedControl` часто используют как визуальный переключатель вида.
+- `TabsLine` — альтернатива для табов-подчёркиваний в шапке раздела. Тот же критерий
+  выбора, что и у `Tabs`: нужна ли семантика табов.
+- `IconWrapper` — рендерится внутри каждого сегмента (`displayContents`) и по классам
+  `active` / `disabled` управляет цветом иконки из `@sberbusiness/icons-next`. Поэтому
+  сегмент с иконкой перекрашивается вместе с выбранным состоянием; `paletteIndex` в примерах
+  задаёт базовый цвет.
+- `ButtonBase` — внутренняя кнопка, на которой построен сегмент (в barrel библиотеки не
+  экспортируется). Даёт `type="button"`, `data-tx` и проброс ref.
 
-- При использовании `Segment` вне `SegmentedControl` — `value === ""`, ничего не выбрано, клик noop. Безопасно.
+---
 
-### `getTitle`
+## Stories
 
-- Если `title` передан — использует его.
-- Иначе — если `children: string` — берёт children (для tooltip'а на overflow-text).
-- Иначе — undefined.
+Основные истории: `stories/SegmentedControl/SegmentedControl.stories.tsx`
+Файлы примеров: `stories/SegmentedControl/examples/`
 
-### Темы — 4 варианта
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `type`, `theme`, `size`, `disabled` |
+| `Default` | `Default.tsx` | Минимальный контрол: `SINGLE`, `GENERAL_1`, `LG`, пять сегментов |
+| `Types` | `Types.tsx` | `SINGLE` и `MULTIPLE` рядом; у MULTIPLE выбраны два сегмента |
+| `Themes` | `Themes.tsx` | Все четыре значения `ESegmentedControlTheme` |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Disabled` | `Disabled.tsx` | `disabled` на всём контроле, выбранный сегмент сохраняет вид |
+| `Example` | `Example.tsx` | Production-like: три сегмента только с иконками в контейнере 144px |
+| `VisualTests` | `VisualTests.tsx` | Краевые состояния для скриншотов: `:focus-visible` (открывается `play`), выключенные отдельные сегменты (включая выбранный), обрезка длинной подписи, сегменты-иконки, MULTIPLE без выбора и с полным выбором |
+
+Из скриншот-тестов исключены (`testRunner: { skip: true }`) `Playground`, `Default` и
+`Example`: `Default` визуально дублирует блок SINGLE в `Types`, а сегменты только с иконкой
+покрыты отдельным блоком в `VisualTests` (там они сняты в теме `SECONDARY_1`, тогда как
+`Example` использует `GENERAL_1`).
+
+Story ID участвуют в именах baseline-скриншотов (`segmentedcontrol--themes--xs.png` и т.п.),
+поэтому переименование story требует перегенерации baseline и удаления осиротевших файлов.
 
-- `GENERAL_1`, `GENERAL_2`, `SECONDARY_1`, `SECONDARY_2`. Проверять в LESS — отличия в фоне/border/цвете.
+---
 
-### Sizes — собственный enum
+## История изменений
 
-- `ESegmentedControlSize.SM/MD/LG` — **не** `EComponentSize`. Расхождение с типичной практикой (исторически).
+| Дата | Изменение |
+|---|---|
+| 2026-09-30 | Создан документ. AI-рефакторинг: `SegmentedControlSegment` переведён с `React.FC` на `forwardRef<HTMLButtonElement>`, чистые хелперы вынесены в `utils.ts` (`isSegmentSelected`, `getSegmentTitle`), JSDoc на props и полях контекста, внутренние импорты приведены к относительным. Добавлены unit-тесты (`__tests__/SegmentedControlSegment.test.tsx`, `__tests__/utils.test.tsx`, классы тем и размеров в `__tests__/SegmentedControl.test.tsx`). Stories перенесены в `stories/SegmentedControl/` по modern pattern, добавлена story `VisualTests`. |
 
 ---
 
-## Инварианты
+## Примеры использования
 
-- **`type` обязателен**, discriminator union'а. Меняет тип `value`/`onSelect`.
-- **SINGLE: повторный клик не снимает выбор** (нет «снять всё»). Для optional-single — потребитель сам реализует.
-- **MULTIPLE: `onSelect` получает полный массив**, не дельту.
-- **`theme` и `size` обязательны** (нет default'ов).
-- **`size` — собственный enum** `ESegmentedControlSize`, не `EComponentSize`.
-- **`disabled` через context** — групповой; локальный `Segment.disabled` мержится.
-- **`aria-pressed={selected}`** — публичный a11y-контракт.
-- **`SegmentedControlContext` default — `{ SINGLE, "", false, noop }`** — Segment безопасен вне группы.
-- **ForwardRef** на корне SegmentedControl, **`FC`** на Segment.
-- **`IconWrapper displayContents`** — обязателен для не-DOM обёртки.
-- **`Segment.onClick` вызывается после `onSegmentSelect`** — порядок может быть важен.
+### Default
 
----
+`stories/SegmentedControl/examples/Default.tsx`
 
-## Accessibility
+```tsx
+import React, { useState } from "react";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState("segment_3");
+
+    return (
+        <SegmentedControl
+            type={ESegmentedControlType.SINGLE}
+            theme={ESegmentedControlTheme.GENERAL_1}
+            size={ESegmentedControlSize.LG}
+            value={value}
+            onSelect={setValue}
+        >
+            <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+        </SegmentedControl>
+    );
+};
+```
 
-- `<button aria-pressed>` — корректная семантика toggle (особенно для MULTIPLE).
-- **Нет `role="group"` / `aria-label`** на контейнере — потребитель должен передать `aria-label`/`aria-labelledby` через `...rest`.
-- **Tab-навигация** — каждый Segment в фокусе по Tab. Для radio-like UX (стрелки) семантика отсутствует — это `<button>`, не `<input type="radio">`.
-- `disabled` через `<button disabled>` — корректно.
-- `title` атрибут — даёт tooltip; для длинных лейблов с overflow — UX полезно.
+### Types
 
----
+`stories/SegmentedControl/examples/Types.tsx`
 
-## Дизайн-токены
+```tsx
+import React, { useState } from "react";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+export const Types = () => {
+    const [singleValue, setSingleValue] = useState("segment_3");
+    const [multipleValue, setMultipleValue] = useState(["segment_2", "segment_4"]);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>SINGLE</div>
+                <SegmentedControl
+                    type={ESegmentedControlType.SINGLE}
+                    theme={ESegmentedControlTheme.GENERAL_1}
+                    size={ESegmentedControlSize.LG}
+                    value={singleValue}
+                    onSelect={setSingleValue}
+                >
+                    <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+                </SegmentedControl>
+            </div>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>MULTIPLE</div>
+                <SegmentedControl
+                    type={ESegmentedControlType.MULTIPLE}
+                    theme={ESegmentedControlTheme.GENERAL_1}
+                    size={ESegmentedControlSize.LG}
+                    value={multipleValue}
+                    onSelect={setMultipleValue}
+                >
+                    <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+                    <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+                </SegmentedControl>
+            </div>
+        </div>
+    );
+};
+```
 
-Нет собственных — наследуются от `Button`/тем (`general_1`, `secondary_1`, ...). Token-структура — в `styles/`.
+### Themes
 
----
+`stories/SegmentedControl/examples/Themes.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+interface IThemeItemProps {
+    theme: ESegmentedControlTheme;
+}
+
+const ThemeItem = ({ theme }: IThemeItemProps) => {
+    const [value, setValue] = useState("segment_3");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{theme.toUpperCase()}</div>
+            <SegmentedControl
+                type={ESegmentedControlType.SINGLE}
+                theme={theme}
+                size={ESegmentedControlSize.LG}
+                value={value}
+                onSelect={setValue}
+            >
+                <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+            </SegmentedControl>
+        </div>
+    );
+};
+
+const THEMES = Object.values(ESegmentedControlTheme);
+
+export const Themes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {THEMES.map((theme) => (
+            <ThemeItem key={theme} theme={theme} />
+        ))}
+    </div>
+);
+```
 
-- `Tabs` — для большего количества опций / длинных лейблов.
-- `Radio` / `Checkbox` (+ `RadioYGroup` / аналог) — альтернатива для form-input семантики.
-- `ButtonBase` — нижележащий primitive.
-- `IconWrapper` — управление цветом иконок внутри (active/disabled).
+### Sizes
 
----
+`stories/SegmentedControl/examples/Sizes.tsx`
 
-## Stories
+```tsx
+import React, { useState } from "react";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+interface ISizeItemProps {
+    size: ESegmentedControlSize;
+}
+
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState("segment_3");
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+            <SegmentedControl
+                type={ESegmentedControlType.SINGLE}
+                theme={ESegmentedControlTheme.GENERAL_1}
+                size={size}
+                value={value}
+                onSelect={setValue}
+            >
+                <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+                <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+            </SegmentedControl>
+        </div>
+    );
+};
+
+const SIZES = Object.values(ESegmentedControlSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
 
-`stories/SegmentedControl/SegmentedControl.stories.tsx`
-Примеры: `stories/SegmentedControl/examples/`
+### Disabled
 
----
+`stories/SegmentedControl/examples/Disabled.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+export const Disabled = () => {
+    const [value, setValue] = useState("segment_3");
+
+    return (
+        <SegmentedControl
+            type={ESegmentedControlType.SINGLE}
+            theme={ESegmentedControlTheme.GENERAL_1}
+            size={ESegmentedControlSize.LG}
+            value={value}
+            onSelect={setValue}
+            disabled
+        >
+            <SegmentedControl.Segment value="segment_1">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_2">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_3">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_4">Segment</SegmentedControl.Segment>
+            <SegmentedControl.Segment value="segment_5">Segment</SegmentedControl.Segment>
+        </SegmentedControl>
+    );
+};
+```
+
+### Example
+
+`stories/SegmentedControl/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { DefaulticonStrokePrdIcon20 } from "@sberbusiness/icons-next";
+import {
+    SegmentedControl,
+    ESegmentedControlSize,
+    ESegmentedControlTheme,
+    ESegmentedControlType,
+} from "@sberbusiness/triplex-next";
+
+/** Индекс палитры иконки: выбранный сегмент рисует иконку на контрастном фоне. */
+const SELECTED_ICON_PALETTE_INDEX = 10;
+const ICON_PALETTE_INDEX = 5;
+
+const SEGMENTS = [
+    { value: "segment_1", label: "segment 1" },
+    { value: "segment_2", label: "segment 2" },
+    { value: "segment_3", label: "segment 3" },
+];
+
+export const Example = () => {
+    const [value, setValue] = useState("segment_2");
+
+    return (
+        <div style={{ width: 144 }}>
+            <SegmentedControl
+                type={ESegmentedControlType.SINGLE}
+                theme={ESegmentedControlTheme.GENERAL_1}
+                size={ESegmentedControlSize.LG}
+                value={value}
+                onSelect={setValue}
+            >
+                {SEGMENTS.map((segment) => (
+                    <SegmentedControl.Segment key={segment.value} value={segment.value} aria-label={segment.label}>
+                        <DefaulticonStrokePrdIcon20
+                            paletteIndex={value === segment.value ? SELECTED_ICON_PALETTE_INDEX : ICON_PALETTE_INDEX}
+                            style={{ display: "block" }}
+                        />
+                    </SegmentedControl.Segment>
+                ))}
+            </SegmentedControl>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |