routexiz 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 delpikye-v
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,566 @@
+# 🕹️ routexiz
+
+[![NPM](https://img.shields.io/npm/v/routexiz.svg)](https://www.npmjs.com/package/routexiz) ![Downloads](https://img.shields.io/npm/dt/routexiz.svg)
+
+<a href="https://codesandbox.io/p/sandbox/2lslks" target="_blank">LIVE EXAMPLE</a>
+
+A lightweight, powerful, and modern router for React.
+
+Built with:
+- ⚡ Suspense-first data loading
+- 🧠 Guards & middlewares
+- 🔗 Nested routing
+- 🚀 Prefetching & caching
+- 🧩 Fully flexible architecture
+
+---
+
+# Why routexiz?
+
+Traditional routing:
+```ts
+navigate("/users/1")
+```
+
+routexiz:
+```ts
+navigate("/users/:id", {
+  params: { id: 1 }
+})
+```
+
+- ⚡ Suspense data loading (like React 18 philosophy)
+- 🧠 Guards (before navigation)
+- 🔧 Middleware (side-effects)
+- 🔁 Nested routing builder API
+- 🚀 Prefetch (hover + viewport)
+- 🧩 Loader caching with TTL
+- ❌ Error boundary per route
+- 🎨 Transition support
+
+---
+
+# Installation
+
+```bash
+npm install routexiz
+```
+
+---
+
+# Quick Start
+
+```tsx
+import { route, RouterProvider } from "routexiz"
+
+route("/", () => <div>Home</div>)
+
+export default function App() {
+  return <RouterProvider />
+}
+```
+
+---
+
+# Routing API
+
+<b>route()</b>
+
+```ts
+route(path, component, config?)
+```
+
+<b>builder API</b>
+
+```ts
+route("/", Layout, root => {
+  root.route("/dashboard", Dashboard, dash => {
+    dash.guard(fn)
+    dash.middleware(fn)
+    dash.meta({ title: "Dashboard" })
+  })
+})
+```
+
+---
+
+# Navigation
+
+## useNavigate
+
+```ts
+const navigate = useNavigate()
+
+navigate("/users/:id", {
+  params: { id: 1 },
+  query: { tab: "profile" }
+})
+```
+
+---
+
+## Link
+
+```tsx
+<Link
+  to="/users/:id"
+  params={{ id: 1 }}
+  query={{ tab: "profile" }}
+>
+  Open User
+</Link>
+```
+
+## NavLink 
+```ts
+<NavLink
+  to="/users/:id"
+  params={{ id: 1 }}
+  className={({ isActive }) => isActive ? "active" : ""}
+>
+  Open User
+</NavLink>
+```
+
+---
+
+# Data Loading
+
+```ts
+route("/users/:id", User, {
+  loader: async ({ params }) => fetchUser(params.id)
+})
+
+// Access loader data:
+const data = useRouteData()
+```
+
+### Access data
+
+```ts
+const data = useRouteData()
+```
+
+---
+
+# Guards
+
+```ts
+dash.guard(({ params }) => {
+  if (!isLoggedIn()) return false
+})
+```
+
+---
+
+# Middleware
+
+```ts
+dash.middleware(async ({ params }) => {
+  console.log("run side effects")
+})
+```
+
+---
+
+# Prefetch
+
+- Hover
+- Viewport (IntersectionObserver)
+
+```tsx
+import { Link } from "routexiz"
+
+export default function UsersList() {
+  return (
+    <div>
+      <h2>Users</h2>
+      {/* Prefetch on hover */}
+      <Link to="/users/1" params={{ id: 1 }} query={{ tab: "profile" }}>
+        User 1 (hover to prefetch)
+      </Link>
+
+      {/* Prefetch when enters viewport */}
+      <Link to="/users/2" params={{ id: 2 }} query={{ tab: "profile" }}>
+        User 2 (prefetch on viewport)
+      </Link>
+    </div>
+  )
+}
+```
+
+---
+
+# Error Handling
+
+```ts
+route("/users/:id", User, {
+  errorBoundary: ({ error }) => <div>Error: {String(error)}</div>
+})
+```
+
+---
+
+# Fallback
+
+```ts
+route("/users/:id", User, {
+  fallback: <div>Loading...</div>
+})
+```
+
+---
+
+# Lazy
+
+```ts
+import React, { Suspense } from "react"
+import { route, RouterProvider } from "routexiz"
+
+// Lazy load page
+const Dashboard = React.lazy(() => import("./pages/Dashboard"))
+
+route("/", Dashboard, {
+  fallback: <div>Loading Dashboard...</div>,
+})
+```
+
+---
+
+# Cache (TTL)
+
+## Declare route with cache
+```ts
+route("/users/:id", User, {
+  loader: async ({ params }) => {
+    const res = await fetch(`https://jsonplaceholder.typicode.com/users/${params.id}`)
+    if (!res.ok) throw new Error("User not found")
+    return res.json()
+  },
+  ttl: 5000, // cache expires in 5 seconds
+  fallback: <div>Loading user...</div>,
+  errorBoundary: ({ error }) => <div>Error: {String(error)}</div>
+})
+```
+
+## Access cached data inside component
+```ts
+import { useRouteData, useParams } from "routexiz"
+
+function User() {
+  const data = useRouteData<any>()
+  const params = useParams()
+
+  return (
+    <div>
+      User {params.id}
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  )
+}
+
+```
+## Prefetch / warm up cache
+```ts
+import { prefetch } from "routexiz"
+
+// Prefetch user 1 in background
+prefetch("/users/1")
+```
+
+## Cleanup expired cache
+```ts
+import { cleanupCache } from "routexiz"
+
+// Remove all expired resources
+cleanupCache()
+
+// Remove only 10 oldest expired items
+cleanupCache(10)
+```
+
+> TTL cache ensures route loaders are cached for fast navigation and automatically cleaned after expiry.
+
+---
+
+# Global Fallback & Error
+
+`routexiz` allows you to configure global fallback UI and global error boundaries for your entire app.
+
+## Set Global Fallback
+```ts
+import { setGlobalFallback } from "routexiz"
+
+// Enable global fallback with a custom loader
+setGlobalFallback(true, <div>App is loading...</div>)
+```
+
+- If a route does not provide its own fallback, this global fallback will be used.
+
+- Works with Suspense loaders.
+
+## Set Global Error
+```ts
+import { setGlobalError } from "routexiz"
+
+// Enable global error handling with a custom render
+setGlobalError(true, (error) => (
+  <div style={{ color: "red" }}>Oops! {String(error)}</div>
+))
+```
+
+- If a route does not provide its own errorBoundary, this global error component will be used.
+
+- Receives an error object and must return a valid React element.
+
+## Example with RouterProvider
+```ts
+import React, { Suspense } from "react"
+import { RouterProvider, setGlobalFallback, setGlobalError } from "routexiz"
+
+setGlobalFallback(true, <div>Loading app...</div>)
+setGlobalError(true, (error) => <div>Error occurred: {String(error)}</div>)
+
+export default function App() {
+  return (
+    <Suspense fallback={null}>
+      <RouterProvider />
+    </Suspense>
+  )
+}
+```
+
+- The Suspense wrapper can still override the global fallback if needed.
+
+- Per-route fallback and errorBoundary take priority over global settings.
+
+---
+
+# Hooks
+
+## useRouteData()
+
+Returns the data loaded by the route's loader. Suspense-aware.
+
+```ts
+import { useRouteData } from "routexiz"
+
+function User() {
+  const data = useRouteData<{ id: string; name: string }>()
+  return (
+    <div>
+      User {data.id}: {data.name}
+    </div>
+  )
+}
+
+```
+
+## useParams()
+
+Returns the dynamic route parameters.
+```ts
+import { useParams } from "routexiz"
+
+function User() {
+  const params = useParams()
+  return <div>User ID: {params.id}</div>
+}
+```
+
+## useRouteContext()
+
+Returns the current route path.
+
+```ts
+import { useRouteContext } from "routexiz"
+
+function CurrentRoute() {
+  const path = useRouteContext()
+  return <div>Current route: {path}</div>
+}
+```
+
+## useNavigation()
+
+Returns router state: loading, current path, and pending path.
+
+```ts
+import { useNavigation } from "routexiz"
+
+function NavStatus() {
+  const { loading, path, pendingPath } = useNavigation()
+  return (
+    <div>
+      {loading ? `Navigating to ${pendingPath}...` : `Current path: ${path}`}
+    </div>
+  )
+}
+```
+
+## useTransition()
+
+Returns transition info (name and stage). Useful for page animations.
+
+```ts
+import { useTransition } from "routexiz"
+
+function PageTransition() {
+  const { name, stage } = useTransition()
+  return <div>Transition {name}: {stage}</div>
+}
+```
+
+---
+
+# Full Example
+
+```ts
+import React from "react"
+import { Link, NavLink, RouterProvider, route, useRouteData, useParams } from "routexiz"
+
+/* =========================
+   PAGES
+========================= */
+function Home() {
+  return <div>Home Page</div>
+}
+
+function About() {
+  return <div>About Page</div>
+}
+
+function User() {
+  const params = useParams()
+  const data = useRouteData<any>()
+
+  return (
+    <div>
+      User Page {params.id}
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  )
+}
+
+/* =========================
+   ROUTES
+========================= */
+route("/", Home, root => {
+  root.route("/about", About)
+  root.route("/user/:id", User, {
+    loader: async ({ params }) => {
+      await new Promise(r => setTimeout(r, 400))
+      return { id: params.id, name: "User " + params.id }
+    },
+    fallback: <div>Loading user...</div>,
+    errorBoundary: ({ error }) => <div>Error: {String(error)}</div>
+  })
+})
+
+/* =========================
+   NAVIGATION
+========================= */
+function Navbar() {
+  return (
+    <nav style={{ marginBottom: 20 }}>
+      {/* Link */}
+      <Link
+        to="/"
+        className="link"
+        activeClassName="active-link"
+        style={{ marginRight: 10 }}
+      >
+        Home
+      </Link>
+
+      {/* NavLink */}
+      <NavLink
+        to="/about"
+        className={({ isActive }) => isActive ? "active-link" : "link"}
+        style={({ isActive }) => ({
+          marginRight: 10,
+          color: isActive ? "green" : "blue"
+        })}
+      >
+        About
+      </NavLink>
+
+      <NavLink
+        to="/user/1"
+        className={({ isActive }) => isActive ? "active-link" : "link"}
+        style={({ isActive }) => ({
+          marginRight: 10,
+          color: isActive ? "green" : "blue"
+        })}
+      >
+        User 1
+      </NavLink>
+
+      <NavLink
+        to="/user/2"
+        className={({ isActive }) => isActive ? "active-link" : "link"}
+        style={({ isActive }) => ({
+          color: isActive ? "green" : "blue"
+        })}
+      >
+        User 2
+      </NavLink>
+    </nav>
+  )
+}
+
+/* =========================
+   APP
+========================= */
+export default function App() {
+  return (
+    <div>
+      <h1>Link + NavLink Demo</h1>
+      <Navbar />
+      <RouterProvider />
+    </div>
+  )
+}
+```
+
+--- 
+
+# Comparison
+
+`routexiz` focuses on **modern React routing** with Suspense-first `data loading`, `nested routes`, `guards`, `middleware`, and `prefetch/caching`.  
+It’s lightweight and flexible, designed for client-side SPAs.
+
+
+| Criteria                  | routexiz | React Router | TanStack Router | Remix |
+| ------------------------- | -------- | ------------ | --------------- | ----- |
+| Nested routes builder API | ✅        | ✅           | ✅              | ✅    |
+| Suspense-first loaders    | ✅        | ⚠️           | ✅              | ✅    |
+| Guards & middleware       | ✅        | ⚠️           | ✅              | ⚠️    |
+| Prefetch / caching        | ✅        | ❌           | ✅              | ⚠️    |
+| Error boundary per route  | ✅        | ⚠️           | ✅              | ✅    |
+| Transition support        | ✅        | ❌           | ⚠️              | ⚠️    |
+| Lightweight & minimal     | ✅        | ⚠️           | ⚠️              | ⚠️    |
+
+---
+
+# Architecture
+
+```text
+Link / navigate
+   ↓
+matchRouteChain
+   ↓
+guards → middleware
+   ↓
+loader (cached)
+   ↓
+Suspense
+   ↓
+render tree
+```
+
+---
+
+# License
+
+MIT

package/build/components/Link.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    to: string;
+    transition?: string;
+    replace?: boolean;
+    activeClassName?: string;
+    onNavigate?: (to: string) => void;
+    partialMatch?: boolean;
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    hash?: string;
+    disablePrefetch?: boolean;
+}
+export declare function Link(props: LinkProps): JSX.Element;

package/build/components/LinkCore.d.ts

@@ -0,0 +1,23 @@
+type UseLinkCoreOptions = {
+    to: string;
+    transition?: string;
+    replace?: boolean;
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    hash?: string;
+    partialMatch?: boolean;
+    disablePrefetch?: boolean;
+};
+export declare function useLinkCore({ to, transition, replace, params, query, hash, partialMatch, disablePrefetch, }: UseLinkCoreOptions): {
+    ref: import("react").RefObject<HTMLAnchorElement>;
+    fullPath: string;
+    isActive: boolean;
+    go: () => void;
+};
+export declare const LinkCore: import("react").ForwardRefExoticComponent<import("react").AnchorHTMLAttributes<HTMLAnchorElement> & {
+    fullPath: string;
+    onNavigate: () => void;
+    onPrefetch?: () => void;
+    disablePrefetch?: boolean;
+} & import("react").RefAttributes<HTMLAnchorElement>>;
+export {};

package/build/components/NavLink.d.ts

@@ -0,0 +1,18 @@
+import React from "react";
+export interface NavLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'style'> {
+    to: string;
+    transition?: string;
+    replace?: boolean;
+    params?: Record<string, any>;
+    query?: Record<string, any>;
+    hash?: string;
+    partialMatch?: boolean;
+    disablePrefetch?: boolean;
+    className?: string | ((opts: {
+        isActive: boolean;
+    }) => string);
+    style?: React.CSSProperties | ((opts: {
+        isActive: boolean;
+    }) => React.CSSProperties);
+}
+export declare function NavLink(props: NavLinkProps): JSX.Element;

package/build/components/RouteTree.d.ts

@@ -0,0 +1,4 @@
+export declare function RenderTree({ chain, data }: {
+    chain: any[];
+    data: Record<string, any>;
+}): JSX.Element;

package/build/components/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./Link";
+export * from "./NavLink";
+export { useLinkCore } from "./LinkCore";

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./router";
+export * from "./components";

package/build/index.esm.js

@@ -0,0 +1 @@
+import e,{createContext as n,useContext as r,Suspense as t,useState as o,useEffect as a,forwardRef as i,useRef as s}from"react";import{jsx as c,jsxs as h,Fragment as u}from"react/jsx-runtime";import l from"joinclass";const d=n(null),p=n(null),f=n(null),m=n({loading:!1,path:"",pendingPath:""}),y=n({name:"",stage:"idle"});function g(){const e=r(d);return e?.read()}function w(){return r(p)}function v(){return r(f)}function P(){return r(m)}function b(){return r(y)}let q=!1,k=!1,N=c("div",{children:"Loading..."}),E=({error:e})=>h("div",{children:["Global Error: ",String(e)]});function x(e,n){q=e,n&&(N=n)}function S(e,n){k=e,n&&(E=({error:e})=>n(e))}function C(){return q}function F(){return k}function I(){return N}function K(){return E}class M extends e.Component{constructor(e){super(e),this.reset=()=>{this.setState(e=>({hasError:!1,error:null,resetKey:e.resetKey+1}))},this.state={hasError:!1,error:null,resetKey:0}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}render(){if(this.state.hasError){const e=this.props.errorBoundary??(F()?K():void 0),n=this.props.fallback??h("div",{children:["Error: ",String(this.state.error)]});return e?c(e,{error:this.state.error}):n}return c(e.Fragment,{children:this.props.children},this.state.resetKey)}}function R({resource:e,errorBoundary:n,children:r}){try{return e?.read(),c(u,{children:r})}catch(e){if(e instanceof Promise)throw e;const r=n??(F()?K():void 0);if(r)return c(r,{error:e});throw e}}function B({chain:e,data:n}){return c(u,{children:function r(o=0){const a=e[o];if(!a)return null;const i=a.node.component,s=n[a.node.path];if(!i)return r(o+1);let h=a.node.options?.fallback,u=a.node.parent;for(;!h&&u;)h=u.options?.fallback,u=u.parent;return!h&&C()&&(h=I()),c(M,{fallback:h,errorBoundary:a.node.options?.errorBoundary,children:c(t,{fallback:h,children:c(p.Provider,{value:a.node.path,children:c(d.Provider,{value:s,children:c(f.Provider,{value:a.params,children:c(R,{resource:s,errorBoundary:a.node.options?.errorBoundary,children:c(i,{children:r(o+1)})})})})})})})}()})}const D=new Map;function A(e=1/0){const n=Date.now();let r=0;for(const[t,o]of D.entries())if(o.expiry<=n&&(D.delete(t),r++,r>=e))break}function U(e,n,r,t){const o=Date.now(),a=D.get(e);if(a&&!t&&(!r||a.expiry>o))return a.resource;const i=L(n());return D.set(e,{resource:i,expiry:o+(r??0)}),i}function L(e,n){let r=n?"success":"pending",t=n??null;const o=e.then(e=>{r="success",t=e},e=>{r="error",t=e});return{read(){if("pending"===r)throw o;if("error"===r)throw t;return t},update(e){t=e,r="success"},get:()=>t}}function O(e){return e.startsWith("/")||(e="/"+e),"/"!==e&&e.endsWith("/")&&(e=e.slice(0,-1)),e}function W(e){return O(e).split("/").filter(Boolean)}function j(e){const[n,r]=e.split("#"),[t,o]=n.split("?"),a={};return o&&o.split("&").forEach(e=>{const[n,r]=e.split("=");n&&(a[decodeURIComponent(n)]=decodeURIComponent(r??""))}),{path:O(t),query:a,hash:r??""}}function $(e,n){const{path:r,query:t,hash:o}=j(n),a=W(r),i=e.map(e=>({node:e,segIndex:0,params:{},chain:[]}));for(;i.length;){const{node:e,segIndex:n,params:r,chain:s}=i.pop(),c=W(e.path);let h=0;const u={...r};for(;h<c.length;h++){const e=c[h],r=a[n+h];if(!r)break;if(e.startsWith(":"))u[e.slice(1)]=decodeURIComponent(r);else if(e!==r)break}if(h!==c.length)continue;const l=n+h,d=[...s,{node:e,params:u,query:t,hash:o}];if(l===a.length)return d;for(const n of e.children)i.push({node:n,segIndex:l,params:u,chain:d})}return null}function J(e,n,r,t){if(e=O(e),n)for(const r in n)e=e.replace(`:${r}`,encodeURIComponent(n[r]));if(r&&Object.keys(r).length){e+=`?${new URLSearchParams(r).toString()}`}return t&&(e+=`#${t}`),e}let G=[];function T(e,n,r){const t={path:e,component:n,children:[],options:{}};"function"==typeof r?z(t)(r):r&&(t.options=r),G.push(t)}function z(e){const n={guard:r=>(e.guardFns||(e.guardFns=[]),e.guardFns.push(r),n),middleware:r=>(e.middlewares||(e.middlewares=[]),e.middlewares.push(r),n),meta:r=>(e.meta=r,n),route(n,r,t){const o={path:n,component:r,children:[],options:{},guardFns:[],middlewares:[],parent:e};"function"==typeof t?z(o)(t):t&&(o.options=t),e.children.push(o);const a={guard:e=>(o.guardFns?.push(e),a),middleware:e=>(o.middlewares?.push(e),a),meta:e=>(o.meta=e,a),route(e,n,r){const t={path:e,component:n,children:[],options:{},guardFns:[],middlewares:[],parent:o};return"function"==typeof r?z(t)(r):r&&(t.options=r),o.children.push(t),a}};return a}};return e=>{e(n)}}function H(e,n){const r={};return e.forEach(e=>{const t=e.node.options?.loader;if(!t)return;const o=JSON.stringify({path:e.node.path,params:e.params,query:e.query,hash:e.hash}),a=e.node.options?.ttl,i=U(o,()=>t({params:e.params,path:e.node.path,query:e.query,hash:e.hash}),a,n?.forceReload);r[e.node.path]=i}),r}async function Q(e){const n=$(G,e);if(!n)return{};const r={};n.forEach(e=>{const n=e.node.options?.loader;n&&(r[e.node.path]=U(JSON.stringify({path:e.node.path,params:e.params,query:e.query,hash:e.hash}),()=>n({params:e.params,path:e.node.path,query:e.query,hash:e.hash}),e.node.options?.ttl))});for(const e in r)r[e].read();return r}function V(e){const n=$(G,e);n&&H(n,{forceReload:!1})}let X=null,Y=[],Z=[];function _(e){Y.push(e)}function ee(e){Z.push(e)}async function ne(e,n,r=!1){const t={...n,forceReload:n?.forceReload??!0},o=J(e,t.params,t.query,t.hash),a=await async function(e){return Promise.all(Y.map(n=>n(e))).then(e=>e.every(e=>!1!==e))}(o);if(!a)return console.warn("Navigation blocked by beforeNavigation hook",o);r?window.history.replaceState({},"",o):window.history.pushState({},"",o),X?.(o,t),async function(e){for(const n of Z)await n(e)}(o)}function re(e,n){return ne(e,n,!1)}function te(e,n){return re(e,n)}function oe(e){return P().path===e}function ae(e){return()=>V(e)}function ie(){const e=(e,n)=>ne(J(e,n?.params,n?.query,n?.hash),n);return e.replace=(e,n)=>ne(J(e,n?.params,n?.query,n?.hash),n,!0),e}function se(){const[e,n]=o({chain:[],data:{},loading:!1,path:"",pendingPath:"",transition:{name:"",stage:"idle"}});async function r(e,r){let t=$(G,e)??$(G,"*")??[];for(const n of t)for(const r of n.node.guardFns||[]){if(!await r({params:n.params,path:n.node.path,query:n.query,hash:n.hash}))return console.warn("Navigation blocked by guard",e)}for(const e of t)for(const n of e.node.middlewares||[])await n({params:e.params,path:e.node.path,query:e.query,hash:e.hash}).catch(console.error);n(n=>({...n,loading:!0,pendingPath:e,transition:{name:r?.transition||"fade",stage:"exiting"}}));const o=H(t,r);n(n=>({...n,chain:t,data:{...n.data,...o},loading:!1,path:e,pendingPath:"",transition:{name:r?.transition||"fade",stage:"entering"}})),window.scrollTo(0,0)}return a(()=>{X=r,r(window.location.pathname),window.addEventListener("popstate",()=>r(window.location.pathname))},[]),c(m.Provider,{value:{loading:e.loading,path:e.path,pendingPath:e.pendingPath},children:c(y.Provider,{value:e.transition,children:c(B,{chain:e.chain,data:e.data})})})}function ce({to:e,transition:n,replace:r,params:t,query:o,hash:i,partialMatch:c,disablePrefetch:h}){const u=ie(),l=P(),d=s(null),p=J(e,t,o,i),f=c?l.path?.startsWith(p):l.path===p;return a(()=>{if(h)return;const e=d.current;if(!e)return;const n=new IntersectionObserver(e=>{e.some(e=>e.isIntersecting)&&(V(p),n.disconnect())},{rootMargin:"200px"});return n.observe(e),()=>n.disconnect()},[p,h]),{ref:d,fullPath:p,isActive:f,go:()=>{r?u.replace(e,{transition:n,params:t,query:o,hash:i}):u(e,{transition:n,params:t,query:o,hash:i})}}}re.replace=(e,n)=>ne(e,n,!0);const he=i(({fullPath:e,onNavigate:n,onPrefetch:r,onClick:t,onMouseEnter:o,onKeyDown:a,disablePrefetch:i,...s},h)=>c("a",{ref:h,href:e,...s,onClick:e=>{t&&t(e),e.metaKey||e.ctrlKey||e.shiftKey||(e.preventDefault(),n())},onMouseEnter:e=>{o&&o(e),i||r?.()},onKeyDown:e=>{"Enter"===e.key&&(e.preventDefault(),n()),a&&a(e)}}));function ue(e){const{to:n,transition:r,replace:t,activeClassName:o="active",onNavigate:a,partialMatch:i,params:s,query:h,hash:u,className:d,disablePrefetch:p,...f}=e,{ref:m,fullPath:y,isActive:g,go:w}=ce({to:n,transition:r,replace:t,params:s,query:h,hash:u,partialMatch:i,disablePrefetch:p});return c(he,{ref:m,fullPath:y,onNavigate:()=>{w(),a?.(y)},onPrefetch:()=>V(y),className:l(d,g&&o),disablePrefetch:p,...f})}function le(e){const{to:n,transition:r,replace:t,params:o,query:a,hash:i,partialMatch:s,className:h,style:u,disablePrefetch:l,...d}=e,{ref:p,fullPath:f,isActive:m,go:y}=ce({to:n,transition:r,replace:t,params:o,query:a,hash:i,partialMatch:s,disablePrefetch:l}),g="function"==typeof h?h({isActive:m}):h,w="function"==typeof u?u({isActive:m}):u;return c(he,{ref:p,fullPath:f,onNavigate:y,onPrefetch:()=>V(f),className:g,style:w,disablePrefetch:l,...d})}he.displayName="LinkCore";export{ue as Link,d as LoaderDataContext,le as NavLink,f as ParamsContext,p as RouteContext,se as RouterProvider,m as RouterStateContext,y as TransitionContext,ee as addAfterNavigationHook,_ as addBeforeNavigationHook,J as buildPath,A as cleanupCache,L as createResource,K as getGlobalError,I as getGlobalFallback,U as getResource,F as getUseGlobalError,C as getUseGlobalFallback,Q as loadRouteData,$ as matchRouteChain,re as navigate,j as parseQueryHash,V as prefetch,te as redirect,T as route,S as setGlobalError,x as setGlobalFallback,ce as useLinkCore,ie as useNavigate,P as useNavigation,v as useParams,ae as usePrefetch,w as useRouteContext,g as useRouteData,oe as useRouteMatch,b as useTransition};

package/build/index.js

@@ -0,0 +1 @@
+"use strict";var e=require("react"),t=require("react/jsx-runtime"),r=require("joinclass");const n=e.createContext(null),o=e.createContext(null),a=e.createContext(null),s=e.createContext({loading:!1,path:"",pendingPath:""}),i=e.createContext({name:"",stage:"idle"});function c(){return e.useContext(s)}let u=!1,h=!1,p=t.jsx("div",{children:"Loading..."}),l=({error:e})=>t.jsxs("div",{children:["Global Error: ",String(e)]});function d(){return u}function f(){return h}function x(){return p}function m(){return l}class g extends e.Component{constructor(e){super(e),this.reset=()=>{this.setState(e=>({hasError:!1,error:null,resetKey:e.resetKey+1}))},this.state={hasError:!1,error:null,resetKey:0}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}render(){if(this.state.hasError){const e=this.props.errorBoundary??(f()?m():void 0),r=this.props.fallback??t.jsxs("div",{children:["Error: ",String(this.state.error)]});return e?t.jsx(e,{error:this.state.error}):r}return t.jsx(e.Fragment,{children:this.props.children},this.state.resetKey)}}function y({resource:e,errorBoundary:r,children:n}){try{return e?.read(),t.jsx(t.Fragment,{children:n})}catch(e){if(e instanceof Promise)throw e;const n=r??(f()?m():void 0);if(n)return t.jsx(n,{error:e});throw e}}function v({chain:r,data:s}){return t.jsx(t.Fragment,{children:function i(c=0){const u=r[c];if(!u)return null;const h=u.node.component,p=s[u.node.path];if(!h)return i(c+1);let l=u.node.options?.fallback,f=u.node.parent;for(;!l&&f;)l=f.options?.fallback,f=f.parent;return!l&&d()&&(l=x()),t.jsx(g,{fallback:l,errorBoundary:u.node.options?.errorBoundary,children:t.jsx(e.Suspense,{fallback:l,children:t.jsx(o.Provider,{value:u.node.path,children:t.jsx(n.Provider,{value:p,children:t.jsx(a.Provider,{value:u.params,children:t.jsx(y,{resource:p,errorBoundary:u.node.options?.errorBoundary,children:t.jsx(h,{children:i(c+1)})})})})})})})}()})}const w=new Map;function P(e,t,r,n){const o=Date.now(),a=w.get(e);if(a&&!n&&(!r||a.expiry>o))return a.resource;const s=b(t());return w.set(e,{resource:s,expiry:o+(r??0)}),s}function b(e,t){let r=t?"success":"pending",n=t??null;const o=e.then(e=>{r="success",n=e},e=>{r="error",n=e});return{read(){if("pending"===r)throw o;if("error"===r)throw n;return n},update(e){n=e,r="success"},get:()=>n}}function q(e){return e.startsWith("/")||(e="/"+e),"/"!==e&&e.endsWith("/")&&(e=e.slice(0,-1)),e}function C(e){return q(e).split("/").filter(Boolean)}function j(e){const[t,r]=e.split("#"),[n,o]=t.split("?"),a={};return o&&o.split("&").forEach(e=>{const[t,r]=e.split("=");t&&(a[decodeURIComponent(t)]=decodeURIComponent(r??""))}),{path:q(n),query:a,hash:r??""}}function k(e,t){const{path:r,query:n,hash:o}=j(t),a=C(r),s=e.map(e=>({node:e,segIndex:0,params:{},chain:[]}));for(;s.length;){const{node:e,segIndex:t,params:r,chain:i}=s.pop(),c=C(e.path);let u=0;const h={...r};for(;u<c.length;u++){const e=c[u],r=a[t+u];if(!r)break;if(e.startsWith(":"))h[e.slice(1)]=decodeURIComponent(r);else if(e!==r)break}if(u!==c.length)continue;const p=t+u,l=[...i,{node:e,params:h,query:n,hash:o}];if(p===a.length)return l;for(const t of e.children)s.push({node:t,segIndex:p,params:h,chain:l})}return null}function R(e,t,r,n){if(e=q(e),t)for(const r in t)e=e.replace(`:${r}`,encodeURIComponent(t[r]));if(r&&Object.keys(r).length){e+=`?${new URLSearchParams(r).toString()}`}return n&&(e+=`#${n}`),e}let N=[];function E(e){const t={guard:r=>(e.guardFns||(e.guardFns=[]),e.guardFns.push(r),t),middleware:r=>(e.middlewares||(e.middlewares=[]),e.middlewares.push(r),t),meta:r=>(e.meta=r,t),route(t,r,n){const o={path:t,component:r,children:[],options:{},guardFns:[],middlewares:[],parent:e};"function"==typeof n?E(o)(n):n&&(o.options=n),e.children.push(o);const a={guard:e=>(o.guardFns?.push(e),a),middleware:e=>(o.middlewares?.push(e),a),meta:e=>(o.meta=e,a),route(e,t,r){const n={path:e,component:t,children:[],options:{},guardFns:[],middlewares:[],parent:o};return"function"==typeof r?E(n)(r):r&&(n.options=r),o.children.push(n),a}};return a}};return e=>{e(t)}}function F(e,t){const r={};return e.forEach(e=>{const n=e.node.options?.loader;if(!n)return;const o=JSON.stringify({path:e.node.path,params:e.params,query:e.query,hash:e.hash}),a=e.node.options?.ttl,s=P(o,()=>n({params:e.params,path:e.node.path,query:e.query,hash:e.hash}),a,t?.forceReload);r[e.node.path]=s}),r}function S(e){const t=k(N,e);t&&F(t,{forceReload:!1})}let D=null,M=[],I=[];async function K(e,t,r=!1){const n={...t,forceReload:t?.forceReload??!0},o=R(e,n.params,n.query,n.hash),a=await async function(e){return Promise.all(M.map(t=>t(e))).then(e=>e.every(e=>!1!==e))}(o);if(!a)return console.warn("Navigation blocked by beforeNavigation hook",o);r?window.history.replaceState({},"",o):window.history.pushState({},"",o),D?.(o,n),async function(e){for(const t of I)await t(e)}(o)}function B(e,t){return K(e,t,!1)}function L(){const e=(e,t)=>K(R(e,t?.params,t?.query,t?.hash),t);return e.replace=(e,t)=>K(R(e,t?.params,t?.query,t?.hash),t,!0),e}function G({to:t,transition:r,replace:n,params:o,query:a,hash:s,partialMatch:i,disablePrefetch:u}){const h=L(),p=c(),l=e.useRef(null),d=R(t,o,a,s),f=i?p.path?.startsWith(d):p.path===d;return e.useEffect(()=>{if(u)return;const e=l.current;if(!e)return;const t=new IntersectionObserver(e=>{e.some(e=>e.isIntersecting)&&(S(d),t.disconnect())},{rootMargin:"200px"});return t.observe(e),()=>t.disconnect()},[d,u]),{ref:l,fullPath:d,isActive:f,go:()=>{n?h.replace(t,{transition:r,params:o,query:a,hash:s}):h(t,{transition:r,params:o,query:a,hash:s})}}}B.replace=(e,t)=>K(e,t,!0);const U=e.forwardRef(({fullPath:e,onNavigate:r,onPrefetch:n,onClick:o,onMouseEnter:a,onKeyDown:s,disablePrefetch:i,...c},u)=>t.jsx("a",{ref:u,href:e,...c,onClick:e=>{o&&o(e),e.metaKey||e.ctrlKey||e.shiftKey||(e.preventDefault(),r())},onMouseEnter:e=>{a&&a(e),i||n?.()},onKeyDown:e=>{"Enter"===e.key&&(e.preventDefault(),r()),s&&s(e)}}));U.displayName="LinkCore",exports.Link=function(e){const{to:n,transition:o,replace:a,activeClassName:s="active",onNavigate:i,partialMatch:c,params:u,query:h,hash:p,className:l,disablePrefetch:d,...f}=e,{ref:x,fullPath:m,isActive:g,go:y}=G({to:n,transition:o,replace:a,params:u,query:h,hash:p,partialMatch:c,disablePrefetch:d});return t.jsx(U,{ref:x,fullPath:m,onNavigate:()=>{y(),i?.(m)},onPrefetch:()=>S(m),className:r(l,g&&s),disablePrefetch:d,...f})},exports.LoaderDataContext=n,exports.NavLink=function(e){const{to:r,transition:n,replace:o,params:a,query:s,hash:i,partialMatch:c,className:u,style:h,disablePrefetch:p,...l}=e,{ref:d,fullPath:f,isActive:x,go:m}=G({to:r,transition:n,replace:o,params:a,query:s,hash:i,partialMatch:c,disablePrefetch:p}),g="function"==typeof u?u({isActive:x}):u,y="function"==typeof h?h({isActive:x}):h;return t.jsx(U,{ref:d,fullPath:f,onNavigate:m,onPrefetch:()=>S(f),className:g,style:y,disablePrefetch:p,...l})},exports.ParamsContext=a,exports.RouteContext=o,exports.RouterProvider=function(){const[r,n]=e.useState({chain:[],data:{},loading:!1,path:"",pendingPath:"",transition:{name:"",stage:"idle"}});async function o(e,t){let r=k(N,e)??k(N,"*")??[];for(const t of r)for(const r of t.node.guardFns||[]){if(!await r({params:t.params,path:t.node.path,query:t.query,hash:t.hash}))return console.warn("Navigation blocked by guard",e)}for(const e of r)for(const t of e.node.middlewares||[])await t({params:e.params,path:e.node.path,query:e.query,hash:e.hash}).catch(console.error);n(r=>({...r,loading:!0,pendingPath:e,transition:{name:t?.transition||"fade",stage:"exiting"}}));const o=F(r,t);n(n=>({...n,chain:r,data:{...n.data,...o},loading:!1,path:e,pendingPath:"",transition:{name:t?.transition||"fade",stage:"entering"}})),window.scrollTo(0,0)}return e.useEffect(()=>{D=o,o(window.location.pathname),window.addEventListener("popstate",()=>o(window.location.pathname))},[]),t.jsx(s.Provider,{value:{loading:r.loading,path:r.path,pendingPath:r.pendingPath},children:t.jsx(i.Provider,{value:r.transition,children:t.jsx(v,{chain:r.chain,data:r.data})})})},exports.RouterStateContext=s,exports.TransitionContext=i,exports.addAfterNavigationHook=function(e){I.push(e)},exports.addBeforeNavigationHook=function(e){M.push(e)},exports.buildPath=R,exports.cleanupCache=function(e=1/0){const t=Date.now();let r=0;for(const[n,o]of w.entries())if(o.expiry<=t&&(w.delete(n),r++,r>=e))break},exports.createResource=b,exports.getGlobalError=m,exports.getGlobalFallback=x,exports.getResource=P,exports.getUseGlobalError=f,exports.getUseGlobalFallback=d,exports.loadRouteData=async function(e){const t=k(N,e);if(!t)return{};const r={};t.forEach(e=>{const t=e.node.options?.loader;t&&(r[e.node.path]=P(JSON.stringify({path:e.node.path,params:e.params,query:e.query,hash:e.hash}),()=>t({params:e.params,path:e.node.path,query:e.query,hash:e.hash}),e.node.options?.ttl))});for(const e in r)r[e].read();return r},exports.matchRouteChain=k,exports.navigate=B,exports.parseQueryHash=j,exports.prefetch=S,exports.redirect=function(e,t){return B(e,t)},exports.route=function(e,t,r){const n={path:e,component:t,children:[],options:{}};"function"==typeof r?E(n)(r):r&&(n.options=r),N.push(n)},exports.setGlobalError=function(e,t){h=e,t&&(l=({error:e})=>t(e))},exports.setGlobalFallback=function(e,t){u=e,t&&(p=t)},exports.useLinkCore=G,exports.useNavigate=L,exports.useNavigation=c,exports.useParams=function(){return e.useContext(a)},exports.usePrefetch=function(e){return()=>S(e)},exports.useRouteContext=function(){return e.useContext(o)},exports.useRouteData=function(){const t=e.useContext(n);return t?.read()},exports.useRouteMatch=function(e){return c().path===e},exports.useTransition=function(){return e.useContext(i)};

package/build/router/contexts.d.ts

@@ -0,0 +1,25 @@
+export type TransitionStage = "idle" | "entering" | "exiting";
+export declare const LoaderDataContext: import("react").Context<any>;
+export declare const RouteContext: import("react").Context<string | null>;
+export declare const ParamsContext: import("react").Context<any>;
+export declare const RouterStateContext: import("react").Context<{
+    loading: boolean;
+    path: string;
+    pendingPath: string;
+}>;
+export declare const TransitionContext: import("react").Context<{
+    name: string;
+    stage: TransitionStage;
+}>;
+export declare function useRouteData<T = any>(): T;
+export declare function useRouteContext(): string | null;
+export declare function useParams(): any;
+export declare function useNavigation(): {
+    loading: boolean;
+    path: string;
+    pendingPath: string;
+};
+export declare function useTransition(): {
+    name: string;
+    stage: TransitionStage;
+};

package/build/router/core.d.ts

@@ -0,0 +1,29 @@
+import React from "react";
+import type { ReactNode } from "react";
+import type { BuilderRouteAPI, RouteOptions } from "./types";
+export declare function route<P = any, R = any>(path: string, component?: React.ComponentType<{
+    children?: ReactNode;
+}>, options?: ((api: BuilderRouteAPI) => void) | RouteOptions<P, R>): void;
+export declare function loadRouteData(path: string): Promise<Record<string, any>>;
+export declare function prefetch(path: string): void;
+export type NavigateOpts = {
+    transition?: string;
+    forceReload?: boolean;
+    params?: Record<string, string | number>;
+    query?: Record<string, string | number>;
+    hash?: string;
+};
+export declare function addBeforeNavigationHook(fn: (path: string) => boolean | Promise<boolean>): void;
+export declare function addAfterNavigationHook(fn: (path: string) => void | Promise<void>): void;
+export declare function navigate(path: string, opts?: NavigateOpts): Promise<void>;
+export declare namespace navigate {
+    var replace: (path: string, opts?: NavigateOpts) => Promise<void>;
+}
+export declare function redirect(path: string, opts?: NavigateOpts): Promise<void>;
+export declare function useRouteMatch(pathPattern: string): boolean;
+export declare function usePrefetch(path: string): () => void;
+export declare function useNavigate(): {
+    (path: string, opts?: NavigateOpts): Promise<void>;
+    replace(path: string, opts?: NavigateOpts): Promise<void>;
+};
+export declare function RouterProvider(): JSX.Element;

package/build/router/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contexts";
+export * from "./core";
+export * from "./resource";
+export * from "./setting";
+export * from "./types";
+export * from "./utils";

package/build/router/resource.d.ts

@@ -0,0 +1,11 @@
+export declare function cleanupCache(limit?: number): void;
+export declare function getResource<T>(key: string, loader: () => Promise<T>, ttl?: number, forceReload?: boolean): {
+    read(): unknown;
+    update(newData: unknown): void;
+    get(): unknown;
+};
+export declare function createResource<T>(promise: Promise<T>, existing?: T): {
+    read(): T | null;
+    update(newData: T): void;
+    get(): T | null;
+};

package/build/router/setting.d.ts

@@ -0,0 +1,8 @@
+export declare function setGlobalFallback(enable: boolean, fallback?: React.ReactNode): void;
+export declare function setGlobalError(enable: boolean, render?: (error: any) => React.ReactElement | null): void;
+export declare function getUseGlobalFallback(): boolean;
+export declare function getUseGlobalError(): boolean;
+export declare function getGlobalFallback(): import("react").ReactNode;
+export declare function getGlobalError(): import("react").ComponentType<{
+    error: any;
+}>;

package/build/router/types.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+type LoaderContext<P = any> = {
+    params: P;
+    path: string;
+    query?: Record<string, string>;
+    hash?: string;
+};
+export type RouteOptions<P = any, R = any> = {
+    loader?: (context: LoaderContext<P>) => Promise<R>;
+    meta?: Record<string, any>;
+    errorBoundary?: React.ComponentType<{
+        error: any;
+    }>;
+    fallback?: React.ReactNode;
+    ttl?: number;
+};
+export type GuardFn<P = any> = (context: LoaderContext<P>) => boolean | Promise<boolean>;
+export type MiddlewareFn<P = any> = (context: LoaderContext<P>) => any | Promise<any>;
+export type RouteNode<P = any, R = any> = {
+    path: string;
+    component?: React.ComponentType<{
+        children?: ReactNode;
+    }>;
+    children: RouteNode[];
+    options: RouteOptions<P, R>;
+    guardFns?: GuardFn<P>[];
+    middlewares?: MiddlewareFn<P>[];
+    meta?: Record<string, any>;
+    parent?: RouteNode;
+};
+export type BuilderRouteAPI = {
+    guard: (fn: GuardFn) => BuilderRouteAPI;
+    middleware: (fn: MiddlewareFn) => BuilderRouteAPI;
+    route: <P = any, R = any>(path: string, component?: React.ComponentType<{
+        children?: ReactNode;
+    }>, options?: ((api: BuilderRouteAPI) => void) | RouteOptions<P, R>) => BuilderRouteAPI;
+    meta: (obj: Record<string, any>) => BuilderRouteAPI;
+};
+export {};

package/build/router/utils.d.ts

@@ -0,0 +1,8 @@
+import type { RouteNode } from "./types";
+export declare function parseQueryHash(pathname: string): {
+    path: string;
+    query: Record<string, string>;
+    hash: string;
+};
+export declare function matchRouteChain(routes: RouteNode[], pathname: string): any[] | null;
+export declare function buildPath(path: string, params?: Record<string, any>, query?: Record<string, any>, hash?: string): string;

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "routexiz",
+  "version": "0.0.1",
+  "description": "Intent-based routing for React. Navigate by intent instead of URLs.",
+  "author": "Delpi.Kye",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+
+  "main": "./build/index.js",
+  "module": "./build/index.esm.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.esm.js",
+      "require": "./build/index.js"
+    }
+  },
+
+  "files": [
+    "build"
+  ],
+  
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rimraf build && rollup -c",
+    "watch": "rollup -c -w",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delpikye-v/routexiz.git"
+  },
+  "homepage": "https://github.com/delpikye-v/routexiz#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/routexiz/issues"
+  },
+  "keywords": [
+    "react",
+    "router",
+    "intent-router",
+    "navigation",
+    "intent-navigation",
+    "react-navigation",
+    "frontend",
+    "spa",
+    "routing"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "joinclass": "^1.1.2"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "rimraf": "^5.0.5",
+    "rollup": "^3.29.4",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}