snice 4.9.0 → 4.11.0

package/docs/components/flip-card.md

@@ -0,0 +1,169 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/flip-card.md instead)
+
+# Flip Card Component
+
+The flip card component creates a two-sided card with a CSS 3D flip animation. Content is placed in front and back slots, and the card can be flipped by clicking, keyboard interaction, or programmatically.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-flip-card style="width: 300px; height: 200px;">
+  <div slot="front">Front side</div>
+  <div slot="back">Back side</div>
+</snice-flip-card>
+```
+
+```typescript
+import 'snice/components/flip-card/snice-flip-card';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `flipped` | `boolean` | `false` | Whether the back face is currently showing |
+| `clickToFlip` (attr: `click-to-flip`) | `boolean` | `true` | Enable click and keyboard interaction to toggle the card |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Flip axis direction |
+| `duration` | `number` | `600` | Flip animation duration in milliseconds |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `front` | Content displayed on the front face of the card |
+| `back` | Content displayed on the back face of the card |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `flip()` | -- | Toggle between front and back faces |
+| `flipTo()` | `side: 'front' \| 'back'` | Flip to a specific side |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `flip-change` | `{ flipped: boolean, side: 'front' \| 'back' }` | Fired when the card flips to a different side |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--flip-duration` | Animation duration (automatically set from the `duration` property) |
+
+## Examples
+
+### Horizontal Flip (Default)
+
+Click the card to flip it horizontally around the Y axis.
+
+```html
+<snice-flip-card style="width: 300px; height: 200px;">
+  <div slot="front" style="display: flex; align-items: center; justify-content: center; background: #3b82f6; color: white; height: 100%; border-radius: 8px;">
+    Click to flip
+  </div>
+  <div slot="back" style="display: flex; align-items: center; justify-content: center; background: #10b981; color: white; height: 100%; border-radius: 8px;">
+    Back side!
+  </div>
+</snice-flip-card>
+```
+
+### Vertical Flip
+
+Use `direction="vertical"` to flip the card around the X axis.
+
+```html
+<snice-flip-card direction="vertical" style="width: 300px; height: 200px;">
+  <div slot="front" style="padding: 2rem; background: #f3f4f6; height: 100%; box-sizing: border-box;">
+    <h3>Question</h3>
+    <p>What is the capital of France?</p>
+  </div>
+  <div slot="back" style="padding: 2rem; background: #dbeafe; height: 100%; box-sizing: border-box;">
+    <h3>Answer</h3>
+    <p>Paris</p>
+  </div>
+</snice-flip-card>
+```
+
+### Custom Duration
+
+Set `duration` to control the speed of the flip animation.
+
+```html
+<!-- Slow flip -->
+<snice-flip-card duration="1200" style="width: 250px; height: 180px;">
+  <div slot="front">Slow flip (1.2s)</div>
+  <div slot="back">Back side</div>
+</snice-flip-card>
+
+<!-- Fast flip -->
+<snice-flip-card duration="200" style="width: 250px; height: 180px;">
+  <div slot="front">Fast flip (0.2s)</div>
+  <div slot="back">Back side</div>
+</snice-flip-card>
+```
+
+### Programmatic Control
+
+Disable click-to-flip and control the card from JavaScript.
+
+```html
+<snice-flip-card id="controlled-card" click-to-flip="false" style="width: 300px; height: 200px;">
+  <div slot="front" style="padding: 1.5rem;">
+    <h3>Product Details</h3>
+    <p>Wireless Headphones - $79.99</p>
+  </div>
+  <div slot="back" style="padding: 1.5rem;">
+    <h3>Specifications</h3>
+    <p>Battery: 30 hours, Bluetooth 5.0, Weight: 250g</p>
+  </div>
+</snice-flip-card>
+
+<div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
+  <button onclick="document.getElementById('controlled-card').flipTo('front')">Show Front</button>
+  <button onclick="document.getElementById('controlled-card').flipTo('back')">Show Back</button>
+  <button onclick="document.getElementById('controlled-card').flip()">Toggle</button>
+</div>
+```
+
+### Flashcard Study Deck
+
+Build a flashcard-style study app by listening to flip events.
+
+```html
+<snice-flip-card id="flashcard" direction="vertical" style="width: 350px; height: 250px;">
+  <div slot="front" style="display: flex; align-items: center; justify-content: center; font-size: 1.25rem; padding: 2rem; text-align: center;">
+    <strong>What does HTML stand for?</strong>
+  </div>
+  <div slot="back" style="display: flex; align-items: center; justify-content: center; font-size: 1.25rem; padding: 2rem; text-align: center;">
+    HyperText Markup Language
+  </div>
+</snice-flip-card>
+
+<script type="module">
+  import 'snice/components/flip-card/snice-flip-card';
+
+  const card = document.getElementById('flashcard');
+  card.addEventListener('flip-change', (e) => {
+    console.log(`Now showing: ${e.detail.side}`);
+  });
+</script>
+```
+
+## Accessibility
+
+- **Keyboard support**: When `click-to-flip` is enabled, pressing Enter or Space toggles the card
+- **Focus management**: The card is focusable and has `tabindex="0"` when click-to-flip is enabled
+- **ARIA attributes**: The component conveys state for assistive technologies
+- **Visible content**: Both sides of the card accept arbitrary slotted content, allowing for accessible markup on each face

package/docs/components/flow.md

@@ -0,0 +1,208 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/flow.md instead)
+
+# Flow
+`<snice-flow>`
+
+A node-based flow/diagram editor component for building visual workflows, data pipelines, and node graphs. Features draggable nodes with input/output ports, bezier curve edges, zoom/pan canvas, snap-to-grid, and a minimap overview.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/flow/snice-flow';
+```
+
+```html
+<snice-flow id="flow" snap-to-grid minimap style="height: 450px;"></snice-flow>
+
+<script type="module">
+  const flow = document.getElementById('flow');
+  flow.nodes = [
+    { id: 'start', x: 50, y: 100, label: 'Start',
+      outputs: [{ id: 'out', label: 'Out' }] },
+    { id: 'process', x: 300, y: 80, label: 'Process',
+      inputs: [{ id: 'in', label: 'In' }],
+      outputs: [{ id: 'out', label: 'Out' }] },
+    { id: 'end', x: 550, y: 100, label: 'End',
+      inputs: [{ id: 'in', label: 'In' }] },
+  ];
+  flow.edges = [
+    { id: 'e1', source: 'start', target: 'process',
+      sourcePort: 'out', targetPort: 'in' },
+    { id: 'e2', source: 'process', target: 'end',
+      sourcePort: 'out', targetPort: 'in' },
+  ];
+</script>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/flow/snice-flow';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-flow.min.js"></script>
+```
+
+## Examples
+
+### Data Pipeline
+
+Build a data processing pipeline with typed nodes and colored headers:
+
+```html
+<snice-flow id="pipeline" snap-to-grid minimap style="height: 500px;"></snice-flow>
+
+<script type="module">
+  const flow = document.getElementById('pipeline');
+  flow.nodes = [
+    {
+      id: 'input', x: 40, y: 40, label: 'User Input',
+      type: 'trigger', color: 'rgb(22 163 74)',
+      outputs: [{ id: 'data', label: 'Data' }],
+    },
+    {
+      id: 'validate', x: 280, y: 40, label: 'Validate',
+      type: 'transform', color: 'rgb(37 99 235)',
+      inputs: [{ id: 'in', label: 'Input' }],
+      outputs: [{ id: 'valid', label: 'Valid' }, { id: 'error', label: 'Error' }],
+    },
+    {
+      id: 'save', x: 520, y: 40, label: 'Save to DB',
+      type: 'action', color: 'rgb(147 51 234)',
+      inputs: [{ id: 'data', label: 'Data' }],
+    },
+  ];
+  flow.edges = [
+    { id: 'e1', source: 'input', target: 'validate',
+      sourcePort: 'data', targetPort: 'in' },
+    { id: 'e2', source: 'validate', target: 'save',
+      sourcePort: 'valid', targetPort: 'data' },
+  ];
+</script>
+```
+
+### Animated Edges
+
+Add `animated: true` to an edge for a flowing dashed animation:
+
+```javascript
+flow.edges = [
+  { id: 'e1', source: 'a', target: 'b',
+    sourcePort: 'out', targetPort: 'in',
+    animated: true, color: 'rgb(220 38 38)' },
+];
+```
+
+### Programmatic API
+
+```javascript
+// Add nodes and edges dynamically
+flow.addNode({
+  id: 'new-node', x: 200, y: 200, label: 'New Node',
+  inputs: [{ id: 'in', label: 'In' }],
+  outputs: [{ id: 'out', label: 'Out' }],
+});
+
+flow.addEdge({
+  id: 'new-edge', source: 'start', target: 'new-node',
+  sourcePort: 'out', targetPort: 'in',
+});
+
+// Remove
+flow.removeNode('new-node'); // also removes connected edges
+flow.removeEdge('new-edge');
+
+// Fit all nodes into view
+flow.fitView();
+```
+
+### Drawing Edges
+
+Users can create connections by clicking and dragging from a port dot on one node to a port dot on another node. A preview bezier curve shows while dragging.
+
+## Properties
+
+| Property | Type | Default | Attribute | Description |
+|----------|------|---------|-----------|-------------|
+| `nodes` | `FlowNode[]` | `[]` | - | Array of node definitions (set via JS) |
+| `edges` | `FlowEdge[]` | `[]` | - | Array of edge definitions (set via JS) |
+| `snapToGrid` | `boolean` | `true` | `snap-to-grid` | Snap node positions to grid |
+| `gridSize` | `number` | `20` | `grid-size` | Grid spacing in pixels |
+| `zoomEnabled` | `boolean` | `true` | `zoom-enabled` | Enable mouse wheel zoom |
+| `panEnabled` | `boolean` | `true` | `pan-enabled` | Enable background pan |
+| `minimap` | `boolean` | `true` | `minimap` | Show minimap overview |
+| `editable` | `boolean` | `true` | `editable` | Allow drawing new edges |
+
+## Types
+
+```typescript
+interface FlowNode {
+  id: string;
+  x: number;
+  y: number;
+  type?: string;                    // Shown as small label above title
+  data?: Record<string, unknown>;   // Custom data payload
+  label?: string;                   // Node title
+  width?: number;                   // Default: 160
+  height?: number;                  // Default: 80
+  inputs?: FlowPort[];              // Input ports (left side)
+  outputs?: FlowPort[];             // Output ports (right side)
+  color?: string;                   // Header background color
+  selected?: boolean;
+}
+
+interface FlowPort {
+  id: string;
+  label?: string;
+  type?: string;
+}
+
+interface FlowEdge {
+  id: string;
+  source: string;          // Source node id
+  target: string;          // Target node id
+  sourcePort?: string;     // Source port id
+  targetPort?: string;     // Target port id
+  label?: string;          // Edge label (shown at midpoint)
+  color?: string;          // Custom stroke color
+  animated?: boolean;      // Dashed animated stroke
+}
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `addNode(node)` | Add a node to the canvas |
+| `removeNode(id)` | Remove a node and its connected edges |
+| `addEdge(edge)` | Add an edge between two ports |
+| `removeEdge(id)` | Remove an edge |
+| `fitView()` | Auto-zoom to fit all nodes in view |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `node-drag` | `{ node, x, y }` | Node was dragged to new position |
+| `node-select` | `{ node }` | Node selected (null when deselected) |
+| `edge-connect` | `{ edge }` | New edge created by dragging between ports |
+| `edge-disconnect` | `{ edge }` | Edge removed |
+| `canvas-click` | `{ x, y }` | Background canvas clicked |
+
+## Interaction
+
+- **Drag nodes**: Click and drag a node to move it. Snaps to grid if enabled.
+- **Draw edges**: Click and drag from a port dot to another port dot.
+- **Pan canvas**: Click and drag on the background.
+- **Zoom**: Mouse wheel to zoom in/out around cursor.
+- **Select node**: Click a node to select it (blue highlight).
+- **Select edge**: Click an edge to select it.
+- **Deselect**: Click on the canvas background.
+
+## CSS Custom Properties
+
+The component uses standard snice theme tokens with fallbacks. Override with custom properties on the host element.

package/docs/components/funnel.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/funnel.md instead)
+
 # Funnel Component
 
 The funnel component renders an SVG-based funnel/conversion chart, ideal for visualizing pipeline stages, conversion funnels, and drop-off analysis. Each stage is rendered as a trapezoid shape that narrows proportionally to its value.

package/docs/components/gantt.md

@@ -0,0 +1,187 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/gantt.md instead)
+
+# Gantt Component
+
+The Gantt component displays an interactive Gantt chart for project timeline visualization. It features draggable and resizable task bars, multiple zoom levels, task grouping, progress indicators, dependency arrows, and a today line.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-gantt></snice-gantt>
+```
+
+```typescript
+import 'snice/components/gantt/snice-gantt';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tasks` | `GanttTask[]` | `[]` | Array of task objects (set via JavaScript) |
+| `zoom` | `'day' \| 'week' \| 'month'` | `'week'` | Timeline zoom level |
+| `showDependencies` (attr: `show-dependencies`) | `boolean` | `true` | Render dependency arrows between tasks |
+
+### GanttTask Type
+
+```typescript
+interface GanttTask {
+  id: string;
+  name: string;
+  start: string;          // ISO date (YYYY-MM-DD)
+  end: string;            // ISO date (YYYY-MM-DD)
+  progress?: number;      // 0-100 completion percentage
+  dependencies?: string[];// IDs of prerequisite tasks
+  color?: string;         // Bar color override
+  group?: string;         // Group name for visual grouping
+}
+```
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `scrollToDate()` | `date: string` | Scroll the timeline to center on a specific date (ISO format) |
+| `scrollToTask()` | `id: string` | Scroll the timeline to a specific task's start date |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `task-click` | `{ task: GanttTask }` | Fired when a task bar or task name is clicked |
+| `task-resize` | `{ task: GanttTask, start: string, end: string }` | Fired when a task is resized by dragging its left or right handles |
+| `task-move` | `{ task: GanttTask, start: string, end: string }` | Fired when a task bar is dragged to a new position |
+| `task-link` | `{ source: string, target: string }` | Fired when a dependency link is created between tasks |
+
+## Examples
+
+### Basic Project Timeline
+
+Display a simple list of tasks on a weekly timeline.
+
+```html
+<snice-gantt id="project-gantt" zoom="week"></snice-gantt>
+
+<script type="module">
+  import 'snice/components/gantt/snice-gantt';
+
+  const gantt = document.getElementById('project-gantt');
+  gantt.tasks = [
+    { id: '1', name: 'Research', start: '2026-03-01', end: '2026-03-05', progress: 100 },
+    { id: '2', name: 'Design', start: '2026-03-03', end: '2026-03-10', progress: 75 },
+    { id: '3', name: 'Development', start: '2026-03-08', end: '2026-03-21', progress: 30 },
+    { id: '4', name: 'Testing', start: '2026-03-18', end: '2026-03-25', progress: 0 },
+    { id: '5', name: 'Launch', start: '2026-03-25', end: '2026-03-27', progress: 0 }
+  ];
+</script>
+```
+
+### Grouped Tasks with Dependencies
+
+Use the `group` field to visually group related tasks and `dependencies` to draw arrows between them.
+
+```html
+<snice-gantt id="grouped-gantt" zoom="week" show-dependencies></snice-gantt>
+
+<script type="module">
+  const gantt = document.getElementById('grouped-gantt');
+  gantt.tasks = [
+    { id: '1', name: 'Requirements', start: '2026-04-01', end: '2026-04-05', progress: 100, group: 'Planning' },
+    { id: '2', name: 'Architecture', start: '2026-04-03', end: '2026-04-08', progress: 80, group: 'Planning', dependencies: ['1'] },
+    { id: '3', name: 'Frontend', start: '2026-04-08', end: '2026-04-18', progress: 40, group: 'Development', dependencies: ['2'] },
+    { id: '4', name: 'Backend', start: '2026-04-08', end: '2026-04-20', progress: 35, group: 'Development', dependencies: ['2'] },
+    { id: '5', name: 'Integration', start: '2026-04-18', end: '2026-04-25', progress: 0, group: 'QA', dependencies: ['3', '4'] },
+    { id: '6', name: 'Release', start: '2026-04-25', end: '2026-04-28', progress: 0, group: 'QA', dependencies: ['5'] }
+  ];
+</script>
+```
+
+### Custom Task Colors
+
+Use the `color` field on individual tasks to override the default bar color.
+
+```html
+<snice-gantt id="colored-gantt" zoom="week"></snice-gantt>
+
+<script type="module">
+  const gantt = document.getElementById('colored-gantt');
+  gantt.tasks = [
+    { id: '1', name: 'Critical Path', start: '2026-05-01', end: '2026-05-10', color: 'rgb(220 38 38)', progress: 50 },
+    { id: '2', name: 'Normal Task', start: '2026-05-03', end: '2026-05-12', progress: 25 },
+    { id: '3', name: 'Milestone', start: '2026-05-08', end: '2026-05-09', color: 'rgb(234 88 12)', progress: 0 },
+    { id: '4', name: 'Low Priority', start: '2026-05-10', end: '2026-05-20', color: 'rgb(22 163 74)', progress: 10 }
+  ];
+</script>
+```
+
+### Zoom Levels
+
+Toggle between day, week, and month views using the `zoom` property or the built-in header toggle buttons.
+
+```html
+<snice-gantt id="zoom-gantt" zoom="month"></snice-gantt>
+
+<div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
+  <button onclick="document.getElementById('zoom-gantt').zoom = 'day'">Day</button>
+  <button onclick="document.getElementById('zoom-gantt').zoom = 'week'">Week</button>
+  <button onclick="document.getElementById('zoom-gantt').zoom = 'month'">Month</button>
+</div>
+
+<script type="module">
+  const gantt = document.getElementById('zoom-gantt');
+  gantt.tasks = [
+    { id: '1', name: 'Phase 1', start: '2026-01-01', end: '2026-03-31', progress: 100, group: 'H1' },
+    { id: '2', name: 'Phase 2', start: '2026-04-01', end: '2026-06-30', progress: 60, group: 'H1' },
+    { id: '3', name: 'Phase 3', start: '2026-07-01', end: '2026-09-30', progress: 10, group: 'H2' },
+    { id: '4', name: 'Phase 4', start: '2026-10-01', end: '2026-12-31', progress: 0, group: 'H2' }
+  ];
+</script>
+```
+
+### Event Handling
+
+Listen for task interactions to update your application state or sync with a backend.
+
+```html
+<snice-gantt id="event-gantt" zoom="week" show-dependencies></snice-gantt>
+
+<script type="module">
+  const gantt = document.getElementById('event-gantt');
+  gantt.tasks = [
+    { id: '1', name: 'Design', start: '2026-03-01', end: '2026-03-07', progress: 80 },
+    { id: '2', name: 'Develop', start: '2026-03-05', end: '2026-03-15', dependencies: ['1'] }
+  ];
+
+  gantt.addEventListener('task-click', (e) => {
+    console.log('Clicked task:', e.detail.task.name);
+  });
+
+  gantt.addEventListener('task-move', (e) => {
+    console.log('Moved task:', e.detail.task.name, 'to', e.detail.start, '-', e.detail.end);
+  });
+
+  gantt.addEventListener('task-resize', (e) => {
+    console.log('Resized task:', e.detail.task.name, 'new dates:', e.detail.start, '-', e.detail.end);
+  });
+
+  // Scroll to a specific date on load
+  gantt.scrollToDate('2026-03-01');
+</script>
+```
+
+## Accessibility
+
+- **Draggable tasks**: Task bars can be dragged to move their dates and resized via left/right edge handles
+- **Today indicator**: A red vertical line marks the current date on the timeline
+- **Zoom controls**: The header provides Day/Week/Month toggle buttons for quick zoom changes
+- **Task grouping**: Tasks with the same `group` value are visually grouped in the sidebar for organization
+- **Progress indicators**: Each task bar displays a filled portion representing its completion percentage
+- **Dependency arrows**: When `show-dependencies` is enabled, arrows connect tasks to their prerequisites

package/docs/components/gauge.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/gauge.md instead)
+
 # Gauge Component
 
 The gauge component renders an SVG-based semicircle gauge/meter chart, ideal for dashboards and data visualization. It displays a value within a range using an animated arc fill with optional label text.

package/docs/components/heatmap.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/heatmap.md instead)
+
 # Heatmap Component
 
 The heatmap component displays a GitHub-style contribution calendar heatmap. It visualizes data as a grid of colored cells organized by week and day, with intensity levels indicating the magnitude of each data point.

package/docs/components/image.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/image.md instead)
+
 # Image Component
 
 The `<snice-image>` component provides a flexible image display with variants, sizes, lazy loading, and fallback support.