feat: add navigation-api router

package.json

@@ -31,6 +31,7 @@
     "postinstall": "simple-git-hooks"
   },
   "devDependencies": {
+    "@types/dom-navigation": "^1.0.6",
     "@vitest/coverage-v8": "^2.1.9",
     "@vitest/ui": "^2.1.9",
     "brotli": "^1.3.3",
@@ -44,9 +45,9 @@
     "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.13",
+    "typedoc-plugin-markdown": "^4.8.1",
+    "typescript": "~5.8.2",
     "vitest": "^2.1.9"
   },
   "simple-git-hooks": {

packages/router/add-dts-module-augmentation.mjs

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs/promises'
+
+async function patchVueRouterDts() {
+  const content = await fs.readFile('./src/globalExtensions.ts', {
+    encoding: 'utf-8',
+  })
+  const moduleAugmentationIdx = content.indexOf('/**')
+  if (moduleAugmentationIdx === -1) {
+    throw new Error(
+      'Cannot find module augmentation in globalExtensions.ts, first /** comment is expected to start module augmentation'
+    )
+  }
+  const targetContent = await fs.readFile('./dist/vue-router.d.ts', {
+    encoding: 'utf-8',
+  })
+  await fs.writeFile(
+    './dist/vue-router.d.ts',
+    `${targetContent}
+${content.slice(moduleAugmentationIdx)}`,
+    { encoding: 'utf8' }
+  )
+}
+
+patchVueRouterDts()

packages/router/package.json

@@ -91,7 +91,7 @@
     "dev": "vitest --ui",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 1",
     "build": "rimraf dist && rollup -c rollup.config.mjs",
-    "build:dts": "api-extractor run --local --verbose && tail -n +10 src/globalExtensions.ts >> dist/vue-router.d.ts",
+    "build:dts": "api-extractor run --local --verbose && node ./add-dts-module-augmentation.mjs",
     "build:playground": "vue-tsc --noEmit && vite build --config playground/vite.config.ts",
     "build:e2e": "vue-tsc --noEmit && vite build --config e2e/vite.config.mjs",
     "build:size": "pnpm run build && rollup -c size-checks/rollup.config.mjs",
@@ -117,12 +117,13 @@
     "@vue/devtools-api": "^6.6.4"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.48.0",
+    "@microsoft/api-extractor": "^7.52.13",
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-commonjs": "^25.0.8",
     "@rollup/plugin-node-resolve": "^15.3.1",
     "@rollup/plugin-replace": "^5.0.7",
     "@rollup/plugin-terser": "^0.4.4",
+    "@types/dom-navigation": "^1.0.6",
     "@types/jsdom": "^21.1.7",
     "@types/nightwatch": "^2.3.32",
     "@vitejs/plugin-vue": "^5.2.3",

packages/router/src/RouterView.ts

@@ -30,6 +30,7 @@ import {
 import { assign, isArray, isBrowser } from './utils'
 import { warn } from './warning'
 import { isSameRouteRecord } from './location'
+import { TransitionMode, transitionModeKey } from './transition'
 
 export interface RouterViewProps {
   name?: string
@@ -62,6 +63,7 @@ export const RouterViewImpl = /*#__PURE__*/ defineComponent({
     __DEV__ && warnDeprecatedUsage()
 
     const injectedRoute = inject(routerViewLocationKey)!
+    const transitionMode = inject(transitionModeKey, 'auto')!
     const routeToDisplay = computed<RouteLocationNormalizedLoaded>(
       () => props.route || injectedRoute.value
     )
@@ -145,7 +147,11 @@ export const RouterViewImpl = /*#__PURE__*/ defineComponent({
         matchedRoute && matchedRoute.components![currentName]
 
       if (!ViewComponent) {
-        return normalizeSlot(slots.default, { Component: ViewComponent, route })
+        return normalizeSlot(slots.default, {
+          Component: ViewComponent,
+          route,
+          transitionMode,
+        })
       }
 
       // props from route configuration
@@ -199,8 +205,11 @@ export const RouterViewImpl = /*#__PURE__*/ defineComponent({
       return (
         // pass the vnode to the slot as a prop.
         // h and <component :is="..."> both accept vnodes
-        normalizeSlot(slots.default, { Component: component, route }) ||
-        component
+        normalizeSlot(slots.default, {
+          Component: component,
+          route,
+          transitionMode,
+        }) || component
       )
     }
   },
@@ -228,9 +237,11 @@ export const RouterView = RouterViewImpl as unknown as {
       default?: ({
         Component,
         route,
+        transitionMode,
       }: {
         Component: VNode
         route: RouteLocationNormalizedLoaded
+        transitionMode: TransitionMode
       }) => VNode[]
     }
   }

packages/router/src/focus.ts

@@ -0,0 +1,109 @@
+import type { RouteLocationNormalized } from './typed-routes'
+import type { Router, RouterOptions } from './router'
+import { nextTick } from 'vue'
+
+export function enableFocusManagement(router: Router) {
+  // navigation-api router will handle this for us
+  if (router.name !== 'legacy') {
+    return
+  }
+
+  const { handleFocus, clearFocusTimeout } = createFocusManagementHandler()
+
+  const unregisterBeforeEach = router.beforeEach(() => {
+    clearFocusTimeout()
+  })
+
+  const unregister = router.afterEach(async to => {
+    const focusManagement =
+      to.meta.focusManagement ?? router.options.focusManagement
+
+    // user wants manual focus
+    if (focusManagement === false) return
+
+    let selector = '[autofocus], body'
+
+    if (focusManagement === true) {
+      selector = '[autofocus],h1,main,body'
+    } else if (
+      typeof focusManagement === 'string' &&
+      focusManagement.length > 0
+    ) {
+      selector = focusManagement
+    }
+
+    // ensure DOM is updated, enqueuing a microtask before handling focus
+    await nextTick()
+
+    handleFocus(selector)
+  })
+
+  return () => {
+    clearFocusTimeout()
+    unregisterBeforeEach()
+    unregister()
+  }
+}
+
+export function prepareFocusReset(
+  to: RouteLocationNormalized,
+  routerFocusManagement?: RouterOptions['focusManagement']
+) {
+  let focusReset: 'after-transition' | 'manual' = 'after-transition'
+  let selector: string | undefined
+
+  const focusManagement = to.meta.focusManagement ?? routerFocusManagement
+  if (focusManagement === false) {
+    focusReset = 'manual'
+  }
+  if (focusManagement === true) {
+    focusReset = 'manual'
+    selector = '[autofocus],h1,main,body'
+  } else if (typeof focusManagement === 'string') {
+    focusReset = 'manual'
+    selector = focusManagement || '[autofocus],h1,main,body'
+  }
+
+  return [focusReset, selector] as const
+}
+
+export function createFocusManagementHandler() {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined
+
+  return {
+    handleFocus: (selector: string) => {
+      clearTimeout(timeoutId)
+      requestAnimationFrame(() => {
+        timeoutId = handleFocusManagement(selector)
+      })
+    },
+    clearFocusTimeout: () => {
+      clearTimeout(timeoutId)
+    },
+  }
+}
+
+function handleFocusManagement(
+  selector: string
+): ReturnType<typeof setTimeout> {
+  return setTimeout(() => {
+    const target = document.querySelector<HTMLElement>(selector)
+    if (!target) return
+    target.focus({ preventScroll: true })
+    if (document.activeElement === target) return
+    // element has tabindex already, likely not focusable
+    // because of some other reason, bail out
+    if (target.hasAttribute('tabindex')) return
+    const restoreTabindex = () => {
+      target.removeAttribute('tabindex')
+      target.removeEventListener('blur', restoreTabindex)
+    }
+    // temporarily make the target element focusable
+    target.setAttribute('tabindex', '-1')
+    target.addEventListener('blur', restoreTabindex)
+    // try to focus again
+    target.focus({ preventScroll: true })
+    // remove tabindex and event listener if focus still not worked
+    if (document.activeElement !== target) restoreTabindex()
+  }, 150) // screen readers may need more time to react
+}

packages/router/src/history/common.ts

@@ -44,10 +44,50 @@ export enum NavigationDirection {
   unknown = '',
 }
 
+export interface NavigationApiEvent {
+  readonly navigationType: 'reload' | 'push' | 'replace' | 'traverse'
+  readonly canIntercept: boolean
+  readonly userInitiated: boolean
+  readonly hashChange: boolean
+  readonly hasUAVisualTransition: boolean
+  readonly destination: {
+    readonly url: string
+    readonly key: string | null
+    readonly id: string | null
+    readonly index: number
+    readonly sameDocument: boolean
+    getState(): unknown
+  }
+  readonly signal: AbortSignal
+  readonly formData: FormData | null
+  readonly downloadRequest: string | null
+  readonly info?: unknown
+
+  scroll(): void
+}
+
 export interface NavigationInformation {
   type: NavigationType
   direction: NavigationDirection
   delta: number
+  /**
+   * True if the navigation was triggered by the browser back button.
+   *
+   * Note: available only with the new Navigation API Router.
+   */
+  isBackBrowserButton?: boolean
+  /**
+   * True if the navigation was triggered by the browser forward button.
+   *
+   * Note: available only with the new Navigation API Router.
+   */
+  isForwardBrowserButton?: boolean
+  /**
+   * The native Navigation API Event.
+   *
+   * Note: available only with the new Navigation API Router.
+   */
+  navigationApiEvent?: NavigationApiEvent
 }
 
 export interface NavigationCallback {

packages/router/src/index.ts

@@ -138,7 +138,13 @@ export type {
 } from './typed-routes'
 
 export { createRouter } from './router'
+export { createNavigationApiRouter } from './navigation-api'
 export type { Router, RouterOptions, RouterScrollBehavior } from './router'
+export type { RouterApiOptions } from './navigation-api'
+export type { TransitionMode, RouterViewTransition } from './transition'
+export type { ModernRouterOptions } from './modern-router-factory'
+export { injectTransitionMode, transitionModeKey } from './transition'
+export { createModernRouter } from './modern-router-factory'
 
 export { NavigationFailureType, isNavigationFailure } from './errors'
 export type {
@@ -160,6 +166,7 @@ export type {
   UseLinkReturn,
 } from './RouterLink'
 export { RouterView } from './RouterView'
+export { isChangingPage } from './utils/routes'
 export type { RouterViewProps } from './RouterView'
 
 export type { TypesConfig } from './config'

packages/router/src/modern-router-factory.ts

@@ -0,0 +1,55 @@
+import type { Router } from './router'
+import type { RouterApiOptions } from './navigation-api'
+import type { TransitionMode } from './transition'
+import { createNavigationApiRouter } from './navigation-api'
+import { isBrowser } from './utils'
+
+export interface ModernRouterOptions {
+  /**
+   * Factory function that creates a legacy router instance.
+   * Typically: () => createRouter({@ history: createWebHistory(), routes })
+   */
+  legacy: {
+    factory: (transitionMode: TransitionMode) => Router
+  }
+  /**
+   * Options for the new Navigation API based router.
+   * If provided and the browser supports it, this will be used.
+   */
+  navigationApi?: {
+    options: RouterApiOptions
+  }
+  /**
+   * Enable Native View Transitions.
+   *
+   * @default undefined
+   */
+  viewTransition?: boolean
+}
+
+export function createModernRouter(options: ModernRouterOptions): Router {
+  let transitionMode: TransitionMode = 'auto'
+
+  if (
+    options?.viewTransition &&
+    typeof document !== 'undefined' &&
+    !!document.startViewTransition
+  ) {
+    transitionMode = 'view-transition'
+  }
+
+  const useNavigationApi =
+    options.navigationApi &&
+    isBrowser &&
+    typeof window !== 'undefined' &&
+    window.navigation
+
+  if (useNavigationApi) {
+    return createNavigationApiRouter(
+      options.navigationApi!.options,
+      transitionMode
+    )
+  } else {
+    return options.legacy.factory(transitionMode)
+  }
+}