# Modal

Модальне вікно зі стеком шарів, пасткою фокуса й блокуванням прокрутки.


Знизу до `sm` вікно — bottom sheet, вище — центрований діалог. Це не декор:
центроване вікно на телефоні з піднятою клавіатурою просто не вміщається.

## Приклад


Example (app/demos/modal/ModalBasic.vue):

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

const open = ref(false)
</script>

<template>
  <UiButton @click="open = true">Відкрити вікно</UiButton>

  <UiModal v-model="open" title="Видалити проєкт?" size="sm">
    <p class="text-muted">
      Дію не можна скасувати. Разом із проєктом буде видалено всі його сторінки
      та завантажені файли.
    </p>

    <template #footer>
      <UiButton variant="tonal" @click="open = false">Скасувати</UiButton>
      <UiButton variant="danger" @click="open = false">Видалити</UiButton>
    </template>
  </UiModal>
</template>

```


Шапка — як header bar у GNOME: те саме тло, що й вміст, без окремої смуги й
постійної лінії, а назва по центру. Саме центр відрізняє шапку від тексту під
нею: назва ліворуч над лівим абзацом читалася як його перший рядок. Лінія під
шапкою з'являється, лише коли вміст прокручено під неї, а над футером — поки
під кнопками лишився непрокручений вміст. Власний слот `header` (поле пошуку,
вкладки) лишається ліворуч на всю ширину.

Хрестик — кругле тло без рамки (`h-9`), тихе за кольором, але в нього легко
влучити й мишею, і пальцем. Кнопки футера мають однакову мінімальну
ширину (7rem) і центрований підпис — «Скасувати» й «Зберегти» не різняться на
око. У режимі bottom sheet (до `sm`) вони ділять ширину порівну: дві дії
поруч читаються рівноцінними й вціляють під великий палець.

## Свайп униз (bottom sheet)

`swipe-to-close` додає шторці нативний жест: над шапкою з'являється ручка, і
вікно можна потягнути вниз — за ручку або за шапку (крім її кнопок і полів).
Відпустили далі чверті висоти чи різким кидком — вікно закривається, інакше
повертається на місце. Жест діє лише поки вікно bottom sheet (до `sm`): за
шапку центрованого діалогу не тягають. Типово вимкнено — поведінка без пропа
не змінилася.

Свайп — явна дія, як хрестик: працює з `closable` і навіть у `persistent`
вікні. Якщо закриття треба підтвердити («Відкинути зміни?»), керуйте
`v-model` самі — відмовлена шторка повертається на місце, а не висить за
краєм.


Example (app/demos/modal/ModalSwipe.vue):

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

const open = ref(false)
</script>

<template>
  <UiButton @click="open = true">Відкрити шторку</UiButton>

  <UiModal v-model="open" title="Поділитися" size="sm" swipe-to-close>
    <p class="text-muted">
      На телефоні вікно — шторка знизу. Потягніть її за ручку чи шапку вниз,
      щоб закрити, як нативний sheet. На ширшому екрані вікно центроване, і
      жест вимкнено.
    </p>

    <template #footer>
      <UiButton variant="tonal" @click="open = false">Скасувати</UiButton>
      <UiButton @click="open = false">Надіслати</UiButton>
    </template>
  </UiModal>
</template>

```


## Вкладені оверлеї

Усі оверлеї бібліотеки ділять один стек шарів. Відкрийте другий рівень і
натисніть Escape — закриється лише верхній. Те саме з підказкою чи меню
всередині вікна: Escape спершу закриває їх, а вікно з формою — лише
наступним натиском.


Example (app/demos/modal/ModalNested.vue):

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

const first = ref(false)
const second = ref(false)
</script>

<template>
  <UiButton variant="outline" @click="first = true">Вкладені оверлеї</UiButton>

  <UiModal v-model="first" title="Перший рівень" size="md">
    <p class="text-muted">
      Відкрийте другий рівень і натисніть Escape — закриється лише верхній.
      Це працює завдяки спільному стеку шарів: кожен оверлей знає, чи він
      наразі верхній.
    </p>
    <template #footer>
      <UiButton variant="outline" @click="second = true">Відкрити другий</UiButton>
    </template>
  </UiModal>

  <UiModal v-model="second" title="Другий рівень" size="sm">
    <p class="text-muted">
      z-index цього вікна на 10 більший за попереднє. Прокрутка фону лишається
      заблокованою, поки відкрито хоч один оверлей.
    </p>
  </UiModal>
</template>

```


## API

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

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

Для короткої взаємодії, яка має перервати основний потік: підтвердження,
компактна форма, перегляд деталі.

Якщо форма велика або користувач має звірятися зі сторінкою під нею —
беріть `UiDrawer`.

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

Не кладіть у модалку багатокрокові майстри. Заблокована прокрутка фону плюс
обмежена висота панелі роблять довгий вміст незручним саме там, де його
найбільше.

Не ставте `:closable="false"`, доки у вікні немає власного шляху виходу.
Цей прапорець вимикає **всі** способи закриття одразу: і хрестик, і Escape,
і клік по фону. Разом із пасткою фокуса, яка робить решту сторінки `inert`,
вікно стає глухим кутом — вийти можна хіба перезавантаженням вкладки. Саме
так свого часу поводився пошук по цій документації. Якщо закриття справді
має бути лише явним, лишіть у вікні власну кнопку, яка змінює `v-model`.

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

Панель має `role="dialog"`, `aria-modal="true"` і назву — з `title` через
`aria-labelledby` або з `aria-label`, якщо заголовок замінено слотом.

Для підтверджень, що переривають роботу й чекають відповіді, задайте
`role="alertdialog"` і `ariaDescribedby` — id елемента з текстом питання.
Коли фокус одразу стає на кнопку, без опису скрінрідер оголошує лише
заголовок і кнопку й мовчить про те, що саме підтверджується. Так робить
`UiConfirmDialog`.

Коли слот `header` містить не заголовок, а керування — поле пошуку,
перемикач — назву треба задати props `ariaLabel` явно. Інакше
`aria-labelledby` вказує на контейнер слота, і назву вікна браузер
обчислює зі **значення** поля: діалог оголошувався як «Діалог: тек», щойно
користувач набирав «текст».

Фокус утримується всередині панелі, а при закритті повертається на елемент,
з якого вікно відкрили. Решта прямих дітей `<body>` на час відкриття
позначаються `inert` і `aria-hidden` — з лічильником, тож вкладені
оверлеї можна закривати в будь-якому порядку: атрибути знімаються, коли
елемент відпустив останній оверлей.

Типово фокус отримує **сама панель, а не перший інпут**: на мобільних
автофокус в інпуті одразу піднімає клавіатуру і з'їдає пів екрана. Якщо
потрібно інакше — задайте `initialFocus`.

## Портування

Компонент не працює сам по собі: йому потрібні композабли зі списку
залежностей вище. Чотири з них (`useOverlayStack`, `useScrollLock`,
`useFocusTrap`, `useReducedMotion`) становлять overlay-ядро, а
`useScrollEdges` вмикає лінії шапки й футера під час прокрутки. Усі вони
спільні для `UiModal`, `UiDrawer` і `UiConfirmDialog` — копіюйте їх один раз
на проєкт.


## Event descriptions

- `update:modelValue`: Зміна стану відкриття. Використовуйте через `v-model`.
- `close`: Вікно закрито — будь-яким способом — хрестиком, Escape або кліком по фону.


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