feat(ui): add command palette for quick navigation and actions

Author: serhalp

app/app.vue

@@ -144,6 +144,8 @@ if (import.meta.client) {
       <NuxtPage />
     </div>
 
+    <CommandPalette />
+
     <AppFooter />
 
     <ScrollToTop />

app/components/AppFooter.vue

@@ -53,6 +53,10 @@ const closeModal = () => modalRef.value?.close?.()
                 {{ $t('shortcuts.section.global') }}
               </p>
               <ul class="mb-6 flex flex-col gap-2">
+                <li class="flex gap-2 items-center">
+                  <kbd class="kbd">⌘K</kbd>/<kbd class="kbd">Ctrl+K</kbd>
+                  <span>{{ $t('shortcuts.command_palette') }}</span>
+                </li>
                 <li class="flex gap-2 items-center">
                   <kbd class="kbd">/</kbd>
                   <span>{{ $t('shortcuts.focus_search') }}</span>

app/components/CommandPalette.client.vue

@@ -0,0 +1,323 @@
+<script setup lang="ts">
+import type { CommandPaletteCommand } from '~/types/command-palette'
+
+const { isOpen, query, close, toggle, view, setView } = useCommandPalette()
+const { groupedCommands, flatCommands, hasResults, submitSearchQuery, trimmedQuery } =
+  useCommandPaletteCommands()
+const keyboardShortcuts = useKeyboardShortcuts()
+const route = useRoute()
+
+const modalRef = useTemplateRef<{
+  showModal: () => void
+  close: () => void
+}>('modalRef')
+const inputRef = useTemplateRef<{
+  focus: () => void
+}>('inputRef')
+
+const activeIndex = shallowRef(-1)
+const previouslyFocused = shallowRef<HTMLElement | null>(null)
+
+const dialogId = 'command-palette-modal'
+const inputId = `${dialogId}-input`
+const descriptionId = `${dialogId}-description`
+const statusId = `${dialogId}-status`
+const resultsId = `${dialogId}-results`
+
+const inputDescribedBy = computed(() => `${descriptionId} ${statusId}`)
+const isLanguageView = computed(() => view.value === 'languages')
+const modalSubtitle = computed(() =>
+  isLanguageView.value ? $t('command_palette.subtitle_languages') : $t('command_palette.subtitle'),
+)
+
+const statusMessage = computed(() => {
+  const count = flatCommands.value.length
+
+  if (!count && trimmedQuery.value) {
+    return $t('command_palette.status.no_matches_search', { query: trimmedQuery.value })
+  }
+
+  if (trimmedQuery.value) {
+    return $t('command_palette.status.matching', { count }, count)
+  }
+
+  return $t('command_palette.status.available', { count }, count)
+})
+
+const commandIndexMap = computed(() => {
+  return new Map(flatCommands.value.map((command, index) => [command.id, index]))
+})
+
+function getDialog() {
+  return document.querySelector<HTMLDialogElement>(`#${dialogId}`)
+}
+
+function getInputElement() {
+  return document.querySelector<HTMLInputElement>(`#${inputId}`)
+}
+
+function getCommandElements() {
+  return Array.from(
+    getDialog()?.querySelectorAll<HTMLButtonElement>('[data-command-item="true"]') ?? [],
+  )
+}
+
+function focusInput() {
+  inputRef.value?.focus()
+}
+
+function focusCommand(index: number) {
+  const elements = getCommandElements()
+  const element = elements[index]
+  if (!element) return
+
+  activeIndex.value = index
+  element.focus()
+}
+
+async function handleCommandSelect(command: CommandPaletteCommand) {
+  await command.action()
+}
+
+function handleGlobalKeydown(event: KeyboardEvent) {
+  if (event.isComposing) return
+
+  const isToggleShortcut =
+    event.key.toLowerCase() === 'k' &&
+    (event.metaKey || event.ctrlKey) &&
+    !event.altKey &&
+    !event.shiftKey
+
+  if (isToggleShortcut) {
+    if (!keyboardShortcuts.value) return
+
+    event.preventDefault()
+    toggle()
+    return
+  }
+
+  if (!isOpen.value) return
+
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    const currentIndex = getCommandElements().findIndex(el => el === document.activeElement)
+    const nextIndex =
+      currentIndex < 0 ? 0 : Math.min(currentIndex + 1, flatCommands.value.length - 1)
+    focusCommand(nextIndex)
+    return
+  }
+
+  if (event.key === 'ArrowUp') {
+    event.preventDefault()
+    const currentIndex = getCommandElements().findIndex(el => el === document.activeElement)
+    if (currentIndex <= 0) {
+      activeIndex.value = -1
+      focusInput()
+      return
+    }
+
+    focusCommand(currentIndex - 1)
+    return
+  }
+
+  if (event.key === 'Enter' && document.activeElement === getInputElement()) {
+    const firstCommand = flatCommands.value[0]
+    if (!firstCommand) {
+      if (!trimmedQuery.value) return
+
+      event.preventDefault()
+      void submitSearchQuery()
+      return
+    }
+
+    event.preventDefault()
+    void handleCommandSelect(firstCommand)
+  }
+}
+
+function handleDialogClose() {
+  if (isOpen.value) {
+    close()
+    return
+  }
+
+  activeIndex.value = -1
+  previouslyFocused.value?.focus()
+  previouslyFocused.value = null
+}
+
+function handleBack() {
+  setView('root')
+}
+
+watch(
+  isOpen,
+  async open => {
+    const dialog = getDialog()
+
+    if (open) {
+      previouslyFocused.value =
+        document.activeElement instanceof HTMLElement ? document.activeElement : null
+      await nextTick()
+      if (!dialog?.open) {
+        modalRef.value?.showModal()
+      }
+      await nextTick()
+      focusInput()
+      activeIndex.value = -1
+      return
+    }
+
+    if (dialog?.open) {
+      modalRef.value?.close()
+      return
+    }
+
+    activeIndex.value = -1
+    previouslyFocused.value?.focus()
+    previouslyFocused.value = null
+  },
+  { flush: 'post' },
+)
+
+watch(
+  () => route.fullPath,
+  () => {
+    if (isOpen.value) {
+      close()
+    }
+  },
+)
+
+watch(query, () => {
+  activeIndex.value = -1
+})
+
+useEventListener(document, 'keydown', handleGlobalKeydown)
+</script>
+
+<template>
+  <Modal
+    ref="modalRef"
+    :id="dialogId"
+    :modalTitle="$t('command_palette.title')"
+    :modalSubtitle="modalSubtitle"
+    class="max-w-2xl p-0 overflow-hidden"
+    @close="handleDialogClose"
+  >
+    <div class="-mx-6 -mt-6">
+      <p :id="descriptionId" class="sr-only">
+        {{ $t('command_palette.instructions') }}
+      </p>
+      <p :id="statusId" class="sr-only" role="status" aria-live="polite">
+        {{ statusMessage }}
+      </p>
+
+      <div class="border-b border-border px-4 py-4 sm:px-6">
+        <button
+          v-if="isLanguageView"
+          type="button"
+          class="mb-3 inline-flex items-center gap-2 rounded-md px-2 py-1 font-mono text-xs text-fg-muted transition-colors duration-150 hover:text-fg focus-visible:outline-accent/70"
+          @click="handleBack"
+        >
+          <span class="i-lucide:arrow-left rtl-flip inline-block h-3.5 w-3.5" aria-hidden="true" />
+          {{ $t('command_palette.back') }}
+        </button>
+        <label :for="inputId" class="sr-only">{{ $t('command_palette.input_label') }}</label>
+        <InputBase
+          :id="inputId"
+          ref="inputRef"
+          v-model="query"
+          type="search"
+          :placeholder="$t('command_palette.placeholder')"
+          no-correct
+          size="large"
+          class="w-full"
+          :aria-describedby="inputDescribedBy"
+          :aria-controls="resultsId"
+        />
+      </div>
+
+      <div
+        :id="resultsId"
+        class="max-h-[60vh] overflow-y-auto px-2 py-3 sm:px-3"
+        :aria-label="$t('command_palette.results_label')"
+        role="region"
+      >
+        <p v-if="!hasResults" class="px-3 py-6 text-center text-sm text-fg-muted">
+          {{ $t('command_palette.empty') }}
+        </p>
+        <p v-if="!hasResults && trimmedQuery" class="px-3 pb-6 text-center text-sm text-fg-subtle">
+          {{ $t('command_palette.empty_search_hint', { query: trimmedQuery }) }}
+        </p>
+
+        <div v-else class="flex flex-col gap-3">
+          <section
+            v-for="group in groupedCommands"
+            :key="group.id"
+            :aria-labelledby="`${dialogId}-group-${group.id}`"
+          >
+            <h3
+              :id="`${dialogId}-group-${group.id}`"
+              class="px-3 pb-1 text-xs font-mono uppercase tracking-wide text-fg-subtle"
+            >
+              {{ group.label }}
+            </h3>
+
+            <ul class="m-0 flex list-none flex-col gap-1 p-0">
+              <li v-for="command in group.items" :key="command.id">
+                <button
+                  type="button"
+                  class="w-full cursor-pointer rounded-lg border border-transparent px-3 py-3 text-start transition-colors duration-150 hover:border-border hover:bg-bg-subtle focus-visible:outline-accent/70"
+                  :class="
+                    activeIndex === (commandIndexMap.get(command.id) ?? -1)
+                      ? 'border-border bg-bg-subtle'
+                      : ''
+                  "
+                  data-command-item="true"
+                  :aria-current="command.active ? 'true' : undefined"
+                  @click="void handleCommandSelect(command)"
+                  @focus="activeIndex = commandIndexMap.get(command.id) ?? -1"
+                  @mouseenter="activeIndex = commandIndexMap.get(command.id) ?? -1"
+                >
+                  <span class="flex items-center gap-3">
+                    <span
+                      class="inline-block h-4 w-4 shrink-0 text-fg-subtle"
+                      :class="command.iconClass"
+                      aria-hidden="true"
+                    />
+                    <span class="min-w-0 flex-1">
+                      <span class="block truncate text-sm font-medium text-fg">
+                        {{ command.label }}
+                      </span>
+                    </span>
+                    <span
+                      v-if="command.badge"
+                      class="rounded border border-border bg-bg px-2 py-0.5 text-xs font-mono text-fg-muted"
+                    >
+                      {{ command.badge }}
+                    </span>
+                    <span
+                      v-if="command.active"
+                      class="rounded border border-accent/30 bg-accent/10 px-2 py-0.5 text-xs font-mono text-accent"
+                    >
+                      {{ command.activeLabel || $t('command_palette.current') }}
+                    </span>
+                    <span
+                      v-if="command.external"
+                      class="i-lucide:external-link inline-block h-3.5 w-3.5 shrink-0 text-fg-subtle"
+                      aria-hidden="true"
+                    />
+                    <span v-if="command.external" class="sr-only">
+                      {{ $t('command_palette.links.external') }}
+                    </span>
+                  </span>
+                </button>
+              </li>
+            </ul>
+          </section>
+        </div>
+      </div>
+    </div>
+  </Modal>
+</template>