# SwipeStack

Стек двох екранів на телефоні — деталі в'їжджають поверх списку, свайп праворуч повертає назад.


Навігація телефона як у нативному застосунку: верхній екран (деталі)
в'їжджає справа, нижній (список) відступає ліворуч у тінь і лишається
змонтованим — повернення миттєве, прокрутка й пошук на місці. Свайп
праворуч з будь-якого місця верхнього екрана тягне його за пальцем, і під
ним видно нижній. Відпустили далі ~40% ширини чи кидком — компонент
доводить екран за край і шле `back`; кидок назад чи коротший рух повертає
екран на місце.

## Приклад


Example (app/demos/swipe-stack/SwipeStackBasic.vue):

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'

const threads = [
  { id: 1, title: 'Дизайн', preview: 'Нові макети вже в теці' },
  { id: 2, title: 'Продукт · запуск', preview: 'Домовились на четвер' },
  { id: 3, title: 'Підтримка', preview: 'Клієнт підтвердив виправлення' },
]
const openId = ref<number | null>(null)
const current = computed(() => threads.find((thread) => thread.id === openId.value) ?? null)
</script>

<template>
  <UiSwipeStack
    :open="openId !== null"
    class="h-96 w-full max-w-sm rounded-overlay border border-line"
    base-class="bg-card"
    page-class="bg-main"
    @back="openId = null"
  >
    <template #base>
      <header class="flex h-12 shrink-0 items-center border-b border-line px-4 font-semibold text-ink">Розмови</header>
      <ul class="min-h-0 flex-1 overflow-y-auto">
        <li v-for="thread in threads" :key="thread.id">
          <button
            type="button"
            class="flex w-full flex-col items-start gap-0.5 px-4 py-3 text-left transition-colors hover:bg-hover active:bg-hover focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
            @click="openId = thread.id"
          >
            <span class="font-medium text-ink">{{ thread.title }}</span>
            <span class="text-sm text-muted">{{ thread.preview }}</span>
          </button>
        </li>
      </ul>
    </template>
    <template #page>
      <header class="flex h-12 shrink-0 items-center gap-1 border-b border-line bg-card px-2">
        <UiButton variant="ghost" size="icon" label="Назад" @click="openId = null">
          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 18l-6-6 6-6" /></svg>
        </UiButton>
        <span class="truncate font-semibold text-ink">{{ current?.title }}</span>
      </header>
      <div class="min-h-0 flex-1 overflow-y-auto p-4 text-sm text-muted">
        <p>{{ current?.preview }}.</p>
        <p class="mt-3">На дотиковому екрані потягніть цей екран праворуч — під ним видно список, і відпущений далі 40% ширини екран повертає назад.</p>
      </div>
    </template>
  </UiSwipeStack>
</template>

```


Стан тримає батько: `open` — чи відкритий верхній екран, а на `back` він
його закриває. Зазвичай це роутер: `open` — «маршрут не корінь», `back` —
`router.back()`. Тоді і системне «назад» браузера, і кнопка «Назад» у шапці
дають ту саму анімацію.

```vue
<UiSwipeStack :open="route.name !== 'home'" class="h-full" @back="router.back()">
  <template #base><ChatList /></template>
  <template #page><RouterView /></template>
</UiSwipeStack>
```

## Жест

Свайп не починається з полів, повзунків, полотна й елементів із
`touch-action: none` — вони самі обробляють палець; для решти є
`data-no-swipe` і проп `swipe`. Області вертикальної прокрутки всередині
верхнього екрана (`overflow-y-auto`) компонент сам переводить у
`touch-action: pan-y pinch-zoom`: без цього кожна з них забирала б
горизонтальний рух собі. Горизонтальні області прокрутки (код, вкладки)
лишаються як є — там палець прокручує вбік.

Власний свайп «назад» браузера (Safari на iPhone, жест Android) уже показує
свою анімацію: компонент це бачить (`hasUAVisualTransition`) і другої
поверх неї не програє. Зі зменшеним рухом (`prefers-reduced-motion`) екрани
змінюються без зсуву, а жест лишається — його рух веде палець.

## Своя розмітка

Коли нижній і верхній екрани не вкладаються в слоти (у розмітки є власні
обгортки й обробники), логіку дає композабл `useSwipeStack`: стилі обох
екранів, затемнення, тінь і хуки для `<Transition>` — без глобального CSS.

```ts
const stack = useSwipeStack({ open, pageEl, back: () => router.back() })
// <div :style="stack.underStyle.value" :class="stack.underHidden.value ? 'invisible' : ''">…</div>
// <Transition v-bind="stack.transition"><div v-if="open" ref="pageEl" :style="stack.pageStyle.value">…</div></Transition>
```

## API

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

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

Для телефонної розкладки «список → деталі»: чати й переписка, пошта й лист,
налаштування й підрозділ. На широкому екрані ті самі екрани зазвичай стоять
поруч (`UiResizablePanels`), і стек не потрібен.

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

Не для глибокої навігації: стек має рівно два рівні. Третій рівень (деталі
деталей) — ще один `UiSwipeStack` чи `useSwipeStack` усередині верхнього
екрана. Не для модальних дій — це `UiModal` чи `UiDrawer`: вони мають
затемнений фон, пастку фокуса й Escape.

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

Нижній екран, поки на ньому стоїть верхній, позначено `inert`: до нього не
доходять ні Tab, ні скрінрідер, а після завершення переходу він ще й
невидимий. Свайп — додатковий шлях: у верхньому екрані має бути видима
кнопка «Назад».


## Event descriptions

- `back`: Свайп довів верхній екран за край — закрийте його (зазвичай крок назад у роутері).


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