snice 4.27.0 → 4.29.0

package/docs/components/file-gallery.md

@@ -1,6 +1,6 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/file-gallery.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/file-gallery.md -->
 
-# File Gallery Component
+# File Gallery
 
 The `<snice-file-gallery>` component provides a file upload gallery with drag-and-drop support, image previews, pausable/resumable uploads, and progress tracking.
 
@@ -10,9 +10,7 @@ The `<snice-file-gallery>` component provides a file upload gallery with drag-an
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
-- [Upload Handler](#upload-handler)
 - [Examples](#examples)
-- [Features](#features)
 
 ## Properties
 
@@ -21,363 +19,102 @@ The `<snice-file-gallery>` component provides a file upload gallery with drag-an
 | `accept` | `string` | `''` | Allowed file types (same as input accept) |
 | `multiple` | `boolean` | `true` | Allow multiple file selection |
 | `disabled` | `boolean` | `false` | Whether gallery is disabled |
-| `maxSize` | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
-| `maxFiles` | `number` | `-1` | Maximum number of files (-1 = no limit) |
+| `maxSize` (attr: `max-size`) | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
+| `maxFiles` (attr: `max-files`) | `number` | `-1` | Maximum number of files (-1 = no limit) |
 | `view` | `'grid' \| 'list'` | `'grid'` | Display layout mode |
-| `showProgress` | `boolean` | `true` | Show upload progress |
-| `allowPause` | `boolean` | `true` | Allow pause/resume of uploads |
-| `allowDelete` | `boolean` | `true` | Allow file deletion |
-| `autoUpload` | `boolean` | `true` | Start upload immediately on file add |
-| `showDropzone` | `boolean` | `true` | Show drop zone for drag & drop uploads |
-| `showAddButton` | `boolean` | `false` | Show add button tile in gallery |
+| `showProgress` (attr: `show-progress`) | `boolean` | `true` | Show upload progress |
+| `allowPause` (attr: `allow-pause`) | `boolean` | `true` | Allow pause/resume of uploads |
+| `allowDelete` (attr: `allow-delete`) | `boolean` | `true` | Allow file deletion |
+| `autoUpload` (attr: `auto-upload`) | `boolean` | `true` | Start upload immediately on file add |
+| `showDropzone` (attr: `show-dropzone`) | `boolean` | `true` | Show drop zone for drag & drop uploads |
+| `showAddButton` (attr: `show-add-button`) | `boolean` | `false` | Show add button tile in gallery |
 | `showHeader` (attr: `show-header`) | `boolean` | `true` | Show gallery header section |
-| `files` | `GalleryFile[]` | `[]` | Current files (read-only) |
+| `files` | `GalleryFile[]` | `[]` | Current files (read-only getter) |
 
 ## Methods
 
 ### Getters
 
-#### `files: GalleryFile[]`
-Get all files in the gallery (read-only).
-
-```typescript
-const allFiles = gallery.files;
-```
-
-#### `customActions: CustomAction[]`
-Get all custom action buttons (read-only).
-
-```typescript
-const actions = gallery.customActions;
-```
-
-#### `getFile(fileId: string): GalleryFile | undefined`
-Get a specific file by ID.
-
-```typescript
-const file = gallery.getFile('file-id-123');
-```
-
-#### `getCustomAction(actionId: string): CustomAction | undefined`
-Get a specific custom action by ID.
-
-```typescript
-const action = gallery.getCustomAction('action-id-456');
-```
-
-#### `isPending(fileId: string): boolean`
-Check if a file upload is pending.
-
-```typescript
-if (gallery.isPending('file-id-123')) {
-  console.log('File is waiting to upload');
-}
-```
-
-#### `isUploading(fileId: string): boolean`
-Check if a file is currently uploading.
-
-#### `isPaused(fileId: string): boolean`
-Check if a file upload is paused.
-
-#### `isCompleted(fileId: string): boolean`
-Check if a file upload is completed.
-
-#### `hasError(fileId: string): boolean`
-Check if a file upload has an error.
-
-#### `canAddFiles(): boolean`
-Check if more files can be added (respects maxFiles limit).
-
-```typescript
-if (gallery.canAddFiles()) {
-  gallery.openFilePicker();
-}
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `files` | `GalleryFile[]` | Get all files (read-only) |
+| `customActions` | `CustomAction[]` | Get all custom action buttons (read-only) |
+| `getFile(fileId)` | `GalleryFile \| undefined` | Get a specific file by ID |
+| `getCustomAction(actionId)` | `CustomAction \| undefined` | Get a specific custom action by ID |
+| `isPending(fileId)` | `boolean` | Check if a file upload is pending |
+| `isUploading(fileId)` | `boolean` | Check if a file is currently uploading |
+| `isPaused(fileId)` | `boolean` | Check if a file upload is paused |
+| `isCompleted(fileId)` | `boolean` | Check if a file upload is completed |
+| `hasError(fileId)` | `boolean` | Check if a file upload has an error |
+| `canAddFiles()` | `boolean` | Check if more files can be added (respects maxFiles) |
 
 ### File Management
 
-#### `addFiles(files: FileList | File[]): void`
-Add files to the gallery.
-
-```typescript
-gallery.addFiles(fileInput.files);
-```
-
-#### `addFileWithPreview(file: File, previewDataUrl: string): void`
-Add a file with a custom preview (e.g., from camera/canvas).
-
-```typescript
-const canvas = document.createElement('canvas');
-// ... draw on canvas
-canvas.toBlob((blob) => {
-  const file = new File([blob], 'photo.png', { type: 'image/png' });
-  const preview = canvas.toDataURL('image/png');
-  gallery.addFileWithPreview(file, preview);
-});
-```
-
-#### `removeFile(fileId: string): void`
-Remove a file from the gallery.
-
-```typescript
-gallery.removeFile('file-id-123');
-```
-
-#### `clear(): void`
-Remove all files from the gallery.
-
-```typescript
-gallery.clear();
-```
-
-#### `clearCompleted(): void`
-Remove all completed files from the gallery.
-
-```typescript
-gallery.clearCompleted();
-```
-
-#### `clearErrors(): void`
-Remove all files with errors from the gallery.
-
-```typescript
-gallery.clearErrors();
-```
+| Method | Description |
+|--------|-------------|
+| `addFiles(files: FileList \| File[])` | Add files to the gallery |
+| `addFileWithPreview(file: File, previewDataUrl: string)` | Add a file with a custom preview |
+| `removeFile(fileId: string)` | Remove a file from the gallery |
+| `clear()` | Remove all files |
+| `clearCompleted()` | Remove all completed files |
+| `clearErrors()` | Remove all files with errors |
 
 ### Upload Control
 
-#### `pauseUpload(fileId: string): void`
-Pause an ongoing upload.
-
-```typescript
-gallery.pauseUpload('file-id-123');
-```
-
-#### `resumeUpload(fileId: string): Promise<void>`
-Resume a paused upload.
-
-```typescript
-await gallery.resumeUpload('file-id-123');
-```
-
-#### `retryUpload(fileId: string): Promise<void>`
-Retry a failed upload.
-
-```typescript
-await gallery.retryUpload('file-id-123');
-```
-
-#### `cancelUpload(fileId: string): void`
-Cancel an upload and remove the file.
-
-```typescript
-gallery.cancelUpload('file-id-123');
-```
-
-#### `pauseAll(): void`
-Pause all currently uploading files.
-
-```typescript
-gallery.pauseAll();
-```
-
-#### `resumeAll(): void`
-Resume all paused uploads.
-
-```typescript
-gallery.resumeAll();
-```
-
-#### `retryAll(): void`
-Retry all failed uploads.
-
-```typescript
-gallery.retryAll();
-```
-
-#### `cancelAll(): void`
-Cancel all active uploads and remove them.
-
-```typescript
-gallery.cancelAll();
-```
+| Method | Description |
+|--------|-------------|
+| `pauseUpload(fileId: string)` | Pause an ongoing upload |
+| `resumeUpload(fileId: string)` | Resume a paused upload |
+| `retryUpload(fileId: string)` | Retry a failed upload |
+| `cancelUpload(fileId: string)` | Cancel an upload and remove the file |
+| `pauseAll()` | Pause all currently uploading files |
+| `resumeAll()` | Resume all paused uploads |
+| `retryAll()` | Retry all failed uploads |
+| `cancelAll()` | Cancel all active uploads and remove them |
 
 ### Custom Actions
 
-#### `addCustomAction(icon: string, text: string): string`
-Add a custom action button to the gallery. Returns the action ID.
-
-```typescript
-const cameraIcon = '<svg viewBox="0 0 24 24">...</svg>';
-const actionId = gallery.addCustomAction(cameraIcon, 'Camera');
-```
-
-#### `removeCustomAction(actionId: string): void`
-Remove a custom action button.
-
-```typescript
-gallery.removeCustomAction(actionId);
-```
-
-#### `clearCustomActions(): void`
-Remove all custom action buttons.
-
-```typescript
-gallery.clearCustomActions();
-```
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `addCustomAction(icon: string, text: string)` | `string` | Add a custom action button; returns the action ID |
+| `removeCustomAction(actionId: string)` | `void` | Remove a custom action button |
+| `clearCustomActions()` | `void` | Remove all custom action buttons |
 
 ### Utility
 
-#### `openFilePicker(): void`
-Programmatically open the file picker dialog.
-
-```typescript
-gallery.openFilePicker();
-```
-
-#### `setFileBadge(fileId: string, badge: string, position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'): void`
-Add a custom badge overlay to a file's preview thumbnail. Supports HTML content for avatars, icons, or custom elements.
-
-```typescript
-// Add user avatar badge
-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('file-id-123', avatarHTML, 'top-right');
-```
-
-#### `removeFileBadge(fileId: string): void`
-Remove a badge from a file.
-
-```typescript
-gallery.removeFileBadge('file-id-123');
-```
+| Method | Description |
+|--------|-------------|
+| `openFilePicker()` | Programmatically open the file picker dialog |
+| `setFileBadge(fileId, badge, position?)` | Add a custom badge overlay to a file's preview |
+| `removeFileBadge(fileId)` | Remove a badge from a file |
 
 ## Events
 
-### `files-change`
-Fired when files are added or removed.
-
-**Detail**: `{ files: GalleryFile[] }`
-
-```typescript
-gallery.addEventListener('files-change', (e) => {
-  console.log('Files:', e.detail.files);
-});
-```
-
-### `upload-progress`
-Fired during upload progress.
-
-**Detail**: `{ file: GalleryFile, progress: number }`
-
-```typescript
-gallery.addEventListener('upload-progress', (e) => {
-  console.log(`${e.detail.file.file.name}: ${e.detail.progress}%`);
-});
-```
-
-### `upload-complete`
-Fired when an upload completes successfully.
-
-**Detail**: `{ file: GalleryFile, response: UploadResponse, component: SniceFileGalleryElement }`
-
-```typescript
-gallery.addEventListener('upload-complete', (e) => {
-  console.log('Upload complete:', e.detail.response);
-});
-```
-
-### `upload-pause`
-Fired when an upload is paused.
-
-**Detail**: `{ file: GalleryFile, component: SniceFileGalleryElement }`
-
-```typescript
-gallery.addEventListener('upload-pause', (e) => {
-  console.log('Upload paused:', e.detail.file.file.name);
-});
-```
-
-### `file-remove`
-Fired when a file is removed from the gallery.
-
-**Detail**: `{ file: GalleryFile, component: SniceFileGalleryElement }`
-
-```typescript
-gallery.addEventListener('file-remove', (e) => {
-  console.log('File removed:', e.detail.file.file.name);
-});
-```
-
-### `upload-error`
-Fired when an upload fails.
-
-**Detail**: `{ file: GalleryFile, error: string, component: SniceFileGalleryElement }`
-
-```typescript
-gallery.addEventListener('upload-error', (e) => {
-  console.error('Upload error:', e.detail.error);
-});
-```
-
-### `custom-action-click`
-Fired when a custom action button is clicked.
-
-**Detail**: `{ actionId: string }`
-
-```typescript
-gallery.addEventListener('custom-action-click', (e) => {
-  console.log('Custom action clicked:', e.detail.actionId);
-});
-```
-
-### `gallery-error`
-Fired when a validation or general error occurs.
-
-**Detail**: `{ message: string }`
-
-```typescript
-gallery.addEventListener('gallery-error', (e) => {
-  console.error('Error:', e.detail.message);
-});
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `files-change` | `{ files, component }` | Files added or removed |
+| `upload-progress` | `{ file, progress, component }` | Upload progress update |
+| `upload-complete` | `{ file, response, component }` | Upload completed successfully |
+| `upload-error` | `{ file, error, component }` | Upload failed |
+| `upload-pause` | `{ file, component }` | Upload paused |
+| `file-remove` | `{ file, component }` | File removed from gallery |
+| `custom-action-click` | `{ actionId, component }` | Custom action button clicked |
+| `gallery-error` | `{ message, component }` | Validation or general error |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
+| Part | Description |
+|------|-------------|
+| `base` | Outer gallery container |
+| `dropzone` | Drag-and-drop upload zone |
+| `gallery` | File thumbnails grid/list area |
 
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer gallery container |
-| `dropzone` | `<div>` | Drag-and-drop upload zone |
-| `gallery` | `<div>` | File thumbnails grid/list area |
-
-```css
-snice-file-gallery::part(dropzone) {
-  border-style: dashed;
-  border-color: #3b82f6;
-}
+## Basic Usage
 
-snice-file-gallery::part(gallery) {
-  gap: 1rem;
-}
+```typescript
+import 'snice/components/file-gallery/snice-file-gallery';
 ```
 
-## Basic Usage
-
 ```html
 <snice-file-gallery controller="upload-handler"></snice-file-gallery>
 ```
@@ -408,72 +145,8 @@ class UploadHandler implements IController {
 }
 ```
 
-## Upload Handler
-
-The file gallery uses the `@request/@respond` pattern for uploads. Attach a controller with `@respond('file-gallery-upload')`:
-
-```typescript
-import { controller, respond, IController } from 'snice';
-
-@controller('upload-handler')
-class UploadHandler implements IController {
-  element: HTMLElement | null = null;
-
-  async attach(element: HTMLElement) {
-    this.element = element;
-  }
-
-  async detach() {}
-
-  @respond('file-gallery-upload')
-  async handleUpload(request) {
-    const { file, fileId, onProgress, signal } = request;
-
-    const formData = new FormData();
-    formData.append('file', file);
-
-    return new Promise((resolve, reject) => {
-      const xhr = new XMLHttpRequest();
-
-      xhr.upload.addEventListener('progress', (e) => {
-        if (e.lengthComputable && onProgress) {
-          onProgress(e.loaded / e.total);
-        }
-      });
-
-      xhr.addEventListener('load', () => {
-        if (xhr.status === 200) {
-          const response = JSON.parse(xhr.responseText);
-          resolve({ success: true, fileId, url: response.url });
-        } else {
-          reject(new Error('Upload failed'));
-        }
-      });
-
-      xhr.addEventListener('error', () => reject(new Error('Network error')));
-
-      if (signal) {
-        signal.addEventListener('abort', () => {
-          xhr.abort();
-          reject(new Error('Upload cancelled'));
-        });
-      }
-
-      xhr.open('POST', '/api/upload');
-      xhr.send(formData);
-    });
-  }
-}
-```
-
 ## Examples
 
-### Basic Gallery
-
-```html
-<snice-file-gallery></snice-file-gallery>
-```
-
 ### Image Gallery
 
 ```html
@@ -486,16 +159,6 @@ class UploadHandler implements IController {
 <snice-file-gallery auto-upload="false" controller="upload-handler"></snice-file-gallery>
 ```
 
-```typescript
-// Upload files manually
-const files = gallery.files;
-for (const file of files) {
-  if (file.uploadStatus === 'pending') {
-    await gallery.resumeUpload(file.id);
-  }
-}
-```
-
 ### File Limits
 
 ```html
@@ -511,19 +174,9 @@ for (const file of files) {
 <snice-file-gallery view="list"></snice-file-gallery>
 ```
 
-### Custom File Types
-
-```html
-<snice-file-gallery
-  accept=".pdf,.doc,.docx,.txt"
-  allow-pause="false"
-></snice-file-gallery>
-```
-
 ### Add Button Mode
 
 ```html
-<!-- Hide drop zone and show plus tile in gallery instead -->
 <snice-file-gallery
   show-dropzone="false"
   show-add-button="true"
@@ -531,43 +184,24 @@ for (const file of files) {
 ></snice-file-gallery>
 ```
 
-### Tracking Upload Events
+### Custom Action Buttons
 
 ```typescript
-gallery.addEventListener('files-change', (e) => {
-  console.log('Files changed:', e.detail.files);
-});
-
-gallery.addEventListener('upload-progress', (e) => {
-  console.log(`${e.detail.file.file.name}: ${e.detail.progress}%`);
-});
+const cameraIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+  <path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z" stroke-width="2"/>
+  <circle cx="12" cy="13" r="4" stroke-width="2"/>
+</svg>`;
 
-gallery.addEventListener('upload-complete', (e) => {
-  console.log('Upload complete:', e.detail.file.file.name);
-});
+const cameraActionId = gallery.addCustomAction(cameraIcon, 'Camera');
 
-gallery.addEventListener('upload-error', (e) => {
-  console.error('Upload failed:', e.detail.error);
+gallery.addEventListener('custom-action-click', (e) => {
+  if (e.detail.actionId === cameraActionId) {
+    // Open camera, capture image, etc.
+  }
 });
 ```
 
-### Programmatic File Management
-
-```typescript
-gallery.pauseAll();
-gallery.resumeAll();
-gallery.retryAll();
-gallery.clearCompleted();
-gallery.clear();
-```
-
-### Custom Badges for Collaboration
-
-Use badges to show user avatars on files in collaborative scenarios:
-
-```html
-<snice-file-gallery show-dropzone="false" show-add-button="true" controller="upload-handler"></snice-file-gallery>
-```
+### Custom Badges
 
 ```typescript
 const avatarHTML = `<div style="
@@ -575,40 +209,38 @@ const avatarHTML = `<div style="
   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('file-id-123', avatarHTML, 'top-right');
 ```
 
-### Custom Action Buttons
+### Tracking Upload Events
 
 ```typescript
-const cameraIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
-  <path d="M23 19a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h4l2-3h6l2 3h4a2 2 0 0 1 2 2z" stroke-width="2"/>
-  <circle cx="12" cy="13" r="4" stroke-width="2"/>
-</svg>`;
+gallery.addEventListener('files-change', (e) => {
+  console.log('Files changed:', e.detail.files);
+});
 
-const cameraActionId = gallery.addCustomAction(cameraIcon, 'Camera');
+gallery.addEventListener('upload-progress', (e) => {
+  console.log(`${e.detail.file.file.name}: ${e.detail.progress}%`);
+});
 
-gallery.addEventListener('custom-action-click', (e) => {
-  if (e.detail.actionId === cameraActionId) {
-    openCamera().then((imageBlob) => {
-      const file = new File([imageBlob], `photo-${Date.now()}.jpg`, { type: 'image/jpeg' });
-      const preview = URL.createObjectURL(imageBlob);
-      gallery.addFileWithPreview(file, preview);
-    });
-  }
+gallery.addEventListener('upload-complete', (e) => {
+  console.log('Upload complete:', e.detail.file.file.name);
+});
+
+gallery.addEventListener('upload-error', (e) => {
+  console.error('Upload failed:', e.detail.error);
 });
 ```
 
-### Advanced Upload Handler with Retry
+### Upload Handler with XHR Progress
 
 ```typescript
 import { controller, respond, IController } from 'snice';
 
-@controller('upload-with-retry')
-class UploadWithRetry implements IController {
+@controller('upload-handler')
+class UploadHandler implements IController {
   element: HTMLElement | null = null;
   async attach(element: HTMLElement) { this.element = element; }
   async detach() {}
@@ -617,43 +249,39 @@ class UploadWithRetry implements IController {
   async handleUpload(request) {
     const { file, fileId, onProgress, signal } = request;
 
-    const uploadToServer = async (retries = 3) => {
-      try {
-        const formData = new FormData();
-        formData.append('file', file);
+    const formData = new FormData();
+    formData.append('file', file);
 
-        const response = await fetch('/api/upload', {
-          method: 'POST',
-          body: formData,
-          signal,
-        });
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
 
-        if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
+      xhr.upload.addEventListener('progress', (e) => {
+        if (e.lengthComputable && onProgress) {
+          onProgress(e.loaded / e.total);
+        }
+      });
 
-        const data = await response.json();
-        return { success: true, fileId, url: data.url };
-      } catch (error) {
-        if (retries > 0 && error.name !== 'AbortError') {
-          await new Promise(resolve => setTimeout(resolve, 1000));
-          return uploadToServer(retries - 1);
+      xhr.addEventListener('load', () => {
+        if (xhr.status === 200) {
+          const response = JSON.parse(xhr.responseText);
+          resolve({ success: true, fileId, url: response.url });
+        } else {
+          reject(new Error('Upload failed'));
         }
-        throw error;
+      });
+
+      xhr.addEventListener('error', () => reject(new Error('Network error')));
+
+      if (signal) {
+        signal.addEventListener('abort', () => {
+          xhr.abort();
+          reject(new Error('Upload cancelled'));
+        });
       }
-    };
 
-    return uploadToServer();
+      xhr.open('POST', '/api/upload');
+      xhr.send(formData);
+    });
   }
 }
 ```
-
-## Features
-
-- **Drag and Drop**: Native drag-and-drop support with visual feedback
-- **Image Preview**: Automatic thumbnail generation for image files
-- **Pausable Uploads**: Pause and resume uploads using AbortController
-- **Progress Tracking**: Real-time upload progress for each file
-- **File Management**: Add, remove, pause, resume, and retry uploads
-- **View Modes**: Toggle between grid and list layouts
-- **Validation**: File size and type validation with error messaging
-- **Auto Upload**: Optional automatic upload on file add
-- **Accessibility**: Full keyboard support and ARIA attributes