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

package/bundle/components/Row.md

@@ -0,0 +1,125 @@
+---
+component: Row
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Col, Container]
+tokens: []
+stories: stories/Row/Row.stories.tsx
+version: "1.0"
+---
+
+# Row
+
+## Назначение
+
+Строка grid-системы — `<div>` с горизонтальным flex-wrap layout'ом и
+**отрицательными margin'ами по бокам** для компенсации gutter'ов
+дочерних `Col`. Рекомендованный child — `Col`.
+
+Используй когда: компонуешь форму/контент в колоночной сетке проекта.
+Для нестандартного layout'а — flex/grid-CSS напрямую.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Row/
+├── Row.tsx                  # FC; <div> + flex layout
+├── styles/Row.module.less   # margin -horizontal-gap, padding-bottom
+├── index.ts                 # Barrel
+└── __tests__/
+```
+
+---
+
+## Варианты и props
+
+### `IRowProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `paddingBottom` | `boolean` | `true` | Нижний отступ строки. `false` — отключить. |
+| `...HTMLAttributes` | — | — | На корневой `<div>`. |
+
+- `paddingBottom: false` → класс `noPaddingBottom`.
+- **Последняя `Row` в родителе** автоматически получает `padding-bottom: 0` через CSS-селектор `:last-child`.
+
+---
+
+## Ключевые особенности реализации
+
+### Compensating margins
+
+```less
+.row {
+    display: flex;
+    flex-wrap: wrap;
+    margin-left: -@grid-horizontal-gap;
+    margin-right: -@grid-horizontal-gap;
+    padding-bottom: @row-bottom-padding;
+}
+```
+
+- Отрицательные margin компенсируют padding'и `Col`'ов — содержимое крайних колонок выровнено по краю Row.
+- Стандартный bootstrap-style grid pattern.
+
+### `padding-bottom` через CSS, а не inline
+
+- LESS-переменная `@row-bottom-padding` определяет величину.
+- `:last-child` — обнуление: серия Row друг под другом не накапливает отступ снизу.
+
+### `flex-wrap: wrap`
+
+- Колонки с суммарной шириной > 100% переносятся на новую строку (внутри одной Row).
+
+### **Только базовый `<div>`**
+
+- Нет `forwardRef`, нет slots, нет компонентного API. Простой layout helper.
+
+---
+
+## Инварианты
+
+- **`<div>` с `display: flex; flex-wrap: wrap`** — изменение типа layout — breaking.
+- **`paddingBottom: true` default** — большинство строк с отступом.
+- **`:last-child` снимает padding-bottom** — публичное CSS-поведение.
+- **Отрицательные margin'ы** = ожидание дочерних `Col`'ов с padding'ами равными `@grid-horizontal-gap`.
+- **`FC, не forwardRef`**.
+- **Контракт child** — `Col` (на уровне типов не enforced).
+
+---
+
+## Accessibility
+
+- Нейтральный `<div>` — без семантики. Если строка несёт смысл (form-row), потребитель добавляет `role` сам.
+
+---
+
+## Дизайн-токены
+
+LESS-переменные (через `@import '../../../styles/style'`):
+- `@grid-horizontal-gap` — горизонтальный gap.
+- `@row-bottom-padding` — нижний отступ.
+
+---
+
+## Связанные компоненты
+
+- `Col` — колонка, основной child.
+- Прочая grid-система (`Container`) — если есть в проекте.
+
+---
+
+## Stories
+
+`stories/Row/Row.stories.tsx`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/SMSField.md

@@ -0,0 +1,160 @@
+---
+component: SMSField
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [TextField, Tooltip, ButtonIcon, FormField]
+tokens:
+  - --triplex-next-SMSField-Submit_Background_Default
+  - --triplex-next-SMSField-Submit_Background_Hover
+  - --triplex-next-SMSField-Submit_Background_Active
+  - --triplex-next-SMSField-Refresh_Fill_Empty
+  - --triplex-next-SMSField-Refresh_Fill_Full
+  - --triplex-next-SMSField-Refresh_Disabled
+stories: stories/SMSField/SMSField.stories.tsx
+version: "1.0"
+---
+
+# SMSField
+
+## Назначение
+
+Композитный компонент для ввода SMS-кода: поле ввода + кнопка отправки +
+кнопка повторного запроса кода с обратным отсчётом + tooltip над Refresh.
+Работает через `SMSFieldContext` — подкомпоненты обязаны быть детьми `SMSField`.
+
+Используй когда: нужно подтверждение действия SMS-кодом (логин, оплата,
+verification). Для произвольных цифровых полей используй `TextField` с
+`type="tel"`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/SMSField/
+├── SMSField.tsx               # FC + статичные Composition
+├── SMSFieldContext.ts         # Shared state (code, disabled, size...)
+├── types.ts                   # ISMSFieldProps
+├── components/
+│   ├── SMSFieldInput.tsx      # <input> на базе FormField/FormFieldInput
+│   ├── SMSFieldSubmit.tsx     # ButtonIcon (CIRCLE) с SubmitIcon
+│   ├── SMSFieldRefresh.tsx    # ButtonIcon (SQUIRCLE) + круговой прогресс
+│   ├── SMSFieldTooltip.tsx    # Оборачивает Refresh в Tooltip
+│   ├── RefreshIcon.tsx
+│   └── SubmitIcon.tsx
+├── styles/
+└── index.ts
+```
+
+---
+
+## Slot-компоненты
+
+| Slot | Props | Назначение |
+|---|---|---|
+| `SMSField.Input` | `ISMSFieldInputProps` (`InputHTMLAttributes` + `counter?`, `description?`) | Поле ввода кода; фильтрует ввод (только цифры), `maxLength = 8` по умолчанию, `Enter` → `onSubmitCode`. |
+| `SMSField.Submit` | `ButtonHTMLAttributes` | Кнопка отправки (ButtonIcon CIRCLE); автоматически disabled, когда `code === ""`. |
+| `SMSField.Refresh` | `countdownTime`, `countdownTimeLeft`, `onRefresh` | Кнопка запроса кода с круговым прогрессом; disabled пока `countdownTimeLeft > 0`. |
+| `SMSField.Tooltip` | `Partial<ITooltipProps>` + `message`, `children` (ReactElement), `targetRef` | Оборачивает `Refresh` (через `targetRef`) в `Tooltip` с hover-триггером. |
+
+---
+
+## Варианты и props
+
+### `ISMSFieldProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `code` | `string` | — | Текущее значение кода. |
+| `onChangeCode` | `(code: string) => void` | — | Вызывается при валидном вводе (только цифры). |
+| `onSubmitCode` | `(code: string) => void` | — | Вызывается из `SMSField.Submit` и по Enter в `SMSField.Input`. |
+| `size` | `EComponentSize` | — | Прокидывается в дочерние FormField/ButtonIcon. |
+| `disabled?` | `boolean` | `false` | Блокирует все вложенные контролы. |
+| `error?` | `boolean` | `false` | Устанавливает `EFormFieldStatus.ERROR` у `SMSField.Input`. |
+| `...HTMLAttributes<HTMLDivElement>` | — | — | Прокидываются на корневой div. |
+| `TestProps` | — | — | `data-test-*` атрибуты. |
+
+### `ISMSFieldInputProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `counter?` | `ReactNode` | — | Отображается в `FormFieldCounter` внутри description. |
+| `description?` | `ReactNode` | — | Текст под полем. |
+| `maxLength?` | `number` | `8` | Максимальная длина кода. |
+| `...InputHTMLAttributes` | — | — | Стандартные атрибуты input. |
+
+### `ISMSFieldRefreshProps`
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `countdownTime` | `number` | Полное время отсчёта (сек). Для расчёта прогресса. |
+| `countdownTimeLeft` | `number` | Оставшееся время (сек). Если `> 0` — кнопка disabled. |
+| `onRefresh` | `() => void` | Вызывается при клике. |
+
+---
+
+## Контекст (`SMSFieldContext`)
+
+Поля: `code`, `disabled`, `error`, `onChangeCode`, `onSubmitCode`, `size`,
+`sizeClassName`, `disabledSubmit` / `setDisabledSubmit`, `tooltipId` / `setTooltipId`.
+
+- `disabledSubmit` — вычисляется в `SMSField.Submit` (через `useEffect`) и
+  читается в `SMSField.Input` для обработки Enter.
+- `tooltipId` — генерируется в `SMSField.Tooltip` и читается в `SMSField.Refresh`
+  для `aria-describedby`.
+
+---
+
+## Инварианты
+
+- **Регэксп ввода `/^[0-9]*$/`** — только цифры; нецифровой ввод отбрасывается в `SMSFieldInput.handleChange`.
+- **`maxLength` default `8`** — переопределяемо, но не нужно без причины.
+- **Enter в `Input`** вызывает `onSubmitCode(code)` только когда `!disabledSubmit`.
+- **`Submit` disabled, если `code === ""`** — «пустой» код не отправляется.
+- **`Refresh` disabled, если `countdownTimeLeft > 0`** — пользователь не может запросить код повторно до окончания отсчёта.
+- **`Refresh` остаётся enabled при `allDisabled && error`** (`(allDisabled && !error) || disabled || isSmsCountdownTicking`) — пользователь должен иметь возможность перезапросить код при ошибке.
+- **`SMSField.Tooltip` требует `targetRef`** — ref на Refresh-кнопку.
+- **`ISMSFieldTooltipProps.children: React.ReactElement`** — единственный ребёнок.
+- **`SMSField` — FC** (не forwardRef). `Input`, `Refresh` — forwardRef на соответствующие HTML-элементы.
+- **`FormField`/`FormFieldInput`** используется внутри Input — это фиксирует error/disabled-стилизацию.
+
+---
+
+## Accessibility
+
+- `SMSField.Input` наследует accessibility от `FormFieldInput`.
+- `SMSField.Refresh` получает `aria-describedby={tooltipId}` → screen reader озвучивает tooltip как описание кнопки.
+- `autoComplete="off"` захардкожен на input — предотвращает автозаполнение.
+- Tooltip-триггер — `hover`; для клавиатуры — фокус на кнопке активирует tooltip в Tooltip-компоненте (см. Tooltip-AI).
+
+---
+
+## Связанные компоненты
+
+- `FormField`, `FormFieldInput`, `FormFieldCounter`, `FormFieldDescription` — основа поля ввода.
+- `ButtonIcon` — основа для Submit/Refresh.
+- `Tooltip` — обёртка Refresh.
+- `TextField` — общий аналог для не-SMS кейсов.
+
+---
+
+## Stories
+
+Основные истории: `stories/SMSField/SMSField.stories.tsx`
+Примеры: `stories/SMSField/examples/`
+
+| Story | Что демонстрирует |
+|---|---|
+| `Playground` | Интерактивный контроль |
+| `Error` | Состояние ошибки + Refresh доступен |
+| `Disabled` | Общий disabled |
+| `Sizes` | Все размеры (MD/LG) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/SegmentedControl.md

@@ -0,0 +1,235 @@
+---
+component: SegmentedControl
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [Tabs, Radio, Checkbox, ButtonBase, IconWrapper]
+tokens: []
+stories: stories/SegmentedControl/SegmentedControl.stories.tsx
+version: "1.0"
+---
+
+# SegmentedControl
+
+## Назначение
+
+Группа «сегментов»-кнопок: выбор **одного** (`SINGLE`) или **нескольких**
+(`MULTIPLE`) вариантов из небольшого набора. Каждый сегмент —
+`<button aria-pressed>`. Похоже на iOS UISegmentedControl. Управление
+выбором — через `value` + `onSelect` снаружи; внутреннее состояние нет.
+
+Используй когда: 2–6 коротких опций (фильтры, переключатели view).
+Для много опций / длинных лейблов — `Tabs` или `SelectField`. Для
+визуально не-кнопочного выбора — `Radio` / `Checkbox` группы.
+
+---
+
+## Файловая структура
+
+```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__/
+```
+
+---
+
+## Compound-структура
+
+```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>
+```
+
+---
+
+## Варианты и props
+
+### SegmentedControl — `TSegmentedControlProps = ISegmentedControlSingleProps | ISegmentedControlMultipleProps`
+
+#### Общее (`ISegmentedControlCommonProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect">`)
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `theme` | `ESegmentedControlTheme` | — (обязателен) | `GENERAL_1` / `GENERAL_2` / `SECONDARY_1` / `SECONDARY_2`. |
+| `size` | `ESegmentedControlSize` | — (обязателен) | `SM` / `MD` / `LG`. **Собственный enum**, не `EComponentSize`. |
+| `disabled?` | `boolean` | `false` | Дизейблит **все сегменты** (через context). |
+| `...HTMLAttributes` | — | — | На корневой `<div>`. |
+
+#### SINGLE
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `ESegmentedControlType.SINGLE` | Discriminator. |
+| `value` | `string` | Текущий выбранный. |
+| `onSelect` | `(value: string) => void` | Передаётся **новый** value. |
+
+#### MULTIPLE
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `type` | `ESegmentedControlType.MULTIPLE` | Discriminator. |
+| `value` | `string[]` | Массив выбранных. |
+| `onSelect` | `(value: string[]) => void` | Передаётся **полный новый массив** (не дельта). |
+
+### 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`
+
+```ts
+{ type, value, disabled, onSegmentSelect: ({ selected, value }) => void }
+```
+
+### Enums
+
+- `ESegmentedControlType.SINGLE | MULTIPLE`
+- `ESegmentedControlTheme.GENERAL_1 | GENERAL_2 | SECONDARY_1 | SECONDARY_2`
+- `ESegmentedControlSize.SM | MD | LG`
+
+---
+
+## Ключевые особенности реализации
+
+### Discriminated union по `type`
+
+```ts
+type TSegmentedControlProps = ISegmentedControlSingleProps | ISegmentedControlMultipleProps;
+```
+
+- TS гарантирует: `value: string` ↔ `type: SINGLE`; `value: string[]` ↔ `type: MULTIPLE`. `onSelect` сигнатура соответственно.
+- Discriminator обязателен на потребителе.
+
+### `handleSegmentSelect` — превращение `(value, selected)` в новый список
+
+```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`
+
+```ts
+case SINGLE: onSegmentSelect({ value, selected: true });
+case MULTIPLE: onSegmentSelect({ value, selected: !selected });
+```
+
+### `IconWrapper displayContents disabled active={selected}`
+
+```tsx
+<IconWrapper displayContents disabled={...} active={selected}>
+    <ButtonBase aria-pressed={selected} ...>
+        <span className={styles.content}>{children}</span>
+    </ButtonBase>
+</IconWrapper>
+```
+
+- **`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 }
+```
+
+- При использовании `Segment` вне `SegmentedControl` — `value === ""`, ничего не выбрано, клик noop. Безопасно.
+
+### `getTitle`
+
+- Если `title` передан — использует его.
+- Иначе — если `children: string` — берёт children (для tooltip'а на overflow-text).
+- Иначе — undefined.
+
+### Темы — 4 варианта
+
+- `GENERAL_1`, `GENERAL_2`, `SECONDARY_1`, `SECONDARY_2`. Проверять в LESS — отличия в фоне/border/цвете.
+
+### Sizes — собственный enum
+
+- `ESegmentedControlSize.SM/MD/LG` — **не** `EComponentSize`. Расхождение с типичной практикой (исторически).
+
+---
+
+## Инварианты
+
+- **`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`** — порядок может быть важен.
+
+---
+
+## Accessibility
+
+- `<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 полезно.
+
+---
+
+## Дизайн-токены
+
+Нет собственных — наследуются от `Button`/тем (`general_1`, `secondary_1`, ...). Token-структура — в `styles/`.
+
+---
+
+## Связанные компоненты
+
+- `Tabs` — для большего количества опций / длинных лейблов.
+- `Radio` / `Checkbox` (+ `RadioYGroup` / аналог) — альтернатива для form-input семантики.
+- `ButtonBase` — нижележащий primitive.
+- `IconWrapper` — управление цветом иконок внутри (active/disabled).
+
+---
+
+## Stories
+
+`stories/SegmentedControl/SegmentedControl.stories.tsx`
+Примеры: `stories/SegmentedControl/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |