intentx-react-router 1.0.4 → 1.1.0-z10

package/README.md

@@ -1,13 +1,12 @@
 # 🕹️ intentx-react-router
 
-[![NPM](https://img.shields.io/npm/v/intentx-react-router.svg)](https://www.npmjs.com/package/intentx-react-router) ![Downloads](https://img.shields.io/npm/dt/intentx-react-router.svg)
+[![NPM](https://img.shields.io/npm/v/intentx-react-router.svg)](https://www.npmjs.com/package/intentx-react-router) ![Downloads](https://img.shields.io/npm/dt/intentx-react-router.svg) ![Bundle Size](https://img.shields.io/bundlephobia/minzip/intentx-react-router)
 
 <a href="https://codesandbox.io/p/sandbox/q8gg5s" target="_blank">LIVE EXAMPLE</a>
 
-Intent‑based navigation layer for React applications.
+Intent-based navigation layer for React applications.
 
-Built on top of **React Router** and designed to work nicely with
-event‑driven architectures like **eventbus-z**.
+Built on top of React Router and designed for **domain-driven and event-driven navigation**.
 
 > Navigate by **intent**, not by URL.
 
@@ -23,6 +22,7 @@ navigate("/users/42/edit")
 Intent Router:
 ```ts
 navigateIntent("edit-user", 42)
+// → /users/42/edit
 ```
 
 <b>Benefits:</b>
@@ -32,7 +32,6 @@ navigateIntent("edit-user", 42)
 -   🔧 Easy URL refactor
 -   🧩 Micro‑frontend friendly
 -   📡 Event‑driven navigation support
--   🪶 Lightweight core (\~200 lines)
 
 ---
 
@@ -51,15 +50,41 @@ npm install intentx-react-router react-router@^7 react-router-dom@^7
 
 ---
 
+# Quick Start
+
+```tsx
+import { createIntentRouter, navigateIntent } from "intentx-react-router"
+
+createIntentRouter({
+  "view-user": "/users/:id",
+  "edit-user": "/users/:id/edit"
+})
+
+// navigate by intent
+navigateIntent("view-user", 42)
+```
+
+Result:
+```ts
+/users/42
+```
+
+---
+
 # Basic Setup
 
-## 1. Define intents
+## 1️⃣ Define intents
 
 ``` ts
 import { createIntentRouter, NavigateFn } from "intentx-react-router"
 
 createIntentRouter({
-  "view-user": "/users/:userId/name/:page",
+  "view-user": {
+    path: "/users/:userId/name/:page",
+    meta: {
+      title: "User Profile"
+    }
+  },
   "edit-user": "/users/:userId/edit",
   "checkout": "/checkout"
 })
@@ -73,12 +98,12 @@ export function bindRouterNavigate(navigate: NavigateFn) {
 
 ---
 
-## 2. Bind React Router navigate
+## 2️⃣ Bind React Router
 
 ``` ts
 import React from "react"
 import { useNavigate } from "react-router-dom"
-import { bindNavigate } from "intentx-react-router"
+import { bindRouterNavigate } from "./router"
 
 export function RouterBinder() {
   const navigate = useNavigate();
@@ -93,13 +118,17 @@ export function RouterBinder() {
 ```
 ---
 
-## 3. Use in App
+## 3️⃣ Use in App
 
 ```ts
 import React from "react"
 import { BrowserRouter, Routes } from "react-router-dom"
 import { IntentLink, IntentRoute } from "intentx-react-router"
+
 import { RouterBinder } from "./router"
+// or
+// import "./router"
+// import { RouterBinder } from "intentx-react-router"
 
 import { UserPage } from "./pages/UserPage"
 import { EditUserPage } from "./pages/EditUserPage"
@@ -125,6 +154,124 @@ export default function App() {
   )
 }
 ```
+
+IntentRoute automatically maps the intent path to a React Router route.
+
+---
+
+# Modular Router Setup
+## 1️⃣ Define intents
+
+```ts
+// intents/user-intents.ts
+export const userIntents = {
+  home: "/",
+  userProfile: "/users/:id",
+  settings: "/settings"
+}
+
+// intents/cart-intents.ts
+export const cartIntents = {
+  cart: "/cart",
+  checkout: "/checkout"
+}
+```
+
+---
+
+## 2️⃣ Setup router
+
+```ts
+// router/setupRouter.ts
+
+import { setupIntentRouter } from "intentx-react-router"
+
+import { userIntents } from "../intents/user-intents"
+import { cartIntents } from "../intents/cart-intents"
+
+export function setupRouter(navigate) {
+  setupIntentRouter({
+    intents: [
+      userIntents,
+      cartIntents
+    ],
+
+    guards: [
+      (intent, params) => {
+        console.log("Navigate:", intent, params)
+      }
+    ],
+
+    intentGuards: {
+      checkout() {
+        const cartReady = true
+
+        if (!cartReady) {
+          return "/cart"
+        }
+      }
+    },
+
+    navigate
+  })
+}
+```
+
+---
+
+## 3️⃣ Bind router to React Router
+
+```ts
+// App.tsx
+
+import { RouterBinder } from "intentx-react-router"
+import { setupRouter } from "./router/setupRouter"
+
+export default function App() {
+  return (
+    <>
+      <RouterBinder initializeRouter={setupRouter} />
+
+      {/* your routes */}
+    </>
+  )
+}
+```
+
+---
+
+## 4️⃣ Navigate using intent
+
+```ts
+import { navigateIntent } from "intentx-react-router"
+
+navigateIntent("userProfile", { id: 42 })
+
+navigateIntent("checkout")
+```
+
+Generated URL:
+
+```ts
+/users/42
+/checkout
+```
+
+---
+
+## 5️⃣ Object navigation
+```ts
+navigateIntentObject("userProfile", {
+  params: { id: 10 },
+  query: { tab: "posts" }
+})
+```
+
+Result:
+```ts
+/users/10?tab=posts
+```
+
 ---
 
 # Navigation
@@ -336,7 +483,7 @@ import { IntentRoute } from "intentx-react-router"
 
 # Guards
 
-Global guard:
+## Global guard
 
 ```ts
 addIntentGuard((intent, params) => {
@@ -348,7 +495,7 @@ addIntentGuard((intent, params) => {
 })
 ```
 
-Per‑intent guard:
+## Per-intent guard
 
 ```ts
 addIntentGuardFor("checkout", () => {
@@ -362,6 +509,38 @@ addIntentGuardFor("checkout", () => {
 
 ---
 
+## Guard inside intent
+
+You can attach guards directly to intents.
+
+```ts
+createIntentRouter({
+
+  "checkout": {
+    path: "/checkout",
+    guard: () => {
+      if (!isLoggedIn()) {
+        return "/login"
+      }
+    }
+  },
+
+  "admin": {
+    path: "/admin",
+    guard: () => {
+      if (!isAdmin()) {
+        return "/forbidden"
+      }
+    }
+  }
+
+})
+```
+
+This keeps route logic close to its definition.
+
+---
+
 # Preload
 
 Preload logic before navigation.
@@ -465,17 +644,257 @@ This allows:
 
 ---
 
+# Why not just use React Router?
+
+:contentReference[oaicite:1]{index=1} is an excellent routing library and intentx-react-router **does not replace it**.
+
+Instead, it adds a **navigation abstraction layer** on top of React Router.
+
+React Router focuses on **URL-driven navigation**, while intentx-react-router focuses on **intent-driven navigation**.
+
+---
+
+## React Router navigation
+
+In React Router, navigation is usually done by URLs:
+
+```ts
+navigate("/users/42/edit")
+```
+
+The application logic becomes tied to the URL structure.
+
+If the URL changes later:
+
+```text
+/users/:id/edit
+→
+/profile/:id/edit
+```
+
+You must update navigation code across the app.
+
+---
+
+## Intent navigation
+
+intentx-react-router introduces intent-based navigation.
+
+Instead of navigating by URL:
+
+```ts
+navigateIntent("edit-user", 42)
+```
+
+The router resolves the intent into a URL:
+
+```text
+/edit-user → /users/42/edit
+```
+
+If the URL changes later:
+
+```text
+/users/:id/edit
+→
+/profile/:id/edit
+```
+
+You only update the router definition:
+
+```ts
+createIntentRouter({
+  "edit-user": "/profile/:id/edit"
+})
+```
+
+---
+
 # Comparison
 
-| Criteria                | intent-router | React Router |
-|-------------------------|---------------|--------------|
-| Intent-based navigation | ✅            | ❌            |
-| URL refactor safety     | ✅            | ⚠️            |
-| Event-driven navigation | ✅            | ❌            |
-| Micro-frontend friendly | ✅            | ⚠️            |
-| Reverse routing         | ✅            | ❌            |
-| Type-safe intent params | ✅            | ⚠️            |
-| Query support           | ✅            | ⚠️            |
+intentx-react-router focuses on **intent-driven navigation** rather than URL-driven navigation.
+
+Instead of navigating by path strings, you navigate by **domain intent**.
+
+## vs React Router
+
+| Criteria                | intentx-react-router | React Router |
+|-------------------------|----------------------|--------------|
+| Intent-based navigation | ✅                   | ❌            |
+| URL refactor safety     | ✅                   | ⚠️            |
+| Event-driven navigation | ✅                   | ❌            |
+| Micro-frontend friendly | ✅                   | ⚠️            |
+| Reverse routing         | ✅                   | ❌            |
+| Type-safe intent params | ✅                   | ⚠️            |
+| Query support           | ✅                   | ⚠️            |
+
+
+<br />
+
+```ts
+// React Router:
+navigate("/users/42/edit")
+
+// intentx-react-router:
+navigateIntent("edit-user", 42)
+```
+
+---
+
+## vs TanStack Router
+
+:contentReference[oaicite:4]{index=4} is a powerful type-safe router with a full route tree and data loading system.
+
+| Criteria                | intentx-react-router | TanStack Router |
+| ----------------------- | -------------------- | --------------- |
+| Intent navigation       | ✅                    | ❌              |
+| Route tree system       | ❌                    | ✅              |
+| Data loaders            | ❌                    | ✅              |
+| Reverse routing         | ✅                    | ⚠️              |
+| Guards                  | ✅                    | ⚠️              |
+| Event-driven navigation | ✅                    | ❌              |
+| Micro-frontend friendly | ✅                    | ⚠️              |
+
+<br />
+
+Intent Router is designed to be minimal and flexible, especially for event-driven or micro-frontend architectures.
+
+---
+
+## vs Remix Router
+
+:contentReference[oaicite:5]{index=5} provides a full-stack routing system with loaders and server rendering.
+
+| Criteria                  | intentx-react-router  | Remix      |
+| ------------------------- | --------------------- | -----------|
+| Intent navigation         | ✅                    | ❌          |
+| Reverse routing           | ✅                    | ❌          |
+| Guards                    | ✅                    | ⚠️ loaders  |
+| Event-driven navigation   | ✅                    | ❌          |
+| Server loaders            | ❌                    | ✅          |
+| Full-stack routing        | ❌                    | ✅          |
+| Lightweight client router | ✅                    | ❌          |
+
+
+<br />
+
+Remix focuses on server-first routing, while intentx-react-router focuses on client-side intent navigation.
+
+---
+
+# Route Meta
+
+You can attach metadata to intents.
+
+This is useful for:
+
+- auth
+- role permission
+- page title
+- layout selection
+- analytics
+
+---
+
+## Define meta
+
+```ts
+createIntentRouter({
+
+  "home": "/",
+
+  "dashboard": {
+    path: "/dashboard",
+    meta: {
+      title: "Dashboard",
+      auth: true
+    }
+  },
+
+  "admin": {
+    path: "/admin",
+    meta: {
+      title: "Admin Panel",
+      auth: true,
+      role: "admin"
+    }
+  }
+
+})
+```
+
+---
+
+## Read meta
+
+```ts
+import { getIntentMeta } from "intentx-react-router"
+
+const meta = getIntentMeta("admin")
+
+console.log(meta)
+```
+
+Result:
+
+```ts
+{
+  title: "Admin Panel",
+  auth: true,
+  role: "admin"
+}
+```
+
+---
+
+## Meta with guards
+
+Meta works perfectly with guards.
+
+```ts
+addIntentGuard((intent) => {
+
+  const meta = getIntentMeta(intent)
+
+  if (meta?.auth && !isLoggedIn()) {
+    return "/login"
+  }
+
+})
+```
+
+Example with role protection:
+
+```ts
+addIntentGuard((intent) => {
+
+  const meta = getIntentMeta(intent)
+
+  if (meta?.role === "admin" && !isAdmin()) {
+    return "/forbidden"
+  }
+
+})
+```
+
+---
+
+## Meta in React
+
+You can also read meta inside components.
+
+```ts
+import { useIntentRouter, getIntentMeta } from "intentx-react-router"
+
+function PageHeader() {
+
+  const { intent } = useIntentRouter()
+
+  const meta = getIntentMeta(intent)
+
+  return <h1>{meta?.title}</h1>
+}
+```
 
 ---
 
@@ -483,20 +902,29 @@ This allows:
 
 ```text
 Component
-    ↓
+   ↓
 navigateIntent()
-    ↓
-eventbus-z
-    ↓
+   ↓
 Intent Router
-    ↓
+   ↓
+(eventbus-z optional)
+   ↓
 React Router navigate()
-    ↓
-URL
+   ↓
+  URL
 ```
 
 ---
 
+# Debug Mode
+
+Enable debug logs:
+
+```js
+window.__INTENT_ROUTER_DEBUG__ = true
+
+---
+
 # License
 
 MIT

package/build/core/env.d.ts

@@ -0,0 +1 @@
+export declare const __DEV__: boolean;

package/build/core/index.d.ts

@@ -1 +1,2 @@
 export * from "./intentCore";
+export * from "./setupIntentRouter";

package/build/core/intentCore.d.ts

@@ -1,38 +1,49 @@
 import type { GlobalBus } from "eventbus-z";
-export type NavigateIntentOptions<P = any> = {
-    params?: P | any[] | string | number;
+export type IntentSchema = Record<string, {
+    params?: Record<string, any>;
     query?: Record<string, any>;
-    options?: {
-        replace?: boolean;
-        scrollTop?: boolean;
-    };
-};
+}>;
 export type NavigateOptions = {
     replace?: boolean;
     scrollTop?: boolean;
     [key: string]: any;
 };
-type IntentMap = Record<string, string>;
-type GuardFn = (intent: string, params: any) => boolean | string | void;
+export type NavigateIntentOptions<P = any> = {
+    params?: P | any[] | string | number;
+    query?: Record<string, any>;
+    options?: NavigateOptions;
+};
 export type NavigateFn = (path: string, options?: NavigateOptions) => void;
+type GuardFn = ((intent: string, params: any) => boolean | string | void | Promise<boolean | string | void>);
 type PreloadFn = () => Promise<any> | void;
-export declare function createIntentRouter(map: IntentMap): void;
+type IntentMeta = Record<string, any> | ((params: any) => Record<string, any>);
+type IntentConfig = {
+    path: string;
+    meta?: IntentMeta;
+    guard?: GuardFn;
+    preload?: PreloadFn;
+};
+type IntentMapInput = Record<string, string | IntentConfig>;
+export declare function registerIntents(map: IntentMapInput): void;
+export declare function bootstrapRouter(): void;
+export declare function createIntentRouter(map: IntentMapInput): void;
+export declare function getIntentMeta(intent: string, params?: any): any;
+export declare function setIntentMeta(intent: string, meta: IntentMeta): void;
 export declare function bindNavigate(fn: NavigateFn): void;
 export declare function setFallbackPath(path: string): void;
-export declare function navigateIntent<P = any>(intent: string, params?: P | any[] | string | number, query?: Record<string, any>, options?: {
-    replace?: boolean;
-    scrollTop?: boolean;
-}): void;
-export declare function navigateIntentObject<P = any>(intent: string, navigateIntentOption?: NavigateIntentOptions<P>): void;
+export declare function warnRouterNotReady(intent: string): void;
+export declare function navigateIntent(intent: string, params?: any, query?: Record<string, any>, options?: NavigateOptions): void;
+export declare function navigateIntentObject<P = any>(intent: string, args?: NavigateIntentOptions<P>): void;
 export declare function addIntentGuard(fn: GuardFn): void;
 export declare function addIntentGuardFor(intent: string, fn: GuardFn): void;
 export declare function addIntentPreload(intent: string, fn: PreloadFn): void;
 export declare function preloadIntent(intent: string): void;
-export declare function generatePathFromIntent(intent: string, params?: Record<string, any> | any[] | string | number, query?: Record<string, any>): string;
+export declare function generatePathFromIntent(intent: string, params?: any, query?: Record<string, any>): string;
 export declare function resolveIntentFromUrl(url: string): {
     intent: string;
     params: Record<string, any>;
     query: Record<string, any>;
 } | null;
+export declare function syncIntentFromUrl(url: string): void;
 export declare function setSharedBus(externalBus: GlobalBus): void;
 export {};

package/build/core/setupIntentRouter.d.ts

@@ -0,0 +1,9 @@
+type GuardFn = (intent: string, params: any) => any;
+type SetupOptions = {
+    intents?: Record<string, any>[];
+    guards?: GuardFn[];
+    intentGuards?: Record<string, GuardFn>;
+    navigate?: (path: string, options?: any) => void;
+};
+export declare function setupIntentRouter({ intents, guards, intentGuards, navigate }?: SetupOptions): void;
+export {};

package/build/index.esm.js

@@ -1 +1 @@
-import{createEventBus as n}from"eventbus-z";import{jsx as t,Fragment as o,jsxs as r}from"react/jsx-runtime";import{Link as e,useLocation as i,useNavigate as c,BrowserRouter as u}from"react-router-dom";import{useEffect as s}from"react";const a=n();let f=null;let l={},p=null,m=!1;const d=[],h={},T={};let y=null;const E="undefined"!=typeof window&&!0===window.__INTENT_ROUTER_DEBUG__;function A(...n){E&&console.log("[IntentRouter]",...n)}function N(n){if(!n)return"";const t=new URLSearchParams;for(const o in n){const r=n[o];null!=r&&(Array.isArray(r)?r.forEach(n=>t.append(o,String(n))):t.append(o,String(r)))}const o=t.toString();return o?`?${o}`:""}function w(n){l=n,A("intent map loaded",n)}function I(n){p&&p!==n&&E&&console.warn("IntentRouter navigate replaced"),p=n,m||(a.$onMultiple("INTENT_NAVIGATE",G),m=!0)}function g(n){y=n}function _(n,t,o,r){A("emit",n,{params:t,query:o});const e={intent:n,params:t,query:o,...r?{options:r}:{}};a.$emit("INTENT_NAVIGATE",e),f&&f.$emit("INTENT_NAVIGATE",e)}function $(n,t){const{params:o,query:r,options:e}=t||{};A("emit",n,{params:o,query:r});const i={intent:n,params:o,query:r,...e?{options:e}:{}};a.$emit("INTENT_NAVIGATE",i),f&&f.$emit("INTENT_NAVIGATE",i)}function q(n){d.push(n)}function v(n,t){h[n]||(h[n]=[]),h[n].push(t)}function R(n,t){T[n]||(T[n]=[]),T[n].push(t)}function k(n){S(n)}async function G(n){const t=l[n.intent];if(A("receive",n.intent,n),!t)return y&&p?.(y),void console.warn("Unknown intent:",n.intent);const o=V(t,n.params);for(const t of d){const r=await t(n.intent,o);if(!1===r)return;if("string"==typeof r)return void p?.(r,n.options)}const r=h[n.intent]||[];for(const t of r){const r=await t(n.intent,o);if(!1===r)return;if("string"==typeof r)return void p?.(r,n.options)}S(n.intent);const e=P(t,o)+N(n.query);A("navigate",{intent:n.intent,params:o,query:n.query,url:e}),p?.(e,n.options),f&&f.$emit("INTENT_NAVIGATE",n)}function S(n){const t=T[n];if(t)for(const o of t)try{const t=o();t instanceof Promise&&t.catch(()=>{console.warn(`Preload for intent "${n}" failed`)})}catch(t){console.warn(`Preload for intent "${n}" sync error`,t)}}const U={};function V(n,t){const o=function(n){if(U[n])return U[n];const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,o)=>(t.push(o),"")),U[n]=t,t}(n);if(!t)return{};if(Array.isArray(t)){const n={};return o.forEach((o,r)=>{void 0===t[r]&&console.warn(`Missing param "${o}"`),n[o]=t[r]}),n}return"object"==typeof t?t:1===o.length?{[o[0]]:t}:{}}function P(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,o)=>{const r=t[o];return void 0!==r?encodeURIComponent(r):""})}function x(n,t,o){const r=l[n];if(!r)return"";return P(r,V(r,t))+N(o)}const M={};function z(n){if(M[n])return M[n];const t=[],o=new RegExp("^"+n.replace(/:([A-Za-z0-9_]+)/g,(n,o)=>(t.push(o),"([^/]+)"))+"$");return M[n]={regex:o,keys:t},M[n]}function C(n){const[t,o]=n.split("?"),r=function(n){if(!n)return{};const t=new URLSearchParams(n),o={};return t.forEach((n,t)=>{o[t]?Array.isArray(o[t])?o[t].push(n):o[t]=[o[t],n]:o[t]=n}),o}(o);for(const n in l){const o=l[n],{regex:e,keys:i}=z(o),c=t.match(e);if(!c)continue;const u={};return i.forEach((n,t)=>{u[n]=decodeURIComponent(c[t+1])}),{intent:n,params:u,query:r}}return null}function L(n){f=n,f.$onMultiple("INTENT_NAVIGATE",G)}function b({intent:n,params:r,query:i,scrollTop:c,prefetch:u,onClick:s,onMouseEnter:a,onTouchStart:f,...l}){const p=x(n,r,i);return p?t(e,{to:p,onClick:n=>{c&&window.scrollTo({top:0}),s?.(n)},onMouseEnter:t=>{u&&k(n),a?.(t)},onTouchStart:t=>{u&&k(n),f?.(t)},...l}):(console.warn("IntentLink: unknown intent",n),t(o,{children:l.children}))}function Z(){const n=i(),t=C(n.pathname),o=new URLSearchParams(n.search),r={};return o.forEach((n,t)=>{r[t]=n}),{intent:t?.intent??null,params:t?.params??{},query:r}}function j({intent:n,component:r,fallback:e=null,loading:i,guard:c}){const u=Z();return u?u.intent!==n?null:c&&!c(u)?t(o,{children:e}):t(r,{...u}):i?t(o,{children:i}):null}function B({navigate:n}){const t=c();return s(()=>{I(n??t)},[n,t]),null}function D({children:n}){return r(u,{children:[t(B,{}),n]})}function O(n){const t=c();return s(()=>{I(n??t)},[n,t]),_}export{b as IntentLink,j as IntentRoute,D as IntentRouter,B as RouterBinder,q as addIntentGuard,v as addIntentGuardFor,R as addIntentPreload,I as bindNavigate,w as createIntentRouter,x as generatePathFromIntent,_ as navigateIntent,$ as navigateIntentObject,k as preloadIntent,C as resolveIntentFromUrl,g as setFallbackPath,L as setSharedBus,Z as useIntentRouter,O as useNavigateIntent};
+import{createEventBus as n}from"eventbus-z";import{jsx as t,Fragment as e}from"react/jsx-runtime";import{Link as o,useLocation as r,useNavigate as i}from"react-router-dom";import{useEffect as c,useRef as a}from"react";const u="undefined"!=typeof window&&!0===window.__INTENT_ROUTER_DEBUG__,s=n();let f=null,l=null;const p="INTENT_NAVIGATE_DELPIK";let d={},h={},m={},y={},w=!1;const g=[],R={},E={};let _=null;const I=[];let v=!1;function T(...n){u&&console.log("[IntentRouter]",...n)}function $(n){if(!n)return"";const t=new URLSearchParams;for(const e in n){const o=n[e];null!=o&&(Array.isArray(o)?o.forEach(n=>t.append(e,String(n))):t.append(e,String(o)))}const e=t.toString();return e?`?${e}`:""}function A(n){for(const t in n){u&&d[t]&&console.warn(`[IntentRouter] duplicate intent "${t}"`);const e=n[t];"string"!=typeof e?(d[t]=e.path,e.meta&&(h[t]=e.meta),e.guard&&(m[t]=e.guard),e.preload&&(y[t]=e.preload)):d[t]=e}}function k(n){I.push(n),v&&A(n)}function U(){if(v)return;v=!0;const n={};I.length||console.warn("[IntentRouter] no intents registered");for(const t of I)Object.assign(n,t);A(n),T("intent map",d)}function P(n){k(n),U()}function S(n,t){const e=h[n];return e?"function"==typeof e?e(t):e:{}}function b(n,t){h[n]=t}function q(n){l&&l!==n&&u&&console.warn("IntentRouter navigate replaced"),l=n,w||(s.$onMultiple(p,D),w=!0)}function z(n){_=n}function M(n){u&&(l||console.warn(`[IntentRouter] navigateIntent("${n}") called before router initialized.\nMake sure <RouterBinder /> is mounted.`))}function x(n,t,e,o){M(n);const r={intent:n,params:t,query:e,options:o};T("emit",r),s.$emit(p,r),f&&f!==s&&f.$emit(p,r)}function K(n,t){const{params:e,query:o,options:r}=t||{};x(n,e,o,r)}function N(n){g.push(n)}function j(n,t){R[n]||(R[n]=[]),R[n].push(t)}function C(n,t){E[n]||(E[n]=[]),E[n].push(t)}function L(n){G(n)}async function D(n){if(n.__handled)return;n.__handled=!0;const t=d[n.intent];if(!t)return console.warn("Unknown intent:",n.intent),void(_&&l?.(_));const e=Z(t,n.params),o=S(n.intent,e);for(const t of g){const o=await t(n.intent,e);if(!1===o)return;if("string"==typeof o)return void l?.(o)}const r=R[n.intent]||[];for(const t of r){const o=await t(n.intent,e);if(!1===o)return;if("string"==typeof o)return void l?.(o)}const i=m[n.intent];if(i){const t=await i(n.intent,e);if(!1===t)return;if("string"==typeof t)return void l?.(t)}try{const t=y[n.intent]?.();t instanceof Promise&&t.catch(()=>console.warn(`Preload failed for ${n.intent}`))}catch{}G(n.intent);const c=B(t,e)+$(n.query);T("navigate",{intent:n.intent,params:e,meta:o,url:c});const{scrollTop:a,...u}=n.options||{};("undefined"!=typeof window?window.location.pathname+window.location.search:null)!==c||u?.replace?(l?.(c,u),a&&"undefined"!=typeof window&&window.scrollTo(0,0)):T("skip navigation",c)}function G(n){const t=E[n];if(t)for(const e of t)try{const t=e();t instanceof Promise&&t.catch(()=>console.warn(`Preload failed for ${n}`))}catch{}}const O={};function Z(n,t){const e=function(n){if(O[n])return O[n];const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"")),O[n]=t,t}(n);if(!t)return{};if(Array.isArray(t)){const n={};return e.forEach((e,o)=>{n[e]=t[o]}),n}return"object"==typeof t?t:1===e.length?{[e[0]]:t}:{}}function B(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>{const o=t[e];return void 0===o?(console.warn(`Missing param "${e}"`),""):encodeURIComponent(o)})}function V(n,t,e){const o=d[n];if(!o)return"";return B(o,Z(o,t))+$(e)}const F={};function H(n){if(F[n])return F[n];const t=[],e=new RegExp("^"+n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"([^/]+)"))+"$");return F[n]={regex:e,keys:t},F[n]}function J(n){const[t,e]=n.split("?"),o=decodeURI(t),r=function(n){if(!n)return{};const t=new URLSearchParams(n),e={};return t.forEach((n,t)=>{e[t]?Array.isArray(e[t])?e[t].push(n):e[t]=[e[t],n]:e[t]=n}),e}(e);for(const n in d){const t=d[n],{regex:e,keys:i}=H(t),c=o.match(e);if(!c)continue;const a={};return i.forEach((n,t)=>{a[n]=decodeURIComponent(c[t+1])}),{intent:n,params:a,query:r}}return null}function Q(n){const t=J(n);t&&x(t.intent,t.params,t.query)}function W(n){f=n,f!==s&&f.$onMultiple(p,D)}let X=!1;function Y({intents:n=[],guards:t=[],intentGuards:e={},navigate:o}={}){if(X)return;X=!0;const r={};for(const t of n)for(const n in t)u&&r[n]&&console.warn(`[IntentRouter] duplicate intent "${n}"`),r[n]=t[n];Object.keys(r).length&&P(r),t.forEach(N);for(const n in e)j(n,e[n]);o&&q(o)}function nn({intent:n,params:r,query:i,scrollTop:c,prefetch:a,onClick:u,onMouseEnter:s,onTouchStart:f,...l}){const p=V(n,r,i);return p?t(o,{to:p,onClick:t=>{t.metaKey||t.ctrlKey||t.shiftKey||t.altKey||0!==t.button||(t.preventDefault(),x(n,r,i,{scrollTop:c}),u?.(t))},onMouseEnter:t=>{a&&L(n),s?.(t)},onTouchStart:t=>{a&&L(n),f?.(t)},...l}):(M(n),t(e,{children:l.children}))}function tn(){const n=r(),t=J(n.pathname),e=new URLSearchParams(n.search),o={};return e.forEach((n,t)=>{o[t]=n}),{intent:t?.intent??null,params:t?.params??{},query:o}}function en({intent:n,component:o,fallback:r=null,loading:i,guard:c}){const a=tn();return a?a.intent!==n?null:c&&!c(a)?t(e,{children:r}):t(o,{...a}):i?t(e,{children:i}):null}function on(n){const t=i();return c(()=>{q(n??t)},[n,t]),x}function rn({initializeRouter:n}){const t=i(),e=r(),o=a(!1);return on(),c(()=>{n&&(o.current||(o.current=!0,n(t)))},[t,n]),c(()=>{Q(e.pathname+e.search)},[e.pathname,e.search]),null}export{nn as IntentLink,en as IntentRoute,rn as RouterBinder,N as addIntentGuard,j as addIntentGuardFor,C as addIntentPreload,q as bindNavigate,U as bootstrapRouter,P as createIntentRouter,V as generatePathFromIntent,S as getIntentMeta,x as navigateIntent,K as navigateIntentObject,L as preloadIntent,k as registerIntents,J as resolveIntentFromUrl,z as setFallbackPath,b as setIntentMeta,W as setSharedBus,Y as setupIntentRouter,Q as syncIntentFromUrl,tn as useIntentRouter,on as useNavigateIntent,M as warnRouterNotReady};

package/build/index.js

@@ -1 +1 @@
-"use strict";var n=require("eventbus-z"),t=require("react/jsx-runtime"),e=require("react-router-dom"),r=require("react");const o=n.createEventBus();let i=null;let s={},c=null,a=!1;const u=[],f={},l={};let p=null;const d="undefined"!=typeof window&&!0===window.__INTENT_ROUTER_DEBUG__;function m(...n){d&&console.log("[IntentRouter]",...n)}function I(n){if(!n)return"";const t=new URLSearchParams;for(const e in n){const r=n[e];null!=r&&(Array.isArray(r)?r.forEach(n=>t.append(e,String(n))):t.append(e,String(r)))}const e=t.toString();return e?`?${e}`:""}function h(n){c&&c!==n&&d&&console.warn("IntentRouter navigate replaced"),c=n,a||(o.$onMultiple("INTENT_NAVIGATE",E),a=!0)}function g(n,t,e,r){m("emit",n,{params:t,query:e});const s={intent:n,params:t,query:e,...r?{options:r}:{}};o.$emit("INTENT_NAVIGATE",s),i&&i.$emit("INTENT_NAVIGATE",s)}function x(n){T(n)}async function E(n){const t=s[n.intent];if(m("receive",n.intent,n),!t)return p&&c?.(p),void console.warn("Unknown intent:",n.intent);const e=y(t,n.params);for(const t of u){const r=await t(n.intent,e);if(!1===r)return;if("string"==typeof r)return void c?.(r,n.options)}const r=f[n.intent]||[];for(const t of r){const r=await t(n.intent,e);if(!1===r)return;if("string"==typeof r)return void c?.(r,n.options)}T(n.intent);const o=A(t,e)+I(n.query);m("navigate",{intent:n.intent,params:e,query:n.query,url:o}),c?.(o,n.options),i&&i.$emit("INTENT_NAVIGATE",n)}function T(n){const t=l[n];if(t)for(const e of t)try{const t=e();t instanceof Promise&&t.catch(()=>{console.warn(`Preload for intent "${n}" failed`)})}catch(t){console.warn(`Preload for intent "${n}" sync error`,t)}}const N={};function y(n,t){const e=function(n){if(N[n])return N[n];const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"")),N[n]=t,t}(n);if(!t)return{};if(Array.isArray(t)){const n={};return e.forEach((e,r)=>{void 0===t[r]&&console.warn(`Missing param "${e}"`),n[e]=t[r]}),n}return"object"==typeof t?t:1===e.length?{[e[0]]:t}:{}}function A(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>{const r=t[e];return void 0!==r?encodeURIComponent(r):""})}function w(n,t,e){const r=s[n];if(!r)return"";return A(r,y(r,t))+I(e)}const v={};function R(n){if(v[n])return v[n];const t=[],e=new RegExp("^"+n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"([^/]+)"))+"$");return v[n]={regex:e,keys:t},v[n]}function _(n){const[t,e]=n.split("?"),r=function(n){if(!n)return{};const t=new URLSearchParams(n),e={};return t.forEach((n,t)=>{e[t]?Array.isArray(e[t])?e[t].push(n):e[t]=[e[t],n]:e[t]=n}),e}(e);for(const n in s){const e=s[n],{regex:o,keys:i}=R(e),c=t.match(o);if(!c)continue;const a={};return i.forEach((n,t)=>{a[n]=decodeURIComponent(c[t+1])}),{intent:n,params:a,query:r}}return null}function q(){const n=e.useLocation(),t=_(n.pathname),r=new URLSearchParams(n.search),o={};return r.forEach((n,t)=>{o[t]=n}),{intent:t?.intent??null,params:t?.params??{},query:o}}function $({navigate:n}){const t=e.useNavigate();return r.useEffect(()=>{h(n??t)},[n,t]),null}exports.IntentLink=function({intent:n,params:r,query:o,scrollTop:i,prefetch:s,onClick:c,onMouseEnter:a,onTouchStart:u,...f}){const l=w(n,r,o);return l?t.jsx(e.Link,{to:l,onClick:n=>{i&&window.scrollTo({top:0}),c?.(n)},onMouseEnter:t=>{s&&x(n),a?.(t)},onTouchStart:t=>{s&&x(n),u?.(t)},...f}):(console.warn("IntentLink: unknown intent",n),t.jsx(t.Fragment,{children:f.children}))},exports.IntentRoute=function({intent:n,component:e,fallback:r=null,loading:o,guard:i}){const s=q();return s?s.intent!==n?null:i&&!i(s)?t.jsx(t.Fragment,{children:r}):t.jsx(e,{...s}):o?t.jsx(t.Fragment,{children:o}):null},exports.IntentRouter=function({children:n}){return t.jsxs(e.BrowserRouter,{children:[t.jsx($,{}),n]})},exports.RouterBinder=$,exports.addIntentGuard=function(n){u.push(n)},exports.addIntentGuardFor=function(n,t){f[n]||(f[n]=[]),f[n].push(t)},exports.addIntentPreload=function(n,t){l[n]||(l[n]=[]),l[n].push(t)},exports.bindNavigate=h,exports.createIntentRouter=function(n){s=n,m("intent map loaded",n)},exports.generatePathFromIntent=w,exports.navigateIntent=g,exports.navigateIntentObject=function(n,t){const{params:e,query:r,options:s}=t||{};m("emit",n,{params:e,query:r});const c={intent:n,params:e,query:r,...s?{options:s}:{}};o.$emit("INTENT_NAVIGATE",c),i&&i.$emit("INTENT_NAVIGATE",c)},exports.preloadIntent=x,exports.resolveIntentFromUrl=_,exports.setFallbackPath=function(n){p=n},exports.setSharedBus=function(n){i=n,i.$onMultiple("INTENT_NAVIGATE",E)},exports.useIntentRouter=q,exports.useNavigateIntent=function(n){const t=e.useNavigate();return r.useEffect(()=>{h(n??t)},[n,t]),g};
+"use strict";var n=require("eventbus-z"),t=require("react/jsx-runtime"),e=require("react-router-dom"),o=require("react");const r="undefined"!=typeof window&&!0===window.__INTENT_ROUTER_DEBUG__,i=n.createEventBus();let s=null,a=null;const c="INTENT_NAVIGATE_DELPIK";let u={},f={},l={},p={},d=!1;const h=[],g={},m={};let y=null;const x=[];let w=!1;function I(...n){r&&console.log("[IntentRouter]",...n)}function R(n){if(!n)return"";const t=new URLSearchParams;for(const e in n){const o=n[e];null!=o&&(Array.isArray(o)?o.forEach(n=>t.append(e,String(n))):t.append(e,String(o)))}const e=t.toString();return e?`?${e}`:""}function v(n){for(const t in n){r&&u[t]&&console.warn(`[IntentRouter] duplicate intent "${t}"`);const e=n[t];"string"!=typeof e?(u[t]=e.path,e.meta&&(f[t]=e.meta),e.guard&&(l[t]=e.guard),e.preload&&(p[t]=e.preload)):u[t]=e}}function E(n){x.push(n),w&&v(n)}function _(){if(w)return;w=!0;const n={};x.length||console.warn("[IntentRouter] no intents registered");for(const t of x)Object.assign(n,t);v(n),I("intent map",u)}function k(n){E(n),_()}function T(n,t){const e=f[n];return e?"function"==typeof e?e(t):e:{}}function $(n){a&&a!==n&&r&&console.warn("IntentRouter navigate replaced"),a=n,d||(i.$onMultiple(c,j),d=!0)}function b(n){r&&(a||console.warn(`[IntentRouter] navigateIntent("${n}") called before router initialized.\nMake sure <RouterBinder /> is mounted.`))}function q(n,t,e,o){b(n);const r={intent:n,params:t,query:e,options:o};I("emit",r),i.$emit(c,r),s&&s!==i&&s.$emit(c,r)}function A(n){h.push(n)}function P(n,t){g[n]||(g[n]=[]),g[n].push(t)}function U(n){N(n)}async function j(n){if(n.__handled)return;n.__handled=!0;const t=u[n.intent];if(!t)return console.warn("Unknown intent:",n.intent),void(y&&a?.(y));const e=F(t,n.params),o=T(n.intent,e);for(const t of h){const o=await t(n.intent,e);if(!1===o)return;if("string"==typeof o)return void a?.(o)}const r=g[n.intent]||[];for(const t of r){const o=await t(n.intent,e);if(!1===o)return;if("string"==typeof o)return void a?.(o)}const i=l[n.intent];if(i){const t=await i(n.intent,e);if(!1===t)return;if("string"==typeof t)return void a?.(t)}try{const t=p[n.intent]?.();t instanceof Promise&&t.catch(()=>console.warn(`Preload failed for ${n.intent}`))}catch{}N(n.intent);const s=L(t,e)+R(n.query);I("navigate",{intent:n.intent,params:e,meta:o,url:s});const{scrollTop:c,...f}=n.options||{};("undefined"!=typeof window?window.location.pathname+window.location.search:null)!==s||f?.replace?(a?.(s,f),c&&"undefined"!=typeof window&&window.scrollTo(0,0)):I("skip navigation",s)}function N(n){const t=m[n];if(t)for(const e of t)try{const t=e();t instanceof Promise&&t.catch(()=>console.warn(`Preload failed for ${n}`))}catch{}}const S={};function F(n,t){const e=function(n){if(S[n])return S[n];const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"")),S[n]=t,t}(n);if(!t)return{};if(Array.isArray(t)){const n={};return e.forEach((e,o)=>{n[e]=t[o]}),n}return"object"==typeof t?t:1===e.length?{[e[0]]:t}:{}}function L(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>{const o=t[e];return void 0===o?(console.warn(`Missing param "${e}"`),""):encodeURIComponent(o)})}function M(n,t,e){const o=u[n];if(!o)return"";return L(o,F(o,t))+R(e)}const z={};function B(n){if(z[n])return z[n];const t=[],e=new RegExp("^"+n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"([^/]+)"))+"$");return z[n]={regex:e,keys:t},z[n]}function G(n){const[t,e]=n.split("?"),o=decodeURI(t),r=function(n){if(!n)return{};const t=new URLSearchParams(n),e={};return t.forEach((n,t)=>{e[t]?Array.isArray(e[t])?e[t].push(n):e[t]=[e[t],n]:e[t]=n}),e}(e);for(const n in u){const t=u[n],{regex:e,keys:i}=B(t),s=o.match(e);if(!s)continue;const a={};return i.forEach((n,t)=>{a[n]=decodeURIComponent(s[t+1])}),{intent:n,params:a,query:r}}return null}function K(n){const t=G(n);t&&q(t.intent,t.params,t.query)}let C=!1;function O(){const n=e.useLocation(),t=G(n.pathname),o=new URLSearchParams(n.search),r={};return o.forEach((n,t)=>{r[t]=n}),{intent:t?.intent??null,params:t?.params??{},query:r}}function D(n){const t=e.useNavigate();return o.useEffect(()=>{$(n??t)},[n,t]),q}exports.IntentLink=function({intent:n,params:o,query:r,scrollTop:i,prefetch:s,onClick:a,onMouseEnter:c,onTouchStart:u,...f}){const l=M(n,o,r);return l?t.jsx(e.Link,{to:l,onClick:t=>{t.metaKey||t.ctrlKey||t.shiftKey||t.altKey||0!==t.button||(t.preventDefault(),q(n,o,r,{scrollTop:i}),a?.(t))},onMouseEnter:t=>{s&&U(n),c?.(t)},onTouchStart:t=>{s&&U(n),u?.(t)},...f}):(b(n),t.jsx(t.Fragment,{children:f.children}))},exports.IntentRoute=function({intent:n,component:e,fallback:o=null,loading:r,guard:i}){const s=O();return s?s.intent!==n?null:i&&!i(s)?t.jsx(t.Fragment,{children:o}):t.jsx(e,{...s}):r?t.jsx(t.Fragment,{children:r}):null},exports.RouterBinder=function({initializeRouter:n}){const t=e.useNavigate(),r=e.useLocation(),i=o.useRef(!1);return D(),o.useEffect(()=>{n&&(i.current||(i.current=!0,n(t)))},[t,n]),o.useEffect(()=>{K(r.pathname+r.search)},[r.pathname,r.search]),null},exports.addIntentGuard=A,exports.addIntentGuardFor=P,exports.addIntentPreload=function(n,t){m[n]||(m[n]=[]),m[n].push(t)},exports.bindNavigate=$,exports.bootstrapRouter=_,exports.createIntentRouter=k,exports.generatePathFromIntent=M,exports.getIntentMeta=T,exports.navigateIntent=q,exports.navigateIntentObject=function(n,t){const{params:e,query:o,options:r}=t||{};q(n,e,o,r)},exports.preloadIntent=U,exports.registerIntents=E,exports.resolveIntentFromUrl=G,exports.setFallbackPath=function(n){y=n},exports.setIntentMeta=function(n,t){f[n]=t},exports.setSharedBus=function(n){s=n,s!==i&&s.$onMultiple(c,j)},exports.setupIntentRouter=function({intents:n=[],guards:t=[],intentGuards:e={},navigate:o}={}){if(C)return;C=!0;const i={};for(const t of n)for(const n in t)r&&i[n]&&console.warn(`[IntentRouter] duplicate intent "${n}"`),i[n]=t[n];Object.keys(i).length&&k(i),t.forEach(A);for(const n in e)P(n,e[n]);o&&$(o)},exports.syncIntentFromUrl=K,exports.useIntentRouter=O,exports.useNavigateIntent=D,exports.warnRouterNotReady=b;

package/build/router/IntentLink.d.ts

@@ -5,6 +5,6 @@ type Props = {
     query?: Record<string, any>;
     scrollTop?: boolean;
     prefetch?: boolean;
-} & Omit<LinkProps, "to" | "prefetch">;
+} & Omit<LinkProps, "to">;
 export declare function IntentLink({ intent, params, query, scrollTop, prefetch, onClick, onMouseEnter, onTouchStart, ...props }: Props): JSX.Element;
 export {};

package/build/router/IntentRoute.d.ts

@@ -1,4 +1,4 @@
-import { type IntentData } from "./useIntentRouter";
+import type { IntentData } from "./useIntentRouter";
 type Props = {
     intent: string;
     component: React.ComponentType<any>;

package/build/router/RouterBinder.d.ts

@@ -1,5 +1,6 @@
-type Props = {
-    navigate?: any;
+import type { NavigateFn } from "../core/intentCore";
+type RouterBinderProps = {
+    initializeRouter?: (navigate: NavigateFn) => void;
 };
-export declare function RouterBinder({ navigate }: Props): null;
+export declare function RouterBinder({ initializeRouter }: RouterBinderProps): null;
 export {};

package/build/router/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./IntentLink";
 export * from "./IntentRoute";
-export * from "./IntentRouter";
 export * from "./RouterBinder";
 export * from "./useIntentRouter";
 export * from "./useNavigateIntent";

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "intentx-react-router",
-  "version": "1.0.4",
+  "version": "1.1.0-z10",
   "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",
@@ -18,13 +21,14 @@
   "files": [
     "build"
   ],
-  "sideEffects": false,
+
   "scripts": {
     "clean": "rimraf build",
     "build": "rimraf build && rollup -c",
     "watch": "rollup -c -w",
     "typecheck": "tsc --noEmit"
   },
+
   "engines": {
     "node": ">=16"
   },
@@ -36,6 +40,7 @@
   "bugs": {
     "url": "https://github.com/delpikye-v/intentx-react-router/issues"
   },
+
   "keywords": [
     "react",
     "react-router",
@@ -48,6 +53,7 @@
     "spa",
     "routing"
   ],
+
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",

package/build/router/IntentRouter.d.ts

@@ -1,5 +0,0 @@
-type Props = {
-    children: React.ReactNode;
-};
-export declare function IntentRouter({ children }: Props): JSX.Element;
-export {};