From 97f5b29ce75a4ccf8e4abb5ceb18fda880795b83 Mon Sep 17 00:00:00 2001 From: Blaine Kasten Date: Wed, 1 Jul 2020 13:59:37 -0500 Subject: [PATCH 1/9] docs(gatsby-react-router-scroll): Add documentation for scroll restoration options --- docs/docs/reach-router-and-gatsby.md | 41 ++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/docs/reach-router-and-gatsby.md b/docs/docs/reach-router-and-gatsby.md index 390e56f37277f..158e2e4a07e20 100644 --- a/docs/docs/reach-router-and-gatsby.md +++ b/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. Scroll restoration. With Gatsby, you will mostly be using the `` component provided by the `gatsby` package. The [`` API docs](https://www.gatsbyjs.org/docs/gatsby-link/) explain the relationship between `gatsby` `` and `@reach/router` `` very nicely: @@ -20,6 +21,46 @@ With Gatsby, you will mostly be using the `` component provided by the ` Besides using the [`` API](https://www.gatsbyjs.org/docs/gatsby-link/) for linking between pages Gatsby generates, you can define your own client-side routes. See the [client only paths example](https://github.com/gatsbyjs/gatsby/tree/master/examples/client-only-paths) on how to use `` from `@reach/router` to make client routes work seamlessly together with your server routes. +## Scroll Restoration + +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 (deprecated) `ScrollContainer` component or `useScrollRestoration` hook in their code to tell Gatsby about scroll containers that we should track and restore. + +This is an example of using the ScrollContainer component to render a list of countries in an overflow `ul` element. + +```jsx +import { ScrollContainer } from "gatsby-react-router-scroll"; +import countryList from "../utils/country-list"; + +export default class PageComponent extends React.Component { + render() { + return ( + +
    + {countryList.map(country =>
  • {country}
    • ) +
+ + ); + } +} +``` + +Here is an example of using the `useScrollRestoration` hook with the same code. + +```jsx +import { useScrollRestoration } from "gatsby-react-router-scroll"; +import countryList from "../utils/country-list"; + +export default function PageComponent() { + const ulScrollRestoration = useScrollRestoration(`page-component-ul-list`) + + return ( + + ); +} +``` + ## Other resources - [Reach Router docs](https://reach.tech/router) From e39fe093a396de263a6f07772410de1f96733be6 Mon Sep 17 00:00:00 2001 From: Blaine Kasten Date: Wed, 1 Jul 2020 14:12:30 -0500 Subject: [PATCH 2/9] feat(gatsby): export useScrollRestoration from main package --- docs/docs/reach-router-and-gatsby.md | 2 +- packages/gatsby/cache-dir/gatsby-browser-entry.js | 2 ++ packages/gatsby/index.d.ts | 9 ++++++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/docs/reach-router-and-gatsby.md b/docs/docs/reach-router-and-gatsby.md index 158e2e4a07e20..0f22958768ce8 100644 --- a/docs/docs/reach-router-and-gatsby.md +++ b/docs/docs/reach-router-and-gatsby.md @@ -47,7 +47,7 @@ export default class PageComponent extends React.Component { Here is an example of using the `useScrollRestoration` hook with the same code. ```jsx -import { useScrollRestoration } from "gatsby-react-router-scroll"; +import { useScrollRestoration } from "gatsby"; import countryList from "../utils/country-list"; export default function PageComponent() { diff --git a/packages/gatsby/cache-dir/gatsby-browser-entry.js b/packages/gatsby/cache-dir/gatsby-browser-entry.js index 23f03a3088fa5..63fbe06f81eda 100644 --- a/packages/gatsby/cache-dir/gatsby-browser-entry.js +++ b/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, diff --git a/packages/gatsby/index.d.ts b/packages/gatsby/index.d.ts index 1ec387fc90c4c..b51333ccf6311 100644 --- a/packages/gatsby/index.d.ts +++ b/packages/gatsby/index.d.ts @@ -24,6 +24,13 @@ export { withAssetPrefix, } from "gatsby-link" +export const useScrollRestoration: ( + key: string +) => { + ref: React.MutableRefObject + onScroll(): void +} + export const useStaticQuery: (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 (represended by LocaleLookUpInfo) * // and GraphQL query data (represented by IndexQueryProps) * * import {PageProps} from "gatsby" From fb84a24463a9af9f33a89059b976f5624266abb3 Mon Sep 17 00:00:00 2001 From: Blaine Kasten Date: Wed, 1 Jul 2020 15:01:03 -0500 Subject: [PATCH 3/9] Update reach-router-and-gatsby.md --- docs/docs/reach-router-and-gatsby.md | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/docs/reach-router-and-gatsby.md b/docs/docs/reach-router-and-gatsby.md index 0f22958768ce8..758b220979f4b 100644 --- a/docs/docs/reach-router-and-gatsby.md +++ b/docs/docs/reach-router-and-gatsby.md @@ -23,9 +23,26 @@ Besides using the [`` API](https://www.gatsbyjs.org/docs/gatsby-link/) f ## Scroll Restoration -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 (deprecated) `ScrollContainer` component or `useScrollRestoration` hook in their code to tell Gatsby about scroll containers that we should track and restore. +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. -This is an example of using the ScrollContainer component to render a list of countries in an overflow `ul` element. +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 ( +
    + {countryList.map(country =>
  • {country}
    • ) +
+ ); +} +``` + +This is an example of using the (deprecated) ScrollContainer component with the same code. ```jsx import { ScrollContainer } from "gatsby-react-router-scroll"; @@ -44,23 +61,6 @@ export default class PageComponent extends React.Component { } ``` -Here is an example of using the `useScrollRestoration` hook with the same code. - -```jsx -import { useScrollRestoration } from "gatsby"; -import countryList from "../utils/country-list"; - -export default function PageComponent() { - const ulScrollRestoration = useScrollRestoration(`page-component-ul-list`) - - return ( -
    - {countryList.map(country =>
  • {country}
    • ) -
- ); -} -``` - ## Other resources - [Reach Router docs](https://reach.tech/router) From 8fa23d10fab8ea6c0b656e7dff915d2dc4a3b82a Mon Sep 17 00:00:00 2001 From: Blaine Kasten Date: Thu, 2 Jul 2020 11:36:00 -0500 Subject: [PATCH 4/9] Update packages/gatsby/index.d.ts Co-authored-by: Aisha Blake --- packages/gatsby/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gatsby/index.d.ts b/packages/gatsby/index.d.ts index b51333ccf6311..8b1e9e422e423 100644 --- a/packages/gatsby/index.d.ts +++ b/packages/gatsby/index.d.ts @@ -48,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" From 2d16ff7f56d28cd801ba22fb8eb4a2316de466a5 Mon Sep 17 00:00:00 2001 From: Aisha Blake Date: Mon, 6 Jul 2020 15:25:52 -0400 Subject: [PATCH 5/9] Rearrange scroll restoration docs --- docs/docs/making-your-site-accessible.md | 2 +- docs/docs/reach-router-and-gatsby.md | 45 ++---------------------- docs/docs/scroll-restoration.md | 43 ++++++++++++++++++++++ www/src/data/sidebars/doc-links.yaml | 2 ++ 4 files changed, 49 insertions(+), 43 deletions(-) create mode 100644 docs/docs/scroll-restoration.md diff --git a/docs/docs/making-your-site-accessible.md b/docs/docs/making-your-site-accessible.md index 28c68df2e9d6b..2454619b2d5b1 100644 --- a/docs/docs/making-your-site-accessible.md +++ b/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 diff --git a/docs/docs/reach-router-and-gatsby.md b/docs/docs/reach-router-and-gatsby.md index 758b220979f4b..a83dd6f9360fb 100644 --- a/docs/docs/reach-router-and-gatsby.md +++ b/docs/docs/reach-router-and-gatsby.md @@ -11,7 +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. Scroll restoration. +4. Scroll restoration. It supports [scroll restoration](https://reacttraining.com/react-router/web/guides/scroll-restoration), which allows Gatsby to better control pages' scroll position. With Gatsby, you will mostly be using the `` component provided by the `gatsby` package. The [`` API docs](https://www.gatsbyjs.org/docs/gatsby-link/) explain the relationship between `gatsby` `` and `@reach/router` `` very nicely: @@ -21,47 +21,8 @@ With Gatsby, you will mostly be using the `` component provided by the ` Besides using the [`` API](https://www.gatsbyjs.org/docs/gatsby-link/) for linking between pages Gatsby generates, you can define your own client-side routes. See the [client only paths example](https://github.com/gatsbyjs/gatsby/tree/master/examples/client-only-paths) on how to use `` from `@reach/router` to make client routes work seamlessly together with your server routes. -## Scroll Restoration - -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 ( -
    - {countryList.map(country =>
  • {country}
    • ) -
- ); -} -``` - -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 ( - -
    - {countryList.map(country =>
  • {country}
    • ) -
- - ); - } -} -``` - ## 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) diff --git a/docs/docs/scroll-restoration.md b/docs/docs/scroll-restoration.md new file mode 100644 index 0000000000000..92245c6bdbe79 --- /dev/null +++ b/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 ( +
    + {countryList.map(country =>
  • {country}
    • ) +
+ ); +} +``` + +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 ( + +
    + {countryList.map(country =>
  • {country}
    • ) +
+ + ); + } +} +``` \ No newline at end of file diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index a8eaebfb14419..e8fc39114644c 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -474,6 +474,8 @@ items: - title: "@reach/router and Gatsby" link: /docs/reach-router-and-gatsby/ + - title: "Scroll Restoration" + link: /docs/scroll-restroation/ - title: Location Data from Props link: /docs/location-data-from-props/ - title: Creating Dynamic Navigation From 5379721cf83cbfb8c0a7ab7ed2d93aee5087ccf1 Mon Sep 17 00:00:00 2001 From: gatsbybot Date: Mon, 6 Jul 2020 20:35:04 +0000 Subject: [PATCH 6/9] chore: format --- docs/docs/scroll-restoration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/scroll-restoration.md b/docs/docs/scroll-restoration.md index 92245c6bdbe79..3446825985e50 100644 --- a/docs/docs/scroll-restoration.md +++ b/docs/docs/scroll-restoration.md @@ -40,4 +40,4 @@ export default class PageComponent extends React.Component { ); } } -``` \ No newline at end of file +``` From 73dfc6b659ccbe84eb5d3f2935882b33c185d7be Mon Sep 17 00:00:00 2001 From: Aisha Blake Date: Thu, 9 Jul 2020 18:07:17 -0400 Subject: [PATCH 7/9] Add links to scroll restoration page --- docs/docs/reach-router-and-gatsby.md | 2 +- docs/docs/routing.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docs/reach-router-and-gatsby.md b/docs/docs/reach-router-and-gatsby.md index a83dd6f9360fb..d0683234627d7 100644 --- a/docs/docs/reach-router-and-gatsby.md +++ b/docs/docs/reach-router-and-gatsby.md @@ -11,7 +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. Scroll restoration. It supports [scroll restoration](https://reacttraining.com/react-router/web/guides/scroll-restoration), which allows Gatsby to better control pages' scroll position. +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 `` component provided by the `gatsby` package. The [`` API docs](https://www.gatsbyjs.org/docs/gatsby-link/) explain the relationship between `gatsby` `` and `@reach/router` `` very nicely: diff --git a/docs/docs/routing.md b/docs/docs/routing.md index 64fe74e05165e..afffcc445d113 100644 --- a/docs/docs/routing.md +++ b/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 `` 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. From 33bf17e5ef9deda5b94935b5698ca19418fd70f6 Mon Sep 17 00:00:00 2001 From: Aisha Blake Date: Thu, 9 Jul 2020 18:09:56 -0400 Subject: [PATCH 8/9] Fix doc link spelling --- www/src/data/sidebars/doc-links.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 3e1991ff65874..8362a2ac187b6 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -478,7 +478,7 @@ - title: "@reach/router and Gatsby" link: /docs/reach-router-and-gatsby/ - title: "Scroll Restoration" - link: /docs/scroll-restroation/ + link: /docs/scroll-restoration/ - title: Location Data from Props link: /docs/location-data-from-props/ - title: Creating Dynamic Navigation From 9327ce77d7d8a0b1df28fefe6ab7c139b7264ac6 Mon Sep 17 00:00:00 2001 From: Aisha Blake Date: Fri, 10 Jul 2020 10:17:52 -0400 Subject: [PATCH 9/9] Update docs/docs/scroll-restoration.md --- docs/docs/scroll-restoration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/scroll-restoration.md b/docs/docs/scroll-restoration.md index 3446825985e50..614c7cbd0f4c6 100644 --- a/docs/docs/scroll-restoration.md +++ b/docs/docs/scroll-restoration.md @@ -23,7 +23,7 @@ export default function PageComponent() { } ``` -This is an example of using the (deprecated) ScrollContainer component with the same code. +This is an example of using the (deprecated) `ScrollContainer` component with the same code. ```jsx import { ScrollContainer } from "gatsby-react-router-scroll";