# NumberInput

Числове поле зі степерами, групуванням тисяч і повною клавіатурою — без нативного type=number.


Кількість, ціна, знижка, вага — усе, де число вводять руками, а помилка на
порядок коштує грошей.


Example (app/demos/number-input/NumberInputBasic.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiNumberInput from '~/components/ui/UiNumberInput.vue'

const quantity = ref<number | null>(12)
const discount = ref<number | null>(15)
</script>

<template>
  <div class="grid w-full max-w-md gap-4">
    <UiNumberInput
      v-model="quantity"
      label="Кількість"
      :min="1"
      :max="999"
      hint="Стрілки ↑/↓ змінюють на 1, PageUp/PageDown — на 10"
    />
    <UiNumberInput
      v-model="discount"
      label="Знижка"
      unit="%"
      :min="0"
      :max="100"
      :step="5"
      :steppers="false"
    />
    <p class="text-sm text-muted">
      Разом: {{ quantity ?? 0 }} шт., знижка {{ discount ?? 0 }} %
    </p>
  </div>
</template>

```


## Чому не `type="number"`

Нативне числове поле здається очевидним вибором і не годиться відразу з
трьох причин:

1. Воно **не приймає згрупований рядок**. «14 762,50» для нього невалідне
   значення, тобто групування тисяч вимкнене назавжди.
2. Воно малює **власні стрілки** — поруч із нашими кнопками «−»/«+».
3. Для невалідного вводу воно повертає **порожній рядок** — рівно те саме,
   що й для порожнього поля. Відрізнити «користувач нічого не ввів» від
   «користувач ввів казна-що» неможливо.

Тому тут `type="text"` плюс `inputmode="decimal"` (числова клавіатура на
телефоні) плюс `role="spinbutton"` з `aria-valuenow`/`min`/`max`. Роль
обов'язкова: без неї скрінрідер оголошує звичайне текстове поле, і робота
стрілок виглядає як поламка.

Розбір значення розуміє український запис: кому як десятковий роздільник і
нерозривний пробіл як роздільник тисяч. `Number.parseFloat` на «1 234,5»
повернув би `1`.

## Видимий рядок — не модель


Example (app/demos/number-input/NumberInputPrecision.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiNumberInput from '~/components/ui/UiNumberInput.vue'

const price = ref<number | null>(14762.5)
const weight = ref<number | null>(null)
</script>

<template>
  <div class="grid w-full max-w-md gap-4">
    <!-- Поза фокусом — згруповане «14 762,50», у фокусі — сире «14762.5». -->
    <UiNumberInput
      v-model="price"
      label="Ціна"
      unit="грн"
      :precision="2"
      :step="0.5"
      :min="0"
      hint="Клацніть у поле — групування зникне на час редагування"
    />
    <UiNumberInput
      v-model="weight"
      label="Вага"
      unit="кг"
      :precision="3"
      :step="0.1"
      :min="0"
      placeholder="0,000"
      error="Вкажіть вагу — без неї не порахувати доставку"
    />
  </div>
</template>

```


У фокусі поле показує сире число, поза фокусом — згруповане. Це вимагає
тримати видимий рядок окремо від моделі й синхронізувати його з неї **лише
поки поле не у фокусі**.

Інакше відбувається таке: користувач набирає «1,», батько отримує `1`,
повертає його назад у поле, рядок перетворюється на «1», а каретка
стрибає в кінець. Проміжні стани — «1,», «-», «0,00» — парсяться в число,
але переписувати рядок на них не можна.

Клавіші ArrowUp/ArrowDown, PageUp/PageDown і Home/End одразу оновлюють і
модель, і видимий сирий рядок; після blur рядок знову локалізується.

## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiNumberInput)

## Коли використовувати

- Кількість, ціна, відсоток, вага — будь-яке число з відомим кроком.
- Поля, де стрілки з клавіатури природні: коригування на одиницю.
- Значення з межами, які треба показати користувачу.

## Коли НЕ використовувати

- Для номера телефону, картки, рахунку: це не числа, а рядки цифр, і крок
  для них не має сенсу. Беріть [`UiInput`](https://ui.tatet.net/docs/components/input).
- Для коду підтвердження — [`UiInputOtp`](https://ui.tatet.net/docs/components/input-otp).
- Для вибору з діапазону, де точне значення не важливе —
  [`UiSlider`](https://ui.tatet.net/docs/components/slider).

## Доступність

`role="spinbutton"` з `aria-valuenow`, `aria-valuemin`, `aria-valuemax`.
Коли задано `unit`, значення дублюється в `aria-valuetext` разом з
одиницею — інакше «15» звучить без «відсотків».

Одиниця видима завжди: зі степерами вона стоїть перед «+». Раніше вона
ховалася разом зі степерами — а вони типово ввімкнені, — і «кг» чи «грн»
знав лише скрінрідер. Розрахована на коротку одиницю: `%`, `грн`, `шт.`.

Межа вимикає степер лише тоді, коли значення **є** і вже на ній. Порожнє
поле з `min`/`max` не вимикає нічого: «+» стартує від `min` (або від нуля).

Кнопки «−»/«+» мають `tabindex="-1"`: та сама дія вже доступна стрілками, і
дві зайві зупинки табуляції на кожному числовому полі форми — це дорого.
Розмір кнопок — 45px на мобільному, 36px на десктопі.

Утримання кнопки повторює крок. Таймери знімаються на `pointerup`,
`pointercancel`, `pointerleave` і на приховуванні вкладки: пропустити хоч
один шлях — і значення продовжує рости у фоновій вкладці.


## Event descriptions

- `update:modelValue`: Нове значення або `null`, якщо поле порожнє. Використовуйте через `v-model`.
- `change`: Значення, зафіксоване після втрати фокуса або натискання степерів.


[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/number-input.json)
