crossroad 1.3.3 → 2.0.0

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossroad",
-  "version": "1.3.3",
+  "version": "2.0.0",
   "description": "A React library to handle navigation easily in your WebApp",
   "homepage": "https://crossroad.page/",
   "repository": "https://github.com/franciscop/crossroad.git",
@@ -38,7 +38,8 @@
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "react": "^18.3.1",
-    "react-test": "^0.21.3",
+    "react-dom": "^18.3.1",
+    "react-test": "^0.22.1",
     "rollup": "^1.32.1",
     "rollup-plugin-babel": "^4.4.0",
     "rollup-plugin-terser": "^5.2.0"

package/readme.md

@@ -26,7 +26,7 @@ export default function App() {
       <Switch redirect="/">
         <Route path="/" component={Home} />
         <Route path="/users" component={Users} />
-        <Route path="/users/:id" component={Profile} />
+        <Route path="/users/:id<number>" component={Profile} />
       </Switch>
     </Router>
   );
@@ -200,12 +200,14 @@ The `<Switch>` component only accepts `<Route>` as its children.
 
 This component defines a conditional path that, when strictly matched, renders the given component. Its props are:
 
-- `path`: the path to match to the current browser's URL. It can have parameters `/:id` and a wildcard at the end `*` to make it a partial route.
+- `path`: the path to match to the current browser's URL. It can have parameters `/:id`, with optional types like `/:id<number>`, and a wildcard at the end `*` to make it a partial route.
 - `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.
 
+> Exactly one of "component | render | children" props must be defined, not 0, not multiple.
+
 So for example if the `path` prop is `"/user"` and you visit the page `"/user"`, then the component is rendered; it is ignored otherwise:
 
 ```js
@@ -225,17 +227,23 @@ So for example if the `path` prop is `"/user"` and you visit the page `"/user"`,
 When matching a path with a parameter (a part of the url that starts with `:`) it will be passed as a prop straight to the children:
 
 ```js
-// In https://example.com/user/abc
-const User = ({ id }) => <div>Hello {id}</div>;
+// In https://example.com/user/25
+const User = ({ id }) => <div>Hello {id} ({typeof id})</div>;
 const UserList = () => <div>List here</div>;
 
 <Route path="/user/:id" component={User} />;
-// <div>Hello abc</div>
+// <div>Hello 25 (string)</div>
+
+<Route path="/user/:id<number>" component={User} />;
+// <div>Hello 25 (number)</div>
 
 <Route path="/user/:id" render={({ id }) => <User id={id} />} />;
-// <div>Hello abc</div>
+// <div>Hello 25 (string)</div>
+
+<Route path="/user/:id<number>" render={({ id }) => <User id={id} />} />;
+// <div>Hello 25 (number)</div>
 
-// Avoid when you need the params, since they cannot be passed
+// Avoid when you need the params, since they cannot be passed easily
 <Route path="/user/">
   <UserList />
 </Route>;
@@ -278,6 +286,18 @@ It can also match query parameters:
 <Route path="/profile?page=options" component={User} />  // Wrong value
 ```
 
+Finally, it can also attempt to convert the types to the specified format. It does _not_ run validation. The only really useful type right now is `number` and `date` (`string` is the default so no need for it):
+
+```jsx
+<Route path="/user/:id<number>" render={({ id }) => {
+  console.log(id, typeof id);  // 25 number
+}} />;
+
+<Route path="/metrics/:time<date>" render={({ time }) => {
+  console.log(time, typeof time);  // Jan 25th, 2055 Date
+}} />;
+````
+
 ### `<a>`
 
 Links with Crossroad are just traditional plain `<a>`. You write the URL and a relative path, and Crossroad handles all the history, routing, etc:
@@ -622,24 +642,52 @@ setHash("newhash", { mode: "replace" });
 
 ### `useParams()`
 
-Parse the current URL against the given reference:
+Get the parameters from the matched URL, already parsed as an object, or pass an argument to just get the key:
 
-```js
-// In /users/2
-const params = useParams("/users/:id");
-// { id: '2' }
+```ts
+function Profile() {
+  const { username } = useParams();
+  // or
+  const username = useParams('username');
+  return <div>Hello {username}</div>;
+}
 ```
 
-> Note: this returns a plain object, not a [value, setter] array
+The path in the [Route](#route) can also specify the type. Whenever possible it's preferable to use the props (since those can be type-checked automatically):
+
+```js
+function Profile({ id }: { id: number }) {
+  return <div>Hello {id}</div>;
+}
+
+<Route path="/users/:id<number>" component={Profile} />
+````
 
-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):
+Because with React Context we cannot infer the types properly, so if you want to differentiate between string | number you can do so with:
 
 ```js
-// In /pages/settings
-const params = useParams("/users/:id");
-// {}
+// <Route path="/users/:id/books/:bookId" ... />
+const userId = useParams<string>("id");  // "25"
+const bookId = useParams<string>("bookId");  // "55"
+
+
+// <Route path="/users/:id<number>/books/:bookId<number>" ... />
+const userId = useParams<number>("id");  // 25
+const bookId = useParams<number>("bookId");  // 55
 ```
 
+You can also type the whole list of params, but we recommend using useParams() with the key argument:
+
+```js
+// <Route path="/users/:id/books/:bookId" ... />
+const params = useParams<{ id: string, bookId: string }>();
+// { id: "25", bookId: "55" }
+
+// <Route path="/users/:id<number>/books/:bookId<number>" ... />
+const params = useParams<{ id: number, bookId: number }>();
+// { id: 25, bookId: 55 }
+````
+
 ## Examples
 
 ### Static routes
@@ -767,6 +815,46 @@ export default function SearchForm() {
 
 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.
 
+### Dynamic Pagination
+
+This example shows how to use path params with mixed types to track the current page in the URL, enabling bookmarkable, dynamic list navigation. Clicking "Previous" or "Next" updates the page number:
+
+```tsx
+import Router, { Switch, Route, useQuery, useParams } from "crossroad";
+
+const Category = ({ category, page }) => {
+  const posts = fetchPosts(category, page); // Simulated API call
+
+  return (
+    <div>
+      <h1>{category} Posts - Page {page}</h1>
+      <ul>{posts.map(post => <li key={post.id}>{post.title}</li>)}</ul>
+      <nav>
+        {page > 1 ? (
+          <a href={`/${category}/${page - 1}`}>Previous</a>
+        ) : 'Previous'}
+        <a href={`/${category}/${page + 1}`}>Next</a>
+      </nav>
+    </div>
+  );
+};
+
+export default function App() {
+  return (
+    <Router>
+      <nav>
+        <a href="/tech/1">Tech</a>
+        <a href="/lifestyle/1">Lifestyle</a>
+      </nav>
+      <Switch>
+        <Route path="/:category/:page<number>" component={Category} />
+        <Route path="/" component={() => <div>Home</div>} />
+      </Switch>
+    </Router>
+  );
+}
+```
+
 ### Query routing
 
 Some times you prefer the current page to be defined by the query, instead of by the pathname. This might be true for subpages, for tabs, or for other things depending on your app. With Crossroad it's easy to manage:

package/src/index.d.ts

@@ -1,47 +1,93 @@
 import React from "react";
 
-type FC<T> = React.FC<React.PropsWithChildren<T>>;
+// Helper type to parse parameter types from path string
+type ParseParamType<T extends string> = T extends `${infer Name}<${infer Type}>`
+  ? Type extends "number"
+    ? { [K in Name]: number }
+    : Type extends "string"
+      ? { [K in Name]: string }
+      : Type extends "date"
+        ? { [K in Name]: Date }
+        : Type extends "boolean"
+          ? { [K in Name]: boolean }
+          : { [K in Name]: string } // default to string
+  : T extends `${infer Name}`
+    ? { [K in Name]: string }
+    : never;
 
-declare const Router: FC<{ scrollUp?: boolean; url?: string }>;
+// Extracts all params from path and combines them
+type ExtractParams<T extends string> =
+  T extends `${infer Prefix}/:${infer Param}/${infer Rest}`
+    ? ParseParamType<Param> & ExtractParams<`/${Rest}`>
+    : T extends `${infer Prefix}/:${infer Param}`
+      ? ParseParamType<Param>
+      : {};
 
-declare const Route: <T = any>(props: {
+// Main Route component with type inference
+interface RouteProps<
+  T extends Record<string, string | number | boolean | Date> = {},
+> extends Omit<
+    {
+      path?: string;
+      scrollUp?: boolean;
+      component?: React.FunctionComponent<T>;
+      render?: (params: T) => React.ReactNode;
+      children?: React.ReactNode;
+    },
+    "component" | "render"
+  > {
   path?: string;
-  scrollUp?: boolean;
-  component?: React.FunctionComponent<T>;
-  render?: (params: T) => React.ReactNode;
-  children?: any;
-}) => any;
+}
+
+// Infer params from path string literal
+type InferParamsFromPath<T extends string> = T extends `${string}/:${string}`
+  ? ExtractParams<T>
+  : {};
+
+// Modified Route declaration with path-based inference
+declare const Route: <P extends string = string>(
+  props: RouteProps<InferParamsFromPath<P>> & { path?: P } & (
+      | {
+          component: React.FunctionComponent<InferParamsFromPath<P>>;
+          render?: never;
+        }
+      | {
+          render: (params: InferParamsFromPath<P>) => React.ReactNode;
+          component?: never;
+        }
+      | {}
+    ),
+) => React.ReactNode;
 
+// Rest of your original declarations remain the same
+type FC<T = {}> = React.FC<React.PropsWithChildren<T>>;
+declare const Router: FC<{ scrollUp?: boolean; url?: string }>;
 declare const Switch: FC<{
   redirect?: string | { path: string } | (() => string);
 }>;
-
-type Query = {
-  [key: string]: string;
-};
-
+type Query = Record<string, string>;
 type Url = URL & {
   path: string;
   query: Query;
   hash?: string;
 };
-
 type UrlSet = {
   path?: string;
   query?: Query;
   hash?: string;
 };
-
-declare const Context: React.Context<any>;
-
+type Params = Record<string, string | number | boolean | Date>;
 type Callable<T = string> = React.Dispatch<React.SetStateAction<T>>;
-
+declare const Context: React.Context<[Url, Callable<UrlSet | string>]>;
 declare function useUrl(): [Url, Callable<UrlSet | string>];
 declare function usePath(): [string, Callable<string>];
 declare function useQuery(): [Query, Callable<Query>];
-declare function useQuery(filter: string): [string, Callable<string>];
+declare function useQuery(key: string): [string, Callable<string>];
 declare function useHash(): [string, Callable<string>];
-declare function useParams(ref: string): any;
+declare function useParams<T = Params>(): T;
+declare function useParams<T = string | number | boolean | Date>(
+  key: string,
+): T;
 
 export default Router;
 export {