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

package/bundle/components/Footer.md

@@ -0,0 +1,339 @@
+---
+component: Footer
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Page, Header, Button, TableBasic]
+tokens: []
+stories: ""
+version: "1.0"
+---
+
+# Footer
+
+## Назначение
+
+Разметочный футер страницы/формы — контейнер под подвал с описанием и
+кнопками действий. **Compound-компонент**: корневой `Footer` — тонкая
+обёртка-`<div>` с `data-tx`; основная логика разметки — в
+`Footer.Description` (flex-контейнер) + его под-компоненты
+`Footer.Description.Content` (растяжимый контент слева) и
+`Footer.Description.Controls` (фиксированная группа кнопок справа).
+
+Типовой кейс: нижняя часть формы/LightBox'а/страницы, где слева —
+пояснение или статус, справа — действия (`Сохранить`, `Отменить`).
+На мобильных устройствах Controls переносится на следующую строку.
+
+Используй когда: нужна стандартизированная разметка подвала
+"контент + действия" с корректным мобильным wrap-поведением и
+отступами, согласованными с `Button` (компенсация margin'ами).
+Не используй как: универсальный flex-контейнер (возьми `Row`/собственный
+layout).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Footer/
+├── Footer.tsx                              # корень, compound-root, forwardRef + data-tx
+├── index.ts                                # Barrel: Footer, FooterDescription, FooterDescriptionContent, FooterDescriptionControls
+├── components/
+│   ├── FooterDescription.tsx               # Object.assign → Content/Controls
+│   ├── FooterDescriptionContent.tsx        # flex-grow: 1; margin-right: auto
+│   └── FooterDescriptionControls.tsx       # margin-left: auto; padding-left: 24px
+├── styles/
+│   └── Footer.module.less                  # flex/space-between + mobile wrap
+└── __tests__/
+    └── Footer.test.tsx                     # smoke: root, ref, arbitrary props
+```
+
+Особенности:
+- **`forwardRef`** — есть на всех 4 уровнях.
+- **`data-tx`** — только на корне `Footer`. `Description`/`Content`/
+  `Controls` не проставляют (они внутренние под-компоненты одной
+  compound-семьи).
+- **`IFooterDescriptionControlsProps`** импортируется из
+  `@sberbusiness/triplex-next/components/Table/TableBasic/types` —
+  исторический кросс-модульный импорт (type определён в types.ts
+  Table, но используется здесь). Не трогать без осознанного
+  рефакторинга обоих мест.
+- **Нет собственных stories** — Footer демонстрируется через
+  `stories/Page/FooterPage.stories.tsx` и как часть Table/LightBox
+  story-групп.
+- **Тесты** покрывают только корень `Footer` (smoke-уровень —
+  рендер, ref, props-passthrough).
+
+---
+
+## Compound-структура
+
+```tsx
+<Footer>
+    <Footer.Description>
+        <Footer.Description.Content>
+            Комментарий / описание / статус
+        </Footer.Description.Content>
+        <Footer.Description.Controls>
+            <Button>Отменить</Button>
+            <Button>Сохранить</Button>
+        </Footer.Description.Controls>
+    </Footer.Description>
+</Footer>
+```
+
+**Реализация compound-а через `Object.assign`:**
+
+```tsx
+export const Footer = Object.assign(
+    React.forwardRef<HTMLDivElement, IFooterProps>(function Footer({ children, ...rest }, ref) { ... }),
+    { Description: FooterDescription },
+);
+
+export const FooterDescription = Object.assign(
+    React.forwardRef<HTMLDivElement, IFooterDescriptionProps>(function FooterDescription(...) { ... }),
+    {
+        Content: FooterDescriptionContent,
+        Controls: FooterDescriptionControls,
+    },
+);
+```
+
+**Два уровня compound'а:** `Footer.Description` + вложенный
+`Description.Content`/`Description.Controls`. Это редкий паттерн в
+библиотеке — большинство компонентов имеют один уровень.
+
+**Все под-компоненты также экспортируются напрямую через barrel:**
+`FooterDescription`, `FooterDescriptionContent`, `FooterDescriptionControls`.
+Можно использовать либо compound-обращение (`Footer.Description.Content`),
+либо прямой импорт. Предпочтение — compound для читаемости.
+
+---
+
+## Варианты и props
+
+### Footer — `IFooterProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Обычно ровно один `Footer.Description`. |
+| `className`, `style`, `...HTMLDivAttributes` | — | — | Стандартные. |
+
+**Корневой `Footer` — минимальный**: не добавляет flex/padding, только
+data-tx. Никаких собственных классов. Все визуальные свойства —
+в `Description`.
+
+### FooterDescription — `IFooterDescriptionProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Обычно `Content` + `Controls` или только `Controls`. |
+| `className` | `string` | — | Мержится с `styles.footerDescription` через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Стандартные. |
+
+Класс `.footerDescription`:
+```less
+display: flex;
+justify-content: space-between;
+align-items: center;
+```
+
+### FooterDescriptionContent — `IFooterDescriptionContentProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Текст/описание/статус. |
+| `className` | `string` | — | Мержится через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Стандартные. |
+
+Класс `.footerDescriptionContent`:
+```less
+flex-grow: 1;
+margin-right: auto;
+```
+
+**`margin-right: auto`** + `flex-grow: 1` — занимает всё свободное
+место слева, выталкивая `Controls` вправо.
+
+### FooterDescriptionControls — `IFooterDescriptionControlsProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Обычно `<Button>...</Button>`-группа. |
+| `className` | `string` | — | Мержится через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Стандартные. |
+
+Класс `.footerDescriptionControls`:
+```less
+margin-left: auto;
+white-space: nowrap;
+padding-left: 24px;
+```
+
+**`white-space: nowrap`** — не даёт кнопкам переноситься на новую строку
+внутри Controls (на desktop). **`padding-left: 24px`** — минимальный
+gap между Content и Controls.
+
+---
+
+## Ключевые особенности реализации
+
+### Корень `Footer` — "прозрачный" контейнер
+
+```tsx
+<div {...rest} data-tx={process.env.npm_package_version} ref={ref}>
+    {children}
+</div>
+```
+
+Без класса, без padding. Смысл — только как "маркер" (data-tx) и
+стабильная точка для ref потребителя. Визуальная логика делегирована
+`Description`. Если потребитель хочет padding/border — добавляет через
+`className`/`style` в props.
+
+### Mobile wrap — `flex-wrap: wrap` + перераскладка Controls
+
+```less
+@media (max-width: @screen-sm-max) {
+    .footerDescription { flex-wrap: wrap; align-items: normal; }
+    .footerDescriptionContent { width: 100%; }
+    .footerDescriptionControls {
+        padding-left: 0;
+        white-space: normal;                // разрешаем перенос на mobile
+        margin-top: -16px;                  // компенсация Button margin
+        margin-left: -16px;
+        > button {
+            margin-left: 16px;
+            margin-top: 16px;
+        }
+    }
+    .footerDescriptionContent + .footerDescriptionControls {
+        margin-top: 0;                      // если Content есть — полагаемся на его высоту
+    }
+}
+```
+
+**На mobile Controls:**
+- Переносится на новую строку (flex-wrap).
+- `padding-left: 0` — убирает отступ (строка уже новая).
+- `white-space: normal` — кнопки могут переноситься, если места мало.
+- **`margin-top/-left: -16px` + `button > margin: 16px`** — трюк:
+  компенсирует отступы Button'а, чтобы визуально gap между кнопками
+  оставался 16px, но внешние края выравнивались к краю контейнера.
+- **`Content + Controls { margin-top: 0 }`** — когда Content есть,
+  использует его нижний отступ; когда Controls стоит одна (без Content),
+  применяется полноценный -16px для верхнего смещения.
+
+### `.footer` класс в медиа — orphan
+
+```less
+@media (max-width: @screen-sm-max) {
+    .footer { padding: 16px 0; }
+}
+```
+
+**Этот класс объявлен, но НЕ применяется** — в `Footer.tsx` нет
+`className={styles.footer}`. Legacy-остаток. Не удалять без
+подтверждения, что нигде не импортируется напрямую через module-import.
+
+### `IFooterDescriptionControlsProps` — кросс-модульный тип
+
+```ts
+import { IFooterDescriptionControlsProps } from "@sberbusiness/triplex-next/components/Table/TableBasic/types";
+```
+
+Тип живёт в `src/components/Table/TableBasic/types.ts`, но
+используется `FooterDescriptionControls`. Исторический артефакт. Не
+дублировать, не переносить без согласованного обновления Table.
+`Table` импортирует этот же тип и разметку для своего Table-Footer.
+
+### `React.HTMLAttributes<HTMLDivElement>` — пустое extension
+
+```ts
+export interface IFooterProps extends React.HTMLAttributes<HTMLDivElement> {}
+```
+
+Все 4 Props-интерфейса — пустые extensions HTML-атрибутов. Это
+сознательно: интерфейсы существуют как "именованные точки", чтобы
+можно было в будущем добавить пропсы без breaking change, а также
+чтобы TS отображал именно `IFooterDescriptionProps` в hover'ах.
+
+---
+
+## Инварианты
+
+- **`Footer` — минимальный контейнер**: только data-tx, без собственных
+  стилей. Не добавлять padding/border в компонент — оставить на
+  потребителя.
+- **`data-tx`** — только на корневом `Footer`, не на под-компонентах.
+- **Compound через `Object.assign`** — `Footer.Description.Content`,
+  `Footer.Description.Controls`. Не превращать в children-API.
+- **`Description` использует flex `space-between` + `align-items: center`**
+  — desktop. Не менять на grid (сломает mobile wrap).
+- **`Content` с `flex-grow: 1; margin-right: auto`** — занимает место,
+  выталкивает `Controls`.
+- **`Controls` с `margin-left: auto; white-space: nowrap; padding-left: 24px`**
+  — правый край, кнопки в одну строку.
+- **Mobile (`max-width: @screen-sm-max`)** — `flex-wrap: wrap`, Content
+  на 100%, Controls на новой строке с Button-margin-компенсацией.
+  Не менять без обновления Button'а.
+- **`.footer` в медиа-селекторе — orphan**. Не использовать; не
+  удалять без grep'а потребителей.
+- **`IFooterDescriptionControlsProps` — импорт из `Table/TableBasic/types`**,
+  не дублировать локально.
+- **`forwardRef`** — на всех 4 компонентах.
+
+---
+
+## Accessibility
+
+- **`<div>`-контейнеры** — семантика не задаётся (нет `<footer>`-тега).
+  Потребитель должен выбрать корректный semantic-элемент сам, передав
+  нужные ARIA-роли через `...rest`. Для "подвала страницы" ожидается
+  `<Footer role="contentinfo">` или оборачивание во внешний `<footer>`.
+- **Нет `role="toolbar"` на Controls** — группа кнопок не анонсируется
+  как toolbar. Если нужно — потребитель добавляет через `role`/`aria-label`.
+- **Tab-навигация** — естественная (от Content к Controls). Mobile
+  сохраняет tab-order (flex-wrap не меняет DOM-порядок).
+- **Focus ring** — на дочерних `Button`/`Link`, сам Footer не focusable.
+
+---
+
+## Дизайн-токены
+
+**Нет собственных.** Все визуальные свойства — от дочерних компонентов
+(`Button`, `Link`, `Typography`). Footer — только layout.
+
+---
+
+## Связанные компоненты
+
+- `Page` (`src/components/Page`) — типичный контейнер, где используется
+  Footer как подвал страницы (см. `stories/Page/FooterPage.stories.tsx`).
+- `Header` (`src/components/Header`) — верхняя часть страницы, парная
+  к Footer.
+- `LightBox`/`ModalWindow`/`SideOverlay` — часто имеют Footer в нижней
+  части модалки с action-buttons.
+- `Button` — основной дочерний элемент в `Controls`. Mobile-стили
+  специально рассчитаны на отступы Button'а (`margin: 16px` compensation).
+- `Table`/`TableBasic` — переиспользует `IFooterDescriptionControlsProps`
+  тип.
+
+---
+
+## Stories
+
+**Нет собственных stories.** Footer демонстрируется через:
+- `stories/Page/FooterPage.stories.tsx` — в составе страницы.
+- Stories Table/LightBox/ModalWindow — как часть layout'а модалок.
+
+Добавление своих stories — AI-Ready debt (подобные примитивы обычно
+имеют базовый showcase).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/FormField.md

@@ -0,0 +1,326 @@
+---
+component: FormField
+category: Forms
+figma-node: ""
+figma-file: ""
+related: [TextField, TextareaField, NumberField, AmountField, DateField, MonthYearField, SMSField, SelectField, SuggestField, MultiselectField, FormGroup, Button, ButtonIcon]
+tokens:
+  - --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
+stories: stories/FormField/FormField.stories.tsx
+version: "1.0"
+---
+
+# FormField
+
+## Назначение
+
+Низкоуровневый **compound-примитив** для построения полей ввода: контейнер,
+который управляет визуальным состоянием (hover/active/focus/filled/error/warning/disabled),
+плавающим лейблом и отступами под prefix/postfix. Сам по себе не рендерит
+`<input>` — принимает свои под-компоненты (`FormFieldInput`, `FormFieldTextarea`,
+`FormFieldMaskedInput`, `FormFieldTarget`, `FormFieldLabel`, `FormFieldPrefix`,
+`FormFieldPostfix`, `FormFieldClear`, `FormFieldDescription`, `FormFieldCounter`).
+
+Используй `FormField` когда: строишь новый тип поля ввода, которого нет в
+готовых обёртках (`TextField`, `NumberField`, `DateField` и т.п.).
+Не используй напрямую когда: для типового текстового поля подходит
+`TextField` — он уже собирает `FormField` + `FormFieldInput` + `FormFieldLabel`.
+
+---
+
+## Файловая структура
+
+```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
+```
+
+---
+
+## 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>
+```
+
+Корневой `FormField` — provider `FormFieldContext`. Контекст хранит `size`,
+`status`, `targetId`, `labelId`, `prefixWidth`, `postfixWidth`, `filled`,
+`focused`, `active` и сеттеры. Под-компоненты читают/пишут это состояние.
+
+---
+
+## Варианты и props
+
+### FormField — `IFormFieldProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `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
+
+| Значение | Эффект |
+|---|---|
+| `DEFAULT` | Обычное состояние. |
+| `DISABLED` | Визуально disabled; `FormFieldInput`/`FormFieldTextarea` проставляют `disabled`, `FormFieldTarget` получает `tabIndex=-1` и `aria-disabled`. |
+| `ERROR` | Красный фон/шейдоу. |
+| `WARNING` | Жёлтый фон/шейдоу. |
+
+### Под-компоненты — ключевые 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 (для корректного расположения текста и счётчика). |
+
+---
+
+## Ключевые особенности реализации
+
+### Контекст — источник истины
+
+- `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 обновится на следующем рендер-цикле.
+
+`FormFieldLabel` использует те же `prefixWidth`/`postfixWidth` для вычисления `left`/`right`, чтобы плавающий label был ровно над инпутом, не под иконками.
+
+Дефолт `TARGET_PADDING_X_DEFAULT = 12` — стартовое значение до первого измерения префикса/постфикса (и когда их нет).
+
+### Floating label — `filled || active`
+
+Label плавает наверх, когда:
+- поле заполнено (`filled`), либо
+- поле активно (`active === active-prop || focused`).
+
+`FormFieldInput`/`FormFieldTextarea` вычисляют `filled` через `isFilled(value)`:
+- `undefined` → `false`
+- `number` → `true`
+- строка → `value.length !== 0`
+
+Для select-подобных обёрток `FormFieldTarget` пишет `filled = children.length !== 0`.
+
+Принудительно задать `floating` можно prop'ом (для кейсов, где лейбл всегда сверху — например, поле с картинками).
+
+### Autofill detection через CSS-анимации
+
+`FormFieldInput`/`FormFieldTextarea` слушают `onAnimationStart` и проверяют `animationName`:
+- `autofill-applied-hook*` → `setFilled(true)`
+- `autofill-cancelled-hook*` → `syncFilled(value)`
+
+Это единственный способ отловить браузерное автозаполнение, которое не триггерит `onChange`. Стороны анимации объявлены в CSS. Не ломать имена — они парсятся в JS.
+
+### `FormFieldInput.render` — точка расширения
+
+Через `render` пробрасываются все общие props (стили, id, `onFocus/onBlur`, `onAnimationStart`, `onChange`, `disabled`, `size`) и ref. Используется, например, в `FormFieldMaskedInput` — чтобы обернуть `react-text-mask`.
+
+### `FormFieldMaskedInput` — рендерит ДВА инпута
+
+- Первый (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 пересчитывается по пустому значению). Не удалять этот обработчик.
+
+Видимость `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`.
+
+Из-за `uniqueId` (lodash-es, модульный счётчик) id'ы не SSR-safe. Это осознанный legacy-выбор; при SSR используй `id` prop с явным значением.
+
+---
+
+## Инварианты
+
+- **`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 отключён специально. Не включать зависимости.
+
+---
+
+## Accessibility
+
+- **`<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 инпута.
+
+---
+
+## Дизайн-токены
+
+**Корневой контейнер (`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
+```
+
+**Текст:**
+```
+--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
+```
+
+Border-radius задан литералами в `.sm` / `.md` / `.lg`:
+- `SM` → 6px
+- `MD` → 8px
+- `LG` → 10px
+
+---
+
+## Связанные компоненты
+
+### Высокоуровневые обёртки (используют FormField внутри)
+- `TextField`, `TextareaField`, `SMSField`, `NumberField`, `AmountField`, `DateField`, `MonthYearField`, `DocumentNumberEdit` — типовые input-поля.
+- `SelectField`, `SelectExtendedField`, `SuggestField`, `MultiselectField` — select-подобные (внутри обычно `FormFieldTarget`).
+
+### Утилитарные
+- `FormGroup` — группа `FormField`'ов в форме.
+- `Button` / `ButtonIcon` — `FormFieldClear` наследует `ButtonIcon`.
+- `Loader` — может рендериться в `FormFieldPostfix` для состояния загрузки.
+
+### Кросс-модульный импорт
+- `FormFieldClear` импортирует `ButtonIcon` из `../Button/ButtonIcon` — не дублировать.
+- `FormFieldMaskedInput` импортирует `FormFieldInput` по абсолютному пути `@sberbusiness/triplex-next/components/FormField/components/FormFieldInput` — исторически, работает.
+
+---
+
+## Stories
+
+Основные: `stories/FormField/FormField.stories.tsx`
+Примеры: `stories/FormField/examples/`
+
+| 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-регрессия. |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |