refactor: accept versioned route builder in cmd palette

The placeholder shape made callers that already had named-route helpers
resolve routes to strings and then patch encoded placeholders back into
place. That was brittle, especially for routes where Vue Router encodes
params differently from the URL shape users see.

We have a documented guideline that internal navigation should use
route object syntax with named routes instead of strings. This commit
allows callers to respect that guideline.

Author: serhalp

app/composables/useCommandPaletteVersionCommands.ts

@@ -1,12 +1,15 @@
 // @unocss-include
-import type { MaybeRefOrGetter } from 'vue'
+import type { MaybeRef, MaybeRefOrGetter } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import type {
   CommandPaletteCommand,
   CommandPaletteContextCommandInput,
   CommandPalettePackageContext,
 } from '~/types/command-palette'
 import { compare, satisfies, validRange } from 'semver'
 
+type CommandPaletteVersionRoute = (version: string) => RouteLocationRaw
+
 function getSortedVersions(context: CommandPalettePackageContext) {
   return [...context.versions].sort((a, b) => {
     if (a === context.resolvedVersion) return -1
@@ -19,7 +22,7 @@ function createVersionCommands(
   context: CommandPalettePackageContext,
   t: ReturnType<typeof useI18n>['t'],
   versions = getSortedVersions(context),
-  urlPattern?: string | null,
+  routeForVersion?: CommandPaletteVersionRoute | null,
 ): CommandPaletteCommand[] {
   return versions.map(version => ({
     id: `version:${version}`,
@@ -28,13 +31,13 @@ function createVersionCommands(
     keywords: [context.packageName, version, t('command_palette.groups.versions')],
     iconClass: 'i-lucide:tag',
     active: version === context.resolvedVersion,
-    to: urlPattern?.replace('{version}', version) ?? packageRoute(context.packageName, version),
+    to: routeForVersion?.(version) ?? packageRoute(context.packageName, version),
   }))
 }
 
 export function useCommandPaletteVersionCommands(
   context: MaybeRefOrGetter<CommandPalettePackageContext | null>,
-  urlPattern?: MaybeRefOrGetter<string | null | undefined>,
+  routeForVersion?: MaybeRef<CommandPaletteVersionRoute | null | undefined>,
 ) {
   const { t } = useI18n()
 
@@ -43,7 +46,7 @@ export function useCommandPaletteVersionCommands(
       const resolvedContext = toValue(context)
       if (!resolvedContext?.resolvedVersion) return []
 
-      return createVersionCommands(resolvedContext, t, undefined, toValue(urlPattern))
+      return createVersionCommands(resolvedContext, t, undefined, unref(routeForVersion))
     }),
   )
 
@@ -58,6 +61,6 @@ export function useCommandPaletteVersionCommands(
       satisfies(version, semverRange, { includePrerelease: true }),
     )
 
-    return createVersionCommands(resolvedContext, t, matchingVersions, toValue(urlPattern))
+    return createVersionCommands(resolvedContext, t, matchingVersions, unref(routeForVersion))
   })
 }

app/pages/diff/[[org]]/[packageName]/v/[versionRange].vue

@@ -116,19 +116,19 @@ const latestVersionDetailed = computed(() => {
   return pkg.value.versions[latestTag] ?? null
 })
 
-const normalizeRoutePath = (routeLocation: RouteLocationRaw) => {
-  const resolvedHref = router.resolve(routeLocation).href
-  return resolvedHref.replace(/%7B/g, '{').replace(/%7D/g, '}')
+function diffVersionUrlPattern(from: string, to: string) {
+  const { org, packageName: name } = route.params
+  return `/diff/${org ? `${org}/` : ''}${name}/v/${from}...${to}`
 }
 
-const fromVersionUrlPattern = computed(() => {
-  return normalizeRoutePath(diffRoute(packageName.value, '{version}', toVersion.value))
-})
-const toVersionUrlPattern = computed(() => {
-  return normalizeRoutePath(diffRoute(packageName.value, fromVersion.value, '{version}'))
-})
+const fromVersionUrlPattern = computed(() => diffVersionUrlPattern('{version}', toVersion.value))
+const toVersionUrlPattern = computed(() => diffVersionUrlPattern(fromVersion.value, '{version}'))
+
+function fromVersionRoute(version: string): RouteLocationRaw {
+  return diffRoute(packageName.value, version, toVersion.value)
+}
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, fromVersionUrlPattern)
+useCommandPaletteVersionCommands(commandPalettePackageContext, fromVersionRoute)
 
 useSeoMeta({
   title: () => {

app/pages/package-code/[[org]]/[packageName]/v/[version]/[...filePath].vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { RouteLocationRaw } from 'vue-router'
 import type { CommandPaletteContextCommandInput } from '~/types/command-palette'
 
 // Maximum file size we'll try to load (500KB) - must match server
@@ -86,7 +87,16 @@ const versionUrlPattern = computed(() =>
   }),
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+function codeVersionRoute(nextVersion: string): RouteLocationRaw {
+  return getCodeUrl({
+    org: route.params.org,
+    packageName: route.params.packageName,
+    version: nextVersion,
+    filePath: filePath.value,
+  })
+}
+
+useCommandPaletteVersionCommands(commandPalettePackageContext, codeVersionRoute)
 
 // Fetch file tree
 const { data: fileTree, status: treeStatus } = useFetch<PackageFileTreeResponse>(

app/pages/package-docs/[...path].vue

@@ -1,4 +1,5 @@
 <script setup lang="ts">
+import type { RouteLocationRaw } from 'vue-router'
 import { setResponseHeader } from 'h3'
 
 definePageMeta({
@@ -123,7 +124,19 @@ const versionUrlPattern = computed(
   () => `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`,
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+function docsVersionRoute(version: string): RouteLocationRaw {
+  const name = pkg.value?.name || packageName.value
+  const [firstSegment = name, ...remainingSegments] = name.split('/')
+
+  return {
+    name: 'docs',
+    params: {
+      path: [firstSegment, ...remainingSegments, 'v', version],
+    },
+  }
+}
+
+useCommandPaletteVersionCommands(commandPalettePackageContext, docsVersionRoute)
 
 const pageTitle = computed(() => {
   if (!packageName.value) return t('package.docs.page_title')

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

@@ -487,7 +487,9 @@ const versionUrlPattern = computed(
   () => `/package/${pkg.value?.name || packageName.value}/v/{version}`,
 )
 
-useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
+useCommandPaletteVersionCommands(commandPalettePackageContext, version =>
+  packageRoute(packageName.value, version),
+)
 
 const dependencyCount = computed(() => getDependencyCount(displayVersion.value))
 

test/nuxt/composables/use-command-palette-commands.spec.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { computed, defineComponent, h, ref, watchEffect, type Ref } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
 import { mockNuxtImport, mountSuspended } from '@nuxt/test-utils/runtime'
 import { downloadPackageTarball } from '~/utils/package-download'
 import type {
@@ -49,7 +50,7 @@ async function captureCommandPalette(options?: {
   npmUser?: string | null
   atprotoHandle?: string | null
   packageContext?: CommandPalettePackageContext | null
-  versionUrlPattern?: string
+  versionRoute?: (version: string) => RouteLocationRaw
   contextCommands?: CommandPaletteContextCommandInput[]
 }) {
   const groupedCommands = ref<CommandPaletteCommandGroup[]>([]) as Ref<CommandPaletteCommandGroup[]>
@@ -76,10 +77,7 @@ async function captureCommandPalette(options?: {
       if (options?.packageContext) {
         setPackageContext(options.packageContext)
         useCommandPalettePackageCommands(() => options.packageContext ?? null)
-        useCommandPaletteVersionCommands(
-          () => options.packageContext ?? null,
-          () => options.versionUrlPattern,
-        )
+        useCommandPaletteVersionCommands(() => options.packageContext ?? null, options.versionRoute)
       } else {
         clearPackageContext()
       }
@@ -345,7 +343,7 @@ describe('useCommandPaletteCommands', () => {
     wrapper.unmount()
   })
 
-  it('keeps version navigation on the current surface when a version URL pattern is provided', async () => {
+  it('keeps version navigation on the current surface when a version route builder is provided', async () => {
     const { wrapper, flatCommands, routePath } = await captureCommandPalette({
       route: '/package-code/vue/v/3.4.2/src/index.ts',
       packageContext: {
@@ -354,7 +352,7 @@ describe('useCommandPaletteCommands', () => {
         latestVersion: '4.0.0',
         versions: ['4.0.0', '3.5.0', '3.4.2'],
       },
-      versionUrlPattern: '/package-code/vue/v/{version}/src/index.ts',
+      versionRoute: version => `/package-code/vue/v/${version}/src/index.ts`,
     })
 
     const versionCommand = flatCommands.value.find(command => command.id === 'version:3.5.0')