Support scroll: false for Link component for app router (#51869)

### What Support `scroll={false}` for Link component in app router. This can be used when you don't need to scroll back to top again when route url changes. For instance hash query changes, if you want to keep the scrolling as it is, you can use this option. ### How Handling the `scroll` option in navigation reducer on client side. Fixes #50105 Fixes NEXT-1377 --------- Co-authored-by: Jiachi Liu <inbox@huozhi.im>
vercel · Jul 4, 2023 · 5d06b79 · 5d06b79
1 parent b8ae8d2
commit 5d06b79
Show file tree

Hide file tree

Showing 12 changed files with 308 additions and 26 deletions.
diff --git a/packages/next/src/client/components/app-router.tsx b/packages/next/src/client/components/app-router.tsx
@@ -231,11 +231,7 @@ function Router({
   )
 
   const navigate: RouterNavigate = useCallback(
-    (
-      href: string,
-      navigateType: 'push' | 'replace',
-      forceOptimisticNavigation: boolean
-    ) => {
+    (href, navigateType, forceOptimisticNavigation, shouldScroll) => {
       const url = new URL(addBasePath(href), location.href)
 
       return dispatch({
@@ -244,6 +240,7 @@ function Router({
         isExternalUrl: isExternalURL(url),
         locationSearch: location.search,
         forceOptimisticNavigation,
+        shouldScroll: shouldScroll ?? true,
         navigateType,
         cache: createEmptyCacheNode(),
         mutable: {},
@@ -296,12 +293,22 @@ function Router({
       },
       replace: (href, options = {}) => {
         startTransition(() => {
-          navigate(href, 'replace', Boolean(options.forceOptimisticNavigation))
+          navigate(
+            href,
+            'replace',
+            Boolean(options.forceOptimisticNavigation),
+            options.scroll ?? true
+          )
         })
       },
       push: (href, options = {}) => {
         startTransition(() => {
-          navigate(href, 'push', Boolean(options.forceOptimisticNavigation))
+          navigate(
+            href,
+            'push',
+            Boolean(options.forceOptimisticNavigation),
+            options.scroll ?? true
+          )
         })
       },
       refresh: () => {

diff --git a/packages/next/src/client/components/router-reducer/handle-mutable.ts b/packages/next/src/client/components/router-reducer/handle-mutable.ts
@@ -9,6 +9,9 @@ export function handleMutable(
   state: ReadonlyReducerState,
   mutable: Mutable
 ): ReducerState {
+  // shouldScroll is true by default, can override to false.
+  const shouldScroll = mutable.shouldScroll ?? true
+
   return {
     buildId: state.buildId,
     // Set href.
@@ -30,19 +33,25 @@ export function handleMutable(
     },
     // All navigation requires scroll and focus management to trigger.
     focusAndScrollRef: {
-      apply:
-        mutable?.scrollableSegments !== undefined
+      apply: shouldScroll
+        ? mutable?.scrollableSegments !== undefined
           ? true
-          : state.focusAndScrollRef.apply,
-      hashFragment:
-        // Empty hash should trigger default behavior of scrolling layout into view.
-        // #top is handled in layout-router.
-        mutable.hashFragment && mutable.hashFragment !== ''
+          : state.focusAndScrollRef.apply
+        : // If shouldScroll is false then we should not apply scroll and focus management.
+          false,
+      hashFragment: shouldScroll
+        ? // Empty hash should trigger default behavior of scrolling layout into view.
+          // #top is handled in layout-router.
+          mutable.hashFragment && mutable.hashFragment !== ''
           ? // Remove leading # and decode hash to make non-latin hashes work.
             decodeURIComponent(mutable.hashFragment.slice(1))
-          : state.focusAndScrollRef.hashFragment,
-      segmentPaths:
-        mutable?.scrollableSegments ?? state.focusAndScrollRef.segmentPaths,
+          : state.focusAndScrollRef.hashFragment
+        : // If shouldScroll is false then we should not apply scroll and focus management.
+          null,
+      segmentPaths: shouldScroll
+        ? mutable?.scrollableSegments ?? state.focusAndScrollRef.segmentPaths
+        : // If shouldScroll is false then we should not apply scroll and focus management.
+          [],
     },
     // Apply cache.
     cache: mutable.cache ? mutable.cache : state.cache,

diff --git a/packages/next/src/client/components/router-reducer/reducers/navigate-reducer.test.tsx b/packages/next/src/client/components/router-reducer/reducers/navigate-reducer.test.tsx
@@ -3,6 +3,7 @@ import type { fetchServerResponse as fetchServerResponseType } from '../fetch-se
 import type { FlightData } from '../../../../server/app-render/types'
 
 const buildId = 'development'
+
 const flightData: FlightData = [
   [
     'children',
@@ -58,6 +59,9 @@ jest.mock('../fetch-server-response', () => {
     fetchServerResponse: (
       url: URL
     ): ReturnType<typeof fetchServerResponseType> => {
+      if (url.pathname === '/linking' && url.hash === '#hash') {
+        return Promise.resolve(['', undefined])
+      }
       if (url.pathname === '/linking/about') {
         return Promise.resolve([flightData, undefined])
       }
@@ -174,6 +178,7 @@ describe('navigateReducer', () => {
       isExternalUrl: false,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -362,6 +367,7 @@ describe('navigateReducer', () => {
       isExternalUrl: false,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -555,6 +561,7 @@ describe('navigateReducer', () => {
       isExternalUrl,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -717,6 +724,7 @@ describe('navigateReducer', () => {
       isExternalUrl,
       locationSearch: '',
       navigateType: 'replace',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -876,6 +884,7 @@ describe('navigateReducer', () => {
       isExternalUrl: false,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: true,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -977,6 +986,169 @@ describe('navigateReducer', () => {
     expect(newState).toMatchObject(expectedState)
   })
 
+  it('should apply navigation for scroll', async () => {
+    const initialTree = getInitialRouterStateTree()
+    const initialCanonicalUrl = '/linking'
+    const children = (
+      <html>
+        <head></head>
+        <body>Root layout</body>
+      </html>
+    )
+    const initialParallelRoutes: CacheNode['parallelRoutes'] = new Map([
+      [
+        'children',
+        new Map([
+          [
+            'linking',
+            {
+              status: CacheStates.READY,
+              parallelRoutes: new Map([
+                [
+                  'children',
+                  new Map([
+                    [
+                      '__PAGE__',
+                      {
+                        status: CacheStates.READY,
+                        data: null,
+                        subTreeData: <>Linking page</>,
+                        parallelRoutes: new Map(),
+                      },
+                    ],
+                  ]),
+                ],
+              ]),
+              data: null,
+              subTreeData: <>Linking layout level</>,
+            },
+          ],
+        ]),
+      ],
+    ])
+
+    const state = createInitialRouterState({
+      buildId,
+      initialTree,
+      initialHead: null,
+      initialCanonicalUrl,
+      children,
+      initialParallelRoutes,
+      isServer: false,
+      location: new URL('/linking', 'https://localhost') as any,
+    })
+
+    const state2 = createInitialRouterState({
+      buildId,
+      initialTree,
+      initialHead: null,
+      initialCanonicalUrl,
+      children,
+      initialParallelRoutes,
+      isServer: false,
+      location: new URL('/linking#hash', 'https://localhost') as any,
+    })
+
+    const action: NavigateAction = {
+      type: ACTION_NAVIGATE,
+      url: new URL('/linking#hash', 'https://localhost'),
+      isExternalUrl: false,
+      locationSearch: '',
+      navigateType: 'push',
+      shouldScroll: false, // should not scroll
+      forceOptimisticNavigation: false,
+      cache: {
+        status: CacheStates.LAZY_INITIALIZED,
+        data: null,
+        subTreeData: null,
+        parallelRoutes: new Map(),
+      },
+      mutable: {},
+    }
+
+    await runPromiseThrowChain(() => navigateReducer(state, action))
+
+    const newState = await runPromiseThrowChain(() =>
+      navigateReducer(state2, action)
+    )
+
+    const expectedState: ReturnType<typeof navigateReducer> = {
+      buildId,
+      prefetchCache: new Map(),
+      pushRef: {
+        mpaNavigation: true,
+        pendingPush: true,
+      },
+      focusAndScrollRef: {
+        apply: false,
+        hashFragment: null,
+        segmentPaths: [],
+      },
+      canonicalUrl: '',
+      nextUrl: '/linking',
+      cache: {
+        status: CacheStates.READY,
+        data: null,
+        subTreeData: (
+          <html>
+            <head></head>
+            <body>Root layout</body>
+          </html>
+        ),
+        parallelRoutes: new Map([
+          [
+            'children',
+            new Map([
+              [
+                'linking',
+                {
+                  status: CacheStates.READY,
+                  parallelRoutes: new Map([
+                    [
+                      'children',
+                      new Map([
+                        [
+                          '__PAGE__',
+                          {
+                            status: CacheStates.READY,
+                            // Real promise is not needed here.
+                            data: null,
+                            parallelRoutes: new Map(),
+                            subTreeData: <>Linking page</>,
+                          },
+                        ],
+                      ]),
+                    ],
+                  ]),
+                  // Real promise is not needed here.
+                  data: null,
+                  subTreeData: <>Linking layout level</>,
+                },
+              ],
+            ]),
+          ],
+        ]),
+      },
+      tree: [
+        '',
+        {
+          children: [
+            'linking',
+            {
+              children: ['__PAGE__', {}],
+            },
+          ],
+        },
+        // TODO-APP: optimistic tree is wrong
+        undefined,
+        undefined,
+        true,
+      ],
+    }
+
+    expect(newState).toMatchObject(expectedState)
+  })
+
   it('should apply navigation with prefetched data', async () => {
     const initialTree = getInitialRouterStateTree()
     const initialCanonicalUrl = '/linking'
@@ -1060,6 +1232,7 @@ describe('navigateReducer', () => {
       isExternalUrl: false,
       navigateType: 'push',
       locationSearch: '',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,
@@ -1342,6 +1515,7 @@ describe('navigateReducer', () => {
       isExternalUrl: false,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,

diff --git a/packages/next/src/client/components/router-reducer/reducers/navigate-reducer.ts b/packages/next/src/client/components/router-reducer/reducers/navigate-reducer.ts
@@ -114,6 +114,7 @@ export function navigateReducer(
     cache,
     mutable,
     forceOptimisticNavigation,
+    shouldScroll,
   } = action
   const { pathname, hash } = url
   const href = createHrefFromUrl(url)
@@ -191,6 +192,7 @@ export function navigateReducer(
       mutable.patchedTree = optimisticTree
       mutable.pendingPush = pendingPush
       mutable.hashFragment = hash
+      mutable.shouldScroll = shouldScroll
       mutable.scrollableSegments = []
       mutable.cache = temporaryCacheNode
       mutable.canonicalUrl = href
@@ -355,12 +357,13 @@ export function navigateReducer(
 
   mutable.previousTree = state.tree
   mutable.patchedTree = currentTree
-  mutable.scrollableSegments = scrollableSegments
   mutable.canonicalUrl = canonicalUrlOverride
     ? createHrefFromUrl(canonicalUrlOverride)
     : href
   mutable.pendingPush = pendingPush
+  mutable.scrollableSegments = scrollableSegments
   mutable.hashFragment = hash
+  mutable.shouldScroll = shouldScroll
 
   return handleMutable(state, mutable)
 }
diff --git a/packages/next/src/client/components/router-reducer/reducers/server-patch-reducer.test.tsx b/packages/next/src/client/components/router-reducer/reducers/server-patch-reducer.test.tsx
@@ -502,6 +502,7 @@ describe('serverPatchReducer', () => {
       isExternalUrl: false,
       locationSearch: '',
       navigateType: 'push',
+      shouldScroll: true,
       forceOptimisticNavigation: false,
       cache: {
         status: CacheStates.LAZY_INITIALIZED,