intentx-react-router 0.1.0

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,325 @@
+# 🕹️ 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)
+
+<a href="https://codesandbox.io/p/sandbox/q8gg5s" target="_blank">LIVE EXAMPLE</a>
+
+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**.
+
+> Navigate by **intent**, not by URL.
+
+---
+
+# Why intentx-react-router?
+
+Traditional routing:
+```ts
+navigate("/users/42/edit")
+```
+
+Intent Router:
+```ts
+navigateIntent("edit-user", 42)
+```
+
+<b>Benefits:</b>
+
+-   🧠 Intent‑driven navigation
+-   🔗 URL structure fully decoupled from UI
+-   🔧 Easy URL refactor
+-   🧩 Micro‑frontend friendly
+-   📡 Event‑driven navigation support
+-   🪶 Lightweight core (\~200 lines)
+
+---
+
+# Installation
+
+```bash
+npm install intentx-react-router eventbus-z react-router
+```
+
+---
+
+# Basic Setup
+
+## Define intents
+
+``` ts
+import { createIntentRouter } from "intentx-react-router"
+
+createIntentRouter({
+  "view-user": "/users/:userId/name/:page",
+  "edit-user": "/users/:userId/edit",
+  "open-cart": "/cart",
+  "checkout": "/checkout"
+})
+```
+
+---
+
+## Bind React Router navigate
+
+``` ts
+import { bindNavigate } from "intentx-react-router"
+
+import { useNavigate } from "react-router"
+
+function RouterBinder() {
+  const navigate = useNavigate()
+
+  bindNavigate(navigate)
+
+  return null
+}
+```
+
+---
+
+# Navigation
+
+## Object params
+
+``` ts
+navigateIntent("view-user", {
+  userId: 1,
+  page: 2
+})
+```
+
+Result:
+
+```ts
+/users/1/name/2
+```
+
+---
+
+## Array params
+
+``` ts
+navigateIntent("view-user", [1,2])
+```
+
+Params automatically map to:
+```ts
+:userId
+:page
+```
+
+---
+
+## Single param shortcut
+
+``` ts
+navigateIntent("edit-user", 1)
+```
+
+Result:
+
+```text
+/users/1/edit
+```
+
+---
+
+# React Helpers
+
+## useNavigateIntent
+
+``` ts
+import { useNavigateIntent } from "intentx-react-router"
+
+function Button() {
+  const navigateIntent = useNavigateIntent()
+
+  return (
+    <button onClick={() => navigateIntent("checkout")}>
+      Checkout
+    </button>
+  )
+}
+```
+
+---
+
+## IntentLink
+
+``` tsx
+import { IntentLink } from "intentx-react-router"
+
+<IntentLink intent="view-user" params={[1,2]}>
+  Open User
+</IntentLink>
+```
+
+Equivalent to:
+
+```ts
+<Link to="/users/1/name/2" />
+```
+
+---
+
+## useIntent
+
+Reads intent + params from URL.
+
+``` ts
+import { useIntent } from "intentx-react-router"
+
+function Page() {
+  const { intent, params } = useIntent()
+
+  console.log(intent)
+  console.log(params)
+
+  return null
+}
+```
+
+Example result:
+
+```ts
+  {
+    intent: "view-user",
+    params: {
+      userId: "1",
+      page: "2"
+    }
+  }
+```
+
+---
+
+## IntentRoute
+
+Intent‑aware route wrapper.
+
+```tsx
+import { IntentRoute } from "intentx-react-router"
+
+<IntentRoute
+  intent="view-user"
+  component={UserPage}
+/>
+```
+
+---
+
+# Guards
+
+Global guard:
+
+```ts
+addIntentGuard((intent, params) => {
+
+  if (!isLoggedIn && intent === "checkout") {
+    return "/login"
+  }
+
+})
+```
+
+Per‑intent guard:
+
+```ts
+addIntentGuardFor("checkout", () => {
+
+  if (!cartReady) {
+    return "/cart"
+  }
+
+})
+```
+
+---
+
+# Preload
+
+Preload logic before navigation.
+
+```ts
+addIntentPreload("checkout", () => {
+  fetchCart()
+})
+```
+
+Manual preload:
+
+```ts
+preloadIntent("checkout")
+```
+
+---
+
+# Reverse Routing
+
+Generate path manually.
+
+``` ts
+generatePathFromIntent("view-user", [1,2])
+```
+
+Result:
+```ts
+/users/1/name/2
+```
+---
+
+# Resolve Intent From URL
+
+``` ts
+resolveIntentFromUrl("/users/1/name/2")
+```
+
+Result:
+```ts
+    {
+      intent: "view-user",
+      params: {
+        userId: "1",
+        page: "2"
+      }
+    }
+```
+
+---
+
+# Comparison
+
+| Criteria                | intent-router | React Router |
+|-------------------------|---------------|--------------|
+| Intent-based navigation | ✅            | ❌            |
+| URL refactor safety     | ✅            | ⚠️            |
+| Event-driven navigation | ✅            | ❌            |
+| Micro-frontend friendly | ✅            | ⚠️            |
+| Reverse routing         | ✅            | ❌            |
+| Type-safe intent params | ✅            | ⚠️            |
+
+---
+
+# Architecture
+
+```text
+Component
+    ↓
+navigateIntent()
+    ↓
+eventbus-z
+    ↓
+Intent Router
+    ↓
+React Router navigate()
+    ↓
+URL
+```
+
+---
+
+# License
+
+MIT

package/build/core/IntentRoute.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+type Props = {
+    intent: string;
+    component: React.ComponentType<any>;
+};
+export declare function IntentRoute({ intent, component: Component }: Props): JSX.Element | null;
+export {};

package/build/core/index.d.ts

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

package/build/core/intentCore.d.ts

@@ -0,0 +1,17 @@
+type IntentMap = Record<string, string>;
+type GuardFn = (intent: string, params: any) => boolean | string | void;
+type NavigateFn = (path: string) => void;
+type PreloadFn = () => Promise<any> | void;
+export declare function createIntentRouter(map: IntentMap): void;
+export declare function bindNavigate(fn: NavigateFn): void;
+export declare function navigateIntent(intent: string, params?: Record<string, any> | any[] | string | number): 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): string;
+export declare function resolveIntentFromUrl(url: string): {
+    intent: string;
+    params: Record<string, any>;
+} | null;
+export {};

package/build/index.d.ts

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

package/build/index.esm.js

@@ -0,0 +1,2 @@
+import{createEventBus as n}from"eventbus-z";import{jsx as t}from"react/jsx-runtime";import{useLocation as r,Link as o,useNavigate as e}from"react-router";import{useEffect as i}from"react";const c=n(),u="INTENT_NAVIGATE";let s={},f=null,a=!1;const l=[],p={},m={};function h(n){s=n}function v(n){f=n,a||(c.$onMultiple(u,E),a=!0)}function d(n,t){c.$emit(u,{intent:n,params:t})}function g(n){l.push(n)}function y(n,t){p[n]||(p[n]=[]),p[n].push(t)}function A(n,t){m[n]||(m[n]=[]),m[n].push(t)}function w(n){z(n)}function E(n){const t=s[n.intent];if(!t)return void console.warn("Unknown intent:",n.intent);const r=$(t,n.params);for(const t of l){const o=t(n.intent,r);if(!1===o)return;if("string"==typeof o)return void(null==f||f(o))}const o=p[n.intent]||[];for(const t of o){const o=t(n.intent,r);if(!1===o)return;if("string"==typeof o)return void(null==f||f(o))}z(n.intent);const e=_(t,r);null==f||f(e)}function z(n){const t=m[n];if(t)for(const n of t)try{const t=n();t instanceof Promise&&t.catch(()=>{})}catch{}}function $(n,t){const r=function(n){const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,r)=>(t.push(r),"")),t}(n);if(!t)return{};if(Array.isArray(t)){const n={};return r.forEach((r,o)=>{void 0===t[o]&&console.warn(`Missing param "${r}"`),n[r]=t[o]}),n}return"object"==typeof t?t:1===r.length?{[r[0]]:t}:{}}function _(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,r)=>{var o;return null!==(o=t[r])&&void 0!==o?o:""})}function x(n,t){const r=s[n];if(!r)return"";return _(r,$(r,t))}function N(n){for(const t in s){const r=s[t],o=[],e=new RegExp("^"+r.replace(/:([A-Za-z0-9_]+)/g,(n,t)=>(o.push(t),"([^/]+)"))+"$"),i=n.match(e);if(!i)continue;const c={};return o.forEach((n,t)=>{c[n]=i[t+1]}),{intent:t,params:c}}return null}function P(){var n,t;const o=r(),e=N(o.pathname),i=new URLSearchParams(o.search),c={};return i.forEach((n,t)=>{c[t]=n}),{intent:null!==(n=null==e?void 0:e.intent)&&void 0!==n?n:null,params:null!==(t=null==e?void 0:e.params)&&void 0!==t?t:{},query:c}}function R({intent:n,component:r}){const o=P();return o.intent!==n?null:t(r,{...o})}function S({intent:n,params:r,query:e,children:i}){let c=x(n,r);if(e){const n=new URLSearchParams(e).toString();n&&(c+="?"+n)}return t(o,{to:c,children:i})}function T(){const n=e();return i(()=>{v(n)},[n]),d}export{S as IntentLink,R as IntentRoute,g as addIntentGuard,y as addIntentGuardFor,A as addIntentPreload,v as bindNavigate,h as createIntentRouter,x as generatePathFromIntent,d as navigateIntent,w as preloadIntent,N as resolveIntentFromUrl,P as useIntent,T as useNavigateIntent};
+//# sourceMappingURL=index.esm.js.map

package/build/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/build/index.js

@@ -0,0 +1,2 @@
+"use strict";var n=require("eventbus-z"),t=require("react/jsx-runtime"),e=require("react-router"),r=require("react");const o=n.createEventBus(),i="INTENT_NAVIGATE";let u={},s=null,c=!1;const a=[],f={},l={};function p(n){s=n,c||(o.$onMultiple(i,h),c=!0)}function d(n,t){o.$emit(i,{intent:n,params:t})}function h(n){const t=u[n.intent];if(!t)return void console.warn("Unknown intent:",n.intent);const e=m(t,n.params);for(const t of a){const r=t(n.intent,e);if(!1===r)return;if("string"==typeof r)return void(null==s||s(r))}const r=f[n.intent]||[];for(const t of r){const r=t(n.intent,e);if(!1===r)return;if("string"==typeof r)return void(null==s||s(r))}v(n.intent);const o=x(t,e);null==s||s(o)}function v(n){const t=l[n];if(t)for(const n of t)try{const t=n();t instanceof Promise&&t.catch(()=>{})}catch{}}function m(n,t){const e=function(n){const t=[];return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>(t.push(e),"")),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 x(n,t){return n.replace(/:([A-Za-z0-9_]+)/g,(n,e)=>{var r;return null!==(r=t[e])&&void 0!==r?r:""})}function g(n,t){const e=u[n];if(!e)return"";return x(e,m(e,t))}function I(n){for(const t in u){const e=u[t],r=[],o=new RegExp("^"+e.replace(/:([A-Za-z0-9_]+)/g,(n,t)=>(r.push(t),"([^/]+)"))+"$"),i=n.match(o);if(!i)continue;const s={};return r.forEach((n,t)=>{s[n]=i[t+1]}),{intent:t,params:s}}return null}function y(){var n,t;const r=e.useLocation(),o=I(r.pathname),i=new URLSearchParams(r.search),u={};return i.forEach((n,t)=>{u[t]=n}),{intent:null!==(n=null==o?void 0:o.intent)&&void 0!==n?n:null,params:null!==(t=null==o?void 0:o.params)&&void 0!==t?t:{},query:u}}exports.IntentLink=function({intent:n,params:r,query:o,children:i}){let u=g(n,r);if(o){const n=new URLSearchParams(o).toString();n&&(u+="?"+n)}return t.jsx(e.Link,{to:u,children:i})},exports.IntentRoute=function({intent:n,component:e}){const r=y();return r.intent!==n?null:t.jsx(e,{...r})},exports.addIntentGuard=function(n){a.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=p,exports.createIntentRouter=function(n){u=n},exports.generatePathFromIntent=g,exports.navigateIntent=d,exports.preloadIntent=function(n){v(n)},exports.resolveIntentFromUrl=I,exports.useIntent=y,exports.useNavigateIntent=function(){const n=e.useNavigate();return r.useEffect(()=>{p(n)},[n]),d};
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/build/router/IntentLink.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+type Props = {
+    intent: string;
+    params?: any;
+    query?: Record<string, any>;
+    children: React.ReactNode;
+};
+export declare function IntentLink({ intent, params, query, children }: Props): JSX.Element;
+export {};

package/build/router/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./IntentLink";
+export * from "./useIntent";
+export * from "./useNavigateIntent";

package/build/router/useIntent.d.ts

@@ -0,0 +1,5 @@
+export declare function useIntent(): {
+    intent: string | null;
+    params: Record<string, any>;
+    query: Record<string, string>;
+};

package/build/router/useNavigateIntent.d.ts

@@ -0,0 +1,2 @@
+import { navigateIntent } from "../core/intentCore";
+export declare function useNavigateIntent(): typeof navigateIntent;

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "intentx-react-router",
+  "version": "0.1.0",
+  "description": "Intent-based routing for React. Navigate by intent instead of URLs.",
+  "author": "Delpi.Kye",
+  "license": "MIT",
+
+  "type": "module",
+  "main": "./build/index.cjs.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.cjs.js"
+    }
+  },
+
+  "files": [
+    "build"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "rimraf build && rollup -c",
+    "watch": "rollup -c -w",
+    "typecheck": "tsc --noEmit"
+  },
+
+  "engines": {
+    "node": ">=16"
+  },
+
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delpikye-v/intentx-route.git"
+  },
+  "homepage": "https://github.com/delpikye-v/intentx-react-router#readme",
+  "bugs": {
+    "url": "https://github.com/delpikye-v/intentx-react-router/issues"
+  },
+  "keywords": [
+    "react",
+    "react-router",
+    "router",
+    "intent-router",
+    "navigation",
+    "intent-navigation",
+    "react-navigation",
+    "frontend",
+    "spa",
+    "routing"
+  ],
+
+  "peerDependencies": {
+    "react": ">=18",
+    "react-router": ">=6"
+  },
+  "dependencies": {
+    "eventbus-z": "^2.4.0"
+  },
+  "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"
+  }
+}