snice 3.7.0 → 3.9.0

package/docs/components/qr-reader.md

@@ -0,0 +1,327 @@
+# QR Reader Component
+
+`<snice-qr-reader>` provides QR code scanning functionality using device cameras with WebAssembly-based QR detection.
+
+## Features
+
+- **Camera Access**: Use front or back camera for QR code scanning
+- **Real-time Detection**: Continuous scanning with ZXing WASM decoder
+- **Auto-start**: Optional automatic camera activation on mount
+- **Event-based**: Emits events for successful scans, errors, and camera status
+- **Responsive**: Adapts to container size with proper aspect ratio
+- **Configurable Speed**: Adjust scan speed for performance vs detection speed trade-off
+
+## Basic Usage
+
+```html
+<snice-qr-reader auto-start></snice-qr-reader>
+
+<script>
+  const reader = document.querySelector('snice-qr-reader');
+
+  reader.addEventListener('@snice/qr-scan', (event) => {
+    console.log('QR Code:', event.detail.data);
+  });
+</script>
+```
+
+## Properties
+
+### `auto-start`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Automatically start scanning when component is mounted
+
+```html
+<snice-qr-reader auto-start></snice-qr-reader>
+```
+
+### `camera`
+- **Type**: `'front' | 'back'`
+- **Default**: `'back'`
+- **Description**: Which camera to use for scanning
+
+```html
+<snice-qr-reader camera="front"></snice-qr-reader>
+```
+
+### `pick-first`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Scan continuously at maximum speed until first successful QR code detection, then stop and shut down camera. Ignores `scan-speed` setting.
+
+```html
+<!-- Scan at max speed until first QR hit, then stop -->
+<snice-qr-reader pick-first></snice-qr-reader>
+```
+
+### `manual-snap`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Photo snapshot mode. Opens camera as a live viewfinder, and you manually trigger snapshot attempts by clicking the snap button.
+
+```html
+<!-- Manual photo snapshot mode -->
+<snice-qr-reader manual-snap></snice-qr-reader>
+```
+
+### `scan-speed`
+- **Type**: `number`
+- **Default**: `3`
+- **Description**: Scan speed from 1-10. Higher values = faster QR detection but more CPU usage. Lower values = slower detection but better performance. **Note**: Ignored when `pick-first` is enabled (always scans at max speed).
+
+```html
+<!-- Slow scan (better performance) -->
+<snice-qr-reader scan-speed="1"></snice-qr-reader>
+
+<!-- Medium scan (balanced, default) -->
+<snice-qr-reader scan-speed="3"></snice-qr-reader>
+
+<!-- Fast scan (faster detection) -->
+<snice-qr-reader scan-speed="10"></snice-qr-reader>
+```
+
+## Methods
+
+### `start()`
+Start the camera and begin scanning for QR codes (or open camera for manual-snap mode).
+
+```javascript
+const reader = document.querySelector('snice-qr-reader');
+reader.start();
+```
+
+### `stop()`
+Stop scanning and release the camera.
+
+```javascript
+reader.stop();
+```
+
+### `snap()`
+Take a snapshot and check for QR codes (manual-snap mode only).
+
+```javascript
+const result = await reader.snap(); // Returns QR data or null
+```
+
+## Events
+
+### `@snice/qr-scan`
+Fired when a QR code is successfully detected.
+
+**Detail Properties:**
+- `data` (string): The decoded QR code content
+- `timestamp` (number): Unix timestamp of the scan
+- `reader` (SniceQRReader): Reference to the component
+
+```javascript
+reader.addEventListener('@snice/qr-scan', (event) => {
+  console.log('Data:', event.detail.data);
+  console.log('Time:', new Date(event.detail.timestamp));
+});
+```
+
+### `@snice/qr-error`
+Fired when an error occurs during scanning.
+
+**Detail Properties:**
+- `error` (any): Error object or message
+- `reader` (SniceQRReader): Reference to the component
+
+```javascript
+reader.addEventListener('@snice/qr-error', (event) => {
+  console.error('Error:', event.detail.error);
+});
+```
+
+### `@snice/camera-ready`
+Fired when the camera has been successfully initialized and is ready to scan.
+
+**Detail Properties:**
+- `reader` (SniceQRReader): Reference to the component
+
+```javascript
+reader.addEventListener('@snice/camera-ready', (event) => {
+  console.log('Camera is ready');
+});
+```
+
+### `@snice/camera-error`
+Fired when camera initialization fails.
+
+**Detail Properties:**
+- `error` (any): Error object or message
+- `reader` (SniceQRReader): Reference to the component
+
+```javascript
+reader.addEventListener('@snice/camera-error', (event) => {
+  console.error('Camera error:', event.detail.error);
+});
+```
+
+## Examples
+
+### Manual Control
+
+```html
+<snice-qr-reader id="reader"></snice-qr-reader>
+<button onclick="startReading()">Start</button>
+<button onclick="stopReading()">Stop</button>
+<div id="result"></div>
+
+<script>
+  const reader = document.getElementById('reader');
+  const result = document.getElementById('result');
+
+  function startReading() {
+    reader.start();
+  }
+
+  function stopReading() {
+    reader.stop();
+  }
+
+  reader.addEventListener('@snice/qr-scan', (e) => {
+    result.textContent = `Scanned: ${e.detail.data}`;
+  });
+</script>
+```
+
+### Pick-First (One-Shot)
+
+```html
+<snice-qr-reader id="scanner" pick-first></snice-qr-reader>
+
+<script>
+  const scanner = document.getElementById('scanner');
+
+  scanner.addEventListener('@snice/qr-scan', (e) => {
+    // Process the scan
+    processQRCode(e.detail.data);
+
+    // Scanner automatically stops and shuts down camera
+  });
+
+  // Start scanning at max speed
+  scanner.start();
+</script>
+```
+
+### Manual Snapshot
+
+```html
+<snice-qr-reader id="snapReader" manual-snap></snice-qr-reader>
+<button id="snapBtn">Take Photo</button>
+
+<script>
+  const reader = document.getElementById('snapReader');
+  const btn = document.getElementById('snapBtn');
+
+  // Open camera
+  reader.start();
+
+  // Manually trigger snapshot
+  btn.addEventListener('click', async () => {
+    const result = await reader.snap();
+    if (result) {
+      console.log('QR Code:', result);
+    } else {
+      console.log('No QR code found');
+    }
+  });
+</script>
+```
+
+### Front Camera
+
+```html
+<snice-qr-reader camera="front" auto-start></snice-qr-reader>
+
+<script>
+  // Useful for self-scanning scenarios
+  document.querySelector('snice-qr-reader')
+    .addEventListener('@snice/qr-scan', (e) => {
+      validateTicket(e.detail.data);
+    });
+</script>
+```
+
+### Error Handling
+
+```html
+<snice-qr-reader id="reader" auto-start></snice-qr-reader>
+<div id="status"></div>
+
+<script>
+  const reader = document.getElementById('reader');
+  const status = document.getElementById('status');
+
+  reader.addEventListener('@snice/qr-scan', (e) => {
+    status.textContent = `✓ Scanned: ${e.detail.data}`;
+    status.style.color = 'green';
+  });
+
+  reader.addEventListener('@snice/qr-error', (e) => {
+    status.textContent = `✗ Error: ${e.detail.error}`;
+    status.style.color = 'red';
+
+    // Retry after error
+    setTimeout(() => reader.start(), 2000);
+  });
+</script>
+```
+
+## Styling
+
+The component uses CSS custom properties for theming:
+
+```css
+snice-qr-reader {
+  --qr-reader-border: var(--snice-color-border, #e5e7eb);
+  --qr-reader-bg: var(--snice-color-bg, #ffffff);
+  --qr-reader-text: var(--snice-color-text, #1f2937);
+
+  /* Size */
+  width: 100%;
+  max-width: 600px;
+}
+```
+
+## Browser Support
+
+- Requires `getUserMedia` API support
+- Uses WebAssembly for QR detection (ZXing)
+- Works on modern browsers (Chrome, Firefox, Safari, Edge)
+- Mobile browser camera access requires HTTPS
+
+## Implementation Details
+
+### QR Detection
+Uses ZXing-C++ WebAssembly build for fast, accurate QR code detection:
+- **License**: Apache 2.0 (ZXing-C++) + MIT (zxing-wasm)
+- **Format Support**: QR Code, Micro QR Code
+- **Performance**: ~60fps scanning on modern devices
+
+### Camera Management
+- Requests user permission for camera access
+- Automatically releases camera when component is destroyed
+- Handles camera errors gracefully with fallback messages
+
+### Privacy
+- Camera feed stays in the browser (no uploads)
+- QR data is only emitted via events
+- Camera is released when scanning stops
+
+## Related Components
+
+- `<snice-qr-code>` - Generate QR codes
+- `<snice-camera>` - General camera capture component
+
+## License
+
+QR detection powered by:
+- **ZXing-C++**: Apache License 2.0
+- **zxing-wasm**: MIT License
+
+See `components/qr-reader/ZXING-LICENSE` for full license text.

package/docs/routing.md

@@ -207,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
 }
 ```
@@ -223,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
@@ -250,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();
   }
@@ -1066,7 +1067,7 @@ class DashboardPage extends HTMLElement {
   private appContext?: AppContext;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.appContext = ctx.application;
     this.requestRender();
   }
@@ -1093,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.7.0",
+  "version": "3.9.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",

package/bin/templates/pwa/public/manifest.json

@@ -1,24 +0,0 @@
-{
-  "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/src/utils/fetch.ts

@@ -1,39 +0,0 @@
-export type Middleware = (
-  url: string,
-  options: RequestInit,
-  next: () => Promise<Response>
-) => Promise<Response>;
-
-export type FetchConfig = {
-  baseURL?: string;
-  middleware?: Middleware[];
-  headers?: Record<string, string>;
-};
-
-export function createFetch(config: FetchConfig = {}) {
-  return async (url: string, options: RequestInit = {}): Promise<Response> => {
-    const fullURL = config.baseURL ? `${config.baseURL}${url}` : url;
-
-    const execute = async (): Promise<Response> => {
-      return fetch(fullURL, {
-        ...options,
-        headers: {
-          ...config.headers,
-          ...options.headers,
-        },
-      });
-    };
-
-    // Chain middleware (reverse order so first middleware wraps execution)
-    let chain = execute;
-    if (config.middleware) {
-      for (let i = config.middleware.length - 1; i >= 0; i--) {
-        const middleware = config.middleware[i];
-        const next = chain;
-        chain = () => middleware(fullURL, options, next);
-      }
-    }
-
-    return chain();
-  };
-}

package/bin/templates/social/README.md

@@ -1,42 +0,0 @@
-# Social Media Sample App
-
-A sample social media application built with Snice showcasing various components.
-
-## Features
-
-This template demonstrates:
-
-### Components Used
-- **snice-card** - Post containers and content cards
-- **snice-avatar** - User profile pictures
-- **snice-button** - Action buttons throughout
-- **snice-badge** - Status indicators and labels
-- **snice-input** - Form inputs in settings
-- **snice-textarea** - Multi-line text input
-- **snice-switch** - Toggle settings
-- **snice-tabs** - Tabbed content on profile
-- **snice-stat** - Statistics display
-- **snice-layout-sidebar** - Sidebar navigation layout
-
-### Pages
-- **Feed** (`/`) - Social feed with posts showing cards, avatars, and badges
-- **Profile** (`/profile`) - User profile with stats and tabs
-- **Messages** (`/messages`) - Message list with avatars
-- **Settings** (`/settings`) - Settings page with forms and switches
-
-## Getting Started
-
-```bash
-npm install
-npm run dev
-```
-
-## Build for Production
-
-```bash
-npm run build
-```
-
-## Customize
-
-Feel free to modify the pages, add new components, or change the styling to fit your needs.

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

@@ -1,14 +0,0 @@
-declare module '*.css' {
-  const content: string;
-  export default content;
-}
-
-declare module '*.css?inline' {
-  const content: string;
-  export default content;
-}
-
-declare module '*.html' {
-  const content: string;
-  export default content;
-}

package/bin/templates/social/index.html

@@ -1,13 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{{projectName}}</title>
-  <link rel="icon" type="image/svg+xml" href="/vite.svg">
-</head>
-<body>
-  <div id="app"></div>
-  <script type="module" src="/src/main.ts"></script>
-</body>
-</html>

package/bin/templates/social/package.json

@@ -1,21 +0,0 @@
-{
-  "name": "{{projectName}}",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "type-check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "snice": "^3.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "terser": "^5.24.0",
-    "typescript": "^5.3.3",
-    "unplugin-swc": "^1.5.7",
-    "vite": "^5.0.10"
-  }
-}

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

@@ -1 +0,0 @@
-<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/social/src/main.ts

@@ -1,33 +0,0 @@
-import { initialize } from './router';
-import './styles/global.css';
-
-// Import theme
-import 'snice/components/theme/theme.css';
-
-// Import layout
-import 'snice/components/layout/snice-layout-sidebar';
-
-// Import snice components
-import 'snice/components/card/snice-card';
-import 'snice/components/avatar/snice-avatar';
-import 'snice/components/button/snice-button';
-import 'snice/components/badge/snice-badge';
-import 'snice/components/input/snice-input';
-import 'snice/components/textarea/snice-textarea';
-import 'snice/components/switch/snice-switch';
-import 'snice/components/tabs/snice-tabs';
-import 'snice/components/tabs/snice-tab';
-import 'snice/components/tabs/snice-tab-panel';
-import 'snice/components/stat/snice-stat';
-import 'snice/components/list/snice-list';
-import 'snice/components/nav/snice-nav';
-
-// Import pages
-import './pages/feed-page';
-import './pages/profile-page';
-import './pages/messages-page';
-import './pages/settings-page';
-import './pages/not-found-page';
-
-// Initialize router
-initialize();