snice 4.12.0 → 4.14.0

package/docs/fetcher.md

@@ -22,12 +22,12 @@ import { Router, ContextAwareFetcher } from 'snice';
 // Create a fetcher instance
 const fetcher = new ContextAwareFetcher();
 
-// Add request middleware (runs before fetch)
+// Attach JWT to outgoing requests
 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}`);
+  const jwt = this.application.principal?.token;
+  if (jwt) {
+    request.headers.set('Authorization', `Bearer ${jwt}`);
   }
   return next();
 });
@@ -43,7 +43,7 @@ fetcher.use('response', async function(response, next) {
 // Pass fetcher to Router
 const router = Router({
   target: '#app',
-  context: { user: null },
+  context: { auth: null },
   fetcher
 });
 
@@ -101,26 +101,43 @@ type RequestMiddleware = (
 - Adding custom headers (CSRF tokens, API keys, etc.)
 - Request validation
 
-**Example - Authentication:**
+**Example - JWT Bearer Token:**
+
+`this` in middleware is the `Context` instance. Store auth state in `application` (your `AppContext`):
+
 ```typescript
+// Attach JWT to every request
 fetcher.use('request', function(request, next) {
-  const token = this.application.auth?.token;
-  if (token) {
-    request.headers.set('Authorization', `Bearer ${token}`);
+  const jwt = this.application.principal?.token;
+  if (jwt) {
+    request.headers.set('Authorization', `Bearer ${jwt}`);
   }
   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
+// Handle expired tokens — refresh or redirect to login
+fetcher.use('response', async function(response, next) {
+  if (response.status === 401) {
+    const refreshToken = this.application.principal?.refreshToken;
+    if (refreshToken) {
+      const res = await fetch('/api/auth/refresh', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken })
+      });
+      if (res.ok) {
+        const { token } = await res.json();
+        this.application.principal.token = token;
+        // Retry original request with new token
+        const retry = new Request(response.url, {
+          headers: { 'Authorization': `Bearer ${token}` }
+        });
+        return fetch(retry);
+      }
+    }
+    this.application.principal = null;
+    window.location.hash = '#/login';
+    throw new Error('Session expired');
   }
   return next();
 });
@@ -177,18 +194,19 @@ fetcher.use('response', async function(response, next) {
 
 **Example - Performance Metrics:**
 ```typescript
-const timings = new WeakMap();
+const timings = new Map<string, number>();
 
 fetcher.use('request', function(request, next) {
-  timings.set(request, Date.now());
+  timings.set(request.url, 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`);
+  const start = timings.get(response.url);
+  if (start) {
+    console.log(`${response.url} took ${Date.now() - start}ms`);
+    timings.delete(response.url);
+  }
   return next();
 });
 ```
@@ -207,7 +225,7 @@ 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');
+    window.location.hash = '#/login';
     throw new Error('Authentication required');
   }
 
@@ -269,22 +287,20 @@ Here's a complete example with authentication, error handling, and logging:
 import { Router, ContextAwareFetcher } from 'snice';
 
 interface AppContext {
-  user?: {
-    token: string;
-    id: string;
-  };
-  config: {
-    apiBaseUrl: string;
+  auth?: {
+    token: string;      // JWT access token
+    refreshToken: string;
+    userId: string;
   };
 }
 
 const fetcher = new ContextAwareFetcher();
 
-// Add authentication token
+// Attach JWT to every request
 fetcher.use('request', function(request, next) {
-  const token = this.application.user?.token;
-  if (token) {
-    request.headers.set('Authorization', `Bearer ${token}`);
+  const jwt = this.application.principal?.token;
+  if (jwt) {
+    request.headers.set('Authorization', `Bearer ${jwt}`);
   }
   return next();
 });
@@ -296,13 +312,12 @@ fetcher.use('request', function(request, next) {
   return next();
 });
 
-// Handle errors globally
+// Handle 401 — attempt token refresh, then redirect on failure
 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');
+    this.application.principal = undefined;
+    window.location.hash = '#/login';
+    throw new Error('Session expired');
   }
 
   if (response.status >= 400) {
@@ -314,19 +329,9 @@ fetcher.use('response', async function(response, next) {
   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'
-    }
-  },
+  context: {},
   fetcher
 });
 
@@ -343,28 +348,17 @@ The `Context` instance is created once per Router and persists for the entire ap
 - `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
+### Modifying Request Headers
 
-The `Request` object passed to middleware is immutable. To modify it, you need to create a new Request:
+The `Request` object's `headers` property is mutable — you can call `request.headers.set()` directly in middleware:
 
 ```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
+  request.headers.set('X-Custom', 'value');
   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:
@@ -424,15 +418,11 @@ interface Fetcher {
 }
 ```
 
-## Best Practices
-
-1. **Configure middleware at startup** - Don't add middleware inside pages or components, as this would add duplicate middleware on each navigation.
+## Notes
 
-2. **Keep middleware focused** - Each middleware should do one thing well (auth, logging, error handling, etc.).
+- **Configure middleware at startup** — don't add middleware inside pages, as it would duplicate on each navigation.
 
-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:
+- **Clone responses before reading** — streams can only be read once:
    ```typescript
    fetcher.use('response', async function(response, next) {
      const clone = response.clone();
@@ -442,6 +432,4 @@ interface Fetcher {
    });
    ```
 
-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.
+- **Always call `next()`** — every middleware must call and return `next()` to continue the chain.

package/docs/observe.md

@@ -336,35 +336,24 @@ class ViewportController implements IController {
 
 ## Options
 
-### Common Options
-
-All observers support these options:
+All observer types share a single options interface. Pass only the fields relevant to the observer type you're using:
 
 ```typescript
 interface ObserveOptions {
-  throttle?: number;  // Throttle callbacks by milliseconds
-}
-```
-
-### Specific Options
-
-```typescript
-// Intersection Observer
-interface IntersectionOptions extends ObserveOptions {
-  threshold?: number | number[];  // 0-1 visibility threshold
+  // Intersection Observer
+  threshold?: number | number[];  // 0-1 visibility percentage
   rootMargin?: string;            // Margin around root
   root?: Element | null;          // Viewport element
-}
 
-// Resize Observer
-interface ResizeOptions extends ObserveOptions {
+  // Resize Observer
   box?: 'content-box' | 'border-box';  // Box model to observe
-}
 
-// Mutation Observer
-interface MutationOptions extends ObserveOptions {
-  subtree?: boolean;     // Observe descendants
-  maxDepth?: number;     // Limit subtree depth
+  // Mutation Observer
+  subtree?: boolean;     // Observe descendants (use with caution)
+  maxDepth?: number;     // Safety limit for subtree depth
+
+  // All observers
+  throttle?: number;     // Throttle callbacks by milliseconds
 }
 ```
 
@@ -547,16 +536,11 @@ class Dashboard extends HTMLElement {
 }
 ```
 
-### Form Auto-Save
+### Dynamic Form Fields
 
 ```typescript
-@element('auto-save-form')
-class AutoSaveForm extends HTMLElement {
-  @observe('mutation:attributes:value', 'input, textarea', { throttle: 1000 })
-  handleInputChange(mutations: MutationRecord[]) {
-    this.saveFormData();
-  }
-
+@element('dynamic-form')
+class DynamicForm extends HTMLElement {
   @observe('mutation:childList', '.dynamic-fields')
   handleFieldsAdded(mutations: MutationRecord[]) {
     mutations.forEach(mutation => {
@@ -577,10 +561,6 @@ class AutoSaveForm extends HTMLElement {
     `;
   }
 
-  saveFormData() {
-    // Save logic
-  }
-
   initializeField(field: Element) {
     // Initialize logic
   }

package/docs/placards.md

@@ -17,7 +17,8 @@ The Placard system allows pages to declare metadata that describes their purpose
 Define a placard for your page using the `placard` option in the `@page` decorator:
 
 ```typescript
-import { page, Placard, render, html } from 'snice';
+import { Placard, render, html } from 'snice';
+import { page } from './router'; // page comes from Router(), not from 'snice'
 
 const placard: Placard<AppContext> = {
   name: 'dashboard',
@@ -151,8 +152,9 @@ parent: 'users'  // Child of the 'users' page
 ### Dynamic Visibility
 
 **`visibleOn`** (optional)
-- Guard functions that determine if the page should appear in navigation
-- Reuses the same guard system as route protection
+- Guard functions for layouts to evaluate when building navigation menus
+- The router passes all placards to layouts unfiltered — layouts must check `visibleOn` themselves
+- Reuses the same guard type as route protection
 
 ```typescript
 visibleOn: [isAuthenticated, hasAdminRole]
@@ -223,7 +225,7 @@ const settingsPlacard: Placard<AppContext> = {
   name: 'user-settings',
   title: 'Settings',
   parent: 'user-profile'
-  // Breadcrumbs will be auto-resolved: Users > Profile > Settings
+  // Layout can resolve breadcrumbs using parent chain: Users > Profile > Settings
 };
 
 // Explicit breadcrumbs
@@ -387,15 +389,3 @@ class BreadcrumbLayout extends HTMLElement implements Layout {
 }
 ```
 
-## Best Practices
-
-1. **Use consistent naming**: Use kebab-case for placard names
-2. **Provide helpful icons**: Visual indicators improve navigation UX
-3. **Set meaningful order**: Lower numbers appear first in navigation
-4. **Use groups wisely**: Group related pages for better organization
-5. **Define search terms**: Help users discover features through search
-6. **Leverage guards**: Use visibleOn to show/hide navigation based on permissions
-7. **Explicit when needed**: Use explicit breadcrumbs for complex hierarchies
-8. **Keep titles short**: Navigation labels should be concise
-9. **Provide tooltips**: Add helpful context for ambiguous page names
-10. **Use parent relationships**: Build hierarchical navigation automatically