snice 4.28.0 → 4.29.0

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

@@ -18,12 +18,6 @@ disabled: boolean = false;
 interface TimeRange { start: string; end: string; }
 ```
 
-## Events
-
-- `time-range-change` → `{ ranges, component }`
-- `time-range-select` → `{ start, component }` - Drag begins
-- `time-range-complete` → `{ range, ranges, component }` - Drag ends
-
 ## Methods
 
 - `getSelectedRanges()` - Returns TimeRange[]
@@ -31,22 +25,29 @@ interface TimeRange { start: string; end: string; }
 - `clearSelection()` - Clear all selections
 - `isSlotDisabled(time)` - Check if time slot is disabled
 
+## Events
+
+- `time-range-change` -> `{ ranges, component }`
+- `time-range-select` -> `{ start, component }` - Drag begins
+- `time-range-complete` -> `{ range, ranges, component }` - Drag ends
+
 ## CSS Parts
 
 - `base` - The outer wrapper container
 - `header` - The header with label and selected value display
 - `slots` - The time slots container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-time-range-picker start-time="08:00" end-time="18:00"></snice-time-range-picker>
-<snice-time-range-picker granularity="30" format="12h"></snice-time-range-picker>
-<snice-time-range-picker multiple></snice-time-range-picker>
-<snice-time-range-picker
-  disabled-ranges='[{"start":"12:00","end":"13:00"}]'>
-</snice-time-range-picker>
-<snice-time-range-picker
-  value='[{"start":"09:00","end":"11:00"}]'>
-</snice-time-range-picker>
+<snice-time-range-picker granularity="30" format="12h" multiple></snice-time-range-picker>
+<snice-time-range-picker disabled-ranges='[{"start":"12:00","end":"13:00"}]'></snice-time-range-picker>
+<snice-time-range-picker value='[{"start":"09:00","end":"11:00"}]'></snice-time-range-picker>
+```
+
+```typescript
+picker.setSelectedRanges([{ start: '09:00', end: '11:00' }]);
+const ranges = picker.getSelectedRanges();
+picker.clearSelection();
 ```

package/docs/ai/components/timeline.md

@@ -1,6 +1,6 @@
 # snice-timeline
 
-Displays chronological events with markers.
+Displays chronological events with markers, timestamps, and descriptions.
 
 ## Properties
 
@@ -30,7 +30,7 @@ interface TimelineItem {
 - `title` - Title text
 - `description` - Description text
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-timeline></snice-timeline>
@@ -39,11 +39,12 @@ interface TimelineItem {
 ```typescript
 timeline.items = [
   { timestamp: '2024-01-15', title: 'Created', description: 'Project started', variant: 'success' },
-  { timestamp: '2024-02-01', title: 'Review', description: 'In review', variant: 'warning', icon: '📋' },
-  { timestamp: '2024-03-01', title: 'Launch', description: 'Deployed', variant: 'info', icon: '🚀' }
+  { timestamp: '2024-02-01', title: 'Review', description: 'In review', variant: 'warning', icon: '!' },
+  { timestamp: '2024-03-01', title: 'Launch', description: 'Deployed', variant: 'info' }
 ];
 ```
 
+```html
 <snice-timeline position="alternate"></snice-timeline>
 <snice-timeline position="right"></snice-timeline>
 <snice-timeline orientation="horizontal"></snice-timeline>

package/docs/ai/components/timer.md

@@ -10,13 +10,6 @@ initialTime: number = 0;   // attr: initial-time, seconds (for timer mode)
 running: boolean;           // read-only
 ```
 
-## Events
-
-- `timer-start` → `{ timer, time }`
-- `timer-stop` → `{ timer, time }`
-- `timer-reset` → `{ timer, time }`
-- `timer-complete` → `{ timer }` - Countdown reached 0
-
 ## Methods
 
 - `start()` - Start timer
@@ -24,13 +17,20 @@ running: boolean;           // read-only
 - `reset()` - Reset to initial state
 - `getTime()` - Get current time in seconds
 
+## Events
+
+- `timer-start` -> `{ timer, time }`
+- `timer-stop` -> `{ timer, time }`
+- `timer-reset` -> `{ timer, time }`
+- `timer-complete` -> `{ timer }` - Countdown reached 0
+
 ## CSS Parts
 
 - `base` - The outer timer container
 - `display` - The time display element
 - `controls` - The start/stop/reset button container
 
-## Usage
+## Basic Usage
 
 ```html
 <!-- Stopwatch (counts up) -->

package/docs/ai/components/toast.md

@@ -2,6 +2,17 @@
 
 Temporary notification system with static API.
 
+## Components
+
+- `<snice-toast-container>` - Positions and manages toasts
+- `<snice-toast>` - Individual toast notification
+
+## snice-toast-container
+
+```typescript
+position: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' = 'bottom-center';
+```
+
 ## snice-toast
 
 ```typescript
@@ -11,17 +22,6 @@ closable: boolean = true;
 icon: boolean = true;
 ```
 
-**CSS Parts (snice-toast):**
-- `base` - Outer toast div (has type modifier class)
-- `icon` - Icon span wrapper
-- `content` - Message text span
-
-## snice-toast-container
-
-```typescript
-position: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' = 'bottom-center';
-```
-
 ## Static API
 
 ```typescript
@@ -49,17 +49,23 @@ interface ToastOptions {
 }
 ```
 
-## Events (snice-toast)
-
-- `close-toast` → `{ id: string }` - Close button clicked
-
-## Container Methods
+## Methods (container instance)
 
 - `show(message, options?)` - Show toast, returns ID
 - `hide(id)` - Hide specific toast
 - `clear()` - Remove all toasts
 
-## Usage
+## Events (snice-toast)
+
+- `close-toast` -> `{ id: string }` - Close button clicked
+
+## CSS Parts (snice-toast)
+
+- `base` - Outer toast div (has type modifier class)
+- `icon` - Icon span wrapper
+- `content` - Message text span
+
+## Basic Usage
 
 ```typescript
 Toast.success('Saved successfully');
@@ -68,7 +74,7 @@ Toast.warning('Low disk space');
 
 Toast.show('Custom', { type: 'success', duration: 5000, position: 'top-right' });
 
-const id = Toast.info('Loading...', { duration: 0 });
+const id = await Toast.info('Loading...', { duration: 0 });
 await operation();
 Toast.hide(id);
 ```

package/docs/ai/components/tooltip.md

@@ -18,24 +18,25 @@ zIndex: number = 10000;          // attr: z-index
 strictPositioning: boolean = false; // attr: strict-positioning
 ```
 
+## Methods
+
+- `show()` - Show tooltip
+- `hide()` - Hide tooltip
+- `toggle()` - Toggle visibility
+- `updatePosition()` - Recalculate position
+
 ## Slots
 
 - `(default)` - Trigger element the tooltip attaches to
 
-**CSS Parts:**
+## CSS Parts
+
 - `trigger` - Wrapper around the slot/trigger content
 - `tooltip` - The tooltip popup div
 - `content` - Text content inside tooltip
 - `arrow` - Arrow element
 
-## Methods
-
-- `show()` - Show tooltip
-- `hide()` - Hide tooltip
-- `toggle()` - Toggle visibility
-- `updatePosition()` - Recalculate position
-
-## Usage
+## Basic Usage
 
 ```html
 <snice-tooltip content="Tooltip text">
@@ -63,17 +64,9 @@ strictPositioning: boolean = false; // attr: strict-positioning
 tip.open = true;
 ```
 
-```html
-<snice-tooltip content="Delayed" delay="500" hide-delay="200">
-  <button>Wait</button>
-</snice-tooltip>
-```
-
 ## Attribute-Based Tooltips
 
-Observer for `tooltip` attribute on any element. No wrapper element — safe inside strict-children components (tabs, accordion, etc.). Auto-activates when the tooltip component is loaded.
-
-### Usage
+Observer for `tooltip` attribute on any element. No wrapper element -- safe inside strict-children components (tabs, accordion, etc.). Auto-activates when the tooltip component is loaded.
 
 ```html
 <button tooltip="Save changes">Save</button>
@@ -108,7 +101,3 @@ Observer for `tooltip` attribute on any element. No wrapper element — safe ins
 | `--tooltip-padding` | `8px 12px` | Content padding |
 | `--tooltip-radius` | `6px` | Border radius |
 | `--tooltip-font-size` | `14px` | Font size |
-
-### Cleanup
-
-The tooltip observer is managed automatically by the tooltip component. It activates as a side effect when any `<snice-tooltip>` component is loaded and cleans up when no longer needed.

package/docs/ai/components/tree.md

@@ -30,14 +30,6 @@ interface TreeNode {
 }
 ```
 
-## Events
-
-- `tree-node-expand` → `{ nodeId, node, tree }`
-- `tree-node-collapse` → `{ nodeId, node, tree }`
-- `tree-node-select` → `{ nodeId, node, selectedNodes, tree }`
-- `tree-node-check` → `{ nodeId, node, checked, checkedNodes, tree }`
-- `tree-node-lazy-load` → `{ nodeId, node, tree }`
-
 ## Methods
 
 - `expandNode(id)` / `collapseNode(id)` / `toggleNode(id)`
@@ -49,6 +41,14 @@ interface TreeNode {
 - `getCheckedNodes()` - Get checked nodes
 - `updateNode(id, updates)` - Update node properties
 
+## Events
+
+- `tree-node-expand` -> `{ nodeId, node, tree }`
+- `tree-node-collapse` -> `{ nodeId, node, tree }`
+- `tree-node-select` -> `{ nodeId, node, selectedNodes, tree }`
+- `tree-node-check` -> `{ nodeId, node, checked, checkedNodes, tree }`
+- `tree-node-lazy-load` -> `{ nodeId, node, tree }`
+
 ## CSS Parts
 
 - `container` - Main tree container
@@ -58,7 +58,7 @@ interface TreeNode {
 
 - `--tree-max-height` - Maximum height of tree (default: `100%`)
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-tree selection-mode="single"></snice-tree>

package/docs/ai/components/treemap.md

@@ -21,19 +21,26 @@ interface TreemapNode {
 }
 ```
 
-## Events
-
-- `treemap-click` → `{ node, depth }`
-- `treemap-hover` → `{ node, depth } | null`
-- `treemap-drill` → `{ node, path }`
-
 ## Methods
 
 - `drillDown(node)` - Drill into node's children
 - `drillUp()` - Go back one level
 - `drillToRoot()` - Reset to root
 
-## Usage
+## Events
+
+- `treemap-click` -> `{ node, depth }`
+- `treemap-hover` -> `{ node, depth } | null`
+- `treemap-drill` -> `{ node, path }`
+
+## CSS Parts
+
+- `breadcrumbs` - Breadcrumb navigation for drill-down
+- `base` - Main treemap container
+- `chart` - Chart rendering area
+- `tooltip` - Hover tooltip element
+
+## Basic Usage
 
 ```html
 <snice-treemap show-labels show-values style="height: 400px;"></snice-treemap>
@@ -55,9 +62,3 @@ treemap.data = {
   ]
 };
 ```
-
-**CSS Parts:**
-- `breadcrumbs` - Breadcrumb navigation for drill-down
-- `base` - Main treemap container
-- `chart` - Chart rendering area
-- `tooltip` - Hover tooltip element

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

@@ -17,23 +17,33 @@ status: 'online'|'away'|'offline'|'busy' = 'offline';
 variant: 'card'|'horizontal'|'compact' = 'card';
 ```
 
-## Slots
+## Methods
 
-- `(default)` - Action buttons (e.g. Follow, Message)
+- `emitActionClick(action: string)` - Dispatch action-click event programmatically
 
 ## Events
 
 - `social-click` -> `{ platform: string, url: string }`
 - `action-click` -> `{ action: string }`
 
-## Methods
+## Slots
 
-- `emitActionClick(action: string)` - Dispatch action-click event programmatically
+- `(default)` - Action buttons (e.g. Follow, Message)
+
+## CSS Parts
+
+- `base` - Outer container
+- `avatar` - Avatar wrapper
+- `status` - Status indicator dot
+- `name` - Name heading
+- `role` - Role/company text
+- `contact` - Contact info section
+- `social` - Social links row
+- `actions` - Actions slot wrapper
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic card -->
 <snice-user-card
   name="Sarah Johnson"
   role="Engineer"
@@ -44,17 +54,14 @@ variant: 'card'|'horizontal'|'compact' = 'card';
   status="online"
 ></snice-user-card>
 
-<!-- Horizontal layout -->
 <snice-user-card variant="horizontal" name="Alex" role="CTO" status="online">
   <button>Message</button>
 </snice-user-card>
 
-<!-- Compact (list item) -->
 <snice-user-card variant="compact" name="Lisa" role="Dev" status="away"></snice-user-card>
 ```
 
 ```javascript
-// Set social links (array property)
 card.social = [
   { platform: 'github', url: 'https://github.com/user' },
   { platform: 'twitter', url: 'https://twitter.com/user' },
@@ -62,22 +69,9 @@ card.social = [
 ];
 ```
 
-## CSS Parts
-
-- `base` - Outer container
-- `avatar` - Avatar wrapper
-- `status` - Status indicator dot
-- `name` - Name heading
-- `role` - Role/company text
-- `contact` - Contact info section
-- `social` - Social links row
-- `actions` - Actions slot wrapper
-
-## Features
+## Accessibility
 
-- 3 layout variants (card/horizontal/compact)
-- Avatar with initials fallback
-- Status indicator (online/away/offline/busy)
-- Contact info with icons (email, phone, location)
-- Social link icons (github, twitter, linkedin, facebook, instagram, youtube, website)
-- Slotted action buttons
+- Avatar fallback uses initials from name
+- Status indicator has `role="img"` and `aria-label`
+- Social links have `aria-label` and `title`
+- Email/phone rendered as accessible links

package/docs/ai/components/video-player.md

@@ -4,18 +4,18 @@ Full-featured video player with custom controls, keyboard shortcuts, PiP, and fu
 
 ## Properties
 
-```ts
-src: string = ''
-poster: string = ''
-autoplay: boolean = false
-muted: boolean = false
-loop: boolean = false
-controls: boolean = true
-playbackRate: number = 1       // attribute: playback-rate
-currentTime: number = 0        // attribute: current-time
-volume: number = 1             // 0-1
-variant: 'default' | 'minimal' | 'cinema' = 'default'
-readonly duration: number      // read-only, set from video metadata
+```typescript
+src: string = '';
+poster: string = '';
+autoplay: boolean = false;
+muted: boolean = false;
+loop: boolean = false;
+controls: boolean = true;
+playbackRate: number = 1;       // attr: playback-rate
+currentTime: number = 0;        // attr: current-time
+volume: number = 1;             // 0-1
+variant: 'default'|'minimal'|'cinema' = 'default';
+duration: number;               // read-only
 ```
 
 ## Methods
@@ -23,42 +23,28 @@ readonly duration: number      // read-only, set from video metadata
 - `play()` - Start playback (async)
 - `pause()` - Pause playback
 - `toggle()` - Toggle play/pause
-- `seekTo(time: number)` - Seek to time in seconds
+- `seekTo(time)` - Seek to time in seconds
 - `requestFullscreen()` - Enter fullscreen (async)
 - `exitFullscreen()` - Exit fullscreen (async)
 - `requestPictureInPicture()` - Toggle picture-in-picture (async)
-- `setPlaybackRate(rate: number)` - Set playback speed
-
-## Slots
-
-- `default` - `<source>` elements for multiple formats
+- `setPlaybackRate(rate)` - Set playback speed
 
 ## Events
 
-- `video-play` -> `{ player: SniceVideoPlayerElement }`
-- `video-pause` -> `{ player: SniceVideoPlayerElement }`
-- `video-ended` -> `{ player: SniceVideoPlayerElement }`
-- `video-time-update` -> `{ player: SniceVideoPlayerElement; currentTime: number; duration: number }`
-- `video-fullscreen-change` -> `{ player: SniceVideoPlayerElement; fullscreen: boolean }`
-- `video-volume-change` -> `{ player: SniceVideoPlayerElement; volume: number; muted: boolean }`
-
-## Keyboard Shortcuts
-
-- Space/K: Toggle play/pause
-- F: Toggle fullscreen
-- M: Toggle mute
-- ArrowRight/ArrowLeft: Seek forward/backward 5s
-- ArrowUp/ArrowDown: Volume up/down 10%
+- `video-play` -> `{ player }`
+- `video-pause` -> `{ player }`
+- `video-ended` -> `{ player }`
+- `video-time-update` -> `{ player, currentTime, duration }`
+- `video-fullscreen-change` -> `{ player, fullscreen }`
+- `video-volume-change` -> `{ player, volume, muted }`
 
-## Variants
+## Slots
 
-- `default` - Full controls, progress bar, PiP, rate selector
-- `minimal` - Simplified controls, no rate/PiP buttons
-- `cinema` - Larger controls, no border radius, box shadow
+- `(default)` - `<source>` elements for multiple formats
 
 ## CSS Custom Properties
 
-- `--snice-video-overlay-bg` - Video background color (default: `rgb(0 0 0)`)
+- `--snice-video-overlay-bg` - Video background (default: `rgb(0 0 0)`)
 - `--snice-video-overlay-alpha` - Overlay with alpha (default: `rgb(0 0 0 / 0.5)`)
 - `--snice-video-controls-color` - Controls text/icon color (default: `rgb(255 255 255)`)
 - `--snice-video-controls-hover-bg` - Button hover background (default: `rgb(255 255 255 / 0.15)`)
@@ -77,31 +63,28 @@ readonly duration: number      // read-only, set from video metadata
 - `--snice-focus-ring-width` - Button focus ring width
 - `--snice-focus-ring-color` - Button focus ring color
 
-**CSS Parts:**
+## CSS Parts
+
 - `base` - Outer container element
 - `video` - The `<video>` element
 - `controls` - Control bar container
 - `progress` - Progress track element
 
-## Usage
+## Keyboard Navigation
+
+- Space/K: Toggle play/pause
+- F: Toggle fullscreen
+- M: Toggle mute
+- ArrowRight/ArrowLeft: Seek forward/backward 5s
+- ArrowUp/ArrowDown: Volume up/down 10%
+
+## Basic Usage
 
 ```html
-<snice-video-player
-  src="video.mp4"
-  poster="poster.jpg"
-  controls
-></snice-video-player>
+<snice-video-player src="video.mp4" poster="poster.jpg"></snice-video-player>
 
-<!-- Multiple sources -->
 <snice-video-player poster="poster.jpg">
   <source src="video.webm" type="video/webm">
   <source src="video.mp4" type="video/mp4">
 </snice-video-player>
 ```
-
-```typescript
-player.addEventListener('video-ended', () => {
-  console.log('Video finished');
-});
-player.play();
-```

package/docs/ai/components/virtual-scroller.md

@@ -29,7 +29,7 @@ interface VirtualScrollerItem {
 
 - `base` - The outer scroller container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-virtual-scroller style="height: 400px;" item-height="60"></snice-virtual-scroller>

package/docs/ai/components/waterfall.md

@@ -4,24 +4,24 @@ Waterfall chart (bridge chart) showing cumulative effect of sequential positive/
 
 ## Properties
 
-```ts
-data: WaterfallDataPoint[] = []
-orientation: 'vertical' | 'horizontal' = 'vertical'
-showValues: boolean = true     // attribute: show-values
-showConnectors: boolean = true // attribute: show-connectors
-animated: boolean = false
+```typescript
+data: WaterfallDataPoint[] = [];
+orientation: 'vertical'|'horizontal' = 'vertical';
+showValues: boolean = true;     // attr: show-values
+showConnectors: boolean = true; // attr: show-connectors
+animated: boolean = false;
 
 interface WaterfallDataPoint {
-  label: string
-  value: number
-  type?: 'increase' | 'decrease' | 'total'  // auto-detected from value sign if omitted
+  label: string;
+  value: number;
+  type?: 'increase'|'decrease'|'total';  // auto-detected from value sign if omitted
 }
 ```
 
 ## Events
 
-- `bar-click` → `{ item: WaterfallDataPoint; index: number }` — bar clicked
-- `bar-hover` → `{ item: WaterfallDataPoint; index: number }` — bar hovered
+- `bar-click` -> `{ item: WaterfallDataPoint, index: number }`
+- `bar-hover` -> `{ item: WaterfallDataPoint, index: number }`
 
 ## CSS Custom Properties
 
@@ -34,7 +34,12 @@ interface WaterfallDataPoint {
 - `--snice-transition-fast` - Bar hover transition (default: `150ms`)
 - `--snice-font-weight-medium` - Value text weight
 
-## Usage
+## CSS Parts
+
+- `base` - Main waterfall container
+- `chart` - Chart rendering area
+
+## Basic Usage
 
 ```html
 <snice-waterfall show-values show-connectors></snice-waterfall>
@@ -53,7 +58,3 @@ chart.addEventListener('bar-click', (e) => {
   console.log(`Clicked: ${e.detail.item.label} (${e.detail.item.value})`);
 });
 ```
-
-**CSS Parts:**
-- `base` - Main waterfall container
-- `chart` - Chart rendering area