@iyulab/router 0.1.0 → 0.3.0

package/README.md

@@ -1,18 +1,19 @@
 # @iyulab/router
 
-A modern client-side router for web applications with support for Lit and React components.
+A modern, lightweight client-side router for web applications with support for both Lit and React components.
 
 ## Features
 
-- 🚀 Modern URLPattern-based routing
-- 🔧 Support for both Lit and React components
-- 📱 Client-side navigation with history management
-- 🎯 Nested routing support
-- ⚡ Async data loading with loaders
-- 🔗 Smart link component with external link detection
-- 📊 Route progress tracking
-- 🎨 Flexible outlet system for component rendering
-- 🌐 Global route information access via `window.route`
+- 🚀 **Modern URLPattern-based routing** - Uses native URLPattern API for powerful path matching
+- 🔧 **Unified Framework Support** - Works with both Lit and React components using render functions
+- 📱 **Client-side Navigation** - History API integration with browser back/forward support
+- 🎯 **Nested Routing** - Support for deeply nested route hierarchies with index and path routes
+- 🔗 **Smart Link Component** - Automatic external link detection and handling
+- 📊 **Route Events** - Track navigation progress with route-begin, route-done, and route-error events
+- 🎨 **Flexible Outlet System** - Unified rendering with renderContent method
+- 🌐 **Global Route Access** - Access current route information anywhere via `window.route`
+- 🔄 **Force Re-rendering** - Control component re-rendering on route changes
+- ⚠️ **Enhanced Error Handling** - Built-in ErrorPage component with improved styling
 
 ## Installation
 
@@ -20,43 +21,89 @@ A modern client-side router for web applications with support for Lit and React
 npm install @iyulab/router
 ```
 
-## Usage
+## Quick Start
 
 ### Basic Setup
 
 ```typescript
 import { Router } from '@iyulab/router';
+import { html } from 'lit';
 
 const router = new Router({
   root: document.getElementById('app')!,
   basepath: '/app',
   routes: [
     {
-      path: '/',
-      element: 'home-page'
+      index: true,
+      render: () => html`<home-page></home-page>`
     },
     {
       path: '/user/:id',
-      component: UserComponent,
-      loader: async (routeInfo) => {
-        const response = await fetch(`/api/user/${routeInfo.params.id}`);
-        return response.json();
-      }
+      render: (routeInfo) => html`<user-page .userId=${routeInfo.params.id}></user-page>`
     }
-  ],
-  notfound: 'not-found-page'
+  ]
 });
 
-// Connect the router
-router.connect();
+// Start routing
+router.go(window.location.href);
+```
+
+### Nested Routes
+
+```typescript
+const routes = [
+  {
+    path: '/dashboard',
+    render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
+    children: [
+      {
+        index: true, // Matches /dashboard exactly
+        render: () => html`<dashboard-home></dashboard-home>`
+      },
+      {
+        path: 'settings',
+        render: () => html`<dashboard-settings></dashboard-settings>`
+      }
+    ]
+  }
+];
 ```
 
+### Mixed Framework Support
+
+```typescript
+import React from 'react';
+
+const routes = [
+  // Lit component
+  {
+    path: '/lit-page',
+    render: (routeInfo) => html`<my-lit-component .routeInfo=${routeInfo}></my-lit-component>`
+  },
+  // React component
+  {
+    path: '/react-page',
+    render: (routeInfo) => React.createElement(MyReactComponent, { routeInfo })
+  },
+  // HTML element
+  {
+    path: '/element-page',
+    render: (routeInfo) => {
+      const element = document.createElement('my-element');
+      element.data = routeInfo.params;
+      return element;
+    }
+  }
+];
+```
+
+## Usage Examples
+
 ### Using with Lit Components
 
 ```typescript
 import { LitElement, html } from 'lit';
 import { customElement } from 'lit/decorators.js';
-import { UOutlet, ULink } from '@iyulab/router';
 
 @customElement('app-root')
 export class AppRoot extends LitElement {
@@ -65,7 +112,7 @@ export class AppRoot extends LitElement {
       <nav>
         <u-link href="/">Home</u-link>
         <u-link href="/about">About</u-link>
-        <u-link href="/user/123">User</u-link>
+        <u-link href="/user/123">User Profile</u-link>
       </nav>
       <main>
         <u-outlet></u-outlet>
@@ -87,7 +134,7 @@ export function AppRoot() {
       <nav>
         <Link href="/">Home</Link>
         <Link href="/about">About</Link>
-        <Link href="/user/123">User</Link>
+        <Link href="/user/123">User Profile</Link>
       </nav>
       <main>
         <Outlet />
@@ -97,144 +144,20 @@ export function AppRoot() {
 }
 ```
 
-### Nested Routes
-
-```typescript
-const routes = [
-  {
-    path: '/dashboard',
-    element: 'dashboard-layout',
-    children: [
-      {
-        index: true,
-        element: 'dashboard-home'
-      },
-      {
-        path: 'settings',
-        element: 'dashboard-settings'
-      },
-      {
-        path: 'profile',
-        component: ProfileComponent
-      }
-    ]
-  }
-];
-```
-
-### Route Information Access
-
-You can access current route information globally via `window.route`:
-
-```typescript
-// In any component or script
-console.log('Current path:', window.route.pathname);
-console.log('Route params:', window.route.params);
-console.log('Query params:', window.route.search);
-console.log('Route data:', window.route.data);
-
-// For Lit components
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-
-@customElement('my-component')
-export class MyComponent extends LitElement {
-  connectedCallback() {
-    super.connectedCallback();
-    // Listen for route changes
-    document.addEventListener('route-change', this.onRouteChange);
-  }
-
-  disconnectedCallback() {
-    document.removeEventListener('route-change', this.onRouteChange);
-    super.disconnectedCallback();
-  }
-
-  private onRouteChange = () => {
-    this.requestUpdate(); // Trigger re-render when route changes
-  };
-
-  render() {
-    return html`
-      <div>Current path: ${window.route?.pathname}</div>
-      <div>Params: ${JSON.stringify(window.route?.params)}</div>
-    `;
-  }
-}
-
-// For React components
-import React, { useState, useEffect } from 'react';
-
-export function MyReactComponent() {
-  const [routeInfo, setRouteInfo] = useState(window.route);
-
-  useEffect(() => {
-    const handleRouteChange = () => {
-      setRouteInfo(window.route);
-    };
-
-    document.addEventListener('route-change', handleRouteChange);
-    return () => document.removeEventListener('route-change', handleRouteChange);
-  }, []);
-
-  return (
-    <div>
-      <div>Current path: {routeInfo?.pathname}</div>
-      <div>Params: {JSON.stringify(routeInfo?.params)}</div>
-    </div>
-  );
-}
-```
-
-## API Reference
-
-### Router
-
-#### Constructor Options
-
-- `root`: HTMLElement - The root element where the router will render components
-- `basepath`: string - The base path for the router (optional, defaults to '/')
-- `routes`: Route[] - Array of route configurations
-- `notfound`: LitElement class or string - Component to render when no route matches
-
-#### Methods
-
-- `connect()`: Connect the router and start listening to navigation events
-- `disconnect()`: Disconnect the router and stop listening to events
-- `go(href: string)`: Navigate to a specific path
-- `goBase()`: Navigate to the base path
-
-### Route Configuration
-
-```typescript
-type Route = {
-  path?: string;           // URL pattern (URLPattern syntax)
-  index?: boolean;         // Index route (matches parent path exactly)
-  element?: typeof LitElement | string;  // Lit element to render
-  component?: ComponentType;             // React component to render
-  loader?: (routeInfo: RouteInfo) => Promise<any>;  // Data loader function
-  title?: string;          // Page title
-  children?: Route[];      // Nested routes
-  force?: boolean;         // Force re-render on navigation
-};
-```
-
-### Components
-
-- `UOutlet` / `Outlet`: Outlet component for rendering route components
-- `ULink` / `Link`: Smart link component with client-side navigation
-
-### Global Route Access
-
-- `window.route`: Global access to current route information (RouteInfo object)
+## Browser Support
 
-## Events
+- **URLPattern API**: Required for routing functionality
+- **Modern browsers**: Chrome 95+, Firefox 106+, Safari 16.4+
+- **Polyfill**: Consider using [urlpattern-polyfill](https://www.npmjs.com/package/urlpattern-polyfill) for older browsers
 
-The router dispatches the following events:
+## Contributing
 
-- `route-change`: Fired when the route changes (detail contains RouteInfo)
-- `route-progress`: Fired during navigation with progress value (0-1)
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.