# CommandPalette

⌘K-палітра команд із пошуком, групами та глобальним хоткеєм Ctrl+K / Cmd+K.


Палітра НЕ обгортка над `UiModal`, але ділить із ним те саме overlay-ядро:
власний Teleport і backdrop, зареєстровані в одному стеку шарів. Тому
`UiCommandPalette`, відкрита поверх `UiModal`, правильно переживає Escape —
закривається лише верхній оверлей — і не пірнає під неї за z-index.

## Приклад


Example (app/demos/command-palette/CommandPaletteBasic.vue):

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

const open = ref(false)
const lastAction = ref('—')

/*
 * Палітра лишається чистим компонентом: тут немає ані роутів, ані NuxtLink.
 * «Навігація» — звичайні команди, що лише емітять select; рішення, що
 * робити з вибором (перехід, дія, лог), — справа споживача.
 */
const groups = [
  {
    id: 'actions',
    label: 'Дії',
    items: [
      { id: 'create-page', label: 'Створити сторінку', hint: '⌘N' },
      { id: 'import', label: 'Імпорт', hint: '⌘I' },
    ],
  },
  {
    id: 'navigation',
    label: 'Навігація',
    items: [
      { id: 'home-docs', label: 'Головна docs' },
      { id: 'tokens', label: 'Токени' },
    ],
  },
]

function onSelect(payload: { groupId: string; item: string }) {
  const label =
    groups
      .find((group) => group.id === payload.groupId)
      ?.items.find((item) => item.id === payload.item)?.label ?? payload.item
  lastAction.value = `${label} (${payload.groupId}/${payload.item})`
}
</script>

<template>
  <div class="flex flex-col items-center gap-3">
    <UiButton @click="open = true">Відкрити палітру</UiButton>

    <!-- Ctrl+K / Cmd+K працює глобально — це повноцінний хоткей демо, не
         декорація. Спробуйте і з клавіатури. -->
    <p class="text-sm text-muted">
      Або натисніть <kbd class="rounded border border-line bg-subtle px-1.5 py-0.5 text-xs text-ink">Ctrl</kbd>
      <span class="text-muted">+</span>
      <kbd class="rounded border border-line bg-subtle px-1.5 py-0.5 text-xs text-ink">K</kbd>
    </p>

    <p class="text-sm text-muted">Остання дія: {{ lastAction }}</p>

    <!--
      hotkey вимкнено САМЕ в демо: сайт документації має власний Ctrl+K для
      пошуку. З увімкненим хоткеєм одне натискання на цій сторінці
      відкривало два оверлеї одночасно — палітру демо і пошук по сайту.
    -->
    <UiCommandPalette
      v-model="open"
      :groups="groups"
      :hotkey="false"
      @select="onSelect"
    />
  </div>
</template>
```


Натисніть Ctrl+K / Cmd+K у будь-якому місці сторінки — палітра відкриється
і без кнопки. Хоткей не спрацьовує, лише коли фокус уже в текстовому полі
або `contenteditable`: там свої комбінації.

Хоткей не залежить від розкладки: на українській клавіша K дає «л», і
перевірка лише `event.key` мовчки не спрацьовувала саме для основної
аудиторії. Латинські розкладки (Dvorak, Colemak) звіряються за літерою,
кирилиця — за фізичною клавішею.

## API

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

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

Для «все в одному місці»: команди, переходи, дії, які користувач має
знаходити за назвою, не пам'ятаючи, в якому меню вони лежать.

Коли команд багато і вони ростуть — групи плюс фільтр масштабуються краще,
ніж вкладені меню.

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

Якщо команд три і вони видимі кнопками на екрані — палітра лише додає
зайвий шар: кнопки зрозуміліші, ніж рядок пошуку.

Не кладіть у палітру деструктивні дії без підтвердження. Enter у палітрі
спрацьовує одразу, і випадковий рядок не має коштувати видалених даних —
для цього є `UiConfirmDialog`.

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

Поле має `role="combobox"` з `aria-controls` на listbox; рядки —
`role="option"` з `aria-selected` на активному. Навігація ↑↓ іде плоским
списком збігів: заголовки груп не фокусуються. Підсвічений рядок
прокручується у видиму область — `aria-activedescendant` сам нічого не
прокручує.

Кожне відкриття скидає запит і повідомляє про це подією `search` з
порожнім рядком: споживач з асинхронним пошуком інакше показав би під
порожнім полем результати старого запиту.

Фокус утримується всередині панелі, а при закритті повертається на елемент,
з якого палітру відкрили. При відкритті фокус отримує **поле пошуку** — на
відміну від `UiModal`, де типово фокусується сама панель.

## Портування

Ті самі чотири композабли overlay-ядра, що й для `UiModal`, плюс
`uiFieldStyles` для стилю поля пошуку. Якщо в проєкті вже є `UiModal`,
копіювати композабли удруге не потрібно.

## Event descriptions

- `update:modelValue`: Зміна стану відкриття. Використовуйте через `v-model`.
- `select`: Обрано команду. У payload приходять `groupId` та `item` — id групи й елемента, не їхні назви.
- `search`: Запит у полі пошуку змінився — на кожен ввід, включно з порожнім рядком.


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