crossroad 0.15.1 → 0.16.2

package/index.min.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossroad",
-  "version": "0.15.1",
+  "version": "0.16.2",
   "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

@@ -302,6 +302,8 @@ Some examples:
 Read and set the full URL:
 
 ```js
+import { useUrl } from "crossroad";
+
 export default function Login() {
   const [url, setUrl] = useUrl();
 
@@ -341,21 +343,35 @@ You can also set it fully or partially:
 ```js
 const [url, setUrl] = useUrl();
 
-setUrl("/#firsttime"); // [Shorthand] Redirect to home with a hashtag
-setUrl({ path: "/", hash: "firsttime" }); // Same as above
-setUrl({ ...url, path: "/" }); // Keep everything the same except the path
-setUrl({ ...url, query: { search: myQuery } }); // Set a full search query
-setUrl({ ...url, query: { ...url.query, safe: 0 } }); // Modify only one query param
+// [Shorthand] Redirect to home with a hashtag
+setUrl("/#firsttime");
+
+// Same as above, but specifying the parts
+setUrl({ path: "/", hash: "firsttime" });
+
+// Keep everything the same except the path
+setUrl({ ...url, path: "/" });
+
+// Set a full search query
+setUrl({ ...url, query: { search: "hello" } });
+
+// Modify only one query param
+setUrl({ ...url, query: { ...url.query, safe: 0 } });
 ```
 
 `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`.
 
-By default `setUrl()` will create a new entry in the browser history. If you want to instead replace the current entry you can pass a second parameter with `{ mode: 'replace' }`:
+#### 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", { 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`. 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.
+
 ### `usePath()`
 
 Read and set only the path(name) part of the URL:
@@ -375,36 +391,44 @@ const Login = () => {
 
 > 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')`
 
-By default `setPath()` will create a new entry in the browser history. If you want to instead replace the current entry you can pass a second parameter with `{ mode: 'replace' }`:
+#### 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("/newurl", { mode: "replace" });
+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`. 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()`
 
 Read and set only the search query parameters from the URL:
 
 ```js
-// In /users?search=name&filter=new
-const [query, setQuery] = useQuery();
-// { search: 'name', filter: 'new' }
+import { useQuery } from "crossroad";
 
-setQuery({ search: "myname" }); // Remove the other query params
-// Goto /users?search=myname
+export default function SearchInput() {
+  // In /users?search=
+  const [query, setQuery] = useQuery();
+  // [{ search: "" }, fn]
 
-setQuery({ ...query, search: "myname" }); // Keep the other query params
-// Goto /users?search=myname&filter=new
+  // Goes to /users?search={value}
+  const onChange = e => setQuery({ search: e.target.value });
+
+  return <input value={query.search} onChange={onChange} />;
+}
 ```
 
-If you pass a parameter, it can read and modify that parameter while keeping the others the same. This is specially useful in e.g. a search form:
+If you pass a key, it can read and modify that parameter while keeping the others the same. This is specially useful in e.g. a search form:
 
 ```js
 // In /users?search=name&filter=new
 const [search, setSearch] = useQuery("search");
 // 'name'
 
-setQuery("myname");
+setSearch("myname");
 // Goto /users?search=myname&filter=new
 ```
 
@@ -414,27 +438,46 @@ When you update it, it will clean any parameter not passed, so make sure to pass
 // In /users?search=name&filter=new
 const [query, setQuery] = useQuery();
 
-setQuery({ search: "myname" }); // Goto /users?q=myname  (removes the filter)
-setQuery({ ...query, search: "myname" }); // Goto /users?q=myname&filter=new
-setQuery(prev => ({ ...prev, search: "myname" })); // Goto /users?q=myname&filter=new
+setQuery({ search: "myname" });
+// Goto /users?search=myname  (removes the filter)
+
+setQuery({ ...query, search: "myname" });
+// Goto /users?search=myname&filter=new
+
+setQuery(prev => ({ ...prev, search: "myname" }));
+// 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.
 
-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' }`:
+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
-setQuery({ search: "abc" }, { mode: "replace" });
+const [myname, setMyname] = useQuery("myname");
+
+// ...
+
+setMyname(newName || null);
 ```
 
-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:
+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
-const [myname, setMyname] = useQuery("myname");
-// ...
-setWord(newName || null);
+import { useQuery as useSearch } from 'crossroad';
+...
 ```
 
+#### New history entry
+
+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" }, { 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`. 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()`
 
 Read and set only the hash part of the URL (without the `"#"`):
@@ -454,6 +497,19 @@ By default `setHash()` will create a new entry in the browser history. If you wa
 setHash("newhash", { mode: "replace" });
 ```
 
+If you want to remove the hash, pass a `null` or `undefined` to the setter.
+
+#### New history entry
+
+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", { 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`. 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()`
 
 Parse the current URL against the given reference:
@@ -464,6 +520,8 @@ const params = useParams("/users/:id");
 // { id: '2' }
 ```
 
+> Note: this returns a plain object, not a [value, setter] array
+
 It's not this method responsibility to match the url, just to attempt to parse it, so if there's no good match it'll just return an empty object (use a `<Route />` for path matching):
 
 ```js
@@ -667,9 +725,9 @@ In this case the order matters, because the generic NotFound will be matched wit
 
 > NOTE: this is a bad idea for SEO, but if that doesn't matter much for you go ahead and host your webapp in Github Pages
 
-Github pages is a bit particular in that as of this writing it does not allow for a generic redirect like most other static website servers, so we need to do a workaround with the `notfound.html` page.
+Github pages is a bit particular in that as of this writing it does not allow for a generic redirect like most other static website servers, so we need to do a workaround with the `404.html` page.
 
-This is because any of your visitors landing on `https://example.com/` will see the proper website (since that'll be directed to `docs/index.html`), but when the user lands on other paths like `https://example.com/info` it'll not find `docs/info.html` and thus render `nofound.html`.
+This is because any of your visitors landing on `https://example.com/` will see the proper website (since that'll be directed to `docs/index.html`), but when the user lands on other paths like `https://example.com/info` it'll not find `docs/info.html` and thus render `404.html`.
 
 So let's save the url and setup a redirect in `404.html`:
 
@@ -730,7 +788,7 @@ export default function App({ url }) {
 }
 ```
 
-Now let's see how to test it. The `url` prop will be undefined in the browser, so it'll use `window.location.href`, so it'll only apply to testing:
+How does it work? The `url` prop will be undefined when a user loads the app (since we **don't** add it to index.js), so it is only being written for testing. On the users' browser, since it's undefinde Crossroad will use `window.location.href` instead.
 
 ```js
 // App.test.js
@@ -759,6 +817,10 @@ describe("use the url prop", () => {
 
 This method is the simplest to get started, but some people don't like having to add code to the production website only for the testing environment. That's all fine, there's another way that is a bit harder to setup but it's also more accurate to the browser's real behavior.
 
+#### Mock window.location
+
+The previous method has **a big limitation**: it doesn't allow you to navigate within your app for a test, since it's always forcing the same url. To avoid this and be able to test better the real-world behavior, use this method.
+
 When you are running Jest, it creates a fake `window` already, so you can plug into that to mock the behavior for the duration of the test. Doing it with a React component makes it even smoother:
 
 ```js
@@ -823,7 +885,27 @@ describe("use the Mock component", () => {
 
 ### Server Side Render
 
-Crossroad has been tested with Next.js and should work both on the server as in the browser. When working on the server, and similar to [how we saw in testing](#testing-routes), we can overload the current url:
+Crossroad has been tested with these libraries/frameworks for SSR:
+
+- ✅ [Razzle](https://razzlejs.org/): it works adding a bit of config; Razzle bundles React Router Dom by default, so you need to install Crossroad, remove React Router Dom and add the code mentioned below.
+- ⚠️ [Next.js](https://nextjs.org/): it works, but is generally not needed since Next.js include its own router and file-based routing.
+- ❌ [Babel-Node](https://babeljs.io/docs/en/babel-node): BabelNode [doesn't support ECMAScript modules (ESM)](https://babeljs.io/docs/en/babel-node#es6-style-module-loading-may-not-function-as-expected), but you are **also** [not supposed to use `babel-node` for production anyway](https://babeljs.io/docs/en/babel-node#not-meant-for-production-use) so this is not a real framework for SSR.
+- Others? I couldn't find many other ways that people are running SSR that I could test.
+
+For Razzle (based on [these docs FaQ](https://razzlejs.org/docs/customization#transpilation-of-external-modules)):
+
+```js
+// razzle.config.js
+module.exports = {
+  modifyWebpackOptions({ options: { webpackOptions } }) {
+    webpackOptions.notNodeExternalResMatch = req => /crossroad/.test(req);
+    webpackOptions.babelRule.include.push(/crossroad/);
+    return webpackOptions;
+  }
+};
+```
+
+When working on the server, and similar to [how we saw in testing](#testing-routes), we can overload the current url:
 
 ```js
 // An express example
@@ -834,16 +916,12 @@ app.get("/users", (req, res) => {
 });
 
 app.get("/users/:id", (req, res) => {
-  const id = req.params.id;
-
   // {...} validate the `id` it here!
 
-  res.render(<App url={`/users/${id}`} />);
+  res.render(<App url={req.url} />);
 });
 ```
 
-There is a big warning in `babel-node` and that applies to us as well. Babel-node [doesn't work with proper EcmaScript Modules (ESM)](https://babeljs.io/docs/en/babel-node#es6-style-module-loading-may-not-function-as-expected) in libraries, so if you are using `babel-node` to compile your Node.js code from JSX to JS, it'll not work with Crossroad. `babel-node` is also [not supposed to be used in production](https://babeljs.io/docs/en/babel-node#not-meant-for-production-use) anyway, so it should not be a big deal.
-
 ## React Router diff
 
 This part of the documentation tries to explain in detail the differences between Crossroad and React Router (Dom). Crossroad goal is to build a modern Router API from scratch, removing the legacy code and using Hooks natively.