snice 3.8.0 → 3.10.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.7.0
+ * snice v3.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.7.0
+ * snice v3.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.7.0
+ * snice v3.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.7.0
+ * snice v3.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/docs/ai/README.md

@@ -21,6 +21,6 @@ Read these instead of `/docs/*.md` for faster context loading.
 **IMPORTANT:** Do NOT read all component docs. Only read a component's doc when you need to use or reference it.
 
 **Implemented Components:**
-- accordion, accordion-item, alert, avatar, badge, banner, breadcrumbs, button, card, checkbox, chip, color-display, color-picker, date-picker, divider, drawer, empty-state, file-upload, image, input, login, modal, nav, progress, radio, select, skeleton, slider, spinner, switch, table, tabs, tab, textarea, timeline, tooltip
+- accordion, accordion-item, alert, avatar, badge, banner, breadcrumbs, button, card, checkbox, chip, color-display, color-picker, date-picker, divider, drawer, empty-state, file-gallery, file-upload, image, input, login, modal, nav, progress, qr-code, qr-reader, radio, select, skeleton, slider, spinner, switch, table, tabs, tab, textarea, timeline, tooltip
 
 **To use a component:** Read `docs/ai/components/{component-name}.md` only when needed.

package/docs/ai/api.md

@@ -208,6 +208,11 @@ attr="${val}" // Attribute
 ?attr="${bool}" // Boolean attribute
 @event="${handler}" // Event listener
 @event:modifier="${handler}" // With keyboard modifier
+
+// IMPORTANT: Event names starting with @
+// Use @@ to escape the @ in event names like @snice/qr-scan
+@@snice/qr-scan="${handler}" // Correct - first @ is syntax, second @ is part of name
+@snice/qr-scan="${handler}" // Wrong - treated as @snice event
 ```
 
 ## Types

package/docs/ai/components/file-gallery.md

@@ -0,0 +1,206 @@
+# snice-file-gallery
+
+File upload gallery with drag-and-drop, preview, pausable/resumable uploads.
+
+## Properties
+
+```typescript
+accept: string = '';
+multiple: boolean = true;
+disabled: boolean = false;
+maxSize: number = -1; // bytes, -1 = no limit
+maxFiles: number = -1; // -1 = no limit
+view: 'grid'|'list' = 'grid';
+showProgress: boolean = true;
+allowPause: boolean = true;
+allowDelete: boolean = true;
+autoUpload: boolean = true;
+showAddButton: boolean = false; // show add button tile instead of drop zone
+hideAddButton: boolean = false; // hide default add button (show only custom actions)
+files: GalleryFile[]; // read-only
+```
+
+## Getters
+
+- `files: GalleryFile[]` - Get all files
+- `customActions: CustomAction[]` - Get all custom actions
+- `getFile(fileId): GalleryFile | undefined` - Get specific file
+- `getCustomAction(actionId): CustomAction | undefined` - Get specific action
+- `isPending(fileId): boolean` - Check if pending
+- `isUploading(fileId): boolean` - Check if uploading
+- `isPaused(fileId): boolean` - Check if paused
+- `isCompleted(fileId): boolean` - Check if completed
+- `hasError(fileId): boolean` - Check if has error
+- `canAddFiles(): boolean` - Check if can add more files
+
+## File Management
+
+- `addFiles(files: FileList | File[])` - Add files to gallery
+- `addFileWithPreview(file: File, previewDataUrl: string)` - Add file with preview
+- `removeFile(fileId: string)` - Remove file
+- `clear()` - Remove all files
+- `clearCompleted()` - Remove completed files
+- `clearErrors()` - Remove files with errors
+
+## Upload Control
+
+- `pauseUpload(fileId: string)` - Pause upload
+- `resumeUpload(fileId: string)` - Resume upload
+- `retryUpload(fileId: string)` - Retry failed upload
+- `cancelUpload(fileId: string)` - Cancel and remove upload
+- `pauseAll()` - Pause all uploading files
+- `resumeAll()` - Resume all paused files
+- `retryAll()` - Retry all errored files
+- `cancelAll()` - Cancel all active uploads
+
+## Custom Actions
+
+- `addCustomAction(icon: string, text: string): string` - Add custom action, returns actionId
+- `removeCustomAction(actionId: string)` - Remove action
+- `clearCustomActions()` - Remove all actions
+
+## Utility
+
+- `openFilePicker()` - Open file picker dialog
+- `setFileBadge(fileId: string, badge: string, position?: 'top-left'|'top-right'|'bottom-left'|'bottom-right')` - Add badge overlay to file preview (supports HTML)
+- `removeFileBadge(fileId: string)` - Remove badge from file
+
+## Events
+
+- `files-change` - {files: GalleryFile[]}
+- `upload-progress` - {file: GalleryFile, progress: number}
+- `upload-complete` - {file: GalleryFile, url?: string}
+- `upload-error` - {file: GalleryFile, error: string}
+- `custom-action-click` - {actionId: string}
+- `error` - {message: string}
+
+## Types
+
+```typescript
+interface GalleryFile {
+  id: string;
+  file: File;
+  preview?: string;
+  uploadProgress: number;
+  uploadStatus: 'pending'|'uploading'|'paused'|'completed'|'error';
+  error?: string;
+  badge?: string; // HTML content for badge overlay
+  badgePosition?: 'top-left'|'top-right'|'bottom-left'|'bottom-right';
+}
+
+interface UploadRequest {
+  file: File;
+  fileId: string;
+  onProgress?: (progress: number) => void;
+  signal?: AbortSignal;
+}
+
+interface UploadResponse {
+  success: boolean;
+  fileId: string;
+  url?: string;
+  error?: string;
+}
+```
+
+## Upload Handler
+
+Uses `@request/@respond` pattern. Handler required:
+
+```typescript
+import { respond } from 'snice';
+
+class UploadController {
+  @respond('file-gallery-upload')
+  async handleUpload(request: UploadRequest): Promise<UploadResponse> {
+    const { file, fileId, onProgress, signal } = request;
+
+    // Implement upload logic
+    // Use onProgress(0-1) for progress tracking
+    // Check signal.aborted for cancellation
+
+    return {
+      success: true,
+      fileId,
+      url: 'https://example.com/file.jpg'
+    };
+  }
+}
+
+const controller = new UploadController();
+controller.attach?.(document.body);
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-file-gallery></snice-file-gallery>
+
+<!-- Images only -->
+<snice-file-gallery accept="image/*"></snice-file-gallery>
+
+<!-- Manual upload -->
+<snice-file-gallery auto-upload="false"></snice-file-gallery>
+
+<!-- Limits -->
+<snice-file-gallery max-files="3" max-size="2097152"></snice-file-gallery>
+
+<!-- List view -->
+<snice-file-gallery view="list"></snice-file-gallery>
+
+<!-- Custom options -->
+<snice-file-gallery
+  accept=".pdf,.doc,.docx"
+  allow-pause="false"
+></snice-file-gallery>
+
+<!-- Add button mode -->
+<snice-file-gallery
+  show-add-button="true"
+  max-files="6"
+></snice-file-gallery>
+
+<!-- Custom actions -->
+<snice-file-gallery id="gallery"></snice-file-gallery>
+<script>
+const gallery = document.querySelector('#gallery');
+
+// Add custom action
+const icon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">...</svg>';
+const actionId = gallery.addCustomAction(icon, 'Camera');
+
+// Handle custom action
+gallery.addEventListener('@snice/custom-action-click', (e) => {
+  if (e.detail.actionId === actionId) {
+    // Handle camera action
+    const file = capturePhoto(); // your implementation
+    gallery.addFileWithPreview(file, previewUrl);
+  }
+});
+
+// Other events
+gallery.addEventListener('@snice/files-change', (e) => {
+  console.log('Files:', e.detail.files);
+});
+gallery.addEventListener('@snice/upload-complete', (e) => {
+  console.log('Complete:', e.detail.url);
+});
+
+// Add custom badge (e.g., user avatar)
+const avatarHTML = `<div style="width:40px;height:40px;border-radius:50%;background:#3b82f6;color:white;display:flex;align-items:center;justify-content:center;font-weight:bold;border:2px solid white;box-shadow:0 2px 4px rgba(0,0,0,0.2)">JD</div>`;
+gallery.setFileBadge(fileId, avatarHTML, 'top-right');
+</script>
+```
+
+## Features
+
+- Drag-and-drop with visual feedback
+- Image preview thumbnails
+- Pausable/resumable uploads via AbortController
+- Real-time progress tracking
+- Grid/list view toggle
+- File validation (size, type)
+- Auto or manual upload modes
+- @request/@respond upload pattern
+- Accessible

package/docs/ai/components/qr-reader.md

@@ -0,0 +1,80 @@
+# snice-qr-reader
+
+QR code scanner using device camera and ZXing WASM decoder.
+
+## API
+
+### Properties
+- `auto-start: boolean = false` - Auto-start scanning on mount
+- `camera: 'front'|'back' = 'back'` - Camera selection
+- `pick-first: boolean = false` - Scan at max speed until first hit, then stop and shutdown
+- `manual-snap: boolean = false` - Photo mode: open camera, manually trigger snapshots
+- `scan-speed: number = 3` - Scan speed 1-10 (higher = faster, more CPU). Ignored when pick-first=true
+
+### Methods
+- `start()` - Start camera/scanning
+- `stop()` - Stop camera/scanning
+- `snap()` - Take snapshot (manual-snap mode)
+
+### Events
+- `@snice/qr-scan` - detail: `{data: string, timestamp: number, reader: SniceQRReader}`
+- `@snice/qr-error` - detail: `{error: any, reader: SniceQRReader}`
+- `@snice/camera-ready` - detail: `{reader: SniceQRReader}`
+- `@snice/camera-error` - detail: `{error: any, reader: SniceQRReader}`
+
+## Usage
+
+```html
+<snice-qr-reader auto-start></snice-qr-reader>
+<script>
+  reader.addEventListener('@snice/qr-scan', e => console.log(e.detail.data));
+</script>
+```
+
+## Implementation
+
+### File Structure
+- `snice-qr-reader.ts` - Main component (camera, scanning loop)
+- `qr-worker.ts` - Web Worker for QR detection
+- `qr-decoder.ts` - ZXing WASM wrapper (legacy)
+- `zxing-reader.mjs` - ZXing ES module
+- `zxing_reader.wasm` - WASM binary
+- `ZXING-LICENSE` - Apache 2.0 + MIT
+
+### QR Detection
+Uses ZXing WASM decoder exclusively for universal browser support.
+
+### Camera Loop
+```ts
+private scanFrame() {
+  ctx.drawImage(video, 0, 0, width, height);
+  const imageData = ctx.getImageData(0, 0, width, height);
+  worker.postMessage({ type: 'decode', imageData });
+  // Worker responds with result in background thread
+  requestAnimationFrame(() => this.scanFrame());
+}
+```
+
+### Lifecycle
+- `@ready` - Init worker, auto-start if enabled
+- `@dispose` - Stop scan, release camera, terminate worker
+- Scan loop uses requestAnimationFrame
+- QR detection runs in Web Worker (non-blocking)
+- Only emits event if QR data changed
+
+### CSS Tokens
+```css
+--qr-reader-border: var(--snice-color-border, #e5e7eb)
+--qr-reader-bg: var(--snice-color-bg, #fff)
+--qr-reader-text: var(--snice-color-text, #1f2937)
+```
+
+## License
+- ZXing-C++: Apache 2.0
+- zxing-wasm: MIT
+- See ZXING-LICENSE file
+
+## Browser Requirements
+- getUserMedia API
+- WebAssembly support
+- HTTPS for mobile