snice 4.27.0 → 4.29.0

package/docs/ai/components/comments.md

@@ -1,24 +1,24 @@
 # snice-comments
 
-Threaded comment system with replies, likes, avatars, and real-time relative timestamps.
+Threaded comment system with replies, likes, avatars, and 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
+```typescript
+comments: Comment[] = [];          // Set via JS
+currentUser: string = '';          // attribute: current-user
+allowReplies: boolean = true;      // attribute: allow-replies
+allowLikes: boolean = true;        // attribute: allow-likes
+maxDepth: number = 3;              // attribute: max-depth
 ```
 
-## Types
+### Comment Type
 
-```ts
+```typescript
 interface Comment {
   id: string;
   author: string;
-  avatar?: string;       // URL for avatar image
+  avatar?: string;
   text: string;
   timestamp: string;     // ISO date string
   replies?: Comment[];
@@ -27,48 +27,67 @@ interface Comment {
 }
 ```
 
-## Events
+## Methods
 
-- `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 }`
+- `addComment(text: string, parentId?: string)` - Add top-level or reply comment
+- `deleteComment(id: string)` - Remove a comment by ID
+- `likeComment(id: string)` - Toggle like on a comment
 
-## Methods
+## Events
 
-- `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
+- `comment-add` -> `{ id, text, author }` - New top-level comment
+- `comment-reply` -> `{ id, text, author, parentId }` - Reply submitted
+- `comment-delete` -> `{ id }` - Comment deleted
+- `comment-like` -> `{ id, likes, liked }` - Like toggled
 
 ## 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 */
+--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
+- `base` - Root container
+- `input-area` - New comment input area
+- `list` - Comments list container
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-comments current-user="Alice" allow-replies max-depth="3"></snice-comments>
+<snice-comments current-user="Alice" allow-replies allow-likes></snice-comments>
 ```
 
 ```typescript
-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 }
+import 'snice/components/comments/snice-comments';
+
+el.comments = [
+  { id: '1', author: 'Bob', text: 'Great post!', timestamp: '2026-02-20T10:00:00Z', likes: 3 }
 ];
-comments.addEventListener('comment-add', e => console.log(e.detail));
+el.addEventListener('comment-add', (e) => console.log(e.detail));
 ```
+
+### Declarative
+
+```html
+<snice-comments current-user="John">
+  <snice-comment author="Alice" timestamp="2026-01-15T10:30:00Z" likes="3">
+    Great article!
+    <snice-comment author="Bob" timestamp="2026-01-15T11:00:00Z">Reply</snice-comment>
+  </snice-comment>
+</snice-comments>
+```
+
+## Accessibility
+
+- Tab through comments, Enter/Space to activate
+- Relative timestamps
+- Delete only on own comments
+- Semantic markup for screen readers

package/docs/ai/components/countdown.md

@@ -1,60 +1,58 @@
 # snice-countdown
 
-Countdown timer to a target date with multiple display formats and visual variants.
+Countdown timer to a target date with multiple visual variants and display formats.
 
 ## 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'
+```typescript
+target: string = '';                                  // ISO date string
+format: 'dhms'|'hms'|'ms' = 'dhms';                 // Display segments
+variant: 'simple'|'flip'|'circular' = 'simple';     // Visual style
 ```
 
 ## Events
 
-- `countdown-complete` → `void` - Fires when countdown reaches zero
-- `countdown-tick` → `{ days, hours, minutes, seconds, total }` - Fires every second
+- `countdown-complete` -> `void` - Countdown reached zero
+- `countdown-tick` -> `{ days, hours, minutes, seconds, total }` - 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-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 */
+--snice-color-border            /* Flip variant border */
+--snice-color-primary           /* Circular variant ring color */
+--snice-color-success           /* Complete state color */
 ```
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer countdown container
 - `segment` - Individual time segment (days, hours, etc.)
 - `value` - Digit value within a segment
 - `label` - Text label within a segment (e.g. "Days")
 - `separator` - Colon separator between segments
 
-## 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
+## Basic Usage
 
 ```html
-<snice-countdown target="2026-12-31T00:00:00Z" format="dhms" variant="flip"></snice-countdown>
+<snice-countdown target="2026-12-31T00:00:00Z" variant="flip" format="dhms"></snice-countdown>
 ```
 
 ```typescript
+import 'snice/components/countdown/snice-countdown';
+
 cd.addEventListener('countdown-complete', () => alert('Done!'));
-cd.addEventListener('countdown-tick', e => console.log(e.detail.total));
+cd.addEventListener('countdown-tick', (e) => console.log(e.detail.total));
 ```
+
+## Accessibility
+
+- Live updates every second
+- `.complete` class added to host on finish
+- Descriptive labels on each segment

package/docs/ai/components/cropper.md

@@ -1,28 +1,28 @@
 # snice-cropper
 
-Image cropping component with draggable/resizable crop area, rotation, zoom, aspect ratio lock, and rule-of-thirds grid.
+Image cropping 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'
+```typescript
+src: string = '';                                    // Image URL
+aspectRatio: number = 0;                             // attribute: aspect-ratio (0 = free, 1 = square, 1.777 = 16:9)
+minWidth: number = 20;                               // attribute: min-width
+minHeight: number = 20;                              // attribute: min-height
+outputType: 'png'|'jpeg'|'webp' = 'png';           // attribute: output-type
 ```
 
-## Events
+## Methods
 
-- `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
+- `crop(): Promise<Blob | null>` - Produce cropped image blob
+- `rotate(degrees: number)` - Rotate image (cumulative)
+- `zoom(level: number)` - Set zoom level (0.1 to 10)
+- `reset()` - Reset rotation, zoom, and crop area
 
-## Methods
+## Events
 
-- `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
+- `crop-change` -> `{ rect: { x, y, width, height } }` - Crop area moved/resized
+- `crop-complete` -> `{ blob: Blob | null }` - After crop() produces output
 
 ## CSS Custom Properties
 
@@ -31,36 +31,36 @@ outputType: CropperOutputType = 'png'         // attr: output-type — 'png' | '
 --snice-color-border              /* Container border */
 --snice-border-radius-lg          /* Container radius */
 --cropper-overlay                 /* Overlay mask color (default: rgb(0 0 0 / 0.5)) */
---cropper-border-color            /* Crop area border color (default: rgb(255 255 255)) */
---cropper-guide-color             /* Rule-of-thirds guide color (default: rgb(255 255 255 / 0.4)) */
---cropper-handle-color            /* Resize handle fill (default: rgb(255 255 255)) */
---cropper-handle-border           /* Resize handle border (default: rgb(0 0 0 / 0.3)) */
+--cropper-border-color            /* Crop area border (default: rgb(255 255 255)) */
+--cropper-guide-color             /* Guide lines (default: rgb(255 255 255 / 0.4)) */
+--cropper-handle-color            /* Handle fill (default: rgb(255 255 255)) */
+--cropper-handle-border           /* Handle border (default: rgb(0 0 0 / 0.3)) */
 ```
 
-**CSS Parts:**
-- `base` - Outer cropper container div
+## CSS Parts
+
+- `base` - Outer cropper container
 - `image-container` - Image display area
 - `crop-area` - Draggable/resizable crop region
 
-## 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
+## Basic Usage
 
 ```html
 <snice-cropper src="/photo.jpg" aspect-ratio="1" output-type="jpeg"></snice-cropper>
 ```
 
 ```typescript
-const blob = await cropper.crop();
+import 'snice/components/cropper/snice-cropper';
 
-// Rotate 90 degrees clockwise
+const blob = await cropper.crop();
 cropper.rotate(90);
-
-// Zoom in
 cropper.zoom(1.5);
+cropper.reset();
 ```
+
+## Accessibility
+
+- Drag to reposition, 8 handles to resize
+- Rule-of-thirds grid overlay
+- Dark mask indicates crop region
+- Aspect ratio enforced on resize when set

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

@@ -5,18 +5,18 @@ Key-value detail panel with grouped sections, multiple value types, and edit-in-
 ## Properties
 
 ```typescript
-fields: DataCardField[] = [];
-editable: boolean = false;              // Global edit mode toggle
+fields: DataCardField[] = [];                          // JS only (attribute: false)
+editable: boolean = false;                             // Global edit mode toggle
 variant: 'default'|'horizontal'|'compact' = 'default';
 
 interface DataCardField {
   label: string;
   value: string | number;
-  type?: 'text'|'link'|'badge'|'date'|'currency';  // default: 'text'
-  editable?: boolean;                    // per-field edit override
-  group?: string;                        // section grouping
-  icon?: string;                         // icon prefix
-  href?: string;                         // for type='link'
+  type?: 'text'|'link'|'badge'|'date'|'currency';     // default: 'text'
+  editable?: boolean;                                   // per-field edit override
+  group?: string;                                       // section grouping
+  icon?: string;                                        // icon prefix
+  href?: string;                                        // for type='link'
   badgeVariant?: 'default'|'primary'|'success'|'warning'|'danger';
 }
 ```
@@ -26,33 +26,39 @@ interface DataCardField {
 - `getValues()` → `Record<string, string|number>` - Get all field values as label:value map
 - `setValues(data)` - Update field values by label
 
-## Slots
-
-- `header` - Custom header content
-- `title` - Title text within default header
-
 ## Events
 
 - `field-change` → `{ field, value, previousValue }` - Field value changed
 - `field-save` → `{ field, value }` - Field value saved
 
+## Slots
+
+- `header` - Custom header content
+- `title` - Title text within default header
+
 ## CSS Parts
 
 - `container`, `header`, `title`, `edit-toggle`
 - `group`, `group-title`
 - `field`, `field-icon`, `field-label`, `field-value`, `field-input`, `field-save`, `field-edit`
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-data-card variant="default"></snice-data-card>
 ```
 
 ```typescript
-details.fields = [
+card.fields = [
   { label: 'Name', value: 'John Doe', group: 'Personal' },
   { label: 'Email', value: 'john@example.com', type: 'link', href: 'mailto:john@example.com', group: 'Personal' },
   { label: 'Status', value: 'Active', type: 'badge', badgeVariant: 'success', group: 'Account' },
   { label: 'Balance', value: '$1,250.00', type: 'currency', group: 'Account' }
 ];
 ```
+
+## Accessibility
+
+- Enter to save, Escape to cancel in edit mode
+- Edit toggle hidden when no fields are editable
+- Links use `rel="noopener"` and `target="_blank"`

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

@@ -1,6 +1,6 @@
 # snice-date-picker
 
-Calendar-based date input with format options and validation.
+Calendar-based date input with format options and validation. Form-associated custom element.
 
 ## Properties
 
@@ -8,22 +8,22 @@ Calendar-based date input with format options and validation.
 value: string = '';
 format: 'yyyy-mm-dd'|'mm/dd/yyyy'|'dd/mm/yyyy'|'yyyy/mm/dd'|'dd-mm-yyyy'|'mm-dd-yyyy'|'mmmm dd, yyyy' = 'mm/dd/yyyy';
 variant: 'outlined'|'filled'|'underlined' = 'outlined';
+size: 'small'|'medium'|'large' = 'medium';
 placeholder: string = '';
+label: string = '';
+helperText: string = '';       // attribute: helper-text
+errorText: string = '';        // attribute: error-text
 disabled: boolean = false;
+readonly: boolean = false;
+loading: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
-readonly: boolean = false;
 clearable: boolean = false;
-loading: boolean = false;
 min: string = '';              // Min date (ISO format)
 max: string = '';              // Max date (ISO format)
-size: 'small'|'medium'|'large' = 'medium';
 name: string = '';
-label: string = '';
-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.
+firstDayOfWeek: number = 0;   // attribute: first-day-of-week, 0=Sun, 1=Mon
 ```
 
 ## Methods
@@ -42,55 +42,48 @@ firstDayOfWeek: number = 0;    // attribute: first-day-of-week, 0=Sun, 1=Mon, et
 
 ## Events
 
-- `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}
+- `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
+## CSS Parts
 
-```html
-<!-- Basic -->
-<snice-date-picker label="Select date"></snice-date-picker>
+- `input` - Text input element
+- `calendar-toggle` - Calendar icon button
+- `clear` - Clear button
+- `spinner` - Loading spinner
+- `calendar` - Calendar popup container
+- `helper-text` - Helper text element
+- `error-text` - Error text element
 
-<!-- With format -->
-<snice-date-picker format="dd/mm/yyyy"></snice-date-picker>
+## Basic Usage
 
-<!-- With min/max -->
+```html
+<snice-date-picker label="Select date"></snice-date-picker>
+<snice-date-picker format="dd/mm/yyyy" clearable></snice-date-picker>
 <snice-date-picker min="2024-01-01" max="2024-12-31"></snice-date-picker>
-
-<!-- Clearable -->
-<snice-date-picker value="2024-03-15" clearable></snice-date-picker>
-
-<!-- Disabled/readonly -->
-<snice-date-picker disabled></snice-date-picker>
-<snice-date-picker readonly></snice-date-picker>
-
-<!-- Form integration -->
 <snice-date-picker name="birthdate" required></snice-date-picker>
-
-<!-- Event handling -->
-<snice-date-picker id="dp"></snice-date-picker>
 ```
 
 ```typescript
 dp.addEventListener('datepicker-change', (e) => {
-  console.log('Date:', e.detail.value);
+  console.log('Date:', e.detail.formatted, 'ISO:', e.detail.iso);
 });
 ```
 
-## Features
-
-- Form-associated custom element
-- Calendar popup with month/year navigation
-- Year picker (click year in header → 12-year grid, navigate ranges, click to select)
-- 7 date format options
-- Min/max date validation
-- Clearable with X button
-- 3 sizes, 3 variants
-- Keyboard accessible
-- Invalid state styling
+## Keyboard Navigation
+
+- Enter/Space on input opens calendar
+- Escape closes calendar, returns focus to input
+
+## Accessibility
+
+- Form-associated with ElementInternals
+- Calendar uses popover="manual"
+- Day buttons have aria-label with formatted date
+- aria-invalid on input when invalid

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

@@ -29,17 +29,7 @@ presets: DateRangePreset[] = [];   // attribute: false (JS only)
 showCalendar: boolean = false;     // attr: show-calendar
 ```
 
-## Formats
-
-`'mm/dd/yyyy'` | `'dd/mm/yyyy'` | `'yyyy-mm-dd'` | `'yyyy/mm/dd'` | `'dd-mm-yyyy'` | `'mm-dd-yyyy'` | `'mmmm dd, yyyy'`
-
-## Events
-
-- `daterange-change` → `{ start, end, startDate, endDate, startIso, endIso }`
-- `daterange-open` → `{ dateRangePicker }`
-- `daterange-close` → `{ dateRangePicker }`
-- `daterange-clear` → `{ dateRangePicker }`
-- `daterange-preset` → `{ label, start, end }`
+Formats: `'mm/dd/yyyy'`|`'dd/mm/yyyy'`|`'yyyy-mm-dd'`|`'yyyy/mm/dd'`|`'dd-mm-yyyy'`|`'mm-dd-yyyy'`|`'mmmm dd, yyyy'`
 
 ## Methods
 
@@ -51,19 +41,45 @@ showCalendar: boolean = false;     // attr: show-calendar
 - `reportValidity()` - Report validation to user, returns `boolean`
 - `setCustomValidity(message)` - Set custom validation message
 
-## Presets
+## Events
 
-```js
+- `daterange-change` → `{ start, end, startDate, endDate, startIso, endIso }`
+- `daterange-open` → `{ dateRangePicker }`
+- `daterange-close` → `{ dateRangePicker }`
+- `daterange-clear` → `{ dateRangePicker }`
+- `daterange-preset` → `{ label, start, end, dateRangePicker }`
+- `daterange-focus` → `{ dateRangePicker }`
+- `daterange-blur` → `{ dateRangePicker }`
+
+## CSS Parts
+
+`input`, `calendar-toggle`, `clear`, `spinner`, `calendar`, `helper-text`, `error-text`
+
+## Basic Usage
+
+```html
+<snice-date-range-picker label="Select Range" clearable columns="2"></snice-date-range-picker>
+```
+
+```typescript
+// Presets (JS only)
 picker.presets = [
   { label: 'Last 7 days', start: new Date(Date.now() - 7*86400000), end: new Date() },
   { label: 'This month', start: new Date(2026, 2, 1), end: new Date(2026, 2, 31) },
 ];
+
+// Events
+picker.addEventListener('daterange-change', (e) => {
+  console.log(e.detail.startIso, e.detail.endIso);
+});
 ```
 
 ## Form Integration
 
 `formAssociated: true`. Submits `{name}-start` and `{name}-end` via FormData.
 
-## CSS Parts
+## Accessibility
 
-`input`, `calendar-toggle`, `clear`, `spinner`, `calendar`, `error-text`, `helper-text`
+- Form-associated with ElementInternals
+- Calendar uses popover="manual"
+- Navigation buttons have aria-labels