Update Readme.md

Readme.md

@@ -752,33 +752,495 @@ const tempData = $.storage('temp', {}, sessionStorage);
 
 ---
 
-### `$.router(routes)` - Router
+## 🧭 `$.router(routes)` - Hash-Based Router
 
-Hash-based router for SPAs with automatic page cleanup.
+Creates a simple, powerful hash-based router for Single Page Applications (SPAs) with **automatic page cleanup** and **zero configuration**. Built on native browser APIs - no dependencies, no complex setup.
+
+### Why Hash-Based?
+
+Hash routing (`#/about`) works **everywhere** - no server configuration needed. It's perfect for:
+- Static sites and SPAs
+- GitHub Pages, Netlify, any static hosting
+- Local development without a server
+- Projects that need to work immediately
+
+### Basic Usage
 
 ```javascript
 import { $, html } from 'sigpro';
-import HomePage from './pages/index.js';
+import HomePage from './pages/HomePage.js';
-import AboutPage from './pages/about.js';
+import AboutPage from './pages/AboutPage.js';
-import UserPage from './pages/user.js';
+import UserPage from './pages/UserPage.js';
+import NotFound from './pages/NotFound.js';
 
+// Define your routes
 const routes = [
-  { path: '/', component: (params) => HomePage(params) },
+  { path: '/', component: () => HomePage() },
-  { path: '/about', component: (params) => AboutPage(params) },
+  { path: '/about', component: () => AboutPage() },
-  { path: /^\/user\/(?<id>\d+)$/, component: (params) => UserPage(params) },
+  { path: '/users/:id', component: (params) => UserPage(params) },
+  { path: /^\/posts\/(?<id>\d+)$/, component: (params) => PostPage(params) },
 ];
 
+// Create and mount the router
 const router = $.router(routes);
 document.body.appendChild(router);
-
-// Navigate programmatically
-$.router.go('/about');
 ```
 
-**Parameters:**
+---
-- `routes`: Array of route objects with `path` (string or RegExp) and `component` function
 
-**Returns:** Container element with the current page
+### 📋 Route Definition
+
+Each route is an object with two properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `RegExp` | Route pattern to match |
+| `component` | `Function` | Function that returns page content (receives `params`) |
+
+#### String Paths (Simple Routes)
+
+```javascript
+{ path: '/', component: () => HomePage() }
+{ path: '/about', component: () => AboutPage() }
+{ path: '/contact', component: () => ContactPage() }
+{ path: '/users/:id', component: (params) => UserPage(params) } // With parameter
+```
+
+String paths support:
+- **Static segments**: `/about`, `/contact`, `/products`
+- **Named parameters**: `:id`, `:slug`, `:username` (captured in `params`)
+
+#### RegExp Paths (Advanced Routing)
+
+```javascript
+// Match numeric IDs only
+{ path: /^\/users\/(?<id>\d+)$/, component: (params) => UserPage(params) }
+
+// Match product slugs (letters, numbers, hyphens)
+{ path: /^\/products\/(?<slug>[a-z0-9-]+)$/, component: (params) => ProductPage(params) }
+
+// Match blog posts by year/month
+{ path: /^\/blog\/(?<year>\d{4})\/(?<month>\d{2})$/, component: (params) => BlogArchive(params) }
+
+// Match optional language prefix
+{ path: /^\/(?<lang>en|es|fr)?\/?about$/, component: (params) => AboutPage(params) }
+```
+
+RegExp gives you **full control** over route matching with named capture groups.
+
+---
+
+### 🎯 Route Parameters
+
+Parameters are automatically extracted and passed to your component:
+
+```javascript
+// Route: '/users/:id'
+// URL: '#/users/42'
+{ path: '/users/:id', component: (params) => {
+  console.log(params.id); // "42"
+  return UserPage(params);
+}}
+
+// Route: /^\/posts\/(?<id>\d+)$/
+// URL: '#/posts/123'
+{ path: /^\/posts\/(?<id>\d+)$/, component: (params) => {
+  console.log(params.id); // "123"
+  return PostPage(params);
+}}
+
+// Multiple parameters
+// Route: '/products/:category/:id'
+// URL: '#/products/electronics/42'
+{ path: '/products/:category/:id', component: (params) => {
+  console.log(params.category); // "electronics"
+  console.log(params.id); // "42"
+  return ProductPage(params);
+}}
+```
+
+---
+
+### 🔄 Automatic Page Cleanup
+
+The router **automatically cleans up** pages when navigating away:
+
+```javascript
+// pages/UserPage.js
+import { $, html } from 'sigpro';
+
+export default (params) => $.page(({ onUnmount }) => {
+  const userData = $(null);
+  const loading = $(true);
+  
+  // Set up polling
+  const interval = setInterval(() => {
+    fetchUserData(params.id);
+  }, 5000);
+  
+  // Register cleanup
+  onUnmount(() => {
+    clearInterval(interval); // ✅ Auto-cleaned on navigation
+    console.log('UserPage cleaned up');
+  });
+  
+  return html`
+    <div>
+      ${loading() ? 'Loading...' : html`<h1>${userData().name}</h1>`}
+    </div>
+  `;
+});
+```
+
+All `$.effect`, `setInterval`, event listeners, and subscriptions are automatically cleaned up.
+
+---
+
+### 🧭 Navigation
+
+#### Programmatic Navigation
+
+```javascript
+import { $ } from 'sigpro';
+
+// Go to specific route
+$.router.go('/about');
+$.router.go('/users/42');
+$.router.go('/products/electronics/123');
+
+// Automatically adds leading slash if missing
+$.router.go('about'); // Same as '/about'
+$.router.go('users/42'); // Same as '/users/42'
+
+// Works with hash
+$.router.go('#/about'); // Also works
+```
+
+#### Link Navigation
+
+```javascript
+// In your HTML templates
+const navigation = html`
+  <nav>
+    <a href="#/">Home</a>
+    <a href="#/about">About</a>
+    <a href="#/users/42">User 42</a>
+    
+    <!-- Or use @click for programmatic -->
+    <button @click=${() => $.router.go('/contact')}>
+      Contact
+    </button>
+  </nav>
+`;
+```
+
+#### Current Route Info
+
+```javascript
+// Get current path (without hash)
+const currentPath = window.location.hash.replace(/^#/, '') || '/';
+
+// Listen to route changes
+window.addEventListener('hashchange', () => {
+  console.log('Route changed to:', window.location.hash);
+});
+```
+
+---
+
+### 📑 Complete Examples
+
+#### Basic SPA with Layout
+
+```javascript
+// app.js
+import { $, html } from 'sigpro';
+import HomePage from './pages/Home.js';
+import AboutPage from './pages/About.js';
+import ContactPage from './pages/Contact.js';
+
+// Layout component with navigation
+const AppLayout = () => html`
+  <div class="app">
+    <header>
+      <nav>
+        <a href="#/">Home</a>
+        <a href="#/about">About</a>
+        <a href="#/contact">Contact</a>
+      </nav>
+    </header>
+    
+    <main>
+      <!-- Router will inject pages here -->
+      <div id="router-outlet"></div>
+    </main>
+    
+    <footer>
+      <p>© 2024 My App</p>
+    </footer>
+  </div>
+`;
+
+// Set up layout
+document.body.appendChild(AppLayout());
+
+// Create and mount router
+const router = $.router([
+  { path: '/', component: HomePage },
+  { path: '/about', component: AboutPage },
+  { path: '/contact', component: ContactPage },
+]);
+
+document.querySelector('#router-outlet').appendChild(router);
+```
+
+#### Blog with Dynamic Posts
+
+```javascript
+// pages/PostPage.js
+import { $, html } from 'sigpro';
+
+export default (params) => $.page(({ onUnmount }) => {
+  const post = $(null);
+  const loading = $(true);
+  const error = $(null);
+  
+  // Fetch post data
+  const loadPost = async () => {
+    loading(true);
+    error(null);
+    
+    try {
+      const response = await fetch(`/api/posts/${params.id}`);
+      const data = await response.json();
+      post(data);
+    } catch (e) {
+      error('Failed to load post');
+    } finally {
+      loading(false);
+    }
+  };
+  
+  loadPost();
+  
+  return html`
+    <article>
+      ${loading() ? html`<div class="spinner">Loading...</div>` : ''}
+      ${error() ? html`<div class="error">${error()}</div>` : ''}
+      ${post() ? html`
+        <h1>${post().title}</h1>
+        <div class="content">${post().content}</div>
+        <a href="#/blog">← Back to blog</a>
+      ` : ''}
+    </article>
+  `;
+});
+
+// routes
+const routes = [
+  { path: '/blog', component: BlogListPage },
+  { path: '/blog/:id', component: BlogPostPage }, // Dynamic route
+];
+```
+
+#### E-commerce with Categories
+
+```javascript
+// routes with multiple parameters
+const routes = [
+  // Products by category
+  { path: '/products/:category', component: (params) => 
+    ProductListPage({ category: params.category })
+  },
+  
+  // Specific product
+  { path: '/products/:category/:id', component: (params) => 
+    ProductDetailPage({ 
+      category: params.category,
+      id: params.id 
+    })
+  },
+  
+  // Search with query (using RegExp)
+  { 
+    path: /^\/search\/(?<query>[^/]+)(?:\/page\/(?<page>\d+))?$/, 
+    component: (params) => SearchPage({
+      query: decodeURIComponent(params.query),
+      page: params.page || 1
+    })
+  },
+];
+```
+
+---
+
+### ⚡ Advanced Features
+
+#### Nested Routes
+
+```javascript
+// Parent route
+const routes = [
+  {
+    path: '/dashboard',
+    component: (params) => DashboardLayout(params, (nestedParams) => {
+      // Nested routing inside dashboard
+      const nestedRoutes = [
+        { path: '/dashboard', component: DashboardHome },
+        { path: '/dashboard/users', component: DashboardUsers },
+        { path: '/dashboard/settings', component: DashboardSettings },
+      ];
+      return $.router(nestedRoutes);
+    })
+  },
+];
+```
+
+#### Route Guards
+
+```javascript
+const routes = [
+  { 
+    path: '/admin', 
+    component: (params) => {
+      // Simple auth guard
+      if (!isAuthenticated()) {
+        $.router.go('/login');
+        return html`<!-- empty -->`;
+      }
+      return AdminPage(params);
+    }
+  },
+];
+```
+
+#### 404 Handling
+
+```javascript
+const routes = [
+  { path: '/', component: HomePage },
+  { path: '/about', component: AboutPage },
+  // No match = automatic 404
+  // The router shows a default "404" if no route matches
+];
+
+// Or custom 404 page
+const routesWith404 = [
+  { path: '/', component: HomePage },
+  { path: '/about', component: AboutPage },
+  // Add catch-all at the end
+  { path: /.*/, component: () => Custom404Page() },
+];
+```
+
+---
+
+### 🎯 API Reference
+
+#### `$.router(routes)`
+
+Creates a router instance.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `routes` | `Array<Route>` | Array of route objects |
+
+**Returns:** `HTMLDivElement` - Container that renders the current page
+
+#### `$.router.go(path)`
+
+Navigates to a route programmatically.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | `string` | Route path (automatically adds leading slash if missing) |
+
+**Example:**
+```javascript
+$.router.go('/users/42');
+$.router.go('about'); // Same as '/about'
+```
+
+#### Route Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `RegExp` | Route pattern to match |
+| `component` | `Function` | Function that returns page content |
+
+The `component` receives `params` object with extracted parameters.
+
+---
+
+### 📊 Comparison
+
+| Feature | SigPro Router | React Router | Vue Router |
+|---------|--------------|--------------|------------|
+| Bundle Size | **~0.5KB** | ~20KB | ~15KB |
+| Dependencies | **0** | Many | Many |
+| Hash-based | ✅ | ✅ | ✅ |
+| History API | ❌ (by design) | ✅ | ✅ |
+| Route params | ✅ | ✅ | ✅ |
+| Nested routes | ✅ | ✅ | ✅ |
+| Lazy loading | ✅ (native) | ✅ | ✅ |
+| Auto cleanup | ✅ | ❌ | ❌ |
+| No config | ✅ | ❌ | ❌ |
+
+### 💡 Pro Tips
+
+1. **Always define the most specific routes first**
+   ```javascript
+   // ✅ Good
+   [
+     { path: '/users/:id/edit', component: EditUser },
+     { path: '/users/:id', component: ViewUser },
+     { path: '/users', component: UserList },
+   ]
+   
+   // ❌ Bad (catch-all before specific)
+   [
+     { path: '/users/:id', component: ViewUser }, // This matches '/users/edit' too!
+     { path: '/users/:id/edit', component: EditUser }, // Never reached
+   ]
+   ```
+
+2. **Use RegExp for validation**
+   ```javascript
+   // Only numeric IDs
+   { path: /^\/users\/(?<id>\d+)$/, component: UserPage }
+   
+   // Only lowercase slugs
+   { path: /^\/products\/(?<slug>[a-z-]+)$/, component: ProductPage }
+   ```
+
+3. **Lazy load pages for better performance**
+   ```javascript
+   const routes = [
+     { path: '/', component: () => import('./Home.js').then(m => m.default) },
+     { path: '/about', component: () => import('./About.js').then(m => m.default) },
+   ];
+   ```
+
+4. **Access route params anywhere**
+   ```javascript
+   // In any component, not just pages
+   const currentParams = () => {
+     const match = window.location.hash.match(/^#\/users\/(?<id>\d+)$/);
+     return match?.groups || {};
+   };
+   ```
+
+---
+
+### 🎉 Why SigPro Router?
+
+- **Zero config** - Works immediately
+- **No dependencies** - Just vanilla JS
+- **Automatic cleanup** - No memory leaks
+- **Tiny footprint** - ~0.5KB minified
+- **Hash-based** - Works everywhere
+- **RegExp support** - Full routing power
+- **Page components** - Built for `$.page`
 
 ---