feat(nuxt): default router scroll behavior

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

@@ -6,22 +6,23 @@
 
 Check the [app source code](https://github.com/nuxt/framework/blob/main/packages/nuxt/src/app/nuxt.ts#L24) for all available hooks.
 
-Hook                   | Arguments           | Environment     | Description
------------------------|---------------------|-----------------|-------------
-`app:created`          | `vueApp`            | Server & Client | Called when initial `vueApp` instance is created.
-`app:error`            | `err`               | Server & Client | Called when a fatal error occurs.
-`app:error:cleared`    | `{ redirect? }`     | Server & Client | Called when a fatal error occurs.
-`app:data:refresh`     | `keys?`             | Server & Client | (internal)
-`meta:register`        | `metaRenderers`     | Server & Client | (internal)
-`vue:setup`            | -                   | Server & Client | (internal)
-`vue:error`            | `err, target, info` | Server & Client | Called when a vue error propages to the root component. [Learn More](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
-`app:rendered`         | `renderContext`     | Server          | Called when SSR rendering is done.
-`app:redirected`       | -                   | Server          | Called before SSR redirection.
-`app:beforeMount`      | `vueApp`            | Client          | Called before mounting the app, called only on client side.
-`app:mounted`          | `vueApp`            | Client          | Called when Vue app is initialized and mounted in browser.
-`app:suspense:resolve` | `appComponent`      | Client          | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
-`page:start`           | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) pending event.
-`page:finish`          | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event.
+Hook                    | Arguments           | Environment     | Description
+------------------------|---------------------|-----------------|-------------
+`app:created`           | `vueApp`            | Server & Client | Called when initial `vueApp` instance is created.
+`app:error`             | `err`               | Server & Client | Called when a fatal error occurs.
+`app:error:cleared`     | `{ redirect? }`     | Server & Client | Called when a fatal error occurs.
+`app:data:refresh`      | `keys?`             | Server & Client | (internal)
+`meta:register`         | `metaRenderers`     | Server & Client | (internal)
+`vue:setup`             | -                   | Server & Client | (internal)
+`vue:error`             | `err, target, info` | Server & Client | Called when a vue error propages to the root component. [Learn More](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured).
+`app:rendered`          | `renderContext`     | Server          | Called when SSR rendering is done.
+`app:redirected`        | -                   | Server          | Called before SSR redirection.
+`app:beforeMount`       | `vueApp`            | Client          | Called before mounting the app, called only on client side.
+`app:mounted`           | `vueApp`            | Client          | Called when Vue app is initialized and mounted in browser.
+`app:suspense:resolve`  | `appComponent`      | Client          | On [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event
+`page:start`            | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) pending event.
+`page:finish`           | `pageComponent?`    | Client          | Called on [Suspense](https://vuejs.org/guide/built-ins/suspense.html#suspense) resolved event.
+`page:transition:finish`| `pageComponent?`    | Client          | After page transition [onAfterLeave](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks) event.
 
 # Nuxt Hooks (build time)
 

packages/nuxt/src/app/nuxt.ts

@@ -33,6 +33,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

@@ -133,6 +133,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)
@@ -142,8 +143,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,6 +1,5 @@
-import { computed, DefineComponent, defineComponent, h, inject, provide, reactive, Suspense, Transition } from 'vue'
+import { computed, DefineComponent, defineComponent, h, inject, nextTick, provide, reactive, Suspense, Transition } from 'vue'
 import { RouteLocation, RouteLocationNormalized, RouteLocationNormalizedLoaded, RouterView } from 'vue-router'
-
 import { generateRouteKey, RouterViewSlotProps, wrapInKeepAlive } from './utils'
 import { useNuxtApp } from '#app'
 import { _wrapIf } from '#app/components/utils'
@@ -28,20 +27,42 @@ 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, { name: props.name, route: props.route, ...attrs }, {
         default: (routeProps: RouterViewSlotProps) => {
           if (!routeProps.Component) { return }
 
           const key = generateRouteKey(props.pageKey, routeProps)
 
-          return _wrapIf(Transition, routeProps.route.meta.pageTransition ?? defaultPageTransition,
+          return _wrapIf(Transition, getTransitionProps(routeProps),
             wrapInKeepAlive(routeProps.route.meta.keepalive, isNested && nuxtApp.isHydrating
             // Include route children in parent suspense
               ? h(Component, { key, routeProps, pageKey: key } 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(Component, { key, routeProps, pageKey: key } as {}) })
             )).default()
         }