snice 3.2.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/gantt.md

@@ -0,0 +1,347 @@
+# Gantt Chart Component
+
+Visual project timeline with task bars and progress tracking.
+
+## Basic Usage
+
+```javascript
+const gantt = document.querySelector('snice-gantt');
+
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Planning',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 7),
+    progress: 100
+  },
+  {
+    id: 2,
+    name: 'Development',
+    start: new Date(2024, 0, 8),
+    end: new Date(2024, 0, 31),
+    progress: 45
+  }
+];
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tasks` | `GanttTask[]` | `[]` | Project tasks |
+| `viewMode` | `'day' \| 'week' \| 'month' \| 'year'` | `'day'` | Timeline granularity |
+| `showToday` | `boolean` | `true` | Highlight today |
+| `showProgress` | `boolean` | `true` | Show progress bars |
+| `showDependencies` | `boolean` | `false` | Show task dependencies |
+| `minDate` | `Date \| string` | `''` | Timeline start date |
+| `maxDate` | `Date \| string` | `''` | Timeline end date |
+
+## GanttTask Interface
+
+```typescript
+interface GanttTask {
+  id: string | number;
+  name: string;
+  start: Date | string;
+  end: Date | string;
+  progress?: number; // 0-100
+  dependencies?: (string | number)[];
+  color?: string;
+  data?: any;
+}
+```
+
+## Methods
+
+### `getTask(id: string | number): GanttTask | undefined`
+Get task by ID.
+
+```javascript
+const task = gantt.getTask(1);
+console.log(task.name, task.progress);
+```
+
+### `scrollToToday(): void`
+Scroll viewport to today's date.
+
+```javascript
+gantt.scrollToToday();
+```
+
+### `scrollToTask(id: string | number): void`
+Scroll to specific task.
+
+```javascript
+gantt.scrollToTask(5);
+```
+
+## Events
+
+### `@snice/gantt-task-click`
+Dispatched when task bar is clicked.
+
+```javascript
+gantt.addEventListener('@snice/gantt-task-click', (e) => {
+  console.log('Task:', e.detail.task);
+  showTaskDetails(e.detail.task);
+});
+```
+
+**Detail:** `{ task: GanttTask, gantt: SniceGanttElement }`
+
+## Examples
+
+### Basic Timeline
+
+```javascript
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Task 1',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 10)
+  },
+  {
+    id: 2,
+    name: 'Task 2',
+    start: new Date(2024, 0, 11),
+    end: new Date(2024, 0, 20)
+  }
+];
+```
+
+### With Progress
+
+```javascript
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Design',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 14),
+    progress: 80
+  },
+  {
+    id: 2,
+    name: 'Development',
+    start: new Date(2024, 0, 8),
+    end: new Date(2024, 0, 31),
+    progress: 35
+  }
+];
+```
+
+### Color-Coded Tasks
+
+```javascript
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Planning',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 7),
+    color: '#4caf50',
+    progress: 100
+  },
+  {
+    id: 2,
+    name: 'In Progress',
+    start: new Date(2024, 0, 8),
+    end: new Date(2024, 0, 21),
+    color: '#ff9800',
+    progress: 40
+  },
+  {
+    id: 3,
+    name: 'Not Started',
+    start: new Date(2024, 0, 22),
+    end: new Date(2024, 0, 31),
+    color: '#f44336',
+    progress: 0
+  }
+];
+```
+
+### Different View Modes
+
+```html
+<button onclick="gantt.viewMode = 'day'">Day</button>
+<button onclick="gantt.viewMode = 'week'">Week</button>
+<button onclick="gantt.viewMode = 'month'">Month</button>
+<button onclick="gantt.viewMode = 'year'">Year</button>
+```
+
+### With Dependencies
+
+```javascript
+gantt.showDependencies = true;
+
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Task A',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 5)
+  },
+  {
+    id: 2,
+    name: 'Task B',
+    start: new Date(2024, 0, 6),
+    end: new Date(2024, 0, 12),
+    dependencies: [1] // Depends on Task A
+  }
+];
+```
+
+### Date Range
+
+```html
+<snice-gantt
+  min-date="2024-01-01"
+  max-date="2024-12-31">
+</snice-gantt>
+```
+
+### Event Handling
+
+```javascript
+gantt.addEventListener('@snice/gantt-task-click', (e) => {
+  const task = e.detail.task;
+
+  // Show task modal
+  showModal({
+    title: task.name,
+    content: `
+      Start: ${task.start.toLocaleDateString()}
+      End: ${task.end.toLocaleDateString()}
+      Progress: ${task.progress}%
+    `
+  });
+});
+```
+
+### Software Project
+
+```javascript
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Requirements Gathering',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 14),
+    progress: 100,
+    color: '#4caf50'
+  },
+  {
+    id: 2,
+    name: 'Design',
+    start: new Date(2024, 0, 15),
+    end: new Date(2024, 0, 31),
+    progress: 75,
+    color: '#2196f3',
+    dependencies: [1]
+  },
+  {
+    id: 3,
+    name: 'Development',
+    start: new Date(2024, 1, 1),
+    end: new Date(2024, 2, 31),
+    progress: 40,
+    color: '#ff9800',
+    dependencies: [2]
+  },
+  {
+    id: 4,
+    name: 'Testing',
+    start: new Date(2024, 3, 1),
+    end: new Date(2024, 3, 30),
+    progress: 0,
+    color: '#9c27b0',
+    dependencies: [3]
+  }
+];
+```
+
+### Construction Project
+
+```javascript
+gantt.viewMode = 'week';
+
+gantt.tasks = [
+  { id: 1, name: 'Site Preparation', start: '2024-01-01', end: '2024-01-14', progress: 100 },
+  { id: 2, name: 'Foundation', start: '2024-01-15', end: '2024-02-15', progress: 60 },
+  { id: 3, name: 'Framing', start: '2024-02-16', end: '2024-03-30', progress: 20 },
+  { id: 4, name: 'Roofing', start: '2024-04-01', end: '2024-04-21', progress: 0 },
+  { id: 5, name: 'Interior', start: '2024-04-22', end: '2024-06-30', progress: 0 }
+];
+```
+
+### Marketing Campaign
+
+```javascript
+gantt.tasks = [
+  {
+    id: 1,
+    name: 'Campaign Planning',
+    start: new Date(2024, 0, 1),
+    end: new Date(2024, 0, 7),
+    progress: 100
+  },
+  {
+    id: 2,
+    name: 'Content Creation',
+    start: new Date(2024, 0, 8),
+    end: new Date(2024, 0, 21),
+    progress: 70
+  },
+  {
+    id: 3,
+    name: 'Social Media',
+    start: new Date(2024, 0, 15),
+    end: new Date(2024, 1, 15),
+    progress: 30
+  },
+  {
+    id: 4,
+    name: 'Email Campaign',
+    start: new Date(2024, 0, 22),
+    end: new Date(2024, 1, 10),
+    progress: 10
+  }
+];
+```
+
+### Dynamic Updates
+
+```javascript
+// Update progress
+function updateProgress(taskId, progress) {
+  gantt.tasks = gantt.tasks.map(task =>
+    task.id === taskId ? { ...task, progress } : task
+  );
+}
+
+// Add task
+function addTask(task) {
+  gantt.tasks = [...gantt.tasks, task];
+}
+
+// Remove task
+function removeTask(taskId) {
+  gantt.tasks = gantt.tasks.filter(t => t.id !== taskId);
+}
+```
+
+## Accessibility
+
+- Keyboard navigation
+- ARIA labels for tasks
+- Screen reader friendly
+- High contrast support
+
+## Browser Support
+
+- Modern browsers with Custom Elements v1 support
+- Date calculations via Date API
+- Responsive timeline scaling