Add Hooks APIs (#346)

* Add Hooks APIs

* Documenation & change useMatch response to match Match

* add hook API navigation links

* some hooks documentation in the intro

* address comments

* yarn format

Author: blainekasten

examples/crud/src/App.js

@@ -256,7 +256,8 @@ const Create = withInvalidateContacts(
           </ul>
           {state === CreateStates.ERROR && (
             <p>
-              There was an error:<br />
+              There was an error:
+              <br />
               <br />
               <b>{error}</b>
             </p>

package.json

@@ -54,9 +54,9 @@
     "prettier": "^1.13.4",
     "pretty-bytes": "^4.0.2",
     "pretty-quick": "^1.6.0",
-    "react": "16.4.1",
-    "react-dom": "16.4.2",
-    "react-test-renderer": "16.4",
+    "react": "16.12.0",
+    "react-dom": "16.12.0",
+    "react-test-renderer": "16.12",
     "render-markdown-js": "^1.3.0",
     "rollup": "^0.56.3",
     "rollup-plugin-babel": "^3.0.3",

src/__snapshots__/index.test.js.snap

@@ -91,6 +91,58 @@ exports[`disrespect has complete disrespect for leading and trailing slashes 1`]
 </div>
 `;
 
+exports[`hooks useLocation returns the location 1`] = `
+<div
+  style={
+    Object {
+      "outline": "none",
+    }
+  }
+  tabIndex="-1"
+>
+  path: /this/path/is/returned
+</div>
+`;
+
+exports[`hooks useNavigate navigates relative 1`] = `
+<div
+  style={
+    Object {
+      "outline": "none",
+    }
+  }
+  tabIndex="-1"
+>
+  IF_THIS_IS_IN_SNAPSHOT_BAAAAADDDDDDDD
+</div>
+`;
+
+exports[`hooks useNavigate navigates relative 2`] = `
+<div
+  style={
+    Object {
+      "outline": "none",
+    }
+  }
+  tabIndex="-1"
+>
+  THIS_IS_WHAT_WE_WANT_TO_SEE_IN_SNAPSHOT
+</div>
+`;
+
+exports[`hooks useParams gives an object of the params from the route 1`] = `
+<div
+  style={
+    Object {
+      "outline": "none",
+    }
+  }
+  tabIndex="-1"
+>
+  {"bar":"123","bax":"hi"}
+</div>
+`;
+
 exports[`links renders links with relative hrefs 1`] = `
 <div
   style={

src/index.js

@@ -1,5 +1,5 @@
 /* eslint-disable jsx-a11y/anchor-has-content */
-import React from "react";
+import React, { useContext } from "react";
 import PropTypes from "prop-types";
 import invariant from "invariant";
 import createContext from "create-react-context";
@@ -520,6 +520,56 @@ let Match = ({ path, children }) => (
   </BaseContext.Consumer>
 );
 
+////////////////////////////////////////////////////////////////////////////////
+// Hooks
+
+const useLocation = () => {
+  const context = useContext(LocationContext);
+
+  if (!context) {
+    throw new Error(
+      "useLocation hook was used but a LocationContext.Provider was not found in the parent tree. Make sure this is used in a component that is a child of Router"
+    );
+  }
+
+  return context.location;
+};
+
+const useNavigate = () => {
+  const context = useContext(LocationContext);
+
+  return context.navigate;
+};
+
+const useParams = () => {
+  const { basepath } = useContext(BaseContext);
+  const location = useLocation();
+
+  const results = match(basepath, location.pathname);
+
+  return results ? results.params : null;
+};
+
+const useRouterMatch = path => {
+  if (!path) {
+    throw new Error(
+      "useRouterMatch(path: string) requires an argument of a string to match against"
+    );
+  }
+  const { baseuri } = useContext(BaseContext);
+  const location = useLocation();
+
+  const resolvedPath = resolve(path, baseuri);
+  const result = match(resolvedPath, location.pathname);
+  return result
+    ? {
+        ...result.params,
+        uri: result.uri,
+        path
+      }
+    : null;
+};
+
 ////////////////////////////////////////////////////////////////////////////////
 // Junk
 let stripSlashes = str => str.replace(/(^\/+|\/+$)/g, "");
@@ -589,5 +639,9 @@ export {
   navigate,
   redirectTo,
   globalHistory,
-  match as matchPath
+  match as matchPath,
+  useLocation,
+  useNavigate,
+  useParams,
+  useRouterMatch
 };

src/index.test.js

@@ -14,7 +14,11 @@ import {
   Match,
   Redirect,
   isRedirect,
-  ServerLocation
+  ServerLocation,
+  useLocation,
+  useNavigate,
+  useParams,
+  useRouterMatch
 } from "./index";
 
 let snapshot = ({ pathname, element }) => {
@@ -876,3 +880,123 @@ describe("trailing wildcard", () => {
     });
   });
 });
+
+describe("hooks", () => {
+  describe("useLocation", () => {
+    it("returns the location", () => {
+      function Fixture() {
+        const location = useLocation();
+        return `path: ${location.pathname}`;
+      }
+
+      snapshot({
+        pathname: `/this/path/is/returned`,
+        element: (
+          <Router>
+            <Fixture path="/this/path/is/returned" />
+          </Router>
+        )
+      });
+    });
+
+    it("throws an error if a location context hasnt been rendered", () => {
+      function Fixture() {
+        const location = useLocation();
+        return `path: ${location.pathname}`;
+      }
+
+      expect(() => {
+        renderToString(<Fixture />);
+      }).toThrow(
+        "useLocation hook was used but a LocationContext.Provider was not found in the parent tree. Make sure this is used in a component that is a child of Router"
+      );
+    });
+  });
+
+  describe("useNavigate", () => {
+    it("navigates relative", async () => {
+      let navigate;
+
+      const Foo = () => {
+        navigate = useNavigate();
+        return `IF_THIS_IS_IN_SNAPSHOT_BAAAAADDDDDDDD`;
+      };
+
+      const Bar = () => `THIS_IS_WHAT_WE_WANT_TO_SEE_IN_SNAPSHOT`;
+
+      const { snapshot } = runWithNavigation(
+        <Router>
+          <Foo path="/foo" />
+          <Bar path="/bar" />
+        </Router>,
+        "/foo"
+      );
+      snapshot();
+      await navigate("/bar");
+      snapshot();
+    });
+  });
+
+  describe("useParams", () => {
+    it("gives an object of the params from the route", () => {
+      const Fixture = () => {
+        const params = useParams();
+        return JSON.stringify(params);
+      };
+
+      snapshot({
+        pathname: "/foo/123/baz/hi",
+        element: (
+          <Router>
+            <Fixture path="/foo/:bar/baz/:bax" />
+          </Router>
+        )
+      });
+    });
+  });
+
+  describe("useRouterMatch", () => {
+    it("matches on direct routes", async () => {
+      let match;
+
+      const Foo = () => {
+        match = useRouterMatch("/foo");
+        return ``;
+      };
+
+      const { snapshot } = runWithNavigation(
+        <Router>
+          <Foo path="/foo" />
+        </Router>,
+        "/foo"
+      );
+
+      expect(match).not.toBe(null);
+    });
+
+    it("matches on matching child routes", () => {
+      let matchExact;
+      let matchSplat;
+
+      const Foo = () => {
+        matchExact = useRouterMatch("/foo");
+        matchSplat = useRouterMatch("/foo/*");
+        return ``;
+      };
+
+      const Bar = () => "";
+
+      const { snapshot } = runWithNavigation(
+        <Router>
+          <Foo path="/foo">
+            <Bar path="/bar" />
+          </Foo>
+        </Router>,
+        "/foo/bar"
+      );
+
+      expect(matchExact).toBe(null);
+      expect(matchSplat).not.toBe(null);
+    });
+  });
+});

src/lib/history.test.js

@@ -34,7 +34,6 @@ describe("navigate", () => {
 
 it("should have a proper search", () => {
   const testHistory = createHistory(createMemorySource("/test"));
-  console.log(testHistory);
   testHistory.navigate("/?asdf");
   expect(testHistory.location.search).toEqual("?asdf");
 });

website/src/Nav.js

@@ -156,6 +156,18 @@ let Nav = () => (
                         <NavLink to="api/navigate">navigate</NavLink>
                       </div>
 
+                      <Header>Hooks API</Header>
+                      <div
+                        css={{
+                          fontFamily: `'SFMono-Regular', Consolas, 'Roboto Mono', 'Droid Sans Mono', 'Liberation Mono', Menlo, Courier, monospace`
+                        }}
+                      >
+                        <NavLink to="api/useLocation">useLocation</NavLink>
+                        <NavLink to="api/useMatch">useMatch</NavLink>
+                        <NavLink to="api/useNavigate">useNavigate</NavLink>
+                        <NavLink to="api/useParams">useParams</NavLink>
+                      </div>
+
                       <Header>Additional API</Header>
                       <div
                         css={{

website/src/markdown/api/useLocation.md

@@ -0,0 +1,17 @@
+# useLocation
+
+Returns the location to any component.
+
+This API requires a hook-compatible version of React.
+
+```jsx
+import { useLocation } from "@reach/router"
+
+const useAnalytics = (props) => {
+  const location = useLocation();
+
+  useEffect(() => {
+    ga.send(['pageview', location.pathname]);
+  }, [])
+)
+```

website/src/markdown/api/useMatch.md

@@ -0,0 +1,50 @@
+# useMatch
+
+Matches a path to the location. Matching is relative to any parent Routers, but not parent match's, because they render even if they don't match.
+
+This API requires a hook-compatible version of React.
+
+```jsx
+import { useMatch } from "@reach/router"
+
+const App = () => {
+  const match = useMatch('/hot/:item');
+
+  return match ? (
+    <div>Hot {match.item}</div>
+  ) : (
+    <div>Uncool</div>
+  )
+)
+```
+
+`useMatch` will return `null` if your path does not match the location. If it does match it will contain:
+
+- `uri`
+- `path`
+- `:params`
+
+## match\[param\]: string
+
+Any params in your the path will be parsed and passed as `match[param]` to your callback.
+
+```jsx
+const match = useMatch("events/:eventId")
+
+props.match ? props.match.eventId : "No match"
+```
+
+## match.uri: string
+
+The portion of the URI that matched. If you pass a wildcard path, the wildcard portion will not be included. Not sure how this is useful for a `Match`, but it's critical for how focus managment works, so we might as well pass it on to Match if we pass it on to Route Components!
+
+```jsx
+// URL: /somewhere/deep/i/mean/really/deep
+const match = useMatch("/somewhere/deep/*")
+
+return <div>{match.uri}</div>
+```
+
+## match.path: string
+
+The path you passed in as a prop.