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

package/bundle/components/AmountField.md

@@ -1,11 +1,11 @@
 ---
 component: AmountField
 category: TextFields
-figma-node: ""
-figma-file: ""
-related: [TextField, NumberField, Amount, FormField, FormFieldInput]
-tokens: []
-stories: stories/TextFields/AmountField.stories.tsx
+related: [TextField, FormField, Amount, NumberField]
+tokens:
+  - FormField.Input_Color_Default
+  - FormField.Input_Color_Disabled
+stories: stories/AmountField/AmountField.stories.tsx
 version: "1.0"
 ---
 
@@ -13,272 +13,175 @@ version: "1.0"
 
 ## Назначение
 
-Поле ввода денежной суммы с автоматическим форматированием: разделители групп
-(пробел), фиксированная дробная часть, запятая как десятичный разделитель,
-отображение валюты справа. Управляет позицией каретки при вводе/удалении так,
-чтобы она не попадала на разделители, и блокирует ввод нецифровых символов
-(кроме запятой/точки).
+Поле ввода денежной суммы. Пока пользователь печатает, значение форматируется на лету
+(разряды разделяются пробелом, целая и дробная части — запятой: `1234.56` → `1 234,56`),
+а наружу через `inputProps.onChange` уходит нормализованное значение с точкой и без
+разделителей разрядов (`"1234.56"`) — его можно отправлять на бэкенд без дополнительной
+обработки. Дробная часть всегда дописывается до `fractionDigits` знаков, а каретка
+удерживается в осмысленной позиции при вводе, удалении и вставке.
 
-Построен поверх `TextFieldBase` и `FormFieldInput` (получает визуальное оформление
-и поддержку label/status/prefix/postfix от FormField-стека). Логика форматирования
-инкапсулирована в классе `AmountBaseInputCore`, который внутренне делит работу на
-парсер (`AmountBaseInputParser`) и форматер (`AmountBaseInputFormatter`).
+Композиция над семейством `FormField`: `TextFieldBase` (→ `FormGroup` → `FormField`) +
+`FormFieldInput`, плюс собственный слой со знаком валюты.
 
-Используй когда: пользователь вводит денежную сумму с валютой и фиксированной
-дробной частью.
-Не используй когда: нужен просто числовой ввод без валюты (используй `NumberField`);
-нужно только отобразить сумму без ввода (используй `Amount`).
+Используй когда: пользователь вводит сумму — платёж, лимит, ставку, любой денежный
+показатель, который нужно показывать с разрядами и хранить числом.
 
----
+Не используй когда: нужно только показать готовую сумму без ввода (`Amount`), нужен
+счётчик/произвольное число без денежного форматирования (`NumberField`), значение имеет
+фиксированный формат-маску (`MaskedField`) или формат произвольный (`TextField`).
 
-## Файловая структура
+---
 
-```text
-src/components/AmountField/
-├── AmountField.tsx                  # React.forwardRef, главный компонент
-├── AmountBaseInputCore.ts           # Класс-оркестратор: parse → format, хранит caret и cache
-├── AmountBaseInputParser.ts         # Класс-парсер: нормализует value, trimLeadingZeros, splits integer/fractional
-├── AmountBaseInputFormatter.ts      # Класс-форматер: добавляет пробелы между группами, запятую
-├── utils.ts                         # createPlaceholder, setFallbackCaret
-├── index.ts                         # Barrel (только AmountField)
-└── __tests__/                       # Unit-тесты
-```
+## Варианты и props
 
-Особенности:
-- **Нет LESS** — компонент визуально идентичен `TextField`, стили наследуются из
-  `TextFieldBase`/`FormFieldInput`.
-- **Нет `stories/AmountField/`** — stories лежат в `stories/TextFields/AmountField.stories.tsx`
-  (логически относится к группе TextFields).
-- Core-логика разделена на 3 класса намеренно — parser, formatter, core (оркестратор).
-  Такое разделение нужно, чтобы можно было тестировать parse/format изолированно.
+`IAmountFieldProps` расширяет `ITextFieldBaseProps` (кроме `children`), поэтому
+`size`, `status`, `active`, `label`, `prefix`, `postfix`, `description`, `counter`,
+`className` и div-атрибуты ведут себя так же, как у `TextField`.
 
----
+### Обязательные props
 
-## Варианты и props
+| Prop | Тип | Описание |
+|---|---|---|
+| `inputProps` | `Omit<IFormFieldInputProps, "type" \| "maxLength" \| "onChange" \| "inputMode" \| "autoComplete"> & { value, onChange, ref? }` | Свойства поля ввода. `value` — нормализованное значение (`"1234.56"`, пустая строка для пустого поля), `onChange(value)` получает такое же нормализованное значение, `ref` — ссылка на `<input>`. Остальные атрибуты (`placeholder`, `id`, `onFocus`, `onBlur`, `onKeyDown`, `onSelect`, data-атрибуты) пробрасываются в `FormFieldInput`. |
 
-### `IAmountFieldProps extends Omit<ITextFieldBaseProps, "children">`
+### Опциональные props
 
 | Prop | Тип | По умолчанию | Описание |
 |---|---|---|---|
-| `inputProps` | `Omit<IFormFieldInputProps, "type" \| "maxLength" \| "onChange" \| "inputMode" \| "autoComplete"> & { value: string; onChange: (value: string) => void }` | — (обязателен) | Всё для `<input>`, кроме полей, которые AmountField задаёт сам. **`onChange` — нестандартный**: получает `value: string` (ЧИСТОЕ значение без форматирования), не event. |
-| `currency` | `string` | — | Название валюты (например, "RUB"). Рендерится справа как постфикс через `Text` с типом `SECONDARY`/`DISABLED`. Не указано — постфикса нет. |
-| `maxIntegerDigits` | `number` | `16` | Максимум цифр до запятой. Ввод сверх лимита игнорируется. |
-| `fractionDigits` | `number` | `2` | Цифр после запятой. Используется для placeholder, parse, format. При `0` — компонент становится integer-only. |
-| `onClear` | `() => void` | — | Если указан — справа перед валютой появляется `FormFieldClear` (крестик). Коллбек при клике. |
-| `postfix` | `React.ReactNode` | — | Дополнительный постфикс (рядом с валютой и clear-кнопкой). Ограничение: ставится после валюты в визуальном порядке. |
-| `...TextFieldBaseProps` | — | — | `label`, `status`, `size`, `prefix`, `description`, `counter`, `data-test-id`, и т.д. |
-
-### Что AmountField заставляет у `inputProps`
-
-- `type`: всегда `"text"` (задаётся TextFieldBase/FormFieldInput по умолчанию; в AmountField не передаётся).
-- `maxLength`: не используется — AmountField сам ограничивает через `maxIntegerDigits` + `fractionDigits`.
-- `onChange`: перехватывается. Снаружи получаешь чистое значение `string` без пробелов и с `.` как разделителем.
-- `inputMode`: всегда `"decimal"` — подсказывает мобильной клавиатуре показать цифры и запятую.
-- `autoComplete`: всегда `"off"` — браузерный автокомплит отключен.
+| `size` | `EComponentSize` | `LG` | Размер поля: SM / MD / LG. Тот же размер получает слой со знаком валюты. |
+| `status` | `EFormFieldStatus` | `DEFAULT` | Статус: default / error / warning / disabled. `DISABLED` блокирует input и приглушает знак валюты. |
+| `currency` | `string` | — | Наименование валюты справа от значения. Не рендерится, пока отформатированное значение пустое. |
+| `maxIntegerDigits` | `number` | `16` | Максимальное количество знаков перед запятой. Лишние цифры не попадают в значение. |
+| `fractionDigits` | `number` | `2` | Количество знаков после запятой. `0` — поле без дробной части. |
+| `onClear` | `() => void` | — | Обработчик очистки. Если передан, перед пользовательским `postfix` рендерится `FormFieldClear`. Компонент сам значение не сбрасывает — это делает потребитель. |
+| `clearProps` | `Omit<IFormFieldClearProps, "onClick">` | — | Свойства кнопки очистки. Имеют смысл только вместе с `onClear`. Сюда передаётся `aria-label` — доступное имя кнопки. `onClick` задаётся через `onClear` и не переопределяется. |
+
+### Особенности поведения
+
+- **Значение контролируемое и нормализованное.** В `value` хранится `"<целая>.<дробная>"`
+  без разделителей разрядов; в поле показывается форматированный вариант с запятой.
+  Значение, пришедшее снаружи, нормализуется только для отображения: `"1234,5"` покажется
+  как `1 234,50`, но `onChange` при этом не вызывается — в состоянии потребителя останется
+  `"1234,5"`, пока пользователь не отредактирует поле. Синхронизировать состояние с
+  нормализованным видом компонент не берётся: это задача потребителя.
+- **Дробная часть дополняется нулями** до `fractionDigits`. Ввод только дробной части
+  (`,5`) восстанавливает целый ноль → `"0.50"`. Если целой части нет, а дробная нулевая
+  (`,00`) — значение считается пустым (`""`).
+- **Ведущие нули отбрасываются** вместе со всем, что стоит перед первой значащей цифрой;
+  любые символы, кроме цифр и десятичного разделителя, игнорируются.
+- **Разделители.** Ввод принимает и `,`, и `.` как десятичный разделитель. В отображаемом
+  значении разряды разделяются обычным пробелом (U+0020), десятичная часть — запятой.
+- **Placeholder.** Если `inputProps.placeholder` не передан (или пустая строка), он
+  генерируется из `fractionDigits`: `0,00` при `2`, `0` при `0`.
+- **Каретка.** После каждого ввода позиция каретки пересчитывается с учётом добавленных
+  разделителей и восстанавливается в layout-эффекте. Эффект зависит не только от
+  `inputProps.value`, но и от `maxIntegerDigits` и `fractionDigits`: смена формата
+  пересчитывает `core.caret` при неизменном значении, и без этих зависимостей каретка
+  осталась бы на индексе прежнего формата. Если значение снаружи не изменилось
+  (ввод невалиден или значение то же), каретка ставится хелпером `setFallbackCaret` —
+  он же учитывает `Backspace`/`Delete` рядом с разделителем и направление выделения.
+- **Знак валюты** рисуется поверх поля отдельным слоем: невидимая (`color: transparent`)
+  копия значения задаёт отступ, за ней идёт сам `currency`. Копия помечена
+  `aria-hidden="true"`.
+- **`data-test-id`** на компоненте порождает суффиксы: `{id}__input` на элементе ввода и
+  `{id}__unit` на знаке валюты.
 
 ---
 
-## Ключевые особенности реализации
-
-### Разделение value и formattedValue
-
-- **`value`** (то, что во внешнем state) — нормализованная строка: только цифры и `.`
-  как разделитель (например, `"1234.56"`).
-- **`formattedValue`** (то, что показывается в `<input>`) — с пробелами и запятой
-  (например, `"1 234,56"`).
-
-`AmountField` рендерит `formattedValue`, но во внешний `onChange` отдаёт `value`.
-Это значит: внешнее состояние всегда совместимо с `big.js` / `parseFloat` /
-backend API без дополнительной очистки.
-
-### Ленивая инициализация core
-
-```tsx
-const core = useRef<AmountBaseInputCore>();
-if (core.current === undefined) core.current = new AmountBaseInputCore(maxIntegerDigits, fractionDigits);
-```
-
-Создаётся **один раз при первом рендере**. Изменение `maxIntegerDigits`/`fractionDigits`
-применяется через `core.current.maxIntegerDigits = ...` в `getFormattedValue`, а не
-через пересоздание инстанса.
-
-### Синхронизация внешнего value с core
-
-```tsx
-if (inputProps.value != core.current.value || ...) {
-    core.current.apply(inputProps.value, inputProps.value.length);
-}
-```
-
-На каждом рендере проверяется, изменилось ли значение извне (controlled re-render)
-или параметры (`max/fractionDigits`). Если да — `core.apply()` пересчитывает
-`formattedValue`. Это гарантирует, что компонент работает как controlled: внешний
-state — единственный источник истины.
-
-### Управление кареткой: `useLayoutEffect` + `setCaretPosition`
-
-```tsx
-useLayoutEffect(() => {
-    if (core.current && refInput.current == document.activeElement)
-        setCaretPosition(refInput.current, Math.max(core.current.caret, 0));
-}, [inputProps.value]);
-```
-
-После каждого изменения value, если input в фокусе, восстанавливается позиция
-каретки в `core.caret`. Это компенсирует то, что React при controlled input
-сбрасывает каретку в конец после rerender.
-
-**`useLayoutEffect`, не `useEffect`** — каретка ставится синхронно до отрисовки,
-чтобы не было визуального "мигания".
-
-### Fallback caret через `setFallbackCaret`
-
-Если `onChange` **не меняет значение** (невалидный ввод, идентичное значение) —
-React не перерендерится, и `useLayoutEffect` не сработает. Для этого случая
-`handleChange` вызывает `setFallbackCaret(event.target, core, fractionDigits)`,
-которая обрабатывает спецкейсы:
-- Каретка перед разделителем `,` → сдвиг вперёд.
-- Backspace/Delete возле разделителей → сдвиг.
-- Обратное направление выделения → каретка в конец.
-
-Эта утилита — единственное место, где компонент напрямую дёргает input DOM API
-(`setSelectionRange`).
-
-### Кеш для восстановления контекста
-
-`core.cache` хранит: последнее `formattedValue`, `key` нажатой клавиши,
-`selectionStart`/`End`/`Direction` на момент последнего select-event. Это даёт
-парсеру/формате́ру/fallback-caret полную картину "что сделал пользователь", чтобы
-правильно обработать ввод.
-
-`handleSelect` обновляет `cache.selectionStart/End/Direction` на каждом
-событии выделения — значит, к моменту `handleChange` эти поля актуальны.
+## Дизайн-токены
 
-### `setRef` вручную
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/FormField.ts`.
 
-```tsx
-const setRef = (instance) => {
-    refInput.current = instance;  // локальный ref
-    if (typeof ref === "function") ref(instance);
-    else if (ref) ref.current = instance;
-};
+```text
+FormField.Input_Color_Default
+FormField.Input_Color_Disabled
 ```
 
-Компоненту нужен **и** локальный ref (для caret-манипуляций), **и** внешний
-forwarded ref. `setRef` передаёт instance в оба. Не заменять на единственный
-внешний ref.
-
-### `createPlaceholder(fractionDigits)`
-
-Если потребитель не передал `inputProps.placeholder`, генерируется автоматически:
-- `fractionDigits=0` → `"0"`.
-- `fractionDigits=2` → `"0,00"`.
-- `fractionDigits=4` → `"0,0000"`.
-
-### `parseFractionalPart` восстанавливает целый ноль
-
-Если пользователь ввёл `.5` (без целой части) и дробная часть ненулевая, парсер
-восстанавливает `0.5`. Если дробная часть только из нулей (`"00"`) — целая часть
-остаётся пустой (парсинг останавливается), итоговое значение `""`.
-
-### `trimLeadingZeros` — не агрессивен
-
-Удаляет ведущие нули **только если следующая цифра ненулевая**. Значение `"0"` или
-`"00"` остаётся целой частью `""` или `"0"` в зависимости от дробной. Это
-обеспечивает корректное поведение при вводе `0,5` (пользователь пишет с нуля).
+Собственных токенов у `AmountField` нет: знак валюты красится теми же токенами, что и текст
+поля, остальное оформление наследуется от семейства `FormField`.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef`** на `AmountField` — обязателен, ref идёт на `<input>`. Не убирать.
-- **`inputMode="decimal"`** — не менять на `numeric` или `text`. `decimal` даёт
-  правильную мобильную клавиатуру с запятой.
-- **`autoComplete="off"`** — не убирать. Браузерный автокомплит ломает
-  форматирование.
-- **`onChange` отдаёт `string` (чистое значение), не event** — это **контракт**.
-  Потребители полагаются на нормализованный формат. Не менять сигнатуру без
-  breaking-change.
-- **Разделение parser/formatter/core** — не сливать в один класс. Тесты
-  построены вокруг парсера/формате́ра в изоляции.
-- **Запятая как разделитель, точка тоже принимается** — парсер
-  (`StringUtils.isDecimalSeparator`) принимает и `.`, и `,`. Formatter всегда
-  выдаёт `,`. Не менять.
-- **Пробел как групповой разделитель** — не менять на NBSP или другой символ
-  (parser полагается на `StringUtils.isDigit` для определения не-цифр).
-- **Core создаётся один раз** — не пересоздавать при каждом изменении props,
-  потеряется кэш.
-- **`useLayoutEffect` (не `useEffect`)** для caret-позиции — не менять.
-- **`setFallbackCaret`** — обязателен в `handleChange`. Без него каретка
-  теряется при идентичном/невалидном вводе.
-- **`data-test-id` суффиксы** (`__input`, `__unit`) — публичный контракт для
-  тестов потребителей. Не переименовывать.
-- **`maxIntegerDigits=16` по умолчанию** — покрывает квадриллионы, но не больше
-  (bigint). Если лимит мал — увеличивать через prop, не в коде.
+- `forwardRef` на компоненте — не убирать. Внешний `ref` указывает на корневой `<div>`
+  `FormField`, ссылка на `<input>` передаётся через `inputProps.ref`.
+- Публичный API (`IAmountFieldProps`: `inputProps`, `currency`, `maxIntegerDigits`,
+  `fractionDigits`, `onClear`, `clearProps` + унаследованные от `ITextFieldBaseProps`) —
+  изменение имён, типов и дефолтов является breaking change.
+- `inputProps` не принимает `type`, `maxLength`, `inputMode`, `autoComplete` и собственный
+  `onChange` с сигнатурой события: их задаёт сам компонент (`inputMode="decimal"`,
+  `autoComplete="off"`, `onChange(value: string)`).
+- Формат нормализованного значения (точка как десятичный разделитель, отсутствие
+  разделителей разрядов) — часть контракта: на нём построены потребители, отправляющие
+  значение на бэкенд.
+- Разделитель разрядов в отображаемом значении — обычный пробел U+0020, тогда как
+  `Amount` (отображение суммы) использует `AmountConst.GroupSeparator` — неразрывный
+  пробел U+00A0. Различие существующее и наблюдаемое (копирование значения, e2e-селекторы),
+  менять его без отдельного решения нельзя.
+- `AmountBaseInputCore`, `AmountBaseInputParser`, `AmountBaseInputFormatter` и `utils.ts` —
+  внутренняя кухня компонента, из barrel `index.ts` не экспортируется.
+- Экземпляр `AmountBaseInputCore` живёт в `useRef` весь срок жизни компонента: он хранит
+  позицию каретки и кэш выделения между рендерами. Пересоздавать его на каждый рендер или
+  заменять на state нельзя — потеряется каретка.
+- CSS-класс `currencyLayout` используется в unit-тестах как селектор слоя валюты —
+  переименование потребует правки теста.
 
 ---
 
 ## Accessibility
 
-- **Нативный `<input>`** — клавиатурная навигация работает из коробки.
-- **`inputMode="decimal"`** — на мобильных устройствах показывается числовая
-  клавиатура с десятичным разделителем.
-- **`autoComplete="off"`** — отключает автозаполнение (важно для сумм —
-  браузерный autofill не подходит под формат).
-- **Валюта рендерится как отдельный `<Text>`** — screen reader прочитает её как
-  обычный текст (например, "RUB"). Для полного названия валюты — потребитель
-  может передать `aria-label` на самом поле через `inputProps`.
-- **Для отрицательных чисел компонент НЕ делает замену `-` → `\u2212`** (в отличие
-  от display-компонента `Amount`). Это корректно: в input'е нужно настоящее
-  значение, которое можно скопировать и переиспользовать; символ `\u2212` ломает
-  parsing извне.
-- **`onClear` + `FormFieldClear`** — кнопка с иконкой внутри поля. Потребитель
-  обязан убедиться, что у кнопки есть `aria-label` (через внутреннюю реализацию
-  FormFieldClear) — проверь при расширении.
-
----
-
-## Дизайн-токены
-
-Нет собственных — все цвета и размеры наследуются из `TextFieldBase`/
-`FormFieldInput`/`Typography`. См. их документацию для списка токенов.
+- Лейбл — настоящий `<label htmlFor>`: `FormFieldInput` генерирует `id` через `lodash uniqueId`
+  и связывает его с `FormFieldLabel`. Свой `id` можно передать в `inputProps`.
+- Копия значения под знаком валюты помечена `aria-hidden="true"` — скринридер читает только
+  значение поля и сам знак валюты.
+- `inputMode="decimal"` даёт числовую клавиатуру на мобильных устройствах.
+- `status={EFormFieldStatus.DISABLED}` выставляет нативный `disabled` — поле штатно выпадает
+  из таб-обхода.
+- Семантика ошибки (`aria-invalid`, `aria-describedby`) не хардкодится: при необходимости
+  потребитель передаёт атрибуты через `inputProps`.
+- Кнопка очистки (`onClear`) — `FormFieldClear` с одной иконкой, без текста. Доступное имя
+  задаётся потребителем через `clearProps={{ "aria-label": "…" }}`: дефолтную строку зашить
+  нельзя, библиотека мультиязычная. Без `aria-label` кнопка остаётся безымянной — в примерах
+  и production-коде его передавать обязательно. Остальные поля семейства (`SuggestField`,
+  `DateField`, `ChipSuggest`, `MonthYearField`, `SelectExtendedField`) такого prop пока не
+  имеют и рендерят `FormFieldClear` только с `onClick`.
+- Собственных клавиатурных сокращений нет; `onKeyDown` и `onSelect` из `inputProps`
+  вызываются после внутренних обработчиков, которые запоминают нажатую клавишу и выделение
+  для расчёта каретки.
 
 ---
 
 ## Связанные компоненты
 
-- `TextFieldBase` (`src/components/TextField/TextFieldBase.tsx`) — базовый
-  контейнер поля, предоставляет label/status/size/prefix/postfix.
-- `FormField` / `FormFieldInput` (`src/components/FormField`) — нативный `<input>`
-  с визуальным оформлением формы.
-- `FormFieldClear` (`src/components/FormField/components/FormFieldClear.tsx`) —
-  кнопка очистки (крестик). Используется, если передан `onClear`.
-- `Typography` (`Text`, `ETextSize.B2`, `EFontType.SECONDARY/DISABLED`) —
-  рендер валюты.
-- `Amount` (`src/components/Amount`) — display-аналог. Форматирование разное:
-  AmountField использует свою реализацию (через parser/formatter классы),
-  Amount — `formatAmount` из `utils/amountUtils.ts` на `big.js`. Результат
-  визуально совпадает, но алгоритмы различны.
-- `NumberField` (`src/components/NumberField`) — числовой ввод без валюты.
-- `AmountConst` (`src/consts/AmountConst`) — общие константы разделителей.
-- Утилиты `utils/inputUtils.ts` (`setCaretPosition`), `utils/keyboard.ts` (`isKey`),
-  `utils/stringUtils.ts` (`StringUtils.isDigit`, `isDecimalSeparator`).
+- `TextFieldBase` — базовая раскладка поля (`FormGroup`/`FormField` + слоты `prefix`,
+  `label`, `postfix`, `description`, `counter`); `IAmountFieldProps` наследует её props.
+  Живёт в семействе `TextField`.
+- `FormField` / `FormFieldInput` — контейнер поля и сам элемент ввода, куда уходит
+  `inputProps`.
+- `FormFieldClear` — кнопка очистки, которую компонент добавляет в постфикс при `onClear`.
+- `Amount` — отображение уже готовой суммы (без ввода), парная компонента для read-only
+  сценариев.
+- `NumberField` — поле для произвольных чисел без денежного форматирования.
+- `MaskedField`, `TextField` — соседние поля той же группы `TextFields` для форматов с
+  маской и произвольного текста.
 
 ---
 
 ## Stories
 
-`stories/TextFields/AmountField.stories.tsx`
-Файлы примеров: `stories/TextFields/examples/AmountField/`
+Основные истории: `stories/AmountField/AmountField.stories.tsx`
+Файлы примеров: `stories/AmountField/examples/`
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `status`, `size`, `label`, `currency`, `prefix`, `postfix`, `description`, `counter`, `maxIntegerDigits`, `fractionDigits` |
-| `Basic` | `BasicExample.tsx` | Базовое controlled-использование |
-| `Sizes` | `SizesExample.tsx` | Все размеры `EComponentSize` |
-| `Statuses` | `StatusesExample.tsx` | Все `EFormFieldStatus` |
-| `WithClearButton` | `WithClearButtonExample.tsx` | С крестиком очистки |
-| `Example` | `ExampleExample.tsx` | Композиция с другими компонентами (формы) |
+| `Playground` | `Playground.tsx` | Интерактивный контроль size / status / label / currency / maxIntegerDigits / fractionDigits и настроек: кнопка очистки, `HelpBox`, описание |
+| `Default` | `Default.tsx` | Минимальное контролируемое поле со знаком валюты |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
+| `Statuses` | `Statuses.tsx` | Статусы default / error / warning / disabled |
+| `Production` | `Production.tsx` | Production-композиция (`Example: production`): кнопка очистки, `HelpBox` в постфиксе, description со ссылкой |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: пустое поле в фокусе (через `play`), заполненные размеры со знаком валюты, заблокированное заполненное поле |
 
 ---
 
@@ -286,37 +189,36 @@ forwarded ref. `setRef` передаёт instance в оба. Не заменят
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-10 | Создан документ (TRI-9). AI-рефакторинг AmountField, unit-тесты на ядро, парсер, форматер и утилиты; добавлен `displayName` |
+| 2026-09-14 | Правки по ревью (TRI-9): добавлен prop `clearProps` — доступное имя кнопки очистки задаётся через `aria-label`. Хелпер `setForwardedRef` переехал в общий внутренний модуль `src/helpers/setForwardedRef.ts` (пять копий по репозиторию свёрнуты в одну); публичный API это не затрагивает. |
+| 2026-09-17 | Правки по ревью (TRI-9): `setForwardedRef` импортируется относительным путём вместо алиаса `@sberbusiness/triplex-next/helpers/...` — алиас в `src` зарезервирован за публичными subentry. |
+| 2026-09-17 | Правки по ревью (TRI-9): в зависимости `useLayoutEffect`, восстанавливающего каретку, добавлены `maxIntegerDigits` и `fractionDigits`. Без них смена формата при неизменном `value` пересчитывала `core.caret`, но не переносила каретку в DOM. |
 
 ---
 
 ## Примеры использования
 
-### Basic
+### Default
 
-`stories/TextFields/examples/AmountField/BasicExample.tsx`
+`stories/AmountField/examples/Default.tsx`
 
 ```tsx
 import React, { useState } from "react";
-import { AmountField, EComponentSize, EFormFieldStatus } from "@sberbusiness/triplex-next";
+import { AmountField } from "@sberbusiness/triplex-next";
 
-export const BasicExample: React.FC = () => {
-    const [value, setValue] = useState("");
+export const Default = () => {
+    const [value, setValue] = useState<string>("");
 
     return (
-        <div style={{ maxWidth: "300px" }}>
+        <div style={{ maxWidth: 300 }}>
             <AmountField
+                label="Label"
                 inputProps={{
                     value,
-                    placeholder: "0,00",
+                    placeholder: "0,00 ₽",
                     onChange: setValue,
                 }}
-                status={EFormFieldStatus.DEFAULT}
-                size={EComponentSize.LG}
-                label="Label"
-                currency="RUB"
-                maxIntegerDigits={18}
-                fractionDigits={2}
+                currency="₽"
             />
         </div>
     );
@@ -325,136 +227,133 @@ export const BasicExample: React.FC = () => {
 
 ### Sizes
 
-`stories/TextFields/examples/AmountField/SizesExample.tsx`
+`stories/AmountField/examples/Sizes.tsx`
 
 ```tsx
 import React, { useState } from "react";
 import { AmountField, EComponentSize } from "@sberbusiness/triplex-next";
 
-const AmountFieldItem: React.FC<{ size: EComponentSize }> = ({ size }) => {
-    const [value, setValue] = useState("");
-
-    return (
-        <AmountField
-            inputProps={{
-                value,
-                placeholder: "0,00",
-                onChange: setValue,
-            }}
-            size={size}
-            label="Label"
-        />
-    );
-};
+interface ISizeItemProps {
+    size: EComponentSize;
+}
 
-export const SizesExample: React.FC = () => {
-    const sizes = Object.values(EComponentSize);
+const SizeItem = ({ size }: ISizeItemProps) => {
+    const [value, setValue] = useState<string>("");
 
     return (
-        <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
-            {sizes.map((size) => (
-                <AmountFieldItem key={size} size={size} />
-            ))}
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{size.toUpperCase()}</div>
+            <AmountField
+                size={size}
+                label="Label"
+                inputProps={{
+                    value,
+                    placeholder: "0,00 ₽",
+                    onChange: setValue,
+                }}
+                currency="₽"
+            />
         </div>
     );
 };
+
+const SIZES = Object.values(EComponentSize);
+
+export const Sizes = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
 ```
 
 ### Statuses
 
-`stories/TextFields/examples/AmountField/StatusesExample.tsx`
+`stories/AmountField/examples/Statuses.tsx`
 
 ```tsx
 import React, { useState } from "react";
 import { AmountField, EFormFieldStatus } from "@sberbusiness/triplex-next";
 
-const AmountFieldItem: React.FC<{ status: EFormFieldStatus }> = ({ status }) => {
-    const [value, setValue] = useState("");
-
-    return (
-        <AmountField
-            inputProps={{
-                value,
-                placeholder: "0,00",
-                onChange: setValue,
-            }}
-            status={status}
-            label="Label"
-        />
-    );
-};
-
-export const StatusesExample: React.FC = () => {
-    const statuses = Object.values(EFormFieldStatus);
-
-    return (
-        <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
-            {statuses.map((status) => (
-                <AmountFieldItem key={status} status={status} />
-            ))}
-        </div>
-    );
-};
-```
-
-### WithClearButton
-
-`stories/TextFields/examples/AmountField/WithClearButtonExample.tsx`
-
-```tsx
-import React, { useState } from "react";
-import { AmountField } from "@sberbusiness/triplex-next";
+interface IStatusItemProps {
+    status: EFormFieldStatus;
+}
 
-export const WithClearButtonExample: React.FC = () => {
-    const [value, setValue] = useState("8967452.31");
+const StatusItem = ({ status }: IStatusItemProps) => {
+    const [value, setValue] = useState<string>("");
 
     return (
-        <div style={{ maxWidth: "300px" }}>
+        <div style={{ maxWidth: 300 }}>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{status.toUpperCase()}</div>
             <AmountField
+                status={status}
+                label="Label"
                 inputProps={{
                     value,
-                    placeholder: "0,00",
+                    placeholder: "0,00 ₽",
                     onChange: setValue,
                 }}
-                label="Label"
-                onClear={() => setValue("")}
+                currency="₽"
             />
         </div>
     );
 };
+
+const STATUSES = Object.values(EFormFieldStatus);
+
+export const Statuses = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        {STATUSES.map((status) => (
+            <StatusItem key={status} status={status} />
+        ))}
+    </div>
+);
 ```
 
-### Example
+### Production
 
-`stories/TextFields/examples/AmountField/ExampleExample.tsx`
+`stories/AmountField/examples/Production.tsx`
 
 ```tsx
-import React, { useState } from "react";
-import { AmountField, HelpBox, ETooltipSize, Text, ETextSize, EFontType, Link } from "@sberbusiness/triplex-next";
+import React, { useState, useRef } from "react";
+import { AmountField, Text, HelpBox, Link, ETextSize, EFontType, ETooltipSize } from "@sberbusiness/triplex-next";
+
+export const Production = () => {
+    const [value, setValue] = useState<string>("");
+    const inputRef = useRef<HTMLInputElement>(null);
 
-export const ExampleExample: React.FC = () => {
-    const [value, setValue] = useState("");
+    const handleLinkClick: React.MouseEventHandler<HTMLAnchorElement> = (event) => {
+        event.preventDefault();
+    };
+
+    const handleClear = () => {
+        setValue("");
+        inputRef.current?.focus();
+    };
 
     return (
-        <div style={{ maxWidth: "300px" }}>
+        <div style={{ maxWidth: 300 }}>
             <AmountField
-                inputProps={{
-                    value,
-                    placeholder: "0,00",
-                    onChange: setValue,
-                }}
                 label="Label"
-                currency="RUB"
                 postfix={<HelpBox tooltipSize={ETooltipSize.SM}>Helpful details appear here</HelpBox>}
                 description={
                     <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
                         (21) Description{" "}
-                        <Link href="#" onClick={(event) => event.preventDefault()}>
+                        <Link href="#" onClick={handleLinkClick}>
                             Link text
                         </Link>
                     </Text>
                 }
-                onClear={() => setValue("")}
+                inputProps={{
+                    value,
+                    placeholder: "0,00 ₽",
+                    onChange: setValue,
+                    ref: inputRef,
+                }}
+                currency="₽"
+                onClear={handleClear}
+                clearProps={{ "aria-label": "Очистить сумму" }}
             />
         </div>
     );