@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.45.0-beta

package/bundle/components/FormGroup.md

@@ -1,11 +1,9 @@
 ---
 component: FormGroup
-category: Forms
-figma-node: ""
-figma-file: ""
-related: [FormField, TextField, SelectField, HelpBox, Alert]
+category: FormField
+related: [FormField, TextField, MaskedField]
 tokens: []
-stories: ""
+stories: stories/FormGroup/FormGroup.stories.tsx
 version: "1.0"
 ---
 
@@ -13,87 +11,229 @@ version: "1.0"
 
 ## Назначение
 
-Разметочная обёртка-`<div>` для группировки элементов формы (`FormField`,
-`HelpBox`, `Alert`, `Description`). Сама по себе **не добавляет стилей** —
-только прокидывает `ref` и все `HTMLDivAttributes`. Смысл — именованная
-точка в DOM для data-атрибутов и семантики формы.
+Контейнер формы: объединяет поле ввода с относящимися к нему элементами — `FormField`,
+`FormFieldDescription`, `HelpBox`, `AlertContext` — в один блок. Части передаются декларативно
+через `children`, поэтому каждой можно задать свои props и data-атрибуты.
 
-Используй когда: нужно сгруппировать несколько полей логически (блок "контакты",
-"адрес") и иметь стабильный wrapper под `data-*`/`aria-*`.
-Не используй как: общий flex-контейнер — возьми `Row`/`Col`.
+Рендерит один `div` без собственных классов, стилей и отступов: расстояния между частями
+задают сами части (`FormFieldDescription`, `Gap`), а не группа.
+
+Используй когда: поле нужно показать вместе с описанием, счётчиком, текстом ошибки,
+подсказкой или сообщением `AlertContext`, и эти элементы должны читаться как одна логическая
+группа формы.
+Не используй когда: достаточно готовой обёртки над полем — `TextField`, `TextareaField`,
+`MaskedField`, `AmountField` уже собирают `FormGroup` + `FormField` внутри себя, и снаружи
+их в `FormGroup` заворачивать не нужно.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/FormGroup/
-├── FormGroup.tsx   # forwardRef, <div>, passthrough props
-└── index.ts        # export * from "./FormGroup"
-```
+Настраиваемых props у компонента нет: он принимает `children` и стандартные атрибуты `div`.
+Внутренний `IFormGroupProps` расширяет `React.HTMLAttributes<HTMLDivElement>`:
+все стандартные атрибуты `div` (включая `className`, `style`, `id`, `role`, `aria-*`, `data-*`
+и обработчики событий) уходят через `...rest` на корневой элемент.
 
-Нет styles, нет tests, нет stories. Демонстрируется опосредованно через
-stories типовых полей, где `FormGroup` иногда обёрнут вокруг формы.
+### Опциональные props
 
----
+| Prop       | Тип               | По умолчанию | Описание                                                                   |
+| ---------- | ----------------- | ------------ | -------------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | —            | Части группы: поле ввода и относящиеся к нему подсказки и сообщения.       |
 
-## Варианты и props
+Поскольку настраиваемых props нет, у компонента нет story `Playground`.
 
-### `IFormGroupProps extends React.HTMLAttributes<HTMLDivElement>`
+---
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `children` | `ReactNode` | Обычно несколько `FormField`/`Alert`/`HelpBox`. |
-| `className`, `style`, `...HTMLDivAttributes` | — | Стандартные. |
+## Дизайн-токены
 
-Интерфейс объявлен **локально, не экспортирован**. Если понадобится
-расширить props — сначала экспортировать интерфейс.
+Собственных CSS-переменных нет — у компонента нет файла стилей. Внешний вид группы
+целиком определяют вложенные компоненты.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef`** — есть, не убирать.
-- **Без собственных классов/стилей** — осознанно. Если добавить flex/padding,
-  сломается большинство существующих интеграций, где вёрстку задают потомки.
-- Все атрибуты прокидываются на корневой `<div>` через spread — включая
-  `className`/`style`. Потребитель сам задаёт лейаут.
+- `forwardRef<HTMLDivElement>` — не убирать. Ref указывает на корневой `div` — тот же
+  элемент, который получает `className` и `...rest`.
+- Корневой элемент — ровно один `div`, а `children` рендерятся в него напрямую, без
+  промежуточных обёрток. Уровень вложенности виден потребителям в DOM и в их CSS-селекторах,
+  поэтому добавление обёртки — наблюдаемое изменение и требует записи в release notes.
+- Компонент не задаёт собственных классов и отступов. Появление здесь `margin`/`gap`
+  сдвинет вёрстку всех форм в библиотеке и у потребителей: `FormGroup` используется внутри
+  `TextFieldBase` (а через него — во всех полях, построенных на нём: `TextField`,
+  `MaskedField`, `TextareaField`, `AmountField`, `NumberField`, `SuggestField`) и в
+  `SMSFieldInput`.
+- `displayName = "FormGroup"` — не менять.
+- Экспорт `FormGroup` идёт в barrel `src/components/FormGroup/index.ts` и далее в корневой
+  `src/components/index.ts` — сохранять. `IFormGroupProps` наружу не экспортируется; добавление
+  этого экспорта — расширение публичного API, отдельное решение владельца.
 
 ---
 
 ## Accessibility
 
-- `<div>` без ARIA-роли. Если группа полей должна объявляться как
-  `role="group"`/`role="radiogroup"` — потребитель передаёт `role` и
-  `aria-labelledby`/`aria-label` через `...rest`.
-- Fieldset-семантика (`<fieldset>` + `<legend>`) не используется;
-  FormGroup не пытается её эмулировать.
-
----
-
-## Дизайн-токены
+Собственного a11y-поведения нет: это структурный контейнер без роли и без интерактивности.
+Семантику задаёт потребитель через проброшенные атрибуты — например `role="group"` вместе с
+`aria-labelledby`, если группа должна объявляться скринридером как единое целое.
 
-Нет.
+Лейбл связывается с полем внутри `FormField`: `FormFieldLabel` берёт `htmlFor` из `targetId`
+в `FormFieldContext`. Описание автоматически не связывается — `aria-describedby` на элементе
+ввода (как и `aria-invalid` для ошибки) задаёт потребитель, см. `FormField-ai.md`. `FormGroup`
+не участвует ни в том, ни в другом.
 
 ---
 
 ## Связанные компоненты
 
-- `FormField` — основной контент внутри FormGroup.
-- `HelpBox`, `Alert` — вспомогательные элементы формы.
-- `Row`, `Col`, `Gap` — предпочтительны, если нужен layout, а не именованная группа.
+- `FormField` — само поле ввода; основной ребёнок группы. О `FormGroup` не знает и на нём
+  не построен: это `FormField` кладут внутрь группы, а не наоборот.
+- `FormFieldDescription` (часть семейства `FormField`) — описание, текст ошибки и счётчик
+  под полем; второй типичный ребёнок группы, отступ от поля задаёт сам (`padding-top`).
+- `TextField`, `MaskedField` — готовые однострочные поля; компактная альтернатива ручной
+  сборке `FormGroup` + `FormField`. Внутри они уже используют `FormGroup` (через
+  `TextFieldBase`), поэтому оборачивать их в него ещё раз не нужно.
+- `HelpBox`, `AlertContext` — подсказка и сообщение, которые кладут в группу рядом с полем.
 
 ---
 
 ## Stories
 
-Нет собственных stories. Используется в примерах `TextField`, `SelectField`,
-`SelectExtendedField`, `FormField`.
+Основные истории: `stories/FormGroup/FormGroup.stories.tsx`
+Файлы примеров: `stories/FormGroup/examples/`
+
+| Story         | Example file      | Что демонстрирует                                                                     |
+| ------------- | ----------------- | ------------------------------------------------------------------------------------- |
+| `Default`     | `Default.tsx`     | Минимальная группа: поле с лейблом и описанием под ним                                |
+| `Example`     | `Example.tsx`     | Production-like форма: поле с описанием и поле с ошибкой плюс `AlertContext` в группе |
+| `VisualTests` | `VisualTests.tsx` | Варианты наполнения: только поле, поле с описанием, ошибка, группа с `AlertContext`, поле с `HelpBox` |
+
+### Почему stories участвуют в скриншот-тестах
+
+Своей разметки у `FormGroup` нет, поэтому baseline'ы (`__screenshots__/formgroup--*`)
+фиксируют не саму группу, а композицию её частей: `FormField`, `FormFieldDescription`,
+`AlertContext`, `HelpBox`. Формально это близко к случаю «компонент без визуального
+интерфейса» из `stories-guide.md` § «Скриншот-тесты», где набор исключают целиком через
+`testRunner: { skip: true }`. Здесь решено baseline'ы держать: они страхуют типовые
+композиции форм, которые потребители копируют из примеров. Обратная сторона — перекраска
+`FormField` или `AlertContext` роняет визуальные тесты `FormGroup` и требует перегенерации;
+это ожидаемо, а не регрессия группы. Отсутствие лишней обёртки вокруг `children` проверяет
+unit-тест, а не скриншот.
 
 ---
 
 ## История изменений
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |
+| Дата       | Изменение                                                                                                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-08-28 | Создан документ. AI-рефакторинг (уточнён JSDoc компонента, `children` задокументирован явно), добавлены unit-тесты и stories в modern pattern. Публичный API не менялся. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/FormGroup/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    FormGroup,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value={value} onChange={(event) => setValue(event.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
+
+### Example
+
+`stories/FormGroup/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    AlertContext,
+    EAlertType,
+    EFontType,
+    EFormFieldStatus,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    FormGroup,
+    Gap,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [account, setAccount] = useState("40702810400000012345");
+    const [amount, setAmount] = useState("");
+
+    return (
+        <div style={{ maxWidth: "360px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Счёт списания</FormFieldLabel>
+                    <FormFieldInput value={account} onChange={(event) => setAccount(event.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Доступно 125 000,00 ₽
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+
+            <Gap size={24} />
+
+            <FormGroup>
+                <FormField status={EFormFieldStatus.ERROR}>
+                    <FormFieldLabel>Сумма платежа</FormFieldLabel>
+                    <FormFieldInput
+                        value={amount}
+                        onChange={(event) => setAmount(event.target.value)}
+                        aria-invalid
+                        aria-describedby="amount-error"
+                    />
+                </FormField>
+                <FormFieldDescription id="amount-error">
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.ERROR}>
+                        Укажите сумму платежа
+                    </Text>
+                </FormFieldDescription>
+
+                <Gap size={8} />
+
+                <AlertContext type={EAlertType.INFO}>
+                    Платёж на сумму более 150 000 ₽ уходит в банк на подтверждение.
+                </AlertContext>
+            </FormGroup>
+        </div>
+    );
+};
+```
+