# Toast

Черга сповіщень, доступна з будь-якого місця без прокидання пропсів.


Стан черги оголошено на рівні модуля, тому `useToast()` — singleton: усі
виклики в застосунку працюють з однією чергою. Показати повідомлення можна
звідки завгодно, не заводячи Pinia-стор і нічого не прокидаючи через дерево.

## Приклад


Example (app/demos/toast/ToastTypes.vue):

```vue
<script setup lang="ts">
import UiButton from '~/components/ui/UiButton.vue'
import { useToast, type ToastType } from '~/composables/useToast'

const toast = useToast()

function showAction() {
  const id = toast.info('Посилання залишиться доступним, доки ви не закриєте це повідомлення.', {
    title: 'Звіт готовий до перегляду',
    duration: 0,
    actions: [
      {
        label: 'Переглянути звіт',
        onClick: () => {
          toast.dismiss(id)
          toast.success('Демонстраційний звіт відкрито')
        },
      },
      { label: 'Закрити', onClick: () => toast.dismiss(id) },
    ],
  })
}

// Імітація запиту: та сама картка проходить «Зберігаю…» → «Збережено»,
// без зникнення і появи нової.
function showPromise() {
  const request = new Promise<string>((resolve) => setTimeout(() => resolve('Чернетка'), 1800))
  void toast.promise(request, {
    loading: 'Зберігаю зміни…',
    success: (name) => `«${name}» збережено`,
    error: 'Не вдалося зберегти',
  })
}

function showQueue() {
  const types: ToastType[] = ['success', 'info', 'warning', 'error']
  const messages = [
    ['Зміни збережено', 'Усі поля профілю успішно оновлено.'],
    ['Експорт розпочато', 'Готуємо файл із вашими даними.'],
    ['Сховище майже заповнене', 'Звільніть місце, щоб продовжити завантаження.'],
    ['Не вдалося синхронізувати', 'Перевірте з’єднання та спробуйте ще раз.'],
    ['Запрошення надіслано', 'Колега отримає посилання для приєднання до команди.'],
    ['Доступне оновлення', 'Нова версія містить покращення швидкодії.'],
    ['Термін посилання спливає', 'Поділіться новим посиланням протягом доби.'],
    ['Завантаження перервано', 'Файл перевищує ліміт. Спробуйте завантажити меншу версію.'],
  ]
  messages.forEach(([title, message], index) => {
    toast.show({ title, message: message!, type: types[index % types.length], duration: 0 })
  })
}
</script>

<template>
  <div class="w-full max-w-lg space-y-5">
    <div>
      <p class="mb-3 text-sm font-medium text-ink">Повідомлення для кожної ситуації</p>
      <div class="flex flex-wrap gap-2">
        <UiButton
          size="sm"
          @click="toast.success('Усі зміни вже у вашому профілі.', { title: 'Успішно збережено' })"
          >Успіх</UiButton
        >
        <UiButton
          size="sm"
          variant="outline"
          @click="
            toast.info('Ми повідомимо, щойно файл буде готовий.', { title: 'Експорт розпочато' })
          "
          >Інформація</UiButton
        >
        <UiButton
          size="sm"
          variant="outline"
          @click="toast.warning('Залишилося менше 10% вільного простору.', { title: 'Мало місця' })"
          >Попередження</UiButton
        >
        <UiButton
          size="sm"
          variant="danger"
          @click="
            toast.error('Перевірте підключення та спробуйте ще раз.', {
              title: 'Не вдалося зберегти',
            })
          "
          >Помилка</UiButton
        >
      </div>
    </div>
    <div class="border-t border-line pt-4">
      <p class="mb-3 text-sm font-medium text-ink">Спробуйте взаємодію</p>
      <div class="flex flex-wrap gap-2">
        <UiButton size="sm" variant="outline" @click="showAction">Із діями · без таймера</UiButton>
        <UiButton
          size="sm"
          variant="outline"
          @click="
            toast.info(
              'Експорт містить усі обрані записи, вкладення та історію змін. Підготовка великого файлу може тривати кілька хвилин.\nВи можете продовжувати роботу — ми повідомимо, коли все буде готово.',
              { title: 'Готуємо детальний звіт для вашої команди', duration: 0 },
            )
          "
          >Довгий текст</UiButton
        >
        <UiButton size="sm" variant="outline" @click="showPromise">Проміс</UiButton>
        <UiButton size="sm" variant="outline" @click="showQueue">Показати 8 сповіщень</UiButton>
      </div>
      <p class="mt-3 text-xs leading-relaxed text-muted">
        Змахніть картку вбік, щоб закрити. Від трьох повідомлень з’явиться «Очистити всі».
        Наведення, фокус і дотик призупиняють автозакриття. F8 переводить фокус до сповіщень,
        F8 чи Escape — назад.
      </p>
    </div>
  </div>
</template>

```


## Використання

```ts
const toast = useToast()

toast.success('Зміни збережено')
toast.error('Не вдалося зберегти')

// Прибрати всі повідомлення та їхні таймери, включно з duration: 0.
toast.dismissAll()

// Кнопки дій під повідомленням: дії — дані тоста, а не слот, бо черга
// живе в composable поза шаблоном. Клік по дії сам тост не закриває —
// закривайте через dismiss(id), коли потрібно.
const id = toast.info('Файл завеликий', {
  duration: 0,
  actions: [
    { label: 'Стиснути', onClick: () => compress() },
    { label: 'Закрити', onClick: () => toast.dismiss(id) },
  ],
})

// Тост на час запиту: «Зберігаю…» без автозакриття, потім success чи
// error у тій самій картці. Повертає той самий проміс.
await toast.promise(save(), {
  loading: 'Зберігаю…',
  success: 'Збережено',
  error: (reason) => `Не вдалося: ${String(reason)}`,
})

// Або вручну: змінити тост на місці, не закриваючи й не показуючи новий.
const upload = toast.loading('Завантаження…')
toast.update(upload, { type: 'success', message: 'Файл завантажено' })
```

## Тост-посилання

Коли тост розповідає про щось, що можна відкрити (згадку в чаті,
нагадування про зустріч, документ, яким поділилися), передайте `onClick`:
клік по картці веде туди, а тост закривається сам. Хрестик і дії
працюють як завжди: вони стоять над посиланням і його не запускають.


Example (app/demos/toast/ToastLink.vue):

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

const toast = useToast()
const opened = ref('')

// Тост-посилання: клік по картці веде до того, про що тост, і закриває його.
// Хрестик і дії працюють як завжди й посиланням не є.
function showMention() {
  toast.info('@Ігор глянь, будь ласка, новий макет головної до обіду.', {
    title: 'Олена Коваль · Дизайн',
    onClick: () => (opened.value = 'Відкрито повідомлення Олени в «Дизайн»'),
  })
}

function showReminder() {
  const id = toast.info('«Ранкова зустріч» почнеться за 10 хв', {
    title: 'Нагадування про зустріч',
    duration: 0,
    onClick: () => (opened.value = 'Відкрито картку «Ранкова зустріч» у чаті'),
    actions: [
      {
        label: 'Приєднатися',
        onClick: () => {
          toast.dismiss(id)
          opened.value = 'Ви в зустрічі'
        },
      },
    ],
  })
}
</script>

<template>
  <div class="w-full max-w-lg space-y-3">
    <div class="flex flex-wrap gap-2">
      <UiButton size="sm" variant="outline" @click="showMention">Згадка</UiButton>
      <UiButton size="sm" variant="outline" @click="showReminder">Нагадування з дією</UiButton>
    </div>
    <p class="text-sm text-muted" aria-live="polite">{{ opened || 'Клацніть по картці тосту.' }}</p>
  </div>
</template>

```


```ts
toast.info('@Ігор глянь макет до обіду', {
  title: 'Олена Коваль · Дизайн',
  onClick: () => router.push(`/c/${chatId}?seq=${seq}&mid=${messageId}`),
})
```

Посилання — це перехід, а не рішення: «Так, буду», «Приєднатися»,
«Скасувати» лишаються діями (`actions`). Тост з `onClick` живе щонайменше
10 с, як і з діями. Свайп убік закриває картку, вертикальний рух
прокручує стос — жоден із жестів кліком не вважається.

Контейнер `UiToaster` монтується **рівно один раз**, зазвичай в `app.vue`. Де стоїть стос на екрані від 768px, задає проп `placement` (`top-right` за замовчуванням, `bottom-right`, `bottom-center`): у застосунку з кнопками в шапці знизу сповіщення не перекривають елементи керування. На вужчому екрані стос завжди знизу на всю ширину. Коли знизу екрана стоїть власна панель (плеєр, панель керування), підніміть стос змінною `--toaster-offset-bottom` на `<html>`: `document.documentElement.style.setProperty('--toaster-offset-bottom', '88px')`.

## API

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

### useToast()

| Метод | Призначення |
| --- | --- |
| `show(options): number` | Додає повідомлення й повертає його id. Опції: `message`, `title`, `type`, `duration`, `actions`, `onClick` (тост-посилання). |
| `success / info / warning / error(message, options?): number` | Скорочені виклики для відповідного статусу. |
| `loading(message, options?): number` | Стан очікування без автозакриття. Завершіть через `update` або `dismiss`. |
| `update(id, patch): void` | Змінює тост на місці й перезапускає відлік. Зміна типу без `duration` бере тривалість нового типу. Закритий тост не воскресає. |
| `promise(task, { loading, success, error }, options?): Promise` | `loading` на час проміса, потім `success` чи `error` у тій самій картці. `success` і `error` можуть бути функціями від результату. Повертає той самий проміс. |
| `dismiss(id): void` | Закриває одне повідомлення та скасовує його таймер. |
| `dismissAll(): void` | Очищає всю чергу й усі таймери. Безпечний для порожньої черги. |
| `pause(id) / resume(id): void` | Призупиняє або відновлює автозакриття; після відновлення лишається щонайменше секунда. |

`toasts` — спільний реактивний список у порядку надходження. Дії не
закривають Toast автоматично; `duration: 0` залишає його до ручного закриття.

Типова тривалість — за типом: 3 с, попередження 5 с, помилка 6 с. Тост із
`actions` чи `onClick` живе щонайменше **10 с**: за три секунди треба прочитати, вирішити
і дотягтися до «Скасувати», з клавіатури — ще й дістатися області через F8.

На сервері `show` нічого не додає і повертає `-1`: черга — спільний
singleton модуля, і тост, піднятий під час рендеру одного запиту, потрапляв
би в HTML наступного.

## Вигляд

Картка має ту саму анатомію й метрики, що й `UiAlert`: іконка тону,
заголовок, текст, хрестик, `text-sm` і `p-3`. Тон передає лише іконка, а
поверхня нейтральна, як в інших оверлеїв: тост висить над довільним
вмістом, і відділяє його тінь, а не заливка. Тому черга з різних статусів
не перетворюється на строкатий стос.

## Черга та мобільні пристрої

На екранах від 768 px Toast з’являються зверху праворуч, до 375 px
завширшки. На телефоні — знизу, із полями та відступом від системної панелі.
Висота області обмежена: до 70% екрана на комп’ютері й 50% на мобільному.
Довга черга прокручується, а панель керування лишається доступною.

Від **трьох повідомлень** з’являються лічильник і **«Очистити всі»**.
Кнопка прибирає також постійні повідомлення. Нові Toast додаються в кінець;
список слідує за ними лише тоді, коли ви вже перебуваєте біля кінця.

Свайп **ліворуч або праворуч на 48 px** закриває окрему картку. Короткий
або скасований жест повертає її на місце. Вертикальний рух прокручує
список. Натискання кнопок дій не починає свайп.

Поки курсор, фокус або дотик перебувають у черзі, автозакриття всіх її
повідомлень призупинене, включно з новими. Відлік продовжиться після
завершення всіх взаємодій.

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

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

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

Не повідомляйте тостом про те, що потребує рішення. Тост зникає — питання
лишається. Для цього є `useConfirm()`.

Не дублюйте тостом помилку поля форми: її місце під самим полем, де видно,
що виправляти.

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

Текст оголошується через два live-регіони контейнера, що існують від
монтування: помилки — `aria-live="assertive"`, решта — `polite`, щоб не
перебивати те, що людина читає. Самі картки live-регіонами не є: регіон,
вставлений у DOM разом із текстом, скрінрідери оголошують ненадійно.
Оновлення через `update` чи `promise` оголошується так само.

Поява Toast не перехоплює фокус. **F8** переводить фокус в область
сповіщень, звідки Tab іде кнопками тостів; F8 чи Escape повертають фокус
туди, звідки прийшли. Працює й під відкритою модалкою: область поза
пасткою фокуса, а Escape в ній модалку не закриває.

У тосту-посилання текст — справжня кнопка: до неї доходить Tab, її
відкривають Enter і Space, а назва для скрінрідера — сам текст тосту.
Кільце фокуса обводить усю картку. Після закриття тосту з клавіатури фокус
переходить на хрестик сусіднього, а не на його текст: Enter не відкриє
того, про що людина ще не вирішила.

Кнопки мають видимий індикатор фокуса. Хрестик і дії компактні, як в
Alert, а на дотику кожну добудовує невидима зона 45×45 px — палець не
промахується повз «Закрити» в текст повідомлення. Системне налаштування
зменшеного руху прибирає анімації переміщення.

Тривалість різна за типом: помилка тримається 6 секунд, попередження 5,
решта 3. Помилку треба встигнути прочитати, а не побачити спалах на місці,
де щойно щось пішло не так.

Контейнер має `data-overlay-ignore` — маркер, який поважає `useFocusTrap`.
Без нього тости, що з'явилися під відкритою модалкою, отримали б `inert`
разом з рештою фону, і закрити їх було б неможливо.

## Що виправлено проти вихідної версії

Таймер автозакриття тепер скасовується при ручному. Раніше він лишався
жити: користувач закривав тост хрестиком, а через секунду спрацьовував
відкладений `splice` і зносив **інший** тост, який на той час опинився на
його місці в масиві.

Тони беруть токени статусів. Вихідна версія малювала попередження білим по
`bg-amber-500` — контраст ≈1.9:1, тобто найгірше читабельним було саме те
повідомлення, яке найважливіше прочитати.


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