snice 4.9.0 → 4.10.0

package/docs/ai/components/comments.md

@@ -0,0 +1,75 @@
+# snice-comments
+
+Threaded comment system with replies, likes, avatars, and real-time relative timestamps.
+
+## Properties
+
+```ts
+comments: Comment[] = []        // Array of comment objects (set via JS)
+currentUser: string = ''        // attr: current-user — name of logged-in user (enables delete on own comments)
+allowReplies: boolean = true    // attr: allow-replies — enable nested replies
+allowLikes: boolean = true      // attr: allow-likes — enable like/unlike
+maxDepth: number = 3            // attr: max-depth — max nesting depth for replies
+```
+
+## Types
+
+```ts
+interface Comment {
+  id: string;
+  author: string;
+  avatar?: string;       // URL for avatar image
+  text: string;
+  timestamp: string;     // ISO date string
+  replies?: Comment[];
+  likes?: number;
+  liked?: boolean;
+}
+```
+
+## Events
+
+- `comment-add` -> `{ id: string, text: string, author: string }`
+- `comment-reply` -> `{ id: string, text: string, author: string, parentId: string }`
+- `comment-delete` -> `{ id: string }`
+- `comment-like` -> `{ id: string, likes: number, liked: boolean }`
+
+## Methods
+
+- `addComment(text: string, parentId?: string): void` — Add top-level or reply comment
+- `deleteComment(id: string): void` — Remove a comment by ID
+- `likeComment(id: string): void` — Toggle like on a comment
+
+## CSS Custom Properties
+
+```css
+--comments-bg             /* Background color */
+--comments-border         /* Border color */
+--comments-text           /* Primary text */
+--comments-text-secondary /* Author name, secondary text */
+--comments-text-tertiary  /* Timestamps, placeholders */
+--comments-primary        /* Submit button, active like color */
+--comments-danger         /* Delete action hover color */
+--comments-bg-element     /* Avatar background, hover states */
+```
+
+## CSS Parts
+
+- `base` — Root container
+- `input-area` — New comment input area
+- `list` — Comments list container
+
+## Usage
+
+```html
+<snice-comments current-user="Alice" allow-replies max-depth="3"></snice-comments>
+```
+
+```js
+const comments = document.querySelector('snice-comments');
+comments.comments = [
+  { id: '1', author: 'Bob', text: 'Great post!', timestamp: '2026-02-20T10:00:00Z', likes: 3 },
+  { id: '2', author: 'Alice', text: 'Thanks!', timestamp: '2026-02-20T11:00:00Z', likes: 0 }
+];
+comments.addEventListener('comment-add', e => console.log(e.detail));
+```

package/docs/ai/components/countdown.md

@@ -0,0 +1,54 @@
+# snice-countdown
+
+Countdown timer to a target date with multiple display formats and visual variants.
+
+## Properties
+
+```ts
+target: string = ''                           // attr: target — ISO date string to count down to
+format: CountdownFormat = 'dhms'              // attr: format — 'dhms' | 'hms' | 'ms'
+variant: CountdownVariant = 'simple'          // attr: variant — 'simple' | 'flip' | 'circular'
+```
+
+## Events
+
+- `countdown-complete` -> `void` — Fires when countdown reaches zero
+- `countdown-tick` -> `{ days: number, hours: number, minutes: number, seconds: number, total: number }` — Fires every second
+
+## CSS Custom Properties
+
+Uses standard snice design tokens:
+
+```css
+--snice-font-family
+--snice-font-size-2xl      /* Digit size */
+--snice-font-size-xs       /* Label size */
+--snice-color-text         /* Digit color */
+--snice-color-text-secondary /* Label color */
+--snice-color-text-tertiary  /* Separator color */
+--snice-color-background-element /* Flip variant card bg */
+--snice-color-border       /* Flip variant border */
+--snice-color-primary      /* Circular variant ring color */
+--snice-color-success      /* Complete state color */
+```
+
+## Behavior
+
+- Ticks every second, auto-stops on completion
+- Adds `.complete` class to host when finished
+- `format` controls which segments display:
+  - `dhms`: Days, Hours, Min, Sec
+  - `hms`: Hours, Min, Sec
+  - `ms`: Min, Sec
+
+## Usage
+
+```html
+<snice-countdown target="2026-12-31T00:00:00Z" format="dhms" variant="flip"></snice-countdown>
+```
+
+```js
+const cd = document.querySelector('snice-countdown');
+cd.addEventListener('countdown-complete', () => alert('Done!'));
+cd.addEventListener('countdown-tick', e => console.log(e.detail.total));
+```

package/docs/ai/components/cropper.md

@@ -0,0 +1,57 @@
+# snice-cropper
+
+Image cropping component with draggable/resizable crop area, rotation, zoom, aspect ratio lock, and rule-of-thirds grid.
+
+## Properties
+
+```ts
+src: string = ''                              // attr: src — Image URL to crop
+aspectRatio: number = 0                       // attr: aspect-ratio — Lock ratio (0 = free, e.g. 1.777 for 16:9)
+minWidth: number = 20                         // attr: min-width — Min crop width in px
+minHeight: number = 20                        // attr: min-height — Min crop height in px
+outputType: CropperOutputType = 'png'         // attr: output-type — 'png' | 'jpeg' | 'webp'
+```
+
+## Events
+
+- `crop-change` -> `{ rect: { x: number, y: number, width: number, height: number } }` — Fires on crop area move/resize
+- `crop-complete` -> `{ blob: Blob | null }` — Fires after `crop()` produces output
+
+## Methods
+
+- `crop(): Promise<Blob | null>` — Produce cropped image blob
+- `rotate(degrees: number): void` — Rotate image by degrees (cumulative)
+- `zoom(level: number): void` — Set zoom level (0.1 to 10)
+- `reset(): void` — Reset rotation, zoom, and crop area to defaults
+
+## CSS Custom Properties
+
+```css
+--snice-color-background-element  /* Container background */
+--snice-color-border              /* Container border */
+--snice-border-radius-lg          /* Container radius */
+```
+
+## Behavior
+
+- Crop area is draggable (move) and resizable via 8 corner/edge handles
+- Rule-of-thirds grid overlay on crop area
+- Dark mask outside crop area
+- Aspect ratio enforced on resize when `aspectRatio > 0`
+
+## Usage
+
+```html
+<snice-cropper src="/photo.jpg" aspect-ratio="1" output-type="jpeg"></snice-cropper>
+```
+
+```js
+const cropper = document.querySelector('snice-cropper');
+const blob = await cropper.crop();
+
+// Rotate 90 degrees clockwise
+cropper.rotate(90);
+
+// Zoom in
+cropper.zoom(1.5);
+```

package/docs/ai/components/date-picker.md

@@ -20,9 +20,10 @@ max: string = '';              // Max date (ISO format)
 size: 'small'|'medium'|'large' = 'medium';
 name: string = '';
 label: string = '';
-helperText: string = '';
-errorText: string = '';
-firstDayOfWeek: number = 0;    // 0=Sun, 1=Mon, etc.
+helperText: string = '';       // attribute: helper-text
+errorText: string = '';        // attribute: error-text
+showCalendar: boolean = false; // attribute: show-calendar
+firstDayOfWeek: number = 0;    // attribute: first-day-of-week, 0=Sun, 1=Mon, etc.
 ```
 
 ## Methods
@@ -35,15 +36,20 @@ firstDayOfWeek: number = 0;    // 0=Sun, 1=Mon, etc.
 - `selectDate(date: Date)` - Programmatically select a date
 - `goToMonth(year, month)` - Navigate to specific month
 - `goToToday()` - Navigate to and select today
+- `checkValidity()` - Check input validity
+- `reportValidity()` - Report input validity
+- `setCustomValidity(message)` - Set custom validation message
 
 ## Events
 
-- `datepicker-change` - {value, date, formatted, iso, datePicker}
-- `datepicker-input` - {value, datePicker}
-- `datepicker-open` - {datePicker}
-- `datepicker-close` - {datePicker}
-- `datepicker-clear` - {datePicker}
-- `datepicker-select` - {date, formatted, iso, datePicker}
+- `datepicker-input` → {value, datePicker}
+- `datepicker-change` → {value, date, formatted, iso, datePicker}
+- `datepicker-focus` → {datePicker}
+- `datepicker-blur` → {datePicker}
+- `datepicker-open` → {datePicker}
+- `datepicker-close` → {datePicker}
+- `datepicker-clear` → {datePicker}
+- `datepicker-select` → {date, formatted, iso, datePicker}
 
 ## Usage
 

package/docs/ai/components/diff.md

@@ -0,0 +1,66 @@
+# snice-diff
+
+Text diff viewer with unified and split (side-by-side) modes, line numbers, collapsible unchanged sections, and addition/deletion stats.
+
+## Properties
+
+```ts
+oldText: string = ''             // attr: old-text — Original text
+newText: string = ''             // attr: new-text — Modified text
+language: string = ''            // attr: language — Language hint (for future syntax highlighting)
+mode: DiffMode = 'unified'      // attr: mode — 'unified' | 'split'
+lineNumbers: boolean = true      // attr: line-numbers — Show line number gutters
+contextLines: number = 3         // attr: context-lines — Unchanged lines shown around changes
+markers: boolean = true          // attr: markers — Show +/- markers column
+```
+
+## Events
+
+- `diff-computed` -> `{ hunks: DiffHunk[], additions: number, deletions: number }` — Fires after diff is calculated
+
+## Types
+
+```ts
+interface DiffLine {
+  type: 'added' | 'removed' | 'unchanged';
+  oldLine: number | null;
+  newLine: number | null;
+  content: string;
+}
+
+interface DiffHunk {
+  lines: DiffLine[];
+  collapsed: boolean;
+}
+```
+
+## CSS Custom Properties
+
+```css
+--snice-diff-added-bg          /* Added line background */
+--snice-diff-removed-bg        /* Removed line background */
+--snice-diff-added-word-bg     /* Word-level added highlight */
+--snice-diff-removed-word-bg   /* Word-level removed highlight */
+```
+
+## Behavior
+
+- LCS-based diff algorithm computes on `oldText`/`newText`/`contextLines` change
+- Unchanged sections beyond context are collapsed; click to expand
+- Header shows +N/-N stats and unified/split toggle buttons
+- Dark mode support via `[data-theme="dark"]` or `prefers-color-scheme: dark`
+
+## Usage
+
+```html
+<snice-diff old-text="hello world" new-text="hello there" mode="unified" context-lines="3"></snice-diff>
+```
+
+```js
+const diff = document.querySelector('snice-diff');
+diff.oldText = originalCode;
+diff.newText = modifiedCode;
+diff.addEventListener('diff-computed', e => {
+  console.log(`+${e.detail.additions} -${e.detail.deletions}`);
+});
+```

package/docs/ai/components/divider.md

@@ -10,7 +10,7 @@ variant: 'solid'|'dashed'|'dotted' = 'solid';
 spacing: 'none'|'small'|'medium'|'large' = 'medium';
 align: 'start'|'center'|'end' = 'center';
 text: string = '';
-textBackground: string = '';
+textBackground: string = '';   // attribute: text-background
 color: string = '';
 capped: boolean = false;
 ```

package/docs/ai/components/draw.md

@@ -9,14 +9,14 @@ width: number = 800;
 height: number = 600;
 tool: 'pen'|'eraser'|'line'|'rectangle'|'circle'|'text' = 'pen';
 color: string = '#000000';
-strokeWidth: number = 2;
-backgroundColor: string = '#ffffff';
+strokeWidth: number = 2;           // attribute: stroke-width
+backgroundColor: string = '#ffffff'; // attribute: background-color
 lazy: boolean = false;
-lazyRadius: number = 60;
+lazyRadius: number = 60;           // attribute: lazy-radius
 friction: number = 0.1;
 smoothing: number = 0.5;
-autoPolygon: boolean = false;
-polygonCurvePoints: number = 10;
+autoPolygon: boolean = false;      // attribute: auto-polygon
+polygonCurvePoints: number = 10;   // attribute: polygon-curve-points
 disabled: boolean = false;
 ```
 

package/docs/ai/components/drawer.md

@@ -8,12 +8,12 @@ Slide-out panel from any viewport side with focus trap and dismissal options.
 open: boolean = false;                         // Visibility state
 position: 'left'|'right'|'top'|'bottom' = 'left';
 size: 'small'|'medium'|'large'|'xl'|'xxl'|'xxxl'|'full' = 'medium';
-noBackdrop: boolean = false;                   // Hide backdrop overlay
-noBackdropDismiss: boolean = false;            // Prevent backdrop click close
-noEscapeDismiss: boolean = false;              // Prevent Escape key close
-noFocusTrap: boolean = false;                  // Disable focus trapping
+noBackdrop: boolean = false;                   // attribute: no-backdrop
+noBackdropDismiss: boolean = false;            // attribute: no-backdrop-dismiss
+noEscapeDismiss: boolean = false;              // attribute: no-escape-dismiss
+noFocusTrap: boolean = false;                  // attribute: no-focus-trap
 persistent: boolean = false;                   // Hide close button, prevent all dismiss
-pushContent: boolean = false;                  // Push main content instead of overlay
+pushContent: boolean = false;                  // attribute: push-content
 contained: boolean = false;                    // Position relative to parent
 ```
 

package/docs/ai/components/empty-state.md

@@ -9,8 +9,8 @@ size: 'small'|'medium'|'large' = 'medium';
 icon: string = '📭';
 title: string = 'No data';
 description: string = '';
-actionText: string = '';
-actionHref: string = '';
+actionText: string = '';       // attribute: action-text
+actionHref: string = '';       // attribute: action-href
 ```
 
 ## Slots

package/docs/ai/components/file-gallery.md

@@ -8,16 +8,16 @@ File upload gallery with drag-and-drop, preview, pausable/resumable uploads.
 accept: string = '';
 multiple: boolean = true;
 disabled: boolean = false;
-maxSize: number = -1; // bytes, -1 = no limit
-maxFiles: number = -1; // -1 = no limit
+maxSize: number = -1;          // attribute: max-size, bytes, -1 = no limit
+maxFiles: number = -1;         // attribute: max-files, -1 = no limit
 view: 'grid'|'list' = 'grid';
-showProgress: boolean = true;
-allowPause: boolean = true;
-allowDelete: boolean = true;
-autoUpload: boolean = true;
-showDropzone: boolean = true; // show drop zone for drag & drop
-showAddButton: boolean = false; // show add button tile in gallery
-showHeader: boolean = true; // show gallery header
+showProgress: boolean = true;  // attribute: show-progress
+allowPause: boolean = true;    // attribute: allow-pause
+allowDelete: boolean = true;   // attribute: allow-delete
+autoUpload: boolean = true;    // attribute: auto-upload
+showDropzone: boolean = true;  // attribute: show-dropzone
+showAddButton: boolean = false; // attribute: show-add-button
+showHeader: boolean = true;    // attribute: show-header
 files: GalleryFile[]; // read-only
 ```
 
@@ -108,31 +108,7 @@ interface UploadResponse {
 
 ## Upload Handler
 
-Uses `@request/@respond` pattern. Handler required:
-
-```typescript
-import { respond } from 'snice';
-
-class UploadController {
-  @respond('file-gallery-upload')
-  async handleUpload(request: UploadRequest): Promise<UploadResponse> {
-    const { file, fileId, onProgress, signal } = request;
-
-    // Implement upload logic
-    // Use onProgress(0-1) for progress tracking
-    // Check signal.aborted for cancellation
-
-    return {
-      success: true,
-      fileId,
-      url: 'https://example.com/file.jpg'
-    };
-  }
-}
-
-const controller = new UploadController();
-controller.attach?.(document.body);
-```
+Uses `@request/@respond` pattern (`file-gallery-upload`). Handler receives `UploadRequest`, returns `UploadResponse`.
 
 ## Usage
 
@@ -152,59 +128,12 @@ controller.attach?.(document.body);
 <!-- List view -->
 <snice-file-gallery view="list"></snice-file-gallery>
 
-<!-- Custom options -->
-<snice-file-gallery
-  accept=".pdf,.doc,.docx"
-  allow-pause="false"
-></snice-file-gallery>
-
-<!-- Add button mode (hide drop zone, show add tile) -->
-<snice-file-gallery
-  show-dropzone="false"
-  show-add-button="true"
-  max-files="6"
-></snice-file-gallery>
-
-<!-- Custom actions -->
-<snice-file-gallery id="gallery"></snice-file-gallery>
+<!-- Add button mode -->
+<snice-file-gallery show-dropzone="false" show-add-button="true" max-files="6"></snice-file-gallery>
+
+<!-- Events -->
 <script>
-const gallery = document.querySelector('#gallery');
-
-// Add custom action
-const icon = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">...</svg>';
-const actionId = gallery.addCustomAction(icon, 'Camera');
-
-// Handle custom action
-gallery.addEventListener('custom-action-click', (e) => {
-  if (e.detail.actionId === actionId) {
-    // Handle camera action
-    const file = capturePhoto(); // your implementation
-    gallery.addFileWithPreview(file, previewUrl);
-  }
-});
-
-// Other events
-gallery.addEventListener('files-change', (e) => {
-  console.log('Files:', e.detail.files);
-});
-gallery.addEventListener('upload-complete', (e) => {
-  console.log('Complete:', e.detail.url);
-});
-
-// Add custom badge (e.g., user avatar)
-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(fileId, avatarHTML, 'top-right');
+gallery.addEventListener('files-change', (e) => console.log(e.detail.files));
+gallery.addEventListener('upload-complete', (e) => console.log(e.detail.url));
 </script>
 ```
-
-## Features
-
-- Drag-and-drop with visual feedback
-- Image preview thumbnails
-- Pausable/resumable uploads via AbortController
-- Real-time progress tracking
-- Grid/list view toggle
-- File validation (size, type)
-- Auto or manual upload modes
-- @request/@respond upload pattern
-- Accessible

package/docs/ai/components/file-upload.md

@@ -13,13 +13,13 @@ disabled: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 label: string = '';
-helperText: string = '';
-errorText: string = '';
-maxSize: number = -1; // bytes
-maxFiles: number = -1;
+helperText: string = '';       // attribute: helper-text
+errorText: string = '';        // attribute: error-text
+maxSize: number = -1;          // attribute: max-size, bytes
+maxFiles: number = -1;         // attribute: max-files
 name: string = '';
-dragDrop: boolean = true;
-showPreview: boolean = true;
+dragDrop: boolean = true;      // attribute: drag-drop
+showPreview: boolean = true;   // attribute: show-preview
 files: FileList | null;
 ```
 

package/docs/ai/components/flip-card.md

@@ -0,0 +1,52 @@
+# snice-flip-card
+
+3D card flip component with front/back faces, horizontal/vertical flip direction, and click or programmatic control.
+
+## Properties
+
+```ts
+flipped: boolean = false                 // attr: flipped — Whether back face is showing
+clickToFlip: boolean = true              // attr: click-to-flip — Enable click/keyboard to toggle
+direction: FlipDirection = 'horizontal'  // attr: direction — 'horizontal' | 'vertical'
+duration: number = 600                   // attr: duration — Flip animation duration in ms
+```
+
+## Slots
+
+- `front` — Content for the front face
+- `back` — Content for the back face
+
+## Events
+
+- `flip-change` -> `{ flipped: boolean, side: 'front' | 'back' }` — Fires on flip state change
+
+## Methods
+
+- `flip(): void` — Toggle between front and back
+- `flipTo(side: 'front' | 'back'): void` — Flip to a specific side
+
+## CSS Custom Properties
+
+```css
+--flip-duration   /* Animation duration, set automatically from duration property */
+```
+
+## Keyboard
+
+When `click-to-flip` is enabled:
+- Enter / Space — Toggle flip
+
+## Usage
+
+```html
+<snice-flip-card direction="horizontal" style="width: 300px; height: 200px;">
+  <div slot="front">Front content</div>
+  <div slot="back">Back content</div>
+</snice-flip-card>
+```
+
+```js
+const card = document.querySelector('snice-flip-card');
+card.flipTo('back');
+card.addEventListener('flip-change', e => console.log(e.detail.side));
+```

package/docs/ai/components/flow.md

@@ -0,0 +1,104 @@
+# snice-flow
+
+Node-based flow/diagram editor with draggable nodes, input/output ports, bezier curve edges, zoom/pan canvas, snap-to-grid, and minimap.
+
+## Properties
+
+```typescript
+nodes: FlowNode[] = [];           // attribute: false (set via JS)
+edges: FlowEdge[] = [];           // attribute: false (set via JS)
+snapToGrid: boolean = true;       // attr: snap-to-grid
+gridSize: number = 20;            // attr: grid-size
+zoomEnabled: boolean = true;      // attr: zoom-enabled
+panEnabled: boolean = true;       // attr: pan-enabled
+minimap: boolean = true;
+editable: boolean = true;
+```
+
+## Types
+
+```typescript
+interface FlowNode {
+  id: string;
+  x: number;
+  y: number;
+  type?: string;
+  data?: Record<string, unknown>;
+  label?: string;
+  width?: number;        // default: 160
+  height?: number;       // default: 80
+  inputs?: FlowPort[];
+  outputs?: FlowPort[];
+  color?: string;        // header background color
+  selected?: boolean;
+}
+
+interface FlowPort {
+  id: string;
+  label?: string;
+  type?: string;
+}
+
+interface FlowEdge {
+  id: string;
+  source: string;        // node id
+  target: string;        // node id
+  sourcePort?: string;   // port id
+  targetPort?: string;   // port id
+  label?: string;
+  color?: string;
+  animated?: boolean;    // dashed animated stroke
+}
+```
+
+## Methods
+
+- `addNode(node: FlowNode): void`
+- `removeNode(id: string): void` - also removes connected edges
+- `addEdge(edge: FlowEdge): void`
+- `removeEdge(id: string): void`
+- `fitView(): void` - auto-zoom to fit all nodes
+
+## Events
+
+- `node-drag` -> `{ node: FlowNode, x: number, y: number }`
+- `node-select` -> `{ node: FlowNode | null }`
+- `edge-connect` -> `{ edge: FlowEdge }`
+- `edge-disconnect` -> `{ edge: FlowEdge }`
+- `canvas-click` -> `{ x: number, y: number }`
+
+## Usage
+
+```html
+<snice-flow id="flow" snap-to-grid minimap style="height:450px"></snice-flow>
+```
+
+```typescript
+const flow = document.getElementById('flow');
+flow.nodes = [
+  { id: 'a', x: 50, y: 50, label: 'Start',
+    outputs: [{ id: 'out', label: 'Out' }] },
+  { id: 'b', x: 300, y: 50, label: 'Process',
+    inputs: [{ id: 'in', label: 'In' }],
+    outputs: [{ id: 'out', label: 'Out' }] },
+];
+flow.edges = [
+  { id: 'e1', source: 'a', target: 'b',
+    sourcePort: 'out', targetPort: 'in' },
+];
+```
+
+## Features
+
+- Draggable nodes with snap-to-grid
+- Input/output ports on nodes
+- Bezier curve edges with arrow markers
+- Draw edges by dragging from port to port
+- Zoom (mouse wheel) and pan (drag background)
+- Node selection with visual highlight
+- Edge selection
+- Minimap showing viewport indicator
+- Dot grid background
+- Animated edge support (dashed flowing)
+- Custom node header colors
+- Responsive via ResizeObserver

package/docs/ai/components/funnel.md

@@ -8,9 +8,9 @@ SVG-based funnel chart for conversion tracking and pipeline visualization.
 data: FunnelStage[] = [];           // Array of { label, value, color? }
 variant: 'default'|'gradient' = 'default';
 orientation: 'vertical'|'horizontal' = 'vertical';
-showLabels: boolean = true;         // attribute: show-labels
-showValues: boolean = true;         // attribute: show-values
-showPercentages: boolean = true;    // attribute: show-percentages
+showLabels: boolean = true;          // attribute: show-labels
+showValues: boolean = true;          // attribute: show-values
+showPercentages: boolean = true;     // attribute: show-percentages
 animation: boolean = false;
 ```