crossroad 1.3.2 → 2.0.0-alpha.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 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!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 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};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crossroad",
-  "version": "1.3.2",
+  "version": "2.0.0-alpha.1",
   "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<umber>" 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>;
@@ -622,24 +630,56 @@ 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):
 
-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
+function Profile({ id }: { id: number }) {
+  return <div>Hello {id}</div>;
+}
+
+<Route path="/users/:id<number>" component={Profile} />
+````
+
+Because with React Context we cannot infer the types properly, we strongly recommend to add the types when using useParams:
 
 ```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 strongly recommend doing it as shown previously:
+
+```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

package/src/index.d.ts

@@ -1,47 +1,88 @@
 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 "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> = {}>
+  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>;
 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>(key: string): T;
 
 export default Router;
 export {