fix: some a11y issues

Author: danielroe

app/components/DocsVersionSelector.vue

@@ -10,7 +10,9 @@ const props = defineProps<{
 }>()
 
 const isOpen = ref(false)
-const dropdownRef = ref<HTMLElement>()
+const dropdownRef = useTemplateRef('dropdownRef')
+const listboxRef = useTemplateRef('listboxRef')
+const focusedIndex = ref(-1)
 
 onClickOutside(dropdownRef, () => {
   isOpen.value = false
@@ -19,10 +21,19 @@ onClickOutside(dropdownRef, () => {
 /** Maximum number of versions to show in dropdown */
 const MAX_VERSIONS = 10
 
+/** Safe version comparison that falls back to string comparison on error */
+function safeCompareVersions(a: string, b: string): number {
+  try {
+    return compareVersions(a, b)
+  } catch {
+    return a.localeCompare(b)
+  }
+}
+
 /** Get sorted list of recent versions with their tags */
 const recentVersions = computed(() => {
   const versionList = Object.keys(props.versions)
-    .sort((a, b) => compareVersions(b, a))
+    .sort((a, b) => safeCompareVersions(b, a))
     .slice(0, MAX_VERSIONS)
 
   // Create a map of version -> tags
@@ -49,11 +60,72 @@ function getDocsUrl(version: string): string {
   return `/docs/${props.packageName}/v/${version}`
 }
 
-function handleKeydown(event: KeyboardEvent) {
+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 = recentVersions.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 'Enter':
+    case ' ':
+      event.preventDefault()
+      if (focusedIndex.value >= 0 && focusedIndex.value < items.length) {
+        navigateToVersion(items[focusedIndex.value]!.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(getDocsUrl(version))
+}
+
+// Reset focused index when dropdown opens
+watch(isOpen, open => {
+  if (open) {
+    const currentIdx = recentVersions.value.findIndex(v => v.isCurrent)
+    focusedIndex.value = currentIdx >= 0 ? currentIdx : 0
+  }
+})
 </script>
 
 <template>
@@ -62,9 +134,9 @@ function handleKeydown(event: KeyboardEvent) {
       type="button"
       aria-haspopup="listbox"
       :aria-expanded="isOpen"
-      class="flex items-center gap-1.5 text-fg-subtle font-mono text-sm hover:text-fg transition-colors"
+      class="flex items-center gap-1.5 text-fg-subtle font-mono text-sm hover:text-fg 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="handleKeydown"
+      @keydown="handleButtonKeydown"
     >
       <span>{{ currentVersion }}</span>
       <span
@@ -74,36 +146,44 @@ function handleKeydown(event: KeyboardEvent) {
         latest
       </span>
       <span
-        class="i-carbon-chevron-down w-3.5 h-3.5 transition-transform duration-200"
+        class="i-carbon-chevron-down w-3.5 h-3.5 transition-[transform] duration-200 motion-reduce:transition-none"
         :class="{ 'rotate-180': isOpen }"
         aria-hidden="true"
       />
     </button>
 
     <Transition
-      enter-active-class="transition duration-150 ease-out"
+      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 duration-100 ease-in"
+      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"
     >
       <div
         v-if="isOpen"
+        ref="listboxRef"
         role="listbox"
-        :aria-activedescendant="`version-${currentVersion}`"
-        class="absolute top-full left-0 mt-2 min-w-[180px] bg-bg-elevated border border-border rounded-lg shadow-lg z-50 py-1 max-h-[300px] overflow-y-auto"
-        @keydown="handleKeydown"
+        tabindex="0"
+        :aria-activedescendant="
+          focusedIndex >= 0 ? `version-${recentVersions[focusedIndex]?.version}` : undefined
+        "
+        class="absolute top-full left-0 mt-2 min-w-[180px] bg-bg-elevated border border-border rounded-lg shadow-lg z-50 py-1 max-h-[300px] overflow-y-auto overscroll-contain focus-visible:outline-none"
+        @keydown="handleListboxKeydown"
       >
         <NuxtLink
-          v-for="{ version, tags, isCurrent } in recentVersions"
+          v-for="({ version, tags, isCurrent }, index) in recentVersions"
           :id="`version-${version}`"
           :key="version"
           :to="getDocsUrl(version)"
           role="option"
           :aria-selected="isCurrent"
-          class="flex items-center justify-between gap-3 px-3 py-2 text-sm font-mono hover:bg-bg-muted transition-colors"
-          :class="isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-muted'"
+          :data-focused="index === focusedIndex"
+          class="flex items-center justify-between gap-3 px-3 py-2 text-sm font-mono hover:bg-bg-muted transition-[color,background-color] focus-visible:outline-none focus-visible:bg-bg-muted"
+          :class="[
+            isCurrent ? 'text-fg bg-bg-muted' : 'text-fg-muted',
+            index === focusedIndex ? 'bg-bg-muted' : '',
+          ]"
           @click="isOpen = false"
         >
           <span class="truncate">{{ version }}</span>
@@ -129,7 +209,7 @@ function handleKeydown(event: KeyboardEvent) {
         >
           <NuxtLink
             :to="`/${packageName}`"
-            class="text-xs text-fg-subtle hover:text-fg transition-colors"
+            class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
             @click="isOpen = false"
           >
             View all {{ Object.keys(versions).length }} versions