snice 4.9.0 → 4.10.0

package/docs/ai/components/tree.md

@@ -1,191 +1,67 @@
 # snice-tree
 
-Hierarchical tree view with expandable nodes, selection, checkboxes, icons, and lazy loading.
+Hierarchical tree view with expandable nodes, selection, checkboxes, and lazy loading.
 
 ## Properties
 
 ```typescript
 nodes: TreeNode[] = [];
-selectionMode: 'single'|'multiple'|'none' = 'single';
-showCheckboxes: boolean = false;
-showIcons: boolean = true;
-expandOnClick: boolean = false;
-selectedNodes: string[] = [];
-checkedNodes: string[] = [];
-```
-
-## TreeNode Interface
+selectionMode: 'single'|'multiple'|'none' = 'single'; // attr: selection-mode
+showCheckboxes: boolean = false;  // attr: show-checkboxes
+showIcons: boolean = true;        // attr: show-icons
+expandOnClick: boolean = false;   // attr: expand-on-click
+selectedNodes: string[] = [];     // attr: selected-nodes
+checkedNodes: string[] = [];      // attr: checked-nodes
 
-```typescript
 interface TreeNode {
-  id: string;              // Unique identifier
-  label: string;           // Display text
-  icon?: string;           // Text/emoji icon
-  iconImage?: string;      // Icon image URL
-  children?: TreeNode[];   // Child nodes
-  disabled?: boolean;      // Disable interaction
-  selected?: boolean;      // Selection state
-  checked?: boolean;       // Checkbox state
-  expanded?: boolean;      // Expansion state
-  lazy?: boolean;          // Enable lazy loading
-  data?: any;             // Custom data
+  id: string;
+  label: string;
+  icon?: string;
+  iconImage?: string;
+  children?: TreeNode[];
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: boolean;
+  expanded?: boolean;
+  lazy?: boolean;
+  data?: any;
 }
 ```
 
-## Methods
-
-### Expand/Collapse
-- `expandNode(id: string)` - Expand a node
-- `collapseNode(id: string)` - Collapse a node
-- `toggleNode(id: string)` - Toggle node expansion
-- `expandAll()` - Expand all nodes
-- `collapseAll()` - Collapse all nodes
-
-### Selection
-- `selectNode(id: string)` - Select a node
-- `deselectNode(id: string)` - Deselect a node
-- `toggleSelection(id: string)` - Toggle selection
-
-### Checkboxes
-- `checkNode(id: string)` - Check a node
-- `uncheckNode(id: string)` - Uncheck a node
-- `toggleCheck(id: string)` - Toggle check state
+## Events
 
-### Getters
-- `getNode(id: string): TreeNode | undefined` - Get node by ID
-- `getSelectedNodes(): TreeNode[]` - Get all selected nodes
-- `getCheckedNodes(): TreeNode[]` - Get all checked nodes
+- `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 }`
 
-## Events
+## Methods
 
-- `tree-node-expand` - Node expanded (detail: { nodeId, node, tree })
-- `tree-node-collapse` - Node collapsed (detail: { nodeId, node, tree })
-- `tree-node-select` - Node selected (detail: { nodeId, node, selectedNodes, tree })
-- `tree-node-check` - Node checked/unchecked (detail: { nodeId, node, checked, checkedNodes, tree })
-- `tree-node-lazy-load` - Lazy node expanded (detail: { nodeId, node, tree })
+- `expandNode(id)` / `collapseNode(id)` / `toggleNode(id)`
+- `expandAll()` / `collapseAll()`
+- `selectNode(id)` / `deselectNode(id)` / `toggleSelection(id)`
+- `checkNode(id)` / `uncheckNode(id)` / `toggleCheck(id)`
+- `getNode(id)` - Get node by ID
+- `getSelectedNodes()` - Get selected nodes
+- `getCheckedNodes()` - Get checked nodes
 
 ## Usage
 
 ```html
-<!-- Basic file tree -->
-<snice-tree id="fileTree"></snice-tree>
+<snice-tree id="tree" selection-mode="single"></snice-tree>
 <script>
-  document.getElementById('fileTree').nodes = [
+  document.getElementById('tree').nodes = [
     {
-      id: 'src',
-      label: 'src',
-      icon: '📁',
-      expanded: true,
+      id: 'src', label: 'src', icon: '📁', expanded: true,
       children: [
         { id: 'index.ts', label: 'index.ts', icon: '📄' },
-        {
-          id: 'components',
-          label: 'components',
-          icon: '📁',
-          children: [
-            { id: 'header.ts', label: 'header.ts', icon: '📄' }
-          ]
-        }
+        { id: 'main.ts', label: 'main.ts', icon: '📄' }
       ]
     }
   ];
 </script>
 
-<!-- Single selection -->
-<snice-tree selection-mode="single"></snice-tree>
-
-<!-- Multiple selection -->
-<snice-tree selection-mode="multiple"></snice-tree>
-
-<!-- No selection -->
-<snice-tree selection-mode="none"></snice-tree>
-
-<!-- Checkbox selection -->
-<snice-tree show-checkboxes></snice-tree>
-
-<!-- Without icons -->
-<snice-tree show-icons="false"></snice-tree>
-
-<!-- Expand/collapse programmatically -->
-<button onclick="tree.expandAll()">Expand All</button>
-<button onclick="tree.collapseAll()">Collapse All</button>
-
-<!-- Selection events -->
-<snice-tree id="tree"></snice-tree>
-<script>
-  const tree = document.getElementById('tree');
-  tree.addEventListener('tree-node-select', (e) => {
-    console.log('Selected:', e.detail.node.label);
-    console.log('All selected:', e.detail.selectedNodes.map(n => n.label));
-  });
-</script>
-
-<!-- Lazy loading -->
-<snice-tree id="lazyTree"></snice-tree>
-<script>
-  const lazyTree = document.getElementById('lazyTree');
-  lazyTree.nodes = [
-    {
-      id: 'folder1',
-      label: 'Click to load...',
-      icon: '📁',
-      lazy: true,
-      children: []
-    }
-  ];
-
-  lazyTree.addEventListener('tree-node-lazy-load', async (e) => {
-    const node = e.detail.node;
-    const data = await fetch(`/api/nodes/${node.id}`).then(r => r.json());
-
-    node.children = data.map(item => ({
-      id: item.id,
-      label: item.name,
-      icon: '📄'
-    }));
-    node.lazy = false;
-    node.expanded = true;
-
-    // Trigger re-render
-    lazyTree.nodes = [...lazyTree.nodes];
-  });
-</script>
-
-<!-- Custom icons with images -->
-<snice-tree id="imgTree"></snice-tree>
-<script>
-  document.getElementById('imgTree').nodes = [
-    {
-      id: '1',
-      label: 'Images',
-      iconImage: '/icons/folder.png',
-      children: [
-        { id: '2', label: 'photo.jpg', iconImage: '/icons/image.png' }
-      ]
-    }
-  ];
-</script>
-
-<!-- Disabled nodes -->
-<snice-tree id="disabledTree"></snice-tree>
-<script>
-  document.getElementById('disabledTree').nodes = [
-    { id: '1', label: 'Active Node' },
-    { id: '2', label: 'Disabled Node', disabled: true }
-  ];
-</script>
+<snice-tree selection-mode="multiple" show-checkboxes></snice-tree>
+<snice-tree show-icons="false" expand-on-click></snice-tree>
 ```
-
-## Features
-
-- Hierarchical data display
-- Expand/collapse nodes
-- Single/multiple/no selection modes
-- Checkbox support for multi-select
-- Text and image icons
-- Lazy loading for large trees
-- Disabled nodes
-- Keyboard navigation (Arrow keys, Enter, Space, Home, End)
-- Full ARIA accessibility
-- Programmatic control
-- Custom data storage per node

package/docs/ai/components/treemap.md

@@ -1,78 +1,57 @@
 # snice-treemap
 
-SVG-based treemap visualization for hierarchical data as nested rectangles.
+Hierarchical data as nested rectangles with squarified layout and drill-down.
 
 ## Properties
 
 ```typescript
 data: TreemapNode = { label: '', value: 0 };
-showLabels: boolean = true;       // attribute: show-labels
-showValues: boolean = false;      // attribute: show-values
-colorScheme: TreemapColorScheme = 'default'; // attribute: color-scheme
+showLabels: boolean = true;      // attr: show-labels
+showValues: boolean = false;     // attr: show-values
+colorScheme: 'default'|'blue'|'green'|'purple'|'orange'|'warm'|'cool'|'rainbow' = 'default'; // attr: color-scheme
 padding: number = 2;
 animation: boolean = true;
-drillPath: TreemapNode[];         // read-only, current drill path
-```
-
-## Types
+drillPath: TreemapNode[];        // read-only
 
-```typescript
 interface TreemapNode {
   label: string;
   value: number;
   children?: TreemapNode[];
   color?: string;
 }
-
-type TreemapColorScheme = 'default' | 'blue' | 'green' | 'purple' | 'orange' | 'warm' | 'cool' | 'rainbow';
 ```
 
-## Methods
+## Events
 
-```typescript
-drillDown(node: TreemapNode): void;  // drill into node's children
-drillUp(): void;                      // go back one level
-drillToRoot(): void;                  // reset to root
-```
+- `treemap-click` → `{ node, depth }`
+- `treemap-hover` → `{ node, depth } | null`
+- `treemap-drill` → `{ node, path }`
 
-## Events
+## Methods
 
-```typescript
-'@snice/treemap-click': CustomEvent<{ node: TreemapNode; depth: number }>;
-'@snice/treemap-hover': CustomEvent<{ node: TreemapNode; depth: number } | null>;
-'@snice/treemap-drill': CustomEvent<{ node: TreemapNode; path: TreemapNode[] }>;
-```
+- `drillDown(node)` - Drill into node's children
+- `drillUp()` - Go back one level
+- `drillToRoot()` - Reset to root
 
 ## Usage
 
 ```html
-<!-- Basic -->
-<snice-treemap show-labels show-values></snice-treemap>
-
-<!-- Color scheme -->
-<snice-treemap show-labels color-scheme="blue"></snice-treemap>
-
-<!-- Set data via JS -->
+<snice-treemap id="map" show-labels show-values style="height: 400px;"></snice-treemap>
 <script>
-  treemap.data = {
+  document.getElementById('map').data = {
     label: 'Root',
     value: 0,
     children: [
       { label: 'A', value: 50 },
-      { label: 'B', value: 30 },
-      { label: 'C', value: 20 },
+      { label: 'B', value: 30, color: '#e74c3c' },
+      { label: 'C', value: 20, children: [
+        { label: 'C1', value: 12 },
+        { label: 'C2', value: 8 }
+      ]}
     ]
   };
 </script>
-```
 
-## Features
-
-- Squarified treemap layout algorithm for optimal aspect ratios
-- 8 color schemes + custom per-node colors
-- Drill-down into child nodes with breadcrumb navigation
-- Tooltips on hover
-- Labels auto-hide when rectangles are too small
-- Responsive sizing via ResizeObserver
-- Animated transitions
-- Accessible: role="img" with aria-label
+<snice-treemap color-scheme="blue" show-labels></snice-treemap>
+<snice-treemap color-scheme="rainbow" show-labels show-values></snice-treemap>
+```

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

@@ -0,0 +1,91 @@
+# snice-video-player
+
+Full-featured video player with custom controls, keyboard shortcuts, PiP, and fullscreen.
+
+## 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
+```
+
+## Methods
+
+- `play()` - Start playback (async)
+- `pause()` - Pause playback
+- `toggle()` - Toggle play/pause
+- `seekTo(time: number)` - 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
+
+## 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%
+
+## Variants
+
+- `default` - Full controls, progress bar, PiP, rate selector
+- `minimal` - Simplified controls, no rate/PiP buttons
+- `cinema` - Larger controls, no border radius, box shadow
+
+## CSS Custom Properties
+
+- `--snice-color-primary` - Progress bar fill (default: `rgb(37 99 235)`)
+- `--snice-border-radius-lg` - Container border radius (default: `0.5rem`)
+- `--snice-transition-fast` - Control transitions (default: `150ms`)
+- `--snice-transition-medium` - Controls fade (default: `250ms`)
+- `--snice-shadow-lg` - Cinema variant shadow
+- `--snice-focus-ring-width` - Button focus ring width
+- `--snice-focus-ring-color` - Button focus ring color
+
+## Usage
+
+```html
+<snice-video-player
+  src="video.mp4"
+  poster="poster.jpg"
+  controls
+></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>
+```
+
+```js
+const player = document.querySelector('snice-video-player');
+player.addEventListener('video-ended', () => {
+  console.log('Video finished');
+});
+player.play();
+```

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

@@ -1,71 +1,48 @@
 # snice-virtual-scroller
 
-Efficiently render large lists by only displaying visible items.
+Efficiently renders large lists by only displaying visible items.
 
 ## Properties
 
 ```typescript
 items: VirtualScrollerItem[] = [];
-itemHeight: number = 50; // px
-bufferSize: number = 5; // extra items outside viewport
-estimatedItemHeight: number = 50;
+itemHeight: number = 50;              // attr: item-height, px
+bufferSize: number = 5;               // attr: buffer-size
+estimatedItemHeight: number = 50;     // attr: estimated-item-height
 renderItem: (item: VirtualScrollerItem, index: number) => string | HTMLElement;
-```
-
-## VirtualScrollerItem
 
-```typescript
 interface VirtualScrollerItem {
   id: string | number;
   data: any;
-  height?: number; // optional custom height
+  height?: number;
 }
 ```
 
 ## Methods
 
-```typescript
-scrollToIndex(index: number): void
-scrollToItem(id: string | number): void
-refresh(): void
-getVisibleRange(): { start: number; end: number }
-```
+- `scrollToIndex(index)` - Scroll to item at index
+- `scrollToItem(id)` - Scroll to item by ID
+- `refresh()` - Recalculate visible range and re-render
+- `getVisibleRange()` - Returns `{ start, end }`
 
 ## Usage
 
-```javascript
-scroller.items = Array.from({ length: 10000 }, (_, i) => ({
-  id: i,
-  data: `Item ${i}`
-}));
+```html
+<snice-virtual-scroller id="list" style="height: 400px;" item-height="60"></snice-virtual-scroller>
 
-scroller.renderItem = (item, index) => {
-  return `<div>${item.data}</div>`;
-};
+<script>
+  const scroller = document.getElementById('list');
 
-// Scroll to item
-scroller.scrollToIndex(500);
+  scroller.items = Array.from({ length: 10000 }, (_, i) => ({
+    id: i,
+    data: { name: `Item ${i + 1}` }
+  }));
 
-// Get visible range
-const range = scroller.getVisibleRange();
-```
+  scroller.renderItem = (item) => {
+    return `<div style="padding: 15px;">${item.data.name}</div>`;
+  };
 
-```html
-<snice-virtual-scroller
-  style="height: 400px;"
-  item-height="60"
-  buffer-size="10">
-</snice-virtual-scroller>
+  scroller.scrollToIndex(500);
+  const range = scroller.getVisibleRange();
+</script>
 ```
-
-## Features
-
-- Only renders visible items + buffer
-- Handles thousands of items efficiently
-- Variable item heights supported
-- Programmatic scrolling
-- Dynamic updates (add/remove/update)
-- Smooth 60fps scrolling
-- Low memory footprint
-- Search and filter support
-- Infinite scroll patterns

package/docs/ai/components/waterfall.md

@@ -0,0 +1,56 @@
+# snice-waterfall
+
+Waterfall chart (bridge chart) showing cumulative effect of sequential positive/negative values.
+
+## Properties
+
+```ts
+data: WaterfallDataPoint[] = []
+orientation: 'vertical' | 'horizontal' = 'vertical'
+showValues: boolean = true     // attribute: show-values
+showConnectors: boolean = true // attribute: show-connectors
+animated: boolean = false
+
+interface WaterfallDataPoint {
+  label: string
+  value: number
+  type?: 'increase' | 'decrease' | 'total'  // auto-detected from value sign if omitted
+}
+```
+
+## Events
+
+- `bar-click` -> `{ item: WaterfallDataPoint; index: number }`
+- `bar-hover` -> `{ item: WaterfallDataPoint; index: number }`
+
+## CSS Custom Properties
+
+- `--snice-color-success` - Increase bar fill (default: `rgb(22 163 74)`)
+- `--snice-color-danger` - Decrease bar fill (default: `rgb(220 38 38)`)
+- `--snice-color-primary` - Total bar fill (default: `rgb(37 99 235)`)
+- `--snice-color-text-secondary` - Label text color
+- `--snice-color-text-tertiary` - Connector line color
+- `--snice-color-border` - Zero-line axis color (default: `rgb(226 226 226)`)
+- `--snice-transition-fast` - Bar hover transition (default: `150ms`)
+- `--snice-font-weight-medium` - Value text weight
+
+## Usage
+
+```html
+<snice-waterfall show-values show-connectors></snice-waterfall>
+```
+
+```js
+const chart = document.querySelector('snice-waterfall');
+chart.data = [
+  { label: 'Start', value: 1000, type: 'total' },
+  { label: 'Revenue', value: 500 },
+  { label: 'Costs', value: -200 },
+  { label: 'Tax', value: -100 },
+  { label: 'End', value: 1200, type: 'total' }
+];
+
+chart.addEventListener('bar-click', (e) => {
+  console.log(`Clicked: ${e.detail.item.label} (${e.detail.item.value})`);
+});
+```

package/docs/ai/components/weather.md

@@ -0,0 +1,78 @@
+# snice-weather
+
+Weather display card with current conditions, humidity, wind, and multi-day forecast.
+
+## Properties
+
+```ts
+data: WeatherData | null = null
+unit: 'celsius' | 'fahrenheit' = 'celsius'
+variant: 'compact' | 'full' = 'full'
+
+interface WeatherData {
+  temp: number
+  condition: string           // e.g. "Sunny", "Partly Cloudy", "Rain"
+  icon?: string               // emoji or custom icon (auto-detected from condition if omitted)
+  humidity?: number            // percentage
+  wind?: number               // km/h
+  forecast?: WeatherForecastDay[]
+}
+
+interface WeatherForecastDay {
+  day: string                 // e.g. "Mon", "Tue"
+  high: number
+  low: number
+  condition: string
+  icon?: string
+}
+```
+
+## Variants
+
+- `full` - Shows current weather, details (humidity/wind), and forecast
+- `compact` - Current temp and icon only; hides details and forecast
+
+## Auto-detected Icons
+
+When `icon` is omitted, mapped from `condition` string:
+- sun/clear -> sun emoji
+- partly cloud -> partly cloudy emoji
+- cloud -> cloud emoji
+- rain -> rain emoji
+- snow -> snow emoji
+- thunder/storm -> thunderstorm emoji
+- fog/mist -> fog emoji
+- wind -> wind emoji
+
+## CSS Custom Properties
+
+- `--snice-color-background-element` - Card background (default: `rgb(252 251 249)`)
+- `--snice-color-border` - Card and forecast divider border
+- `--snice-color-text` - Primary text color (default: `rgb(23 23 23)`)
+- `--snice-color-text-secondary` - Condition/detail text
+- `--snice-color-text-tertiary` - Forecast low temp
+- `--snice-font-weight-bold` - Temperature weight (default: `700`)
+- `--snice-font-weight-semibold` - Forecast high temp weight
+- `--snice-border-radius-lg` - Card border radius (default: `0.5rem`)
+- `--snice-spacing-lg` - Card padding (default: `1.5rem`)
+
+## Usage
+
+```html
+<snice-weather unit="celsius" variant="full"></snice-weather>
+```
+
+```js
+const weather = document.querySelector('snice-weather');
+weather.data = {
+  temp: 22,
+  condition: 'Partly Cloudy',
+  humidity: 65,
+  wind: 12,
+  forecast: [
+    { day: 'Mon', high: 24, low: 18, condition: 'Sunny' },
+    { day: 'Tue', high: 20, low: 15, condition: 'Rain' },
+    { day: 'Wed', high: 22, low: 16, condition: 'Cloudy' }
+  ]
+};
+```