# SplitButton

Головна дія плюс каретка з альтернативами — складена з Button і Menu, без власного позиціонування.


«Зберегти» і поруч каретка: зберегти як чернетку, як шаблон, з
дублюванням. Одна дія очевидна й потрібна в 90 % випадків, решта — поруч,
але не займають місця.


Example (app/demos/split-button/SplitButtonBasic.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiSplitButton, { type SplitButtonItem } from '~/components/ui/UiSplitButton.vue'

const last = ref('—')

const items: SplitButtonItem[] = [
  { id: 'draft', label: 'Зберегти як чернетку', description: 'Не буде видно клієнту' },
  { id: 'template', label: 'Зберегти як шаблон' },
  { id: 'copy', label: 'Зберегти й дублювати' },
  { id: 'discard', label: 'Скасувати зміни', danger: true },
]
</script>

<template>
  <div class="flex flex-col items-start gap-4">
    <div class="flex flex-wrap items-center gap-3">
      <UiSplitButton
        label="Зберегти"
        :items="items"
        menu-width="16rem"
        @click="last = 'Зберегти'"
        @select="last = $event.label"
      />
      <UiSplitButton
        label="Експорт"
        variant="outline"
        :items="[{ id: 'csv', label: 'CSV' }, { id: 'xlsx', label: 'XLSX' }]"
        @click="last = 'Експорт'"
        @select="last = `Експорт → ${$event.label}`"
      />
      <!-- Альтернатив немає — каретка вимкнена, головна дія працює. -->
      <UiSplitButton label="Надіслати" variant="soft" menu-disabled @click="last = 'Надіслати'" />
    </div>

    <p class="text-sm text-muted">Остання дія: <span class="text-ink">{{ last }}</span></p>
  </div>
</template>

```


## Композиція, а не власна реалізація

Компонент не має ні власного позиціонування, ні власної клавіатури для
панелі: він складений із [`UiButton`](https://ui.tatet.net/docs/components/button) і
[`UiMenu`](https://ui.tatet.net/docs/components/menu). Меню вже вміє фліпатись біля краю вікна,
брати z-index зі спільного стеку і закриватись по Escape — повторювати це
означало б завести другу реалізацію, яка розійдеться з першою.

Обидві кнопки живуть усередині слота `trigger` меню. Це не примха
розкладки: APG вимагає, щоб **ArrowDown на головній кнопці теж відкривав
меню**, а `toggle` доступний лише всередині цього слота. `triggerAttrs`
при цьому йде тільки на каретку — панеллю керує вона, а не група.

## Шов

Дві кнопки з `rounded-control` поруч дають подвоєну лінію на `outline` і
видимий стик на `solid`. Тому в головної зрізаний правий кут, у каретки —
лівий, і каретка підтягнута на `-1px`.

`focus-visible:z-10` на обох обов'язковий: без нього сусідня кнопка
підрізає кільце фокуса рівно з того боку, де вони стикаються.

## API

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

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

- Одна дія явно переважає, але поруч є 2–5 споріднених варіантів.
- Панель запису: «Зберегти» з варіантами збереження.
- Експорт із вибором формату, де один формат — типовий.

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

- Коли рівноцінних варіантів більше п'яти або вони не споріднені: це вже
  [`UiMenu`](https://ui.tatet.net/docs/components/menu) з нейтральним тригером.
- Коли головної дії немає — усі варіанти рівні. Тоді кнопка з кареткою
  бреше про пріоритет.
- Для перемикання вигляду —
  [`UiToggleGroup`](https://ui.tatet.net/docs/components/toggle-group).

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

Група має `role="group"` з `aria-label`: без нього скрінрідер читає дві
сусідні кнопки як незв'язані, і призначення каретки лишається невідомим.

Каретка не має власного тексту, тож її ім'я приходить із `menuLabel`, а
символ `▼` прихований через `aria-hidden`.

ArrowDown на головній кнопці відкриває меню, Enter чи Space на каретці —
теж, одразу з фокусом на першому пункті. Далі працює клавіатура `UiMenu`:
стрілки й typeahead по пунктах, Escape закриває й повертає фокус на тригер.


## Event descriptions

- `click`: Натиснуто головну кнопку.
- `select`: Обрано пункт із меню альтернатив. Приходить сам пункт, а не лише його id.


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