feat(nuxt): default router scroll behavior

docs/content/3.api/4.advanced/1.hooks.md

@@ -7,17 +7,18 @@
 
 Check the [app source code](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/app/nuxt.ts#L18) for all available hooks.
 
-Hook                   | Arguments         | Description
------------------------|-------------------|---------------
-`app:created`          | `vueApp`          | When initial `vueApp` instance is created
-`app:beforeMount`      | `vueApp`          | Same as `app:created`
-`app:mounted`          | `vueApp`          | When Vue app is initialized and mounted in browser
-`app:rendered`         | -                 | When SSR rendering is done
-`app:suspense:resolve` | `appComponent`    | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
-`page:start`           | `pageComponent`   | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) pending event
-`page:finish`          | `pageComponent`   | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
-`meta:register`        | `metaRenderers`   | (internal)
-`vue:setup`            | -                 | (internal)
+Hook                    | Arguments         | Description
+------------------------|-------------------|---------------
+`app:created`           | `vueApp`          | When initial `vueApp` instance is created
+`app:beforeMount`       | `vueApp`          | Same as `app:created`
+`app:mounted`           | `vueApp`          | When Vue app is initialized and mounted in browser
+`app:rendered`          | -                 | When SSR rendering is done
+`app:suspense:resolve`  | `appComponent`    | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
+`page:start`            | `pageComponent`   | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) pending event
+`page:finish`           | `pageComponent`   | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
+`page:transition:finish`| `pageComponent`   | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) event
+`meta:register`         | `metaRenderers`   | (internal)
+`vue:setup`             | -                 | (internal)
 
 # Nuxt Hooks (build time)
 

packages/nuxt/src/app/nuxt.ts

@@ -30,6 +30,7 @@ export interface RuntimeNuxtHooks {
   'app:data:refresh': (keys?: string[]) => HookResult
   'page:start': (Component?: VNode) => HookResult
   'page:finish': (Component?: VNode) => HookResult
+  'page:transition:finish': (Component?: VNode) => HookResult
   'meta:register': (metaRenderers: Array<(nuxt: NuxtApp) => NuxtMeta | Promise<NuxtMeta>>) => HookResult
   'vue:setup': () => void
   'vue:error': (...args: Parameters<Parameters<typeof onErrorCaptured>[0]>) => HookResult

packages/nuxt/src/pages/module.ts

@@ -84,6 +84,7 @@ export default defineNuxtModule({
       filename: 'router.options.mjs',
       getContents: async () => {
         // Check for router options
+        const defaultOptsFile = resolve(distDir, 'pages/routing/default-router.options')
         const routerOptionsFiles = (await Promise.all(nuxt.options._layers.map(
           async layer => await findPath(resolve(layer.config.srcDir, 'app/router.options'))
         ))).filter(Boolean)
@@ -93,8 +94,11 @@ export default defineNuxtModule({
 
         return [
           ...routerOptionsFiles.map((file, index) => genImport(file, `routerOptions${index}`)),
+          defaultOptsFile ? genImport(defaultOptsFile, 'defaultOptions') : '',
+
           `const configRouterOptions = ${configRouterOptions}`,
           'export default {',
+          '...(defaultOptions || {}),',
           '...configRouterOptions,',
           // We need to reverse spreading order to respect layers priority
           ...routerOptionsFiles.map((_, index) => `...routerOptions${index},`).reverse(),

packages/nuxt/src/pages/routing/default-router.options.ts

@@ -0,0 +1,60 @@
+import type { RouterConfig } from '@nuxt/schema'
+import { nextTick } from 'vue'
+import { useNuxtApp } from '#app'
+
+// https://router.vuejs.org/api/#routeroptions
+export default <RouterConfig>{
+  scrollBehavior (to, from, savedPosition) {
+    const nuxtApp = useNuxtApp()
+    // If the returned position is falsy or an empty object, will retain current scroll position
+    let position
+    const isRouteChanged = to !== from
+
+    // savedPosition is only available for popstate navigations (back button)
+    if (savedPosition) {
+      position = savedPosition
+    } else if (isRouteChanged) {
+      position = { left: 0, top: 0 }
+    }
+
+    // hash routes on the same page, no page hook is fired so resolve here
+    if (to.path === from.path) {
+      if (from.hash && !to.hash) {
+        return { left: 0, top: 0 }
+      } else if (to.hash) {
+        return {
+          el: to.hash,
+          top: getHashElementScrollMarginTop()
+        }
+      }
+    }
+
+    // if either to or from has no transition then wait for page:finish
+    const hasTransition = to.meta.pageTransition !== false && from.meta.pageTransition !== false
+    const hookAwait = hasTransition ? 'page:transition:finish' : 'page:finish'
+
+    function getHashElementScrollMarginTop () {
+      // vue-router does not incorporate scroll-margin-top on its own.
+      const elem = document.querySelector(to.hash)
+
+      if (elem) {
+        return parseFloat(getComputedStyle(elem).scrollMarginTop)
+      }
+      return 0
+    }
+
+    return new Promise((resolve) => {
+      nuxtApp.hooks.hookOnce(hookAwait, async () => {
+        await nextTick()
+
+        if (to.hash) {
+          position = {
+            el: to.hash,
+            top: getHashElementScrollMarginTop()
+          }
+        }
+        resolve(position)
+      })
+    })
+  }
+}

packages/nuxt/src/pages/runtime/page.ts

@@ -1,4 +1,4 @@
-import { defineComponent, h, inject, provide, Suspense, Transition } from 'vue'
+import { defineComponent, h, inject, provide, Suspense, Transition, nextTick } from 'vue'
 import { RouteLocationNormalizedLoaded, RouterView } from 'vue-router'
 
 import { generateRouteKey, RouterViewSlotProps, wrapInKeepAlive } from './utils'
@@ -21,17 +21,39 @@ export default defineComponent({
     const isNested = inject(isNestedKey, false)
     provide(isNestedKey, true)
 
+    function getTransitionProps (routeProps: RouterViewSlotProps) {
+      const metaTransition = routeProps.route.meta.pageTransition
+      const onAfterLeave = () => {
+        nuxtApp.callHook('page:transition:finish', routeProps.Component)
+      }
+
+      if (typeof metaTransition === 'boolean') {
+        return metaTransition && {
+          ...defaultPageTransition,
+          onAfterLeave
+        }
+      } else {
+        return {
+          ...defaultPageTransition,
+          ...(metaTransition || {}),
+          onAfterLeave
+        }
+      }
+    }
+
     return () => {
       return h(RouterView, {}, {
         default: (routeProps: RouterViewSlotProps) => routeProps.Component &&
-            _wrapIf(Transition, routeProps.route.meta.pageTransition ?? defaultPageTransition,
+            _wrapIf(Transition, getTransitionProps(routeProps),
               wrapInKeepAlive(routeProps.route.meta.keepalive,
                 isNested && nuxtApp.isHydrating
                   // Include route children in parent suspense
                   ? h(routeProps.Component, { key: generateRouteKey(props.pageKey, routeProps) } as {})
                   : h(Suspense, {
                     onPending: () => nuxtApp.callHook('page:start', routeProps.Component),
-                    onResolve: () => nuxtApp.callHook('page:finish', routeProps.Component)
+                    onResolve: () => {
+                      nextTick(() => nuxtApp.callHook('page:finish', routeProps.Component))
+                    }
                   }, { default: () => h(routeProps.Component, { key: generateRouteKey(props.pageKey, routeProps) } as {}) })
               )).default()
       })