snice 3.6.0 → 3.8.0

package/docs/components/timer.md

@@ -0,0 +1,143 @@
+# Timer Component
+
+The `<snice-timer>` component provides a stopwatch and countdown timer.
+
+## Basic Usage
+
+```html
+<!-- Stopwatch -->
+<snice-timer mode="stopwatch"></snice-timer>
+
+<!-- Countdown Timer -->
+<snice-timer mode="timer" initial-time="60"></snice-timer>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'stopwatch' \| 'timer'` | `'stopwatch'` | Timer mode |
+| `initial-time` | `number` | `0` | Starting time in seconds (for timer mode) |
+| `running` | `boolean` | `false` | Timer running state (read-only) |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start()` | `void` | Start the timer |
+| `stop()` | `void` | Stop/pause the timer |
+| `reset()` | `void` | Reset to initial state |
+| `getTime()` | `number` | Get current time in seconds |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/timer-start` | `{ timer, time }` | Timer started |
+| `@snice/timer-stop` | `{ timer, time }` | Timer stopped |
+| `@snice/timer-reset` | `{ timer, time }` | Timer reset |
+| `@snice/timer-complete` | `{ timer }` | Countdown completed (timer mode only) |
+
+## Examples
+
+### Stopwatch
+
+```html
+<snice-timer id="stopwatch" mode="stopwatch"></snice-timer>
+
+<script>
+  const stopwatch = document.getElementById('stopwatch');
+  stopwatch.start();
+
+  // Later...
+  stopwatch.stop();
+  console.log('Elapsed:', stopwatch.getTime(), 'seconds');
+</script>
+```
+
+### Countdown Timer
+
+```html
+<snice-timer id="timer" mode="timer" initial-time="300"></snice-timer>
+
+<script>
+  const timer = document.getElementById('timer');
+
+  timer.addEventListener('@snice/timer-complete', () => {
+    console.log('Time is up!');
+  });
+
+  timer.start();
+</script>
+```
+
+### Programmatic Control
+
+```html
+<snice-timer id="my-timer"></snice-timer>
+
+<button onclick="document.getElementById('my-timer').start()">Start</button>
+<button onclick="document.getElementById('my-timer').stop()">Stop</button>
+<button onclick="document.getElementById('my-timer').reset()">Reset</button>
+
+<script>
+  const timer = document.getElementById('my-timer');
+
+  timer.addEventListener('@snice/timer-start', (e) => {
+    console.log('Timer started at', e.detail.time);
+  });
+
+  timer.addEventListener('@snice/timer-stop', (e) => {
+    console.log('Timer stopped at', e.detail.time);
+  });
+</script>
+```
+
+### Workout Timer
+
+```html
+<snice-timer id="workout" mode="timer" initial-time="45"></snice-timer>
+
+<script>
+  const workout = document.getElementById('workout');
+
+  workout.addEventListener('@snice/timer-complete', () => {
+    alert('Rest time!');
+    // Start rest period
+    workout.initialTime = 15;
+    workout.reset();
+    workout.start();
+  });
+
+  workout.start();
+</script>
+```
+
+## Styling
+
+The timer uses CSS custom properties from the theme system:
+
+```css
+snice-timer {
+  --snice-color-background-element: rgb(252 251 249);
+  --snice-color-border: rgb(226 226 226);
+  --snice-color-text: rgb(23 23 23);
+  --snice-color-success: rgb(22 163 74);
+  --snice-color-warning: rgb(202 138 4);
+  --snice-color-neutral: rgb(82 82 82);
+}
+```
+
+## Accessibility
+
+- Large, readable time display
+- Clear button labels and icons
+- Keyboard accessible controls
+- High contrast buttons
+
+## Best Practices
+
+1. **Choose the right mode**: Use stopwatch for tracking elapsed time, timer for countdowns
+2. **Handle timer-complete**: Listen for completion events in timer mode
+3. **Provide context**: Add labels or descriptions near the timer
+4. **Reset appropriately**: Call `reset()` to return to initial state

package/docs/fetcher.md

@@ -0,0 +1,447 @@
+# Fetch Middleware
+
+Snice provides a context-aware fetch implementation with middleware support, allowing you to intercept and modify HTTP requests and responses globally across your application.
+
+## Overview
+
+The `ContextAwareFetcher` class enables you to:
+
+- Add authentication headers automatically to all requests
+- Handle errors consistently across your application
+- Log HTTP requests and responses
+- Transform requests or responses
+- Implement retry logic
+- Add request/response timing metrics
+- Access application and navigation state in middleware
+
+## Basic Usage
+
+```typescript
+import { Router, ContextAwareFetcher } from 'snice';
+
+// Create a fetcher instance
+const fetcher = new ContextAwareFetcher();
+
+// Add request middleware (runs before fetch)
+fetcher.use('request', function(request, next) {
+  // `this` is bound to the Context instance
+  const token = this.application.user?.token;
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+});
+
+// Add response middleware (runs after fetch)
+fetcher.use('response', async function(response, next) {
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return next();
+});
+
+// Pass fetcher to Router
+const router = Router({
+  target: '#app',
+  context: { user: null },
+  fetcher
+});
+
+router.initialize();
+```
+
+## Using Context.fetch in Pages
+
+Once configured, `ctx.fetch` is available in all pages and components that use the `@context` decorator:
+
+```typescript
+@page({ tag: 'user-page', routes: ['/users/:id'] })
+class UserPage extends HTMLElement {
+  private ctx: Context;
+
+  @context()
+  handleContext(ctx: Context) {
+    this.ctx = ctx;
+  }
+
+  @ready()
+  async loadUser() {
+    try {
+      // Middleware is automatically applied
+      const user = await this.ctx.fetch('/api/users/123')
+        .then(r => r.json());
+
+      console.log('User loaded:', user);
+    } catch (error) {
+      console.error('Failed to load user:', error);
+    }
+  }
+}
+```
+
+## Middleware Types
+
+### Request Middleware
+
+Request middleware runs **before** the actual fetch call. It receives the `Request` object and can modify it before the request is sent.
+
+**Signature:**
+```typescript
+type RequestMiddleware = (
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+) => Promise<Response>
+```
+
+**Common use cases:**
+- Adding authentication headers
+- Modifying request URLs (e.g., adding base URL)
+- Logging outgoing requests
+- Adding custom headers (CSRF tokens, API keys, etc.)
+- Request validation
+
+**Example - Authentication:**
+```typescript
+fetcher.use('request', function(request, next) {
+  const token = this.application.auth?.token;
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+});
+```
+
+**Example - Base URL:**
+```typescript
+fetcher.use('request', function(request, next) {
+  const url = new URL(request.url);
+  if (!url.hostname) {
+    // Relative URL, add base
+    const baseUrl = this.application.config?.apiBaseUrl || 'https://api.example.com';
+    const newRequest = new Request(`${baseUrl}${request.url}`, request);
+    return next(); // Note: modifying request in place doesn't work, would need to reconstruct
+  }
+  return next();
+});
+```
+
+**Example - Request Logging:**
+```typescript
+fetcher.use('request', function(request, next) {
+  console.log(`[${this.navigation.route}] ${request.method} ${request.url}`);
+  return next();
+});
+```
+
+### Response Middleware
+
+Response middleware runs **after** the fetch call completes. It receives the `Response` object and can inspect or transform it.
+
+**Signature:**
+```typescript
+type ResponseMiddleware = (
+  this: Context,
+  response: Response,
+  next: () => Promise<Response>
+) => Promise<Response>
+```
+
+**Common use cases:**
+- Error handling based on status codes
+- Response transformation
+- Logging responses
+- Caching
+- Performance metrics
+- Retry logic
+
+**Example - Error Handling:**
+```typescript
+fetcher.use('response', async function(response, next) {
+  if (!response.ok) {
+    const error = await response.text();
+    console.error(`[${this.navigation.route}] HTTP ${response.status}:`, error);
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  return next();
+});
+```
+
+**Example - Response Logging:**
+```typescript
+fetcher.use('response', async function(response, next) {
+  console.log(`[${this.navigation.route}] Response ${response.status} from ${response.url}`);
+  return next();
+});
+```
+
+**Example - Performance Metrics:**
+```typescript
+const timings = new WeakMap();
+
+fetcher.use('request', function(request, next) {
+  timings.set(request, Date.now());
+  return next();
+});
+
+fetcher.use('response', async function(response, next) {
+  const request = timings.get(response); // Note: this won't work as response doesn't reference request
+  // Better approach: use a Map with URL as key
+  const duration = Date.now() - startTime;
+  console.log(`Request took ${duration}ms`);
+  return next();
+});
+```
+
+## Accessing Context
+
+Middleware functions have `this` bound to the `Context` instance, giving you access to:
+
+- `this.application` - Application-wide state (user, config, theme, etc.)
+- `this.navigation` - Navigation state (current route, route params, placards)
+- `this.id` - Unique context instance ID
+
+**Example - Context-Aware Error Handling:**
+```typescript
+fetcher.use('response', async function(response, next) {
+  if (response.status === 401) {
+    // Unauthorized - clear user and redirect to login
+    this.application.user = null;
+    this.application.router?.navigate('/login');
+    throw new Error('Authentication required');
+  }
+
+  if (response.status === 403) {
+    // Forbidden - log and show error
+    console.error(`Access denied on route: ${this.navigation.route}`);
+    throw new Error('Access forbidden');
+  }
+
+  return next();
+});
+```
+
+## Middleware Execution Order
+
+Middleware executes in the order it's registered:
+
+1. Request middleware runs in registration order (first registered = first executed)
+2. Actual `fetch()` call happens
+3. Response middleware runs in registration order
+
+**Example:**
+```typescript
+const fetcher = new ContextAwareFetcher();
+
+fetcher.use('request', function(request, next) {
+  console.log('Request middleware 1');
+  return next();
+});
+
+fetcher.use('request', function(request, next) {
+  console.log('Request middleware 2');
+  return next();
+});
+
+fetcher.use('response', async function(response, next) {
+  console.log('Response middleware 1');
+  return next();
+});
+
+fetcher.use('response', async function(response, next) {
+  console.log('Response middleware 2');
+  return next();
+});
+
+// Output when fetch is called:
+// Request middleware 1
+// Request middleware 2
+// (actual fetch happens)
+// Response middleware 1
+// Response middleware 2
+```
+
+## Complete Example
+
+Here's a complete example with authentication, error handling, and logging:
+
+```typescript
+import { Router, ContextAwareFetcher } from 'snice';
+
+interface AppContext {
+  user?: {
+    token: string;
+    id: string;
+  };
+  config: {
+    apiBaseUrl: string;
+  };
+}
+
+const fetcher = new ContextAwareFetcher();
+
+// Add authentication token
+fetcher.use('request', function(request, next) {
+  const token = this.application.user?.token;
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+});
+
+// Log all requests
+fetcher.use('request', function(request, next) {
+  const route = this.navigation.route;
+  console.log(`[${route}] ${request.method} ${request.url}`);
+  return next();
+});
+
+// Handle errors globally
+fetcher.use('response', async function(response, next) {
+  if (response.status === 401) {
+    // Clear auth and redirect
+    this.application.user = undefined;
+    window.location.href = '/#/login';
+    throw new Error('Authentication required');
+  }
+
+  if (response.status >= 400) {
+    const errorText = await response.clone().text();
+    console.error(`HTTP ${response.status}:`, errorText);
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  return next();
+});
+
+// Log responses
+fetcher.use('response', async function(response, next) {
+  console.log(`[${this.navigation.route}] Response ${response.status}`);
+  return next();
+});
+
+const router = Router({
+  target: '#app',
+  context: {
+    config: {
+      apiBaseUrl: 'https://api.example.com'
+    }
+  },
+  fetcher
+});
+
+router.initialize();
+```
+
+## Important Notes
+
+### Context is Long-Lived
+
+The `Context` instance is created once per Router and persists for the entire application lifetime. This means:
+
+- Middleware is configured once at application startup
+- `ctx.fetch` is initialized once and reused
+- Middleware can safely reference `this.application` and `this.navigation` as they update in place
+
+### Request Objects are Immutable
+
+The `Request` object passed to middleware is immutable. To modify it, you need to create a new Request:
+
+```typescript
+fetcher.use('request', function(request, next) {
+  // This won't work - headers are read-only on Request
+  // request.headers.set('X-Custom', 'value');
+
+  // Instead, create a new Request
+  const newRequest = new Request(request, {
+    headers: new Headers(request.headers)
+  });
+  newRequest.headers.set('X-Custom', 'value');
+
+  // But this is complex - better to set headers before creating Request
+  return next();
+});
+```
+
+In practice, it's better to set headers by modifying the `headers` property if it exists, or reconstructing the request entirely.
+
+### No Fetcher Means Native Fetch
+
+If no `fetcher` is provided to the Router, `ctx.fetch` defaults to the native `fetch` function bound to the Context instance:
+
+```typescript
+// No fetcher provided
+const router = Router({
+  target: '#app',
+  context: {}
+});
+
+// In pages, ctx.fetch is just native fetch (with `this` bound to Context)
+```
+
+## API Reference
+
+### ContextAwareFetcher
+
+**Constructor:**
+```typescript
+new ContextAwareFetcher()
+```
+
+**Methods:**
+
+**`use(type: 'request', middleware: RequestMiddleware): void`**
+
+Add request middleware that runs before the fetch call.
+
+**`use(type: 'response', middleware: ResponseMiddleware): void`**
+
+Add response middleware that runs after the fetch call.
+
+**`create(ctx: Context): typeof globalThis.fetch`**
+
+Create a fetch function bound to the given Context instance. This is called internally by the Router.
+
+### Type Definitions
+
+```typescript
+type RequestMiddleware = (
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+) => Promise<Response>
+
+type ResponseMiddleware = (
+  this: Context,
+  response: Response,
+  next: () => Promise<Response>
+) => Promise<Response>
+
+interface Fetcher {
+  use(type: 'request', middleware: RequestMiddleware): void;
+  use(type: 'response', middleware: ResponseMiddleware): void;
+  create(ctx: Context): typeof globalThis.fetch;
+}
+```
+
+## Best Practices
+
+1. **Configure middleware at startup** - Don't add middleware inside pages or components, as this would add duplicate middleware on each navigation.
+
+2. **Keep middleware focused** - Each middleware should do one thing well (auth, logging, error handling, etc.).
+
+3. **Use `this.application` for app state** - Access user, config, and other app-wide state via the Context.
+
+4. **Clone responses if needed** - If you need to read the response body in middleware, clone it first as streams can only be read once:
+   ```typescript
+   fetcher.use('response', async function(response, next) {
+     const clone = response.clone();
+     const text = await clone.text();
+     console.log('Response body:', text);
+     return next(); // Original response still has readable body
+   });
+   ```
+
+5. **Handle errors gracefully** - Always consider what should happen when requests fail.
+
+6. **Call `next()`** - Every middleware must call and return `next()` to continue the chain.

package/docs/routing.md

@@ -40,6 +40,7 @@ interface RouterOptions<T = any> {
   transition?: Transition;           // Global transition config
   layout?: string;                   // Default layout for all pages
   context?: T;                       // Router context object (shared state)
+  fetcher?: Fetcher;                 // Optional fetch middleware (see docs/fetcher.md)
 }
 ```
 
@@ -130,6 +131,7 @@ class ProfilePage extends HTMLElement {
     // ctx.application is your router context (AppContext)
     this.appContext = ctx.application;
     // ctx.navigation contains { placards, route, params }
+    // ctx.fetch is available for HTTP requests (with middleware if configured)
     this.requestRender();
   }
 
@@ -205,13 +207,14 @@ class DashboardPage extends HTMLElement {
 The Context object passed to `@context()` methods has the following structure:
 
 ```typescript
-interface Context<T = any> {
-  application: T;  // Your router context (e.g., AppContext)
+interface Context {
+  application: AppContext;  // Your router context (e.g., { user, theme, config })
   navigation: {
     placards: Placard[];           // All page placards
     route: string;                  // Current route name
     params: Record<string, string>; // Route parameters
   };
+  fetch: typeof globalThis.fetch;  // Fetch function with middleware support
   update(): void;  // Notify all subscribers of changes
 }
 ```
@@ -221,10 +224,10 @@ interface Context<T = any> {
 ```typescript
 @page({ tag: 'user-page', routes: ['/users/:userId'] })
 class UserPage extends HTMLElement {
-  private ctx?: Context<AppContext>;
+  private ctx?: Context;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.ctx = ctx;
 
     // Access application state
@@ -248,10 +251,10 @@ When you modify the application context, call `update()` to notify all subscribe
 ```typescript
 @page({ tag: 'settings-page', routes: ['/settings'] })
 class SettingsPage extends HTMLElement {
-  private ctx?: Context<AppContext>;
+  private ctx?: Context;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.ctx = ctx;
     this.requestRender();
   }
@@ -1064,7 +1067,7 @@ class DashboardPage extends HTMLElement {
   private appContext?: AppContext;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.appContext = ctx.application;
     this.requestRender();
   }
@@ -1091,7 +1094,7 @@ class LoginPage extends HTMLElement {
   private appContext?: AppContext;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.appContext = ctx.application;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "type": "module",
   "description": "Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "dist/index.cjs",
@@ -112,6 +112,7 @@
     "@vitest/ui": "^1.0.0",
     "clean-css": "^5.3.3",
     "happy-dom": "^12.0.0",
+    "qrcode": "^1.5.4",
     "rollup": "^4.50.2",
     "semantic-release": "^24.2.7",
     "typescript": "^5.9.2",