docs(gatsby-react-router-scroll): Add documentation for scroll restor…

…ation options (#25450)

* docs(gatsby-react-router-scroll): Add documentation for scroll restoration options

* feat(gatsby): export useScrollRestoration from main package

* Update reach-router-and-gatsby.md

* Update packages/gatsby/index.d.ts

Co-authored-by: Aisha Blake <aisha@gatsbyjs.com>

* Rearrange scroll restoration docs

* chore: format

* Add links to scroll restoration page

* Fix doc link spelling

* Update docs/docs/scroll-restoration.md

Co-authored-by: Aisha Blake <aisha@gatsbyjs.com>
Co-authored-by: Aisha Blake <aisha.g.blake@gmail.com>
Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>

docs/docs/making-your-site-accessible.md

@@ -27,7 +27,7 @@ One of the most common features of every site is navigation. People should be ab
 
 That's why every Gatsby site aims to have an accessible navigation experience by default. Thanks to [@reach/router](https://reach.tech/router), a routing library for React, Gatsby handles page announcements for screen readers on page change. We're actively making improvements to this experience, and we [welcome your feedback](/accessibility-statement/).
 
-Since the [second major release](/blog/2018-09-17-gatsby-v2/), your Gatsby sites use `@reach/router` under the hood. While additional accessibility testing is always a good idea, the [Gatsby Link Component](/docs/gatsby-link/) wraps [@reach/router's Link component](https://reach.tech/router/api/Link) to improve accessibility without you having to think about it.
+Since the [second major release](/blog/2018-09-17-gatsby-v2/), your Gatsby sites use `@reach/router` under the hood. While additional accessibility testing is always a good idea, the [Gatsby Link Component](/docs/gatsby-link/) wraps [@reach/router's Link component](https://reach.tech/router/api/Link) to improve accessibility without you having to think about it. `@reach/router` also supports [scroll restoration](/docs/scroll-restoration).
 
 ### Gatsby builds HTML pages by default
 

docs/docs/reach-router-and-gatsby.md

@@ -11,6 +11,7 @@ The main reasons Gatsby uses `@reach/router` are:
 1. Preloading. You can read more about preloading in the docs for the [Gatsby Link API](https://www.gatsbyjs.org/docs/gatsby-link/).
 2. The [routing accessibility](https://reach.tech/router/accessibility) it provides.
 3. It supports [server rendering](https://reach.tech/router/server-rendering) which helps Gatsby build routed files at build time.
+4. It supports [scroll restoration](/docs/scroll-restoration), which allows Gatsby to better control pages' scroll position.
 
 With Gatsby, you will mostly be using the `<Link />` component provided by the `gatsby` package. The [`<Link />` API docs](https://www.gatsbyjs.org/docs/gatsby-link/) explain the relationship between `gatsby` `<Link />` and `@reach/router` `<Link />` very nicely:
 
@@ -23,4 +24,5 @@ Besides using the [`<Link />` API](https://www.gatsbyjs.org/docs/gatsby-link/) f
 ## Other resources
 
 - [Reach Router docs](https://reach.tech/router)
-- [Video about using @reach/router in a standalone project (not Gatsby)](https://www.youtube.com/watch?v=J1vsBrSUptA).
+- [Video about using @reach/router in a standalone project (not Gatsby)](https://www.youtube.com/watch?v=J1vsBrSUptA)
+- Gatsby documentation on [scroll restoration](/docs/scroll-restoration)

docs/docs/routing.md

@@ -59,6 +59,8 @@ In order to link between pages, you can use [`gatsby-link`](/docs/gatsby-link/).
 
 Alternatively, you can navigate between pages using standard `<a>` tags, but you won't get the benefit of prefetching in this case.
 
+Gatsby will handle scroll restoration for you in most cases. To track and restore scroll position in additional containers, you can [use the `useScrollRestoration` hook](/docs/scroll-restoration/).
+
 ## Creating authentication-gated links
 
 For pages dealing with sensitive information, or other dynamic behavior, you may want to handle that information server-side. Gatsby lets you create [client-only routes](/docs/client-only-routes-and-user-authentication) that live behind an authentication gate, ensuring that the information is only available to authorized users.

docs/docs/scroll-restoration.md

@@ -0,0 +1,43 @@
+---
+title: Scroll Restoration
+---
+
+Scroll restoration refers to the [`scrollRestoration`](https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration) property on the [`History`](https://developer.mozilla.org/en-US/docs/Web/API/History) API. This property allows restoring a user's scroll position when navigating to a new page.
+
+Gatsby will handle scroll restoration for you in most cases. However, when you render containers that have their own scroll values, those scroll positions are typically lost between page transitions. To solve that, users can use the `useScrollRestoration` hook or the (deprecated) `ScrollContainer` component in their code to tell Gatsby about scroll containers that we should track and restore.
+
+Here is an example of using the `useScrollRestoration` hook to render a list of countries in an overflow `ul` element.
+
+```jsx
+import { useScrollRestoration } from "gatsby";
+import countryList from "../utils/country-list";
+
+export default function PageComponent() {
+    const ulScrollRestoration = useScrollRestoration(`page-component-ul-list`)
+
+    return (
+        <ul style={{ height: 200, overflow: `auto` }} {...ulScrollRestoration}>
+            {countryList.map(country => <li>{country}</li>)
+        </ul>
+    );
+}
+```
+
+This is an example of using the (deprecated) `ScrollContainer` component with the same code.
+
+```jsx
+import { ScrollContainer } from "gatsby-react-router-scroll";
+import countryList from "../utils/country-list";
+
+export default class PageComponent extends React.Component {
+    render() {
+        return (
+            <ScrollContainer key="page-component-ul-list">
+                <ul style={{ height: 200, overflow: `auto` }}>
+                    {countryList.map(country => <li>{country}</li>)
+                </ul>
+            </ScrollContainer>
+        );
+    }
+}
+```

packages/gatsby/cache-dir/gatsby-browser-entry.js

@@ -9,6 +9,7 @@ import Link, {
   navigateTo,
   parsePath,
 } from "gatsby-link"
+import { useScrollRestoration } from "gatsby-react-router-scroll"
 import PageRenderer from "./public-page-renderer"
 import loader from "./loader"
 
@@ -107,6 +108,7 @@ export {
   push, // TODO replace for v3
   replace, // TODO remove replace for v3
   navigateTo, // TODO: remove navigateTo for v3
+  useScrollRestoration,
   StaticQueryContext,
   StaticQuery,
   PageRenderer,

packages/gatsby/index.d.ts

@@ -24,6 +24,13 @@ export {
   withAssetPrefix,
 } from "gatsby-link"
 
+export const useScrollRestoration: (
+  key: string
+) => {
+  ref: React.MutableRefObject<HTMLElement | undefined>
+  onScroll(): void
+}
+
 export const useStaticQuery: <TData = any>(query: any) => TData
 
 export const parsePath: (path: string) => WindowLocation
@@ -41,7 +48,7 @@ export const prefetchPathname: (path: string) => void
  * export default (props: PageProps) => {
  *
  * @example
- * // When adding types for both pageContext (represended by LocaleLookUpInfo) 
+ * // When adding types for both pageContext (represented by LocaleLookUpInfo)
  * // and GraphQL query data (represented by IndexQueryProps)
  *
  * import {PageProps} from "gatsby"

www/src/data/sidebars/doc-links.yaml

@@ -477,6 +477,8 @@
               items:
                 - title: "@reach/router and Gatsby"
                   link: /docs/reach-router-and-gatsby/
+                - title: "Scroll Restoration"
+                  link: /docs/scroll-restoration/
                 - title: Location Data from Props
                   link: /docs/location-data-from-props/
                 - title: Creating Dynamic Navigation