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

package/bundle/components/Radio.md

@@ -1,10 +1,21 @@
 ---
 component: Radio
-category: Form Controls
-figma-node: ""
-figma-file: ""
-related: [Checkbox, RadioYGroup, RadioXGroup, Typography, FormField]
-tokens: []
+category: Inputs
+related: [RadioXGroup, RadioYGroup, Text]
+tokens:
+  - Radio.Background_Default
+  - Radio.BorderColor_Default
+  - Radio.Dot_Default
+  - Radio.Background_Checked_Default
+  - Radio.BorderColor_Checked_Default
+  - Radio.Background_Hover
+  - Radio.Background_Disabled
+  - Radio.BorderColor_Disabled
+  - Radio.Background_Checked_Disabled
+  - Radio.BorderColor_Checked_Disabled
+  - Radio.Dot_Disabled
+  - Radio.BorderColor_Focused
+  - Radio.Background_Checked_Hover
 stories: stories/Radio/Radio.stories.tsx
 version: "1.0"
 ---
@@ -13,162 +24,274 @@ version: "1.0"
 
 ## Назначение
 
-Радио-кнопка: нативный `<input type="radio">` с visually-hidden default'ом
-+ кастомная иконка (`<span>` со стилями) + опциональный текст-описание
-(через `Text`). Сгруппировать кнопки можно горизонтально (`RadioXGroup`)
-или вертикально (`RadioYGroup`) — оба контейнера дают `role="radiogroup"`.
+Радио-кнопка с необязательной текстовой подписью в обёртке `<label>`. Выбор,
+события и участие в форме обеспечивает нативный `<input type="radio">`;
+компонент задаёт размеры и оформление выбранного, недоступного, наведённого
+и сфокусированного состояния.
 
-Используй когда: выбор одного варианта из небольшого набора (если
-больше ~5 — `SelectField`). Для multi-choice — `Checkbox` + `RadioYGroup`-
-аналог.
+Используй когда: пользователь должен выбрать один вариант из нескольких.
+Связывай варианты общим `name` и задавай каждому собственный `value`.
 
----
-
-## Файловая структура
-
-```text
-src/components/Radio/
-├── Radio.tsx           # forwardRef<HTMLInputElement>; <label> + <input> + <span> + <Text>
-├── RadioXGroup.tsx     # FC; <div role="radiogroup"> + indent (12-32)
-├── RadioYGroup.tsx     # FC; <div role="radiogroup">
-├── styles/Radio.module.less + RadioXGroup + RadioYGroup
-├── index.ts            # Barrel
-└── __tests__/
-```
+Не используй когда: требуется независимый выбор нескольких значений — нужен
+`Checkbox`; для длинного списка вариантов удобнее `SelectField`.
 
 ---
 
 ## Варианты и props
 
-### Radio — `IRadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size">`
+### Обязательные props
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `size` | `EComponentSize` | `MD` | Размер кнопки + связанный размер `Text`. |
-| `labelAttributes?` | `LabelHTMLAttributes<HTMLLabelElement>` | — | Атрибуты на `<label>` (className мержится). |
-| `children?` | `ReactNode` | — | Текст-описание справа от радио. Если пуст — текст не рендерится, label получает класс без `nonempty`. |
-| `disabled?` | `boolean` | — | Прокидывается в `<input>` + добавляет класс `disabled` на label. |
-| `...inputAttributes` | `InputHTMLAttributes<HTMLInputElement>` | — | Все остальные `<input>`-атрибуты (`name`, `value`, `checked`, `onChange`, ...). |
+Обязательных custom-props нет. Для доступного имени передавай видимую подпись
+через `children` либо `aria-label` / `aria-labelledby` для самого input.
 
-- **`type` исключён** — всегда `"radio"`.
-- **`size` исключён из `InputHTMLAttributes`** — наш собственный enum, не нативный.
-- ForwardRef → `<input>`.
+### Опциональные props
 
-### Маппинг `size` → текст:
+| Prop | По умолчанию | Описание |
+|---|---|---|
+| `size` | `EComponentSize.MD` | `SM` / `MD` / `LG`; диаметр индикатора 16 / 24 / 28px, текст `B4` / `B3` / `B2` соответственно |
+| `children` | — | Содержимое подписи, отображаемое через `Text` с `tag="div"` |
+| `labelAttributes` | — | HTML-атрибуты корневого `<label>`; его `className` объединяется с внутренними классами label |
+| `className` | — | Дополнительный класс внутреннего `<input>`, а не корневого label |
+| `checked` | — | Управляемый выбор; обновляй его в ответ на `onChange` либо передавай `readOnly` для фиксированного состояния |
+| `defaultChecked` | — | Начальный выбор в неуправляемом режиме |
+| `disabled` | `false` | Нативно блокирует выбор, исключает из Tab-навигации и меняет оформление; выбранность сохраняется |
+| `name`, `value` | — | Общий `name` связывает варианты в нативную группу, `value` определяет значение в событии и форме |
+| `onChange` | — | Нативный React change-event; выбранный вариант доступен через `event.target.value` и `event.target.checked` |
+| Остальные input-атрибуты | — | `id`, `required`, `aria-*`, обработчики и другие стандартные атрибуты уходят на input; `type` и HTML `size` исключены из API |
+
+### Ограничения использования
+
+- Собственного состояния выбора нет. Не смешивай `checked` и `defaultChecked`.
+  Повторное нажатие на выбранный вариант не снимает выбор и не вызывает новый
+  `onChange`.
+- `RadioXGroup` и `RadioYGroup` задают компоновку и роль группы, но не управляют
+  выбором. Даже внутри них общий `name` необходимо передать самим Radio.
+- Класс `nonempty` и обёртка `Text` зависят от truthiness `children`. Без подписи
+  дополнительный отступ не применяется. Существующая особенность: числовой `0`
+  выводится React как текст без `Text` и класса `nonempty`; для числовой подписи
+  передавай строку (`String(value)`).
+- Темизация задаётся через `ThemeProvider`, отдельного prop `theme` у Radio нет.
 
-| `size` | `Text size` |
-|---|---|
-| `LG` | `B2` |
-| `MD` | `B3` |
-| `SM` | `B4` |
+---
 
-### RadioXGroup — `IRadioXGroupProps extends HTMLAttributes<HTMLDivElement>`
+## Дизайн-токены
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `indent` | `TIndentSize` (`12 \| 16 \| 20 \| 24 \| 28 \| 32`) | `12` | Горизонтальный gap (в `px`, через CSS-классы `indent-{N}`). |
-| `...HTMLAttributes` | — | — | На `<div>`. `role="radiogroup"`. |
+Переопределяются через `ThemeProvider` (prop `tokens`) — см.
+`src/components/ThemeProvider/ThemeProvider-ai.md` → «Как переопределять токены».
+Значения по умолчанию — `src/components/DesignTokens/components/Radio.ts`.
 
-### RadioYGroup — `IRadioYGroupProps extends HTMLAttributes<HTMLDivElement>`
+```text
+Radio.Background_Default
+Radio.BorderColor_Default
+Radio.Dot_Default
+Radio.Background_Checked_Default
+Radio.BorderColor_Checked_Default
+Radio.Background_Hover
+Radio.Background_Disabled
+Radio.BorderColor_Disabled
+Radio.Background_Checked_Disabled
+Radio.BorderColor_Checked_Disabled
+Radio.Dot_Disabled
+Radio.BorderColor_Focused
+Radio.Background_Checked_Hover
+```
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `...HTMLAttributes` | — | На `<div>`. `role="radiogroup"`. Gap — фиксированный (см. CSS). |
+Несмотря на имя `BorderColor`, соответствующие токены содержат готовое значение
+`box-shadow`, а не отдельный цвет. `BorderColor_Focused` оформляет клавиатурный
+фокус через `:focus-visible`.
 
 ---
 
-## Ключевые особенности реализации
-
-### Native `<input>` + кастомный `<span>` (visually-hidden pattern)
+## Инварианты
 
-```tsx
-<label>
-    <input type="radio" className={styles.radio} ... />
-    <span className={styles.radioIcon} />
-    {children && <Text>{children}</Text>}
-</label>
-```
+- Сохраняй `forwardRef<HTMLInputElement>` и `displayName = "Radio"`.
+  Ref указывает на input, корневой DOM-элемент остаётся label.
+- DOM-порядок `label` → `input` + соседний `span.radioIcon` + необязательный
+  `Text` важен: выбранность, недоступность и фокус индикатора стилизуются
+  соседними CSS-селекторами.
+- `className` относится к input, `labelAttributes.className` — к label.
+  Не меняй распределение атрибутов между ними.
+- Сохраняй публичные `IRadioProps`, значения `EComponentSize`, barrel-экспорты
+  и существующие имена классов / дизайн-токенов.
+- Классы размеров стоят на input и label. Не удаляй их при рефакторинге:
+  вложенные элементы и подпись зависят от размера.
+- Сохраняй нативную семантику `name`, `checked`, `defaultChecked`, `disabled`
+  и событий; дополнительных обработчиков клавиатуры в компоненте нет.
 
-- `<input>` скрыт визуально (`appearance: none` / `opacity: 0` в стилях), но **остаётся в фокусной последовательности** и работает как нативный radio.
-- `<span class="radioIcon">` — визуальная рамка/точка, реагирует на состояния `:checked`, `:disabled`, `:focus-visible` через CSS-селекторы вида `input:checked + .radioIcon`.
+---
 
-### Текст-описание — через `<Text size>`
+## Accessibility
 
-- Маппинг по `size`: SM→B4, MD→B3, LG→B2.
-- Если `children` пуст — `<Text>` не рендерится (избегаем лишнего span).
-- `nonempty` класс на label — позволяет CSS отличать "только иконка" от "иконка + текст" (например, для горизонтального gap'а).
+- Роль `radio` и состояние выбранности обеспечивает нативный input. Вложенный
+  label связывает видимую подпись с input и делает её кликабельной.
+- Без видимой подписи передавай `aria-label` либо корректную ссылку
+  `aria-labelledby` на input; атрибуты label его доступное имя не заменяют.
+- Tab, Space и навигацию внутри нативной группы обеспечивает браузер.
+  Фокус индикатора показывается через `:focus-visible`.
+- Для названия группы используй `fieldset` с `legend` либо именованный
+  контейнер `role="radiogroup"`. Групповая роль сама по себе не заменяет
+  общий `name` у Radio.
+- `disabled` применяется к самому input. Компонент не хардкодит текст
+  `aria-label` / `title`: локализацию задаёт потребитель.
 
-### `labelAttributes` — мерж className
+---
 
-```ts
-labelAttributes?.className → clsx(..., labelAttributes?.className)
-```
+## Связанные компоненты
 
-- Стандартный паттерн.
+- `RadioXGroup` — горизонтальная компоновка Radio с настраиваемым отступом
+  и ролью `radiogroup`; см. `RadioXGroup-ai.md`.
+- `RadioYGroup` — вертикальная компоновка Radio с ролью `radiogroup`;
+  см. `RadioYGroup-ai.md`.
+- `Text` — рендерится внутри Radio для подписи. Его размер зависит от `size`
+  Radio: `SM` → `B4`, `MD` → `B3`, `LG` → `B2`.
 
-### Группы — `role="radiogroup"`, **без `value`**
+---
 
-- `RadioXGroup` / `RadioYGroup` — **тонкие layout-обёртки**. Не управляют выбранным значением, не вешают `name` на дочерние radio. Контракт name/value/onChange — на потребителе.
-- Это отличается от ряда библиотек (`MUI.RadioGroup` управляет состоянием) — здесь группа только семантическая + layout.
+## Stories
 
-### `RadioXGroup.indent` — фиксированный набор
+Основные истории: `stories/Radio/Radio.stories.tsx`
+Файлы примеров: `stories/Radio/examples/`
 
-- `TIndentSize = 12 | 16 | 20 | 24 | 28 | 32` (px). Добавляет класс `indent-{N}`.
-- Default `12px`.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Controls для подписи, размера, выбранности и disabled; выбор синхронизируется с Controls |
+| `Default` | `Default.tsx` | Минимальная радио-кнопка с размером MD |
+| `Sizes` | `Sizes.tsx` | Подписанные размеры SM / MD / LG |
+| `States` | `States.tsx` | Controlled-выбор через `checked` и `onChange` с общим `name`; выбранный и невыбранный disabled-варианты |
+| `WithoutLabel` | `WithoutLabel.tsx` | Все размеры и комбинации checked / disabled без видимой подписи, с aria-label |
+| `VisualTests` | `VisualTests.tsx` | Клавиатурный фокус через play, hover невыбранного варианта, checked / disabled всех размеров и длинная подпись |
+| `VisualTestsCheckedHover` | — | Тот же renderer, hover выбранного варианта |
+
+Примеры компоновки Radio в группах — в stories `RadioXGroup` и `RadioYGroup`.
+
+Visual-истории скрыты из autodocs и sidebar тегами `!autodocs` / `!dev`, но снимаются
+test-runner'ом на viewport xs / xl. Из скриншот-тестов исключены Playground
+(интерактивный) и Default (MD покрыт `Sizes`).
+
+Для hover задан opt-in параметр `testRunner.hoverSelector`: synthetic
+`userEvent.hover` из play не включает CSS `:hover`, поэтому test-runner
+перемещает реальный указатель после каждого remount. Указатель в одном снимке
+может стоять только над одним элементом, поэтому hover выбранного варианта
+вынесен в `VisualTestsCheckedHover`. Baseline-файлы генерируются только
+CI / Docker; локальные macOS-скриншоты не публикуются.
 
 ---
 
-## Инварианты
+## История изменений
 
-- **`<input type="radio">`** — нативный, фиксирован. `type` исключён из props.
-- **`size: EComponentSize` default `MD`** — наш enum, не размер `<input>`.
-- **`children` — описание справа**, опционально. Без `children` рендерится только иконка.
-- **Текст всегда `<Text tag="div" size>` с маппингом** SM→B4 / MD→B3 / LG→B2.
-- **`labelAttributes` — единственный канал** для прокидывания `<label>`-атрибутов (`for`, `id`, `className`).
-- **`RadioXGroup`/`RadioYGroup`** — layout + `role="radiogroup"`. Не управляют состоянием.
-- **`RadioXGroup.indent` default `12`**, набор фиксирован `TIndentSize`.
-- **ForwardRef → `<input>`** на Radio. Не на label/wrapper.
-- **`RadioXGroup` / `RadioYGroup` — `FC`, не forwardRef**.
-- **`data-tx`** — на `<label>`.
+| Дата | Изменение |
+|---|---|
+| 2026-10-07 | Создан документ. Проведён AI-рефакторинг Radio, уточнён JSDoc, расширены тесты публичных контрактов; stories переведены на modern pattern (Default, Sizes, States, WithoutLabel) с визуальным покрытием размеров, checked / disabled, пустой и длинной подписи, клавиатурного фокуса и настоящего hover. |
 
 ---
 
-## Accessibility
+## Примеры использования
 
-- Нативный `<input type="radio">` — клавиатура (стрелки внутри той же `name`-группы), screen readers — работают «из коробки».
-- **`<label>` оборачивает input** — клик по тексту/иконке тоже выбирает radio.
-- `role="radiogroup"` на контейнере группы — корректная семантика для AT. Но **`aria-labelledby`** / `aria-label` группы нужно передавать через `...rest`.
-- **`name`** — потребитель должен передавать одинаковый name на все радио в группе (иначе нативная группировка/стрелки не работают).
-- `disabled` — корректно через `<input disabled>` (focus-skip, SR озвучивает).
-- `:focus-visible` стили — через CSS-класс на `<span class="radioIcon">` (стандартный паттерн).
+### Default
 
----
+`stories/Radio/examples/Default.tsx`
 
-## Дизайн-токены
+```tsx
+import React from "react";
+import { Radio } from "@sberbusiness/triplex-next";
+
+export const Default = () => <Radio>Radio text</Radio>;
+```
 
-Нет собственных. Цвета/размер `<span class="radioIcon">` — из `styles/Radio.module.less` (часто переменные проекта; уточнить в LESS).
+### Sizes
 
----
+`stories/Radio/examples/Sizes.tsx`
 
-## Связанные компоненты
+```tsx
+import React from "react";
+import { Radio, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = [EComponentSize.SM, EComponentSize.MD, EComponentSize.LG];
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <Radio size={size}>Radio text</Radio>
+            </div>
+        ))}
+    </div>
+);
+```
 
-- `Checkbox` — параллельный компонент.
-- `Text` (Typography) — описание.
-- `RadioXGroup` / `RadioYGroup` — layout-группы.
-- `EComponentSize`, `ETextSize`.
-- `TIndentSize` (`consts/IndentConst`).
+### States
 
----
+`stories/Radio/examples/States.tsx`
 
-## Stories
+```tsx
+import React from "react";
+import { Radio } from "@sberbusiness/triplex-next";
+
+export const States = () => {
+    const name = React.useId();
+    const [value, setValue] = React.useState("second");
+
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>Selected</div>
+                <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
+                    <Radio name={`${name}-selected`} value="first" checked={value === "first"} onChange={handleChange}>
+                        Radio text
+                    </Radio>
+                    <Radio
+                        name={`${name}-selected`}
+                        value="second"
+                        checked={value === "second"}
+                        onChange={handleChange}
+                    >
+                        Radio text
+                    </Radio>
+                </div>
+            </div>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>Disabled</div>
+                <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
+                    <Radio name={`${name}-disabled`} value="checked" disabled defaultChecked>
+                        Radio text
+                    </Radio>
+                    <Radio name={`${name}-disabled`} value="unchecked" disabled>
+                        Radio text
+                    </Radio>
+                </div>
+            </div>
+        </div>
+    );
+};
+```
 
-`stories/Radio/Radio.stories.tsx`
-Примеры: `stories/Radio/examples/`
+### WithoutLabel
 
----
+`stories/Radio/examples/WithoutLabel.tsx`
 
-## История изменений
+```tsx
+import React from "react";
+import { Radio, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = [EComponentSize.SM, EComponentSize.MD, EComponentSize.LG];
+
+export const WithoutLabel = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <div key={size}>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                <div style={{ display: "flex", gap: 24, alignItems: "center", flexWrap: "wrap" }}>
+                    <Radio size={size} aria-label={`Не выбран, ${size}`} />
+                    <Radio size={size} defaultChecked aria-label={`Выбран, ${size}`} />
+                    <Radio size={size} disabled aria-label={`Не выбран, недоступен, ${size}`} />
+                    <Radio size={size} defaultChecked disabled aria-label={`Выбран, недоступен, ${size}`} />
+                </div>
+            </div>
+        ))}
+    </div>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |