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

package/bundle/components/AmountField.md

@@ -0,0 +1,289 @@
+---
+component: AmountField
+category: TextFields
+figma-node: ""
+figma-file: ""
+related: [TextField, NumberField, Amount, FormField, FormFieldInput]
+tokens: []
+stories: stories/TextFields/AmountField.stories.tsx
+version: "1.0"
+---
+
+# AmountField
+
+## Назначение
+
+Поле ввода денежной суммы с автоматическим форматированием: разделители групп
+(пробел), фиксированная дробная часть, запятая как десятичный разделитель,
+отображение валюты справа. Управляет позицией каретки при вводе/удалении так,
+чтобы она не попадала на разделители, и блокирует ввод нецифровых символов
+(кроме запятой/точки).
+
+Построен поверх `TextFieldBase` и `FormFieldInput` (получает визуальное оформление
+и поддержку label/status/prefix/postfix от FormField-стека). Логика форматирования
+инкапсулирована в классе `AmountBaseInputCore`, который внутренне делит работу на
+парсер (`AmountBaseInputParser`) и форматер (`AmountBaseInputFormatter`).
+
+Используй когда: пользователь вводит денежную сумму с валютой и фиксированной
+дробной частью.
+Не используй когда: нужен просто числовой ввод без валюты (используй `NumberField`);
+нужно только отобразить сумму без ввода (используй `Amount`).
+
+---
+
+## Файловая структура
+
+```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-тесты
+```
+
+Особенности:
+- **Нет LESS** — компонент визуально идентичен `TextField`, стили наследуются из
+  `TextFieldBase`/`FormFieldInput`.
+- **Нет `stories/AmountField/`** — stories лежат в `stories/TextFields/AmountField.stories.tsx`
+  (логически относится к группе TextFields).
+- Core-логика разделена на 3 класса намеренно — parser, formatter, core (оркестратор).
+  Такое разделение нужно, чтобы можно было тестировать parse/format изолированно.
+
+---
+
+## Варианты и props
+
+### `IAmountFieldProps extends Omit<ITextFieldBaseProps, "children">`
+
+| 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"` — браузерный автокомплит отключен.
+
+---
+
+## Ключевые особенности реализации
+
+### Разделение 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` вручную
+
+```tsx
+const setRef = (instance) => {
+    refInput.current = instance;  // локальный ref
+    if (typeof ref === "function") ref(instance);
+    else if (ref) ref.current = instance;
+};
+```
+
+Компоненту нужен **и** локальный 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` (пользователь пишет с нуля).
+
+---
+
+## Инварианты
+
+- **`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, не в коде.
+
+---
+
+## 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`. См. их документацию для списка токенов.
+
+---
+
+## Связанные компоненты
+
+- `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`).
+
+---
+
+## Stories
+
+`stories/TextFields/AmountField.stories.tsx`
+Файлы примеров: `stories/TextFields/examples/AmountField/`
+
+| 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` | Композиция с другими компонентами (формы) |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Avatar.md

@@ -0,0 +1,209 @@
+---
+component: Avatar
+category: Avatars
+figma-node: ""
+figma-file: ""
+related: [Badge, IconWrapper]
+tokens:
+  - --triplex-next-Avatar-Background
+stories: stories/Avatar/Avatar.stories.tsx
+version: "1.0"
+---
+
+# Avatar
+
+## Назначение
+
+Контейнер-"плитка" для представления пользовательской идентичности: картинки
+профиля, инициалов, иконки или любого другого ReactNode. Задаёт квадратные
+размеры, скруглённые углы и фоновый цвет. Сам по себе никакого контента не
+рендерит — только обёртка со стилями; визуальное наполнение — через children.
+
+Размер шкалы (XXS → XXL) покрывает от маленькой иконки в списке до большого
+hero-аватара в профиле.
+
+Используй когда: нужно представить пользователя/сущность в виде стандартного
+квадратного блока с картинкой или инициалами.
+Не используй когда: нужен только круглый avatar — в этой реализации формы
+фиксированы (squircle с разными radius), круг не предусмотрен. Если нужны
+инициалы с авто-генерацией — это задача потребителя, компонент не рендерит текст.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Avatar/
+├── Avatar.tsx                     # React.forwardRef, минимальная обёртка
+├── enums.ts                       # EAvatarSize (XXS, XS, SM, MD, LG, XL, XXL)
+├── types.ts                       # IAvatarProps
+├── index.ts                       # Barrel: enums + types + Avatar
+├── styles/Avatar.module.less      # Размеры + border-radius + фон
+└── __tests__/Avatar.test.tsx
+```
+
+Особенности:
+- **Типы и enum вынесены в отдельные файлы** (`types.ts`, `enums.ts`) —
+  это паттерн более крупных компонентов, здесь избыточен, но сохранён для
+  единообразия. Не сводить в один файл без общего рефакторинга стайл-гайда.
+- **Нет helpers, нет subcomponents** — компонент максимально тонкий.
+
+---
+
+## Варианты и props
+
+### `IAvatarProps extends React.HTMLAttributes<HTMLDivElement>`
+
+| Prop | Тип | Обязателен | Описание |
+|---|---|---|---|
+| `size` | `EAvatarSize` | **Да** | Размер + скругление углов. Нет значения по умолчанию — потребитель обязан указать. |
+| `children` | `React.ReactNode` | Нет | Содержимое (через `...HTMLAttributes`). Обычно `<img>`, `<svg>`, `<Text>` или их комбинация. Overflow скрывается (`overflow: hidden`) — контент обрезается по форме. |
+| `className` | `string` | Нет | Объединяется с `styles.avatar + sizeClass` через `clsx`. |
+| `...HTMLDivAttributes` | — | — | Все стандартные атрибуты `<div>`, включая `onClick`, `role`, `aria-*`, `style`. |
+
+### `EAvatarSize` — полная шкала
+
+| Значение | Width/Height | Border-radius |
+|---|---|---|
+| `XXS` | 28px | 6px |
+| `XS` | 32px | 8px |
+| `SM` | 40px | 10px |
+| `MD` | 56px | 16px |
+| `LG` | 80px | 20px |
+| `XL` | 96px | 24px |
+| `XXL` | 128px | 28px |
+
+Радиусы непропорциональны размеру (MD=56px с radius=16px ≈ 28%, XXL=128px с
+radius=28px ≈ 22%). Это **дизайн-решение**, а не формула — не пересчитывать.
+Уменьшение относительного радиуса на больших размерах даёт более "квадратный"
+squircle-вид на крупных аватарах.
+
+---
+
+## Ключевые особенности реализации
+
+### flex-центрирование контента
+
+```less
+.avatar {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+}
+```
+
+Любой children центрируется автоматически. Для `<img>` потребитель обычно задаёт
+`width: 100%; height: 100%; object-fit: cover;` чтобы заполнить всю область —
+compon компонент не делает этого сам, намеренно: потребитель может показать
+маленькую иконку по центру, а не растянутое изображение.
+
+### `overflow: hidden` обрезает по форме
+
+Любой child обрезается по squircle-границам. Это ключевое свойство — картинка
+автоматически получает скруглённые углы без собственного `border-radius`.
+
+### `sizeToClassNameMap` — прямой маппинг enum → className
+
+```ts
+const sizeToClassNameMap = {
+    [EAvatarSize.XXS]: styles.xxs,
+    // ...
+};
+```
+
+Объект, не функция. Полный охват всех значений enum (TypeScript проверяет через
+Record-тип на ключах). При добавлении нового размера — **обновлять обе точки**:
+enum и map.
+
+### Фон через CSS-переменную
+
+`background: var(--triplex-next-Avatar-Background)` — единственный токен
+компонента. Фон виден, когда children прозрачен или меньше области. Потребитель
+может переопределить через `style` или `className` (например, для цветных
+avatar'ов с инициалами).
+
+### `forwardRef` на `<div>`
+
+Ref идёт на root div. Используется для анимаций, позиционирования Tooltip и т.д.
+Не убирать.
+
+---
+
+## Инварианты
+
+- **`forwardRef`** — обязателен. Не убирать.
+- **`size` обязателен** — не делать defaultValue, чтобы потребитель явно выбирал
+  масштаб (избежать случайного использования мелких аватаров в hero-контексте).
+- **`EAvatarSize` значения** — публичное API, не переименовывать.
+- **Размеры и radius в LESS** — не менять без согласования с дизайнером.
+  Значения подобраны под токены отступов сетки (28, 32, 40, 56, 80, 96, 128 —
+  кратны 4/8).
+- **`overflow: hidden`** на root — не убирать, от этого зависит скругление
+  контента.
+- **`background: var(--triplex-next-Avatar-Background)`** — единственный
+  дизайн-токен, не хардкодить цвета.
+- **`flex` центрирование** — не менять на grid без согласования, это затрагивает
+  все потребительские стили внутри Avatar.
+- **Компонент — тонкая обёртка, НЕ рендерит children-специфику** (например, не
+  генерирует инициалы из имени). Всё — на стороне потребителя. Не усложнять.
+- **Типы в отдельном файле (`types.ts`)** — сохранять паттерн для консистентности
+  с другими компонентами, даже если выглядит избыточным.
+
+---
+
+## Accessibility
+
+- **Никаких ARIA-ролей по умолчанию** — `<div>` без роли. Если Avatar
+  интерактивный (clickable), потребитель обязан:
+  - Передать `role="button"` + `tabIndex={0}` + `onKeyDown` для клавиатуры.
+  - Или обернуть в `<button>` / `<a>` (с учётом того, что Avatar — div, а div
+    внутри button валиден, но button внутри div — нет).
+- **`<img>` внутри** — alt-текст задаёт потребитель. Avatar не добавляет
+  `aria-label`, не озвучивает children.
+- **Инициалы как children (`<Text>`)** — screen reader прочитает их как текст.
+  Для полного имени — потребитель может скрыть инициалы от screen reader
+  (`aria-hidden`) и добавить `aria-label="Иван Иванов"` на Avatar.
+
+---
+
+## Дизайн-токены
+
+```
+--triplex-next-Avatar-Background    # Фон контейнера
+```
+
+Единственный токен. Цвет контента (иконки, текста) определяется самим
+контентом, не компонентом.
+
+---
+
+## Связанные компоненты
+
+- `Badge` (`src/components/Badge`) — часто комбинируется с Avatar (индикатор
+  статуса / счётчика в углу). Позиционирование — задача потребителя.
+- `IconWrapper` (`src/components/IconWrapper`) — может быть использован внутри
+  Avatar как children для показа иконки вместо фото.
+- `Text` / Typography — используется для рендера инициалов внутри Avatar.
+
+---
+
+## Stories
+
+`stories/Avatar/Avatar.stories.tsx`
+Файлы примеров: `stories/Avatar/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size` |
+| `Default` | `DefaultExample.tsx` | Базовое использование (XXL) |
+| `Sizes` | `SizesExample.tsx` | Все 7 размеров на одной шкале |
+| `Example` | `ExampleUsage.tsx` | Композиция с другими компонентами |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |