# FormField

Лейбл, опис, підказка й помилка для будь-якого контрола — з тими самими ARIA-зв'язками, що у вбудованих полях.


Поля бібліотеки (`UiInput`, `UiSelect`, `UiTextarea`…) мають власні
`label`, `hint` і `error`. `UiFormField` дає ту саму обв'язку контролам, у
яких її немає: сегментному перемикачу, нативному `<input type="color">`,
сторонньому віджету чи власному полю.


Example (app/demos/form-field/FormFieldBasic.vue):

```vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import UiFormField from '~/components/ui/UiFormField.vue'
import UiToggleGroup from '~/components/ui/UiToggleGroup.vue'
import { fieldClass } from '~/utils/uiFieldStyles'

const density = shallowRef<string | number>('comfortable')
const color = shallowRef('#2563eb')
</script>

<template>
  <div class="flex w-full max-w-md flex-col gap-6">
    <!-- Сегментний перемикач не має власного лейбла — FormField дає і
         видимий заголовок групи, і його зв'язок для скрінрідера. -->
    <UiFormField
      label="Щільність таблиць"
      description="Застосовується до всіх таблиць робочого простору."
      as="fieldset"
    >
      <template #default="{ labelId, describedBy }">
        <UiToggleGroup
          v-model="density"
          block
          :aria-labelledby="labelId"
          :aria-describedby="describedBy"
          :options="[
            { value: 'compact', label: 'Щільно' },
            { value: 'comfortable', label: 'Звичайно' },
            { value: 'relaxed', label: 'Просторо' },
          ]"
        />
      </template>
    </UiFormField>

    <!-- Сторонній чи нативний контрол: id і describedBy — зі слота. -->
    <UiFormField label="Колір бренду" hint="Використовується для кнопок і посилань" :error="color === '#ffffff' ? 'Білий не читається на білому тлі' : undefined">
      <template #label-aside>
        <button type="button" class="rounded-control text-accent hover:underline focus:outline-none focus-visible:ring-2 focus-visible:ring-ring" @click="color = '#2563eb'">
          Скинути
        </button>
      </template>
      <template #default="{ id, describedBy, invalid }">
        <div class="flex items-center gap-2">
          <input
            :id="id"
            v-model="color"
            type="color"
            class="h-10 w-12 shrink-0 cursor-pointer rounded-control border border-line bg-input p-1 md:h-9"
            :aria-describedby="describedBy"
            :aria-invalid="invalid || undefined"
          />
          <input v-model="color" :class="fieldClass('md', { error: invalid })" aria-label="Колір бренду, HEX" />
        </div>
      </template>
    </UiFormField>
  </div>
</template>

```


## Як прив'язати контрол

Слот за замовчуванням отримує все, що треба розкласти на поле:

- `id` — на нього вказує `for` лейбла;
- `labelId` — для `aria-labelledby`, де `for` не працює (групи, власні
  віджети);
- `describedBy` — опис і рівно один із пари «помилка / підказка»;
- `invalid`, `required`, `disabled`.

```vue
<UiFormField label="Колір" hint="HEX або вибір з палітри" :error="error">
  <template #default="{ id, describedBy, invalid }">
    <input :id="id" type="color" :aria-describedby="describedBy" :aria-invalid="invalid || undefined" />
  </template>
</UiFormField>
```

## API

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

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

- Контрол без власного лейбла: `UiToggleGroup`, `UiSlider` без `label`,
  нативні поля, сторонні віджети.
- Група контролів під одним заголовком — `as="fieldset"`: кілька
  чекбоксів, перемикачів.
- Лейбл із дією праворуч — «Забули пароль?», «Скинути» — через слот
  `label-aside`.

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

- Навколо `UiInput`, `UiSelect` та інших полів із власним `label` — вийде
  два лейбли й два описи.
- Для макета форми (колонки, відступи між полями) — це звичайна сітка.

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

`aria-describedby` вказує на `description` і рівно на ОДИН із пари помилка
/ підказка. Обидва одразу — і скрінрідер зачитає інструкцію, яку
користувач щойно порушив, раніше за причину відмови (правило дому).

У режимі `fieldset` лейбл — `<legend>`, і вона стоїть **першою дитиною**
`fieldset`: лише тоді браузер дає групі назву. Вкладена у flex-рядок поруч
із `label-aside`, вона назвою вже не була б. Тому легенда прихована, а
видимий рядок дублює її для ока з `aria-hidden`.

Помилка має `role="alert"` і з'являється разом із текстом — так само, як у
вбудованих полях: стан помилки вмикає САМА наявність тексту.


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