# Lightbox

Повноекранна галерея — фото, відео, YouTube, iframe і власні слайди; щипок, збільшення з інерцією, поворот, слайдшоу, повний екран, політ із мініатюри.


Галерея стоїть на тому самому стеку шарів, що й Modal та Drawer: її можна
відкрити з модалки, а Escape закриє лише верхній шар. Фон — майже чорний в
обох темах: фото читається на темному, а кнопки й підписи несуть власну
поверхню картки.

Орієнтир за можливостями — [Fancybox](https://fancyapps.com/fancybox/):
відео й сторінки поруч із фото, щипок і збільшення з інерцією, поворот і
віддзеркалення, слайдшоу, повний екран, закриття змахом, політ фото з
мініатюри. Усе без залежностей — компонент копіюється разом із трьома
композаблами оверлеїв.

Відкрийте фото й закрийте його знову: воно виростає з мініатюри й
повертається в неї, навіть якщо в галереї догорнули до іншого.


Example (app/demos/lightbox/LightboxGallery.vue):

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

const toast = useToast()

const images: LightboxItem[] = [
  { src: '/demo/vase-terracotta.svg', alt: 'Ваза з червоної глини на світлому тлі', caption: 'Ваза «Теракота» — червона глина, ручне формування, 32 см' },
  { src: '/demo/vase-cobalt.svg', alt: 'Висока ваза під кобальтовою поливою', caption: 'Ваза «Кобальт» — кам’яна маса, полива з крапом' },
  { src: '/demo/mug-cream.svg', alt: 'Чашка з кремовою поливою і коричневим обідком', caption: 'Чашка «Вершки», 350 мл' },
  { src: '/demo/bowl-sage.svg', alt: 'Широка миска під зеленою поливою', caption: 'Миска «Шавлія», діаметр 18 см' },
  { src: '/demo/plate-speckled.svg', alt: 'Тарілка з рябою поливою, вигляд згори' },
]

const open = shallowRef(false)
const index = shallowRef(0)

// Мініатюри на сторінці: з них фото «виростає» при відкритті й у них же
// повертається при закритті — навіть якщо в галереї догорнули до іншого.
const thumbs: (HTMLElement | null)[] = []

function show(at: number) {
  index.value = at
  open.value = true
}
</script>

<template>
  <div class="w-full">
    <ul class="grid grid-cols-3 gap-2 sm:grid-cols-5">
      <li v-for="(image, at) in images" :key="image.src">
        <!-- Мініатюра — кнопка: відкриття галереї — дія, і фокус після
             закриття повернеться саме сюди. -->
        <button
          type="button"
          class="block w-full overflow-clip rounded-card border border-line transition-[border-color,box-shadow] hover:border-line-strong focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-ring-offset"
          :aria-label="`Відкрити фото ${at + 1}: ${image.alt}`"
          @click="show(at)"
        >
          <img
            :ref="(element) => (thumbs[at] = element as HTMLElement | null)"
            :src="image.src"
            alt=""
            class="aspect-square w-full object-cover"
          />
        </button>
      </li>
    </ul>

    <UiLightbox v-model="open" v-model:index="index" :images="images" :origin="(i) => thumbs[i]">
      <template #actions="{ image }">
        <UiButton
          variant="outline"
          size="icon"
          class="rounded-full"
          label="Поділитися"
          @click="toast.info(`Посилання на «${image.alt}» скопійовано`)"
        >
          <svg class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <circle cx="18" cy="5" r="3" /><circle cx="6" cy="12" r="3" /><circle cx="18" cy="19" r="3" />
            <path d="m8.6 13.5 6.8 4M15.4 6.5l-6.8 4" />
          </svg>
        </UiButton>
      </template>
    </UiLightbox>
  </div>
</template>

```


## Відео, сторінки й власні слайди

Вид слайда визначається за адресою: посилання YouTube чи Vimeo стає
вбудованим плеєром, файл `.mp4`/`.webm`/`.ogv`/`.mov` — `<video>`, решта —
зображенням. Явний `type` потрібен лише для `iframe` (мапа, PDF, будь-яка
сторінка) і `custom` — власного вмісту через слот `custom`.


Example (app/demos/lightbox/LightboxMedia.vue):

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

const toast = useToast()

/*
 * Вид слайда визначається за адресою: файл .mp4 — відео, посилання
 * YouTube — вбудований плеєр. Явний type потрібен лише для iframe і
 * власного вмісту.
 */
const items: LightboxItem[] = [
  {
    src: '/demo/vase-terracotta.svg',
    alt: 'Ваза з червоної глини на світлому тлі',
    caption: 'Фото: ваза «Теракота», 32 см',
  },
  {
    src: '/demo/pottery-wheel.mp4',
    poster: '/demo/pottery-wheel.jpg',
    alt: 'Ваза обертається на гончарному колі',
    caption: 'Відеофайл: ваза на гончарному колі, 5 с',
  },
  {
    src: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ',
    alt: 'Big Buck Bunny — відкритий мультфільм Blender Foundation',
    caption: 'YouTube: плеєр вбудовується без cookies, доки не натиснуто «відтворити»',
  },
  {
    type: 'iframe',
    src: 'https://www.openstreetmap.org/export/embed.html?bbox=34.570%2C49.938%2C34.650%2C49.978&layer=mapnik&marker=49.9584%2C34.6093',
    alt: 'Мапа Опішні — столиці українського гончарства',
    caption: 'Iframe: мапа OpenStreetMap',
  },
  {
    type: 'custom',
    src: 'workshop',
    alt: 'Майстер-клас у майстерні',
    caption: 'Власний вміст через слот custom — з кнопками й формами',
  },
]

const tiles = [
  { label: 'Фото', image: '/demo/vase-terracotta.svg' },
  { label: 'Відео', image: '/demo/pottery-wheel.jpg' },
  { label: 'YouTube', image: null },
  { label: 'Мапа', image: null },
  { label: 'Свій слайд', image: null },
]

const open = shallowRef(false)
const index = shallowRef(0)

function show(at: number) {
  index.value = at
  open.value = true
}
</script>

<template>
  <div class="w-full">
    <ul class="grid grid-cols-2 gap-2 sm:grid-cols-5">
      <li v-for="(tile, at) in tiles" :key="tile.label">
        <button
          type="button"
          class="relative block w-full overflow-clip rounded-card border border-line bg-subtle transition-[border-color,box-shadow] hover:border-line-strong focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-ring-offset"
          :aria-label="`Відкрити: ${items[at]!.alt}`"
          @click="show(at)"
        >
          <img v-if="tile.image" :src="tile.image" alt="" class="aspect-square w-full object-cover" />
          <span v-else class="flex aspect-square w-full items-center justify-center text-muted" aria-hidden="true">
            <svg class="h-8 w-8" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
              <rect x="3.5" y="5" width="17" height="14" rx="2" />
              <path d="M3.5 9h17" />
            </svg>
          </span>
          <span class="absolute bottom-2 left-2 rounded-full border border-line bg-card/90 px-2 py-0.5 text-xs font-medium text-ink shadow-card">
            {{ tile.label }}
          </span>
        </button>
      </li>
    </ul>

    <UiLightbox v-model="open" v-model:index="index" :images="items" aria-label="Медіа галереї">
      <template #custom="{ active }">
        <div class="w-[min(26rem,calc(100vw-2rem))] rounded-overlay border border-line bg-card p-5 text-ink shadow-overlay">
          <p class="text-xs font-medium tracking-wide text-muted uppercase">Субота, 11:00</p>
          <h3 class="mt-1 text-lg font-semibold">Майстер-клас на гончарному колі</h3>
          <p class="mt-2 text-sm text-muted">
            Дві години з майстринею: центрування глини, перша чашка, покриття поливою. Випалений
            виріб заберете за тиждень.
          </p>
          <div class="mt-4 flex flex-wrap gap-2">
            <UiButton :disabled="!active" @click="toast.success('Місце заброньовано')">Записатися</UiButton>
            <UiButton variant="outline" :disabled="!active" @click="toast.info('Програму надіслано на пошту')">Програма</UiButton>
          </div>
        </div>
      </template>
    </UiLightbox>
  </div>
</template>

```


Плеєр і iframe монтуються **лише для поточного слайда**. Сусід із YouTube,
змонтований заздалегідь, почав би грати за кадром, а кожен зайвий iframe —
це ще й чужі cookies; сусіди показують обкладинку (`poster`, `thumbnail`, а
для YouTube — його власне прев'ю). YouTube вбудовується з
`youtube-nocookie.com`, Vimeo — з `dnt=1`: галерея не має права вирішувати
за людину про трекінг.

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

## Інструменти й слайдшоу

`toolbar` — перелік кнопок верхньої панелі в потрібному порядку. Лічильник
і хрестик є завжди, а кнопка, якій нема чого робити, не з'являється: повний
екран на iPhone (там на весь екран розгортається лише `<video>`), слайдшоу й
мініатюри для одного слайда.


Example (app/demos/lightbox/LightboxTools.vue):

```vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import UiButton from '~/components/ui/UiButton.vue'
import UiLightbox, { type LightboxItem } from '~/components/ui/UiLightbox.vue'

const images: LightboxItem[] = [
  { src: '/demo/vase-terracotta-detail.svg', alt: 'Крупний план поливи й пояска теракотової вази', caption: 'Прозора полива лише на пояску — решта матова' },
  { src: '/demo/vase-cobalt-detail.svg', alt: 'Крупний план кобальтової поливи з білим крапом', caption: 'Білий крап — окиси в поливі, кожна ваза унікальна' },
  { src: '/demo/plate-speckled.svg', alt: 'Тарілка з рябою поливою, вигляд згори', caption: 'Тарілка «Ряба», діаметр 26 см' },
  { src: '/demo/bowl-sage.svg', alt: 'Широка миска під зеленою поливою', caption: 'Миска «Шавлія», діаметр 18 см' },
]

const open = shallowRef(false)
const slideshow = shallowRef(false)

function show(autoplay: boolean) {
  slideshow.value = autoplay
  open.value = true
}
</script>

<template>
  <div class="flex flex-wrap gap-2">
    <UiButton @click="show(false)">Переглянути з інструментами</UiButton>
    <UiButton variant="outline" @click="show(true)">Запустити слайдшоу</UiButton>

    <!-- Колесо гортає, а не збільшує; щипок на тачпаді однаково збільшує.
         Панелі ховаються через 2,5 с без руху миші. -->
    <UiLightbox
      v-model="open"
      :images="images"
      :toolbar="['zoomIn', 'zoomOut', 'rotate', 'flip', 'download', 'slideshow', 'fullscreen', 'thumbnails']"
      :autoplay="slideshow"
      :interval="2500"
      :idle="2500"
      transition="fade"
      wheel="navigate"
      loop
    />
  </div>
</template>

```


| Кнопка | Що робить |
|---|---|
| `zoom` | Перемикає «вписано» ↔ збільшено: до натурального розміру великого фото, але щонайменше вдвічі |
| `zoomIn`, `zoomOut` | Крок збільшення — у 1,5 раза |
| `rotate` | Дві кнопки: поворот на чверть оберту проти і за годинниковою стрілкою; повернуте фото вписується заново |
| `flip` | Дві кнопки: віддзеркалення по горизонталі й по вертикалі — в осях екрана, навіть після повороту |
| `slideshow` | Слайдшоу з лінією прогресу. Чекає, поки фото завантажиться, і зупиняється на останньому кадрі без `loop` |
| `fullscreen` | Повний екран через Fullscreen API; закриття галереї виходить із нього, лише якщо вмикала саме вона |
| `thumbnails` | Сховати чи показати стрічку мініатюр |
| `download` | Завантажити оригінал (`download` слайда або `src`) |

Слайдшоу чекає й на відео: обрізати ролик на третій секунді гірше, ніж
зачекати, тож файлове відео саме перегортає слайд, коли закінчиться, а
YouTube, Vimeo й сторінки тримають слайдшоу на паузі. `autoplay` запускає
слайдшоу при відкритті — і тоді кнопка паузи є завжди, навіть якщо її немає
в `toolbar`. При `prefers-reduced-motion` слайдшоу саме не стартує.

`idle` ховає панелі й стрілки, коли миша не рухається, — фото лишається
саме. Панелі не зникають з-під курсора, що стоїть на них, і з-під фокуса з
клавіатури, а Tab до схованої кнопки повертає їх. На дотику панелі ховає й
повертає одиночний дотик до фото.

## Жести й клавіатура

| Дія | Миша | Дотик | Клавіатура |
|---|---|---|---|
| Наступний / попередній | стрілки на краях, колесо з `wheel="navigate"` | свайп | ← → PageUp PageDown Home End |
| Збільшити | клік по фото, колесо, щипок на тачпаді | подвійний дотик, щипок | `+` |
| Рухати збільшене | перетягування з інерцією | палець з інерцією | стрілки |
| Зменшити | клік по фото, колесо | подвійний дотик, щипок | `−`, `0`, Escape |
| Сховати панелі | без руху миші (`idle`) | дотик до фото | — |
| Слайдшоу | кнопка | кнопка | Пробіл |
| Закрити | хрестик, клік у порожнє поле, змах угору чи вниз | змах угору чи вниз, хрестик | Escape |

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

Свайп використовує ту саму логіку, що [`UiCarousel`](https://ui.tatet.net/docs/components/carousel):
поріг масштабується від ширини екрана, швидкий змах гортає навіть коротшим
рухом, а вісь жесту визначається до того, як щось рухати, — горизонталь
гортає, вертикаль закриває. Під час свайпу видно сусідній слайд: у DOM
завжди три слайди, поточний і два сусіди, і їхні фото вантажаться наперед.

Збільшене фото, дотягнуте до краю, віддає решту руху треку: наступний слайд
виїжджає, як у галереї телефона, без зменшення назад. Щипок тримає під
пальцями ту саму деталь, трохи пружинить за межами масштабу й повертається в
них після відпускання. Колесо збільшує в точці курсора, а щипок на тачпаді
(браузер надсилає його як Ctrl + колесо) — завжди, навіть із
`wheel="navigate"`: це жест масштабу, а не прокрутки.

## Політ із мініатюри

`origin` — функція, що за індексом повертає мініатюру на сторінці:
`:origin="(i) => thumbs[i]"`. Фото виростає з неї при відкритті й повертається
в неї при закритті — з того місця, де воно зараз: збільшене чи недотягнуте
змахом. Мініатюра з `object-cover` обрізає фото — політ відтворює й
обрізання (clip-path у власних координатах зображення), і заокруглення кутів
обгортки.

Галерея просто згасає, коли летіти нікуди або чесно не вийде: при
`prefers-reduced-motion`, для повернутого чи віддзеркаленого фото і коли
мініатюра не видна — прокручена за край сторінки чи каруселі, а не лише за
межі вікна. Якщо фото ще вантажиться, політ чекає його не довше 600 мс:
анімація, що стартує через секунду після кліку, виглядає як збій.

## Поля слайда

| Поле | Для чого |
|---|---|
| `src` | Адреса фото, відеофайлу, відео YouTube/Vimeo чи сторінки. Для `custom` — унікальний ключ |
| `alt` | Текстова альтернатива фото чи назва відео. Обов'язкове: для скрінрідера це і є слайд |
| `type` | `image`, `video`, `iframe`, `custom`. Типово — за `src` |
| `caption` | Підпис під слайдом. Складніший — через слот `caption` |
| `thumbnail` | Мініатюра для стрічки. Поки вантажиться повне фото, вона ж стоїть на його місці заглушкою |
| `srcset`, `sizes` | Відповідні розміри. Під час збільшення галерея підставляє в `sizes` фактичну ширину, і браузер довантажує більший файл |
| `width`, `height` | Натуральний розмір: заглушка не виходить за нього, iframe бере з нього пропорції |
| `poster` | Обкладинка відео — і в плеєрі, і в стрічці |
| `download` | Адреса для кнопки «Завантажити», якщо вона інша, ніж `src`; `false` — не пропонувати |

## Підписи й мова

Усі рядки галереї — у `labels`. Задавайте лише ключі, що змінюються: у
проєкті з i18n це об'єкт із `t()`, і зміна мови оновить підписи без
перемонтування.

```vue
<UiLightbox
  v-model="open"
  :images="images"
  :labels="{
    close: t('gallery.close'),
    slide: (position, total, title) => t('gallery.slide', { position, total, title }),
  }"
/>
```

## Список, що дотягується

Месенджер відкриває галерею з одним фото, а сусідні підвантажує вже після
відкриття. Два правила, щоб це не було видно:

- **Підміна списку під відкритою галереєю.** Якщо разом зі списком `images`
  змінився й `index` і тепер вказує на ту саму адресу, що показана на екрані,
  галерея стає на новий номер на місці: слайд лишається тим самим вузлом, трек
  не їде, стрічка мініатюр не гортається. Якщо `index` вказує на інше фото —
  це звичайний перехід.
- **`loading-more`.** Поки список дотягується, стрічка мініатюр і кнопки
  слайдшоу та мініатюр займають місце навіть для одного слайда (кнопка
  слайдшоу неактивна). Без цього, коли прийдуть решта фото, стрічка забере
  висоту в сцени, і фото стрибне. Вимкніть прапорець, щойно список
  дотягнувся або не дотягнувся.

```vue
<UiLightbox
  v-model="open"
  v-model:index="index"
  :images="images"
  :loading-more="loadingMore"
/>
```

## Посилання на слайд

Хеш у стилі Fancybox (`#gallery-3`) галерея не пише сама: у застосунку з
роутером він сперечався б із роутером за історію. Ті самі дві речі —
посилання на конкретне фото й «Назад», що закриває галерею, — дає `v-model`
на query-параметр:

```vue
<script setup lang="ts">
const route = useRoute()
const router = useRouter()

const photo = computed(() => Number(route.query.photo ?? -1))
let pushed = false

const open = computed({
  get: () => photo.value >= 0,
  set: (value) => {
    if (value) return
    // Галерею відкрили ми — «Назад» просто прибирає свій запис. Прийшли
    // за посиланням одразу на фото — back() вивів би з сайту.
    if (pushed) router.back()
    else router.replace({ query: { ...route.query, photo: undefined } })
    pushed = false
  },
})
const index = computed({
  get: () => Math.max(photo.value, 0),
  set: (value) => router.replace({ query: { ...route.query, photo: value } }),
})

function show(at: number) {
  pushed = true
  router.push({ query: { ...route.query, photo: at } })
}
</script>

<template>
  <UiLightbox v-model="open" v-model:index="index" :images="images" />
</template>
```

Відкриття — `push`, гортання — `replace`, тож «Назад» закриває галерею
одним натиском, а не гортає назад кожен переглянутий кадр.

## API

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

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

- Фото товару, об'єкта, роботи в портфоліо — коли деталь важлива і
  мініатюри замало.
- Вкладення в чаті чи тікеті: фото, відео, PDF — в одній галереї.
- Огляд, де фото чергуються з відео чи мапою.

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

- Для послідовності слайдів у потоці сторінки — це `UiCarousel`.
- Для одного декоративного зображення без деталей: відкриття на весь
  екран нічого не додає.
- Для форми чи довгого тексту: слот `custom` — для вмісту поряд із фото, а
  не замість `UiModal` чи `UiDrawer`.

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

Діалог з `aria-modal`, назвою з `ariaLabel` і пасткою фокуса. Фокус при
відкритті стає на саму панель, а не на хрестик: стрілки гортають одразу, а
перший Tab доходить до першої кнопки. Після закриття фокус повертається
туди, звідки галерею відкрили, — тому мініатюри на сторінці мають бути
кнопками. З `origin` — на мініатюру слайда, який переглядали, туди ж, куди
летить фото: кнопка, з якої відкрили, часто вже недосяжна (у каруселі, що
йде за індексом галереї, її слайд став `inert`), і фокус падав би в
`<body>`.

Поточний слайд оголошує live-регіон: «Зображення 2 з 5: Хол», для відео —
«Відео 2 з 5: …». Під час слайдшоу оголошення вимикаються: кадри
змінюються самі, і скрінрідер інакше говорив би без упину. `alt`
обов'язковий у кожного слайда. Мініатюри мають `aria-current` на поточній, а
сусідні слайди — `inert` і `aria-hidden`: ні Tab, ні скрінрідер у них не
потрапляють. Фокус зі слайда, що виїжджає, переходить на панель, а не
падає в `<body>`.

Кнопки-перемикачі (слайдшоу, повний екран, мініатюри, збільшення) міняють
назву — «Запустити слайдшоу» / «Зупинити слайдшоу», — а не тримають одну
назву з `aria-pressed`: разом ці два способи суперечили б один одному.

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

Усі рухи — перехід між слайдами, політ із мініатюри, інерція, анімація
збільшення — вимикаються при `prefers-reduced-motion`.

## Чого немає і чому

- **Хеш в адресі** — див. «Посилання на слайд»: роутер робить це краще.
- **Захист від збереження** (`protected` у Fancybox) — заборона правого
  кліку нікого не зупиняє, а скрінрідерам і людям із розширеннями заважає.
- **Ajax-вміст** — у Vue для цього є слот `custom` із власним
  завантаженням даних.

## Деталі реалізації

Уся геометрія — чисті функції в `app/utils/lightbox.ts`, покриті тестами
без рендеру: межі масштабу (`zoomLimits`, `fitScale` для повернутого фото),
збільшення навколо точки (`zoomAround`), межі зсуву (`panBounds`), гумові
краї, інерція (`releaseVelocity`, `decay`), поріг закриття змахом, розбір
посилань YouTube і Vimeo, перетворення для польоту з мініатюри
(`originTransform`, `visibleFraction`).

Слайд вважається готовим після `decode()`, а не після події `load`: зображення
має `decoding="async"`, і між завантаженням файлу та першою відмальовкою
лишалися порожні кадри — заглушка-мініатюра вже зникла, а фото ще не видно.

Під пальцем збільшення й трек рухаються імперативно — записом `transform`
у стиль, а не реактивним `:style`: інакше кожен `pointermove` перемальовував
би весь компонент разом зі стрічкою мініатюр. Реактивні лише похідні
прапорці, що змінюються рідко: «збільшено», «на межі масштабу».


## Event descriptions

- `update:modelValue`: Зміна стану відкриття. Використовуйте через `v-model`.
- `update:index`: Поточний слайд змінився — стрілкою, свайпом, мініатюрою чи слайдшоу. Використовуйте через `v-model:index`.
- `close`: Галерею закрито — хрестиком, Escape, змахом угору чи вниз або кліком у порожнє поле.


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