# Carousel

Керована карусель зі swipe, клавіатурою, autoplay-паузою та reduced motion.


## Приклад


Example (app/demos/carousel/CarouselBasic.vue):

```vue
<script setup lang="ts">
import { shallowRef } from 'vue'

const active = shallowRef(0)
const slides = [
  {
    eyebrow: 'Компоненти',
    title: 'Copy-first без lock-in',
    text: 'Код компонента живе у вашому проєкті й лишається повністю редагованим.',
    meta: '0 залежностей',
  },
  {
    eyebrow: 'Доступність',
    title: 'Клавіатура як контракт',
    text: 'ARIA, focus і reduced motion перевіряються разом із поведінкою.',
    meta: '142 тести',
  },
  {
    eyebrow: 'Теми',
    title: 'Семантичні токени',
    text: 'Light і dark використовують один набір ролей, а не сирі кольори.',
    meta: '2 теми',
  },
]
</script>

<template>
  <UiCarousel v-model="active" :items="slides" loop autoplay aria-label="Переваги tatetUI">
    <template #slide="{ item }">
      <article class="min-h-52 overflow-hidden rounded-overlay border border-line bg-card shadow-card">
        <!-- Верхня акцентна смуга: тонкий слід бренду, що не конкурує з
             контентом, але прибирає «порожнє» відчуття плоского слайда. -->
        <div class="h-1 bg-gradient-to-r from-primary-400 to-primary-600" aria-hidden="true" />
        <!-- На мобільному: менші відступи (p-5), текст 16px щоб iOS Safari
             не зумував сторінку при взаємодії, і заголовок без md-стрибків
             розміру. Зростає тільки до lg — там уже екран для десктопу. -->
        <div class="flex flex-col justify-center p-5 sm:p-8 lg:p-10">
          <p class="text-xs font-semibold uppercase tracking-widest text-accent">{{ item.eyebrow }}</p>
          <h3 class="mt-2 text-xl font-bold text-ink sm:mt-3 sm:text-2xl lg:text-3xl">{{ item.title }}</h3>
          <p class="mt-2 max-w-xl text-base leading-6 text-muted sm:mt-3 md:leading-7">{{ item.text }}</p>
          <p class="mt-4 inline-flex items-center gap-1.5 text-xs font-medium text-muted sm:mt-6">
            <span class="inline-block size-1.5 rounded-full bg-success" aria-hidden="true" />
            {{ item.meta }}
          </p>
        </div>
      </article>
    </template>
  </UiCarousel>
</template>
```


## API

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

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

Для невеликої послідовності промо, onboarding або медіа, де один елемент має
бути в центрі уваги. Компонент підтримує controlled index і кастомний слот
слайда.

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

Не ховайте критичний контент чи основну навігацію в каруселі. Для списку
карток краще звичайна grid, а для великих наборів — pagination.

## На мобільних пристроях

Основний жест — свайп. Поріг перемикання масштабується від ширини треку
(15%, але не менше 40px), а швидкий короткий змах (флік до 200 мс) листає
слайд навіть без «дотягування» — відчуття жесту однакове на телефоні та
планшеті. Жест класифікується за домінантною віссю: горизонтальний рух
веде слайд один-в-один (з гумовими краями без `loop`), вертикальний —
цілком віддається скролу сторінки. Вказівник захоплюється
`setPointerCapture`, тож палець, що з'їхав із компонента, не обриває
перетягування. Другий палець не збиває активний жест. Стрілки навігації на
coarse-вказівнику приховані — вони конфліктували б із пальцем поверх
контенту; навігація — свайп і крапки-індикатори з зоною дотику 44×44.

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

Region і слайди мають carousel-ролі та позицію «N з M». Стрілки, Home й End
працюють із клавіатури — на самій каруселі та її власних кнопках, але не
на полях і посиланнях усередині слайда: там стрілки належать курсору, а
перехоплення ще й робило слайд із фокусом `inert`, і фокус падав у
`<body>`. Autoplay зупиняється під час focus і hover, має явну
кнопку Pause, стає на паузу, доки вкладка у фоні, та не запускається при
`prefers-reduced-motion` — який також вимикає slide-transition переходу.

Перетягування (`draggable`) — піксель-в-піксель за вказівником; клік одразу
після жесту проковтується, щоб не «натискати» те, що було під пальцем у
момент відпускання. `touch-pan-y` лишає вертикальне гортання сторінці, тож
жест не конфліктує з прокруткою.

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

Логіка жесту — чисті функції в `app/utils/carousel.ts` (`dragThreshold`,
`dragAxis`, `shouldAdvance`, `rubberBandDelta`, `swipeDirection`), покриті
тестами без рендеру. Трек зсувається `translate3d` — шар на GPU без
перестворень на кожному pointermove.

## Event descriptions

- `update:modelValue`: Індекс активного слайда.
- `change`: Новий індекс після переходу.


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