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

package/bundle/components/RadioXGroup.md

@@ -0,0 +1,259 @@
+---
+component: RadioXGroup
+category: Inputs
+related: [Radio, RadioYGroup]
+tokens: []
+stories: stories/RadioXGroup/RadioXGroup.stories.tsx
+version: "1.0"
+---
+
+# RadioXGroup
+
+## Назначение
+
+Контейнер для горизонтального расположения связанных `Radio` с переносом на следующую строку и настраиваемым отступом между вариантами. Сам контейнер не хранит выбранное значение и не управляет дочерними радио-кнопками.
+
+Используй когда: варианты одного выбора нужно разместить в строку с переносами.
+Не используй когда: варианты должны идти вертикально — используй `RadioYGroup`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+Обязательных custom-props нет. Для содержательной группы передай дочерние `Radio` и доступное имя группы.
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `indent` | `TIndentSize` | `12` | Горизонтальный отступ между Radio в пикселях: `12`, `16`, `20`, `24`, `28`, `32`. |
+| `children` | `React.ReactNode` | — | Содержимое группы, обычно непосредственные дочерние `Radio`. |
+| `className`, `...rest` | `React.HTMLAttributes<HTMLDivElement>` | — | Пользовательский класс, HTML-атрибуты, ARIA-атрибуты и обработчики корневого `div`. |
+
+### Ограничения использования
+
+- Размер, выбранное и отключённое состояния задаются каждому `Radio`: у группы нет собственных `size`, `checked`, `disabled` или `onChange` для выбранного значения.
+- Все `Radio` одного выбора должны иметь общий `name`. Разные группы должны использовать разные `name`: роль `radiogroup` сама по себе не связывает нативные input.
+- Группа использует `inline-flex` и `flex-flow: row wrap`. Ширину и внешние отступы определяет окружающая разметка; отдельного вертикального зазора между строками нет.
+- `indent` задаёт отрицательные горизонтальные маргины контейнера и положительные маргины по половине отступа у потомков с классом `.label` из `Radio`. Это не универсальный `gap`: для произвольных children без этого класса внутренние маргины не появятся, а отрицательные маргины контейнера останутся.
+- `onChange`, унаследованный от HTML-атрибутов, получает всплывающий `React.FormEvent<HTMLDivElement>` от дочернего input. Значение читается из input-источника события; собственного callback-контракта выбора у группы нет.
+
+---
+
+## Дизайн-токены
+
+Собственных дизайн-токенов нет: стили `RadioXGroup` задают только раскладку и отступы. Цвета и состояния дочерних радио-кнопок определяются компонентом `Radio`.
+
+---
+
+## Инварианты
+
+- `forwardRef` обязателен; ref указывает на корневой `HTMLDivElement`.
+- Корневой DOM-элемент — `div`, роль по умолчанию — `radiogroup`.
+- `IRadioXGroupProps`, `indent`, значения `TIndentSize`, дефолт `12` и публичные barrel-экспорты сохраняются.
+- Порядок `role="radiogroup"` перед `...rest` сохраняет существующий контракт: переданный `role` может переопределить роль по умолчанию.
+- `className` объединяется через `clsx`, остальные HTML-атрибуты приходят на корневой элемент, `indent` в DOM не передаётся.
+- LESS-классы `radioXGroup` и `indent-{n}`, геометрия маргинов и связь с `.label` из `Radio` должны сохраняться при рефакторинге.
+- `displayName` — `RadioXGroup`. Компонент не добавляет state, контекст или клавиатурные обработчики.
+
+---
+
+## Accessibility
+
+- Доступное имя группы задаёт потребитель через `aria-label` или `aria-labelledby` со ссылкой на существующий заголовок.
+- По умолчанию `role="radiogroup"` обозначает группу радио-кнопок; при переопределении `role` ответственность за семантику остаётся у потребителя.
+- `Radio` внутри группы сохраняют нативную семантику `input type="radio"`. Общий `name` обеспечивает единственный выбор и нативную клавиатурную навигацию между вариантами.
+- Подписи и `disabled` передаются дочерним `Radio`. Контейнер не перемещает фокус и по умолчанию не добавляет `tabIndex`.
+
+---
+
+## Связанные компоненты
+
+- `Radio` — часть семейства, рендерится потребителем внутри группы; его корневой `.label` участвует в горизонтальных отступах.
+- `RadioYGroup` — альтернативная компоновка того же набора радио-кнопок по вертикали.
+
+---
+
+## Stories
+
+Основные истории: `stories/RadioXGroup/RadioXGroup.stories.tsx`
+Файлы примеров: `stories/RadioXGroup/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Controls для `indent` и настройки размера/disabled дочерних Radio; исключена из скриншот-тестов. |
+| `Default` | `Default.tsx` | Группа с дефолтным отступом, общим `name` и доступным именем. |
+| `Indents` | `Indents.tsx` | Все шесть значений горизонтального отступа. |
+| `Sizes` | `Sizes.tsx` | Дочерние Radio размеров SM, MD и LG. |
+| `States` | `States.tsx` | Controlled-выбор через `checked` и `onChange`; выбранный и невыбранный отключённые Radio. |
+| `VisualTests` | `VisualTests.tsx` | Клавиатурный focus через `play`, CSS hover через реальную мышь test-runner (`parameters.testRunner.hoverSelector`); скрыта из autodocs. |
+
+Legacy stories `stories/Radio.stories.tsx` и их ID сохраняются; новый набор имеет собственный title `Components/RadioXGroup`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-07 | Создан документ для TRI-69: добавлен forwardRef на корневой div, уточнён JSDoc; контракты indent, HTML-атрибутов и ref покрыты unit-тестами, добавлены современные stories. |
+| 2026-10-07 | Исправлено визуальное покрытие CSS hover: test-runner перемещает реальную мышь по opt-in селектору и возвращает её после снимка. |
+| 2026-10-07 | По замечаниям ревью удалены история Wrapping и пример пустой группы из VisualTests. |
+| 2026-10-08 | Story `RadioSizes` переименована в `Sizes`; подписи вариантов приведены к общему формату, States разбита на подписанные секции Selected и Disabled, VisualTests скрыта из сайдбара (`!dev`). |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/RadioXGroup/examples/Default.tsx`
+
+```tsx
+import React from "react";
+import { Radio, RadioXGroup } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const name = React.useId();
+
+    return (
+        <RadioXGroup aria-label="Способ доставки">
+            <Radio name={name} value="courier" defaultChecked>
+                Radio text
+            </Radio>
+            <Radio name={name} value="pickup">
+                Radio text
+            </Radio>
+            <Radio name={name} value="post">
+                Radio text
+            </Radio>
+        </RadioXGroup>
+    );
+};
+```
+
+### Indents
+
+`stories/RadioXGroup/examples/Indents.tsx`
+
+```tsx
+import React from "react";
+import { Radio, RadioXGroup, TIndentSize } from "@sberbusiness/triplex-next";
+
+const INDENTS = [12, 16, 20, 24, 28, 32] satisfies TIndentSize[];
+
+export const Indents = () => {
+    const name = React.useId();
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 24, width: 480, maxWidth: "100%" }}>
+            {INDENTS.map((indent) => (
+                <div key={indent}>
+                    <div style={{ marginBottom: 8, fontWeight: 700 }}>indent = {indent}</div>
+                    <RadioXGroup indent={indent} aria-label={`Способ доставки, отступ ${indent}`}>
+                        <Radio name={`${name}-${indent}`} value="courier" defaultChecked>
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${indent}`} value="pickup">
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${indent}`} value="post">
+                            Radio text
+                        </Radio>
+                    </RadioXGroup>
+                </div>
+            ))}
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/RadioXGroup/examples/Sizes.tsx`
+
+```tsx
+import React from "react";
+import { Radio, RadioXGroup, EComponentSize } from "@sberbusiness/triplex-next";
+
+const SIZES = [EComponentSize.SM, EComponentSize.MD, EComponentSize.LG];
+
+export const Sizes = () => {
+    const name = React.useId();
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 24, width: 480, maxWidth: "100%" }}>
+            {SIZES.map((size) => (
+                <div key={size}>
+                    <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                    <RadioXGroup aria-label={`Способ доставки, размер Radio ${size}`}>
+                        <Radio name={`${name}-${size}`} value="courier" size={size} defaultChecked>
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${size}`} value="pickup" size={size}>
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${size}`} value="post" size={size}>
+                            Radio text
+                        </Radio>
+                    </RadioXGroup>
+                </div>
+            ))}
+        </div>
+    );
+};
+```
+
+### States
+
+`stories/RadioXGroup/examples/States.tsx`
+
+```tsx
+import React from "react";
+import { Radio, RadioXGroup } 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, width: 480, maxWidth: "100%" }}>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>Selected</div>
+                <RadioXGroup aria-label="Выбранный вариант">
+                    <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>
+                    <Radio name={`${name}-selected`} value="third" checked={value === "third"} onChange={handleChange}>
+                        Radio text
+                    </Radio>
+                </RadioXGroup>
+            </div>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>Disabled</div>
+                <RadioXGroup aria-label="Отключённые варианты">
+                    <Radio name={`${name}-disabled`} value="checked" disabled defaultChecked>
+                        Radio text
+                    </Radio>
+                    <Radio name={`${name}-disabled`} value="unchecked" disabled>
+                        Radio text
+                    </Radio>
+                </RadioXGroup>
+            </div>
+        </div>
+    );
+};
+```
+

package/bundle/components/RadioYGroup.md

@@ -0,0 +1,266 @@
+---
+component: RadioYGroup
+category: Inputs
+related: [Radio, RadioXGroup]
+tokens: []
+stories: stories/RadioYGroup/RadioYGroup.stories.tsx
+version: "1.0"
+---
+
+# RadioYGroup
+
+## Назначение
+
+Вертикальный контейнер для связанных радио-кнопок с ролью `radiogroup` по умолчанию.
+Компонент задаёт раскладку и семантику группы; выбор остаётся на уровне вложенных
+`Radio` и приложения.
+
+Используй когда: нужно разместить варианты одного выбора друг под другом.
+Не используй когда: варианты должны идти в строку — используй `RadioXGroup`;
+для независимых множественных вариантов подходит семейство `Checkbox`.
+
+---
+
+## Варианты и props
+
+### Обязательные props
+
+Обязательных props нет.
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `children` | `React.ReactNode` | — | Обычно несколько `Radio` с общим `name` и разными `value` |
+| `className` | `string` | — | Добавляется к классу корневого контейнера через `clsx` |
+| `role` | `React.AriaRole` | `radiogroup` | Стандартный HTML-prop; позволяет переопределить роль |
+| `aria-label` / `aria-labelledby` | HTML/ARIA-атрибуты | — | Доступное имя группы задаёт потребитель |
+| `...divAttributes` | `React.HTMLAttributes<HTMLDivElement>` | — | Остальные атрибуты и обработчики событий корневого `<div>` |
+
+### Ограничения использования
+
+- Собственных `size`, `checked`, `defaultChecked`, `disabled`, `name` и `value`
+  у группы нет: их передают каждому дочернему `Radio`. Группа не клонирует children
+  и не передаёт им props через контекст.
+- Одинаковый `name` связывает нативные радио-кнопки в один выбор. Независимым
+  наборам в одной форме нужны разные `name`; сами контейнеры их не изолируют.
+- В controlled-режиме приложение хранит выбранное значение, передаёт `checked`
+  каждому `Radio` и обновляет значение через его `onChange`. В uncontrolled-режиме
+  начальный выбор задаётся `defaultChecked` одного `Radio`.
+- Раскладка корня — `display: inline-flex` и `flex-flow: column wrap`. Ширина
+  и внешние отступы не задаются.
+- Смежные `Radio` одного размера получают вертикальный отступ: SM — 8px,
+  MD — 16px, LG — 20px. Правила `.label.sm + .label.sm`, `.label.md + .label.md`
+  и `.label.lg + .label.lg` из `styles/RadioYGroup.module.less` используют общие
+  классы семейства `Radio`: `scripts/generate-scoped-name.ts` формирует имя класса
+  из семейства, локального имени и версии библиотеки. Между соседями разных размеров
+  и между произвольными children эти отступы не назначаются; отдельная обёртка
+  вокруг каждого `Radio` разрывает соседство `label`-элементов.
+- `aria-disabled` на контейнере не отключает дочерние контролы: для блокировки
+  взаимодействия нужен `disabled` у каждого `Radio`.
+
+---
+
+## Дизайн-токены
+
+Собственных дизайн-токенов у `RadioYGroup` нет: его LESS задаёт только раскладку.
+Цвета, hover, focus и disabled вложенных радио-кнопок используют токены группы
+`Radio` из `src/components/DesignTokens/components/Radio.ts`; их переопределяют
+через `ThemeProvider` по общим правилам темизации.
+
+---
+
+## Инварианты
+
+- `forwardRef<HTMLDivElement>` обязателен; объектный и callback ref указывают
+  на корневой `<div>`, а при размонтировании callback получает `null`.
+- `className`, `ref` и HTML-атрибуты относятся к одному корневому `<div>`.
+- Роль по умолчанию — `radiogroup`; `{...rest}` идёт после роли, поэтому переданный
+  `role` её переопределяет. Не фиксировать роль и не исключать `role` из интерфейса
+  без согласования изменения публичного поведения.
+- `RadioYGroup` и `IRadioYGroupProps` экспортируются через
+  `src/components/Radio/index.ts`; `displayName` — `RadioYGroup`.
+- Селекторы отступов связаны с классами `label`, `sm`, `md`, `lg` из
+  `Radio.module.less` через общий генератор имён в Vite и Storybook. Учитывать эту
+  связь при изменении классов, расположения модулей или генератора.
+- Компонент не хранит выбор, не управляет фокусом и не перехватывает клавиатуру.
+- Story IDs `components-radioygroup--*` связаны с visual baselines;
+  legacy IDs из `stories/Radio.stories.tsx` также сохраняются.
+
+---
+
+## Accessibility
+
+- `role="radiogroup"` описывает набор вариантов одного выбора. Потребитель
+  передаёт `aria-label` либо `aria-labelledby`, ссылающийся на существующую
+  подпись группы. Текст внутри компонента не задаётся.
+- Каждый `Radio` остаётся нативным `<input type="radio">` внутри `<label>`;
+  его children задают подпись конкретного варианта. Для варианта без текста
+  потребитель должен передать доступное имя самому `Radio`.
+- Клавиатура и выбор работают через нативные radio inputs с общим `name`.
+  Контейнер не реализует отдельную стрелочную навигацию и не переносит фокус.
+- Корневой `<div>` по умолчанию не фокусируется. `ref` не вызывает фокусировку;
+  потребитель может передать `tabIndex`, если сценарий требует фокуса контейнера.
+- Disabled и `:focus-visible` отображаются на дочернем `Radio`.
+
+---
+
+## Связанные компоненты
+
+- `Radio` — базовый элемент семейства; задаёт размер, значение, выбор,
+  disabled и обработчики отдельных вариантов.
+- `RadioXGroup` — альтернативная горизонтальная раскладка с собственным `indent`.
+
+---
+
+## Stories
+
+Основные истории: `stories/RadioYGroup/RadioYGroup.stories.tsx`
+Файлы примеров: `stories/RadioYGroup/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Default` | `Default.tsx` | Минимальная группа с доступным именем и общим `name` дочерних Radio |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG на дочерних Radio, выбранные и невыбранные варианты |
+| `States` | `States.tsx` | Controlled-выбор через `checked` и `onChange`; выбранный и невыбранный disabled-варианты |
+| `VisualTests` | `VisualTests.tsx` | Фокус с клавиатуры и hover невыбранного варианта |
+| `VisualTestsCheckedHover` | — | Фокус выбранного варианта и hover выбранного варианта, тот же renderer |
+
+Playground не создаётся: у группы нет собственных настраиваемых props.
+Обе VisualTests-истории скрыты из меню и autodocs тегами `!dev` и `!autodocs`.
+Они используют `play`; настоящий CSS hover перед снимком
+устанавливает test-runner через opt-in параметр `visualTests.hoverTarget`.
+Baseline-файлы создаются только CI/Docker на viewport xs и xl.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-05 | Создан документ (TRI-70): добавлен forwardRef на корневой div, описаны accessibility и HTML-контракты, unit-тесты и modern stories |
+| 2026-10-05 | Уточнены отступы между смежными Radio одного размера и связь CSS-классов внутри семейства через общий генератор имён |
+| 2026-10-05 | VisualTests-истории скрыты из меню Storybook, пример Disabled упрощён до размера MD |
+| 2026-10-08 | Stories `Selected` и `Disabled` объединены в `States` с подписанными секциями |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/RadioYGroup/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { uniqueId } from "lodash-es";
+import { Radio, RadioYGroup } from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [name] = useState(() => uniqueId("radio-y-group-default-"));
+
+    return (
+        <RadioYGroup aria-label="Выберите вариант">
+            <Radio name={name} value="first">
+                Radio text
+            </Radio>
+            <Radio name={name} value="second">
+                Radio text
+            </Radio>
+            <Radio name={name} value="third">
+                Radio text
+            </Radio>
+        </RadioYGroup>
+    );
+};
+```
+
+### Sizes
+
+`stories/RadioYGroup/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { uniqueId } from "lodash-es";
+import { EComponentSize, Radio, RadioYGroup } from "@sberbusiness/triplex-next";
+
+const SIZES = [EComponentSize.SM, EComponentSize.MD, EComponentSize.LG];
+
+export const Sizes = () => {
+    const [name] = useState(() => uniqueId("radio-y-group-sizes-"));
+
+    return (
+        <div style={{ display: "flex", alignItems: "flex-start", flexWrap: "wrap", gap: 32 }}>
+            {SIZES.map((size) => (
+                <div key={size} style={{ width: 180 }}>
+                    <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+                    <RadioYGroup aria-label={`Варианты размера ${size.toUpperCase()}`}>
+                        <Radio name={`${name}-${size}`} value="first" size={size}>
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${size}`} value="second" size={size} defaultChecked>
+                            Radio text
+                        </Radio>
+                        <Radio name={`${name}-${size}`} value="third" size={size}>
+                            Radio text
+                        </Radio>
+                    </RadioYGroup>
+                </div>
+            ))}
+        </div>
+    );
+};
+```
+
+### States
+
+`stories/RadioYGroup/examples/States.tsx`
+
+```tsx
+import React, { useState } from "react";
+import { uniqueId } from "lodash-es";
+import { Radio, RadioYGroup } from "@sberbusiness/triplex-next";
+
+export const States = () => {
+    const [name] = useState(() => uniqueId("radio-y-group-states-"));
+    const [value, setValue] = 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>
+                <RadioYGroup aria-label="Выбранный вариант">
+                    <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>
+                    <Radio name={`${name}-selected`} value="third" checked={value === "third"} onChange={handleChange}>
+                        Radio text
+                    </Radio>
+                </RadioYGroup>
+            </div>
+            <div>
+                <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>Disabled</div>
+                <RadioYGroup aria-label="Отключённые варианты">
+                    <Radio name={`${name}-disabled`} value="first" disabled>
+                        Radio text
+                    </Radio>
+                    <Radio name={`${name}-disabled`} value="second" disabled defaultChecked>
+                        Radio text
+                    </Radio>
+                </RadioYGroup>
+            </div>
+        </div>
+    );
+};
+```
+