@revealui/router 0.2.1 → 0.3.0

package/dist/router-B2MrlNC3.d.ts

@@ -0,0 +1,187 @@
+import { ComponentType, ReactNode } from 'react';
+
+/**
+ * Middleware function — runs before route resolution.
+ * Return `true` to continue, `false` to abort, or a redirect path string.
+ */
+type RouteMiddleware = (context: MiddlewareContext) => boolean | string | Promise<boolean | string>;
+/**
+ * Context passed to middleware functions
+ */
+interface MiddlewareContext {
+    /** Current URL pathname */
+    pathname: string;
+    /** Matched route params (if available at this stage) */
+    params: RouteParams;
+    /** Route metadata */
+    meta?: RouteMeta;
+}
+/**
+ * Route configuration
+ */
+interface Route<TData = unknown, TProps = Record<string, unknown>> {
+    /** Route path pattern (e.g., '/', '/about', '/posts/:id') */
+    path: string;
+    /** Component to render for this route */
+    component: ComponentType<TProps>;
+    /** Optional layout component */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Optional data loader function */
+    loader?: (params: RouteParams) => Promise<TData> | TData;
+    /** Optional metadata */
+    meta?: RouteMeta;
+    /** Optional middleware that runs before this route's loader */
+    middleware?: RouteMiddleware[];
+    /** Nested child routes — children inherit parent's layout and middleware */
+    children?: Route[];
+}
+/**
+ * Route parameters extracted from URL
+ */
+interface RouteParams {
+    [key: string]: string;
+}
+/**
+ * Route metadata (for SEO, etc.)
+ */
+interface RouteMeta {
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * Matched route result
+ */
+interface RouteMatch<TData = unknown> {
+    route: Route<TData>;
+    params: RouteParams;
+    data?: TData;
+}
+/**
+ * Router configuration options
+ */
+interface RouterOptions {
+    /** Base URL path */
+    basePath?: string;
+    /** 404 component */
+    notFound?: ComponentType;
+    /** Error boundary component */
+    errorBoundary?: ComponentType<{
+        error: Error;
+    }>;
+}
+/**
+ * Navigation options
+ */
+interface NavigateOptions<TState = unknown> {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** State to pass with navigation */
+    state?: TState;
+}
+/**
+ * Current location state
+ */
+interface Location {
+    /** URL pathname (e.g., '/about') */
+    pathname: string;
+    /** Query string including leading '?' (e.g., '?q=test') or empty string */
+    search: string;
+    /** Hash fragment including leading '#' (e.g., '#section') or empty string */
+    hash: string;
+}
+
+/**
+ * RevealUI Router - Lightweight file-based routing with SSR support
+ */
+declare class Router {
+    private routes;
+    private flatRoutes;
+    private globalMiddleware;
+    private options;
+    private listeners;
+    private currentMatch;
+    private lastPathname;
+    private popstateHandler;
+    private clickHandler;
+    constructor(options?: RouterOptions);
+    /**
+     * Add global middleware that runs before all routes.
+     */
+    use(...middleware: RouteMiddleware[]): void;
+    /**
+     * Get router options
+     */
+    getOptions(): RouterOptions;
+    /**
+     * Register a route. Nested children are flattened with combined paths,
+     * middleware, and layout chains.
+     */
+    register(route: Route): void;
+    /**
+     * Register multiple routes
+     */
+    registerRoutes(routes: Route[]): void;
+    /**
+     * Flatten nested routes into the flat lookup table.
+     * Children inherit parent path prefix, middleware, and layout.
+     */
+    private flattenRoute;
+    /**
+     * Match a URL to a route.
+     * Checks flattened routes first (includes nested), then falls back to top-level.
+     */
+    match(url: string): RouteMatch | null;
+    /**
+     * Resolve a route with middleware execution and data loading.
+     *
+     * Middleware chain: global middleware → route middleware → loader.
+     * If any middleware returns `false`, resolution is aborted (returns null).
+     * If any middleware returns a string, navigation is redirected to that path.
+     */
+    resolve(url: string): Promise<RouteMatch | null>;
+    /**
+     * Navigate to a URL (client-side only)
+     */
+    navigate(url: string, options?: NavigateOptions): void;
+    /**
+     * Go back in history
+     */
+    back(): void;
+    /**
+     * Go forward in history
+     */
+    forward(): void;
+    /**
+     * Subscribe to route changes
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Get current route match
+     */
+    getCurrentMatch(): RouteMatch | null;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): Route[];
+    /**
+     * Clear all routes and middleware
+     */
+    clear(): void;
+    private normalizePath;
+    private notifyListeners;
+    /**
+     * Initialize client-side routing.
+     * Uses a global flag to prevent duplicate event listeners on HMR re-invocation.
+     */
+    initClient(): void;
+    /**
+     * Clean up client-side event listeners.
+     * Call this before unmounting or during HMR teardown.
+     */
+    dispose(): void;
+}
+
+export { type Location as L, type MiddlewareContext as M, type NavigateOptions as N, Router as R, type RouteMatch as a, type Route as b, type RouteMeta as c, type RouteMiddleware as d, type RouteParams as e, type RouterOptions as f };

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import * as _hono_node_server from '@hono/node-server';
 import { Context } from 'hono';
-import { b as Route, R as Router } from './router-DctgwX83.js';
+import { b as Route, R as Router } from './router-B2MrlNC3.js';
 import 'react';
 
 /**

package/dist/server.js

@@ -1,16 +1,17 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/server.tsx
 import { logger as logger2 } from "@revealui/core/observability/logger";
-import { renderToPipeableStream, renderToString } from "react-dom/server";
+import { renderToReadableStream, renderToString } from "react-dom/server";
 
 // src/components.tsx
-import { createContext, useContext, useEffect, useSyncExternalStore } from "react";
+import {
+  Component,
+  createContext,
+  use,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 var RouterContext = createContext(null);
 var MatchContext = createContext(null);
@@ -22,6 +23,7 @@ function RouterProvider({
 }
 function Routes() {
   const router = useRouter();
+  const options = router.getOptions();
   const match = useSyncExternalStore(
     (callback) => router.subscribe(callback),
     () => router.getCurrentMatch(),
@@ -29,13 +31,15 @@ function Routes() {
     // Server-side snapshot (same as client)
   );
   if (!match) {
-    return /* @__PURE__ */ jsx(NotFound, {});
+    const CustomNotFound = options.notFound;
+    return CustomNotFound ? /* @__PURE__ */ jsx(CustomNotFound, {}) : /* @__PURE__ */ jsx(NotFound, {});
   }
   const { route, params, data } = match;
-  const Component = route.component;
+  const RouteComponent = route.component;
   const Layout = route.layout;
-  const element = /* @__PURE__ */ jsx(Component, { params, data });
-  return /* @__PURE__ */ jsx(MatchContext.Provider, { value: match, children: Layout ? /* @__PURE__ */ jsx(Layout, { children: element }) : element });
+  const element = /* @__PURE__ */ jsx(RouteComponent, { params, data });
+  const wrapped = Layout ? /* @__PURE__ */ jsx(Layout, { children: element }) : element;
+  return /* @__PURE__ */ jsx(MatchContext.Provider, { value: match, children: options.errorBoundary ? /* @__PURE__ */ jsx(RouteErrorBoundary, { fallback: options.errorBoundary, children: wrapped }) : wrapped });
 }
 function Link({
   to,
@@ -64,7 +68,7 @@ function Link({
   return /* @__PURE__ */ jsx("a", { href: to, onClick: handleClick, className, style, ...props, children });
 }
 function useRouter() {
-  const router = useContext(RouterContext);
+  const router = use(RouterContext);
   if (!router) {
     throw new Error("useRouter must be used within a RouterProvider");
   }
@@ -77,10 +81,31 @@ function NotFound() {
     /* @__PURE__ */ jsx(Link, { to: "/", children: "Go Home" })
   ] });
 }
+var RouteErrorBoundary = class extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  render() {
+    if (this.state.error) {
+      const Fallback = this.props.fallback;
+      return /* @__PURE__ */ jsx(Fallback, { error: this.state.error });
+    }
+    return this.props.children;
+  }
+};
 
 // src/router.ts
 import { logger } from "@revealui/core/observability/logger";
+import { createElement } from "react";
+var MAX_PATTERN_LENGTH = 2048;
 function compilePathPattern(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Route pattern exceeds ${MAX_PATTERN_LENGTH} characters`);
+  }
   const keys = [];
   let src = "^";
   let i = 0;
@@ -112,8 +137,17 @@ function compilePathPattern(pattern) {
   src += "$";
   return { regex: new RegExp(src), keys };
 }
+var patternCache = /* @__PURE__ */ new Map();
+function getCompiledPattern(pattern) {
+  let compiled = patternCache.get(pattern);
+  if (!compiled) {
+    compiled = compilePathPattern(pattern);
+    patternCache.set(pattern, compiled);
+  }
+  return compiled;
+}
 function pathMatch(pattern, options = {}) {
-  const { regex, keys } = compilePathPattern(pattern);
+  const { regex, keys } = getCompiledPattern(pattern);
   const decode = options.decode ?? ((s) => s);
   return (path) => {
     const m = regex.exec(path);
@@ -130,9 +164,14 @@ function pathMatch(pattern, options = {}) {
 }
 var Router = class {
   routes = [];
+  flatRoutes = [];
+  globalMiddleware = [];
   options;
   listeners = /* @__PURE__ */ new Set();
   currentMatch = null;
+  lastPathname = null;
+  popstateHandler = null;
+  clickHandler = null;
   constructor(options = {}) {
     this.options = {
       basePath: "",
@@ -140,10 +179,24 @@ var Router = class {
     };
   }
   /**
-   * Register a route
+   * Add global middleware that runs before all routes.
+   */
+  use(...middleware) {
+    this.globalMiddleware.push(...middleware);
+  }
+  /**
+   * Get router options
+   */
+  getOptions() {
+    return this.options;
+  }
+  /**
+   * Register a route. Nested children are flattened with combined paths,
+   * middleware, and layout chains.
    */
   register(route) {
     this.routes.push(route);
+    this.flattenRoute(route, "", [], void 0);
   }
   /**
    * Register multiple routes
@@ -154,11 +207,37 @@ var Router = class {
     });
   }
   /**
-   * Match a URL to a route
+   * Flatten nested routes into the flat lookup table.
+   * Children inherit parent path prefix, middleware, and layout.
+   */
+  flattenRoute(route, parentPath, parentMiddleware, parentLayout) {
+    const fullPath = joinPaths(parentPath, route.path);
+    const combinedMiddleware = [...parentMiddleware, ...route.middleware ?? []];
+    const effectiveLayout = parentLayout && route.layout ? wrapLayouts(parentLayout, route.layout) : route.layout ?? parentLayout;
+    if (route.component) {
+      this.flatRoutes.push({
+        ...route,
+        path: fullPath,
+        middleware: combinedMiddleware.length > 0 ? combinedMiddleware : void 0,
+        layout: effectiveLayout,
+        children: void 0
+        // Already flattened
+      });
+    }
+    if (route.children) {
+      for (const child of route.children) {
+        this.flattenRoute(child, fullPath, combinedMiddleware, effectiveLayout);
+      }
+    }
+  }
+  /**
+   * Match a URL to a route.
+   * Checks flattened routes first (includes nested), then falls back to top-level.
    */
   match(url) {
     const path = this.normalizePath(url);
-    for (const route of this.routes) {
+    const allRoutes = this.flatRoutes.length > 0 ? this.flatRoutes : this.routes;
+    for (const route of allRoutes) {
       const matcher = pathMatch(route.path, { decode: decodeURIComponent });
       const result = matcher(path);
       if (result) {
@@ -171,13 +250,35 @@ var Router = class {
     return null;
   }
   /**
-   * Resolve a route with data loading
+   * Resolve a route with middleware execution and data loading.
+   *
+   * Middleware chain: global middleware → route middleware → loader.
+   * If any middleware returns `false`, resolution is aborted (returns null).
+   * If any middleware returns a string, navigation is redirected to that path.
    */
   async resolve(url) {
     const matched = this.match(url);
     if (!matched) {
       return null;
     }
+    const allMiddleware = [...this.globalMiddleware, ...matched.route.middleware ?? []];
+    if (allMiddleware.length > 0) {
+      const context = {
+        pathname: this.normalizePath(url),
+        params: matched.params,
+        meta: matched.route.meta
+      };
+      for (const mw of allMiddleware) {
+        const result = await mw(context);
+        if (result === false) {
+          return null;
+        }
+        if (typeof result === "string") {
+          this.navigate(result);
+          return null;
+        }
+      }
+    }
     if (matched.route.loader) {
       try {
         matched.data = await matched.route.loader(matched.params);
@@ -189,9 +290,7 @@ var Router = class {
         throw error;
       }
     }
-    if (typeof window === "undefined") {
-      this.currentMatch = matched;
-    }
+    this.currentMatch = matched;
     return matched;
   }
   /**
@@ -207,6 +306,8 @@ var Router = class {
     } else {
       window.history.pushState(options.state || null, "", fullUrl);
     }
+    this.lastPathname = window.location.pathname;
+    this.currentMatch = this.match(window.location.pathname);
     this.notifyListeners();
   }
   /**
@@ -241,7 +342,12 @@ var Router = class {
     if (typeof window === "undefined") {
       return this.currentMatch;
     }
-    return this.match(window.location.pathname);
+    const pathname = window.location.pathname;
+    if (pathname !== this.lastPathname) {
+      this.lastPathname = pathname;
+      this.currentMatch = this.match(pathname);
+    }
+    return this.currentMatch;
   }
   /**
    * Get all registered routes
@@ -250,10 +356,12 @@ var Router = class {
     return [...this.routes];
   }
   /**
-   * Clear all routes
+   * Clear all routes and middleware
    */
   clear() {
     this.routes = [];
+    this.flatRoutes = [];
+    this.globalMiddleware = [];
   }
   normalizePath(url) {
     let path = url;
@@ -272,16 +380,23 @@ var Router = class {
     });
   }
   /**
-   * Initialize client-side routing
+   * Initialize client-side routing.
+   * Uses a global flag to prevent duplicate event listeners on HMR re-invocation.
    */
   initClient() {
     if (typeof window === "undefined") {
       return;
     }
-    window.addEventListener("popstate", () => {
+    const g = globalThis;
+    if (g.__revealui_router_initialized) return;
+    g.__revealui_router_initialized = true;
+    this.popstateHandler = () => {
+      this.lastPathname = window.location.pathname;
+      this.currentMatch = this.match(window.location.pathname);
       this.notifyListeners();
-    });
-    document.addEventListener("click", (e) => {
+    };
+    window.addEventListener("popstate", this.popstateHandler);
+    this.clickHandler = (e) => {
       const target = e.target.closest("a");
       if (!target) return;
       const href = target.getAttribute("href");
@@ -289,9 +404,37 @@ var Router = class {
         e.preventDefault();
         this.navigate(href);
       }
-    });
+    };
+    document.addEventListener("click", this.clickHandler);
+  }
+  /**
+   * Clean up client-side event listeners.
+   * Call this before unmounting or during HMR teardown.
+   */
+  dispose() {
+    if (typeof window === "undefined") return;
+    if (this.popstateHandler) {
+      window.removeEventListener("popstate", this.popstateHandler);
+      this.popstateHandler = null;
+    }
+    if (this.clickHandler) {
+      document.removeEventListener("click", this.clickHandler);
+      this.clickHandler = null;
+    }
+    this.listeners.clear();
+    const g = globalThis;
+    g.__revealui_router_initialized = false;
   }
 };
+function joinPaths(parent, child) {
+  if (!parent || parent === "/") return child;
+  if (!child || child === "/") return parent;
+  return `${parent.replace(/\/$/, "")}/${child.replace(/^\//, "")}`;
+}
+function wrapLayouts(Parent, Child) {
+  const WrappedLayout = ({ children }) => createElement(Parent, null, createElement(Child, null, children));
+  return WrappedLayout;
+}
 
 // src/server.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
@@ -329,24 +472,19 @@ function createSSRHandler(routes, options = {}) {
         return c.html(template("<div>404 - Page Not Found</div>"));
       }
       if (options.streaming) {
-        return new Promise((resolve, reject) => {
-          const { pipe } = renderToPipeableStream(
-            /* @__PURE__ */ jsx2(RouterProvider, { router, children: /* @__PURE__ */ jsx2(Routes, {}) }),
-            {
-              onShellReady() {
-                c.header("Content-Type", "text/html");
-                const html2 = pipe;
-                resolve(c.body(html2));
-              },
-              onError(error) {
-                logger2.error("SSR error", error instanceof Error ? error : new Error(String(error)));
-                if (options.onError) {
-                  options.onError(error, c);
-                }
-                reject(error);
+        const stream = await renderToReadableStream(
+          /* @__PURE__ */ jsx2(RouterProvider, { router, children: /* @__PURE__ */ jsx2(Routes, {}) }),
+          {
+            onError(error) {
+              logger2.error("SSR error", error instanceof Error ? error : new Error(String(error)));
+              if (options.onError) {
+                options.onError(error, c);
               }
             }
-          );
+          }
+        );
+        return new Response(stream, {
+          headers: { "Content-Type": "text/html; charset=utf-8" }
         });
       }
       const html = renderToString(
@@ -389,9 +527,15 @@ async function hydrate(router, rootElement = null) {
     return;
   }
   const dataScript = document.getElementById("__REVEALUI_DATA__");
-  const _ssrData = dataScript ? JSON.parse(dataScript.textContent || "{}") : {};
+  const ssrData = dataScript ? JSON.parse(dataScript.textContent || "{}") : {};
+  if (ssrData.route) {
+    const match = router.match(window.location.pathname);
+    if (match) {
+      match.data = ssrData.data;
+    }
+  }
   router.initClient();
-  const { hydrateRoot } = __require("react-dom/client");
+  const { hydrateRoot } = await import("react-dom/client");
   hydrateRoot(
     root,
     /* @__PURE__ */ jsx2(RouterProvider, { router, children: /* @__PURE__ */ jsx2(Routes, {}) })