# NumberField: API

## Пропсы корня

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `value` | `number` | — | Нет | Контролируемое значение. `NaN` означает, что поле пустое. |
| `defaultValue` | `number` | `NaN` | Нет | Начальное значение для неконтролируемого использования. По умолчанию `NaN` — пустое поле. |
| `onChangeValue` | `(value: number) => void` | — | Нет | Вызывается с числом при его изменении и с `NaN`, когда поле очищено. |
| `step` | `number` | `1` | Нет | Шаг, на который значение увеличивается или уменьшается клавишами со стрелками или кнопками счётчика. |
| `min` | `number` | `Number.MIN_SAFE_INTEGER` | Нет | Минимально допустимое значение поля. Соблюдается и через HTML-атрибуты, и во внутренней логике. |
| `max` | `number` | `Number.MAX_SAFE_INTEGER` | Нет | Максимально допустимое значение поля. |
| `ref` | `Ref<HTMLDivElement>` | — | Нет | Ref, передаваемый на элемент. |
| `precision` | `number` | `0` | Нет | Количество знаков после запятой, до которого округляется значение. Полезно для финансовой или научной точности. |
| `changeOnWheel` | `boolean` | `true` | Нет | Включает изменение значения колесом мыши, когда поле в фокусе. |
| `allowEmpty` | `boolean` | `true` | Нет | Позволяет полю быть пустым (null/undefined) вместо значения 0 по умолчанию. Полезно для необязательных числовых полей. |
| `maximumFractionDigits` | `number` | `2` | Нет | Максимальное количество цифр после десятичного разделителя. Управляет точностью числа, когда значение вводится или меняется действиями увеличения/уменьшения. Обычно используется для денежных сумм, измерений или рейтингов, где дробную точность нужно ограничить. Пример: `maximumFractionDigits={0}` → только целые числа; `maximumFractionDigits={2}` → до двух знаков после запятой |
| `disabled` | `boolean` | — | Нет | Отключает весь NumberField. |
| `size` | `TextFieldSize` | `'md'` | Нет | Визуальный размер текстового поля. Влияет на отступы, размер шрифта и общую высоту. 'sm': компактное поле; 'md': по умолчанию; 'lg': просторная раскладка |
| `error` | `boolean` | — | Нет | Показывает поле ввода в состоянии ошибки. |

Также принимает все атрибуты `<div>`.

## Дочерние части

- `NumberFieldInput`: числовой input, связанный с контекстом.
- `NumberFieldIncrementButton`: кнопка увеличения.
- `NumberFieldDecrementButton`: кнопка уменьшения.

### `NumberFieldDecrementButton`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconButtonSize` | — | Нет | Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит кнопку как дочерний компонент через `Slot` (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. |
| `variant` | `ButtonBaseVariant` | — | Нет | Определяет визуальный стиль кнопки: цветовую схему и акцент. |
| `appearance` | `ButtonBaseAppearance` | — | Нет | Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). |
| `disabled` | `boolean` | — | Нет | Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с `asChild`: отключённым состоянием владеет дочерний элемент, например через `aria-disabled` или ссылку без `href`. |
| `className` | `string` | — | Нет | Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. |
| `children` | `ReactNode` | — | Нет | Содержимое кнопки — текст, иконка или любой React-узел. |
| `ref` | `Ref<HTMLButtonElement>` | — | Нет | Ref, передаваемый на нативный элемент `<button>`. Даёт прямой доступ к DOM для управления фокусом или измерений. |

Также принимает все атрибуты `<button>`.

### `NumberFieldIncrementButton`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `size` | `IconButtonSize` | — | Нет | Размер контейнера кнопки. Управляет отступами и общей кликабельной областью. |
| `asChild` | `boolean` | — | Нет | Если true, рендерит кнопку как дочерний компонент через `Slot` (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег. |
| `variant` | `ButtonBaseVariant` | — | Нет | Определяет визуальный стиль кнопки: цветовую схему и акцент. |
| `appearance` | `ButtonBaseAppearance` | — | Нет | Настраивает структурный внешний вид кнопки (фон, рамка и т. д.). |
| `disabled` | `boolean` | — | Нет | Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с `asChild`: отключённым состоянием владеет дочерний элемент, например через `aria-disabled` или ссылку без `href`. |
| `className` | `string` | — | Нет | Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей. |
| `children` | `ReactNode` | — | Нет | Содержимое кнопки — текст, иконка или любой React-узел. |
| `ref` | `Ref<HTMLButtonElement>` | — | Нет | Ref, передаваемый на нативный элемент `<button>`. Даёт прямой доступ к DOM для управления фокусом или измерений. |

Также принимает все атрибуты `<button>`.

### `NumberFieldInput`

| Проп | Тип | По умолчанию | Обязательный | Описание |
| --- | --- | --- | --- | --- |
| `ref` | `Ref<HTMLInputElement>` | — | Нет | Ref, передаваемый на нижележащий нативный элемент `<input>`. |

Также принимает все атрибуты `<input>`.

## Типы

- `NumberFieldProps`
- `NumberFieldInputProps`
- `NumberFieldIncrementProps`
- `NumberFieldDecrementProps`
- `NumberFieldSize`

## Модель состояния

- Корень отслеживает, находится ли текущее значение на min или max.
- Стрелки и, если включены, события колеса меняют значение на шаг через логику корня. Как и в `<input type="number">`, колесо меняет только поле в фокусе; без фокуса оно прокручивает страницу.
- Шаг сохраняет десятичные знаки значения и `step` (`0.7` + `0.1` даёт `0.8`).
- `onKeyDown` корня выполняется после встроенной обработки стрелок и не заменяет её.
- Корень принимает `value`, `defaultValue` и `onChangeValue` как число, `NaN` — для пустого поля; `NumberFieldInput` показывает отформатированный текст и по-прежнему вызывает собственные `onChange` и `onInput`. Сброс формы восстанавливает `defaultValue`, если поле не контролируемое.