crossroad 0.16.0 → 1.1.0

package/index.min.js

@@ -1 +1 @@
-import t,{createContext as e,useState as r,useEffect as n,useContext as a}from"react";var o=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},i=t=>{if("string"==typeof t)return t;const{path:e,query:r={},hash:n}=t||{};let a=e||"/";const o=new URLSearchParams(Object.entries(r).map(([t,e])=>(e.map?e:[e]).map(e=>[t,e])).flat()).toString();return o&&(a+="?"+o),n&&(a+="#"+n),a};var p=()=>"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={},a=t.path.split("/").every((t,a)=>{const o=e.path.split("/")[a];return t.startsWith(":")?(n[t.slice(1)]=o,r):o===t});return a&&Object.assign(r,n),a&&r}var h=({path:e="*",exact:r=!0,component:n,render:s,children:i})=>{const p=a(o),h=l(e,p[0]);if(!h)return null;if(n){const e=n;i=t.createElement(e,h)}else if(s)i=s(h);else if(!i)throw new Error("Route needs prop `component`, `render` or `children`");return t.createElement(o.Provider,{value:[{...p[0],params:h},...p.slice(1)]},i)},c=()=>{const t=a(o);if(!t)throw new Error("Wrap your App with <Router>");return t};var u=({redirect:t,children:e})=>{const[r,a]=c(),o=(t=>(Array.isArray(t)||(t=[t]),t.filter(t=>t&&t.props)))(e).find(t=>l(t.props.path||"*",r))||null;return n(()=>{t&&(o||("function"==typeof t&&(t=t(r)),a(i(t))))},[t,o]),o},f=()=>{const[t,e]=c();return[t.path,(r,n)=>e({...t,path:r},n)]},d=t=>{const[e,r]=c(),n=e.query,a=(t,n)=>r({...e,query:t},n);return t?[n[t],(e,r)=>a({...n,[t]:e},r)]:[n,a]},y=()=>{const[t,e]=c();return[t.hash,(r,n)=>e({...t,hash:r},n)]},m=t=>{const e=a(o);return t?l(t,e[0].path)||{}:e[0].params};export default({url:e,children:a})=>{const l=e||(p()?"/":window.location.href),[h,c]=r(()=>s(l)),u=(t,{mode:e="push"}={})=>{if(!history[e+"State"])throw new Error(`Invalid mode "${e}"`);history[e+"State"]({},null,i(t)),c(s(t))};return n(()=>{if(p())return;const t=()=>u(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"));e&&(t.preventDefault(),u(e))};return window.addEventListener("popstate",t),document.addEventListener("click",e),()=>{window.removeEventListener("popstate",t),document.removeEventListener("click",e)}},[]),t.createElement(o.Provider,{value:[h,u]},a)};export{o as Context,h as Route,u as Switch,y as useHash,m as useParams,f as usePath,d as useQuery,c as useUrl};
+import t,{createContext as e,useState as r,useCallback as n,useEffect as a,useContext as o}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 a=e||"/";const o=new URLSearchParams(Object.entries(r).map(([t,e])=>(Array.isArray(e)?e:[e]).map(e=>[t,e])).flat().filter(([t,e])=>e)).toString();return o&&(a+="?"+o),n&&(a+="#"+n),a};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={},a=t.path.split("/").every((t,a)=>{const o=e.path.split("/")[a];return t.startsWith(":")?(n[t.slice(1)]=o,r):o===t});return a&&Object.assign(r,n),a&&r}var l=({path:e="*",exact:r=!0,component:n,render:a,children:s})=>{const p=o(i),u=c(e,p[0]);if(!u)return null;if(n){const e=n;s=t.createElement(e,u)}else if(a)s=a(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=o(i);if(!t)throw new Error("Wrap your App with <Router>");return t};var f=({redirect:t,children:e})=>{const[r,n]=h(),o=(t=>(Array.isArray(t)||(t=[t]),t.filter(t=>t&&t.props)))(e).find(t=>c(t.props.path||"*",r))||null;return a(()=>{t&&(o||("function"==typeof t&&(t=t(r)),n(p(t))))},[t,o]),o},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(),a=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],a]})(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]},g=t=>{const e=o(i);return t?c(t,e[0].path)||{}:e[0].params};export default({url:e,children:o})=>{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 a(()=>{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"));e&&(t.preventDefault(),f(e))};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]},o)};export{i as Context,l as Route,f as Switch,m as useHash,g as useParams,y as usePath,q as useQuery,h as useUrl};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossroad",
-  "version": "0.16.0",
+  "version": "1.1.0",
   "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",
@@ -35,7 +35,7 @@
     "babel-polyfill": "^6.26.0",
     "jest": "^25.3.0",
     "react": "^16.8.0 || ^17.0.0",
-    "react-test": "^0.9.1",
+    "react-test": "^0.10.2",
     "rollup": "^1.32.1",
     "rollup-plugin-babel": "^4.4.0",
     "rollup-plugin-terser": "^5.2.0"

package/readme.md

@@ -125,6 +125,30 @@ export default function App() {
 
 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 Home from './pages/Home';
+import Dashboard from './pages/Dashboard';
+import Profile from './pages/Profile';
+
+export default function App() {
+  return (
+    <Router>
+      <Switch>
+        <Route path="/" component={Home} />
+        <Route path="/dashboard" component={Dashboard} />
+        <Route path="/:username" component={Profile} />
+      </Switch>
+    </Router>
+  );
+}
+```
+
 ### `<Switch />`
 
 A component that will only render the first of its children that matches the current URL. This is very useful to handle 404s, multiple routes matching, etc. For example, if you have a username system like `"/:username"` but want to have a help page, you can make it work easily with the switch:
@@ -356,11 +380,45 @@ setUrl({ ...url, path: "/" });
 setUrl({ ...url, query: { search: "hello" } });
 
 // Modify only one query param
-setUrl({ ...url, query: { ...url.query, safe: 0 } });
+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();
+useEffect(() => {
+  if (url.path === '/base') {
+    setUrl('/base/deeper');
+  }
+}, [url, 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:
+
+```js
+const [url, setUrl] = useUrl();
+useEffect(() => {
+  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' }`:
@@ -369,7 +427,7 @@ By default `setUrl()` will create a new entry in the browser history. If you wan
 setUrl("/newurl", { mode: "replace" });
 ```
 
-- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`.
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`. This is because `/b` and `/c` are both independent entries in your history.
 - `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/c` and then click on the back button, it'll go back to `/a`. This is because `/c` is overwriting `/b`, instead of adding a new entry.
 
 ### `usePath()`
@@ -389,8 +447,43 @@ const Login = () => {
 };
 ```
 
+The path is always a string equivalent to `window.location.pathname`.
+
 > 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')`
 
+#### Setter
+
+The setter can be invoked directly, or with a callback:
+
+```js
+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:
+
+```js
+const [path, setPath] = usePath();
+useEffect(() => {
+  if (path === '/base') {
+    setPath('/base/deeper');
+  }
+}, [path, setPath]);
+```
+
+If you update the path with the current path, it won't trigger a rerender. So the above can also be written as this, removing all dependencies:
+
+```js
+const [path, setPath] = usePath();
+useEffect(() => {
+  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' }`:
@@ -399,7 +492,7 @@ By default `setPath()` will create a new entry in the browser history. If you wa
 setPath("/newpath", { mode: "replace" });
 ```
 
-- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`.
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/c` and then click on the back button, the browser will go back to `/b`. This is because `/b` and `/b?q=c` are both independent entries in your history.
 - `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/c` and then click on the back button, it'll go back to `/a`. This is because `/c` is overwriting `/b`, instead of adding a new entry.
 
 ### `useQuery()`
@@ -439,18 +532,18 @@ When you update it, it will clean any parameter not passed, so make sure to pass
 const [query, setQuery] = useQuery();
 
 setQuery({ search: "myname" });
-// Goto /users?q=myname  (removes the filter)
+// Goto /users?search=myname  (removes the filter)
 
 setQuery({ ...query, search: "myname" });
-// Goto /users?q=myname&filter=new
+// Goto /users?search=myname&filter=new
 
 setQuery(prev => ({ ...prev, search: "myname" }));
-// Goto /users?q=myname&filter=new
+// Goto /users?search=myname&filter=new
 ```
 
 `setQuery` only modifies the query string part of the URL, keeping the `path` and `hash` the same as they were previously.
 
-When you set a search query to `null` or `false`, it will be removed from the URL. However, empty strings are not removed. So if you want empty strings to also remove the parameter in the URL, please do this:
+When you set a search query to `null` it will be removed from the URL. However, empty strings `""`, zero `0` or boolean `false` are not removed. So if you want falsy values to also remove the parameter in the URL, please do this:
 
 ```js
 const [myname, setMyname] = useQuery("myname");
@@ -460,7 +553,7 @@ const [myname, setMyname] = useQuery("myname");
 setMyname(newName || null);
 ```
 
-If you are using `react-query` and already have a bunch of `useQuery()` in your code and prefer to use other name, just rename this method when importing it:
+If you are using `react-query` and already have a bunch of `useQuery()` in your code and prefer to use other name, you can rename this method when importing it:
 
 ```js
 import { useQuery as useSearch } from 'crossroad';
@@ -475,7 +568,7 @@ By default `setQuery()` will create a new entry in the browser history. If you w
 setQuery({ search: "abc" }, { mode: "replace" });
 ```
 
-- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b?q=c` and then click on the back button, the browser will go back to `/b`.
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b?q=c` and then click on the back button, the browser will go back to `/b`. This is because `/b` and `/b?q=c` are both independent entries in your history.
 - `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/b?q=c` and then click on the back button, it'll go back to `/a`. This is because `/b?q=c` is overwriting `/b`, instead of adding a new entry.
 
 ### `useHash()`
@@ -507,7 +600,7 @@ By default `setHash()` will create a new entry in the browser history. If you wa
 setHash("newhash", { mode: "replace" });
 ```
 
-- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b#c` and then click on the back button, the browser will go back to `/b`.
+- `push` (default): creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(push)> `/b#c` and then click on the back button, the browser will go back to `/b`. This is because `/b` and `/b?q=c` are both independent entries in your history.
 - `replace`: creates a new entry in the history. E.g. if you navigate `/a` => `/b` =(replace)> `/b#c` and then click on the back button, it'll go back to `/a`. This is because `/b#c` is overwriting `/b`, instead of adding a new entry.
 
 ### `useParams()`
@@ -839,7 +932,7 @@ export default function Mock({ url, children }) {
   // Undo the setup when the component unmounts
   useEffect(() => {
     return () => Object.defineProperty(window, "location", oldLocation);
-  });
+  }, []);
   return <div>{children}</div>;
 }
 ```