# TagInput

Вільний ввід міток з підказками — з пакетною вставкою і Backspace, який не з'їдає теги мовчки.


Мітки клієнта, галузі, теги задачі. На відміну від
[`UiMultiSelect`](https://ui.tatet.net/docs/components/multi-select), тут значення не обмежені
готовим списком: користувач вводить своє.


Example (app/demos/tag-input/TagInputBasic.vue):

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

const tags = ref<string[]>(['vip', 'терміново'])
const rejected = ref('')

function onReject(tag: string, reason: string) {
  const reasons: Record<string, string> = {
    duplicate: 'така мітка вже є',
    max: 'досягнуто межі',
    length: 'задовга мітка',
    empty: 'порожня мітка',
  }
  rejected.value = `«${tag}» — ${reasons[reason] ?? reason}`
}
</script>

<template>
  <div class="w-full max-w-md space-y-3">
    <UiTagInput
      v-model="tags"
      label="Мітки клієнта"
      placeholder="Введіть і натисніть Enter"
      :max="6"
      :max-length="20"
      hint="Enter або кома завершують мітку. Backspace двічі — видаляє останню."
      @reject="onReject"
    />
    <p v-if="rejected" class="text-sm text-warning">Відхилено: {{ rejected }}</p>
    <p class="text-sm text-muted">Збережеться як: {{ tags.length ? tags.join(', ') : 'порожньо' }}</p>
  </div>
</template>

```


## Backspace не має з'їдати мітки мовчки

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

Тому перше натискання лише **зводить** останню мітку: вона отримує видимий
стан «зараз зникне». Друге видаляє. І кожне видалення оголошується в
`aria-live` — інакше для скрінрідера нічого не відбувається взагалі, бо
фокус лишається в тому самому полі.

## Пакетна вставка

Вставка `a, b, a, c` у поле, де вже є `a`, з `max: 3` має додати `b`,
спинитися на межі й повідомити про це **один раз**. Логіка «на кожне
натискання» тут не працює: вона дала б чотири події і напівзастосований
масив.

Тому весь список проходить через одну функцію, яка перевіряє пакет проти
робочої копії й емітить `update:modelValue` рівно раз. Причина відмови
приходить у `reject` — рішення, чи це помилка й якими словами, лишається
за формою, а не за полем.

## Підказки


Example (app/demos/tag-input/TagInputSuggestions.vue):

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

const tags = ref<string[]>(['Логістика'])

const suggestions = [
  'Логістика', 'Виробництво', 'Роздріб', 'Гуртівня', 'Послуги',
  'IT', 'Будівництво', 'Агро', 'Медицина', 'Освіта',
]
</script>

<template>
  <div class="w-full max-w-md">
    <UiTagInput
      v-model="tags"
      label="Галузі"
      placeholder="Почніть вводити"
      :suggestions="suggestions"
      hint="Список фільтрується, але вільний ввід теж дозволено"
    />
  </div>
</template>

```


З непорожнім `suggestions` поле стає справжнім ARIA-комбобоксом:
`aria-expanded`, `aria-controls`, `aria-activedescendant`, стрілки й Enter
— так само, як у [`UiCombobox`](https://ui.tatet.net/docs/components/combobox). Вільний ввід
при цьому лишається: підказки допомагають, а не обмежують.

Панель переприв'язується не лише на прокрутку й зміну розміру вікна, а й
через `ResizeObserver` на самому полі. Причина конкретна: **поле росте** —
мітки переносяться на новий рядок, висота змінюється, і панель відклеїлася
б від нього тієї ж миті.

## API

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

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

- Мітки й теги, де список значень заздалегідь невідомий.
- Отримувачі листа, ключові слова, довільні категорії.
- Поля, куди значення часто вставляють із буфера списком.

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

- Коли значення обмежені готовим набором — це
  [`UiMultiSelect`](https://ui.tatet.net/docs/components/multi-select) з чекбоксами й
  «вибрати все».
- Для одного значення з підказками —
  [`UiCombobox`](https://ui.tatet.net/docs/components/combobox).
- Для довгого тексту, який лише виглядає як список —
  [`UiTextarea`](https://ui.tatet.net/docs/components/textarea).

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

Мітки — це `<ul>` уже ухвалених значень, а **не** `role="listbox"`. Дві
причини. По-перше, кожна мітка містить кнопку видалення, а `role="option"`
забороняє інтерактивних нащадків — кнопка стала б недосяжною в режимі
читання. По-друге, з підказками в одному віджеті було б два listbox, а
`aria-controls` на полі може вказувати лише на один.

Кнопка видалення кожної мітки має власне ім'я «Видалити ‹мітка›».
Додавання, видалення й досягнення межі оголошуються через
`aria-live="polite"`.

На межі `max` поле стає `readonly`, а не `disabled`. Вимкнене поле
викидало фокус із-під пальців, і Backspace, яким звільняють місце,
переставав працювати. Кнопки видалення мають невидиму зону дотику 45×45 —
сама кнопка лишається дрібною, щоб не роздувати мітку.

## Форма й розміри

`name` віддає формі **мітки** — по прихованому інпуту на кожну, як
[`UiMultiSelect`](https://ui.tatet.net/docs/components/multi-select). Раніше `name` стояв на полі
вводу, і сабміт віддавав недописаний текст замість міток.

`size` керує висотою поля, шрифтом і розміром міток — як у решти полів.
Фокус і помилка — із того самого контракту `uiFieldStyles`: м'яке кільце
через `focus-within`, у стані помилки — червоне. Текст на телефоні 16px:
інакше iOS зумує сторінку при фокусі.

`aria-describedby` вказує рівно на один опис: помилка перекриває підказку,
а не додається до неї.


## Event descriptions

- `update:modelValue`: Новий список міток. Використовуйте через `v-model`.
- `add`: Мітку додано. Приходить уже нормалізоване значення.
- `remove`: Мітку видалено. Приходять саме значення і його колишній індекс.
- `reject`: Мітку відхилено. Другим аргументом — причина - duplicate, max, length або empty.


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