snice 3.6.0 → 3.8.0

package/README.md

@@ -416,10 +416,10 @@ When you modify the application context, call `update()` to notify all subscribe
 ```typescript
 @page({ tag: 'login-page', routes: ['/login'] })
 class LoginPage extends HTMLElement {
-  private ctx?: Context<AppContext>;
+  private ctx?: Context;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.ctx = ctx;
     this.requestRender();
   }

package/bin/snice.js

@@ -46,13 +46,12 @@ Options:
 
 Templates:
   base    - Minimal starter with counter example (default)
-  social  - Social media sample app showcasing components
+  pwa     - Progressive Web App with auth, middleware, and live notifications
 
 Examples:
   snice create-app my-app
-  snice create-app my-app --template=social
-  snice create-app --template=social my-app
-  npx snice create-app my-app --template=social
+  snice create-app my-app --template=pwa
+  npx snice create-app my-app --template=pwa
 `);
 }
 
@@ -90,7 +89,7 @@ function createApp(projectPath, template = 'base') {
   // Check if template exists
   if (!existsSync(templateDir)) {
     console.error(`❌ Template "${template}" not found!`);
-    console.error(`Available templates: base, social`);
+    console.error(`Available templates: base, pwa`);
     process.exit(1);
   }
 

package/bin/templates/CLAUDE.md

@@ -17,13 +17,23 @@ src/
   pages/          # @page decorated route components
   components/     # @element decorated UI components
   controllers/    # @controller decorated behavior modules
+  utils/          # Pure functions, helpers (formatDate, debounce)
+  services/       # Stateless static functions for business logic/external APIs
+  daemons/        # Stateful classes with lifecycle (start/stop/dispose)
+  middleware/     # Composable middleware (fetch, logging, etc)
+  guards/         # Route guards
+  types/          # TypeScript types
   styles/         # Global CSS
 ```
 
 **Separation of concerns:**
-- **Pages** - Orchestrate elements, handle URLs
-- **Elements** - Pure presentation, no business logic
-- **Controllers** - Behavior, data fetching, swappable
+- **Pages** - Orchestrate elements, handle URLs, most logic happens here
+- **Components** - Pure presentation, no business logic
+- **Controllers** - Attach to elements, add business behavior unsuitable for the page or components
+- **Services** - Stateless business logic, API calls
+- **Daemons** - Lifecycle-managed (WebSocket, P2P, intervals)
+- **Middleware** - Composable functions (auth, retry)
+- **Utils** - Pure helper functions
 
 ## Decorators
 
@@ -129,6 +139,18 @@ html`
 - **Element ↔ Controller:** Request/Response (`@request`, `@respond`)
 - **Global State:** Context (`@context()`)
 
+## Common Mistakes
+
+**Controllers are NOT global services.** They attach to elements via `controller="name"`. Use `utils/` for shared logic like API calls, auth, toasts.
+
+**@request/@respond is NOT a service bus.** It's for element-to-element or element-to-controller communication only. Use utility functions for app-wide features.
+
+**Guards receive Context, not AppContext.** Check `ctx.application.property`, not `ctx.property`. Guards: `(ctx: Context) => boolean`
+
+**Context must be mutated then updated.** After changing `ctx.application`, call `ctx.update()` to notify subscribers. Pages need `@context()` to get context reference.
+
+**@property is for parent-provided attributes.** Internal component state should be regular properties, not decorated. Only use `@property()` when the value comes from a parent element via attributes.
+
 ## Build Commands
 
 ```bash

package/bin/templates/pwa/README.md

@@ -0,0 +1,188 @@
+# {{projectName}}
+
+A Progressive Web App (PWA) built with [Snice](https://github.com/sniceio/snice).
+
+## Features
+
+- ⚡ **JWT Authentication** - Token-based auth with automatic refresh
+- 🔒 **Protected Routes** - Route guards for authenticated pages
+- 🎯 **Middleware Pattern** - Composable fetch middleware (auth, error, retry)
+- 📱 **PWA Ready** - Service worker, offline support, installable
+- 🔔 **Live Notifications** - WebSocket daemon for real-time updates
+- 🎨 **Snice Components** - Pre-built UI components
+- 📦 **Type-Safe** - Full TypeScript support
+- 🚀 **Fast Build** - Vite + SWC for blazing fast dev and builds
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+
+# Type check
+npm run type-check
+```
+
+## Demo Credentials
+
+- **Email:** demo@example.com
+- **Password:** demo
+
+## Project Structure
+
+```
+src/
+  utils/          # Pure helper functions
+  services/       # Business logic (auth, storage, jwt)
+  middleware/     # Fetch middleware (auth, error, retry)
+  daemons/        # Lifecycle-managed classes (notifications WebSocket)
+  guards/         # Route guards (auth)
+  types/          # TypeScript types
+  pages/          # Routable pages (@page decorator)
+  styles/         # Global styles
+```
+
+## Architecture Patterns
+
+### Context-Aware Fetcher
+
+Built-in middleware system with context access:
+
+```typescript
+// fetcher.ts - Setup
+import { ContextAwareFetcher } from 'snice';
+
+const fetcher = new ContextAwareFetcher();
+fetcher.use('request', authMiddleware);
+fetcher.use('response', errorMiddleware);
+
+// Middleware with context access
+export async function authMiddleware(
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+): Promise<Response> {
+  const token = getToken();
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+}
+
+// Usage in pages via ctx.fetch()
+async loadData() {
+  const response = await this.ctx.fetch('/api/data');
+  const data = await response.json();
+}
+```
+
+### Daemons for Lifecycle Management
+
+Use daemons for resources that need start/stop/dispose:
+
+```typescript
+const daemon = getNotificationsDaemon();
+daemon.start(); // In main.ts
+
+// In component
+const unsubscribe = daemon.subscribe((notification) => {
+  console.log(notification);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+### Route Guards
+
+Protect routes with guards:
+
+```typescript
+import { authGuard } from './guards/auth';
+
+@page({
+  tag: 'dashboard-page',
+  routes: ['/dashboard'],
+  guards: [authGuard]
+})
+export class DashboardPage extends HTMLElement {
+  // ...
+}
+```
+
+### Context for Global State
+
+Access shared state via context:
+
+```typescript
+import type { Principal } from './types/auth';
+
+@context()
+handleContext(ctx: Context) {
+  const principal = ctx.application.principal as Principal | undefined;
+  this.user = principal?.user;
+}
+```
+
+## Customization
+
+### Replace Mock API
+
+Update `src/services/auth.ts` to call your real API:
+
+```typescript
+export async function login(credentials: LoginCredentials) {
+  const response = await fetch('https://your-api.com/auth/login', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(credentials)
+  });
+
+  const data = await response.json();
+  setToken(data.token);
+  setUser(data.user);
+  return data;
+}
+```
+
+### Enable Real WebSocket
+
+Update `src/daemons/notifications.ts`:
+
+```typescript
+// Replace startMockNotifications() with:
+this.connect();
+```
+
+### Configure Environment
+
+Create `.env` file:
+
+```
+VITE_API_URL=https://your-api.com
+VITE_WS_URL=wss://your-ws.com
+```
+
+### Update Icons
+
+Replace placeholder icons in `public/icons/`:
+- `icon-192.png` (192x192)
+- `icon-512.png` (512x512)
+
+## Learn More
+
+- [Snice Documentation](https://sniceio.github.io/snice)
+- [Vite PWA Plugin](https://vite-pwa-org.netlify.app/)
+
+## License
+
+MIT

package/bin/templates/pwa/global.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_URL?: string;
+  readonly VITE_WS_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/bin/templates/pwa/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="{{projectName}} - PWA built with Snice" />
+    <meta name="theme-color" content="#6366f1" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="apple-touch-icon" href="/icons/icon-192.png" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/bin/templates/pwa/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "type-check": "tsc --noEmit",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "snice": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vite-pwa/assets-generator": "^0.2.4",
+    "@vitest/coverage-v8": "^1.0.4",
+    "@vitest/ui": "^1.0.4",
+    "happy-dom": "^12.10.3",
+    "terser": "^5.24.0",
+    "typescript": "^5.3.3",
+    "unplugin-swc": "^1.5.7",
+    "vite": "^5.0.10",
+    "vite-plugin-pwa": "^0.17.4",
+    "vitest": "^1.0.4",
+    "workbox-window": "^7.0.0"
+  }
+}

package/bin/templates/pwa/public/icons/.gitkeep

@@ -0,0 +1,6 @@
+# Icons directory
+# Replace these with your actual app icons:
+# - icon-192.png (192x192)
+# - icon-512.png (512x512)
+
+# For now, vite-plugin-pwa will generate placeholder icons during build

package/bin/templates/pwa/src/daemons/notifications.ts

@@ -0,0 +1,148 @@
+import type { Notification } from '../types/notifications';
+
+type NotificationHandler = (notification: Notification) => void;
+
+export class NotificationsDaemon {
+  private ws: WebSocket | null = null;
+  private handlers: Set<NotificationHandler> = new Set();
+  private reconnectInterval: number = 5000;
+  private reconnectTimer: number | null = null;
+  private mockInterval: number | null = null;
+  private url: string;
+  private isStarted: boolean = false;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  start(): void {
+    if (this.isStarted) return;
+    this.isStarted = true;
+
+    // For demo purposes, use mock notifications instead of real WebSocket
+    // In production, uncomment the connect() line and remove startMockNotifications()
+    // this.connect();
+    this.startMockNotifications();
+  }
+
+  stop(): void {
+    if (!this.isStarted) return;
+    this.isStarted = false;
+
+    this.stopMockNotifications();
+
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  dispose(): void {
+    this.stop();
+    this.handlers.clear();
+  }
+
+  subscribe(handler: NotificationHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private connect(): void {
+    try {
+      this.ws = new WebSocket(this.url);
+
+      this.ws.onopen = () => {
+        console.log('WebSocket connected');
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const notification: Notification = JSON.parse(event.data);
+          this.notify(notification);
+        } catch (err) {
+          console.error('Failed to parse notification:', err);
+        }
+      };
+
+      this.ws.onerror = (error) => {
+        console.error('WebSocket error:', error);
+      };
+
+      this.ws.onclose = () => {
+        console.log('WebSocket disconnected');
+        if (this.isStarted) {
+          this.scheduleReconnect();
+        }
+      };
+    } catch (err) {
+      console.error('Failed to create WebSocket:', err);
+      if (this.isStarted) {
+        this.scheduleReconnect();
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer !== null) return;
+
+    this.reconnectTimer = window.setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, this.reconnectInterval);
+  }
+
+  private notify(notification: Notification): void {
+    this.handlers.forEach(handler => {
+      try {
+        handler(notification);
+      } catch (err) {
+        console.error('Notification handler error:', err);
+      }
+    });
+  }
+
+  // Mock notifications for demo
+  private startMockNotifications(): void {
+    const messages = [
+      { title: 'Welcome!', message: 'Thanks for checking out the PWA template', type: 'info' as const },
+      { title: 'New Feature', message: 'Check out the notifications page', type: 'success' as const },
+      { title: 'System Update', message: 'A new version is available', type: 'info' as const },
+      { title: 'Reminder', message: 'Don\'t forget to star the repo!', type: 'warning' as const }
+    ];
+
+    let index = 0;
+    this.mockInterval = window.setInterval(() => {
+      const notification: Notification = {
+        id: `mock-${Date.now()}`,
+        ...messages[index % messages.length],
+        timestamp: new Date().toISOString()
+      };
+      this.notify(notification);
+      index++;
+    }, 10000); // Send notification every 10 seconds
+  }
+
+  private stopMockNotifications(): void {
+    if (this.mockInterval !== null) {
+      clearInterval(this.mockInterval);
+      this.mockInterval = null;
+    }
+  }
+}
+
+// Singleton instance
+let instance: NotificationsDaemon | null = null;
+
+export function getNotificationsDaemon(): NotificationsDaemon {
+  if (!instance) {
+    // In production, use actual WebSocket URL from env
+    const wsUrl = import.meta.env.VITE_WS_URL || 'ws://localhost:8080';
+    instance = new NotificationsDaemon(wsUrl);
+  }
+  return instance;
+}

package/bin/templates/pwa/src/fetcher.ts

@@ -0,0 +1,15 @@
+import { ContextAwareFetcher } from 'snice';
+import { authMiddleware } from './middleware/auth';
+import { errorMiddleware } from './middleware/error';
+import { createRetryMiddleware } from './middleware/retry';
+
+const fetcher = new ContextAwareFetcher();
+
+// Add request middleware (runs before fetch)
+fetcher.use('request', authMiddleware);
+fetcher.use('request', createRetryMiddleware());
+
+// Add response middleware (runs after fetch)
+fetcher.use('response', errorMiddleware);
+
+export { fetcher };

package/bin/templates/pwa/src/guards/auth.ts

@@ -0,0 +1,12 @@
+import type { AppContext } from 'snice';
+import type { Principal } from '../types/auth';
+
+export function authGuard(appContext: AppContext): boolean {
+  const principal = appContext.principal as Principal | undefined;
+
+  if (!principal?.isAuthenticated) {
+    window.location.href = '#/login';
+    return false;
+  }
+  return true;
+}

package/bin/templates/pwa/src/main.ts

@@ -0,0 +1,42 @@
+import { initialize } from './router';
+import './styles/global.css';
+
+// Import snice layout and components
+import 'snice/components/layout/snice-layout';
+import 'snice/components/button/snice-button';
+import 'snice/components/card/snice-card';
+import 'snice/components/input/snice-input';
+import 'snice/components/alert/snice-alert';
+import 'snice/components/avatar/snice-avatar';
+import 'snice/components/empty-state/snice-empty-state';
+import 'snice/components/spinner/snice-spinner';
+
+// Import pages
+import './pages/login';
+import './pages/dashboard';
+import './pages/profile';
+import './pages/notifications';
+
+// Import and start daemons
+import { getNotificationsDaemon } from './daemons/notifications';
+
+// Start notifications daemon
+const notificationsDaemon = getNotificationsDaemon();
+notificationsDaemon.start();
+
+// Initialize router
+initialize();
+
+// Register service worker (PWA)
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', () => {
+    navigator.serviceWorker.register('/sw.js').then(
+      (registration) => {
+        console.log('Service Worker registered:', registration);
+      },
+      (error) => {
+        console.error('Service Worker registration failed:', error);
+      }
+    );
+  });
+}

package/bin/templates/pwa/src/middleware/auth.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'snice';
+import { getToken } from '../services/storage';
+
+export async function authMiddleware(
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+): Promise<Response> {
+  const token = getToken();
+
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+
+  return next();
+}

package/bin/templates/pwa/src/middleware/error.ts

@@ -0,0 +1,36 @@
+import type { Context } from 'snice';
+import type { Principal } from '../types/auth';
+import { clearToken } from '../services/storage';
+
+export async function errorMiddleware(
+  this: Context,
+  response: Response,
+  next: () => Promise<Response>
+): Promise<Response> {
+  // Handle 401 unauthorized - token expired or invalid
+  if (response.status === 401) {
+    clearToken();
+
+    // Update context to reflect logged out state
+    if (this.application.principal) {
+      const principal = this.application.principal as Principal;
+      principal.user = null;
+      principal.isAuthenticated = false;
+    }
+
+    window.location.href = '#/login';
+    throw new Error('Unauthorized - redirecting to login');
+  }
+
+  // Handle other errors
+  if (!response.ok) {
+    const contentType = response.headers.get('content-type');
+    if (contentType && contentType.includes('application/json')) {
+      const error = await response.json();
+      throw new Error(error.message || `Request failed with status ${response.status}`);
+    }
+    throw new Error(`Request failed with status ${response.status}`);
+  }
+
+  return next();
+}

package/bin/templates/pwa/src/middleware/retry.ts

@@ -0,0 +1,31 @@
+import type { Context } from 'snice';
+
+export function createRetryMiddleware(retries = 3, delay = 1000) {
+  return async function retryMiddleware(
+    this: Context,
+    _request: Request,
+    next: () => Promise<Response>
+  ): Promise<Response> {
+    let lastError: Error;
+
+    for (let i = 0; i < retries; i++) {
+      try {
+        return await next();
+      } catch (err) {
+        lastError = err as Error;
+
+        // Don't retry on certain errors
+        if (err instanceof Error && err.message.includes('Unauthorized')) {
+          throw err;
+        }
+
+        // Wait before retrying (exponential backoff)
+        if (i < retries - 1) {
+          await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
+        }
+      }
+    }
+
+    throw lastError!;
+  };
+}