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

package/bundle/components/MultiselectField.md

@@ -0,0 +1,213 @@
+---
+component: MultiselectField
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [SelectExtendedField, SelectField, Dropdown, Checkbox, FormField]
+tokens: []
+stories: stories/MultiselectField/MultiselectField.stories.tsx
+version: "1.0"
+---
+
+# MultiselectField
+
+## Назначение
+
+Контейнер для **мульти-выбора** из списка: `<SelectExtendedField>` с
+`<MultiselectField.Dropdown>` внутри. Сам компонент — **тонкая обёртка**,
+прокидывающая `size` через `MultiselectFieldContext` к дочерним слотам
+(Header/Content/Footer). Список опций (чекбоксы), кнопки применения,
+заголовок с поиском — реализуются потребителем в Header/Content/Footer.
+
+Используй когда: нужен выбор нескольких элементов с собственным dropdown'ом
+и UI-контролами (поиск, "выбрать все", apply). Для одиночного выбора —
+`SelectField`. Для более гибкого API — `SelectExtendedField` напрямую.
+
+---
+
+## Файловая структура
+
+```text
+src/components/MultiselectField/
+├── MultiselectField.tsx                           # forwardRef, обёртка + Object.assign
+├── MultiselectFieldContext.ts                     # { size }
+├── index.ts                                       # Barrel (только MultiselectField)
+├── components/
+│   ├── MultiselectFieldDropdown.tsx               # Dropdown + FocusTrap + Object.assign
+│   ├── MultiselectFieldDropdownHeader.tsx         # <div>
+│   ├── MultiselectFieldDropdownContent.tsx        # <div> + опц. LoaderScreen
+│   ├── MultiselectFieldDropdownFooter.tsx         # <div>
+│   └── index.ts
+└── styles/*.module.less
+```
+
+---
+
+## Compound-структура
+
+```tsx
+<MultiselectField
+    size={EComponentSize.MD}
+    opened={opened}
+    onOpenedChange={setOpened}
+>
+    <MultiselectField.Target>
+        {/* Target — реэкспорт SelectExtendedFieldTarget */}
+    </MultiselectField.Target>
+
+    <MultiselectField.Dropdown>
+        <MultiselectField.Dropdown.Header>
+            {/* Поиск, "Выбрать все" */}
+        </MultiselectField.Dropdown.Header>
+
+        <MultiselectField.Dropdown.Content loading={loading}>
+            {items.map((it) => (
+                <Checkbox key={it.id} checked={...} onChange={...}>
+                    {it.label}
+                </Checkbox>
+            ))}
+        </MultiselectField.Dropdown.Content>
+
+        <MultiselectField.Dropdown.Footer>
+            <Button>Применить</Button>
+        </MultiselectField.Dropdown.Footer>
+    </MultiselectField.Dropdown>
+</MultiselectField>
+```
+
+`MultiselectField.Target` **= реэкспорт** `SelectExtendedFieldTarget` (не собственный компонент). Используй как псевдоним.
+
+---
+
+## Варианты и props
+
+### MultiselectField — `IMultiselectFieldProps extends ISelectExtendedFieldProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `size` | `EComponentSize` | `MD` | Пишется в `MultiselectFieldContext` и пробрасывается в Dropdown. |
+| `...ISelectExtendedFieldProps` | — | — | Всё поведение outer-контейнера (opened, onOpenedChange, targetRef, …) от SelectExtendedField. |
+
+### MultiselectField.Dropdown — `IMultiselectFieldDropdownProps extends IDropdownProps`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `focusTrapProps` | `FocusTrapProps` | — | Переопределение `focus-trap-react`. |
+| `opened`, `targetRef`, `mobileViewProps`, `...IDropdownProps` | — | — | От `Dropdown`. |
+
+- **`width` захардкожен `EDropdownWidth.MIN_TARGET`** — dropdown всегда минимум как target. Не переопределяется.
+- **`size` берётся из `MultiselectFieldContext`**, не от prop'а.
+
+### MultiselectField.Dropdown.Header / Footer / Content — `HTMLAttributes<HTMLDivElement>`
+
+- Header / Footer — простые `<div>`-слоты с собственной стилизацией (padding, border).
+- Content — `<div tabIndex={-1}>` с `sizeToClassNameMap[size]` для подстройки (scroll height, padding). Имеет prop **`loading: boolean`** — при true показывает `LoaderScreen type="small"` поверх контента.
+
+### MultiselectFieldContext
+
+```ts
+interface IMultiselectFieldContext { size: EComponentSize; }
+```
+
+Публичная точка расширения: при создании кастомных элементов в Content можно читать `size` и адаптировать под него.
+
+---
+
+## Ключевые особенности реализации
+
+### `size` — через Context, не через prop на Dropdown
+
+```tsx
+<MultiselectFieldContext.Provider value={{ size }}>
+    <SelectExtendedField {...props}>{children}</SelectExtendedField>
+</MultiselectFieldContext.Provider>
+```
+
+- Dropdown и Content читают `size` из контекста.
+- **Dropdown переопределяет** `size` prop на Dropdown: `<Dropdown ... size={size} />`. То есть потребительский `size` на Dropdown **игнорируется** — всегда выигрывает context.
+
+### `FocusTrap` внутри Dropdown
+
+```tsx
+<FocusTrap focusTrapOptions={{ clickOutsideDeactivates: true, preventScroll: true, ... }}>
+    <div role="presentation">{children}</div>
+</FocusTrap>
+```
+
+- `clickOutsideDeactivates: true` — клик вне dropdown'а деактивирует trap и закрывает (стандарт для popover/selects).
+- Все потомки оборачиваются в `<div role="presentation">` — требование FocusTrap (нужен single wrapper-element).
+
+### `MultiselectField.Target = SelectExtendedFieldTarget`
+
+```tsx
+Object.assign(..., { Dropdown, Target: SelectExtendedFieldTarget })
+```
+
+- **Это не собственная реализация**, а пересвет. Потребитель видит `.Target` в типах, но фактически это SelectExtendedField's target.
+
+### Content `tabIndex={-1}`
+
+Чтобы скролл внутри Content был фокусируемым мышью/колесиком (и при этом не участвовал в Tab-последовательности). Для переключения между чекбоксами — TAB идёт по интерактивным детям.
+
+### Loader — `LoaderScreen type="small"`
+
+```tsx
+{loading && <LoaderScreen type="small" className={styles.loaderScreen} />}
+```
+
+- Маленький оверлей (см. LoaderScreen-AI).
+- Visibility — потребитель контролирует `loading` prop.
+
+---
+
+## Инварианты
+
+- **`size` через `MultiselectFieldContext`** — публичная точка расширения; не заменять на prop-drilling без решения по обратной совместимости.
+- **`MultiselectField.Target = SelectExtendedFieldTarget`** — псевдоним, не своя реализация. При рефакторинге SelectExtendedField — проверять, что Target совместим.
+- **`EDropdownWidth.MIN_TARGET`** захардкожен — ширина dropdown'а всегда ≥ ширины target'а.
+- **`FocusTrap clickOutsideDeactivates: true`** — контракт: клик вне → закрытие. При смене — потребуется явное `onOpenedChange`.
+- **`MultiselectFieldContext.size` default `MD`** — не менять без breaking-проверки.
+- **`Content.loading`** — контроль loader'а, типичное API.
+- **ForwardRef** на корне `MultiselectField` и на `MultiselectFieldDropdown`.
+- **Header/Footer/Content — `React.FC`** (без forwardRef).
+
+---
+
+## Accessibility
+
+- FocusTrap удерживает фокус внутри dropdown'а → клавиатурная навигация между чекбоксами/кнопками корректна.
+- `role="presentation"` на wrapper'е FocusTrap — правильно: обёртка не несёт семантики.
+- **Нет `aria-multiselectable="true"` на dropdown'е** — потребителям для скринридеров имеет смысл добавить через `...rest` на Content / Dropdown.
+- Чекбоксы внутри Content — стандартный `<Checkbox>` с нативной keyboard-семантикой.
+- Target — `SelectExtendedFieldTarget` обеспечивает `aria-expanded` / `aria-haspopup="listbox"` (проверь в SelectExtendedField, если не — гэп).
+
+---
+
+## Дизайн-токены
+
+Нет собственных. Размеры/padding/цвет от `Dropdown`, `SelectExtendedField`, `Checkbox`.
+
+---
+
+## Связанные компоненты
+
+- `SelectExtendedField` / `SelectExtendedFieldTarget` — основа.
+- `Dropdown` — popover-container.
+- `Checkbox` — типичный элемент в Content.
+- `LoaderScreen` — loader в Content.
+- `focus-trap-react` — FocusTrap.
+
+---
+
+## Stories
+
+`stories/MultiselectField/MultiselectField.stories.tsx`
+Примеры: `stories/MultiselectField/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Notification.md

@@ -0,0 +1,233 @@
+---
+component: Notification
+category: Feedback
+figma-node: ""
+figma-file: ""
+related: [SideOverlay, Alert, UnorderedList, ButtonIcon, Typography]
+tokens: []
+stories: stories/Notification/Notification.stories.tsx
+version: "1.0"
+---
+
+# Notification
+
+## Назначение
+
+Карточка уведомления — `<div role="alertdialog">` с фиксированной
+compound-структурой: `Icon` (опц.), `Body` (Header / Content / List /
+Footer), `Close` (опц.), `Time` (опц.). Содержательная часть собирается
+потребителем; компонент задаёт лэйаут, типографику и поведение close-by-
+hover для side-overlay.
+
+`NotificationGrouped` — визуальная группировка (стопка) — оборачивает
+одну Notification и подкладывает два декоративных `<div>` снизу как
+эффект «стопки карточек» (без логики управления списком).
+
+Используй когда: показываешь информационное / системное сообщение
+(в SideOverlay, Alert, отдельной странице, history-list).
+
+---
+
+## Файловая структура
+
+```text
+src/components/Notification/
+├── Notification.tsx                       # FC (как INotificationSFC) + slots
+├── NotificationGrouped.tsx                # FC, обёртка + декоративный footer
+├── components/
+│   ├── NotificationIcon.tsx               # <div> wrapper для иконки
+│   ├── NotificationBody.tsx               # FC (как INotificationBodySFC) + slots
+│   ├── NotificationHeader.tsx             # <h3>
+│   ├── NotificationBodyContent.tsx        # <Text size=B3 type=PRIMARY tag=div>
+│   ├── NotificationBodyList.tsx           # <UnorderedList> + map по values[]
+│   ├── NotificationFooter.tsx             # <div>
+│   ├── NotificationClose.tsx              # <ButtonIcon> с CrossStrokeSrvIcon16
+│   ├── NotificationTime.tsx               # <span> с временем
+│   └── NotificationGroupedFooter.tsx      # 2 декоративных <div>
+├── index.ts                               # Barrel: Notification + NotificationGrouped
+├── styles/Notification.module.less
+└── __tests__/Notification.test.tsx
+```
+
+---
+
+## Compound-структура
+
+```tsx
+<Notification onClick={...} isShowCloseOnHover>
+    <Notification.Icon><MailIcon /></Notification.Icon>
+    <Notification.Body>
+        <Notification.Body.Header>Заголовок</Notification.Body.Header>
+        <Notification.Body.Content>Текст сообщения</Notification.Body.Content>
+        <Notification.Body.List values={["Один", "Два"]} />
+        <Notification.Body.Footer>
+            <Button>Действие</Button>
+        </Notification.Body.Footer>
+    </Notification.Body>
+    <Notification.Close onClick={handleClose} />
+    <Notification.Time time="12:34" />
+</Notification>
+
+<NotificationGrouped>
+    <Notification>...</Notification>
+</NotificationGrouped>
+```
+
+Контракт компонента: «Может содержать только Icon, Body, Close, Time» — на
+уровне типов не ограничено (`children: ReactElement | ReactElement[]`),
+но стилизация рассчитана только на эти 4 слота.
+
+---
+
+## Варианты и props
+
+### Notification — `INotificationProps extends React.ButtonHTMLAttributes<HTMLElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `children` | `ReactElement \| ReactElement[]` | — | Только Icon/Body/Close/Time. |
+| `withExtraBottomPadding` | `boolean` | `false` | Дополнительный нижний padding (mail-варианты). |
+| `isShowCloseOnHover` | `boolean` | `false` | Close видим только при hover'е (для SideOverlay/Alert). |
+| `onClick` | `() => void` | — | Клик по карточке. |
+| `...HTMLAttributes` | `ButtonHTMLAttributes<HTMLElement>` | — | Прокидываются на корневой `<div>` (имя `Button*` — историческое). |
+
+- Корневой тег — **`<div role="alertdialog">`**, не `<button>` (несмотря на `ButtonHTMLAttributes`).
+- `data-tx={process.env.npm_package_version}` — версия пакета.
+
+### Notification.Body — `INotificationBodySFC` (slots: Header, Content, List, Footer)
+
+- `children: ReactNode` — последовательность заголовка / контента / списка / футера.
+- Каждый слот — `React.FC` (без forwardRef).
+
+### Notification.Body.Header
+
+- `<h3>` с фиксированными стилями. `children: ReactNode`.
+
+### Notification.Body.Content
+
+- `<Text tag="div" size=B3 type=PRIMARY>{children}</Text>` — типографика жёстко зашита.
+
+### Notification.Body.List — `INotificationBodyListProps extends IUnorderedListProps`
+
+- **`values: string[]`** — массив строк, рендерятся как `UnorderedList.Item`.
+- `...IUnorderedListProps` — пробрасывается. `className` мержится с локальным.
+
+### Notification.Body.Footer
+
+- `<div>` с локальной стилизацией. `children: ReactNode`.
+
+### Notification.Close — `INotificationCloseProps extends Omit<IButtonIconProps, "children">`
+
+- **Иконка фиксирована**: `CrossStrokeSrvIcon16 paletteIndex={5}`.
+- `onClick: () => void` (обязателен).
+- `children?: never` — нельзя кастомизировать иконку.
+- Обёрнут в `<span>` для позиционирования.
+
+### Notification.Icon — `INotificationIconProps`
+
+- `children: ReactElement` — потребительская иконка. Обёрнута в `<div>` с фикс.размером (см. styles).
+
+### Notification.Time — `INotificationTimeProps`
+
+- `time: ReactText` (string|number) — рендерится в `<span>` без форматирования.
+
+### NotificationGrouped — `INotificationGroupedProps`
+
+- `children: ReactNode` — обычно одна `<Notification>`.
+- Добавляет **2 декоративных `<div>`** снизу (`NotificationGroupedFooter`) — визуальный эффект «стопки».
+
+---
+
+## Ключевые особенности реализации
+
+### `INotificationSFC` — slots через property assignment, не Object.assign
+
+```tsx
+export const Notification: INotificationSFC = ((props) => {...}) as INotificationSFC;
+Notification.displayName = "Notification";
+Notification.Icon = NotificationIcon;
+// ...
+```
+
+То же — `INotificationBodySFC`. **Нет `forwardRef`** на корне.
+
+### `role="alertdialog"` на корневом `<div>`
+
+- Семантика модального уведомления, требующего внимания. Несмотря на `ButtonHTMLAttributes` в типах — корень всегда `<div>`, поэтому атрибуты `<button>`-only (например `disabled`, `type="submit"`) не применятся.
+
+### `isShowCloseOnHover` — для SideOverlay/Alert
+
+- Класс `styles.showCloseOnHover` — включает CSS-правило, которое делает `Notification.Close` видимым только при hover'е на родителе. Используется в `Alert` и `SideOverlay` (по комментарию в коде).
+
+### `withExtraBottomPadding` — mail-вариант
+
+- Дополнительный нижний padding для случая mail-нотификации (где Footer часто содержит CTA-кнопки).
+
+### `Body.List` — только строки
+
+- `values: string[]` — невозможно использовать ReactNode-элементы (ссылки, форматирование) внутри списка без рефакторинга. Известное ограничение API.
+
+### `Close` — фиксированная иконка
+
+- `CrossStrokeSrvIcon16 paletteIndex={5}` — нельзя заменить (`children: never`). Если нужно другое — потребитель кладёт собственный `ButtonIcon` мимо слота.
+
+### `Grouped` — только декорация
+
+- `NotificationGrouped` не управляет stack'ом нескольких уведомлений; это чистый CSS-эффект «карточка из 3-х слоёв» вокруг одного `Notification`.
+
+---
+
+## Инварианты
+
+- **Корень — `<div role="alertdialog">`**, не интерактивный элемент. `ButtonHTMLAttributes` — историческое API (имя), не означает `<button>` рендера.
+- **`children` — только Icon / Body / Close / Time** (контракт документации; типы шире, но стили рассчитаны только на эти 4 слота).
+- **`Body` — Header / Content / List / Footer** в этом смысловом порядке (CSS закладывает spacing).
+- **`Close` иконка фиксирована**; `children: never`.
+- **`Body.List.values: string[]`** — не `ReactNode[]`. При расширении API — breaking.
+- **`Body.Content` типография зашита** (`B3 / PRIMARY`).
+- **`Body.Header` — `<h3>`**. Heading-уровень не настраивается — может конфликтовать с outline страницы (a11y).
+- **`isShowCloseOnHover` ↔ родитель** — работает только когда `Notification` — внутри SideOverlay/Alert (CSS `:hover` на родителе/самом элементе).
+- **FC, не forwardRef** на всех уровнях (legacy).
+- **`NotificationGrouped` — декорация**, не контейнер для списка.
+- **`data-tx`** — версия пакета на корне.
+
+---
+
+## Accessibility
+
+- `role="alertdialog"` — корректный для модального уведомления, но контейнер не сам управляет `aria-labelledby` / `aria-describedby` — потребитель должен передать их через `...HTMLAttributes`.
+- `<h3>` в `Body.Header` — фиксированный heading-уровень. Для контекстов, где это нарушает outline (например, top-level Alert на странице без h1/h2), — возможен a11y-гэп.
+- `Close` — `<ButtonIcon>` с иконкой crossbar; **нет `aria-label`** в коде (передаётся через `...buttonProps`). Потребитель должен установить `aria-label="Закрыть уведомление"` при создании `<Notification.Close>`.
+- `isShowCloseOnHover` — close-кнопка не видна без hover'а ⇒ для keyboard-only пользователей может быть недоступна, если фокус-стили не показывают её. Проверить!
+- Корень — `<div>`, но `onClick` есть — без `keydown` Enter/Space обработчика. Если `onClick` критичен — клавиатура не работает.
+
+---
+
+## Дизайн-токены
+
+Нет собственных. Цвета/spacing — из глобальных токенов (см. `styles/Notification.module.less`). Иконка `CrossStrokeSrvIcon16` использует `paletteIndex={5}`.
+
+---
+
+## Связанные компоненты
+
+- `SideOverlay` / `Alert` — типичные контейнеры (закрытие по hover).
+- `UnorderedList` — основа `Body.List`.
+- `Text` (Typography) — `Body.Content`.
+- `ButtonIcon` — `Close`.
+- `CrossStrokeSrvIcon16` — иконка close.
+
+---
+
+## Stories
+
+`stories/Notification/Notification.stories.tsx`
+Примеры: `stories/Notification/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/NumberField.md

@@ -0,0 +1,178 @@
+---
+component: NumberField
+category: Form Controls
+figma-node: ""
+figma-file: ""
+related: [TextField, FormField, Amount]
+tokens: []
+stories: stories/NumberField/NumberField.stories.tsx
+version: "1.0"
+---
+
+# NumberField
+
+## Назначение
+
+Текстовое поле для ввода **числовых значений**: фильтрует ввод на лету,
+оставляя только цифры, один десятичный разделитель (`,`) и опциональный
+unary minus в позиции 0. Сам visual layer — `TextFieldBase`; уникальное
+поведение — кастомный `<input>` (`NumberFieldInput`), который чистит
+строку и компенсирует позицию каретки.
+
+Используй когда: поле для ввода числа без формата суммы (без
+group-separator). Для сумм с разделителями разрядов — `Amount`. Для
+строковых значений — `TextField`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/NumberField/
+├── NumberField.tsx        # FC, обёртка над TextFieldBase + NumberFieldInput
+├── NumberFieldInput.tsx   # forwardRef, кастомная фильтрация ввода
+├── types.ts               # INumberFieldProps = ITextFieldProps
+├── index.ts               # Barrel
+└── __tests__/
+```
+
+---
+
+## Варианты и props
+
+### `INumberFieldProps extends ITextFieldProps`
+
+Полностью наследует API `TextField`. Уникального prop'а нет.
+
+| Prop (важные из ITextFieldProps) | Тип | Описание |
+|---|---|---|
+| `inputProps` | `IFormFieldInputProps` | Прокидывается в `<NumberFieldInput>` (включая `value`, `onChange`, `placeholder`, `ref`). |
+| `size` / `status` / `label` / `prefix` / `postfix` / ... | — | От `TextFieldBase`. |
+
+### Внутренние правила фильтрации (`NumberFieldInput`)
+
+| Случай | Поведение |
+|---|---|
+| Цифра `0–9` | оставляется |
+| `,` или `.` (decimal separator) | первый — нормализуется в `,`; второй (если **правее каретки**) — заменяет первый, первый стирается |
+| `-` в позиции `0` | оставляется как unary minus |
+| Любое другое | удаляется |
+| `,` или `.` левее уже существующего разделителя | удаляется |
+
+- Разделитель — `AmountConst.DecimalComma` (`,`).
+- Каретка корректируется: `setCaretPosition(target, caret + (newLength - oldLength))`.
+
+---
+
+## Ключевые особенности реализации
+
+### Фильтр в `onChange`, **не** в `onBeforeInput`
+
+```tsx
+const handleChange = (event) => {
+    const caret = getCaretPosition(event.target);
+    const value = getFilteredValue(event.target.value, caret);
+    const caretShift = value.length - event.target.value.length;
+    event.target.value = value;
+    setCaretPosition(event.target, caret + caretShift);
+    onChange?.(event);
+};
+```
+
+- `event.target.value` мутируется **синхронно** до вызова потребительского `onChange` — потребитель получает уже отфильтрованное значение.
+- React будет видеть это как controlled-input change (если потребитель контролирует значение).
+
+### Поведение «второй разделитель правее каретки»
+
+```ts
+// Если уже был ',' и пользователь вводит ещё один справа от каретки:
+// сдвигаем разделитель вправо, старый затираем.
+if (separatorIndex == -1) buffer.push(",")
+else if (i > caret) { buffer.push(","); buffer[separatorIndex] = ""; ... }
+```
+
+- Полезно для UX: если пользователь печатает `123,4` и ставит курсор после `123`, нажатие `,` снова — переместит разделитель.
+- Если новый разделитель **левее или на каретке** — он игнорируется (старый сохраняется).
+
+### Unary minus только в позиции 0
+
+```ts
+else if (i === 0 && StringUtils.isUnaryMinus(value[i])) buffer.push("-");
+```
+
+- `-` где-либо ещё — удаляется.
+- Поддерживается **один** минус. Двойной минус — невозможен.
+
+### `,` vs `.`
+
+- `.` принимается на ввод (например, нажатие `.` на нумпаде), но конвертируется в `,` (`AmountConst.DecimalComma`).
+- Контракт значения: всегда строка с `,` (если используется decimal). Для backend'а, если ожидается `.` — потребитель должен сам сконвертировать.
+
+### `NumberField` — только `TextFieldBase`-обёртка
+
+```tsx
+export const NumberField = ({ inputProps, ...restProps }) => (
+    <TextFieldBase {...restProps}>
+        <NumberFieldInput {...inputProps} />
+    </TextFieldBase>
+);
+```
+
+- **Не `forwardRef`** на `NumberField` — но `NumberFieldInput` — `forwardRef<HTMLInputElement>`. Если нужен ref на input — потребитель должен передать его через `inputProps.ref`.
+
+### `IFormFieldInputProps` для `inputProps`
+
+- `inputProps` — стандартный для FormField API (`value`, `onChange`, `defaultValue`, `placeholder`, `disabled`, `ref`).
+
+---
+
+## Инварианты
+
+- **Фильтрация — `digit | "," | начальный "-"`** — расширение списка допустимых символов = breaking.
+- **Один разделитель**, конвертируется в `,`.
+- **Unary minus только в позиции 0** — внутри числа `-` теряется.
+- **`AmountConst.DecimalComma = ","`** — изменение глобальной константы повлияет на NumberField.
+- **`event.target.value` мутируется** до вызова потребительского `onChange` — `onChange` получает уже отфильтрованную строку.
+- **Каретка корректируется** через `setCaretPosition` — без потери позиции при удалении невалидных символов.
+- **`NumberFieldInput` — `forwardRef`**, `NumberField` — простая FC.
+- **API = `ITextFieldProps`** — нет собственных props. Расширения = breaking.
+
+---
+
+## Accessibility
+
+- Стандартный `<input>` (через `FormFieldInput`) — клавиатура работает как для TextField.
+- `inputmode` / `type` **не выставляется** на `numeric` / `decimal` — на mobile откроется обычная клавиатура. Потребитель может передать через `inputProps.inputMode = "decimal"`.
+- Скринридеры читают как обычное text input. Для семантики числа — потребитель добавляет `aria-*`.
+
+---
+
+## Дизайн-токены
+
+Нет собственных — наследуются от `TextField` / `FormField`.
+
+---
+
+## Связанные компоненты
+
+- `TextField` / `TextFieldBase` — визуальная база.
+- `FormFieldInput` — нижележащий `<input>`.
+- `Amount` — для денежных значений (с group-separator и фиксированной точностью).
+- `AmountConst` — `DecimalComma`, `DecimalPoint`.
+- `StringUtils` — `isDigit`, `isDecimalSeparator`, `isUnaryMinus`.
+- `inputUtils` — `getCaretPosition`, `setCaretPosition`.
+
+---
+
+## Stories
+
+`stories/NumberField/NumberField.stories.tsx`
+Примеры: `stories/NumberField/examples/`
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |