@sberbusiness/triplex-next-mcp-server 0.36.0-beta0 → 1.41.0-beta

package/bundle/components/FormField.md

@@ -1,9 +1,7 @@
 ---
 component: FormField
-category: Forms
-figma-node: ""
-figma-file: ""
-related: [TextField, TextareaField, NumberField, AmountField, DateField, MonthYearField, SMSField, SelectField, SuggestField, MultiselectField, FormGroup, Button, ButtonIcon]
+category: FormField
+related: [FormFieldLabel, FormFieldInput, FormFieldTextarea, FormFieldTarget, FormFieldMaskedInput, FormFieldPrefix, FormFieldPostfix, FormFieldClear, FormFieldDescription, FormFieldCounter, FormGroup, TextField, TextareaField, MaskedField, SelectField, SuggestField, DateField]
 tokens:
   - --triplex-next-FormField-Background_Default
   - --triplex-next-FormField-Background_Hover
@@ -33,294 +31,532 @@ version: "1.0"
 
 ## Назначение
 
-Низкоуровневый **compound-примитив** для построения полей ввода: контейнер,
-который управляет визуальным состоянием (hover/active/focus/filled/error/warning/disabled),
-плавающим лейблом и отступами под prefix/postfix. Сам по себе не рендерит
-`<input>` — принимает свои под-компоненты (`FormFieldInput`, `FormFieldTextarea`,
-`FormFieldMaskedInput`, `FormFieldTarget`, `FormFieldLabel`, `FormFieldPrefix`,
-`FormFieldPostfix`, `FormFieldClear`, `FormFieldDescription`, `FormFieldCounter`).
+Низкоуровневый контейнер поля ввода: рисует фон, скругление, обводку и состояния (default / error / warning / disabled, активное и заполненное), а также раздаёт вложенным субкомпонентам общий контекст (`FormFieldContext`) — размер, статус, фокус, заполненность, идентификаторы элемента ввода и лейбла, ширины префикса и постфикса.
 
-Используй `FormField` когда: строишь новый тип поля ввода, которого нет в
-готовых обёртках (`TextField`, `NumberField`, `DateField` и т.п.).
-Не используй напрямую когда: для типового текстового поля подходит
-`TextField` — он уже собирает `FormField` + `FormFieldInput` + `FormFieldLabel`.
+Используй когда: собираешь поле из частей вручную — `FormFieldLabel` + один из элементов ввода (`FormFieldInput` / `FormFieldTextarea` / `FormFieldMaskedInput` / `FormFieldTarget`) + опционально `FormFieldPrefix` / `FormFieldPostfix` / `FormFieldDescription` / `FormFieldCounter`, либо строишь на его основе собственный field-компонент.
 
----
-
-## Файловая структура
-
-```text
-src/components/FormField/
-├── FormField.tsx                       # Корневой контейнер, Provider контекста
-├── FormFieldContext.ts                 # IFormFieldContext (size/status/ids/widths/filled/focused)
-├── FormFieldDescriptionContext.ts      # Контекст для Description/Counter (withCounter)
-├── enums.ts                            # EFormFieldStatus
-├── consts.ts                           # TARGET_PADDING_X_DEFAULT = 12
-├── types.ts                            # TFormFieldMaskedInputMask
-├── index.ts                            # Barrel: все компоненты, enums, types
-├── components/
-│   ├── FormFieldInput.tsx              # <input>, поддерживает render-функцию
-│   ├── FormFieldTextarea.tsx           # <textarea>
-│   ├── FormFieldMaskedInput.tsx        # Маскированный инпут (react-text-mask)
-│   ├── FormFieldMaskedInputPresets.ts  # Готовые маски: phone, inn, snils, date и т.д.
-│   ├── FormFieldTarget.tsx             # Нередактируемое значение (для select-подобных)
-│   ├── FormFieldLabel.tsx              # Плавающий label
-│   ├── FormFieldPrefix.tsx             # Левый слот, измеряет ширину → context
-│   ├── FormFieldPostfix.tsx            # Правый слот, измеряет ширину → context
-│   ├── FormFieldClear.tsx              # Кнопка очистки (ButtonIcon с иконкой X)
-│   ├── FormFieldDescription.tsx        # Описание под полем
-│   ├── FormFieldCounter.tsx            # Счётчик символов (внутри Description)
-│   └── utils.ts                        # isFilled()
-├── styles/
-│   ├── FormField.module.less           # Размеры/статусы/hover/active
-│   └── FormField*.module.less          # По одному на под-компонент
-└── __tests__/
-    ├── FormField.test.tsx              # error/disabled/focus/props-passthrough
-    └── FormFieldInput.test.tsx
-```
+Не используй когда: достаточно готовой обёртки — `TextField` (однострочный ввод), `TextareaField` (многострочный), `MaskedField` (маска), `SelectField` / `SuggestField` / `DateField` (выбор значения). `FormGroup` альтернативой не является: это контейнер, внутрь которого кладут само поле вместе с сообщением об ошибке.
 
 ---
 
-## Compound-структура
-
-Составляется вручную (не через `Object.assign`), потомки — отдельные
-экспорты, которые читают `FormFieldContext`:
-
-```tsx
-<FormField size={EComponentSize.LG} status={EFormFieldStatus.DEFAULT}>
-    <FormFieldPrefix>{/* иконка слева */}</FormFieldPrefix>
-    <FormFieldLabel>Название поля</FormFieldLabel>
-    <FormFieldInput value={value} onChange={onChange} />
-    <FormFieldPostfix>
-        <FormFieldClear onClick={handleClear} />
-        {/* или счётчик, иконка, тд */}
-    </FormFieldPostfix>
-    <FormFieldDescription>
-        Текст описания
-        <FormFieldCounter>{value.length} / 100</FormFieldCounter>
-    </FormFieldDescription>
-</FormField>
-```
+## Варианты и props
 
-Корневой `FormField` — provider `FormFieldContext`. Контекст хранит `size`,
-`status`, `targetId`, `labelId`, `prefixWidth`, `postfixWidth`, `filled`,
-`focused`, `active` и сеттеры. Под-компоненты читают/пишут это состояние.
+`FormField` — контейнер и провайдер контекста. Собственного «значения» у него нет: состояния `filled` и `focused` вычисляются вложенными элементами ввода и поднимаются в контекст через сеттеры.
 
----
+### Обязательные props
 
-## Варианты и props
+Обязательных custom-props нет. Практически всегда передаётся `children` — субкомпоненты семейства.
 
-### FormField — `IFormFieldProps extends React.HTMLAttributes<HTMLDivElement>`
+### Опциональные props
 
-| Prop | Тип | Default | Описание |
+| Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `size` | `EComponentSize` | `LG` | Размер (`SM`/`MD`/`LG`); управляет высотой, радиусом, шрифтом. |
-| `status` | `EFormFieldStatus` | `DEFAULT` | `DEFAULT` / `DISABLED` / `ERROR` / `WARNING`. |
-| `active` | `boolean` | `false` | Принудительно активное состояние (например, при открытом dropdown). Фактическое `active` в контексте = `active || focused`. |
-| `className`, `style`, `...HTMLDivAttributes`, `data-*` | — | — | Стандартные. Padding-Left/Right перезаписывается на ширины prefix/postfix. |
-
-### EFormFieldStatus
+| `size` | `EComponentSize` | `EComponentSize.LG` | Размер поля: `SM` / `MD` / `LG`. Влияет на скругление корневого элемента и через контекст — на размеры лейбла, элемента ввода и плейсхолдера маски. |
+| `status` | `EFormFieldStatus` | `EFormFieldStatus.DEFAULT` | Визуальное состояние: `DEFAULT` / `ERROR` / `WARNING` / `DISABLED`. `DISABLED` дополнительно проставляет `disabled` вложенным `input`/`textarea` и `aria-disabled` + `tabIndex={-1}` у `FormFieldTarget`. |
+| `active` | `boolean` | `false` | Принудительно активное состояние (например, когда фокус визуально принадлежит связанному dropdown). Итоговая активность = `active \|\| focused`. |
 
-| Значение | Эффект |
-|---|---|
-| `DEFAULT` | Обычное состояние. |
-| `DISABLED` | Визуально disabled; `FormFieldInput`/`FormFieldTextarea` проставляют `disabled`, `FormFieldTarget` получает `tabIndex=-1` и `aria-disabled`. |
-| `ERROR` | Красный фон/шейдоу. |
-| `WARNING` | Жёлтый фон/шейдоу. |
+Остальные props — стандартные атрибуты `div` и `data-*`, они пробрасываются на корневой элемент.
 
-### Под-компоненты — ключевые props
+### Особенности поведения
 
-| Компонент | Важные props | Заметки |
-|---|---|---|
-| `FormFieldInput` | `render?: (props, ref) => ReactNode`, все `InputHTMLAttributes` | `render` позволяет подключить сторонний `<input>` (валидация, маска), получая наши стили/id/onFocus/onBlur. |
-| `FormFieldTextarea` | все `TextareaHTMLAttributes` | Симметричен Input, без `render`. |
-| `FormFieldMaskedInput` | `value: string`, `mask: TFormFieldMaskedInputMask`, `placeholderMask?`, `placeholderChar = "0"` | Использует `react-text-mask`. `presets` — статичное поле с готовыми масками (`phone`, `inn`, `cardNumber`, `snils`, `date`, `swiftCode` и др.) и их placeholder'ами. |
-| `FormFieldTarget` | `placeholder?: ReactNode` | Нередактируемый `<div>` с `tabIndex=0`, `aria-labelledby`, для select-подобных обёрток. Placeholder — только при отсутствии children. |
-| `FormFieldLabel` | `floating?: boolean` | По умолчанию `floating = filled || active`. Принудительный `floating` нужен редко (например, когда поле всегда с плавающим лейблом). `htmlFor` ставится из контекста — не передавать вручную (тип `Omit<..., "htmlFor">`). |
-| `FormFieldPrefix` / `FormFieldPostfix` | все `HTMLAttributes<HTMLSpanElement>` | Меряют `getBoundingClientRect().width` и пишут в `FormFieldContext`, чтобы контейнер получил корректные `padding-left/right`, а label не залез под иконки. |
-| `FormFieldClear` | все `ButtonHTMLAttributes<HTMLButtonElement>` кроме `children` | Рендерит `ButtonIcon` с `CrossStrokeSrvIcon16`. `onMouseDown` вызывает `preventDefault` — кнопка не забирает фокус у поля при клике. |
-| `FormFieldDescription` / `FormFieldCounter` | `HTMLAttributes<HTMLDivElement>` | `Counter` монтирует флаг `withCounter` в `FormFieldDescriptionContext`, который меняет layout Description (для корректного расположения текста и счётчика). |
+- Горизонтальные внутренние отступы корневого `div` задаются инлайн-стилем из ширин префикса и постфикса (`paddingLeft: prefixWidth`, `paddingRight: postfixWidth`). Значение по умолчанию — `TARGET_PADDING_X_DEFAULT` (12px); `FormFieldPrefix` / `FormFieldPostfix` измеряют себя через `ResizeObserver` и обновляют его. Пользовательский `style` мерджится последним и может переопределить отступы.
+- Класс `filled` выставляется, когда вложенный элемент ввода сообщил о наличии значения. Для `FormFieldInput` / `FormFieldTextarea` это включает браузерное автозаполнение (ловится через CSS-анимационные хуки `autofill-applied-hook` / `autofill-cancelled-hook`), для `FormFieldTarget` — наличие `children`.
+- Кнопка `FormFieldClear` показывается стилями только при `filled` и hover/активном состоянии непустого и не заблокированного поля, а также при собственном фокусе (`:focus`) — чтобы кнопка оставалась видимой при клавиатурной навигации.
+- Идентификаторы генерируются субкомпонентами (`uniqueId` из `lodash-es`, не `React.useId` — код должен оставаться совместимым с React 17) и попадают в контекст как `targetId` / `labelId`; на них опирается связка `label[htmlFor]` ↔ элемент ввода.
+- Вне `FormField` субкомпоненты используют `initialFormFieldContext`, где `filled: true` — это осознанный временный фикс для `DropdownMobileHeader`, а сеттеры являются no-op.
 
 ---
 
-## Ключевые особенности реализации
-
-### Контекст — источник истины
-
-- `FormField` хранит всё состояние (`useState` внутри корня), собирает его в `IFormFieldContext` через `useMemo` и отдаёт через Provider.
-- Под-компоненты **только читают** контекст (`size`, `status`, `filled`, `focused`, `active`, ширины) и **вызывают сеттеры** (`setFilled`, `setFocused`, `setTargetId`, `setLabelId`, `setPrefixWidth`, `setPostfixWidth`).
-- Корневому `FormField` не нужно `value` — `filled` управляется через `FormFieldInput`/`FormFieldTextarea`/`FormFieldTarget` на основе их значения (см. `isFilled`).
-
-### Автоматическое `padding-left/right` от prefix/postfix
+## Дизайн-токены
 
-`FormField` пишет в inline style:
-```ts
-style={{ paddingLeft: prefixWidth, paddingRight: postfixWidth, ...style }}
 ```
-`FormFieldPrefix`/`FormFieldPostfix` после рендера делают `getBoundingClientRect().width` → пишут в контекст → корень перерендеривается с новым padding. Если prefix/postfix меняют ширину динамически (например, текстом) — padding обновится на следующем рендер-цикле.
+--triplex-next-FormField-Background_Default
+--triplex-next-FormField-Background_Hover
+--triplex-next-FormField-Background_Active
+--triplex-next-FormField-Background_Disabled
+--triplex-next-FormField-Background_Error
+--triplex-next-FormField-Background_Error_Hover
+--triplex-next-FormField-Background_Warning
+--triplex-next-FormField-Background_Warning_Hover
+--triplex-next-FormField-Shadow_Default
+--triplex-next-FormField-Shadow_Active
+--triplex-next-FormField-Shadow_Error_Active
+--triplex-next-FormField-Shadow_Warning_Active
+--triplex-next-FormField-Input_Color_Default
+--triplex-next-FormField-Input_Color_Disabled
+--triplex-next-FormField-Label_Color_Default
+--triplex-next-FormField-Label_Color_Disabled
+--triplex-next-FormField-Placeholder_Color
+--triplex-next-FormField-Target_Color_Default
+--triplex-next-FormField-Target_Color_Disabled
+--triplex-next-FormField-Target_PlaceholderColor_Default
+```
 
-`FormFieldLabel` использует те же `prefixWidth`/`postfixWidth` для вычисления `left`/`right`, чтобы плавающий label был ровно над инпутом, не под иконками.
+---
 
-Дефолт `TARGET_PADDING_X_DEFAULT = 12` — стартовое значение до первого измерения префикса/постфикса (и когда их нет).
+## Инварианты
 
-### Floating label — `filled || active`
+- `forwardRef` обязателен, ref ведёт на корневой `div`; корневой элемент менять нельзя.
+- `EFormFieldStatus` и его строковые значения (`default` / `disabled` / `error` / `warning`) — публичный API, как и props `size` / `status` / `active`.
+- Barrel `src/components/FormField/index.ts` реэкспортирует `enums`, `types`, `components` и сам `FormField` — состав экспортов не сокращать. Маппинг статуса на класс (`STATUS_TO_CLASS_NAME_MAP`) — внутренняя константа модуля и в barrel не входит.
+- `FormFieldContext` и `FormFieldDescriptionContext` в barrel не входят: это внутренний механизм семейства, но на нём завязаны все субкомпоненты — менять форму значения контекста без правки субкомпонентов нельзя.
+- Классы `formField`, `filled`, `active`, `error`, `warning`, `disabled`, а также `sm` / `md` / `lg` проверяются unit-тестами и используются в вложенных селекторах стилей семейства.
+- Генерация id — через `uniqueId` (`lodash-es`), без `React.useId`: ветка `release-0` собирается на React 17.
+- `FormFieldDescription` и `FormFieldCounter` объявлены как `React.FC` без `forwardRef` — осознанное историческое отличие от остальных субкомпонентов. Добавление ref расширяет публичный API; решение владельца — оставить как есть.
+- Внутренние утилиты семейства (`components/utils.ts` — `isFilled`, `setForwardedRef`; `components/useFormFieldAffixWidth.ts`) намеренно не попадают в barrel `components/index.ts`.
+- Компонент не рендерит собственных подписей и текстов — библиотека мультиязычная.
 
-Label плавает наверх, когда:
-- поле заполнено (`filled`), либо
-- поле активно (`active === active-prop || focused`).
+---
 
-`FormFieldInput`/`FormFieldTextarea` вычисляют `filled` через `isFilled(value)`:
-- `undefined` → `false`
-- `number` → `true`
-- строка → `value.length !== 0`
+## Accessibility
 
-Для select-подобных обёрток `FormFieldTarget` пишет `filled = children.length !== 0`.
+- Корневой элемент — обычный `div` без роли: семантику даёт вложенный нативный `input` / `textarea`.
+- Связка лейбла и поля: `FormFieldLabel` получает `htmlFor={targetId}` из контекста, элемент ввода — сгенерированный `id`. Поэтому `screen.getByLabelText(...)` находит поле, а клик по лейблу фокусирует ввод.
+- `FormFieldTarget` (нередактируемое значение, например для select-подобных полей) получает `tabIndex={0}`, `aria-labelledby={labelId}` и `aria-disabled`; при `status = DISABLED` — `tabIndex={-1}`.
+- При `status = DISABLED` вложенные `input` / `textarea` получают нативный `disabled`, то есть выпадают из таб-порядка.
+- Плейсхолдер маски в `FormFieldMaskedInput` рендерится с `aria-hidden="true"` — скринридер читает только реальное значение input.
+- Текст описания (`FormFieldDescription`) визуально связан с полем, но не связывается автоматически через `aria-describedby` — при необходимости потребитель передаёт `aria-describedby` элементу ввода сам.
 
-Принудительно задать `floating` можно prop'ом (для кейсов, где лейбл всегда сверху — например, поле с картинками).
+---
 
-### Autofill detection через CSS-анимации
+## Связанные компоненты
 
-`FormFieldInput`/`FormFieldTextarea` слушают `onAnimationStart` и проверяют `animationName`:
-- `autofill-applied-hook*` → `setFilled(true)`
-- `autofill-cancelled-hook*` → `syncFilled(value)`
+- `FormFieldLabel` — плавающий лейбл; поднимается над полем, когда поле заполнено или активно (можно форсировать props `floating`).
+- `FormFieldInput` — однострочный ввод; поддерживает render-prop `render` для подмены инпута с сохранением стилизации.
+- `FormFieldTextarea` — многострочный ввод.
+- `FormFieldMaskedInput` — маскированный ввод на базе `react-text-mask`; содержит пресеты масок (`FormFieldMaskedInput.presets`).
+- `FormFieldTarget` — нередактируемое значение с `placeholder`, используется select-подобными полями.
+- `FormFieldPrefix` / `FormFieldPostfix` — контейнеры слева/справа; их измеренная ширина становится внутренним отступом поля. Общая логика измерения и проброса ref вынесена во внутренний хук `components/useFormFieldAffixWidth.ts` (в barrel не экспортируется).
+- `FormFieldClear` — кнопка очистки (`ButtonIcon` с иконкой креста), гасит фокус на `mousedown`.
+- `FormFieldDescription` — описание под полем; провайдер `FormFieldDescriptionContext`.
+- `FormFieldCounter` — счётчик символов внутри описания; сообщает `FormFieldDescription` о своём наличии.
+- `TextField`, `TextareaField`, `MaskedField`, `SelectField`, `SuggestField`, `DateField` — компоненты уровнем выше, построенные на этом семействе.
+- `FormGroup` — контейнер формы (`div` без собственной логики), объединяющий поле с `HelpBox` / `Alert` / описанием. О `FormField` ничего не знает и на семействе не построен: поле кладут внутрь него.
 
-Это единственный способ отловить браузерное автозаполнение, которое не триггерит `onChange`. Стороны анимации объявлены в CSS. Не ломать имена — они парсятся в JS.
+---
 
-### `FormFieldInput.render` — точка расширения
+## Stories
 
-Через `render` пробрасываются все общие props (стили, id, `onFocus/onBlur`, `onAnimationStart`, `onChange`, `disabled`, `size`) и ref. Используется, например, в `FormFieldMaskedInput` — чтобы обернуть `react-text-mask`.
+Основные истории: `stories/FormField/FormField.stories.tsx`
+Файлы примеров: `stories/FormField/examples/`
 
-### `FormFieldMaskedInput` — рендерит ДВА инпута
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `status`, `size`, лейбла, плейсхолдера и описания |
+| `Default` | `DefaultExample.tsx` | Минимальная композиция: лейбл + input |
+| `WithPrefixAndPostfix` | `WithPrefixAndPostfixExample.tsx` | Контент слева и справа от поля и влияние на отступы |
+| `WithClearButton` | `WithClearButtonExample.tsx` | Кнопка очистки значения в постфиксе |
+| `WithCounter` | `WithCounterExample.tsx` | Описание со счётчиком символов |
+| `States` | `StatesExample.tsx` | Статусы default / error / warning / disabled |
+| `Textarea` | `TextareaExample.tsx` | Многострочный ввод |
+| `Sizes` | `SizesExample.tsx` | Размеры `SM` / `MD` / `LG` |
+| `MaskedInput` | `MaskedInputExample.tsx` | Маскированный ввод и пресеты масок |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия: состояния и размеры на одной странице |
 
-- Первый (readOnly, `tabIndex=-1`, `aria-hidden`) — рисует placeholder-маску (например, `дд.мм.гггг`).
-- Второй (`react-text-mask`) — принимает ввод, без guide'а, `value` берёт через `conformToMask`.
-- Это интегрированное legacy-решение — не заменять на один инпут без согласования, placeholder-маска с подсветкой уже введённых символов требует двухслойной разметки.
-- Специальная обработка для масок `phone` и `swiftCode` через `pipe` (нормализация `7`/`8` → `+7 (`, uppercase для SWIFT).
+---
 
-### `FormFieldClear` — `preventDefault` на mouseDown
+## История изменений
 
-Кнопка очистки лежит в `FormFieldPostfix`. При клике `onMouseDown` вызывает `event.preventDefault()` — иначе поле теряет фокус (= `focused = false`, = label падает, = filled пересчитывается по пустому значению). Не удалять этот обработчик.
+| Дата | Изменение |
+|---|---|
+| 2026-07-31 | Создан документ. AI-рефакторинг FormField: JSDoc на props, enum, контекстах и константах, активное состояние вычисляется одним выражением, контекст типизирован `IFormFieldContext`, unit-тесты расширены с 4 до 23 кейсов. Публичный API не изменён. |
+| 2026-07-31 | AI-рефакторинг распространён на субкомпоненты `FormFieldInput`, `FormFieldLabel`, `FormFieldPrefix`, `FormFieldPostfix`, `FormFieldClear`, `FormFieldDescription`, `FormFieldCounter`: JSDoc с указанием значений по умолчанию, дедупликация `FormFieldPrefix` / `FormFieldPostfix` через внутренний хук `useFormFieldAffixWidth`, общий `setForwardedRef` в `components/utils.ts`, unit-тесты. Публичный API не изменён. `FormFieldTextarea`, `FormFieldTarget` и `FormFieldMaskedInput` намеренно не затронуты — их покрывают задачи `TextareaField`, `SelectField` и `MaskedField`. |
+| 2026-07-31 | Исправлено: `className` у `FormFieldDescription` и `FormFieldCounter` затирал базовый класс — теперь объединяется через `clsx`. Изменение наблюдаемого поведения, зафиксировано в release notes 1.41.0. |
+| 2026-08-03 | Ломающее изменение: `statusToClassNameMap` убран из публичного barrel и переименован во внутреннюю константу `STATUS_TO_CLASS_NAME_MAP`. Зафиксировано в release notes 1.41.0. |
 
-Видимость `FormFieldClear` управляется CSS в `FormField.module.less`:
-```less
-&.filled:not(.disabled) {
-    &:hover, &.active {
-        .formFieldClear { visibility: visible; opacity: 1; pointer-events: auto; }
-    }
-}
-```
-Кнопка появляется только когда поле заполнено и в hover/active. Если компонент Clear используется вне FormField (редкий кейс) — видимость нужно задавать вручную.
+---
 
-### ID-связка label ↔ target
+## Примеры использования
 
-- Каждый target-компонент (`Input`/`Textarea`/`Target`) генерирует `id` через `uniqueId("input_"/"textarea_"/"target_")`, если не передан снаружи, и пишет его в `FormFieldContext.targetId` через `useLayoutEffect`.
-- `FormFieldLabel` берёт `targetId` из контекста и ставит в `htmlFor`.
-- `FormFieldLabel` сам генерирует `id` и пишет в `labelId` → `FormFieldTarget` использует его как `aria-labelledby`.
+### Default
 
-Из-за `uniqueId` (lodash-es, модульный счётчик) id'ы не SSR-safe. Это осознанный legacy-выбор; при SSR используй `id` prop с явным значением.
+`stories/FormField/examples/DefaultExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import { FormField, FormFieldInput, FormFieldLabel } from "@sberbusiness/triplex-next";
+
+export const DefaultExample = () => {
+    const [value, setValue] = useState("");
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormField>
+                <FormFieldLabel>Название поля</FormFieldLabel>
+                <FormFieldInput
+                    value={value}
+                    onChange={(e) => setValue(e.target.value)}
+                    placeholder="Введите текст..."
+                />
+            </FormField>
+        </div>
+    );
+};
+```
 
-## Инварианты
+### WithPrefixAndPostfix
 
-- **`forwardRef`** — на всех under компонентах кроме `FormFieldDescription` и `FormFieldCounter` (они `React.FC`, т.к. не ожидается ref наружу). `FormField`, `FormFieldInput`, `FormFieldTextarea`, `FormFieldTarget`, `FormFieldLabel`, `FormFieldPrefix`, `FormFieldPostfix`, `FormFieldClear` — обязательно `forwardRef`.
-- **`IFormFieldContext` shape** — изменение полей/сеттеров ломает все под-компоненты и внешние обёртки (`TextField` и т.д.). Добавлять аккуратно.
-- **`FormField` корень** переопределяет `paddingLeft`/`paddingRight` из `style` значениями из контекста — передавать свои padding'и через `style` бесполезно, их затрёт. Документировать для потребителей.
-- **Имена animation `autofill-applied-hook*` / `autofill-cancelled-hook*`** — завязаны на CSS; при переименовании обновить оба места.
-- **`EFormFieldStatus` значения** — публичный API, используются в `TextField`, `NumberField` и т.д.
-- **`FormFieldMaskedInput.presets`** — публичный API (импортируется пользователями для переиспользования масок). Новые маски можно добавлять, существующие — не переименовывать и не менять форму.
-- **`FormFieldClear.onMouseDown → preventDefault`** — не удалять (иначе фокус уходит при клике на очистку).
-- **Ширина prefix/postfix пишется на каждом рендере** (`useEffect` без deps в `FormFieldPrefix`/`FormFieldPostfix`). Это намеренно — измеряем после каждого рендера, защита от зависимостей-гонок. При изменении помни про бесконечный ре-рендер: записываем в context, только если `width !== prefixWidth`.
-- **`FormFieldInput` в `useLayoutEffect` с `[]` deps** делает первичную синхронизацию `filled` без warning'а — eslint отключён специально. Не включать зависимости.
+`stories/FormField/examples/WithPrefixAndPostfixExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import { DefaulticonStrokePrdIcon20 } from "@sberbusiness/icons-next";
+import {
+    FormField,
+    FormFieldInput,
+    FormFieldLabel,
+    FormFieldPostfix,
+    FormFieldPrefix,
+    HelpBox,
+    ETooltipPreferPlace,
+    ETooltipSize,
+} from "@sberbusiness/triplex-next";
+
+export const WithPrefixAndPostfixExample = () => {
+    const [value, setValue] = useState("");
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormField>
+                <FormFieldPrefix>
+                    <DefaulticonStrokePrdIcon20 paletteIndex={5} />
+                </FormFieldPrefix>
+                <FormFieldLabel>Название поля</FormFieldLabel>
+                <FormFieldInput value={value} onChange={(e) => setValue(e.target.value)} />
+                <FormFieldPostfix>
+                    <HelpBox tooltipSize={ETooltipSize.SM} preferPlace={ETooltipPreferPlace.ABOVE}>
+                        Text
+                    </HelpBox>
+                </FormFieldPostfix>
+            </FormField>
+        </div>
+    );
+};
+```
 
-## Accessibility
+### WithClearButton
 
-- **`<input>`/`<textarea>`** — нативные, полная поддержка клавиатуры. `disabled` ставится библиотекой, когда `status === DISABLED`.
-- **`FormFieldTarget`** — не нативный input, поэтому:
-  - `tabIndex=0` в обычном состоянии, `-1` при `DISABLED`.
-  - `aria-labelledby={labelId}` — связь с `FormFieldLabel`.
-  - `aria-disabled` при `DISABLED`.
-- **`FormFieldLabel`** — нативный `<label htmlFor={targetId}>`, связь через контекст.
-- **Без хардкода текста** — подписи, placeholder'ы, `aria-label` пишет потребитель (мультиязычность).
-- **`FormFieldClear`** — это `ButtonIcon` (без видимого текста). Потребитель **обязан** передать `aria-label` через `...rest`.
-- **`FormFieldMaskedInput`** — первый (placeholder-)input помечен `aria-hidden="true"` и `tabIndex={-1}`, скринридер читает только второй (реальный) инпут.
-- **Статусы `ERROR`/`WARNING`** не выставляют `aria-invalid` автоматически. Если нужно — потребитель передаёт `aria-invalid` в props инпута.
+`stories/FormField/examples/WithClearButtonExample.tsx`
 
----
+```tsx
+import React, { useState } from "react";
+import {
+    FormField,
+    FormFieldClear,
+    FormFieldInput,
+    FormFieldLabel,
+    FormFieldPostfix,
+    HelpBox,
+    ETooltipPreferPlace,
+    ETooltipSize,
+} from "@sberbusiness/triplex-next";
+
+export const WithClearButtonExample = () => {
+    const [value, setValue] = useState("");
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormField>
+                <FormFieldLabel>Название поля</FormFieldLabel>
+                <FormFieldInput value={value} onChange={(e) => setValue(e.target.value)} />
+                <FormFieldPostfix>
+                    <FormFieldClear onClick={() => setValue("")} />
+                    <HelpBox tooltipSize={ETooltipSize.SM} preferPlace={ETooltipPreferPlace.ABOVE}>
+                        Text
+                    </HelpBox>
+                </FormFieldPostfix>
+            </FormField>
+        </div>
+    );
+};
+```
 
-## Дизайн-токены
+### WithCounter
 
-**Корневой контейнер (`FormField.module.less`):**
-```
---triplex-next-FormField-Background_Default
---triplex-next-FormField-Background_Hover
---triplex-next-FormField-Background_Active
---triplex-next-FormField-Background_Disabled
---triplex-next-FormField-Background_Error[_Hover]
---triplex-next-FormField-Background_Warning[_Hover]
---triplex-next-FormField-Shadow_Default
---triplex-next-FormField-Shadow_Active
---triplex-next-FormField-Shadow_Error_Active
---triplex-next-FormField-Shadow_Warning_Active
-```
+`stories/FormField/examples/WithCounterExample.tsx`
 
-**Текст:**
-```
---triplex-next-FormField-Input_Color_Default / _Disabled
---triplex-next-FormField-Label_Color_Default / _Disabled
---triplex-next-FormField-Placeholder_Color
---triplex-next-FormField-Target_Color_Default / _Disabled
---triplex-next-FormField-Target_PlaceholderColor_Default
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    ETextSize,
+    FormField,
+    FormFieldCounter,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const WithCounterExample = () => {
+    const [value, setValue] = useState("");
+    const maxLength = 201;
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormField>
+                <FormFieldLabel>Название поля</FormFieldLabel>
+                <FormFieldInput
+                    value={value}
+                    onChange={(e) => e.target.value.length <= maxLength && setValue(e.target.value)}
+                />
+            </FormField>
+            <FormFieldDescription>
+                <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                    Описание поля
+                </Text>
+                <FormFieldCounter>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        {value.length}/{maxLength}
+                    </Text>
+                </FormFieldCounter>
+            </FormFieldDescription>
+        </div>
+    );
+};
 ```
 
-Border-radius задан литералами в `.sm` / `.md` / `.lg`:
-- `SM` → 6px
-- `MD` → 8px
-- `LG` → 10px
+### States
 
----
+`stories/FormField/examples/StatesExample.tsx`
 
-## Связанные компоненты
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    EFormFieldStatus,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    FormGroup,
+    Gap,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const StatesExample = () => {
+    const [v, setV] = useState("");
+    const [e, setE] = useState("");
+    const [w, setW] = useState("");
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Default</div>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value={v} onChange={(x) => setV(x.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+            <Gap size={24} />
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Error</div>
+            <FormGroup>
+                <FormField status={EFormFieldStatus.ERROR}>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value={e} onChange={(x) => setE(x.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.ERROR}>
+                        Текст ошибки
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+            <Gap size={24} />
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Warning</div>
+            <FormGroup>
+                <FormField status={EFormFieldStatus.WARNING}>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value={w} onChange={(x) => setW(x.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.WARNING}>
+                        Текст предупреждения
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+            <Gap size={24} />
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>Disabled</div>
+            <FormGroup>
+                <FormField status={EFormFieldStatus.DISABLED}>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value="Value disabled" />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
 
-### Высокоуровневые обёртки (используют FormField внутри)
-- `TextField`, `TextareaField`, `SMSField`, `NumberField`, `AmountField`, `DateField`, `MonthYearField`, `DocumentNumberEdit` — типовые input-поля.
-- `SelectField`, `SelectExtendedField`, `SuggestField`, `MultiselectField` — select-подобные (внутри обычно `FormFieldTarget`).
+### Textarea
 
-### Утилитарные
-- `FormGroup` — группа `FormField`'ов в форме.
-- `Button` / `ButtonIcon` — `FormFieldClear` наследует `ButtonIcon`.
-- `Loader` — может рендериться в `FormFieldPostfix` для состояния загрузки.
+`stories/FormField/examples/TextareaExample.tsx`
 
-### Кросс-модульный импорт
-- `FormFieldClear` импортирует `ButtonIcon` из `../Button/ButtonIcon` — не дублировать.
-- `FormFieldMaskedInput` импортирует `FormFieldInput` по абсолютному пути `@sberbusiness/triplex-next/components/FormField/components/FormFieldInput` — исторически, работает.
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    ETextSize,
+    FormField,
+    FormFieldCounter,
+    FormFieldDescription,
+    FormFieldLabel,
+    FormFieldTextarea,
+    FormGroup,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const TextareaExample = () => {
+    const [value, setValue] = useState("");
+    const maxLength = 201;
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldTextarea
+                        value={value}
+                        onChange={(e) => e.target.value.length <= maxLength && setValue(e.target.value)}
+                    />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                    <FormFieldCounter>
+                        <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                            {value.length}/{maxLength}
+                        </Text>
+                    </FormFieldCounter>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
 
----
+### Sizes
 
-## Stories
+`stories/FormField/examples/SizesExample.tsx`
 
-Основные: `stories/FormField/FormField.stories.tsx`
-Примеры: `stories/FormField/examples/`
+```tsx
+import React, { useState } from "react";
+import { EComponentSize, FormField, FormFieldInput, FormFieldLabel, FormGroup } from "@sberbusiness/triplex-next";
+
+export const SizesExample = () => {
+    const [sm, setSm] = useState("");
+    const [md, setMd] = useState("");
+    const [lg, setLg] = useState("");
+    return (
+        <div style={{ maxWidth: "400px" }}>
+            <div style={{ marginBottom: "32px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>SM</div>
+                <FormGroup>
+                    <FormField size={EComponentSize.SM}>
+                        <FormFieldLabel>Маленькое поле</FormFieldLabel>
+                        <FormFieldInput
+                            value={sm}
+                            onChange={(e) => setSm(e.target.value)}
+                            placeholder="Введите текст..."
+                        />
+                    </FormField>
+                </FormGroup>
+            </div>
+            <div style={{ marginBottom: "32px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>MD</div>
+                <FormGroup>
+                    <FormField size={EComponentSize.MD}>
+                        <FormFieldLabel>Среднее поле</FormFieldLabel>
+                        <FormFieldInput
+                            value={md}
+                            onChange={(e) => setMd(e.target.value)}
+                            placeholder="Введите текст..."
+                        />
+                    </FormField>
+                </FormGroup>
+            </div>
+            <div style={{ marginBottom: "32px" }}>
+                <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>LG</div>
+                <FormGroup>
+                    <FormField size={EComponentSize.LG}>
+                        <FormFieldLabel>Большое поле</FormFieldLabel>
+                        <FormFieldInput
+                            value={lg}
+                            onChange={(e) => setLg(e.target.value)}
+                            placeholder="Введите текст..."
+                        />
+                    </FormField>
+                </FormGroup>
+            </div>
+        </div>
+    );
+};
+```
 
-| Story | Example file | Что демонстрирует |
-|---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактив: status, size, label, placeholder, description. |
-| `Default` | `DefaultExample.tsx` | Минимальная сборка FormField + Label + Input. |
-| `WithPrefixAndPostfix` | `WithPrefixAndPostfixExample.tsx` | Иконки/контент в Prefix/Postfix + автовыравнивание label. |
-| `WithClearButton` | `WithClearButtonExample.tsx` | `FormFieldClear` в Postfix, видимость при filled+hover. |
-| `WithCounter` | `WithCounterExample.tsx` | `FormFieldDescription` + `FormFieldCounter`. |
-| `States` | `StatesExample.tsx` | `DEFAULT` / `ERROR` / `WARNING` / `DISABLED`. |
-| `Textarea` | `TextareaExample.tsx` | `FormFieldTextarea` вместо Input. |
-| `Sizes` | `SizesExample.tsx` | SM / MD / LG. |
-| `MaskedInput` | `MaskedInputExample.tsx` | `FormFieldMaskedInput` c готовыми presets. |
-| `VisualTests` | `VisualTestsExample.tsx` | Screenshot-регрессия. |
+### MaskedInput
 
----
+`stories/FormField/examples/MaskedInputExample.tsx`
 
-## История изменений
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldLabel,
+    FormFieldMaskedInput,
+    FormGroup,
+    Gap,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const MaskedInputExample = () => {
+    const [phoneValue, setPhoneValue] = useState("");
+    const [cardValue, setCardValue] = useState("");
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Номер телефона</FormFieldLabel>
+                    <FormFieldMaskedInput
+                        value={phoneValue}
+                        onChange={(e) => setPhoneValue(e.target.value)}
+                        mask={FormFieldMaskedInput.presets.masks.phone}
+                    />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+            <Gap size={24} />
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Номер карты</FormFieldLabel>
+                    <FormFieldMaskedInput
+                        value={cardValue}
+                        onChange={(e) => setCardValue(e.target.value)}
+                        mask={FormFieldMaskedInput.presets.masks.cardNumber}
+                        placeholderMask={FormFieldMaskedInput.presets.placeholderMasks.cardNumber}
+                        placeholder="Введите номер карты"
+                    />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |