snice 3.5.0 → 3.7.0

package/bin/snice.js

@@ -47,6 +47,7 @@ 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
@@ -90,7 +91,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, social, 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
+- **Components** - Pure presentation, no business logic
+- **Controllers** - Attach to elements, add behavior
+- **Utils** - Pure helper functions
+- **Services** - Stateless business logic, API calls
+- **Daemons** - Lifecycle-managed (WebSocket, P2P, intervals)
+- **Middleware** - Composable functions (auth, logging, retry)
 
 ## 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<T>, not T.** Check `ctx.application.property`, not `ctx.property`. Guards: `(ctx: Context<AppContext>) => 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,173 @@
+# {{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
+
+### Middleware-Based Fetch
+
+Composable middleware for all API calls:
+
+```typescript
+import { createFetch } from './utils/fetch';
+import { authMiddleware } from './middleware/auth';
+import { errorMiddleware } from './middleware/error';
+import { retryMiddleware } from './middleware/retry';
+
+export const api = createFetch({
+  baseURL: import.meta.env.VITE_API_URL,
+  middleware: [authMiddleware, errorMiddleware, retryMiddleware()],
+  headers: { 'Content-Type': 'application/json' }
+});
+
+// Usage
+const data = await api('/users').then(r => r.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
+@context()
+handleContext(ctx: Context<AppContext>) {
+  this.user = ctx.application.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,17 @@
+<!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="manifest" href="/manifest.json" />
+    <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,25 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "type-check": "tsc --noEmit",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "snice": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vite-pwa/assets-generator": "^0.2.4",
+    "terser": "^5.24.0",
+    "typescript": "^5.3.3",
+    "unplugin-swc": "^1.5.7",
+    "vite": "^5.0.10",
+    "vite-plugin-pwa": "^0.17.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/public/manifest.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{projectName}}",
+  "short_name": "{{projectName}}",
+  "description": "PWA built with Snice",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#6366f1",
+  "orientation": "portrait-primary",
+  "icons": [
+    {
+      "src": "/icons/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "/icons/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ]
+}

package/bin/templates/pwa/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

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/guards/auth.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'snice';
+import type { AppContext } from '../types/auth';
+
+export function authGuard(ctx: Context<AppContext>): boolean {
+  if (!ctx.application.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,15 @@
+import type { Middleware } from '../utils/fetch';
+import { getToken } from '../services/storage';
+
+export async function authMiddleware(url: string, options: RequestInit, next: () => Promise<Response>): Promise<Response> {
+  const token = getToken();
+
+  if (token) {
+    options.headers = {
+      ...options.headers,
+      'Authorization': `Bearer ${token}`,
+    };
+  }
+
+  return next();
+}

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

@@ -0,0 +1,25 @@
+import type { Middleware } from '../utils/fetch';
+import { clearToken } from '../services/storage';
+
+export async function errorMiddleware(url: string, options: RequestInit, next: () => Promise<Response>): Promise<Response> {
+  const response = await next();
+
+  // Handle 401 unauthorized - token expired or invalid
+  if (response.status === 401) {
+    clearToken();
+    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 response;
+}

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

@@ -0,0 +1,27 @@
+import type { Middleware } from '../utils/fetch';
+
+export function retryMiddleware(retries = 3, delay = 1000): Middleware {
+  return async (url, options, next) => {
+    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!;
+  };
+}