Support scroll: false for Link component for app router

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: () => {

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,

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,

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)
 }

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,