From d8937d042edd229657289fce164d4e7815997d68 Mon Sep 17 00:00:00 2001 From: Tim Osborn Date: Sun, 2 Feb 2020 02:19:36 +1100 Subject: [PATCH] =?UTF-8?q?fix(gatsby-link):=20Adds=20Type,=20PropType,=20?= =?UTF-8?q?tests,=20and=20docs=20for=20`st=E2=80=A6=20(#20807)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix code example for "Example of providing state to a link component" https://www.gatsbyjs.org/docs/location-data-from-props/#example-of-providing-state-to-a-link-component Signed-off-by: Tim Osborn * Add PropType and TS definition for the `state` prop Signed-off-by: Tim Osborn * Cross link docs relevant to GatsbyLink Signed-off-by: Tim Osborn * Add tests for passing state Signed-off-by: Tim Osborn * Update index.d.ts Co-authored-by: Ward Peeters --- docs/docs/gatsby-link.md | 3 +++ docs/docs/location-data-from-props.md | 7 +++--- packages/gatsby-link/index.d.ts | 4 +++ packages/gatsby-link/src/__tests__/index.js | 27 +++++++++++++++++++++ packages/gatsby-link/src/index.js | 1 + 5 files changed, 39 insertions(+), 3 deletions(-) diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md index afd8acdfc2d5b..f24ca64b4726c 100644 --- a/docs/docs/gatsby-link.md +++ b/docs/docs/gatsby-link.md @@ -249,6 +249,8 @@ const Form = () => ( ) ``` +Then from the receiving page you can access the `location` state as demonstrated in [Pass state as props to the linked page](#pass-state-as-props-to-the-linked-page). + ### Replace history during programmatic navigation If the navigation should replace history instead of pushing a new entry into the navigation history, add the `replace` prop with a value of `true` to the `options` argument of `navigate`. @@ -390,4 +392,5 @@ onClick = () => { ## Additional resources - [Authentication tutorial for client-only routes](/tutorial/authentication-tutorial/) +- [Routing: Getting Location Data from Props](/docs/location-data-from-props/) - [`gatsby-plugin-catch-links`](https://www.gatsbyjs.org/packages/gatsby-plugin-catch-links/) to automatically intercept local links in Markdown files for `gatsby-link` like behavior diff --git a/docs/docs/location-data-from-props.md b/docs/docs/location-data-from-props.md index 15a457b4511c2..31b41d1e30623 100644 --- a/docs/docs/location-data-from-props.md +++ b/docs/docs/location-data-from-props.md @@ -38,9 +38,9 @@ Through client-side routing in Gatsby you can provide a location object instead // but if you want to add some additional state - ``` @@ -64,6 +64,7 @@ The great thing is you can expect the `location` prop to be available to you on ## Other resources +- [Gatsby Link API](/docs/gatsby-link/) - [@reach/router docs](https://reach.tech/router/api/Location) - [react-router location docs](https://github.com/ReactTraining/react-router/blob/master/packages/react-router/docs/api/location.md) - [Hash Router](https://reacttraining.com/react-router/web/api/HashRouter) diff --git a/packages/gatsby-link/index.d.ts b/packages/gatsby-link/index.d.ts index 88695d7283fa8..795ffa1361ab3 100644 --- a/packages/gatsby-link/index.d.ts +++ b/packages/gatsby-link/index.d.ts @@ -12,6 +12,10 @@ export interface GatsbyLinkProps extends LinkProps { partiallyActive?: boolean /** Used to declare that this link replaces the current URL in history with the target */ replace?: boolean + /** Used to pass state data to the linked page. + * The linked page will have a `location` prop containing a nested `state` object structure containing the passed data. + */ + state?: TState /** The URL you want to link to */ to: string } diff --git a/packages/gatsby-link/src/__tests__/index.js b/packages/gatsby-link/src/__tests__/index.js index 24793275d708b..1bbf0bbdd5eba 100644 --- a/packages/gatsby-link/src/__tests__/index.js +++ b/packages/gatsby-link/src/__tests__/index.js @@ -227,6 +227,18 @@ describe(`navigate`, () => { undefined ) }) + + it(`passes a state object`, () => { + const to = `/some-path` + const options = { state: { myStateKey: `a state value` } } + + getNavigate()(to, options) + + expect(global.___navigate).toHaveBeenCalledWith( + `${global.__BASE_PATH__}${to}`, + options + ) + }) }) describe(`ref forwarding`, () => { @@ -253,3 +265,18 @@ describe(`ref forwarding`, () => { expect(ref.current).toEqual(expect.any(HTMLElement)) }) }) + +describe(`state`, () => { + it(`passes a state object`, () => { + const to = `/` + const state = { myStateKey: `a state value` } + getNavigate() + + const { link } = setup({ linkProps: { state } }) + link.click() + + expect( + global.___navigate + ).toHaveBeenCalledWith(`${global.__BASE_PATH__}${to}`, { state }) + }) +}) diff --git a/packages/gatsby-link/src/index.js b/packages/gatsby-link/src/index.js index ebba62912b3c4..53f7147c7962b 100644 --- a/packages/gatsby-link/src/index.js +++ b/packages/gatsby-link/src/index.js @@ -187,6 +187,7 @@ GatsbyLink.propTypes = { onClick: PropTypes.func, to: PropTypes.string.isRequired, replace: PropTypes.bool, + state: PropTypes.object, } const showDeprecationWarning = (functionName, altFunctionName, version) =>