npm - @revealui/router - Versions diffs - 0.2.0 - Mend

@revealui/router 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/LICENSE +22 -0
package/README.md +353 -0
package/dist/index.d.ts +57 -0
package/dist/index.js +285 -0
package/dist/index.js.map +1 -0
package/dist/router-DctgwX83.d.ts +126 -0
package/dist/server.d.ts +32 -0
package/dist/server.js +371 -0
package/dist/server.js.map +1 -0
package/package.json +51 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,22 @@
+MIT License
+Copyright (c) 2025 RevealUI Team
+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 ADDED Viewed

@@ -0,0 +1,353 @@
+# @revealui/router
+Lightweight, type-safe file-based router for RevealUI with built-in SSR support.
+## Features
+- 🚀 **Simple & Fast** - Minimal API, maximum performance
+- 📁 **File-based routing** - Convention over configuration
+- 🔒 **Type-safe** - Full TypeScript support
+- 🌊 **SSR & Hydration** - Built-in server-side rendering with React
+- 🎯 **Hono Integration** - First-class support for Hono server
+- 📦 **No dependencies** - Except React and path-to-regexp
+- ⚡ **Code splitting ready** - Supports lazy loading
+- 🔗 **Data loading** - Built-in loader support per route
+## Installation
+```bash
+pnpm add @revealui/router
+```
+## Quick Start
+### 1. Define Your Routes
+```typescript
+import { Router, type Route } from '@revealui/router'
+import Home from './pages/Home'
+import About from './pages/About'
+import Post from './pages/Post'
+const routes: Route[] = [
+  {
+    path: '/',
+    component: Home,
+    meta: { title: 'Home' },
+  },
+  {
+    path: '/about',
+    component: About,
+    meta: { title: 'About Us' },
+  },
+  {
+    path: '/posts/:id',
+    component: Post,
+    loader: async ({ id }) => {
+      const post = await fetch(`/api/posts/${id}`).then(r => r.json())
+      return { post }
+    },
+  },
+]
+const router = new Router()
+router.registerRoutes(routes)
+```
+### 2. Client-Side Usage
+```typescript
+import { RouterProvider, Routes, Link } from '@revealui/router'
+function App() {
+  return (
+    <RouterProvider router={router}>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <Routes />
+    </RouterProvider>
+  )
+}
+```
+### 3. Server-Side Rendering (SSR)
+```typescript
+import { Hono } from 'hono'
+import { createSSRHandler } from '@revealui/router/server'
+import routes from './routes'
+const app = new Hono()
+app.get('*', createSSRHandler(routes, {
+  template: (html, data) => `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>${data?.title || 'My App'}</title>
+      </head>
+      <body>
+        <div id="root">${html}</div>
+        <script id="__REVEALUI_DATA__" type="application/json">
+          ${JSON.stringify(data)}
+        </script>
+        <script type="module" src="/client.js"></script>
+      </body>
+    </html>
+  `,
+}))
+```
+## API Reference
+### Router
+```typescript
+const router = new Router(options)
+```
+**Methods:**
+- `register(route: Route)` - Register a single route
+- `registerRoutes(routes: Route[])` - Register multiple routes
+- `match(url: string)` - Match a URL to a route
+- `resolve(url: string)` - Match and load route data
+- `navigate(url: string, options?)` - Client-side navigation
+- `back()` / `forward()` - Browser history navigation
+- `subscribe(listener)` - Subscribe to route changes
+- `initClient()` - Initialize client-side routing
+### Components
+#### `<RouterProvider>`
+Provides router instance to your app:
+```typescript
+<RouterProvider router={router}>
+  <App />
+</RouterProvider>
+```
+#### `<Routes>`
+Renders the matched route component:
+```typescript
+<Routes />
+```
+#### `<Link>`
+Client-side navigation link:
+```typescript
+<Link to="/about" replace={false}>
+  About Us
+</Link>
+```
+#### `<Navigate>`
+Declarative navigation:
+```typescript
+<Navigate to="/login" replace />
+```
+### Hooks
+#### `useRouter()`
+Access the router instance:
+```typescript
+const router = useRouter()
+router.navigate('/about')
+```
+#### `useParams()`
+Get route parameters:
+```typescript
+const { id } = useParams<{ id: string }>()
+```
+#### `useData()`
+Get route data from loader:
+```typescript
+const { post } = useData<{ post: Post }>()
+```
+#### `useMatch()`
+Get current route match:
+```typescript
+const match = useMatch()
+console.log(match?.route.path, match?.params)
+```
+#### `useNavigate()`
+Get navigation function:
+```typescript
+const navigate = useNavigate()
+navigate('/about', { replace: true })
+```
+## Route Patterns
+Supports path-to-regexp patterns:
+```typescript
+'/posts/:id'           // Named parameter
+'/posts/:id?'          // Optional parameter
+'/posts/:id(\\d+)'     // Parameter with regex
+'/posts/*'             // Wildcard
+'/posts/:path*'        // Wildcard with name
+```
+## Data Loading
+Routes can have loaders for data fetching:
+```typescript
+{
+  path: '/user/:id',
+  component: UserProfile,
+  loader: async ({ id }) => {
+    const user = await fetchUser(id)
+    return { user }
+  },
+}
+```
+Access data in your component:
+```typescript
+function UserProfile() {
+  const { user } = useData<{ user: User }>()
+  return <div>{user.name}</div>
+}
+```
+## Layouts
+Wrap routes with layouts:
+```typescript
+{
+  path: '/dashboard',
+  component: Dashboard,
+  layout: DashboardLayout,
+}
+```
+Layout component:
+```typescript
+function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+## SSR with Streaming
+Enable streaming SSR for better performance:
+```typescript
+createSSRHandler(routes, {
+  streaming: true,
+  onError: (error, context) => {
+    console.error('SSR Error:', error)
+  },
+})
+```
+## Dev Server
+Quick development server:
+```typescript
+import { createDevServer } from '@revealui/router/server'
+await createDevServer(routes, {
+  port: 3000,
+  template: (html, data) => `...`,
+})
+```
+## Integration with RevealUI
+Works seamlessly with other RevealUI packages:
+```typescript
+import { Router } from '@revealui/router'
+import { getRevealUI } from '@revealui/core'
+const router = new Router()
+router.register({
+  path: '/cms/:slug',
+  component: CMSPage,
+  loader: async ({ slug }) => {
+    const revealui = await getRevealUI()
+    const page = await revealui.find({
+      collection: 'pages',
+      where: { slug: { equals: slug } },
+    })
+    return { page: page.docs[0] }
+  },
+})
+```
+## TypeScript
+Full type safety:
+```typescript
+import type { Route, RouteParams } from '@revealui/router'
+interface PostParams extends RouteParams {
+  id: string
+}
+const route: Route = {
+  path: '/posts/:id',
+  component: Post,
+  loader: async (params: PostParams) => {
+    // params.id is typed as string
+    return { post: await fetchPost(params.id) }
+  },
+}
+```
+## Comparison with Other Routers
+| Feature | @revealui/router | TanStack Router | React Router |
+|---------|-----------------|-----------------|--------------|
+| Bundle Size | ~5KB | ~50KB | ~20KB |
+| SSR Built-in | ✅ | ⚠️ Requires Start | ⚠️ Complex setup |
+| Type Safety | ✅ | ✅ | ⚠️ Limited |
+| Data Loading | ✅ | ✅ | ✅ |
+| Learning Curve | Low | Medium | Low |
+## License
+MIT - RevealUI
+## Contributing
+See [CONTRIBUTING.md](../../CONTRIBUTING.md)

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { R as Router, a as RouteMatch, N as NavigateOptions } from './router-DctgwX83.js';
+export { b as Route, c as RouteMeta, d as RouteParams, e as RouterOptions } from './router-DctgwX83.js';
+/**
+ * RouterProvider - Provides router instance to the app
+ */
+declare function RouterProvider({ router, children, }: {
+    router: Router;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Routes - Renders the matched route component
+ */
+declare function Routes(): react_jsx_runtime.JSX.Element;
+/**
+ * Link - Client-side navigation link
+ */
+declare function Link({ to, replace, children, className, style, onClick, ...props }: {
+    to: string;
+    replace?: boolean;
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    onClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+    [key: string]: unknown;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * useRouter - Hook to access router instance
+ */
+declare function useRouter(): Router;
+/**
+ * useMatch - Hook to access current route match
+ */
+declare function useMatch(): RouteMatch | null;
+/**
+ * useParams - Hook to access route parameters
+ */
+declare function useParams<T = Record<string, string>>(): T;
+/**
+ * useData - Hook to access route data
+ */
+declare function useData<T = unknown>(): T | undefined;
+/**
+ * useNavigate - Hook to get navigation function
+ */
+declare function useNavigate(): (to: string, options?: NavigateOptions) => void;
+/**
+ * Navigate - Component for declarative navigation
+ */
+declare function Navigate({ to, replace }: {
+    to: string;
+    replace?: boolean;
+}): null;
+export { Link, Navigate, NavigateOptions, RouteMatch, Router, RouterProvider, Routes, useData, useMatch, useNavigate, useParams, useRouter };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,285 @@
+// src/components.tsx
+import { createContext, useContext, useEffect, useSyncExternalStore } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var RouterContext = createContext(null);
+var MatchContext = createContext(null);
+function RouterProvider({
+  router,
+  children
+}) {
+  return /* @__PURE__ */ jsx(RouterContext.Provider, { value: router, children });
+}
+function Routes() {
+  const router = useRouter();
+  const match = useSyncExternalStore(
+    (callback) => router.subscribe(callback),
+    () => router.getCurrentMatch(),
+    () => router.getCurrentMatch()
+    // Server-side snapshot (same as client)
+  );
+  if (!match) {
+    return /* @__PURE__ */ jsx(NotFound, {});
+  }
+  const { route, params, data } = match;
+  const Component = 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 });
+}
+function Link({
+  to,
+  replace = false,
+  children,
+  className,
+  style,
+  onClick,
+  ...props
+}) {
+  const router = useRouter();
+  const handleClick = (e) => {
+    onClick?.(e);
+    if (e.defaultPrevented) {
+      return;
+    }
+    if (e.button !== 0) {
+      return;
+    }
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+      return;
+    }
+    e.preventDefault();
+    router.navigate(to, { replace });
+  };
+  return /* @__PURE__ */ jsx("a", { href: to, onClick: handleClick, className, style, ...props, children });
+}
+function useRouter() {
+  const router = useContext(RouterContext);
+  if (!router) {
+    throw new Error("useRouter must be used within a RouterProvider");
+  }
+  return router;
+}
+function useMatch() {
+  return useContext(MatchContext);
+}
+function useParams() {
+  const match = useMatch();
+  return match?.params || {};
+}
+function useData() {
+  const match = useMatch();
+  return match?.data;
+}
+function useNavigate() {
+  const router = useRouter();
+  return (to, options) => {
+    router.navigate(to, options);
+  };
+}
+function NotFound() {
+  return /* @__PURE__ */ jsxs("div", { style: { padding: "2rem", textAlign: "center" }, children: [
+    /* @__PURE__ */ jsx("h1", { children: "404 - Page Not Found" }),
+    /* @__PURE__ */ jsx("p", { children: "The page you're looking for doesn't exist." }),
+    /* @__PURE__ */ jsx(Link, { to: "/", children: "Go Home" })
+  ] });
+}
+function Navigate({ to, replace = false }) {
+  const router = useRouter();
+  useEffect(() => {
+    router.navigate(to, { replace });
+  }, [to, replace, router]);
+  return null;
+}
+// src/router.ts
+import { match as pathMatch } from "path-to-regexp";
+// ../core/src/observability/logger.ts
+import { logger as utilsLogger } from "@revealui/utils/logger";
+import {
+  createLogger,
+  Logger,
+  logAudit,
+  logError,
+  logger,
+  logQuery
+} from "@revealui/utils/logger";
+// src/router.ts
+var Router = class {
+  routes = [];
+  options;
+  listeners = /* @__PURE__ */ new Set();
+  currentMatch = null;
+  constructor(options = {}) {
+    this.options = {
+      basePath: "",
+      ...options
+    };
+  }
+  /**
+   * Register a route
+   */
+  register(route) {
+    this.routes.push(route);
+  }
+  /**
+   * Register multiple routes
+   */
+  registerRoutes(routes) {
+    routes.forEach((route) => {
+      this.register(route);
+    });
+  }
+  /**
+   * Match a URL to a route
+   */
+  match(url) {
+    const path = this.normalizePath(url);
+    for (const route of this.routes) {
+      const matcher = pathMatch(route.path, { decode: decodeURIComponent });
+      const result = matcher(path);
+      if (result) {
+        return {
+          route,
+          params: result.params || {}
+        };
+      }
+    }
+    return null;
+  }
+  /**
+   * Resolve a route with data loading
+   */
+  async resolve(url) {
+    const matched = this.match(url);
+    if (!matched) {
+      return null;
+    }
+    if (matched.route.loader) {
+      try {
+        matched.data = await matched.route.loader(matched.params);
+      } catch (error) {
+        logger.error(
+          "Route loader error",
+          error instanceof Error ? error : new Error(String(error))
+        );
+        throw error;
+      }
+    }
+    if (typeof window === "undefined") {
+      this.currentMatch = matched;
+    }
+    return matched;
+  }
+  /**
+   * Navigate to a URL (client-side only)
+   */
+  navigate(url, options = {}) {
+    if (typeof window === "undefined") {
+      return;
+    }
+    const fullUrl = this.options.basePath + url;
+    if (options.replace) {
+      window.history.replaceState(options.state || null, "", fullUrl);
+    } else {
+      window.history.pushState(options.state || null, "", fullUrl);
+    }
+    this.notifyListeners();
+  }
+  /**
+   * Go back in history
+   */
+  back() {
+    if (typeof window !== "undefined") {
+      window.history.back();
+    }
+  }
+  /**
+   * Go forward in history
+   */
+  forward() {
+    if (typeof window !== "undefined") {
+      window.history.forward();
+    }
+  }
+  /**
+   * Subscribe to route changes
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Get current route match
+   */
+  getCurrentMatch() {
+    if (typeof window === "undefined") {
+      return this.currentMatch;
+    }
+    return this.match(window.location.pathname);
+  }
+  /**
+   * Get all registered routes
+   */
+  getRoutes() {
+    return [...this.routes];
+  }
+  /**
+   * Clear all routes
+   */
+  clear() {
+    this.routes = [];
+  }
+  normalizePath(url) {
+    let path = url;
+    if (this.options.basePath && path.startsWith(this.options.basePath)) {
+      path = path.slice(this.options.basePath.length);
+    }
+    path = path.split("?")[0].split("#")[0];
+    if (!path.startsWith("/")) {
+      path = `/${path}`;
+    }
+    return path;
+  }
+  notifyListeners() {
+    this.listeners.forEach((listener) => {
+      listener();
+    });
+  }
+  /**
+   * Initialize client-side routing
+   */
+  initClient() {
+    if (typeof window === "undefined") {
+      return;
+    }
+    window.addEventListener("popstate", () => {
+      this.notifyListeners();
+    });
+    document.addEventListener("click", (e) => {
+      const target = e.target.closest("a");
+      if (!target) return;
+      const href = target.getAttribute("href");
+      if (href?.startsWith("/") && !target.hasAttribute("target") && !target.hasAttribute("download") && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey) {
+        e.preventDefault();
+        this.navigate(href);
+      }
+    });
+  }
+};
+export {
+  Link,
+  Navigate,
+  Router,
+  RouterProvider,
+  Routes,
+  useData,
+  useMatch,
+  useNavigate,
+  useParams,
+  useRouter
+};
+//# sourceMappingURL=index.js.map