fix(gatsby-link): Adds Type, PropType, tests, and docs for `st… (#20807)

* 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 <[email protected]>

* Add PropType and TS definition for the `state` prop

Signed-off-by: Tim Osborn <[email protected]>

* Cross link docs relevant to GatsbyLink

Signed-off-by: Tim Osborn <[email protected]>

* Add tests for passing state

Signed-off-by: Tim Osborn <[email protected]>

* Update index.d.ts

Co-authored-by: Ward Peeters <[email protected]>

Author: ptim

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

docs/docs/location-data-from-props.md

@@ -38,9 +38,9 @@ Through client-side routing in Gatsby you can provide a location object instead
 <Link to="/somepagecomponent"/>
 
 // but if you want to add some additional state
-<Link to={{
-  pathname: '/somepagecomponent',
-  state: {modal: true}
+<Link
+  to={'/somepagecomponent'}
+  state={{modal: true}}
 }}>
 ```
 
@@ -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)

packages/gatsby-link/index.d.ts

@@ -12,6 +12,10 @@ export interface GatsbyLinkProps<TState> extends LinkProps<TState> {
   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
 }

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

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