snice 3.1.0 → 3.3.0

package/docs/components/draw.md

@@ -0,0 +1,307 @@
+# Draw Component
+
+Canvas drawing with smooth lazy-brush technology.
+
+## Basic Usage
+
+```html
+<snice-draw id="draw" width="800" height="600"></snice-draw>
+
+<script>
+  const draw = document.getElementById('draw');
+
+  // Clear canvas
+  draw.clear();
+
+  // Undo/redo
+  draw.undo();
+  draw.redo();
+
+  // Download
+  draw.download('my-drawing.png');
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `width` | `number` | `800` | Canvas width |
+| `height` | `number` | `600` | Canvas height |
+| `tool` | `DrawTool` | `'pen'` | Drawing tool |
+| `color` | `string` | `'#000000'` | Brush color |
+| `strokeWidth` | `number` | `2` | Brush width |
+| `backgroundColor` | `string` | `'#ffffff'` | Canvas background |
+| `lazy` | `boolean` | `false` | Enable lazy brush |
+| `lazyRadius` | `number` | `60` | Lazy brush radius |
+| `friction` | `number` | `0.1` | Lazy brush friction |
+| `smoothing` | `number` | `0.5` | Line smoothing (0-1) |
+| `autoPolygon` | `boolean` | `false` | Enable auto-polygon |
+| `polygonCurvePoints` | `number` | `10` | Polygon curve smoothness (2-30) |
+| `disabled` | `boolean` | `false` | Disable drawing |
+
+## Tools
+
+- `'pen'` - Draw with brush
+- `'eraser'` - Erase strokes
+- `'line'` - Draw straight lines
+- `'rectangle'` - Draw rectangles
+- `'circle'` - Draw circles
+- `'text'` - Add text
+
+## Methods
+
+### `clear(): void`
+Clear the entire canvas.
+
+### `undo(): void`
+Undo last stroke.
+
+### `redo(): void`
+Redo previously undone stroke.
+
+### `toDataURL(type?, quality?): string`
+Export as data URL.
+
+### `toBlob(type?, quality?): Promise<Blob>`
+Export as Blob.
+
+### `download(filename?): void`
+Download drawing.
+
+### `loadImage(url): Promise<void>`
+Load image onto canvas.
+
+### `getStrokes(): DrawStroke[]`
+Get all strokes.
+
+### `setStrokes(strokes): void`
+Set strokes (for loading saved drawings).
+
+## Events
+
+- `@snice/draw-start` - Drawing started
+- `@snice/draw-end` - Drawing ended (stroke complete)
+- `@snice/draw-clear` - Canvas cleared
+- `@snice/draw-undo` - Undo performed
+- `@snice/draw-redo` - Redo performed
+
+## Examples
+
+### Basic Drawing
+
+```html
+<snice-draw width="800" height="600"></snice-draw>
+```
+
+### Custom Colors
+
+```javascript
+const draw = document.querySelector('snice-draw');
+draw.color = '#ff0000';
+draw.strokeWidth = 5;
+```
+
+### Toolbar Integration
+
+```html
+<div>
+  <button onclick="draw.tool = 'pen'">Pen</button>
+  <button onclick="draw.tool = 'eraser'">Eraser</button>
+  <input type="color" oninput="draw.color = this.value">
+  <button onclick="draw.clear()">Clear</button>
+  <button onclick="draw.undo()">Undo</button>
+  <button onclick="draw.redo()">Redo</button>
+</div>
+
+<snice-draw id="draw"></snice-draw>
+```
+
+### Lazy Brush Settings
+
+```javascript
+// More responsive (smaller radius)
+draw.lazyRadius = 10;
+
+// Very smooth (larger radius)
+draw.lazyRadius = 60;
+
+// Disable lazy brush
+draw.lazy = false;
+```
+
+### Export Drawing
+
+```javascript
+// As data URL
+const dataURL = draw.toDataURL('image/png');
+
+// As blob
+const blob = await draw.toBlob('image/png', 0.9);
+
+// Download
+draw.download('my-artwork.png');
+```
+
+### Save and Load
+
+Each stroke has a unique ID for tracking and manipulation:
+
+```javascript
+// Save drawing
+const strokes = draw.getStrokes();
+localStorage.setItem('drawing', JSON.stringify(strokes));
+
+// Load drawing
+const saved = JSON.parse(localStorage.getItem('drawing'));
+draw.setStrokes(saved);
+
+// Access individual strokes by ID
+const strokes = draw.getStrokes();
+console.log(strokes[0].id); // e.g., "stroke-1735216842123-x7k9m2p"
+
+// Filter strokes
+const penStrokes = strokes.filter(s => s.tool === 'pen');
+
+// Remove specific stroke
+const filtered = strokes.filter(s => s.id !== 'stroke-id-to-remove');
+draw.setStrokes(filtered);
+```
+
+**Stroke Structure:**
+
+```typescript
+interface DrawStroke {
+  id: string;          // Unique identifier
+  tool: DrawTool;      // 'pen' | 'eraser' | etc
+  color: string;       // Hex color
+  width: number;       // Stroke width
+  points: Point[];     // Array of {x, y, pressure?}
+  timestamp: number;   // Creation time (ms)
+}
+```
+
+### Load Background Image
+
+```javascript
+await draw.loadImage('background.jpg');
+```
+
+### Event Handling
+
+```javascript
+draw.addEventListener('@snice/draw-end', (e) => {
+  const stroke = e.detail.stroke;
+  console.log(`Drew ${stroke.points.length} points`);
+
+  // Auto-save
+  saveDrawing();
+});
+```
+
+### Keyboard Shortcuts
+
+```javascript
+document.addEventListener('keydown', (e) => {
+  if (e.ctrlKey || e.metaKey) {
+    if (e.key === 'z') {
+      e.preventDefault();
+      if (e.shiftKey) {
+        draw.redo();
+      } else {
+        draw.undo();
+      }
+    }
+  }
+});
+```
+
+## Lazy Brush
+
+The lazy brush creates smooth, organic lines by making the brush lag behind your cursor within a configurable radius. This eliminates jitter and produces professional-looking strokes.
+
+**How it works:**
+1. Cursor moves freely
+2. Brush follows within `lazyRadius`
+3. Creates smooth curves
+4. Reduces hand tremor effects
+
+**Tips:**
+- Larger radius = smoother, slower response
+- Smaller radius = more control, less smoothing
+- Disable for pixel-perfect control
+
+## Auto-Polygon
+
+Auto-polygon automatically processes completed strokes into closed shapes. When you finish drawing (release the mouse/pointer), it analyzes the stroke and applies smart shape completion.
+
+**Features:**
+
+1. **Self-Intersection Detection**
+   - Detects when your stroke crosses itself
+   - Automatically trims at the first intersection point
+   - Creates a clean closed shape without excess
+
+2. **Auto-Close Open Shapes**
+   - If start and end points are far apart (>20px)
+   - Connects them with a smooth quadratic curve
+   - Curve adapts to the gap distance
+
+**Properties:**
+
+- `autoPolygon` - Enable/disable the feature (default: `false`)
+- `polygonCurvePoints` - Curve smoothness, 2-30 (default: `10`)
+  - Lower values (2-5): Sharp, direct connection
+  - Medium values (10-15): Balanced smooth curve
+  - Higher values (20-30): Very smooth, organic curve
+
+**Example:**
+
+```javascript
+const draw = document.querySelector('snice-draw');
+
+// Enable auto-polygon
+draw.autoPolygon = true;
+
+// Adjust curve smoothness
+draw.polygonCurvePoints = 15; // Smoother curves
+```
+
+```html
+<snice-draw
+  auto-polygon
+  polygon-curve-points="15">
+</snice-draw>
+```
+
+**Use Cases:**
+
+- Sketching closed shapes quickly
+- Drawing polygons without precision
+- Creating organic forms that auto-complete
+- UI wireframing and mockups
+- Diagram creation
+
+**How It Works:**
+
+The algorithm processes strokes on `pointerup`:
+
+1. Simplify points (sample every 5th point for performance)
+2. Check for self-intersections using line-line intersection
+3. If intersection found: trim and close at that point
+4. If no intersection and gap >20px: generate curve points
+5. Use quadratic Bezier with perpendicular control point
+6. Insert interpolated points for smooth rendering
+
+## Browser Support
+
+- Modern browsers with Canvas API
+- Pointer Events API for touch support
+- Works on desktop and mobile
+
+## Performance
+
+- Optimized canvas rendering
+- Efficient stroke storage
+- Smooth 60fps drawing
+- Touch and stylus pressure support

package/docs/components/empty-state.md

@@ -0,0 +1,79 @@
+# Empty State Component
+
+The `<snice-empty-state>` component provides a consistent way to display empty or no-data states.
+
+## Basic Usage
+
+```html
+<snice-empty-state
+  icon="📭"
+  title="No data"
+  description="There's nothing here yet"
+></snice-empty-state>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `icon` | `string` | `'📭'` | Icon (emoji or text) |
+| `title` | `string` | `'No data'` | Title text |
+| `description` | `string` | `''` | Description text |
+| `actionText` | `string` | `''` | Action button text |
+| `actionHref` | `string` | `''` | Action link URL |
+
+## Events
+
+### `@snice/empty-state-action`
+Fired when action button/link is clicked.
+
+## Examples
+
+### No Search Results
+
+```html
+<snice-empty-state
+  icon="🔍"
+  title="No results found"
+  description="Try adjusting your search criteria"
+  action-text="Clear Search"
+></snice-empty-state>
+```
+
+### Empty List
+
+```html
+<snice-empty-state
+  icon="📦"
+  title="No items yet"
+  description="Get started by creating your first item"
+  action-text="Create Item"
+></snice-empty-state>
+```
+
+### 404 Page
+
+```html
+<snice-empty-state
+  icon="🤷"
+  title="Page not found"
+  description="The page you're looking for doesn't exist"
+  action-text="Go Home"
+  action-href="/"
+></snice-empty-state>
+```
+
+### With Custom Content
+
+```html
+<snice-empty-state
+  icon="🎨"
+  title="No projects"
+>
+  <div slot="">
+    <button>Create Project</button>
+    <button>Import Project</button>
+  </div>
+</snice-empty-state>
+```

package/docs/components/file-upload.md

@@ -0,0 +1,263 @@
+# File Upload Component
+
+The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Features](#features)
+- [Examples](#examples)
+
+## Basic Usage
+
+```html
+<snice-file-upload
+  label="Upload Documents"
+  accept=".pdf,.doc,.docx"
+  max-size="5242880"
+></snice-file-upload>
+```
+
+```typescript
+import 'snice/components/file-upload/snice-file-upload';
+
+const upload = document.querySelector('snice-file-upload');
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log('Files:', e.detail.files);
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'outlined' \| 'filled'` | `'outlined'` | Visual style variant |
+| `accept` | `string` | `''` | Allowed file types (same as input accept) |
+| `multiple` | `boolean` | `false` | Allow multiple file selection |
+| `label` | `string` | `''` | Label text |
+| `helperText` | `string` | `''` | Helper text below upload area |
+| `errorText` | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Whether upload is disabled |
+| `required` | `boolean` | `false` | Whether upload is required |
+| `invalid` | `boolean` | `false` | Whether to show invalid state |
+| `maxSize` | `number` | `-1` | Maximum file size in bytes (-1 = no limit) |
+| `maxFiles` | `number` | `-1` | Maximum number of files (-1 = no limit) |
+| `name` | `string` | `''` | Form field name |
+| `dragDrop` | `boolean` | `true` | Enable drag-and-drop |
+| `showPreview` | `boolean` | `true` | Show image previews |
+| `files` | `FileList \| null` | `null` | Selected files (read-only) |
+
+## Methods
+
+### `clear(): void`
+Remove all selected files.
+
+```typescript
+upload.clear();
+```
+
+### `removeFile(index: number): void`
+Remove a specific file by index.
+
+```typescript
+upload.removeFile(0); // Remove first file
+```
+
+## Events
+
+### `@snice/file-upload-change`
+Fired when files are added or removed.
+
+**Detail**: `{ files: File[], fileUpload: SniceFileUploadElement }`
+
+```typescript
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log('Selected files:', e.detail.files);
+  e.detail.files.forEach(file => {
+    console.log(`- ${file.name} (${file.size} bytes)`);
+  });
+});
+```
+
+### `@snice/file-upload-error`
+Fired when file validation fails.
+
+**Detail**: `{ message: string, fileUpload: SniceFileUploadElement }`
+
+```typescript
+upload.addEventListener('@snice/file-upload-error', (e) => {
+  console.error('Upload error:', e.detail.message);
+});
+```
+
+## Features
+
+- **Drag and Drop**: Native drag-and-drop support with visual feedback
+- **Image Preview**: Automatic thumbnail generation for image files
+- **File Validation**: Size and type validation with error messaging
+- **Multiple Files**: Support for single or multiple file selection
+- **File Management**: Add and remove files before upload
+- **Form Integration**: Form-associated custom element
+- **Accessibility**: Full keyboard support and ARIA attributes
+
+## Examples
+
+### Basic Upload
+
+```html
+<snice-file-upload
+  label="Upload File"
+  helper-text="Choose a file to upload"
+></snice-file-upload>
+```
+
+### Image Upload with Preview
+
+```html
+<snice-file-upload
+  label="Upload Image"
+  accept="image/*"
+  max-size="2097152"
+  helper-text="Maximum 2MB, images only"
+></snice-file-upload>
+```
+
+### Multiple Files
+
+```html
+<snice-file-upload
+  label="Upload Documents"
+  accept=".pdf,.doc,.docx"
+  multiple
+  max-files="5"
+  helper-text="Select up to 5 documents"
+></snice-file-upload>
+```
+
+### Without Drag-and-Drop
+
+```html
+<snice-file-upload
+  label="Upload File"
+  drag-drop="false"
+></snice-file-upload>
+```
+
+### Different Sizes
+
+```html
+<snice-file-upload size="small" label="Small"></snice-file-upload>
+<snice-file-upload size="medium" label="Medium"></snice-file-upload>
+<snice-file-upload size="large" label="Large"></snice-file-upload>
+```
+
+### Different Variants
+
+```html
+<snice-file-upload variant="outlined" label="Outlined"></snice-file-upload>
+<snice-file-upload variant="filled" label="Filled"></snice-file-upload>
+```
+
+### Error State
+
+```html
+<snice-file-upload
+  label="Resume"
+  invalid
+  error-text="Please upload your resume"
+  required
+></snice-file-upload>
+```
+
+### File Type Restrictions
+
+```html
+<!-- Images only -->
+<snice-file-upload accept="image/*" label="Images"></snice-file-upload>
+
+<!-- Specific formats -->
+<snice-file-upload accept=".pdf,.doc,.docx" label="Documents"></snice-file-upload>
+
+<!-- Multiple types -->
+<snice-file-upload accept="image/*,.pdf" label="Images and PDFs"></snice-file-upload>
+```
+
+### With Size Validation
+
+```html
+<snice-file-upload
+  label="Upload Photo"
+  accept="image/*"
+  max-size="5242880"
+  helper-text="Maximum 5MB"
+></snice-file-upload>
+
+<script>
+const upload = document.querySelector('snice-file-upload');
+upload.addEventListener('@snice/file-upload-error', (e) => {
+  alert(e.detail.message);
+});
+</script>
+```
+
+### Form Integration
+
+```html
+<form id="upload-form">
+  <snice-file-upload
+    name="documents"
+    label="Upload Documents"
+    accept=".pdf,.doc,.docx"
+    multiple
+    required
+  ></snice-file-upload>
+
+  <button type="submit">Submit</button>
+</form>
+
+<script>
+document.getElementById('upload-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+
+  const formData = new FormData(e.target);
+  const files = formData.getAll('documents');
+
+  console.log(`Uploading ${files.length} file(s)...`);
+
+  // Upload to server
+  const response = await fetch('/api/upload', {
+    method: 'POST',
+    body: formData
+  });
+
+  console.log('Upload complete!');
+});
+</script>
+```
+
+### Managing Files Programmatically
+
+```html
+<snice-file-upload id="file-upload" multiple></snice-file-upload>
+<button onclick="clearFiles()">Clear All</button>
+<button onclick="removeFirst()">Remove First</button>
+
+<script>
+const upload = document.getElementById('file-upload');
+
+function clearFiles() {
+  upload.clear();
+}
+
+function removeFirst() {
+  upload.removeFile(0);
+}
+
+upload.addEventListener('@snice/file-upload-change', (e) => {
+  console.log(`${e.detail.files.length} file(s) selected`);
+});
+</script>
+```