`;
}, ['messages', 'currentMessage'], true);
```
**Usage - embed in ANY website:**
```html
```
---
### π― **Quick Decision Guide**
| Use Light DOM (`false`) when... | Use Shadow DOM (`true`) when... |
|--------------------------------|-------------------------------|
| β Component is part of your main app | β Building a UI library for others |
| β Using global CSS (Tailwind, Bootstrap) | β Creating embeddable widgets |
| β Need to inherit theme variables | β Styles must be pixel-perfect everywhere |
| β Working with existing design system | β Component has complex, specific styles |
| β Quick prototyping | β Distributing to different projects |
| β Form elements that should match site | β Need style isolation/encapsulation |
### π‘ **Pro Tips**
1. **Light DOM components** are great for app-specific UI that should feel "native" to your site
2. **Shadow DOM components** are perfect for reusable "products" that must look identical everywhere
3. You can mix both in the same app - choose per component based on needs
4. Shadow DOM also provides DOM isolation - great for complex widgets
```javascript
// Mix and match in the same app!
$.component('app-header', setup, ['title']); // Light DOM
$.component('user-menu', setup, ['items']); // Light DOM
$.component('chat-widget', setup, ['messages'], true); // Shadow DOM
$.component('data-grid', setup, ['columns', 'data'], true); // Shadow DOM
```
---
### `$.fetch(url, data, [loading])` - Fetch
Simple fetch wrapper with automatic JSON handling and optional loading signal.
```javascript
import { $ } from 'sigpro';
const loading = $(false);
async function loadUser(id) {
const data = await $.fetch(`/api/users/${id}`, null, loading);
if (data) userData(data);
}
// In your UI
html`
`;
```
**Parameters:**
- `url`: Endpoint URL
- `data`: Data to send (auto JSON.stringify'd)
- `loading`: Optional signal function to track loading state
**Returns:** `Promise` - Parsed JSON response or null on error
---
### `$.storage(key, initialValue, [storage])` - Persistent Signal
Signal that automatically syncs with localStorage or sessionStorage.
```javascript
import { $ } from 'sigpro';
// Automatically saves to localStorage
const theme = $.storage('theme', 'light');
const user = $.storage('user', null);
theme('dark'); // Saved to localStorage
// Page refresh... theme() returns 'dark'
// Use sessionStorage instead
const tempData = $.storage('temp', {}, sessionStorage);
```
**Parameters:**
- `key`: Storage key name
- `initialValue`: Default value if none stored
- `storage`: Storage type (default: `localStorage`, options: `sessionStorage`)
**Returns:** Signal function that persists to storage on changes
---
## π§ `$.router(routes)` - Hash-Based Router
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/HomePage.js';
import AboutPage from './pages/AboutPage.js';
import UserPage from './pages/UserPage.js';
import NotFound from './pages/NotFound.js';
// Define your routes
const routes = [
{ path: '/', component: () => HomePage() },
{ path: '/about', component: () => AboutPage() },
{ path: '/users/:id', component: (params) => UserPage(params) },
{ path: /^\/posts\/(?\d+)$/, component: (params) => PostPage(params) },
];
// Create and mount the router
const router = $.router(routes);
document.body.appendChild(router);
```
---
### π 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\/(?\d+)$/, component: (params) => UserPage(params) }
// Match product slugs (letters, numbers, hyphens)
{ path: /^\/products\/(?[a-z0-9-]+)$/, component: (params) => ProductPage(params) }
// Match blog posts by year/month
{ path: /^\/blog\/(?\d{4})\/(?\d{2})$/, component: (params) => BlogArchive(params) }
// Match optional language prefix
{ path: /^\/(?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\/(?\d+)$/
// URL: '#/posts/123'
{ path: /^\/posts\/(?\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`
${loading() ? 'Loading...' : html`
${userData().name}
`}
`;
});
```
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`
`;
```
#### 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`
`;
// 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`
${loading() ? html`
Loading...
` : ''}
${error() ? html`
${error()}
` : ''}
${post() ? html`
${post().title}
${post().content}
β Back to blog
` : ''}
`;
});
// 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\/(?[^/]+)(?:\/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``;
}
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` | 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\/(?\d+)$/, component: UserPage }
// Only lowercase slugs
{ path: /^\/products\/(?[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\/(?\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`
---
### `html` - Template Literal Tag
Creates reactive DOM fragments using template literals.
#### Basic Usage
```javascript
import { $, html } from 'sigpro';
const count = $(0);
const fragment = html`