snice 4.8.0 → 4.10.0

package/docs/components/divider.md

@@ -0,0 +1,132 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/divider.md instead)
+
+# Divider
+`<snice-divider>`
+
+Separator line with optional text label.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/divider/snice-divider';
+```
+
+```html
+<snice-divider></snice-divider>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/divider/snice-divider';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-divider.min.js"></script>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the line style.
+
+```html
+<snice-divider variant="solid"></snice-divider>
+<snice-divider variant="dashed"></snice-divider>
+<snice-divider variant="dotted"></snice-divider>
+```
+
+### With Text
+
+Use the `text` attribute to add a label to the divider.
+
+```html
+<snice-divider text="OR"></snice-divider>
+<snice-divider text="Section Title"></snice-divider>
+```
+
+### Text Alignment
+
+Use the `align` attribute to position the text label.
+
+```html
+<snice-divider text="Start" align="start"></snice-divider>
+<snice-divider text="Center" align="center"></snice-divider>
+<snice-divider text="End" align="end"></snice-divider>
+```
+
+### Text Background
+
+Use the `text-background` attribute to set the background behind the text label, useful when placed over colored backgrounds.
+
+```html
+<snice-divider text="Section" text-background="#ffffff"></snice-divider>
+```
+
+### Spacing
+
+Use the `spacing` attribute to control vertical margin around the divider.
+
+```html
+<snice-divider spacing="none"></snice-divider>
+<snice-divider spacing="small"></snice-divider>
+<snice-divider spacing="medium"></snice-divider>
+<snice-divider spacing="large"></snice-divider>
+```
+
+### Vertical Orientation
+
+Set `orientation` to `vertical` for use in horizontal layouts.
+
+```html
+<div style="display: flex; align-items: center; height: 50px; gap: 1rem;">
+  <span>Left</span>
+  <snice-divider orientation="vertical"></snice-divider>
+  <span>Right</span>
+</div>
+```
+
+### Custom Color
+
+Use the `color` attribute to change the divider color.
+
+```html
+<snice-divider color="#3b82f6"></snice-divider>
+<snice-divider color="rgb(22 163 74)"></snice-divider>
+```
+
+### Capped Ends
+
+Set the `capped` attribute for rounded line ends.
+
+```html
+<snice-divider capped></snice-divider>
+<snice-divider capped variant="dashed"></snice-divider>
+```
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Divider direction |
+| `variant` | `variant` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | Line style |
+| `spacing` | `spacing` | `'none' \| 'small' \| 'medium' \| 'large'` | `'medium'` | Vertical margin |
+| `align` | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Text position |
+| `text` | `text` | `string` | `''` | Text label content |
+| `textBackground` | `text-background` | `string` | `''` | Text label background color |
+| `color` | `color` | `string` | `''` | Custom divider color |
+| `capped` | `capped` | `boolean` | `false` | Rounded line ends |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--divider-color` | Line color | `var(--snice-color-border)` |
+| `--divider-thickness` | Line thickness | `1px` |
+| `--divider-text-bg` | Text label background | `transparent` |
+| `--divider-text-padding` | Text label padding | `0 1rem` |
+| `--divider-text-gap` | Gap around text label | `1rem` |

package/docs/components/doc.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/doc.md instead)
+
 # snice-doc
 
 A simple WYSIWYG document editor component with formatting toolbar and content insertion capabilities.

package/docs/components/draw.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/draw.md instead)
+
 # Draw Component
 
 Canvas drawing with smooth lazy-brush technology.

package/docs/components/drawer.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/drawer.md instead)
+
 # Drawer Component
 
 The `<snice-drawer>` component provides a slide-out panel that appears from any side of the viewport. It's commonly used for navigation menus, filters, settings panels, or additional content that shouldn't occupy permanent screen space.

package/docs/components/empty-state.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/empty-state.md instead)
+
 # Empty State Component
 
 The `<snice-empty-state>` component provides a consistent way to display empty or no-data states.

package/docs/components/file-gallery.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/file-gallery.md instead)
+
 # File Gallery Component
 
 The `<snice-file-gallery>` component provides a file upload gallery with drag-and-drop support, image previews, pausable/resumable uploads, and progress tracking.

package/docs/components/file-upload.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/file-upload.md instead)
+
 # File Upload Component
 
 The `<snice-file-upload>` component provides a file upload interface with drag-and-drop support, file previews, and validation.

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.