From 9d3bc0d43179b8e800046761eece221d0b64a508 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 21:00:22 +0200
Subject: [PATCH 01/12] fix: better a11y for PackageSelector (use combobox
 pattern)

---
 app/components/Compare/PackageSelector.vue | 37 ++++++++++++++++++----
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/app/components/Compare/PackageSelector.vue b/app/components/Compare/PackageSelector.vue
index a37978d7ff..2a5a001068 100644
--- a/app/components/Compare/PackageSelector.vue
+++ b/app/components/Compare/PackageSelector.vue
@@ -10,6 +10,10 @@ const props = defineProps<{
 
 const maxPackages = computed(() => props.max ?? MAX_PACKAGE_SELECTION)
 
+// Generate unique IDs for accessibility (prevents collisions when multiple instances mount)
+const inputId = useId()
+const listboxId = `${inputId}-listbox`
+
 // Input state
 const inputValue = shallowRef('')
 const isInputFocused = shallowRef(false)
@@ -175,6 +179,14 @@ function handleKeydown(e: KeyboardEvent) {
   }
 }
 
+const activeDescendantId = computed(() =>
+  highlightedIndex.value >= 0 ? `${listboxId}-option-${highlightedIndex.value}` : undefined,
+)
+
+const showDropdown = computed(
+  () => isInputFocused.value && (navigableItems.value.length > 0 || isSearching.value),
+)
+
 // Reset highlight when user types
 watch(inputValue, () => {
   highlightedIndex.value = -1
@@ -200,8 +212,8 @@ onClickOutside(containerRef, () => {
 <template>
   <div class="space-y-3">
     <!-- Selected packages -->
-    <div v-if="packages.length > 0" class="flex flex-wrap gap-2">
-      <TagStatic v-for="pkg in packages" :key="pkg">
+    <ul v-if="packages.length > 0" class="flex flex-wrap gap-2">
+      <TagStatic as="li" v-for="pkg in packages" :key="pkg">
         <!-- No dependency display -->
         <template v-if="pkg === NO_DEPENDENCY_ID">
           <span class="text-sm text-accent italic flex items-center gap-1.5">
@@ -223,12 +235,12 @@ onClickOutside(containerRef, () => {
           classicon="i-lucide:x"
         />
       </TagStatic>
-    </div>
+    </ul>
 
     <!-- Add package input -->
     <div v-if="packages.length < maxPackages" ref="containerRef" class="relative">
       <div class="relative group flex items-center">
-        <label for="package-search" class="sr-only">
+        <label :for="inputId" class="sr-only">
           {{ $t('compare.selector.search_label') }}
         </label>
         <span
@@ -237,7 +249,7 @@ onClickOutside(containerRef, () => {
           /
         </span>
         <InputBase
-          id="package-search"
+          :id="inputId"
           v-model="inputValue"
           type="text"
           :placeholder="
@@ -247,7 +259,12 @@ onClickOutside(containerRef, () => {
           "
           no-correct
           class="w-full min-w-25 ps-7"
+          role="combobox"
           aria-autocomplete="list"
+          aria-haspopup="listbox"
+          :aria-controls="listboxId"
+          :aria-expanded="showDropdown"
+          :aria-activedescendant="activeDescendantId"
           ref="inputRef"
           @focus="isInputFocused = true"
           @keydown="handleKeydown"
@@ -263,14 +280,19 @@ onClickOutside(containerRef, () => {
         leave-to-class="opacity-0"
       >
         <div
-          v-if="isInputFocused && (navigableItems.length > 0 || isSearching)"
+          v-if="showDropdown"
+          :id="listboxId"
           ref="listRef"
+          role="listbox"
           class="absolute top-full inset-x-0 mt-1 px-0.5 bg-bg-elevated border border-border rounded-lg shadow-lg z-50 max-h-64 overflow-y-auto"
         >
           <!-- No dependency option (easter egg with James) -->
           <ButtonBase
             v-if="showNoDependencyOption"
             data-navigable
+            role="option"
+            :id="`${listboxId}-option-0`"
+            :aria-selected="highlightedIndex === 0"
             class="block w-full text-start !border-transparent"
             :class="highlightedIndex === 0 ? '!bg-accent/15' : ''"
             :aria-label="$t('compare.no_dependency.add_column')"
@@ -296,6 +318,9 @@ onClickOutside(containerRef, () => {
             v-for="(result, index) in filteredResults"
             :key="result.name"
             data-navigable
+            role="option"
+            :id="`${listboxId}-option-${index + resultIndexOffset}`"
+            :aria-selected="highlightedIndex === index + resultIndexOffset"
             class="block w-full text-start my-0.5 !border-transparent"
             :class="highlightedIndex === index + resultIndexOffset ? '!bg-accent/15' : ''"
             @mouseenter="highlightedIndex = index + resultIndexOffset"

From 457ca337d7723518793d567f4291f1751f3d117d Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 21:05:10 +0200
Subject: [PATCH 02/12] fix: a11y issue in usercombobox

---
 app/components/UserCombobox.vue | 49 +++++++++++++++++----------------
 1 file changed, 25 insertions(+), 24 deletions(-)

diff --git a/app/components/UserCombobox.vue b/app/components/UserCombobox.vue
index 5464b65814..0a1e2b4cb0 100644
--- a/app/components/UserCombobox.vue
+++ b/app/components/UserCombobox.vue
@@ -45,6 +45,8 @@ const showNewUserHint = computed(() => {
   return value.length > 0 && !isExactMatch.value && filteredSuggestions.value.length === 0
 })
 
+const showDropdown = computed(() => isOpen.value && filteredSuggestions.value.length > 0)
+
 function handleInput() {
   isOpen.value = true
   highlightedIndex.value = -1
@@ -97,15 +99,14 @@ function handleKeydown(event: KeyboardEvent) {
   switch (event.key) {
     case 'ArrowDown':
       event.preventDefault()
-      if (highlightedIndex.value < filteredSuggestions.value.length - 1) {
-        highlightedIndex.value++
-      }
+      highlightedIndex.value = (highlightedIndex.value + 1) % filteredSuggestions.value.length
       break
     case 'ArrowUp':
       event.preventDefault()
-      if (highlightedIndex.value > 0) {
-        highlightedIndex.value--
-      }
+      highlightedIndex.value =
+        highlightedIndex.value <= 0
+          ? filteredSuggestions.value.length - 1
+          : highlightedIndex.value - 1
       break
     case 'Enter': {
       event.preventDefault()
@@ -148,7 +149,7 @@ const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
       v-bind="noCorrect"
       role="combobox"
       aria-autocomplete="list"
-      :aria-expanded="isOpen && (filteredSuggestions.length > 0 || showNewUserHint)"
+      :aria-expanded="showDropdown"
       aria-haspopup="listbox"
       :aria-controls="listboxId"
       :aria-activedescendant="
@@ -171,7 +172,7 @@ const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
       :leave-to-class="prefersReducedMotion ? '' : 'opacity-0'"
     >
       <ul
-        v-if="isOpen && (filteredSuggestions.length > 0 || showNewUserHint)"
+        v-if="showDropdown"
         :id="listboxId"
         ref="listRef"
         role="listbox"
@@ -196,23 +197,23 @@ const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
         >
           @{{ username }}
         </li>
-
-        <!-- Hint for new user -->
-        <li
-          v-if="showNewUserHint"
-          class="px-2 py-1 font-mono text-xs text-fg-subtle border-t border-border mt-1 pt-2"
-          role="status"
-          aria-live="polite"
-        >
-          <span class="i-lucide:info w-3 h-3 me-1 align-middle" aria-hidden="true" />
-          {{
-            $t('user.combobox.press_enter_to_add', {
-              username: inputValue.trim().replace(/^@/, ''),
-            })
-          }}
-          <span class="text-amber-400">{{ $t('user.combobox.add_to_org_hint') }}</span>
-        </li>
       </ul>
     </Transition>
+
+    <!-- Hint for new user -->
+    <div role="status" aria-live="polite" aria-atomic="true">
+      <div
+        v-if="isOpen && showNewUserHint"
+        class="mt-1 px-2 py-1 font-mono text-xs text-fg-subtle border border-border rounded bg-bg-elevated"
+      >
+        <span class="i-lucide:info w-3 h-3 me-1 align-middle" aria-hidden="true" />
+        {{
+          $t('user.combobox.press_enter_to_add', {
+            username: inputValue.trim().replace(/^@/, ''),
+          })
+        }}
+        <span class="text-amber-400">{{ $t('user.combobox.add_to_org_hint') }}</span>
+      </div>
+    </div>
   </div>
 </template>

From 7aaa841ceeba5ced8aae9c36fe1aa4e3cf2e3b24 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 21:40:30 +0200
Subject: [PATCH 03/12] fix: align readmetocdropdown with standards

---
 app/components/ReadmeTocDropdown.vue | 193 +++++++++++++--------------
 1 file changed, 93 insertions(+), 100 deletions(-)

diff --git a/app/components/ReadmeTocDropdown.vue b/app/components/ReadmeTocDropdown.vue
index 3e86018230..8aabd73c2e 100644
--- a/app/components/ReadmeTocDropdown.vue
+++ b/app/components/ReadmeTocDropdown.vue
@@ -44,10 +44,9 @@ const idToIndex = computed(() => {
   return map
 })
 
-const listRef = useTemplateRef('listRef')
+const menuRef = useTemplateRef('menuRef')
 const triggerRef = useTemplateRef('triggerRef')
 const isOpen = shallowRef(false)
-const highlightedIndex = shallowRef(-1)
 
 const dropdownPosition = shallowRef<{ top: number; right: number } | null>(null)
 
@@ -59,10 +58,10 @@ function getDropdownStyle(): Record<string, string> {
   }
 }
 
-// Close on scroll (but not when scrolling inside the dropdown)
+// Close on scroll (but not when scrolling inside the menu)
 function handleScroll(event: Event) {
   if (!isOpen.value) return
-  if (listRef.value && event.target instanceof Node && listRef.value.contains(event.target)) {
+  if (menuRef.value && event.target instanceof Node && menuRef.value.contains(event.target)) {
     return
   }
   close()
@@ -71,95 +70,105 @@ useEventListener('scroll', handleScroll, { passive: true })
 
 // Generate unique ID for accessibility
 const inputId = useId()
-const listboxId = `${inputId}-toc-listbox`
+const menuId = `${inputId}-toc-menu`
 
-function toggle() {
-  if (isOpen.value) {
-    close()
-  } else {
-    const rect = triggerRef.value?.getBoundingClientRect()
-    if (rect) {
-      dropdownPosition.value = {
-        top: rect.bottom + 4,
-        right: rect.right,
-      }
+function getMenuItems(): HTMLElement[] {
+  if (!menuRef.value) return []
+  return Array.from(menuRef.value.querySelectorAll<HTMLElement>('[role="menuitem"]'))
+}
+
+function open() {
+  const rect = triggerRef.value?.getBoundingClientRect()
+  if (rect) {
+    dropdownPosition.value = {
+      top: rect.bottom + 4,
+      right: rect.right,
     }
-    isOpen.value = true
-    // Highlight active item if any
-    const activeIndex = idToIndex.value.get(props.activeId ?? '')
-    highlightedIndex.value = activeIndex ?? 0
   }
+  isOpen.value = true
 }
 
 function close() {
   isOpen.value = false
-  highlightedIndex.value = -1
-}
-
-function select() {
-  close()
-  triggerRef.value?.focus()
 }
 
-function getIndex(id: string): number {
-  return idToIndex.value.get(id) ?? -1
+function toggle() {
+  if (isOpen.value) {
+    close()
+  } else {
+    open()
+  }
 }
 
 // Check for reduced motion preference
 const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
 
-onClickOutside(listRef, close, { ignore: [triggerRef] })
+onClickOutside(menuRef, close, { ignore: [triggerRef] })
 
-function handleKeydown(event: KeyboardEvent) {
-  if (!isOpen.value) return
+function handleTriggerKeydown(event: KeyboardEvent) {
+  switch (event.key) {
+    case 'ArrowDown':
+    case 'ArrowUp':
+      event.preventDefault()
+      if (!isOpen.value) open()
+      break
+    case 'Escape':
+      if (isOpen.value) close()
+      break
+  }
+}
 
-  const itemCount = props.toc.length
+function handleMenuKeydown(event: KeyboardEvent) {
+  const items = getMenuItems()
+  const currentIndex = items.findIndex(el => el === document.activeElement)
 
   switch (event.key) {
     case 'ArrowDown':
       event.preventDefault()
-      highlightedIndex.value = (highlightedIndex.value + 1) % itemCount
+      items[(currentIndex + 1) % items.length]?.focus()
       break
     case 'ArrowUp':
       event.preventDefault()
-      highlightedIndex.value =
-        highlightedIndex.value <= 0 ? itemCount - 1 : highlightedIndex.value - 1
+      items[currentIndex <= 0 ? items.length - 1 : currentIndex - 1]?.focus()
       break
-    case 'Enter': {
+    case 'Home':
       event.preventDefault()
-      const item = props.toc[highlightedIndex.value]
-      if (item) {
-        select()
-      }
+      items[0]?.focus()
+      break
+    case 'End':
+      event.preventDefault()
+      items[items.length - 1]?.focus()
       break
-    }
     case 'Escape':
       close()
       triggerRef.value?.focus()
       break
+    case 'Tab':
+      // Close menu and return focus to trigger; Tab then advances naturally from trigger
+      event.preventDefault()
+      close()
+      triggerRef.value?.focus()
+      break
   }
 }
 
-const itemScrollIntoView = (index: number) => {
-  const item = props.toc[index]
-  if (!item) return
-  const el = document.getElementById(`${listboxId}-${item.id}`)
-  if (el) {
-    el.scrollIntoView({ block: 'center' })
+function handleMenuFocusout(event: FocusEvent) {
+  if (!menuRef.value?.contains(event.relatedTarget as Node | null)) {
+    close()
   }
 }
 
-watch(
-  isOpen,
-  open => {
-    if (open && highlightedIndex.value >= 0) {
-      itemScrollIntoView(highlightedIndex.value)
-    }
-  },
-  {
-    flush: 'post',
-  },
-)
+watch(isOpen, isNowOpen => {
+  if (isNowOpen) {
+    nextTick(() => {
+      const items = getMenuItems()
+      const activeIndex = props.activeId ? (idToIndex.value.get(props.activeId) ?? 0) : 0
+      const target = items[activeIndex] ?? items[0]
+      target?.focus()
+      target?.scrollIntoView({ block: 'nearest' })
+    })
+  }
+})
 </script>
 
 <template>
@@ -167,11 +176,11 @@ watch(
     ref="triggerRef"
     type="button"
     :aria-expanded="isOpen"
-    aria-haspopup="listbox"
+    aria-haspopup="menu"
     :aria-label="$t('package.readme.toc_title')"
-    :aria-controls="isOpen ? listboxId : undefined"
+    :aria-controls="isOpen ? menuId : undefined"
     @click="toggle"
-    @keydown="handleKeydown"
+    @keydown="handleTriggerKeydown"
     classicon="i-lucide:list"
     class="px-2.5"
     block
@@ -197,71 +206,55 @@ watch(
     >
       <div
         v-if="isOpen"
-        :id="listboxId"
-        ref="listRef"
-        role="listbox"
-        :aria-activedescendant="
-          highlightedIndex >= 0 && toc[highlightedIndex]?.id
-            ? `${listboxId}-${toc[highlightedIndex]?.id}`
-            : undefined
-        "
+        :id="menuId"
+        ref="menuRef"
+        role="menu"
         :aria-label="$t('package.readme.toc_title')"
         :style="getDropdownStyle()"
+        tabindex="-1"
+        @keydown="handleMenuKeydown"
+        @focusout="handleMenuFocusout"
         class="fixed bg-bg-subtle border border-border rounded-md shadow-lg z-50 max-h-80 overflow-y-auto w-56 overscroll-contain"
       >
         <template v-for="node in tocTree" :key="node.id">
           <NuxtLink
-            :id="`${listboxId}-${node.id}`"
+            :id="`${menuId}-${node.id}`"
             :to="`#${node.id}`"
-            role="option"
-            :aria-selected="activeId === node.id"
-            class="flex items-center gap-2 px-3 py-1.5 text-sm cursor-pointer transition-colors duration-150"
-            :class="[
-              activeId === node.id ? 'text-fg font-medium' : 'text-fg-muted',
-              highlightedIndex === getIndex(node.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
-            ]"
+            role="menuitem"
+            tabindex="-1"
+            class="flex items-center gap-2 px-3 py-1.5 text-sm cursor-pointer transition-colors duration-150 hover:bg-bg-elevated focus:bg-bg-elevated"
+            :class="activeId === node.id ? 'text-fg font-medium' : 'text-fg-muted'"
             dir="auto"
-            @click="select()"
-            @mouseenter="highlightedIndex = getIndex(node.id)"
+            @click="close()"
           >
             <span class="truncate">{{ node.text }}</span>
           </NuxtLink>
 
           <template v-for="child in node.children" :key="child.id">
             <NuxtLink
-              :id="`${listboxId}-${child.id}`"
+              :id="`${menuId}-${child.id}`"
               :to="`#${child.id}`"
-              role="option"
-              :aria-selected="activeId === child.id"
-              class="flex items-center gap-2 px-3 py-1.5 ps-6 text-sm cursor-pointer transition-colors duration-150"
-              :class="[
-                activeId === child.id ? 'text-fg font-medium' : 'text-fg-subtle',
-                highlightedIndex === getIndex(child.id) ? 'bg-bg-elevated' : 'hover:bg-bg-elevated',
-              ]"
+              role="menuitem"
+              tabindex="-1"
+              class="flex items-center gap-2 px-3 py-1.5 ps-6 text-sm cursor-pointer transition-colors duration-150 hover:bg-bg-elevated focus:bg-bg-elevated"
+              :class="activeId === child.id ? 'text-fg font-medium' : 'text-fg-subtle'"
               dir="auto"
-              @click="select()"
-              @mouseenter="highlightedIndex = getIndex(child.id)"
+              @click="close()"
             >
               <span class="truncate">{{ child.text }}</span>
             </NuxtLink>
 
             <NuxtLink
               v-for="grandchild in child.children"
-              :id="`${listboxId}-${grandchild.id}`"
+              :id="`${menuId}-${grandchild.id}`"
               :to="`#${grandchild.id}`"
               :key="grandchild.id"
-              role="option"
-              :aria-selected="activeId === grandchild.id"
-              class="flex items-center gap-2 px-3 py-1.5 ps-9 text-sm cursor-pointer transition-colors duration-150"
-              :class="[
-                grandchild.id === activeId ? 'text-fg font-medium' : 'text-fg-subtle',
-                highlightedIndex === getIndex(grandchild.id)
-                  ? 'bg-bg-elevated'
-                  : 'hover:bg-bg-elevated',
-              ]"
+              role="menuitem"
+              tabindex="-1"
+              class="flex items-center gap-2 px-3 py-1.5 ps-9 text-sm cursor-pointer transition-colors duration-150 hover:bg-bg-elevated focus:bg-bg-elevated"
+              :class="grandchild.id === activeId ? 'text-fg font-medium' : 'text-fg-subtle'"
               dir="auto"
-              @click="select()"
-              @mouseenter="highlightedIndex = getIndex(grandchild.id)"
+              @click="close()"
             >
               <span class="truncate">{{ grandchild.text }}</span>
             </NuxtLink>

From d79a99d9939f53c238dba5f9060175c2fec5aa33 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:04:08 +0200
Subject: [PATCH 04/12] fix: a11y issues with VersionSelector

---
 app/components/VersionSelector.vue | 519 ++++++++++++++---------------
 i18n/locales/en.json               |   2 +
 i18n/schema.json                   |   6 +
 3 files changed, 262 insertions(+), 265 deletions(-)

diff --git a/app/components/VersionSelector.vue b/app/components/VersionSelector.vue
index cf00f60199..f9fdef1eb2 100644
--- a/app/components/VersionSelector.vue
+++ b/app/components/VersionSelector.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { onClickOutside } from '@vueuse/core'
+import { useEventListener } from '@vueuse/core'
 import { compare } from 'verkit'
 import {
   buildVersionToTagsMap,
@@ -26,14 +26,17 @@ const props = withDefaults(
   },
 )
 
+const popoverRef = useTemplateRef<HTMLElement>('popoverRef')
+const triggerRef = useTemplateRef<HTMLElement>('triggerRef')
+
+// isOpen is kept only to animate the trigger chevron
 const isOpen = shallowRef(false)
-const dropdownRef = useTemplateRef('dropdownRef')
-const listboxRef = useTemplateRef('listboxRef')
-const focusedIndex = shallowRef(-1)
 
-onClickOutside(dropdownRef, () => {
-  isOpen.value = false
-})
+const uid = useId()
+const popoverId = `${uid}-versions`
+
+// Close popover on scroll so it doesn't float away from its anchor
+useEventListener('scroll', () => popoverRef.value?.hidePopover(), true)
 
 // ============================================================================
 // Version Display Types
@@ -363,120 +366,9 @@ async function toggleGroup(groupId: string) {
 }
 
 // ============================================================================
-// Keyboard Navigation
+// Helpers (unchanged)
 // ============================================================================
 
-/** Flat list of navigable items for keyboard navigation */
-const flatItems = computed(() => {
-  const items: Array<{ type: 'group' | 'version'; groupId: string; version?: VersionDisplay }> = []
-
-  for (const group of visibleVersionGroups.value) {
-    items.push({ type: 'group', groupId: group.id, version: group.primaryVersion })
-
-    if (group.isExpanded && group.versions.length > 1) {
-      // Skip first version (it's the primary)
-      for (const v of group.versions.slice(1)) {
-        items.push({ type: 'version', groupId: group.id, version: v })
-      }
-    }
-  }
-
-  return items
-})
-
-function handleButtonKeydown(event: KeyboardEvent) {
-  if (event.key === 'Escape') {
-    isOpen.value = false
-  } else if (event.key === 'ArrowDown' && !isOpen.value) {
-    event.preventDefault()
-    isOpen.value = true
-    focusedIndex.value = 0
-  }
-}
-
-function handleListboxKeydown(event: KeyboardEvent) {
-  const items = flatItems.value
-
-  switch (event.key) {
-    case 'Escape':
-      isOpen.value = false
-      break
-    case 'ArrowDown':
-      event.preventDefault()
-      focusedIndex.value = Math.min(focusedIndex.value + 1, items.length - 1)
-      scrollToFocused()
-      break
-    case 'ArrowUp':
-      event.preventDefault()
-      focusedIndex.value = Math.max(focusedIndex.value - 1, 0)
-      scrollToFocused()
-      break
-    case 'Home':
-      event.preventDefault()
-      focusedIndex.value = 0
-      scrollToFocused()
-      break
-    case 'End':
-      event.preventDefault()
-      focusedIndex.value = items.length - 1
-      scrollToFocused()
-      break
-    case 'ArrowRight': {
-      event.preventDefault()
-      const item = items[focusedIndex.value]
-      if (item?.type === 'group') {
-        const group = versionGroups.value.find(g => g.id === item.groupId)
-        if (group && !isGroupOpen(group) && canToggleGroup(group)) {
-          toggleGroup(item.groupId)
-        }
-      }
-      break
-    }
-    case 'ArrowLeft': {
-      event.preventDefault()
-      const item = items[focusedIndex.value]
-      if (item?.type === 'group') {
-        const group = versionGroups.value.find(g => g.id === item.groupId)
-        if (group?.isExpanded) {
-          group.isExpanded = false
-        } else if (group && controlsAdditionalGroups(group) && showAllGroups.value) {
-          showAllGroups.value = false
-        }
-      } else if (item?.type === 'version') {
-        // Jump to parent group
-        const groupIndex = items.findIndex(i => i.type === 'group' && i.groupId === item.groupId)
-        if (groupIndex >= 0) {
-          focusedIndex.value = groupIndex
-          scrollToFocused()
-        }
-      }
-      break
-    }
-    case 'Enter':
-    case ' ':
-      event.preventDefault()
-      if (focusedIndex.value >= 0 && focusedIndex.value < items.length) {
-        const item = items[focusedIndex.value]
-        if (item?.version) {
-          navigateToVersion(item.version.version)
-        }
-      }
-      break
-  }
-}
-
-function scrollToFocused() {
-  nextTick(() => {
-    const focused = listboxRef.value?.querySelector('[data-focused="true"]')
-    focused?.scrollIntoView({ block: 'nearest' })
-  })
-}
-
-function navigateToVersion(version: string) {
-  isOpen.value = false
-  navigateTo(getVersionUrl(version))
-}
-
 function hasNestedVersions(group: VersionGroup): boolean {
   return group.versions.length > 1
 }
@@ -502,15 +394,98 @@ function canToggleGroup(group: VersionGroup): boolean {
   )
 }
 
-// Reset focused index when dropdown opens
-watch(isOpen, open => {
-  if (open) {
-    // Find current version in flat list
-    const currentIdx = flatItems.value.findIndex(item => item.version?.isCurrent)
-    focusedIndex.value = currentIdx >= 0 ? currentIdx : 0
+// ============================================================================
+// Popover & Focus Management
+// ============================================================================
+
+// min-w-[220px] from the template — used as the overflow threshold when the
+// element is still display:none (offsetWidth would be 0 in beforetoggle).
+const MIN_POPOVER_WIDTH = 220
+
+/**
+ * Position the popover below its trigger.
+ *
+ * `width` should be the popover's rendered width when known (resize handler),
+ * or MIN_POPOVER_WIDTH when the element is still hidden (beforetoggle).
+ * Left-aligns unless that width would overflow the right viewport edge.
+ */
+function positionPopover(width = MIN_POPOVER_WIDTH) {
+  if (!triggerRef.value || !popoverRef.value) return
+  const rect = triggerRef.value.getBoundingClientRect()
+  const el = popoverRef.value
+
+  el.style.top = `${rect.bottom + 8}px`
+
+  if (rect.left + width > window.innerWidth) {
+    el.style.left = 'auto'
+    el.style.right = `${window.innerWidth - rect.right}px`
+  } else {
+    el.style.left = `${rect.left}px`
+    el.style.right = 'auto'
   }
+}
+
+/**
+ * Runs before the popover is shown — sets position before first paint and
+ * before the CSS entry transition starts (no forced-reflow interference).
+ */
+function handlePopoverBeforeToggle(event: ToggleEvent) {
+  if (event.newState === 'open') positionPopover()
+}
+
+// Reposition while the popover is open. The element is visible here so
+// offsetWidth is accurate and reading it doesn't interfere with animation.
+useEventListener('resize', () => {
+  if (isOpen.value) positionPopover(popoverRef.value?.offsetWidth)
 })
 
+function handlePopoverToggle(event: ToggleEvent) {
+  isOpen.value = event.newState === 'open'
+
+  if (event.newState !== 'open') return
+
+  // Move focus to the current version link, or the first interactive element
+  nextTick(() => {
+    const current = popoverRef.value?.querySelector<HTMLElement>('[aria-current="page"]')
+    const first = popoverRef.value?.querySelector<HTMLElement>('a[href], button:not([disabled])')
+    ;(current ?? first)?.focus()
+  })
+}
+
+/** ArrowDown/Up navigate between visible interactive elements in the popover. */
+function handlePopoverKeydown(event: KeyboardEvent) {
+  if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return
+
+  event.preventDefault()
+
+  const focusable = Array.from(
+    popoverRef.value?.querySelectorAll<HTMLElement>(
+      'a[href], button:not([disabled]):not([tabindex="-1"])',
+    ) ?? [],
+  )
+
+  const current = document.activeElement as HTMLElement
+  const idx = focusable.indexOf(current)
+
+  let next: HTMLElement | undefined
+  if (event.key === 'ArrowDown') next = focusable[idx + 1] ?? focusable[0]
+  else if (event.key === 'ArrowUp') next = focusable[idx - 1] ?? focusable[focusable.length - 1]
+  else if (event.key === 'Home') next = focusable[0]
+  else next = focusable[focusable.length - 1]
+
+  next?.focus()
+  next?.scrollIntoView({ block: 'nearest' })
+}
+
+/** Open the popover with ArrowDown when focus is on the trigger. */
+function handleTriggerKeydown(event: KeyboardEvent) {
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    popoverRef.value?.showPopover()
+    // focus is managed by handlePopoverToggle via the toggle event
+  }
+}
+
 // Rebuild groups when props change
 watch(
   () => [props.distTags, props.versions, props.currentVersion],
@@ -526,15 +501,21 @@ watch(
 </script>
 
 <template>
-  <div ref="dropdownRef" class="relative">
+  <!--
+    Uses the native Popover API:
+    - popovertarget wires the button to the popover declaratively
+    - The browser provides aria-expanded, light-dismiss (click outside + Esc),
+      and automatic focus-return to the trigger on close
+    - We add focus-on-open and ArrowDown/Up navigation on top
+  -->
+  <nav :aria-label="$t('package.versions.nav_label')">
     <button
+      ref="triggerRef"
       type="button"
-      aria-haspopup="listbox"
-      :aria-expanded="isOpen"
+      :popovertarget="popoverId"
       class="break-all text-start font-mono text-sm hover:text-accent transition-[color] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-bg rounded"
-      @click="isOpen = !isOpen"
-      @keydown="handleButtonKeydown"
       data-testid="version-selector-button"
+      @keydown="handleTriggerKeydown"
     >
       <span dir="ltr" class="me-1.5">{{ currentVersion }}</span>
       <span
@@ -550,149 +531,157 @@ watch(
       />
     </button>
 
-    <Transition
-      enter-active-class="transition-[opacity,transform] duration-150 ease-out motion-reduce:transition-none"
-      enter-from-class="opacity-0 scale-95"
-      enter-to-class="opacity-100 scale-100"
-      leave-active-class="transition-[opacity,transform] duration-100 ease-in motion-reduce:transition-none"
-      leave-from-class="opacity-100 scale-100"
-      leave-to-class="opacity-0 scale-95"
+    <ul
+      :id="popoverId"
+      ref="popoverRef"
+      popover="auto"
+      :aria-label="$t('package.versions.selector_label')"
+      class="version-selector-popover min-w-[220px] max-w-[calc(100vw-40px)] bg-bg-subtle/80 backdrop-blur-sm border border-border-subtle rounded-lg shadow-lg shadow-fg-subtle/10 py-1 max-h-[400px] overflow-y-auto overscroll-contain"
+      @beforetoggle="handlePopoverBeforeToggle"
+      @toggle="handlePopoverToggle"
+      @keydown="handlePopoverKeydown"
     >
-      <div
-        v-if="isOpen"
-        ref="listboxRef"
-        role="listbox"
-        tabindex="0"
-        :aria-activedescendant="
-          focusedIndex >= 0 ? `version-${flatItems[focusedIndex]?.version?.version}` : undefined
-        "
-        class="absolute top-full mt-2 min-w-[220px] max-w-[calc(100vw-40px)] bg-bg-subtle/80 backdrop-blur-sm border border-border-subtle rounded-lg shadow-lg shadow-fg-subtle/10 z-50 py-1 max-h-[400px] overflow-y-auto overscroll-contain focus-visible:outline-none"
-        :class="positionClass"
-        @keydown="handleListboxKeydown"
-      >
-        <!-- Version groups -->
-        <div v-for="group in visibleVersionGroups" :key="group.id">
-          <!-- Group header (primary version) -->
-          <div
-            :id="`version-${group.primaryVersion.version}`"
-            role="option"
-            :aria-selected="group.primaryVersion.isCurrent"
-            :data-focused="
-              flatItems[focusedIndex]?.groupId === group.id &&
-              flatItems[focusedIndex]?.type === 'group'
+      <!-- Version groups -->
+      <li v-for="group in visibleVersionGroups" :key="group.id">
+        <div
+          class="flex items-center gap-2 px-3 py-2 text-sm font-mono transition-[color,background-color]"
+          :class="group.primaryVersion.isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-muted'"
+        >
+          <!-- Expand toggle: proper button with label, controls the sub-version list -->
+          <button
+            v-if="canToggleGroup(group)"
+            type="button"
+            class="w-4 h-4 flex items-center justify-center text-fg-subtle hover:text-fg transition-colors shrink-0"
+            :aria-expanded="isGroupOpen(group)"
+            :aria-controls="`${popoverId}-sub-${group.id}`"
+            :aria-label="
+              isGroupOpen(group)
+                ? $t('package.versions.collapse', { tag: group.label })
+                : $t('package.versions.expand', { tag: group.label })
             "
-            class="flex items-center gap-2 px-3 py-2 text-sm font-mono hover:bg-bg-muted transition-[color,background-color] focus-visible:outline-none"
-            :class="[
-              group.primaryVersion.isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-muted',
-              flatItems[focusedIndex]?.groupId === group.id &&
-              flatItems[focusedIndex]?.type === 'group'
-                ? 'bg-bg-muted'
-                : '',
-            ]"
+            @click="toggleGroup(group.id)"
+          >
+            <span
+              v-if="group.isLoading"
+              class="i-svg-spinners:ring-resize w-3 h-3"
+              aria-hidden="true"
+            />
+            <span
+              v-else
+              class="w-3 h-3 transition-transform duration-200 rtl-flip"
+              :class="isGroupOpen(group) ? 'i-lucide:chevron-down' : 'i-lucide:chevron-right'"
+              aria-hidden="true"
+            />
+          </button>
+          <span v-else class="w-4 h-4 shrink-0" />
+
+          <!-- Version link -->
+          <NuxtLink
+            :id="`${popoverId}-${group.primaryVersion.version}`"
+            :to="getVersionUrl(group.primaryVersion.version)"
+            :aria-current="group.primaryVersion.isCurrent ? 'page' : undefined"
+            class="flex-1 truncate hover:text-fg transition-colors"
+            @click="popoverRef?.hidePopover()"
           >
-            <!-- Expand button -->
-            <button
-              v-if="canToggleGroup(group)"
-              type="button"
-              class="w-4 h-4 flex items-center justify-center text-fg-subtle hover:text-fg transition-colors shrink-0"
-              :aria-expanded="isGroupOpen(group)"
-              :aria-label="isGroupOpen(group) ? $t('common.collapse') : $t('common.expand')"
-              @click.stop="toggleGroup(group.id)"
+            <span dir="ltr">{{ group.primaryVersion.version }}</span>
+          </NuxtLink>
+
+          <!-- Tags -->
+          <span v-if="group.primaryVersion.tags?.length" class="flex items-center gap-1 shrink-0">
+            <span
+              v-for="tag in group.primaryVersion.tags"
+              :key="tag"
+              class="text-xs px-1.5 py-0.5 rounded font-sans font-medium"
+              :class="tag === 'latest' ? 'badge-accent' : 'badge-subtle'"
             >
-              <span
-                v-if="group.isLoading"
-                class="i-svg-spinners:ring-resize w-3 h-3"
-                aria-hidden="true"
-              />
-              <span
-                v-else
-                class="w-3 h-3 transition-transform duration-200 rtl-flip"
-                :class="isGroupOpen(group) ? 'i-lucide:chevron-down' : 'i-lucide:chevron-right'"
-                aria-hidden="true"
-              />
-            </button>
-            <span v-else class="w-4 h-4 shrink-0" />
-
-            <!-- Version link -->
+              {{ tag }}
+            </span>
+          </span>
+        </div>
+
+        <!-- Sub-versions, controlled by the expand button above -->
+        <ol
+          v-if="group.isExpanded && group.versions.length > 1"
+          :id="`${popoverId}-sub-${group.id}`"
+          reversed
+          class="ms-6 border-is border-border"
+        >
+          <li v-for="v in group.versions.slice(1)" :key="v.version">
             <NuxtLink
-              :to="getVersionUrl(group.primaryVersion.version)"
-              class="flex-1 truncate hover:text-fg transition-colors"
-              @click="isOpen = false"
+              :id="`${popoverId}-${v.version}`"
+              :to="getVersionUrl(v.version)"
+              :aria-current="v.isCurrent ? 'page' : undefined"
+              class="flex items-center justify-between gap-2 ps-4 pe-3 py-1.5 text-xs font-mono hover:bg-bg-muted transition-[color,background-color] focus-visible:outline-none"
+              :class="v.isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-subtle'"
+              @click="popoverRef?.hidePopover()"
             >
-              <span dir="ltr">
-                {{ group.primaryVersion.version }}
+              <span class="truncate" dir="ltr">{{ v.version }}</span>
+              <span v-if="v.tags?.length" class="flex items-center gap-1 shrink-0">
+                <span
+                  v-for="tag in v.tags"
+                  :key="tag"
+                  class="text-4xs px-1 py-0.5 rounded font-sans font-medium"
+                  :class="tag === 'latest' ? 'badge-accent' : 'badge-subtle'"
+                >
+                  {{ tag }}
+                </span>
               </span>
             </NuxtLink>
+          </li>
+        </ol>
+      </li>
+
+      <!-- Link to package page for full version list -->
+      <li class="border-t border-border mt-1 pt-1 px-3 py-2">
+        <NuxtLink
+          :to="packageVersionsRoute(packageName)"
+          class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
+          @click="popoverRef?.hidePopover()"
+        >
+          {{
+            $t(
+              'package.versions.view_all',
+              { count: Object.keys(versions).length },
+              Object.keys(versions).length,
+            )
+          }}
+        </NuxtLink>
+      </li>
+    </ul>
+  </nav>
+</template>
 
-            <!-- Tags -->
-            <span v-if="group.primaryVersion.tags?.length" class="flex items-center gap-1 shrink-0">
-              <span
-                v-for="tag in group.primaryVersion.tags"
-                :key="tag"
-                class="text-xs px-1.5 py-0.5 rounded font-sans font-medium"
-                :class="tag === 'latest' ? 'badge-accent' : 'badge-subtle'"
-              >
-                {{ tag }}
-              </span>
-            </span>
-          </div>
+<style scoped>
+/*
+  Popover positioning: reset the UA default (centered in viewport) and animate.
+  The JS positionPopover() sets top/left at open-time.
+  @starting-style provides the "from" frame for the entry transition.
+*/
+.version-selector-popover {
+  position: fixed;
+  margin: 0;
+  inset: auto;
+
+  opacity: 0;
+  transform: scale(0.95);
+  transform-origin: top left;
+
+  transition:
+    opacity 0.15s ease-out,
+    transform 0.15s ease-out,
+    display 0.15s allow-discrete,
+    overlay 0.15s allow-discrete;
+}
 
-          <!-- Expanded versions -->
-          <div
-            v-if="group.isExpanded && group.versions.length > 1"
-            class="ms-6 border-is border-border"
-          >
-            <template v-for="v in group.versions.slice(1)" :key="v.version">
-              <NuxtLink
-                :id="`version-${v.version}`"
-                :to="getVersionUrl(v.version)"
-                role="option"
-                :aria-selected="v.isCurrent"
-                :data-focused="
-                  flatItems[focusedIndex]?.groupId === group.id &&
-                  flatItems[focusedIndex]?.type === 'version' &&
-                  flatItems[focusedIndex]?.version?.version === v.version
-                "
-                class="flex items-center justify-between gap-2 ps-4 pe-3 py-1.5 text-xs font-mono hover:bg-bg-muted transition-[color,background-color] focus-visible:outline-none"
-                :class="[
-                  v.isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-subtle',
-                  flatItems[focusedIndex]?.version?.version === v.version ? 'bg-bg-muted' : '',
-                ]"
-                @click="isOpen = false"
-              >
-                <span class="truncate" dir="ltr">{{ v.version }}</span>
-                <span v-if="v.tags?.length" class="flex items-center gap-1 shrink-0">
-                  <span
-                    v-for="tag in v.tags"
-                    :key="tag"
-                    class="text-4xs px-1 py-0.5 rounded font-sans font-medium"
-                    :class="tag === 'latest' ? 'badge-accent' : 'badge-subtle'"
-                  >
-                    {{ tag }}
-                  </span>
-                </span>
-              </NuxtLink>
-            </template>
-          </div>
-        </div>
+.version-selector-popover:popover-open {
+  opacity: 1;
+  transform: scale(1);
+}
 
-        <!-- Link to package page for full version list -->
-        <div class="border-t border-border mt-1 pt-1 px-3 py-2">
-          <NuxtLink
-            :to="packageVersionsRoute(packageName)"
-            class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
-            @click="isOpen = false"
-          >
-            {{
-              $t(
-                'package.versions.view_all',
-                { count: Object.keys(versions).length },
-                Object.keys(versions).length,
-              )
-            }}
-          </NuxtLink>
-        </div>
-      </div>
-    </Transition>
-  </div>
-</template>
+@starting-style {
+  .version-selector-popover:popover-open {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+</style>
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index c6881a08ae..433922b16f 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -585,6 +585,8 @@
     },
     "versions": {
       "title": "Versions",
+      "selector_label": "Select version",
+      "nav_label": "Package versions",
       "collapse": "Collapse {tag}",
       "expand": "Expand {tag}",
       "collapse_other": "Collapse other versions",
diff --git a/i18n/schema.json b/i18n/schema.json
index a955b9da4e..159837c333 100644
--- a/i18n/schema.json
+++ b/i18n/schema.json
@@ -1759,6 +1759,12 @@
             "title": {
               "type": "string"
             },
+            "selector_label": {
+              "type": "string"
+            },
+            "nav_label": {
+              "type": "string"
+            },
             "collapse": {
               "type": "string"
             },

From afee34643f71b65d25b334788b971ac57d16ff7d Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:29:46 +0200
Subject: [PATCH 05/12] feat: use j/k navigation for search results

---
 app/components/AppFooter.vue                 |  2 +-
 app/pages/search.vue                         | 40 ++++++++++---------
 docs/content/2.guide/2.keyboard-shortcuts.md |  8 ++--
 docs/content/index.md                        |  2 +-
 test/e2e/interactions.spec.ts                | 41 +++++++++++---------
 5 files changed, 51 insertions(+), 42 deletions(-)

diff --git a/app/components/AppFooter.vue b/app/components/AppFooter.vue
index 4580671cd3..746a4862e3 100644
--- a/app/components/AppFooter.vue
+++ b/app/components/AppFooter.vue
@@ -232,7 +232,7 @@ const footerSections = computed<Array<{ label: string; links: FooterLink[] }>>((
       </p>
       <ul class="mb-6 flex flex-col gap-2">
         <li class="flex gap-2 items-center">
-          <kbd class="kbd">↑</kbd>/<kbd class="kbd">↓</kbd>
+          <kbd class="kbd">j</kbd>/<kbd class="kbd">k</kbd>
           <span>{{ $t('shortcuts.navigate_results') }}</span>
         </li>
         <li class="flex gap-2 items-center">
diff --git a/app/pages/search.vue b/app/pages/search.vue
index 9010734a57..49793b54c1 100644
--- a/app/pages/search.vue
+++ b/app/pages/search.vue
@@ -438,6 +438,18 @@ function getFocusableElements(): HTMLElement[] {
   return [...suggestions, ...packages]
 }
 
+/**
+ * Returns true when focus is inside a text-entry context where j/k should
+ * not be intercepted (input, textarea, or contenteditable).
+ */
+function isTypingContext(): boolean {
+  const el = document.activeElement
+  if (!el) return false
+  const tag = el.tagName
+  if (tag === 'INPUT' || tag === 'TEXTAREA') return true
+  return (el as HTMLElement).isContentEditable
+}
+
 /**
  * Focus an element and scroll it into view
  */
@@ -477,22 +489,18 @@ watch(displayResults, newResults => {
   }
 })
 
-/**
- * Focus the header search input
- */
-function focusSearchInput() {
-  const searchInput = document.querySelector<HTMLInputElement>(
-    'input[type="search"], input[name="q"]',
-  )
-  searchInput?.focus()
-}
-
 const keyboardShortcuts = useKeyboardShortcuts()
 
 function handleResultsKeydown(e: KeyboardEvent) {
   if (!keyboardShortcuts.value) {
     return
   }
+
+  // Don't intercept j/k when the user is typing in an input, textarea, or contenteditable
+  if ((e.key === 'j' || e.key === 'k') && isTypingContext()) {
+    return
+  }
+
   // If the active element is an input, navigate to exact match or wait for results
   if (e.key === 'Enter' && document.activeElement?.tagName === 'INPUT') {
     // Get value directly from input (not from route query, which may be debounced)
@@ -521,7 +529,7 @@ function handleResultsKeydown(e: KeyboardEvent) {
 
   const currentIndex = elements.findIndex(el => el === document.activeElement)
 
-  if (e.key === 'ArrowDown') {
+  if (e.key === 'j') {
     e.preventDefault()
     const nextIndex = currentIndex < 0 ? 0 : Math.min(currentIndex + 1, elements.length - 1)
     const el = elements[nextIndex]
@@ -529,13 +537,9 @@ function handleResultsKeydown(e: KeyboardEvent) {
     return
   }
 
-  if (e.key === 'ArrowUp') {
+  if (e.key === 'k') {
+    if (currentIndex <= 0) return
     e.preventDefault()
-    // At first result or no result focused: return focus to search input
-    if (currentIndex <= 0) {
-      focusSearchInput()
-      return
-    }
     const nextIndex = currentIndex - 1
     const el = elements[nextIndex]
     if (el) focusElement(el)
@@ -555,7 +559,7 @@ function handleResultsKeydown(e: KeyboardEvent) {
   }
 }
 
-onKeyDown(['ArrowDown', 'ArrowUp', 'Enter'], handleResultsKeydown)
+onKeyDown(['j', 'k', 'Enter'], handleResultsKeydown)
 
 useSeoMeta({
   title: () =>
diff --git a/docs/content/2.guide/2.keyboard-shortcuts.md b/docs/content/2.guide/2.keyboard-shortcuts.md
index 1c35a31660..eba2444252 100644
--- a/docs/content/2.guide/2.keyboard-shortcuts.md
+++ b/docs/content/2.guide/2.keyboard-shortcuts.md
@@ -36,10 +36,10 @@ These shortcuts work anywhere on the site. Press `/` from any page to quickly se
 
 ## Search results
 
-| Key                       | Action                |
-| ------------------------- | --------------------- |
-| `Arrow Up` / `Arrow Down` | Move through results  |
-| `Enter`                   | Open selected package |
+| Key       | Action                |
+| --------- | --------------------- |
+| `j` / `k` | Move through results  |
+| `Enter`   | Open selected package |
 
 ## Package page
 
diff --git a/docs/content/index.md b/docs/content/index.md
index 012bd7ce8f..c0f0df11ee 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -42,7 +42,7 @@ links:
 :::u-page-feature{icon="i-lucide:link" to="/guide/url-structure" title="Use familiar URLs" description="Replace npmjs.com with npmx.dev in any URL and share exact package, code, diff, docs, changelog, timeline, stats, search, and compare views."}
 :::
 
-:::u-page-feature{icon="i-lucide:keyboard" to="/guide/keyboard-shortcuts" title="Navigate with keyboard" description="Open the command palette with ⌘K on macOS or Ctrl+K on Windows and Linux. Press / to search. Use arrow keys to browse results."}
+:::u-page-feature{icon="i-lucide:keyboard" to="/guide/keyboard-shortcuts" title="Navigate with keyboard" description="Open the command palette with ⌘K on macOS or Ctrl+K on Windows and Linux. Press / to search. Use j/k to browse results."}
 :::
 
 :::u-page-feature{icon="i-lucide:shield-check" to="/guide/features" title="Check security" description="Vulnerability warnings from OSV database and provenance indicators for verified builds."}
diff --git a/test/e2e/interactions.spec.ts b/test/e2e/interactions.spec.ts
index 2ac88c05fc..ef41a900aa 100644
--- a/test/e2e/interactions.spec.ts
+++ b/test/e2e/interactions.spec.ts
@@ -2,7 +2,9 @@ import { expect, test } from './test-utils'
 
 test.describe('Compare Page', () => {
   test('no-dep column renders separately from package columns', async ({ page, goto }) => {
-    await goto('/compare?packages=vue,__no_dependency__', { waitUntil: 'hydration' })
+    await goto('/compare?packages=vue,__no_dependency__', {
+      waitUntil: 'hydration',
+    })
 
     const grid = page.locator('.comparison-grid')
     await expect(grid).toBeVisible({ timeout: 15000 })
@@ -20,7 +22,9 @@ test.describe('Compare Page', () => {
     goto,
   }) => {
     // Start with vue and no-dep
-    await goto('/compare?packages=vue,__no_dependency__', { waitUntil: 'hydration' })
+    await goto('/compare?packages=vue,__no_dependency__', {
+      waitUntil: 'hydration',
+    })
 
     const grid = page.locator('.comparison-grid')
     await expect(grid).toBeVisible({ timeout: 15000 })
@@ -176,7 +180,7 @@ test.describe('Package Page', () => {
 })
 
 test.describe('Search Pages', () => {
-  test('/search?q=vue → keyboard navigation (arrow keys + enter)', async ({ page, goto }) => {
+  test('/search?q=vue → keyboard navigation (j/k + enter)', async ({ page, goto }) => {
     await goto('/search?q=vue', { waitUntil: 'hydration' })
 
     await expect(page.locator('text=/found \\d+|showing \\d+/i').first()).toBeVisible({
@@ -187,11 +191,11 @@ test.describe('Search Pages', () => {
     await expect(firstResult).toBeVisible()
 
     // Global keyboard navigation works regardless of focus
-    // ArrowDown selects the next result
-    await page.keyboard.press('ArrowDown')
+    // j moves focus to the next result
+    await page.keyboard.press('j')
 
-    // ArrowUp selects the previous result
-    await page.keyboard.press('ArrowUp')
+    // k moves focus to the previous result (does nothing at the first item)
+    await page.keyboard.press('k')
 
     // Enter navigates to the selected result
     // URL is /package/vue or /org/vue or /user/vue. Not /vue
@@ -199,7 +203,7 @@ test.describe('Search Pages', () => {
     await expect(page).toHaveURL(/\/(package|org|user)\/vue/)
   })
 
-  test('/search?q=vue → ArrowDown navigates only between results, not keyword buttons', async ({
+  test('/search?q=vue → j navigates only between results, not keyword buttons', async ({
     page,
     goto,
   }) => {
@@ -214,16 +218,16 @@ test.describe('Search Pages', () => {
     await expect(firstResult).toBeVisible()
     await expect(secondResult).toBeVisible()
 
-    // ArrowDown from input focuses the first result
-    await page.keyboard.press('ArrowDown')
+    // j from input focuses the first result
+    await page.keyboard.press('j')
     await expect(firstResult).toBeFocused()
 
-    // Second ArrowDown focuses the second result (not a keyword button within the first)
-    await page.keyboard.press('ArrowDown')
+    // Second j focuses the second result (not a keyword button within the first)
+    await page.keyboard.press('j')
     await expect(secondResult).toBeFocused()
   })
 
-  test('/search?q=vue → ArrowUp from first result returns focus to search input', async ({
+  test('/search?q=vue → k at first result does nothing (focus stays on first result)', async ({
     page,
     goto,
   }) => {
@@ -234,12 +238,13 @@ test.describe('Search Pages', () => {
     })
 
     // Navigate to first result
-    await page.keyboard.press('ArrowDown')
-    await expect(page.locator('[data-result-index="0"]').first()).toBeFocused()
+    await page.keyboard.press('j')
+    const firstResult = page.locator('[data-result-index="0"]').first()
+    await expect(firstResult).toBeFocused()
 
-    // ArrowUp returns to the search input
-    await page.keyboard.press('ArrowUp')
-    await expect(page.locator('input[type="search"]')).toBeFocused()
+    // k at the first result does nothing — focus stays on the first result
+    await page.keyboard.press('k')
+    await expect(firstResult).toBeFocused()
   })
 
   test('/search?q=vue → "/" focuses the search input from results', async ({ page, goto }) => {

From a1d64c6ad004bfce162551e255f7a2e0c1137836 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Tue, 4 Aug 2026 22:36:03 +0200
Subject: [PATCH 06/12] fix: apply combobox aria attributes to command palatte

---
 app/components/CommandPalette.client.vue | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/app/components/CommandPalette.client.vue b/app/components/CommandPalette.client.vue
index 4b6bca418d..27f1d8e593 100644
--- a/app/components/CommandPalette.client.vue
+++ b/app/components/CommandPalette.client.vue
@@ -327,6 +327,10 @@ useEventListener(document, 'keydown', handleGlobalKeydown)
             no-password-manager
             size="lg"
             class="w-full"
+            role="combobox"
+            aria-expanded="true"
+            aria-haspopup="listbox"
+            aria-autocomplete="list"
             :aria-describedby="inputDescribedBy"
             :aria-controls="RESULTS_ID"
           />

From 47e57842406ed0e67dbb81f3cca912bd95935d1d Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Wed, 5 Aug 2026 07:41:15 +0200
Subject: [PATCH 07/12] fix: revert command palette changes

---
 app/components/CommandPalette.client.vue | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/app/components/CommandPalette.client.vue b/app/components/CommandPalette.client.vue
index 27f1d8e593..4b6bca418d 100644
--- a/app/components/CommandPalette.client.vue
+++ b/app/components/CommandPalette.client.vue
@@ -327,10 +327,6 @@ useEventListener(document, 'keydown', handleGlobalKeydown)
             no-password-manager
             size="lg"
             class="w-full"
-            role="combobox"
-            aria-expanded="true"
-            aria-haspopup="listbox"
-            aria-autocomplete="list"
             :aria-describedby="inputDescribedBy"
             :aria-controls="RESULTS_ID"
           />

From f6a4e82f3a4f5a912ad852f085e32fe5443ac705 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Wed, 5 Aug 2026 08:43:08 +0200
Subject: [PATCH 08/12] test: update version selector tests

---
 test/nuxt/components/VersionSelector.spec.ts | 867 ++++++-------------
 1 file changed, 254 insertions(+), 613 deletions(-)

diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index 417d563edb..56f7a18b1e 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -13,6 +13,20 @@ vi.mock('~/utils/npm/api', () => ({
 const mockNavigateTo = vi.fn()
 vi.stubGlobal('navigateTo', mockNavigateTo)
 
+const defaultProps = {
+  packageName: 'test-package',
+  currentVersion: '1.0.0',
+  versions: { '1.0.0': {} },
+  distTags: { latest: '1.0.0' },
+  urlPattern: '/package-docs/test-package/v/{version}',
+}
+
+/** Returns true when the native popover is open (in the top layer). */
+function isPopoverOpen(component: Awaited<ReturnType<typeof mountSuspended>>): boolean {
+  const popover = component.find('[popover="auto"]')
+  return popover.exists() && popover.element.matches(':popover-open')
+}
+
 describe('VersionSelector', () => {
   beforeEach(() => {
     mockFetchAllPackageVersions.mockReset()
@@ -21,17 +35,8 @@ describe('VersionSelector', () => {
 
   describe('basic rendering', () => {
     it('renders the current version in the button', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const button = component.find('[data-testid="version-selector-button"]')
       expect(button.exists()).toBe(true)
       expect(button.text()).toContain('1.0.0')
     })
@@ -39,313 +44,204 @@ describe('VersionSelector', () => {
     it('shows "latest" badge when current version is latest', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '2.0.0': {} },
           distTags: { latest: '2.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
         },
       })
-
       expect(component.text()).toContain('latest')
     })
 
-    it('does not show "latest" badge when current version is not latest', async () => {
+    it('does not show "latest" badge in trigger when current version is not latest', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
+          ...defaultProps,
           versions: { '1.0.0': {}, '2.0.0': {} },
           distTags: { latest: '2.0.0', old: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
         },
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      // The button itself shouldn't have the latest badge
+      const button = component.find('[data-testid="version-selector-button"]')
       expect(button.text()).not.toContain('latest')
     })
 
-    it('has aria-expanded="false" initially', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      expect(button.attributes('aria-expanded')).toBe('false')
+    it('popover is not visible initially', async () => {
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      expect(isPopoverOpen(component)).toBe(false)
     })
   })
 
-  describe('dropdown behavior', () => {
-    it('opens dropdown when button is clicked', async () => {
+  describe('popover behavior', () => {
+    it('opens popover when trigger is clicked', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      expect(button.attributes('aria-expanded')).toBe('true')
-      expect(component.find('[role="listbox"]').exists()).toBe(true)
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      expect(isPopoverOpen(component)).toBe(true)
+      component.unmount()
     })
 
-    it('closes dropdown when button is clicked again', async () => {
+    it('closes popover when trigger is clicked again', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
+      const button = component.find('[data-testid="version-selector-button"]')
       await button.trigger('click')
-      expect(button.attributes('aria-expanded')).toBe('true')
-
+      expect(isPopoverOpen(component)).toBe(true)
       await button.trigger('click')
-      expect(button.attributes('aria-expanded')).toBe('false')
+      expect(isPopoverOpen(component)).toBe(false)
+      component.unmount()
     })
 
-    it('shows version groups in dropdown', async () => {
+    it('shows version groups in popover', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-      expect(listbox.text()).toContain('2.0.0')
-      expect(listbox.text()).toContain('1.0.0')
+      const popover = component.find('[popover="auto"]')
+      expect(popover.text()).toContain('2.0.0')
+      expect(popover.text()).toContain('1.0.0')
+      component.unmount()
     })
 
     it('shows "View all X versions" link', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '1.0.0',
           versions: { '1.0.0': {}, '2.0.0': {}, '3.0.0': {} },
           distTags: { latest: '3.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
       expect(component.text()).toContain('View all 3 versions')
+      component.unmount()
     })
   })
 
   describe('keyboard navigation', () => {
-    it('opens dropdown on ArrowDown when closed', async () => {
+    it('opens popover on ArrowDown when trigger is focused', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('keydown', { key: 'ArrowDown' })
-
-      expect(button.attributes('aria-expanded')).toBe('true')
+      await component
+        .find('[data-testid="version-selector-button"]')
+        .trigger('keydown', { key: 'ArrowDown' })
+      expect(isPopoverOpen(component)).toBe(true)
+      component.unmount()
     })
 
-    it('closes dropdown on Escape', async () => {
+    it('closes popover on Escape', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      expect(isPopoverOpen(component)).toBe(true)
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-      expect(button.attributes('aria-expanded')).toBe('true')
-
-      await button.trigger('keydown', { key: 'Escape' })
-      expect(button.attributes('aria-expanded')).toBe('false')
+      await component.find('[popover="auto"]').trigger('keydown', { key: 'Escape' })
+      expect(isPopoverOpen(component)).toBe(false)
+      component.unmount()
     })
 
-    it('navigates with arrow keys in listbox', async () => {
+    it('navigates with arrow keys in popover', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-
-      // Navigate down
-      await listbox.trigger('keydown', { key: 'ArrowDown' })
-
-      // Navigate up
-      await listbox.trigger('keydown', { key: 'ArrowUp' })
-
-      // Should still be focused on an item (test that it doesn't crash)
-      expect(listbox.exists()).toBe(true)
-    })
-
-    it('closes listbox on Escape', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-      await listbox.trigger('keydown', { key: 'Escape' })
-
-      expect(button.attributes('aria-expanded')).toBe('false')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const popover = component.find('[popover="auto"]')
+      await popover.trigger('keydown', { key: 'ArrowDown' })
+      await popover.trigger('keydown', { key: 'ArrowUp' })
+      expect(isPopoverOpen(component)).toBe(true)
+      component.unmount()
     })
 
     it('navigates to Home and End', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '3.0.0',
           versions: { '1.0.0': {}, '2.0.0': {}, '3.0.0': {} },
-          distTags: {
-            latest: '3.0.0',
-            beta: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '3.0.0', beta: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-
-      // Navigate to end
-      await listbox.trigger('keydown', { key: 'End' })
-
-      // Navigate to home
-      await listbox.trigger('keydown', { key: 'Home' })
-
-      // Should not crash
-      expect(listbox.exists()).toBe(true)
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const popover = component.find('[popover="auto"]')
+      await popover.trigger('keydown', { key: 'End' })
+      await popover.trigger('keydown', { key: 'Home' })
+      expect(isPopoverOpen(component)).toBe(true)
+      component.unmount()
     })
   })
 
   describe('version selection', () => {
-    it('closes dropdown and navigates when clicking a version', async () => {
+    it('generates correct URL from pattern', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
+          urlPattern: '/package-code/test-package/v/{version}/src/index.ts',
         },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Click on the version link
       const versionLink = component.findAll('a').find(a => a.text().includes('1.0.0'))
-      expect(versionLink?.exists()).toBe(true)
-      await versionLink!.trigger('click')
-
-      // Dropdown should close
-      expect(button.attributes('aria-expanded')).toBe('false')
+      expect(versionLink?.attributes('href')).toBe(
+        '/package-code/test-package/v/1.0.0/src/index.ts',
+      )
+      component.unmount()
     })
 
-    it('generates correct URL from pattern', async () => {
+    it('closes popover when clicking a version link', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-code/test-package/v/{version}/src/index.ts',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
 
       const versionLink = component.findAll('a').find(a => a.text().includes('1.0.0'))
-      expect(versionLink?.attributes('href')).toBe(
-        '/package-code/test-package/v/1.0.0/src/index.ts',
-      )
+      expect(versionLink?.exists()).toBe(true)
+      await versionLink!.trigger('click')
+      expect(isPopoverOpen(component)).toBe(false)
+      component.unmount()
     })
   })
 
   describe('expand/collapse groups', () => {
     it('shows expand button for groups', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Find expand button within the dropdown
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
-      expect(expandButton.exists()).toBe(true)
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      expect(component.find('[popover="auto"] button[aria-expanded]').exists()).toBe(true)
+      component.unmount()
     })
 
     it('loads versions when expanding a group', async () => {
@@ -355,25 +251,16 @@ describe('VersionSelector', () => {
       ])
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Find and click expand button
-      const expandButton = component.find('[role="listbox"] button[aria-expanded="false"]')
-      await expandButton.trigger('click')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
 
       await vi.waitFor(() => {
         expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package')
       })
+      component.unmount()
     })
 
     it('collapses group when clicking expanded button', async () => {
@@ -384,46 +271,30 @@ describe('VersionSelector', () => {
       ])
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.2.0',
-          versions: { '1.2.0': {} },
-          distTags: { latest: '1.2.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Expand
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
-      await expandButton.trigger('click')
-
-      await vi.waitFor(() => {
-        expect(mockFetchAllPackageVersions).toHaveBeenCalled()
+        props: { ...defaultProps, currentVersion: '1.2.0', versions: { '1.2.0': {} } },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
 
-      // Wait for expansion
+      await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalled())
       await vi.waitFor(
-        () => {
-          const btn = component.find('[role="listbox"] button[aria-expanded="true"]')
-          expect(btn.exists()).toBe(true)
-        },
+        () =>
+          expect(component.find('[popover="auto"] button[aria-expanded="true"]').exists()).toBe(
+            true,
+          ),
         { timeout: 2000 },
       )
 
-      // Collapse
-      const expandedButton = component.find('[role="listbox"] button[aria-expanded="true"]')
-      await expandedButton.trigger('click')
-
+      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(
-        () => {
-          const btn = component.find('[role="listbox"] button[aria-expanded="false"]')
-          expect(btn.exists()).toBe(true)
-        },
+        () =>
+          expect(component.find('[popover="auto"] button[aria-expanded="false"]').exists()).toBe(
+            true,
+          ),
         { timeout: 2000 },
       )
+      component.unmount()
     })
 
     it('toggles older version groups for a single-version tagged release', async () => {
@@ -433,39 +304,26 @@ describe('VersionSelector', () => {
       ])
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {}, '0.9.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const expandButton = component.find('[role="listbox"] button[aria-expanded="false"]')
-      await expandButton.trigger('click')
-
-      await vi.waitFor(() => {
-        expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package')
+        props: { ...defaultProps, versions: { '1.0.0': {}, '0.9.0': {} } },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
 
+      await vi.waitFor(() =>
+        expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package'),
+      )
       await vi.waitFor(() => {
-        expect(component.find('[role="listbox"]').text()).toContain('0.9')
-        const expandedButton = component.find('[role="listbox"] button[aria-expanded="true"]')
-        expect(expandedButton.exists()).toBe(true)
+        expect(component.find('[popover="auto"]').text()).toContain('0.9')
+        expect(component.find('[popover="auto"] button[aria-expanded="true"]').exists()).toBe(true)
       })
 
-      const expandedButton = component.find('[role="listbox"] button[aria-expanded="true"]')
-      await expandedButton.trigger('click')
-
+      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(() => {
-        expect(component.find('[role="listbox"]').text()).not.toContain('0.9')
-        const collapsedButton = component.find('[role="listbox"] button[aria-expanded="false"]')
-        expect(collapsedButton.exists()).toBe(true)
+        expect(component.find('[popover="auto"]').text()).not.toContain('0.9')
+        expect(component.find('[popover="auto"] button[aria-expanded="false"]').exists()).toBe(true)
       })
+      component.unmount()
     })
 
     it('does not reveal unrelated older groups when expanding a tagged row with nested versions', async () => {
@@ -478,73 +336,33 @@ describe('VersionSelector', () => {
 
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '1.2.0',
           versions: { '1.2.0': {}, '1.1.0': {}, '1.0.0': {}, '0.9.0': {} },
-          distTags: { latest: '1.2.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const trigger = component.find('button[aria-haspopup="listbox"]')
-      await trigger.trigger('click')
-
-      const expandButton = component.find('[role="listbox"] button[aria-expanded="false"]')
-      await expandButton.trigger('click')
-
-      await vi.waitFor(() => {
-        expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package')
-      })
-
-      await vi.waitFor(() => {
-        const listboxText = component.find('[role="listbox"]').text()
-        expect(listboxText).toContain('1.1.0')
-        expect(listboxText).toContain('1.0.0')
-        expect(listboxText).not.toContain('0.9')
-      })
-
-      const expandedButton = component.find('[role="listbox"] button[aria-expanded="true"]')
-      await expandedButton.trigger('click')
-
-      await vi.waitFor(() => {
-        const listboxText = component.find('[role="listbox"]').text()
-        expect(listboxText).not.toContain('1.1.0')
-        expect(listboxText).not.toContain('1.0.0')
-        expect(listboxText).not.toContain('0.9')
-      })
-    })
-
-    it('collapses additional version groups with ArrowLeft when showAllGroups is open', async () => {
-      mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.0.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
-      ])
-
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {}, '0.9.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
         },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
 
-      const trigger = component.find('button[aria-haspopup="listbox"]')
-      await trigger.trigger('click')
-
-      await component.find('[role="listbox"] button[aria-expanded="false"]').trigger('click')
-
+      await vi.waitFor(() =>
+        expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package'),
+      )
       await vi.waitFor(() => {
-        expect(component.find('[role="listbox"]').text()).toContain('0.9')
+        const text = component.find('[popover="auto"]').text()
+        expect(text).toContain('1.1.0')
+        expect(text).toContain('1.0.0')
+        expect(text).not.toContain('0.9')
       })
 
-      const listbox = component.find('[role="listbox"]')
-      await listbox.trigger('keydown', { key: 'ArrowLeft' })
-
+      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(() => {
-        expect(listbox.text()).not.toContain('0.9')
+        const text = component.find('[popover="auto"]').text()
+        expect(text).not.toContain('1.1.0')
+        expect(text).not.toContain('1.0.0')
+        expect(text).not.toContain('0.9')
       })
+      component.unmount()
     })
 
     it('resets showAllGroups when dist-tags props change after loading', async () => {
@@ -554,28 +372,17 @@ describe('VersionSelector', () => {
       ])
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {}, '0.9.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: { ...defaultProps, versions: { '1.0.0': {}, '0.9.0': {} } },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
 
-      const trigger = component.find('button[aria-haspopup="listbox"]')
-      await trigger.trigger('click')
-      await component.find('[role="listbox"] button[aria-expanded="false"]').trigger('click')
-
-      await vi.waitFor(() => {
-        expect(component.find('[role="listbox"]').text()).toContain('0.9')
-      })
+      await vi.waitFor(() => expect(component.find('[popover="auto"]').text()).toContain('0.9'))
 
       await component.setProps({ distTags: { latest: '1.0.0' } })
-
-      await vi.waitFor(() => {
-        expect(component.find('[role="listbox"]').text()).not.toContain('0.9')
-      })
+      await vi.waitFor(() => expect(component.find('[popover="auto"]').text()).not.toContain('0.9'))
+      component.unmount()
     })
 
     it('ignores expand clicks while a group is already loading', async () => {
@@ -586,19 +393,11 @@ describe('VersionSelector', () => {
       mockFetchAllPackageVersions.mockReturnValue(loadPromise)
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const trigger = component.find('button[aria-haspopup="listbox"]')
-      await trigger.trigger('click')
-
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const expandButton = component.find('[popover="auto"] button[aria-expanded]')
       await expandButton.trigger('click')
       await expandButton.trigger('click')
 
@@ -611,6 +410,7 @@ describe('VersionSelector', () => {
           trustStatus: { provenance: false, trustedPublisher: false, stagedPublish: false },
         },
       ])
+      component.unmount()
     })
   })
 
@@ -625,26 +425,17 @@ describe('VersionSelector', () => {
 
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '0.10.1',
           versions: { '0.10.1': {} },
           distTags: { latest: '0.10.1' },
-          urlPattern: '/package-docs/test-package/v/{version}',
         },
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Expand the group
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
-      await expandButton.trigger('click')
-
-      await vi.waitFor(() => {
-        expect(mockFetchAllPackageVersions).toHaveBeenCalled()
-      })
-
-      // Wait for versions to load
+      await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalled())
       await vi.waitFor(
         () => {
           const text = component.text()
@@ -654,52 +445,33 @@ describe('VersionSelector', () => {
         },
         { timeout: 2000 },
       )
+      component.unmount()
     })
   })
 
   describe('dist-tag display', () => {
     it('displays multiple tags for same version', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: {
-            latest: '1.0.0',
-            stable: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: { ...defaultProps, distTags: { latest: '1.0.0', stable: '1.0.0' } },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-      expect(listbox.text()).toContain('latest')
-      expect(listbox.text()).toContain('stable')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const popover = component.find('[popover="auto"]')
+      expect(popover.text()).toContain('latest')
+      expect(popover.text()).toContain('stable')
+      component.unmount()
     })
 
     it('shows "latest" tag with special styling', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Find the latest tag span
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
       const latestTags = component.findAll('span').filter(s => s.text() === 'latest')
       expect(latestTags.length).toBeGreaterThan(0)
-      // Should have accent styling
-      const hasAccentStyle = latestTags.some(t => t.classes().some(c => c.includes('badge-accent')))
-      expect(hasAccentStyle).toBe(true)
+      expect(latestTags.some(t => t.classes().some(c => c.includes('badge-accent')))).toBe(true)
+      component.unmount()
     })
   })
 
@@ -709,206 +481,114 @@ describe('VersionSelector', () => {
       mockFetchAllPackageVersions.mockReturnValue(promise)
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Click expand
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
-      await expandButton.trigger('click')
-
-      // Should show loading spinner (motion-safe:animate-spin is applied)
       await vi.waitFor(() => {
-        const spinner = component.find('.i-svg-spinners\\:ring-resize')
-        expect(spinner.exists()).toBe(true)
+        expect(component.find('.i-svg-spinners\\:ring-resize').exists()).toBe(true)
       })
-
-      // Resolve the promise to clean up
       resolve([])
+      component.unmount()
     })
   })
 
   describe('accessibility', () => {
-    it('has aria-haspopup="listbox" on trigger button', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup]')
-      expect(button.attributes('aria-haspopup')).toBe('listbox')
+    it('trigger button has popovertarget wired to the popover id', async () => {
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const button = component.find('[data-testid="version-selector-button"]')
+      const popover = component.find('[popover="auto"]')
+      expect(button.attributes('popovertarget')).toBe(popover.attributes('id'))
     })
 
-    it('has role="listbox" on dropdown', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      expect(component.find('[role="listbox"]').exists()).toBe(true)
+    it('popover has an accessible aria-label', async () => {
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      expect(component.find('[popover="auto"]').attributes('aria-label')).toBeTruthy()
     })
 
-    it('has role="option" on version items', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      expect(component.find('[role="option"]').exists()).toBe(true)
+    it('component is wrapped in a nav with an aria-label', async () => {
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      expect(component.find('nav[aria-label]').exists()).toBe(true)
     })
 
-    it('sets aria-selected on current version', async () => {
+    it('current version link has aria-current="page"', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const selectedOption = component.find('[role="option"][aria-selected="true"]')
-      expect(selectedOption.exists()).toBe(true)
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const currentLink = component.find('a[aria-current="page"]')
+      expect(currentLink.exists()).toBe(true)
+      expect(currentLink.text()).toContain('1.0.0')
+      component.unmount()
     })
 
-    it('updates aria-activedescendant when navigating', async () => {
+    it('non-current version links do not have aria-current', async () => {
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const listbox = component.find('[role="listbox"]')
-      expect(listbox.attributes('aria-activedescendant')).toBeDefined()
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const oldLink = component.findAll('a[href]').find(a => a.text().includes('1.0.0'))
+      expect(oldLink?.attributes('aria-current')).toBeUndefined()
+      component.unmount()
     })
 
-    it('expand buttons have aria-expanded attribute', async () => {
+    it('expand buttons have aria-expanded and aria-controls', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const expandButton = component.find('[popover="auto"] button[aria-expanded]')
       expect(expandButton.exists()).toBe(true)
       expect(['true', 'false']).toContain(expandButton.attributes('aria-expanded'))
+      expect(expandButton.attributes('aria-controls')).toBeTruthy()
+      component.unmount()
     })
 
-    it('expand buttons have aria-label', async () => {
+    it('expand buttons have a descriptive aria-label', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      const expandButton = component.find('[role="listbox"] button[aria-label]')
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      const expandButton = component.find('[popover="auto"] button[aria-label]')
       expect(expandButton.exists()).toBe(true)
-      expect(expandButton.attributes('aria-label')).toMatch(/Expand|Collapse/)
+      expect(expandButton.attributes('aria-label')).toBeTruthy()
+      component.unmount()
     })
 
-    it('icons have aria-hidden attribute', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-      })
-
-      // The chevron icon in the main button
-      const chevronIcon = component.find('button[aria-haspopup] span[aria-hidden="true"]')
-      expect(chevronIcon.exists()).toBe(true)
+    it('decorative icons have aria-hidden', async () => {
+      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      expect(component.findAll('[aria-hidden="true"]').length).toBeGreaterThan(0)
     })
   })
 
   describe('error handling', () => {
     it('handles fetch errors gracefully', async () => {
       mockFetchAllPackageVersions.mockRejectedValue(new Error('Network error'))
-
       const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
 
       const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
+        props: defaultProps,
+        attachTo: document.body,
       })
+      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
 
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-
-      // Click expand
-      const expandButton = component.find('[role="listbox"] button[aria-expanded]')
-      await expandButton.trigger('click')
-
-      // Wait for error to be logged
       await vi.waitFor(() => {
         expect(consoleSpy).toHaveBeenCalledWith('Failed to load versions:', expect.any(Error))
       })
-
       consoleSpy.mockRestore()
+      component.unmount()
     })
   })
 
@@ -921,66 +601,27 @@ describe('VersionSelector', () => {
 
       const component = await mountSuspended(VersionSelector, {
         props: {
-          packageName: 'test-package',
+          ...defaultProps,
           currentVersion: '2.0.0',
           versions: { '1.0.0': {}, '2.0.0': {} },
-          distTags: {
-            latest: '2.0.0',
-            old: '1.0.0',
-          },
-          urlPattern: '/package-docs/test-package/v/{version}',
+          distTags: { latest: '2.0.0', old: '1.0.0' },
         },
+        attachTo: document.body,
       })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
+      const button = component.find('[data-testid="version-selector-button"]')
       await button.trigger('click')
 
-      // Expand first group
-      const expandButtons = component.findAll('[role="listbox"] button[aria-expanded="false"]')
-      if (expandButtons[0]) {
-        await expandButtons[0].trigger('click')
-      }
-
-      await vi.waitFor(() => {
-        expect(mockFetchAllPackageVersions).toHaveBeenCalledTimes(1)
-      })
+      const expandButtons = component.findAll('[popover="auto"] button[aria-expanded="false"]')
+      if (expandButtons[0]) await expandButtons[0].trigger('click')
+      await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalledTimes(1))
 
-      // Close and reopen
       await button.trigger('click')
       await button.trigger('click')
 
-      // Expand another group - should not fetch again
-      const updatedButtons = component.findAll('[role="listbox"] button[aria-expanded="false"]')
-      if (updatedButtons[0]) {
-        await updatedButtons[0].trigger('click')
-      }
-
-      // Should still only have been called once
+      const updatedButtons = component.findAll('[popover="auto"] button[aria-expanded="false"]')
+      if (updatedButtons[0]) await updatedButtons[0].trigger('click')
       expect(mockFetchAllPackageVersions).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  describe('click outside', () => {
-    it('closes dropdown when clicking outside', async () => {
-      const component = await mountSuspended(VersionSelector, {
-        props: {
-          packageName: 'test-package',
-          currentVersion: '1.0.0',
-          versions: { '1.0.0': {} },
-          distTags: { latest: '1.0.0' },
-          urlPattern: '/package-docs/test-package/v/{version}',
-        },
-        attachTo: document.body,
-      })
-
-      const button = component.find('button[aria-haspopup="listbox"]')
-      await button.trigger('click')
-      expect(button.attributes('aria-expanded')).toBe('true')
-
-      // Simulate click outside by directly setting isOpen
-      // Note: onClickOutside is hard to test in JSDOM, so we verify the behavior exists
-      // by checking the component closes when we trigger a click on the main element
-      // after it opens
+      component.unmount()
     })
   })
 })

From 772c66b1fc36bdf24355e8351a90eae51b9e9634 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Thu, 6 Aug 2026 11:44:56 +0200
Subject: [PATCH 09/12] fix: tests

---
 test/e2e/docs.spec.ts                        |  41 +++--
 test/nuxt/components/VersionSelector.spec.ts | 161 ++++++++++---------
 2 files changed, 113 insertions(+), 89 deletions(-)

diff --git a/test/e2e/docs.spec.ts b/test/e2e/docs.spec.ts
index 267ed6ad69..83a0915495 100644
--- a/test/e2e/docs.spec.ts
+++ b/test/e2e/docs.spec.ts
@@ -1,5 +1,21 @@
+import type { Page } from '@playwright/test'
 import { expect, test } from './test-utils'
 
+/** The version selector trigger button in the package subheader. */
+function getVersionButton(page: Page) {
+  return page.locator('[data-testid="package-subheader"] [data-testid="version-selector-button"]')
+}
+
+/** The native popover that holds the version links. */
+function getVersionDropdown(page: Page) {
+  return page.locator('[popover="auto"]')
+}
+
+/** Version links inside the open dropdown for the given package. */
+function getVersionLinks(page: Page, packageName: string) {
+  return getVersionDropdown(page).locator(`a[href*="/package-docs/${packageName}/v/"]`)
+}
+
 test.describe('API Documentation Pages', () => {
   test('docs page loads and shows content for a package', async ({ page, goto }) => {
     // Use a small, stable package with TypeScript types
@@ -10,7 +26,7 @@ test.describe('API Documentation Pages', () => {
 
     // Header should show package name and version
     await expect(page.locator('header').getByText('ufo')).toBeVisible()
-    await expect(page.locator('[data-testid="package-subheader"]').getByText('1.6.3')).toBeVisible()
+    await expect(getVersionButton(page).getByText('1.6.3')).toBeVisible()
 
     // Should have documentation content
     const docsContent = page.locator('.docs-content')
@@ -94,35 +110,30 @@ test.describe('Version Selector', () => {
     await goto('/package-docs/ufo/v/1.6.3', { waitUntil: 'hydration' })
 
     // Find and click the version selector button (wait for it to be visible)
-    const versionButton = page
-      .locator('[data-testid="package-subheader"] button')
-      .filter({ hasText: '1.6.3' })
+    const versionButton = getVersionButton(page).filter({ hasText: '1.6.3' })
     await expect(versionButton).toBeVisible({ timeout: 10000 })
 
     await versionButton.click()
 
-    // Dropdown should appear with version options
-    const dropdown = page.locator('[role="listbox"]')
+    // Popover should appear with version links
+    const dropdown = getVersionDropdown(page)
     await expect(dropdown).toBeVisible()
 
     // Should show multiple versions
-    const versionOptions = dropdown.locator('[role="option"]')
-    await expect(versionOptions.first()).toBeVisible()
+    await expect(getVersionLinks(page, 'ufo').first()).toBeVisible()
   })
 
   test('selecting a version navigates to that version', async ({ page, goto }) => {
     await goto('/package-docs/ufo/v/1.6.3', { waitUntil: 'hydration' })
 
     // Find and click the version selector button (wait for it to be visible)
-    const versionButton = page
-      .locator('[data-testid="package-subheader"] button')
-      .filter({ hasText: '1.6.3' })
+    const versionButton = getVersionButton(page).filter({ hasText: '1.6.3' })
     await expect(versionButton).toBeVisible({ timeout: 10000 })
 
     await versionButton.click()
 
     // Find a version link that's not the current version by checking the href
-    const versionLinks = page.locator('[role="option"] a[href*="/package-docs/ufo/v/"]')
+    const versionLinks = getVersionLinks(page, 'ufo')
     const count = await versionLinks.count()
 
     // Find first link that doesn't point to 1.6.3
@@ -150,14 +161,12 @@ test.describe('Version Selector', () => {
     await goto('/package-docs/ufo/v/1.6.3', { waitUntil: 'hydration' })
 
     // Wait for version button to be visible
-    const versionButton = page
-      .locator('[data-testid="package-subheader"] button')
-      .filter({ hasText: '1.6.3' })
+    const versionButton = getVersionButton(page).filter({ hasText: '1.6.3' })
     await expect(versionButton).toBeVisible({ timeout: 10000 })
 
     await versionButton.click()
 
-    const dropdown = page.locator('[role="listbox"]')
+    const dropdown = getVersionDropdown(page)
     await expect(dropdown).toBeVisible()
 
     // Press escape
diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index 56f7a18b1e..a6145c7e14 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { userEvent } from '@vitest/browser/context'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import type { PackageVersionInfo } from '#shared/types/npm-registry'
 import VersionSelector from '~/components/VersionSelector.vue'
@@ -21,9 +22,26 @@ const defaultProps = {
   urlPattern: '/package-docs/test-package/v/{version}',
 }
 
+type VersionSelectorWrapper = Awaited<ReturnType<typeof mountSuspended>>
+
+/** The trigger button that toggles the version popover. */
+function getTrigger(component: VersionSelectorWrapper) {
+  return component.find('[data-testid="version-selector-button"]')
+}
+
+/** The native popover element that holds the version groups. */
+function getPopover(component: VersionSelectorWrapper) {
+  return component.find('[popover="auto"]')
+}
+
+/** Open the popover by activating its trigger. */
+function openPopover(component: VersionSelectorWrapper) {
+  return getTrigger(component).trigger('click')
+}
+
 /** Returns true when the native popover is open (in the top layer). */
-function isPopoverOpen(component: Awaited<ReturnType<typeof mountSuspended>>): boolean {
-  const popover = component.find('[popover="auto"]')
+function isPopoverOpen(component: VersionSelectorWrapper): boolean {
+  const popover = getPopover(component)
   return popover.exists() && popover.element.matches(':popover-open')
 }
 
@@ -36,7 +54,7 @@ describe('VersionSelector', () => {
   describe('basic rendering', () => {
     it('renders the current version in the button', async () => {
       const component = await mountSuspended(VersionSelector, { props: defaultProps })
-      const button = component.find('[data-testid="version-selector-button"]')
+      const button = getTrigger(component)
       expect(button.exists()).toBe(true)
       expect(button.text()).toContain('1.0.0')
     })
@@ -61,7 +79,7 @@ describe('VersionSelector', () => {
           distTags: { latest: '2.0.0', old: '1.0.0' },
         },
       })
-      const button = component.find('[data-testid="version-selector-button"]')
+      const button = getTrigger(component)
       expect(button.text()).not.toContain('latest')
     })
 
@@ -77,7 +95,7 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       expect(isPopoverOpen(component)).toBe(true)
       component.unmount()
     })
@@ -87,7 +105,7 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      const button = component.find('[data-testid="version-selector-button"]')
+      const button = getTrigger(component)
       await button.trigger('click')
       expect(isPopoverOpen(component)).toBe(true)
       await button.trigger('click')
@@ -105,9 +123,9 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
 
-      const popover = component.find('[popover="auto"]')
+      const popover = getPopover(component)
       expect(popover.text()).toContain('2.0.0')
       expect(popover.text()).toContain('1.0.0')
       component.unmount()
@@ -123,7 +141,7 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       expect(component.text()).toContain('View all 3 versions')
       component.unmount()
     })
@@ -135,9 +153,7 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component
-        .find('[data-testid="version-selector-button"]')
-        .trigger('keydown', { key: 'ArrowDown' })
+      await getTrigger(component).trigger('keydown', { key: 'ArrowDown' })
       expect(isPopoverOpen(component)).toBe(true)
       component.unmount()
     })
@@ -147,11 +163,13 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       expect(isPopoverOpen(component)).toBe(true)
 
-      await component.find('[popover="auto"]').trigger('keydown', { key: 'Escape' })
-      expect(isPopoverOpen(component)).toBe(false)
+      // A real (trusted) Escape triggers the browser's native popover
+      // light-dismiss; a synthetic keydown event would not.
+      await userEvent.keyboard('{Escape}')
+      await vi.waitFor(() => expect(isPopoverOpen(component)).toBe(false))
       component.unmount()
     })
 
@@ -165,8 +183,8 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const popover = component.find('[popover="auto"]')
+      await openPopover(component)
+      const popover = getPopover(component)
       await popover.trigger('keydown', { key: 'ArrowDown' })
       await popover.trigger('keydown', { key: 'ArrowUp' })
       expect(isPopoverOpen(component)).toBe(true)
@@ -183,8 +201,8 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const popover = component.find('[popover="auto"]')
+      await openPopover(component)
+      const popover = getPopover(component)
       await popover.trigger('keydown', { key: 'End' })
       await popover.trigger('keydown', { key: 'Home' })
       expect(isPopoverOpen(component)).toBe(true)
@@ -204,7 +222,7 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
 
       const versionLink = component.findAll('a').find(a => a.text().includes('1.0.0'))
       expect(versionLink?.attributes('href')).toBe(
@@ -223,7 +241,7 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
 
       const versionLink = component.findAll('a').find(a => a.text().includes('1.0.0'))
       expect(versionLink?.exists()).toBe(true)
@@ -239,8 +257,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      expect(component.find('[popover="auto"] button[aria-expanded]').exists()).toBe(true)
+      await openPopover(component)
+      expect(getPopover(component).find('button[aria-expanded]').exists()).toBe(true)
       component.unmount()
     })
 
@@ -254,8 +272,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded="false"]').trigger('click')
 
       await vi.waitFor(() => {
         expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package')
@@ -274,24 +292,20 @@ describe('VersionSelector', () => {
         props: { ...defaultProps, currentVersion: '1.2.0', versions: { '1.2.0': {} } },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded]').trigger('click')
 
       await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalled())
       await vi.waitFor(
         () =>
-          expect(component.find('[popover="auto"] button[aria-expanded="true"]').exists()).toBe(
-            true,
-          ),
+          expect(getPopover(component).find('button[aria-expanded="true"]').exists()).toBe(true),
         { timeout: 2000 },
       )
 
-      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
+      await getPopover(component).find('button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(
         () =>
-          expect(component.find('[popover="auto"] button[aria-expanded="false"]').exists()).toBe(
-            true,
-          ),
+          expect(getPopover(component).find('button[aria-expanded="false"]').exists()).toBe(true),
         { timeout: 2000 },
       )
       component.unmount()
@@ -307,21 +321,21 @@ describe('VersionSelector', () => {
         props: { ...defaultProps, versions: { '1.0.0': {}, '0.9.0': {} } },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded="false"]').trigger('click')
 
       await vi.waitFor(() =>
         expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package'),
       )
       await vi.waitFor(() => {
-        expect(component.find('[popover="auto"]').text()).toContain('0.9')
-        expect(component.find('[popover="auto"] button[aria-expanded="true"]').exists()).toBe(true)
+        expect(getPopover(component).text()).toContain('0.9')
+        expect(getPopover(component).find('button[aria-expanded="true"]').exists()).toBe(true)
       })
 
-      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
+      await getPopover(component).find('button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(() => {
-        expect(component.find('[popover="auto"]').text()).not.toContain('0.9')
-        expect(component.find('[popover="auto"] button[aria-expanded="false"]').exists()).toBe(true)
+        expect(getPopover(component).text()).not.toContain('0.9')
+        expect(getPopover(component).find('button[aria-expanded="false"]').exists()).toBe(true)
       })
       component.unmount()
     })
@@ -339,25 +353,26 @@ describe('VersionSelector', () => {
           ...defaultProps,
           currentVersion: '1.2.0',
           versions: { '1.2.0': {}, '1.1.0': {}, '1.0.0': {}, '0.9.0': {} },
+          distTags: { latest: '1.2.0' },
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded="false"]').trigger('click')
 
       await vi.waitFor(() =>
         expect(mockFetchAllPackageVersions).toHaveBeenCalledWith('test-package'),
       )
       await vi.waitFor(() => {
-        const text = component.find('[popover="auto"]').text()
+        const text = getPopover(component).text()
         expect(text).toContain('1.1.0')
         expect(text).toContain('1.0.0')
         expect(text).not.toContain('0.9')
       })
 
-      await component.find('[popover="auto"] button[aria-expanded="true"]').trigger('click')
+      await getPopover(component).find('button[aria-expanded="true"]').trigger('click')
       await vi.waitFor(() => {
-        const text = component.find('[popover="auto"]').text()
+        const text = getPopover(component).text()
         expect(text).not.toContain('1.1.0')
         expect(text).not.toContain('1.0.0')
         expect(text).not.toContain('0.9')
@@ -375,13 +390,13 @@ describe('VersionSelector', () => {
         props: { ...defaultProps, versions: { '1.0.0': {}, '0.9.0': {} } },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded="false"]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded="false"]').trigger('click')
 
-      await vi.waitFor(() => expect(component.find('[popover="auto"]').text()).toContain('0.9'))
+      await vi.waitFor(() => expect(getPopover(component).text()).toContain('0.9'))
 
       await component.setProps({ distTags: { latest: '1.0.0' } })
-      await vi.waitFor(() => expect(component.find('[popover="auto"]').text()).not.toContain('0.9'))
+      await vi.waitFor(() => expect(getPopover(component).text()).not.toContain('0.9'))
       component.unmount()
     })
 
@@ -396,8 +411,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const expandButton = component.find('[popover="auto"] button[aria-expanded]')
+      await openPopover(component)
+      const expandButton = getPopover(component).find('button[aria-expanded]')
       await expandButton.trigger('click')
       await expandButton.trigger('click')
 
@@ -432,8 +447,8 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded]').trigger('click')
 
       await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalled())
       await vi.waitFor(
@@ -455,8 +470,8 @@ describe('VersionSelector', () => {
         props: { ...defaultProps, distTags: { latest: '1.0.0', stable: '1.0.0' } },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const popover = component.find('[popover="auto"]')
+      await openPopover(component)
+      const popover = getPopover(component)
       expect(popover.text()).toContain('latest')
       expect(popover.text()).toContain('stable')
       component.unmount()
@@ -467,7 +482,7 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       const latestTags = component.findAll('span').filter(s => s.text() === 'latest')
       expect(latestTags.length).toBeGreaterThan(0)
       expect(latestTags.some(t => t.classes().some(c => c.includes('badge-accent')))).toBe(true)
@@ -484,8 +499,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded]').trigger('click')
 
       await vi.waitFor(() => {
         expect(component.find('.i-svg-spinners\\:ring-resize').exists()).toBe(true)
@@ -498,14 +513,14 @@ describe('VersionSelector', () => {
   describe('accessibility', () => {
     it('trigger button has popovertarget wired to the popover id', async () => {
       const component = await mountSuspended(VersionSelector, { props: defaultProps })
-      const button = component.find('[data-testid="version-selector-button"]')
-      const popover = component.find('[popover="auto"]')
+      const button = getTrigger(component)
+      const popover = getPopover(component)
       expect(button.attributes('popovertarget')).toBe(popover.attributes('id'))
     })
 
     it('popover has an accessible aria-label', async () => {
       const component = await mountSuspended(VersionSelector, { props: defaultProps })
-      expect(component.find('[popover="auto"]').attributes('aria-label')).toBeTruthy()
+      expect(getPopover(component).attributes('aria-label')).toBeTruthy()
     })
 
     it('component is wrapped in a nav with an aria-label', async () => {
@@ -518,7 +533,7 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       const currentLink = component.find('a[aria-current="page"]')
       expect(currentLink.exists()).toBe(true)
       expect(currentLink.text()).toContain('1.0.0')
@@ -535,7 +550,7 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
+      await openPopover(component)
       const oldLink = component.findAll('a[href]').find(a => a.text().includes('1.0.0'))
       expect(oldLink?.attributes('aria-current')).toBeUndefined()
       component.unmount()
@@ -546,8 +561,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const expandButton = component.find('[popover="auto"] button[aria-expanded]')
+      await openPopover(component)
+      const expandButton = getPopover(component).find('button[aria-expanded]')
       expect(expandButton.exists()).toBe(true)
       expect(['true', 'false']).toContain(expandButton.attributes('aria-expanded'))
       expect(expandButton.attributes('aria-controls')).toBeTruthy()
@@ -559,8 +574,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      const expandButton = component.find('[popover="auto"] button[aria-label]')
+      await openPopover(component)
+      const expandButton = getPopover(component).find('button[aria-label]')
       expect(expandButton.exists()).toBe(true)
       expect(expandButton.attributes('aria-label')).toBeTruthy()
       component.unmount()
@@ -581,8 +596,8 @@ describe('VersionSelector', () => {
         props: defaultProps,
         attachTo: document.body,
       })
-      await component.find('[data-testid="version-selector-button"]').trigger('click')
-      await component.find('[popover="auto"] button[aria-expanded]').trigger('click')
+      await openPopover(component)
+      await getPopover(component).find('button[aria-expanded]').trigger('click')
 
       await vi.waitFor(() => {
         expect(consoleSpy).toHaveBeenCalledWith('Failed to load versions:', expect.any(Error))
@@ -608,17 +623,17 @@ describe('VersionSelector', () => {
         },
         attachTo: document.body,
       })
-      const button = component.find('[data-testid="version-selector-button"]')
+      const button = getTrigger(component)
       await button.trigger('click')
 
-      const expandButtons = component.findAll('[popover="auto"] button[aria-expanded="false"]')
+      const expandButtons = getPopover(component).findAll('button[aria-expanded="false"]')
       if (expandButtons[0]) await expandButtons[0].trigger('click')
       await vi.waitFor(() => expect(mockFetchAllPackageVersions).toHaveBeenCalledTimes(1))
 
       await button.trigger('click')
       await button.trigger('click')
 
-      const updatedButtons = component.findAll('[popover="auto"] button[aria-expanded="false"]')
+      const updatedButtons = getPopover(component).findAll('button[aria-expanded="false"]')
       if (updatedButtons[0]) await updatedButtons[0].trigger('click')
       expect(mockFetchAllPackageVersions).toHaveBeenCalledTimes(1)
       component.unmount()

From 0ac28e80a1c81c7d1595af12847883fb814fd462 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Thu, 6 Aug 2026 11:48:51 +0200
Subject: [PATCH 10/12] fix: remove unused import

---
 test/nuxt/components/VersionSelector.spec.ts | 156 +++++++++++++++----
 1 file changed, 127 insertions(+), 29 deletions(-)

diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index a6145c7e14..09901185e9 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -1,5 +1,4 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
-import { userEvent } from '@vitest/browser/context'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import type { PackageVersionInfo } from '#shared/types/npm-registry'
 import VersionSelector from '~/components/VersionSelector.vue'
@@ -53,7 +52,9 @@ describe('VersionSelector', () => {
 
   describe('basic rendering', () => {
     it('renders the current version in the button', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       const button = getTrigger(component)
       expect(button.exists()).toBe(true)
       expect(button.text()).toContain('1.0.0')
@@ -84,7 +85,9 @@ describe('VersionSelector', () => {
     })
 
     it('popover is not visible initially', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       expect(isPopoverOpen(component)).toBe(false)
     })
   })
@@ -264,8 +267,16 @@ describe('VersionSelector', () => {
 
     it('loads versions when expanding a group', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.0.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '1.0.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
@@ -283,13 +294,29 @@ describe('VersionSelector', () => {
 
     it('collapses group when clicking expanded button', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.2.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '1.1.0', time: '2024-01-12T12:00:00.000Z', hasProvenance: false },
-        { version: '1.0.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '1.2.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '1.1.0',
+          time: '2024-01-12T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '1.0.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
-        props: { ...defaultProps, currentVersion: '1.2.0', versions: { '1.2.0': {} } },
+        props: {
+          ...defaultProps,
+          currentVersion: '1.2.0',
+          versions: { '1.2.0': {} },
+        },
         attachTo: document.body,
       })
       await openPopover(component)
@@ -313,8 +340,16 @@ describe('VersionSelector', () => {
 
     it('toggles older version groups for a single-version tagged release', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.0.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '1.0.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
@@ -342,10 +377,26 @@ describe('VersionSelector', () => {
 
     it('does not reveal unrelated older groups when expanding a tagged row with nested versions', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.2.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '1.1.0', time: '2024-01-12T12:00:00.000Z', hasProvenance: false },
-        { version: '1.0.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-08T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '1.2.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '1.1.0',
+          time: '2024-01-12T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '1.0.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.0',
+          time: '2024-01-08T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
@@ -382,8 +433,16 @@ describe('VersionSelector', () => {
 
     it('resets showAllGroups when dist-tags props change after loading', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '1.0.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '1.0.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
@@ -422,7 +481,11 @@ describe('VersionSelector', () => {
         {
           version: '1.0.0',
           time: '2024-01-15T12:00:00.000Z',
-          trustStatus: { provenance: false, trustedPublisher: false, stagedPublish: false },
+          trustStatus: {
+            provenance: false,
+            trustedPublisher: false,
+            stagedPublish: false,
+          },
         },
       ])
       component.unmount()
@@ -432,10 +495,26 @@ describe('VersionSelector', () => {
   describe('0.x version grouping', () => {
     it('groups 0.x versions by minor version, not major', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '0.10.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '0.10.1', time: '2024-01-16T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
-        { version: '0.9.3', time: '2024-01-12T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '0.10.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.10.1',
+          time: '2024-01-16T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '0.9.3',
+          time: '2024-01-12T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {
@@ -467,7 +546,10 @@ describe('VersionSelector', () => {
   describe('dist-tag display', () => {
     it('displays multiple tags for same version', async () => {
       const component = await mountSuspended(VersionSelector, {
-        props: { ...defaultProps, distTags: { latest: '1.0.0', stable: '1.0.0' } },
+        props: {
+          ...defaultProps,
+          distTags: { latest: '1.0.0', stable: '1.0.0' },
+        },
         attachTo: document.body,
       })
       await openPopover(component)
@@ -512,19 +594,25 @@ describe('VersionSelector', () => {
 
   describe('accessibility', () => {
     it('trigger button has popovertarget wired to the popover id', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       const button = getTrigger(component)
       const popover = getPopover(component)
       expect(button.attributes('popovertarget')).toBe(popover.attributes('id'))
     })
 
     it('popover has an accessible aria-label', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       expect(getPopover(component).attributes('aria-label')).toBeTruthy()
     })
 
     it('component is wrapped in a nav with an aria-label', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       expect(component.find('nav[aria-label]').exists()).toBe(true)
     })
 
@@ -582,7 +670,9 @@ describe('VersionSelector', () => {
     })
 
     it('decorative icons have aria-hidden', async () => {
-      const component = await mountSuspended(VersionSelector, { props: defaultProps })
+      const component = await mountSuspended(VersionSelector, {
+        props: defaultProps,
+      })
       expect(component.findAll('[aria-hidden="true"]').length).toBeGreaterThan(0)
     })
   })
@@ -610,8 +700,16 @@ describe('VersionSelector', () => {
   describe('caching behavior', () => {
     it('only fetches versions once when expanding multiple groups', async () => {
       mockFetchAllPackageVersions.mockResolvedValue([
-        { version: '2.0.0', time: '2024-01-15T12:00:00.000Z', hasProvenance: false },
-        { version: '1.0.0', time: '2024-01-10T12:00:00.000Z', hasProvenance: false },
+        {
+          version: '2.0.0',
+          time: '2024-01-15T12:00:00.000Z',
+          hasProvenance: false,
+        },
+        {
+          version: '1.0.0',
+          time: '2024-01-10T12:00:00.000Z',
+          hasProvenance: false,
+        },
       ])
 
       const component = await mountSuspended(VersionSelector, {

From 20363acce20f6d181a25dcd2d8e20e31f13c6d3a Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Thu, 6 Aug 2026 11:55:58 +0200
Subject: [PATCH 11/12] fix: correct userEvent

---
 test/nuxt/components/VersionSelector.spec.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/test/nuxt/components/VersionSelector.spec.ts b/test/nuxt/components/VersionSelector.spec.ts
index 09901185e9..dca9667b4f 100644
--- a/test/nuxt/components/VersionSelector.spec.ts
+++ b/test/nuxt/components/VersionSelector.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { userEvent } from 'vitest/browser'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import type { PackageVersionInfo } from '#shared/types/npm-registry'
 import VersionSelector from '~/components/VersionSelector.vue'

From ce77199ba5964d36f53d9c81c3dbcfe8fd7ae2b3 Mon Sep 17 00:00:00 2001
From: leekeh <71131586+leekeh@users.noreply.github.com>
Date: Thu, 6 Aug 2026 12:34:04 +0200
Subject: [PATCH 12/12] fix: selector

---
 test/e2e/interactions.spec.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/interactions.spec.ts b/test/e2e/interactions.spec.ts
index ef41a900aa..1b767aa821 100644
--- a/test/e2e/interactions.spec.ts
+++ b/test/e2e/interactions.spec.ts
@@ -30,7 +30,7 @@ test.describe('Compare Page', () => {
     await expect(grid).toBeVisible({ timeout: 15000 })
 
     // Add another package via the input
-    const input = page.locator('#package-search')
+    const input = page.getByRole('combobox', { name: 'Search for packages' })
     await input.fill('nuxt')
 
     // Wait for search results and click on nuxt