snice 4.8.0 → 4.10.0

package/docs/ai/components/code-block.md

@@ -110,94 +110,15 @@ Load from `components/code-block/grammars/` (or `dist/components/code-block/gram
 - `bash.json` — Bash/Shell
 - `snice.json` — Snice (TypeScript + html``/css`` template highlighting)
 
-### Snice Grammar
-
-Extends TypeScript with awareness of snice's template DSL:
-- **`html\``** tagged templates → HTML mode with tag/attribute highlighting
-- **`css\``** tagged templates → CSS mode with property/selector highlighting
-- **`<if>`, `<case>`, `<when>`, `<default>`** → highlighted as keywords (not regular tags)
-- **`.prop=`** property bindings → "property" token
-- **`?attr=`** boolean bindings → "attr-name" token
-- **`@event=`** event bindings → "function" token (includes `@event:modifier` and `@event.modifier`)
-- **`${...}`** interpolations → back to TypeScript mode
-- Handles `html/*html*/\`` editor hint pattern
-
-### Loading Grammars
-
-```html
-<!-- Grammar from URL -->
-<snice-code-block grammar="grammars/typescript.json" language="typescript" id="cb"></snice-code-block>
-<script>
-  document.getElementById('cb').code = 'const x: number = 42;';
-</script>
-
-<!-- Inline grammar object -->
-<snice-code-block id="cb2" language="custom"></snice-code-block>
-<script>
-  document.getElementById('cb2').grammar = {
-    name: 'custom',
-    keywords: ['func', 'var', 'return'],
-    tokenizer: {
-      root: [
-        ['//.*$', 'comment'],
-        ['"[^"]*"', 'string'],
-        ['\\b\\d+\\b', 'number'],
-        ['[a-zA-Z_]\\w*', { cases: { '@keywords': 'keyword', '@default': '' } }]
-      ]
-    }
-  };
-  document.getElementById('cb2').code = 'func main() { return 42; }';
-</script>
-```
-
-### Programmatic Registration
-
-```typescript
-import { registerGrammar, unregisterGrammar, getGrammar } from 'snice/components/code-block/highlighter';
-
-// Register so language string lookup works
-const grammar = await fetch('grammars/typescript.json').then(r => r.json());
-registerGrammar('typescript', grammar);
-registerGrammar('ts', grammar);  // alias
-
-// Then use by name
-highlightCode(code, 'typescript');
-```
-
-### Grammar Format
-
-```typescript
-interface Grammar {
-  name: string;
-  fileTypes?: string[];
-  defaultToken?: string;
-  ignoreCase?: boolean;
-  tokenizer: Record<string, GrammarEntry[]>;
-  [key: string]: any;  // Lookup tables (keywords, builtins, etc.)
-}
-
-// Rule: [regex, token] | [regex, token, nextState] | { include: '@state' }
-// Token: string | { cases: { '@table': 'token', '@default': 'token' } }
-// State: '@stateName' (push) | '@pop' (return)
-```
-
-### Highlighter API (programmatic)
+### Highlighter API
 
 ```typescript
 import { highlightCode, tokenize, registerGrammar, unregisterGrammar, getGrammar } from 'snice/components/code-block/highlighter';
 
-highlightCode(code, grammarObject);      // Use grammar directly → HTML string
-highlightCode(code, 'myLang');           // Use registered grammar (or plaintext if not found)
-tokenize(code, grammarObject);           // Returns Token[]
-registerGrammar('myLang', grammar);      // Register grammar for name lookup
-unregisterGrammar('myLang');             // Remove registered grammar
-getGrammar('myLang');                    // Get registered grammar or undefined
+highlightCode(code, grammarOrName);  // → HTML string
+registerGrammar('myLang', grammar);  // Register for name lookup
 ```
 
-## Token CSS Classes
-
-`keyword`, `string`, `comment`, `tag`, `function`, `class-name`, `number`, `constant`, `attr-name`, `attr-value`, `property`, `operator`, `punctuation`, `builtin`, `regex`
-
 ## Usage
 
 ```html

package/docs/ai/components/color-display.md

@@ -7,9 +7,9 @@ Displays colors with swatch and label.
 ```typescript
 value: string = '';
 format: 'hex'|'rgb'|'hsl' = 'hex';
-showSwatch: boolean = true;
-showLabel: boolean = true;
-swatchSize: 'small'|'medium'|'large' = 'medium';
+showSwatch: boolean = true;      // attribute: show-swatch
+showLabel: boolean = true;       // attribute: show-label
+swatchSize: 'small'|'medium'|'large' = 'medium'; // attribute: swatch-size
 label: string = '';
 ```
 

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

@@ -9,14 +9,14 @@ value: string = '#000000';
 format: 'hex'|'rgb'|'hsl' = 'hex';
 size: 'small'|'medium'|'large' = 'medium';
 label: string = '';
-helperText: string = '';
-errorText: string = '';
+helperText: string = '';       // attribute: helper-text
+errorText: string = '';        // attribute: error-text
 disabled: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 name: string = '';
-showInput: boolean = true;
-showPresets: boolean = false;
+showInput: boolean = true;     // attribute: show-input
+showPresets: boolean = false;  // attribute: show-presets
 presets: string[] = [...];
 loading: boolean = false;
 ```

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;
 ```