@amazing-router/react 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adel Chafic Gannem
+
+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 @@
+# amazing-router-react

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { RouteNode } from '@amazing-router/core';
+import { RouteObject } from 'react-router';
+export * from 'react-router';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Custom hook that provides a simplified navigation API built on top of React Router.
+ *
+ * @returns An object with the current pathname and navigation methods:
+ * - `pathname` — the current URL path.
+ * - `push(path)` — navigates to the given path, pushing a new entry onto the history stack.
+ * - `replace(path)` — navigates to the given path, replacing the current history entry.
+ * - `back()` — navigates back one entry in the history stack.
+ */
+declare const useAmazingRouter: () => {
+    pathname: string;
+    push: (path: string) => void | Promise<void>;
+    replace: (path: string) => void | Promise<void>;
+    back: () => void | Promise<void>;
+};
+
+/**
+ * Custom hook that reads the meta information attached to the currently active route.
+ * Meta is injected into the route's `handle` property during route transformation.
+ *
+ * @returns An object containing the resolved `title`, `description`, and any additional
+ * meta fields defined on the matched route. Falls back to default values if no meta is found.
+ */
+declare const useAmazingMeta: () => {
+    title: string;
+    description: string;
+    image?: string;
+    keywords?: string[];
+    canonical?: string;
+    breadcrumb?: string | react.ReactNode;
+    icon?: string | react.ReactNode;
+    hideInMenu?: boolean;
+    roles?: string[];
+    requiresAuth?: boolean;
+};
+
+/**
+ * Metadata that can be attached to any route node.
+ * This information is read at runtime by the {@link useAmazingMeta} hook.
+ */
+interface MetaProps {
+    /** The page title displayed in the browser tab and used for SEO. */
+    title?: string;
+    /** A short description of the page, used for SEO meta tags. */
+    description?: string;
+    /** URL of the Open Graph / social share image. */
+    image?: string;
+    /** List of keywords associated with the page for SEO purposes. */
+    keywords?: string[];
+    /** The canonical URL for the page, used to avoid duplicate content issues. */
+    canonical?: string;
+    /** Breadcrumb label shown in navigation hierarchies. */
+    breadcrumb?: string | ReactNode;
+    /** Icon associated with this route, used in menus or tabs. */
+    icon?: string | ReactNode;
+    /** When `true`, hides this route from automatically generated menus. */
+    hideInMenu?: boolean;
+    /** List of roles allowed to access this route, used for authorization checks. */
+    roles?: string[];
+    /** When `true`, the route requires the user to be authenticated. */
+    requiresAuth?: boolean;
+    /** Allows any additional custom metadata fields. */
+    [key: string]: any;
+}
+
+/**
+ * Extends React Router's `RouteObject` with Amazing Router specific fields.
+ * Used as the internal representation of each route after transformation.
+ */
+interface AmazingRouteObject extends Omit<RouteObject, "children"> {
+    /** Unique identifier for the route, derived from the file-system path. */
+    id: string;
+    /** The URL path segment for this route. */
+    path?: string;
+    /** The React element rendered when this route is active. */
+    element?: React.ReactNode;
+    /** Optional metadata attached to this route, accessible via `useAmazingMeta`. */
+    meta?: MetaProps;
+    /** Nested child routes. */
+    children?: AmazingRouteObject[];
+}
+
+/**
+ * Recursively transforms a tree of RouteNodes into React Router compatible objects.
+ *
+ * Key behaviors:
+ * - Top-level routes use absolute paths ("/about")
+ * - Nested routes use relative paths ("about") as required by React Router
+ * - Pathless group layout wrappers have NO path property (not even undefined)
+ * - Middleware wraps the page element when present
+ *
+ * @param nodes - Array of nodes from routes.json
+ * @param isNested - Whether these nodes are children of another route
+ * @returns Array of AmazingRouteObject
+ */
+declare function transformRoutes(nodes: RouteNode[], routeFiles: Record<string, () => Promise<any>>, isNested?: boolean): AmazingRouteObject[];
+
+/**
+ * Props for the {@link AmazingProvider} component.
+ */
+interface AmazingProviderProps {
+    /** Optional React node to display while the route configuration is being loaded. */
+    loadingElement?: React.ReactNode;
+}
+/**
+ * Root provider component for Amazing Router.
+ * Dynamically loads the generated `routes.json` and `routeFiles.ts` artifacts
+ * produced by the Amazing Router Vite/Webpack plugin, transforms them into a
+ * React Router-compatible browser router, and renders the application.
+ *
+ * @param props - {@link AmazingProviderProps}
+ */
+declare const AmazingProvider: ({ loadingElement, }: AmazingProviderProps) => string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
+
+export { AmazingProvider, type AmazingProviderProps, type AmazingRouteObject, type MetaProps, transformRoutes, useAmazingMeta, useAmazingRouter };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { RouteNode } from '@amazing-router/core';
+import { RouteObject } from 'react-router';
+export * from 'react-router';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Custom hook that provides a simplified navigation API built on top of React Router.
+ *
+ * @returns An object with the current pathname and navigation methods:
+ * - `pathname` — the current URL path.
+ * - `push(path)` — navigates to the given path, pushing a new entry onto the history stack.
+ * - `replace(path)` — navigates to the given path, replacing the current history entry.
+ * - `back()` — navigates back one entry in the history stack.
+ */
+declare const useAmazingRouter: () => {
+    pathname: string;
+    push: (path: string) => void | Promise<void>;
+    replace: (path: string) => void | Promise<void>;
+    back: () => void | Promise<void>;
+};
+
+/**
+ * Custom hook that reads the meta information attached to the currently active route.
+ * Meta is injected into the route's `handle` property during route transformation.
+ *
+ * @returns An object containing the resolved `title`, `description`, and any additional
+ * meta fields defined on the matched route. Falls back to default values if no meta is found.
+ */
+declare const useAmazingMeta: () => {
+    title: string;
+    description: string;
+    image?: string;
+    keywords?: string[];
+    canonical?: string;
+    breadcrumb?: string | react.ReactNode;
+    icon?: string | react.ReactNode;
+    hideInMenu?: boolean;
+    roles?: string[];
+    requiresAuth?: boolean;
+};
+
+/**
+ * Metadata that can be attached to any route node.
+ * This information is read at runtime by the {@link useAmazingMeta} hook.
+ */
+interface MetaProps {
+    /** The page title displayed in the browser tab and used for SEO. */
+    title?: string;
+    /** A short description of the page, used for SEO meta tags. */
+    description?: string;
+    /** URL of the Open Graph / social share image. */
+    image?: string;
+    /** List of keywords associated with the page for SEO purposes. */
+    keywords?: string[];
+    /** The canonical URL for the page, used to avoid duplicate content issues. */
+    canonical?: string;
+    /** Breadcrumb label shown in navigation hierarchies. */
+    breadcrumb?: string | ReactNode;
+    /** Icon associated with this route, used in menus or tabs. */
+    icon?: string | ReactNode;
+    /** When `true`, hides this route from automatically generated menus. */
+    hideInMenu?: boolean;
+    /** List of roles allowed to access this route, used for authorization checks. */
+    roles?: string[];
+    /** When `true`, the route requires the user to be authenticated. */
+    requiresAuth?: boolean;
+    /** Allows any additional custom metadata fields. */
+    [key: string]: any;
+}
+
+/**
+ * Extends React Router's `RouteObject` with Amazing Router specific fields.
+ * Used as the internal representation of each route after transformation.
+ */
+interface AmazingRouteObject extends Omit<RouteObject, "children"> {
+    /** Unique identifier for the route, derived from the file-system path. */
+    id: string;
+    /** The URL path segment for this route. */
+    path?: string;
+    /** The React element rendered when this route is active. */
+    element?: React.ReactNode;
+    /** Optional metadata attached to this route, accessible via `useAmazingMeta`. */
+    meta?: MetaProps;
+    /** Nested child routes. */
+    children?: AmazingRouteObject[];
+}
+
+/**
+ * Recursively transforms a tree of RouteNodes into React Router compatible objects.
+ *
+ * Key behaviors:
+ * - Top-level routes use absolute paths ("/about")
+ * - Nested routes use relative paths ("about") as required by React Router
+ * - Pathless group layout wrappers have NO path property (not even undefined)
+ * - Middleware wraps the page element when present
+ *
+ * @param nodes - Array of nodes from routes.json
+ * @param isNested - Whether these nodes are children of another route
+ * @returns Array of AmazingRouteObject
+ */
+declare function transformRoutes(nodes: RouteNode[], routeFiles: Record<string, () => Promise<any>>, isNested?: boolean): AmazingRouteObject[];
+
+/**
+ * Props for the {@link AmazingProvider} component.
+ */
+interface AmazingProviderProps {
+    /** Optional React node to display while the route configuration is being loaded. */
+    loadingElement?: React.ReactNode;
+}
+/**
+ * Root provider component for Amazing Router.
+ * Dynamically loads the generated `routes.json` and `routeFiles.ts` artifacts
+ * produced by the Amazing Router Vite/Webpack plugin, transforms them into a
+ * React Router-compatible browser router, and renders the application.
+ *
+ * @param props - {@link AmazingProviderProps}
+ */
+declare const AmazingProvider: ({ loadingElement, }: AmazingProviderProps) => string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
+
+export { AmazingProvider, type AmazingProviderProps, type AmazingRouteObject, type MetaProps, transformRoutes, useAmazingMeta, useAmazingRouter };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var R=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var O=Object.prototype.hasOwnProperty;var j=(e,t)=>{for(var r in t)R(e,r,{get:t[r],enumerable:!0})},g=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of N(t))!O.call(e,o)&&o!==r&&R(e,o,{get:()=>t[o],enumerable:!(n=M(t,o))||n.enumerable});return e},u=(e,t,r)=>(g(e,t,"default"),r&&g(r,t,"default"));var v=e=>g(R({},"__esModule",{value:!0}),e);var i={};j(i,{AmazingProvider:()=>S,transformRoutes:()=>d,useAmazingMeta:()=>F,useAmazingRouter:()=>k});module.exports=v(i);var p=require("react-router"),k=()=>{let e=(0,p.useNavigate)();return{pathname:(0,p.useLocation)().pathname,push:r=>e(r),replace:r=>e(r,{replace:!0}),back:()=>e(-1)}};var P=require("react-router"),F=()=>{let e=(0,P.useMatches)(),r=e[e.length-1]?.handle;return{title:r?.meta?.title||"React - Amazing Router",description:r?.meta?.description||"",...r?.meta}};var c=require("react"),z=require("react-router"),m=require("react/jsx-runtime");function L(e,t){let r=e.replace(/\\/g,"/"),n=t[r];return n?(0,c.lazy)(n):(console.warn(`[Amazing Router] Missing route file for: ${r}`),null)}function $(e,t){let r=e.replace(/\\/g,"/"),n=t[r];return n?(0,c.lazy)(()=>n().then(o=>({default:o.middleware}))):(console.warn(`[Amazing Router] Missing middleware file for: ${r}`),null)}function y(e,t,r=!1){let n=r?e.pagePath:e.layoutPath||e.pagePath;if(!n)return(0,m.jsx)(z.Outlet,{});let o=L(n,t);if(!o)return(0,m.jsx)(z.Outlet,{});let s=(0,m.jsx)(c.Suspense,{fallback:null,children:(0,m.jsx)(o,{})});if(e.middlewarePath){let a=$(e.middlewarePath,t);if(a)return(0,m.jsx)(c.Suspense,{fallback:null,children:(0,m.jsx)(a,{})})}return s}function d(e,t,r=!1){let n=[];for(let o of e){let s=r&&o.path?o.path.replace(/^\//,""):o.path,a={id:o.id,element:y(o,t),handle:{meta:o.meta},children:[],...s!==void 0?{path:s}:{}};o.layoutPath&&o.pagePath&&a.children.push({id:`${o.id}-index`,index:!0,element:y({...o,layoutPath:void 0},t),handle:{meta:o.meta}}),o.children&&o.children.length>0&&a.children.push(...d(o.children,t,!0)),a.children&&a.children.length===0&&delete a.children,n.push(a)}return n}var l=require("react"),f=require("react-router");var x=require("react/jsx-runtime"),S=({loadingElement:e=null})=>{let[t,r]=(0,l.useState)([]),[n,o]=(0,l.useState)({});(0,l.useEffect)(()=>{let a=Date.now(),A=`/.amazing-router/routes.json?t=${a}`,b=`/.amazing-router/routeFiles.ts?t=${a}`;Promise.all([import(A),import(b)]).then(([h,w])=>{r(h.default||[]),o(w.routeFiles||{})}).catch(h=>{console.warn("[Amazing Router] Could not find the generated route files. Did you run the core build or forgot to configure the Vite/Webpack plugin?",h)})},[]);let s=(0,l.useMemo)(()=>{if(!t||t.length===0||Object.keys(n).length===0)return null;let a=d(t,n);return(0,f.createBrowserRouter)(a)},[t,n]);return s?(0,x.jsx)(f.RouterProvider,{router:s}):e};u(i,require("react-router"),module.exports);0&&(module.exports={AmazingProvider,transformRoutes,useAmazingMeta,useAmazingRouter,...require("react-router")});

package/dist/index.mjs

@@ -0,0 +1 @@
+import{useNavigate as z,useLocation as P}from"react-router";var v=()=>{let t=z();return{pathname:P().pathname,push:r=>t(r),replace:r=>t(r,{replace:!0}),back:()=>t(-1)}};import{useMatches as y}from"react-router";var L=()=>{let t=y(),r=t[t.length-1]?.handle;return{title:r?.meta?.title||"React - Amazing Router",description:r?.meta?.description||"",...r?.meta}};import{lazy as d,Suspense as l}from"react";import{Outlet as c}from"react-router";import{jsx as s}from"react/jsx-runtime";function x(t,o){let r=t.replace(/\\/g,"/"),n=o[r];return n?d(n):(console.warn(`[Amazing Router] Missing route file for: ${r}`),null)}function A(t,o){let r=t.replace(/\\/g,"/"),n=o[r];return n?d(()=>n().then(e=>({default:e.middleware}))):(console.warn(`[Amazing Router] Missing middleware file for: ${r}`),null)}function p(t,o,r=!1){let n=r?t.pagePath:t.layoutPath||t.pagePath;if(!n)return s(c,{});let e=x(n,o);if(!e)return s(c,{});let i=s(l,{fallback:null,children:s(e,{})});if(t.middlewarePath){let a=A(t.middlewarePath,o);if(a)return s(l,{fallback:null,children:s(a,{})})}return i}function m(t,o,r=!1){let n=[];for(let e of t){let i=r&&e.path?e.path.replace(/^\//,""):e.path,a={id:e.id,element:p(e,o),handle:{meta:e.meta},children:[],...i!==void 0?{path:i}:{}};e.layoutPath&&e.pagePath&&a.children.push({id:`${e.id}-index`,index:!0,element:p({...e,layoutPath:void 0},o),handle:{meta:e.meta}}),e.children&&e.children.length>0&&a.children.push(...m(e.children,o,!0)),a.children&&a.children.length===0&&delete a.children,n.push(a)}return n}import{useState as f,useEffect as b,useMemo as w}from"react";import{createBrowserRouter as M,RouterProvider as N}from"react-router";import{jsx as O}from"react/jsx-runtime";var U=({loadingElement:t=null})=>{let[o,r]=f([]),[n,e]=f({});b(()=>{let a=Date.now(),h=`/.amazing-router/routes.json?t=${a}`,g=`/.amazing-router/routeFiles.ts?t=${a}`;Promise.all([import(h),import(g)]).then(([u,R])=>{r(u.default||[]),e(R.routeFiles||{})}).catch(u=>{console.warn("[Amazing Router] Could not find the generated route files. Did you run the core build or forgot to configure the Vite/Webpack plugin?",u)})},[]);let i=w(()=>{if(!o||o.length===0||Object.keys(n).length===0)return null;let a=m(o,n);return M(a)},[o,n]);return i?O(N,{router:i}):t};export*from"react-router";export{U as AmazingProvider,m as transformRoutes,L as useAmazingMeta,v as useAmazingRouter};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@amazing-router/react",
+  "version": "1.1.0",
+  "description": "React adapter for Amazing Router Core using React Router under the hood",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --external react",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts --external react",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:ui": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.0.0"
+  },
+  "dependencies": {
+    "@amazing-router/core": "^1.5.4"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "router",
+    "amazing-router",
+    "file-system-routing"
+  ],
+  "author": "AdelGann",
+  "license": "MIT"
+}