feat: keyboard navigation on search results

Closes #61

Author: chaim-chv

app/app.vue

@@ -12,13 +12,12 @@ useHead({
 
 // Global keyboard shortcut: "/" focuses search or navigates to search page
 function handleGlobalKeydown(e: KeyboardEvent) {
-  // Ignore if user is typing in an input, textarea, or contenteditable
   const target = e.target as HTMLElement
-  if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable) {
-    return
-  }
 
-  if (e.key === '/') {
+  const isEditableTarget =
+    target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable
+
+  if (e.key === '/' && !target.isContentEditable) {
     e.preventDefault()
 
     // Try to find and focus search input on current page
@@ -28,10 +27,15 @@ function handleGlobalKeydown(e: KeyboardEvent) {
 
     if (searchInput) {
       searchInput.focus()
-    } else {
-      // Navigate to search page
-      router.push('/search')
+      return
     }
+
+    router.push('/search')
+    return
+  }
+
+  if (isEditableTarget) {
+    return
   }
 }
 

app/components/PackageCard.vue

@@ -9,15 +9,24 @@ defineProps<{
   /** Whether to show the publisher username */
   showPublisher?: boolean
   prefetch?: boolean
+  selected?: boolean
+  index?: number
+}>()
+
+const emit = defineEmits<{
+  focus: [index: number]
 }>()
 </script>
 
 <template>
-  <article class="group card-interactive">
+  <article class="group card-interactive" :class="{ 'bg-bg-muted border-border-hover': selected }">
     <NuxtLink
       :to="{ name: 'package', params: { package: result.package.name.split('/') } }"
       :prefetch-on="prefetch ? 'visibility' : 'interaction'"
       class="block focus:outline-none decoration-none"
+      :data-result-index="index"
+      @focus="emit('focus', index)"
+      @mouseenter="emit('focus', index)"
     >
       <header class="flex items-start justify-between gap-4 mb-2">
         <component

app/components/PackageList.vue

@@ -18,13 +18,17 @@ const props = defineProps<{
   pageSize?: number
   /** Initial page to scroll to (1-indexed) */
   initialPage?: number
+  /** Selected result index (for keyboard navigation) */
+  selectedIndex?: number
 }>()
 
 const emit = defineEmits<{
   /** Emitted when scrolled near the bottom and more items should be loaded */
   loadMore: []
   /** Emitted when the visible page changes */
   pageChange: [page: number]
+  /** Emitted when a result is hovered/focused */
+  select: [index: number]
 }>()
 
 // Reference to WindowVirtualizer for infinite scroll detection
@@ -97,8 +101,11 @@ watch(
             :result="item as NpmSearchResult"
             :heading-level="headingLevel"
             :show-publisher="showPublisher"
+            :selected="index === (selectedIndex ?? -1)"
+            :index="index"
             class="animate-fade-in animate-fill-both"
             :style="{ animationDelay: `${Math.min(index * 0.02, 0.3)}s` }"
+            @focus="emit('select', $event)"
           />
         </div>
       </template>

app/pages/search.vue

@@ -46,6 +46,45 @@ watch(
 const isSearchFocused = ref(false)
 const searchInputRef = ref<HTMLInputElement>()
 
+const selectedIndex = ref(0)
+
+const resultCount = computed(() => visibleResults.value?.objects.length ?? 0)
+
+function clampIndex(next: number) {
+  if (resultCount.value <= 0) return 0
+  return Math.max(0, Math.min(resultCount.value - 1, next))
+}
+
+function focusSelectedResult() {
+  const el = document.querySelector<HTMLElement>(`[data-result-index="${selectedIndex.value}"]`)
+  el?.focus()
+}
+
+function handleResultsKeydown(e: KeyboardEvent) {
+  if (resultCount.value <= 0) return
+
+  if (e.key === 'ArrowDown') {
+    e.preventDefault()
+    selectedIndex.value = clampIndex(selectedIndex.value + 1)
+    focusSelectedResult()
+    return
+  }
+
+  if (e.key === 'ArrowUp') {
+    e.preventDefault()
+    selectedIndex.value = clampIndex(selectedIndex.value - 1)
+    focusSelectedResult()
+    return
+  }
+
+  if (e.key === 'Enter') {
+    const el = document.querySelector<HTMLElement>(`[data-result-index="${selectedIndex.value}"]`)
+    if (!el) return
+    e.preventDefault()
+    el.click()
+  }
+}
+
 // Track if page just loaded (for hiding "Searching..." during view transition)
 const hasInteracted = ref(false)
 onMounted(() => {
@@ -147,12 +186,25 @@ function handlePageChange(page: number) {
   updateUrlPage(page)
 }
 
+function handleSelect(index: number) {
+  if (index < 0) return
+  selectedIndex.value = clampIndex(index)
+}
+
 // Reset pages when query changes
 watch(query, () => {
   loadedPages.value = 1
   hasInteracted.value = true
 })
 
+watch(
+  () => visibleResults.value?.objects,
+  objects => {
+    if (!objects?.length) return
+    selectedIndex.value = 0
+  },
+)
+
 useSeoMeta({
   title: () => (query.value ? `Search: ${query.value} - npmx` : 'Search Packages - npmx'),
 })
@@ -197,6 +249,7 @@ defineOgImageComponent('Default', {
                   class="w-full max-w-full bg-bg-subtle border border-border rounded-lg pl-8 pr-4 py-3 font-mono text-base text-fg placeholder:text-fg-subtle transition-all duration-300 focus:(border-border-hover outline-none) appearance-none"
                   @focus="isSearchFocused = true"
                   @blur="isSearchFocused = false"
+                  @keydown="handleResultsKeydown"
                 />
                 <!-- Hidden submit button for accessibility (form must have submit button per WCAG) -->
                 <button type="submit" class="sr-only">Search</button>
@@ -209,7 +262,7 @@ defineOgImageComponent('Default', {
 
     <!-- Results area with container padding -->
     <div class="container py-6">
-      <section v-if="query" aria-label="Search results">
+      <section v-if="query" aria-label="Search results" @keydown="handleResultsKeydown">
         <!-- Initial loading (only after user interaction, not during view transition) -->
         <LoadingSpinner v-if="showSearching" text="Searching..." />
 
@@ -235,6 +288,7 @@ defineOgImageComponent('Default', {
           <PackageList
             v-if="visibleResults.objects.length > 0"
             :results="visibleResults.objects"
+            :selected-index="selectedIndex"
             heading-level="h2"
             show-publisher
             :has-more="hasMore"
@@ -243,6 +297,7 @@ defineOgImageComponent('Default', {
             :initial-page="initialPage"
             @load-more="loadMore"
             @page-change="handlePageChange"
+            @select="handleSelect"
           />
         </div>
       </section>

tests/url-compatibility.spec.ts

@@ -54,6 +54,42 @@ test.describe('npmjs.com URL Compatibility', () => {
       await expect(page.locator('text=/found \\d+/i')).toBeVisible()
     })
 
+    test('/search?q=vue → keyboard navigation (arrow keys + enter)', async ({ page, goto }) => {
+      await goto('/search?q=vue', { waitUntil: 'domcontentloaded' })
+
+      await expect(page.locator('text=/found \\d+/i')).toBeVisible()
+
+      const searchInput = page.locator('input[type="search"]')
+      await expect(searchInput).toBeFocused()
+
+      const firstResult = page.locator('[data-result-index="0"]').first()
+      await expect(firstResult).toBeVisible()
+
+      await page.keyboard.press('Enter')
+      await expect(page).toHaveURL(/\/package\//)
+
+      await page.goBack()
+      await expect(searchInput).toBeFocused()
+      await expect(page.locator('text=/found \\d+/i')).toBeVisible()
+
+      await page.keyboard.press('ArrowDown')
+      const secondResult = page.locator('[data-result-index="1"]').first()
+      await expect(secondResult).toBeFocused()
+
+      await page.keyboard.press('Enter')
+      await expect(page).toHaveURL(/\/package\//)
+    })
+
+    test('/search?q=vue → "/" focuses the search input from results', async ({ page, goto }) => {
+      await goto('/search?q=vue', { waitUntil: 'domcontentloaded' })
+
+      await expect(page.locator('text=/found \\d+/i')).toBeVisible()
+
+      await page.locator('[data-result-index="0"]').first().focus()
+      await page.keyboard.press('/')
+      await expect(page.locator('input[type="search"]')).toBeFocused()
+    })
+
     test('/search?q=keywords:framework → keyword search', async ({ page, goto }) => {
       await goto('/search?q=keywords:framework', { waitUntil: 'domcontentloaded' })