Custom Route Resolvers

.gitignore

@@ -17,3 +17,4 @@ local.log
 _selenium-server.log
 packages/*/LICENSE
 tracing_output
+tsconfig.vitest-temp.json

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vue/router-root",
   "private": true,
-  "packageManager": "pnpm@9.10.0",
+  "packageManager": "pnpm@10.13.1",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"
@@ -36,17 +36,17 @@
     "brotli": "^1.3.3",
     "chalk": "^5.4.1",
     "enquirer": "^2.4.1",
-    "execa": "^9.5.2",
+    "execa": "^9.6.0",
     "globby": "^14.1.0",
     "lint-staged": "^15.5.1",
     "minimist": "^1.2.8",
     "p-series": "^3.0.0",
     "prettier": "^3.5.3",
     "semver": "^7.7.1",
     "simple-git-hooks": "^2.13.0",
-    "typedoc": "^0.26.11",
-    "typedoc-plugin-markdown": "^4.2.10",
-    "typescript": "~5.6.3",
+    "typedoc": "^0.28.7",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "~5.8.3",
     "vitest": "^2.1.9"
   },
   "simple-git-hooks": {
@@ -71,7 +71,11 @@
         "@types/react",
         "react-dom"
       ]
-    }
+    },
+    "onlyBuiltDependencies": [
+      "chromedriver",
+      "geckodriver"
+    ]
   },
   "volta": {
     "node": "20.11.1"

packages/docs/.gitignore

@@ -1 +1,2 @@
 .vitepress/cache
+api

packages/docs/.vitepress/config/en.ts

@@ -1,4 +1,5 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -53,6 +54,12 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       // catch-all fallback
       '/': [
         {
@@ -179,13 +186,6 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/api/' }],
-        },
-      ],
     },
   },
 }

packages/docs/.vitepress/config/zh.ts

@@ -1,4 +1,6 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
+// TODO: rework the typedoc sidebar to include the /zh/ prefix
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -57,6 +59,12 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/zh/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       '/zh/': [
         {
           text: '设置',
@@ -186,13 +194,6 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/zh/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/zh/api/' }],
-        },
-      ],
     },
   },
 }

packages/docs/package.json

@@ -13,9 +13,10 @@
     "docs:preview": "vitepress preview ."
   },
   "dependencies": {
-    "simple-git": "^3.27.0",
-    "vitepress": "1.5.0",
-    "vitepress-translation-helper": "^0.2.1",
+    "simple-git": "^3.28.0",
+    "typedoc-vitepress-theme": "^1.1.2",
+    "vitepress": "1.6.3",
+    "vitepress-translation-helper": "^0.2.2",
     "vue-router": "workspace:*"
   }
 }

packages/docs/run-typedoc.mjs

@@ -1,15 +1,21 @@
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { createTypeDocApp } from './typedoc-markdown.mjs'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 createTypeDocApp({
-  name: 'API Documentation',
+  textContentMappings: {
+    'title.indexPage': 'API Reference',
+    'title.memberPage': '{name}',
+  },
   tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'),
+  // entryPointStrategy: 'packages',
   categorizeByGroup: true,
   githubPages: false,
-  disableSources: true, // some links are in node_modules and it's ugly
-  plugin: ['typedoc-plugin-markdown'],
+  readme: 'none',
+  indexFormat: 'table',
+  disableSources: true,
+  plugin: ['typedoc-plugin-markdown', 'typedoc-vitepress-theme'],
+  useCodeBlocks: true,
   entryPoints: [path.resolve(__dirname, '../router/src/index.ts')],
 }).then(app => app.build())

packages/docs/typedoc-markdown.mjs

@@ -1,13 +1,12 @@
 // @ts-check
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { Application, PageEvent, TSConfigReader } from 'typedoc'
+import { Application, TSConfigReader, PageEvent } from 'typedoc'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
+/** @satisfies {Partial<import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions>} */
 const DEFAULT_OPTIONS = {
-  // disableOutputCheck: true,
   cleanOutputDir: true,
   excludeInternal: false,
   readme: 'none',
@@ -72,7 +71,7 @@ export async function createTypeDocApp(config = {}) {
     if (project) {
       // Rendered docs
       try {
-        await app.generateDocs(project, options.out)
+        await app.generateOutputs(project)
         app.logger.info(`generated at ${options.out}.`)
       } catch (error) {
         app.logger.error(error)
@@ -88,6 +87,12 @@ export async function createTypeDocApp(config = {}) {
   }
 }
 
+/**
+ * checks if a path exists
+ *
+ * @async
+ * @param {string} path
+ */
 async function exists(path) {
   try {
     await fs.access(path)
@@ -108,7 +113,7 @@ async function exists(path) {
  */
 function prependYAML(contents, vars) {
   return contents
-    .replace(/^/, `${toYAML(vars)}\n\n`)
+    .replace(/^/, toYAML(vars) + '\n\n')
     .replace(/[\r\n]{3,}/g, '\n\n')
 }
 

packages/docs/typedoc.tsconfig.json

@@ -31,6 +31,6 @@
     "removeComments": false,
     "jsx": "preserve",
     "lib": ["esnext", "dom"],
-    "types": ["node"]
+    "types": ["vitest", "node", "vite/client"]
   }
 }

packages/playground/package.json

@@ -9,15 +9,15 @@
     "preview": "vite preview --port 4173"
   },
   "dependencies": {
-    "vue": "~3.5.13"
+    "vue": "~3.5.17"
   },
   "devDependencies": {
     "@types/node": "^20.17.31",
-    "@vitejs/plugin-vue": "^5.2.3",
-    "@vue/compiler-sfc": "~3.5.13",
-    "@vue/tsconfig": "^0.6.0",
-    "vite": "^5.4.18",
+    "@vitejs/plugin-vue": "^5.2.4",
+    "@vue/compiler-sfc": "~3.5.17",
+    "@vue/tsconfig": "^0.7.0",
+    "vite": "^5.4.19",
     "vue-router": "workspace:*",
-    "vue-tsc": "^2.2.10"
+    "vue-tsc": "^2.2.12"
   }
 }

packages/router/__tests__/location.spec.ts

@@ -134,26 +134,121 @@ describe('parseURL', () => {
     })
   })
 
-  it('parses ? after the hash', () => {
+  it('correctly parses a ? after the hash', () => {
     expect(parseURL('/foo#?a=one')).toEqual({
       fullPath: '/foo#?a=one',
       path: '/foo',
       hash: '#?a=one',
       query: {},
     })
-    expect(parseURL('/foo/#?a=one')).toEqual({
-      fullPath: '/foo/#?a=one',
+    expect(parseURL('/foo/?a=two#?a=one')).toEqual({
+      fullPath: '/foo/?a=two#?a=one',
       path: '/foo/',
       hash: '#?a=one',
+      query: { a: 'two' },
+    })
+  })
+
+  it('works with empty query', () => {
+    expect(parseURL('/foo?#hash')).toEqual({
+      fullPath: '/foo?#hash',
+      path: '/foo',
+      hash: '#hash',
+      query: {},
+    })
+    expect(parseURL('/foo#hash')).toEqual({
+      fullPath: '/foo#hash',
+      path: '/foo',
+      hash: '#hash',
+      query: {},
+    })
+    expect(parseURL('/foo?')).toEqual({
+      fullPath: '/foo?',
+      path: '/foo',
+      hash: '',
       query: {},
     })
+    expect(parseURL('/foo')).toEqual({
+      fullPath: '/foo',
+      path: '/foo',
+      hash: '',
+      query: {},
+    })
+  })
+
+  it('works with empty hash', () => {
+    expect(parseURL('/foo#')).toEqual({
+      fullPath: '/foo#',
+      path: '/foo',
+      hash: '#',
+      query: {},
+    })
+    expect(parseURL('/foo?#')).toEqual({
+      fullPath: '/foo?#',
+      path: '/foo',
+      hash: '#',
+      query: {},
+    })
+    expect(parseURL('/foo')).toEqual({
+      fullPath: '/foo',
+      path: '/foo',
+      hash: '',
+      query: {},
+    })
+  })
+
+  it('works with a relative paths', () => {
+    expect(parseURL('foo', '/parent/bar')).toEqual({
+      fullPath: '/parent/foo',
+      path: '/parent/foo',
+      hash: '',
+      query: {},
+    })
+    expect(parseURL('./foo', '/parent/bar')).toEqual({
+      fullPath: '/parent/foo',
+      path: '/parent/foo',
+      hash: '',
+      query: {},
+    })
+    expect(parseURL('../foo', '/parent/bar')).toEqual({
+      fullPath: '/foo',
+      path: '/foo',
+      hash: '',
+      query: {},
+    })
+    // cannot go below root
+    expect(parseURL('../../foo', '/parent/bar')).toEqual({
+      fullPath: '/foo',
+      path: '/foo',
+      hash: '',
+      query: {},
+    })
+
+    expect(parseURL('', '/parent/bar')).toEqual({
+      fullPath: '/parent/bar',
+      path: '/parent/bar',
+      hash: '',
+      query: {},
+    })
+    expect(parseURL('#foo', '/parent/bar')).toEqual({
+      fullPath: '/parent/bar#foo',
+      path: '/parent/bar',
+      hash: '#foo',
+      query: {},
+    })
+    expect(parseURL('?o=o', '/parent/bar')).toEqual({
+      fullPath: '/parent/bar?o=o',
+      path: '/parent/bar',
+      hash: '',
+      query: { o: 'o' },
+    })
   })
 
   it('calls parseQuery', () => {
     const parseQuery = vi.fn()
     originalParseURL(parseQuery, '/?é=é&é=a')
     expect(parseQuery).toHaveBeenCalledTimes(1)
-    expect(parseQuery).toHaveBeenCalledWith('é=é&é=a')
+    expect(parseQuery).toHaveBeenCalledWith('?é=é&é=a')
   })
 })
 

packages/router/__tests__/matcher/pathRanking.spec.ts

@@ -13,19 +13,9 @@ describe('Path ranking', () => {
       return comparePathParserScore(
         {
           score: a,
-          re: /a/,
-          // @ts-expect-error
-          stringify: v => v,
-          // @ts-expect-error
-          parse: v => v,
-          keys: [],
         },
         {
           score: b,
-          re: /a/,
-          stringify: v => v,
-          parse: v => v,
-          keys: [],
         }
       )
     }