crossroad 1.1.4 → 1.2.1

package/index.min.js

@@ -1 +1 @@
-import t,{createContext as e,useState as r,useCallback as n,useEffect as o,useContext as a}from"react";var i=e();const s=t=>{if("string"!=typeof t)return t;const e={},r=new URL(t,"http://localhost:3000/");e.path=r.pathname.replace(/\/$/,"")||"/",e.query={};for(const[t]of r.searchParams)e.query[t]=(n=r.searchParams.getAll(t)).length>1?n:n[0];var n;return r.hash&&(e.hash=r.hash.replace(/^#/,"")),e},p=t=>{if("string"==typeof t)return t;const{path:e,query:r={},hash:n}=t||{};let o=e||"/";const a=new URLSearchParams(Object.entries(r).map(([t,e])=>(Array.isArray(e)?e:[e]).map(e=>[t,e])).flat().filter(([t,e])=>e)).toString();return a&&(o+="?"+a),n&&(o+="#"+n),o};var u=()=>"undefined"==typeof window;function c(t,e,r={}){if(t=JSON.parse(JSON.stringify(s(t))),(e=JSON.parse(JSON.stringify(s(e)))).path=e.path.replace(/\/$/,"")||"/",t.path=t.path.replace(/\/$/,"")||"/",t.path.endsWith("*")){t.path=t.path.replace(/\/?\*/,"")||"/";const r=t.path.split("/").filter(Boolean).length;e.path="/"+e.path.slice(1).split("/").slice(0,r).join("/")}if(Object.entries(t.query).length)for(let r in t.query){if(!(r in e.query))return!1;if(t.query[r]&&t.query[r]!==e.query[r])return!1}if(!t.path.includes(":"))return t.path===e.path&&r;if(t.path.split("/").length!==e.path.split("/").length)return!1;const n={},o=t.path.split("/").every((t,o)=>{const a=e.path.split("/")[o];return t.startsWith(":")?(n[t.slice(1)]=a,r):a===t});return o&&Object.assign(r,n),o&&r}var l=({path:e="*",exact:r=!0,component:n,render:o,children:s})=>{const p=a(i),u=c(e,p[0]);if(!u)return null;if(n){const e=n;s=t.createElement(e,u)}else if(o)s=o(u);else if(!s)throw new Error("Route needs prop `component`, `render` or `children`");return t.createElement(i.Provider,{value:[{...p[0],params:u},...p.slice(1)]},s)},h=()=>{const t=a(i);if(!t)throw new Error("Wrap your App with <Router>");return t};var f=({redirect:t,children:e})=>{const[r,n]=h(),a=(t=>(Array.isArray(t)||(t=[t]),t.filter(t=>t&&t.props)))(e).find(t=>c(t.props.path||"*",r))||null;return o(()=>{t&&(a||("function"==typeof t&&(t=t(r)),n(p(t))))},[t,a]),a},y=()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("function"==typeof t&&(t=t(e.path)),"string"!=typeof t&&(t="/"),{...e,path:t}),r)},[]);return[t.path,r]};const d=t=>p({query:t});var q=t=>t?(t=>{const[e,r]=h(),o=n((e,n)=>{r(r=>{const n=r.query[t];if((e="function"==typeof e?e(n):e)===n)return r;if(e)return{...r,query:{...r.query,[t]:e}};{const{[t]:e,...n}=r.query;return{...r,query:n}}},n)},[]);return[e.query[t],o]})(t):(()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("string"==typeof(t="function"==typeof t?t(e.query):t)&&(t=s("/?"+t.replace(/^\?/,"")).query),t=s(d(t)).query,d(t)===d(e.query)?e:{...e,query:t}),r)},[]);return[t.query,r]})(),m=()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("function"==typeof t&&(t=t(e.hash)),"string"!=typeof t&&(t=""),t=t.replace(/^#/,""),{...e,hash:t}),r)},[]);return[t.hash,r]},w=t=>{const e=a(i);return t?c(t,e[0].path)||{}:e[0].params};export default({url:e,children:a})=>{const c=e||(u()?"/":window.location.href),[l,h]=r(()=>s(c)),f=n((t,{mode:e="push"}={})=>{if(!history[e+"State"])throw new Error(`Invalid mode "${e}"`);t="function"==typeof t?t(l):t,h(r=>p(r)===p(t)?r:(history[e+"State"]({},null,p(t)),s(t)))},[]);return o(()=>{if(u())return;const t=()=>h(s(window.location.href)),e=t=>{const e=(t=>{if(!t)return null;const e=t.getAttribute("href");return e?/^https?:\/\//.test(e)||null!==t.getAttribute("target")?null:e:null})(t.target.closest("a"));if(!e)return;t.preventDefault();const[r,n]=e.split("#");r&&f(r),n&&(window.location.hash="#"+n)};return window.addEventListener("popstate",t),document.addEventListener("click",e),()=>{window.removeEventListener("popstate",t),document.removeEventListener("click",e)}},[f]),t.createElement(i.Provider,{value:[l,f]},a)};export{i as Context,l as Route,f as Switch,m as useHash,w as useParams,y as usePath,q as useQuery,h as useUrl};
+import t,{createContext as e,useState as r,useCallback as n,useEffect as o,useContext as a}from"react";var i=e();const s=t=>{if("string"!=typeof t)return t;const e={},r=new URL(t,"http://localhost:3000/");e.path=r.pathname.replace(/\/$/,"")||"/",e.query={};for(const[t]of r.searchParams)e.query[t]=(n=r.searchParams.getAll(t)).length>1?n:n[0];var n;return r.hash&&(e.hash=r.hash.replace(/^#/,"")),e},p=t=>{if("string"==typeof t)return t;const{path:e,query:r={},hash:n}=t||{};let o=e||"/";const a=new URLSearchParams(Object.entries(r).map(([t,e])=>(Array.isArray(e)?e:[e]).map(e=>[t,e])).flat().filter(([t,e])=>e)).toString();return a&&(o+="?"+a),n&&(o+="#"+n),o};var u=()=>"undefined"==typeof window;function l(t,e,r={}){if(t=JSON.parse(JSON.stringify(s(t))),(e=JSON.parse(JSON.stringify(s(e)))).path=e.path.replace(/\/$/,"")||"/",t.path=t.path.replace(/\/$/,"")||"/",t.path.endsWith("*")){t.path=t.path.replace(/\/?\*/,"")||"/";const r=t.path.split("/").filter(Boolean).length;e.path="/"+e.path.slice(1).split("/").slice(0,r).join("/")}if(Object.entries(t.query).length)for(let r in t.query){if(!(r in e.query))return!1;if(t.query[r]&&t.query[r]!==e.query[r])return!1}if(!t.path.includes(":"))return t.path===e.path&&r;if(t.path.split("/").length!==e.path.split("/").length)return!1;const n={},o=t.path.split("/").every((t,o)=>{const a=e.path.split("/")[o];return t.startsWith(":")?(n[t.slice(1)]=decodeURIComponent(a),r):a===t});return o&&Object.assign(r,n),o&&r}var c=({path:e="*",scrollUp:r,component:n,render:o,children:s})=>{const p=a(i),u=l(e,p[0]);if(!u)return null;if(r&&window.scrollTo(0,0),n){const e=n;s=t.createElement(e,u)}else if(o)s=o(u);else if(!s)throw new Error("Route needs prop `component`, `render` or `children`");return t.createElement(i.Provider,{value:[{...p[0],params:u},...p.slice(1)]},s)},h=()=>{const t=a(i);if(!t)throw new Error("Wrap your App with <Router>");return t};var f=({redirect:t,children:e})=>{const[r,n]=h(),a=(t=>(Array.isArray(t)||(t=[t]),t.filter(t=>t&&t.props)))(e).find(t=>l(t.props.path||"*",r))||null;return o(()=>{t&&(a||("function"==typeof t&&(t=t(r)),n(p(t))))},[t,a]),a},y=()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("function"==typeof t&&(t=t(e.path)),"string"!=typeof t&&(t="/"),{...e,path:t}),r)},[]);return[t.path,r]};const d=t=>p({query:t});var w=t=>t?(t=>{const[e,r]=h(),o=n((e,n)=>{r(r=>{const n=r.query[t];if((e="function"==typeof e?e(n):e)===n)return r;if(e)return{...r,query:{...r.query,[t]:e}};{const{[t]:e,...n}=r.query;return{...r,query:n}}},n)},[]);return[e.query[t],o]})(t):(()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("string"==typeof(t="function"==typeof t?t(e.query):t)&&(t=s("/?"+t.replace(/^\?/,"")).query),t=s(d(t)).query,d(t)===d(e.query)?e:{...e,query:t}),r)},[]);return[t.query,r]})(),m=()=>{const[t,e]=h(),r=n((t,r)=>{e(e=>("function"==typeof t&&(t=t(e.hash)),"string"!=typeof t&&(t=""),t=t.replace(/^#/,""),{...e,hash:t}),r)},[]);return[t.hash,r]},q=t=>{const e=a(i);return t?l(t,e[0].path)||{}:e[0].params};export default({scrollUp:e,url:a,children:l})=>{const c=a||(u()?"/":window.location.href),[h,f]=r(()=>s(c)),y=n((t,{mode:r="push"}={})=>{if(!history[r+"State"])throw new Error(`Invalid mode "${r}"`);t="function"==typeof t?t(h):t,f(n=>p(n)===p(t)?n:(history[r+"State"]({},null,p(t)),e&&window.scrollTo(0,0),s(t)))},[]);return o(()=>{if(u())return;const t=()=>f(s(window.location.href)),e=t=>{const e=(t=>{if(!t)return null;const e=t.getAttribute("href");return e?/^https?:\/\//.test(e)||null!==t.getAttribute("target")?null:e:null})(t.target.closest("a"));if(!e)return;t.preventDefault();const[r,n]=e.split("#");r&&y(r),n&&(window.location.hash="#"+n)};return window.addEventListener("popstate",t),document.addEventListener("click",e),()=>{window.removeEventListener("popstate",t),document.removeEventListener("click",e)}},[y]),t.createElement(i.Provider,{value:[h,y]},l)};export{i as Context,c as Route,f as Switch,m as useHash,q as useParams,y as usePath,w as useQuery,h as useUrl};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossroad",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "A React library to handle navigation in your WebApp. Built with simple components and React Hooks so your code is cleaner.",
   "homepage": "https://crossroad.page/",
   "repository": "https://github.com/franciscop/crossroad.git",

package/readme.md

@@ -3,10 +3,11 @@
 A React library to handle navigation in your WebApp. Built with simple components and React Hooks so you write cleaner code:
 
 - `<Router>`, `<Switch>` and `<Route>` inspired by React Router so it's easy to get started.
-- Very useful hooks like [`useUrl`](#useurl), [`useQuery`](#usequery), etc.
+- Very useful hooks like [`useUrl`](#useurl), [`useQuery`](#usequery), etc. Follow [the rules of hooks](https://reactjs.org/docs/hooks-rules.html).
 - Links are plain `<a>` instead of custom components. [Read more](#a).
 - The `<Route>` path is `exact` by default and can match query parameters.
 - It's [just ~1.5kb](https://bundlephobia.com/package/crossroad) (min+gzip) instead of the 17kb of React Router(+Dom).
+- Add `scrollUp` to `<Router>` o `<Route>` to automatically scroll up on a route change.
 
 [**🔗 Demo on CodeSandbox**](https://codesandbox.io/s/recursing-wozniak-uftyo?file=/src/App.js)
 
@@ -123,18 +124,21 @@ export default function App() {
 }
 ```
 
+Add the prop `scrollUp` to automatically scroll up the browser window when _any_ route changes. In contrast, you could also add it only to a single or multiple `<Route>`.
+
+Add the prop `url` to simulate a fake URL instead of the current `window.location`, useful specially for testing.
+
 You would normally setup this Router straight on your App, along things like [Statux](https://statux.dev/)'s or [Redux](https://redux.js.org/)'s Store, error handling, translations, etc.
 
 An example for a simple app:
 
 ```js
-
 // App.js
-import Router, { Switch, Route} from "crossroad";
+import Router, { Switch, Route } from "crossroad";
 
-import Home from './pages/Home';
-import Dashboard from './pages/Dashboard';
-import Profile from './pages/Profile';
+import Home from "./pages/Home";
+import Dashboard from "./pages/Dashboard";
+import Profile from "./pages/Profile";
 
 export default function App() {
   return (
@@ -200,6 +204,7 @@ This component defines a conditional path that, when strictly matched, renders t
 - `component`: the component that will be rendered if the browser's URL matches the `path` parameter.
 - `render`: a function that will be called with the params if the browser's URL matches the `path` parameter.
 - `children`: the children to render if the browser's URL matches the `path` parameter.
+- `scrollUp`: automatically scroll up the browser window when this route/component/etc is matched.
 
 So for example if the `path` prop is `"/user"` and you visit the page `"/user"`, then the component is rendered; it is ignored otherwise:
 
@@ -352,6 +357,10 @@ These are the structures of each:
   - `setUrl({ path: '/newpath', query: { hello: 'world' } })`: update the path and query (and delete the hash if any)
   - `setUrl(prev => ...)`: use the previous url (object)
 
+`useUrl()` is powerful enough for all of your needs, but you might still be interested in other hooks to simplify situations where you do e.g. heavy query manipulation with [`useQuery`](#usequery).
+
+#### url
+
 The resulting `url` is an object containing each of the parts of the URL:
 
 ```js
@@ -362,7 +371,25 @@ console.log(url.query); // { filter: hello }
 console.log(url.hash); // world
 ```
 
-You can also set it fully or partially:
+It is memoized, so that if the url doesn't change then the object will remain the same. The same of course applies to the subelements like `url.path`. It will however change when the url changes, so you want to put it in your dependencies as usual:
+
+```js
+// You can put the whole thing if you want to listen to
+// ANY change on the url
+useEffect(() => {
+  // ...
+}, [url]);
+
+// Or only a part of it. This is useful becase it WON'T trigger
+// when the query or hashtag change
+useEffect(() => {
+  // ...
+}, [url.path]);
+```
+
+#### Setter
+
+The setter can be invoked directly, or with a callback:
 
 ```js
 const [url, setUrl] = useUrl();
@@ -383,27 +410,15 @@ setUrl({ ...url, query: { search: "hello" } });
 setUrl({ ...url, query: { ...url.query, safe: "no" } });
 ```
 
-`useUrl()` is powerful enough for all of your needs, but you might still be interested in other hooks to simplify situations where you do e.g. heavy query manipulation with `useQuery`.
-
-#### Setter
-
-The setter can be invoked directly, or with a callback:
-
-```js
-setUrl('/newurl');
-setUrl(oldUrl => '/newurl');
-setUrl(oldUrl => ({ ...oldUrl, path: newPath }));
-```
-
 The function `setUrl` is _always_ the same, so it doesn't matter whether you put it as a dependency or not. However the `path` can be updated and change, so you want to depend on it:
 
 ```js
-const [url, setUrl] = useurl();
+const [url, setUrl] = useUrl();
 useEffect(() => {
-  if (url.path === '/base') {
-    setUrl('/base/deeper');
+  if (url.path === "/base") {
+    setUrl("/base/deeper");
   }
-}, [url, setUrl]);
+}, [url.path, setUrl]);
 ```
 
 If you update the url with the current url, it won't trigger a rerender. So the above can also be written as this, removing all dependencies:
@@ -411,19 +426,19 @@ If you update the url with the current url, it won't trigger a rerender. So the
 ```js
 const [url, setUrl] = useUrl();
 useEffect(() => {
-  setUrl(old => {
-    if (old.path === '/base') return '/base/deeper';
+  setUrl((old) => {
+    if (old.path === "/base") return "/base/deeper";
     return old;
   });
 }, []);
 ```
 
-
 #### New history entry
 
 By default `setUrl()` will create a new entry in the browser history. If you want to instead replace the current url you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
+setUrl("/newurl"); // Default: "push"
 setUrl("/newurl", { mode: "replace" });
 ```
 
@@ -447,17 +462,17 @@ const Login = () => {
 };
 ```
 
-The path is always a string equivalent to `window.location.pathname`.
+The path is always a string equivalent to `window.location.pathname`. Why not use `window.location.pathname` then? Because usePath() is a hook that will trigger a re-render when the path changes!
 
-> Note: this _only_ modifies the path(name) and keeps the search query and hash the same, so if you want to modify the full URL you should instead utilize `useUrl()` and `setUrl('/welcome')`
+> Note: `setPath` _only_ modifies the path(name) and keeps the search query and hash the same, so if you want to modify the full URL you should instead utilize `useUrl()` and `setUrl('/welcome')`
 
 #### Setter
 
 The setter can be invoked directly, or with a callback:
 
 ```js
-setPath('/newpath');
-setPath(oldPath => '/newpath');
+setPath("/newpath");
+setPath((oldPath) => "/newpath");
 ```
 
 The function `setPath` is _always_ the same, so it doesn't matter whether you put it as a dependency or not. However the `path` can be updated, so you might want to put that:
@@ -465,8 +480,8 @@ The function `setPath` is _always_ the same, so it doesn't matter whether you pu
 ```js
 const [path, setPath] = usePath();
 useEffect(() => {
-  if (path === '/base') {
-    setPath('/base/deeper');
+  if (path === "/base") {
+    setPath("/base/deeper");
   }
 }, [path, setPath]);
 ```
@@ -476,19 +491,19 @@ If you update the path with the current path, it won't trigger a rerender. So th
 ```js
 const [path, setPath] = usePath();
 useEffect(() => {
-  setPath(old => {
-    if (old === '/base') return '/base/deeper';
+  setPath((old) => {
+    if (old === "/base") return "/base/deeper";
     return old;
   });
 }, []);
 ```
 
-
 #### New history entry
 
 By default `setPath()` will create a new entry in the browser history. If you want to instead replace the current url you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
+setPath("/newpath"); // Default: "push"
 setPath("/newpath", { mode: "replace" });
 ```
 
@@ -508,7 +523,7 @@ export default function SearchInput() {
   // [{ search: "" }, fn]
 
   // Goes to /users?search={value}
-  const onChange = e => setQuery({ search: e.target.value });
+  const onChange = (e) => setQuery({ search: e.target.value });
 
   return <input value={query.search} onChange={onChange} />;
 }
@@ -537,7 +552,7 @@ setQuery({ search: "myname" });
 setQuery({ ...query, search: "myname" });
 // Goto /users?search=myname&filter=new
 
-setQuery(prev => ({ ...prev, search: "myname" }));
+setQuery((prev) => ({ ...prev, search: "myname" }));
 // Goto /users?search=myname&filter=new
 ```
 
@@ -565,6 +580,7 @@ import { useQuery as useSearch } from 'crossroad';
 By default `setQuery()` will create a new entry in the browser history. If you want to instead replace the current entry, so that the "Back" button goes to the previous page, you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
+setQuery({ search: "abc" }); // Default: "push"
 setQuery({ search: "abc" }, { mode: "replace" });
 ```
 
@@ -597,6 +613,7 @@ If you want to remove the hash, pass a `null` or `undefined` to the setter.
 By default `setHash()` will create a new entry in the browser history. If you want to instead replace the current entry, so that the "Back" button goes to the previous page, you can pass a second parameter with `{ mode: 'replace' }`:
 
 ```js
+setHash("newhash"); // Default: "push"
 setHash("newhash", { mode: "replace" });
 ```
 
@@ -679,7 +696,7 @@ That's it, in the [Codesandbox](https://codesandbox.io/s/loving-joana-jikne) we
 
 These refer to the websites where your username is straight after the domain, like Twitter (https://twitter.com/fpresencia). Of course Twitter has _other_ pages besides the username, so how can we emulate loading the page e.g. `/explore` in this case?
 
-The best way is to first define the known, company pages and then use the wildcard for the usernames:
+The best way is to first define the known, company pages and then use the wildcard for the usernames. This **must** be inside a `<Switch>`, otherwise multiple will be rendered:
 
 ```js
 <Switch>
@@ -748,7 +765,7 @@ export default function SearchForm() {
 }
 ```
 
-In here we can see that we are treating the output of `useQuery` in the sam way that we'd treat the output of `useState()`. This is on purpose and it makes things a lot easier for your application to work.
+In here we can see that we are treating the output of `useQuery` in the same way that we'd treat the output of `useState()`. This is on purpose and it makes things a lot easier for your application to work.
 
 ### Query routing
 
@@ -926,7 +943,7 @@ export default function Mock({ url, children }) {
   delete global.window.location;
   Object.defineProperty(global.window, "location", {
     value: new URL(href),
-    configurable: true
+    configurable: true,
   });
 
   // Undo the setup when the component unmounts
@@ -991,10 +1008,10 @@ For Razzle (based on [these docs FaQ](https://razzlejs.org/docs/customization#tr
 // razzle.config.js
 module.exports = {
   modifyWebpackOptions({ options: { webpackOptions } }) {
-    webpackOptions.notNodeExternalResMatch = req => /crossroad/.test(req);
+    webpackOptions.notNodeExternalResMatch = (req) => /crossroad/.test(req);
     webpackOptions.babelRule.include.push(/crossroad/);
     return webpackOptions;
-  }
+  },
 };
 ```
 
@@ -1053,7 +1070,7 @@ import { useUrl } from "crossroad";
 
 export default function LoginButton() {
   const [url, setUrl] = useUrl();
-  const login = async e => {
+  const login = async (e) => {
     // ...
     setUrl("/welcome");
   };