feat: command bar

app/app.vue

@@ -19,6 +19,8 @@ const localeMap = locales.value.reduce(
   {} as Record<string, Directions>,
 )
 
+const commandBarRef = useTemplateRef('commandBarRef')
+
 useHead({
   htmlAttrs: {
     lang: () => locale.value,
@@ -37,6 +39,11 @@ if (import.meta.server) {
 function handleGlobalKeydown(e: KeyboardEvent) {
   const target = e.target as HTMLElement
 
+  if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+    e.preventDefault()
+    commandBarRef.value?.toggle()
+  }
+
   const isEditableTarget =
     target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable
 
@@ -69,6 +76,7 @@ if (import.meta.client) {
 <template>
   <div class="min-h-screen flex flex-col bg-bg text-fg">
     <a href="#main-content" class="skip-link font-mono">{{ $t('common.skip_link') }}</a>
+    <CommandBar ref="commandBarRef" />
 
     <AppHeader :show-logo="!isHomepage" />
 

app/components/CommandBar.vue

@@ -0,0 +1,177 @@
+<template>
+  <Transition name="fade">
+    <div
+      class="fixed inset-0 z-[1000] flex items-center justify-center bg-black/50 backdrop-blur-sm"
+      v-show="show"
+    >
+      <div
+        class="cmdbar-container flex items-center justify-center border border-border shadow-lg rounded-xl bg-bg p2 flex-col gap-2"
+      >
+        <label for="command-input" class="sr-only">command-input</label>
+
+        <search class="relative w-xl h-12 flex items-center">
+          <span class="absolute inset-is-4 text-fg-subtle font-mono pointer-events-none"> > </span>
+          <input
+            type="text"
+            label="Enter command..."
+            v-model="inputVal"
+            id="command-input"
+            ref="inputRef"
+            class="w-full h-full px-4 pl-8 text-fg outline-none bg-bg-subtle border border-border rounded-md"
+            placeholder="Enter command..."
+            @keydown="handleKeydown"
+          />
+        </search>
+
+        <div class="w-xl h-lg overflow-auto">
+          <div
+            v-for="item in filteredCmdList"
+            :key="item.id"
+            class="flex-col items-center justify-between px-4 py-2 not-first:mt-2 hover:bg-bg-elevated select-none cursor-pointer rounded-md transition"
+            :class="{
+              'bg-bg-subtle': item.id === selected,
+              'trigger-anim': item.id === triggeringId,
+            }"
+            @click="triggerCommand(item.id)"
+          >
+            <div class="text-fg">{{ item.name }}</div>
+            <div class="text-fg-subtle text-sm">{{ item.description }}</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Transition>
+</template>
+
+<script setup lang="ts">
+const { commands } = useCommandRegistry()
+
+const selected = shallowRef(commands.value[0]?.id || '')
+const inputVal = shallowRef('')
+const show = shallowRef(false)
+const triggeringId = shallowRef('')
+const inputRef = useTemplateRef('inputRef')
+
+const { focused: inputFocused } = useFocus(inputRef)
+
+const filteredCmdList = computed(() => {
+  if (!inputVal.value) {
+    return commands.value
+  }
+  const filter = inputVal.value.trim().toLowerCase()
+  return commands.value.filter(
+    item =>
+      item.name.toLowerCase().includes(filter) ||
+      item.description?.toLowerCase().includes(filter) ||
+      item.id.includes(filter),
+  )
+})
+
+watch(
+  () => filteredCmdList.value,
+  newVal => {
+    if (newVal.length) {
+      selected.value = newVal[0]?.id || ''
+    }
+  },
+)
+
+function focusInput() {
+  inputFocused.value = true
+}
+
+function open() {
+  inputVal.value = ''
+  selected.value = commands.value[0]?.id || ''
+  show.value = true
+  nextTick(focusInput)
+}
+
+function close() {
+  inputVal.value = ''
+  selected.value = commands.value[0]?.id || ''
+  show.value = false
+}
+
+function toggle() {
+  if (show.value) {
+    close()
+  } else {
+    open()
+  }
+}
+
+function triggerCommand(id: string) {
+  const selectedItem = filteredCmdList.value.find(item => item.id === id)
+  selectedItem?.handler?.({} as CommandContext)
+  triggeringId.value = id
+  setTimeout(() => {
+    close()
+    triggeringId.value = ''
+  }, 100)
+}
+
+const handleKeydown = useThrottleFn((e: KeyboardEvent) => {
+  if (!filteredCmdList.value.length) return
+
+  const currentIndex = filteredCmdList.value.findIndex(item => item.id === selected.value)
+
+  if (e.key === 'ArrowDown') {
+    e.preventDefault()
+    const nextIndex = (currentIndex + 1) % filteredCmdList.value.length
+    selected.value = filteredCmdList.value[nextIndex]?.id || ''
+  } else if (e.key === 'ArrowUp') {
+    e.preventDefault()
+    const prevIndex =
+      (currentIndex - 1 + filteredCmdList.value.length) % filteredCmdList.value.length
+    selected.value = filteredCmdList.value[prevIndex]?.id || ''
+  } else if (e.key === 'Enter') {
+    e.preventDefault()
+    triggerCommand(selected.value)
+  } else if (e.key === 'Escape') {
+    e.preventDefault()
+    close()
+  }
+}, 50)
+
+defineExpose({
+  open,
+  close,
+  toggle,
+})
+</script>
+
+<style scoped>
+.fade-enter-active {
+  transition: all 0.05s ease-out;
+}
+
+.fade-leave-active {
+  transition: all 0.1s ease-in;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+  transform: translateY(-10px);
+}
+
+@keyframes trigger-pulse {
+  0% {
+    transform: scale(1);
+  }
+
+  50% {
+    transform: scale(0.96);
+    background-color: var(--bg-elevated);
+  }
+
+  100% {
+    transform: scale(1);
+  }
+}
+
+.trigger-anim {
+  animation: trigger-pulse 0.1s ease-in-out;
+}
+</style>

app/composables/useCommandRegistry.ts

@@ -0,0 +1,81 @@
+import { computed } from 'vue'
+
+export interface Command {
+  id: string
+  name: string
+  description: string | undefined
+  handler?: (ctx: CommandContext) => Promise<void>
+}
+
+export interface CommandContext {
+  input: (options: CommandInputOptions) => Promise<string | undefined>
+  select: <T>(options: CommandSelectOptions<T>) => Promise<T | undefined>
+}
+
+export interface CommandInputOptions {
+  prompt: string
+}
+
+export interface CommandSelectOptions<T> {
+  prompt: string
+  items: T[]
+}
+
+/**
+ * Composable for global command registry.
+ * @public
+ */
+export const useCommandRegistry = () => {
+  const commands = useState<Map<string, Command>>('commands', () => new Map())
+
+  const register = (command: Command) => {
+    const serverCommand = {
+      ...command,
+      handler: undefined,
+    }
+    if (import.meta.server) {
+      commands.value.set(command.id, serverCommand)
+    } else {
+      commands.value.set(command.id, command)
+    }
+    return () => {
+      commands.value.delete(command.id)
+    }
+  }
+
+  return {
+    register,
+    commands: computed(() => Array.from(commands.value.values())),
+  }
+}
+
+/**
+ * Registers a global command.
+ * @public
+ */
+export const registerGlobalCommand = (command: Command) => {
+  const { register } = useCommandRegistry()
+  return register(command)
+}
+
+/**
+ * Registers a command bound to the current component's lifecycle.
+ *
+ * The command is automatically unregistered when the component unmounts.
+ * Use this to register commands that rely on local component state (context)
+ * via closure capture.
+ *
+ * @public
+ */
+export const registerScopedCommand = (command: Command) => {
+  const { register } = useCommandRegistry()
+  let unregister: () => void
+
+  onMounted(() => {
+    unregister = register(command)
+  })
+
+  onUnmounted(() => {
+    unregister()
+  })
+}

app/pages/[...package].vue

@@ -11,6 +11,15 @@ definePageMeta({
   alias: ['/package/:package(.*)*'],
 })
 
+registerScopedCommand({
+  id: 'package hello',
+  name: 'Hello',
+  description: 'Say hello to the package',
+  handler: async () => {
+    console.log(`Hello ${packageName.value}!`)
+  },
+})
+
 const router = useRouter()
 
 const { packageName, requestedVersion, orgName } = usePackageRoute()
@@ -1071,18 +1080,22 @@ function handleClick(event: MouseEvent) {
   grid-area: header;
   overflow-x: hidden;
 }
+
 .area-install {
   grid-area: install;
   overflow-x: hidden;
 }
+
 .area-vulns {
   grid-area: vulns;
   overflow-x: hidden;
 }
+
 .area-readme {
   grid-area: readme;
   overflow-x: hidden;
 }
+
 .area-sidebar {
   grid-area: sidebar;
 }

app/plugins/commands.ts

@@ -0,0 +1,11 @@
+export default defineNuxtPlugin(() => {
+  const { register } = useCommandRegistry()
+  register({
+    id: 'npmx:hello',
+    name: 'Hello',
+    description: 'Say hello to npmx',
+    handler: async () => {
+      console.log('Hello npmx!')
+    },
+  })
+})