snice 4.8.0 → 4.10.0

package/docs/ai/components/tooltip.md

@@ -6,141 +6,54 @@ Contextual information on hover, click, or focus with smart positioning.
 
 ```typescript
 content: string = '';
-position: TooltipPosition = 'top';
+position: 'top'|'top-start'|'top-end'|'bottom'|'bottom-start'|'bottom-end'|'left'|'left-start'|'left-end'|'right'|'right-start'|'right-end' = 'top';
 trigger: 'hover'|'click'|'focus'|'manual' = 'hover';
-delay: number = 0;                    // Show delay (ms)
-hideDelay: number = 0;                // Hide delay (ms)
-offset: number = 12;                  // Distance from trigger (px)
+delay: number = 0;
+hideDelay: number = 0;           // attr: hide-delay
+offset: number = 12;
 arrow: boolean = true;
-open: boolean = false;                // For manual trigger
-maxWidth: number = 250;               // px
-zIndex: number = 10000;
-strictPositioning: boolean = false;   // Disable auto-repositioning
+open: boolean = false;
+maxWidth: number = 250;          // attr: max-width
+zIndex: number = 10000;          // attr: z-index
+strictPositioning: boolean = false; // attr: strict-positioning
 ```
 
-## Positions
+## Slots
 
-**12 positions:**
-- `top`, `bottom`, `left`, `right`
-- `top-start`, `top-end`
-- `bottom-start`, `bottom-end`
-- `left-start`, `left-end`
-- `right-start`, `right-end`
+- `(default)` - Trigger element the tooltip attaches to
 
 ## Methods
 
-```typescript
-show()            // Show tooltip
-hide()            // Hide tooltip
-toggle()          // Toggle visibility
-updatePosition()  // Recalculate position
-```
+- `show()` - Show tooltip
+- `hide()` - Hide tooltip
+- `toggle()` - Toggle visibility
+- `updatePosition()` - Recalculate position
 
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-tooltip content="Tooltip text">
   <button>Hover me</button>
 </snice-tooltip>
 
-<!-- Position -->
 <snice-tooltip content="Below" position="bottom">
-  <button>Button</button>
+  <button>Bottom</button>
 </snice-tooltip>
 
-<!-- Click trigger -->
 <snice-tooltip content="Click to toggle" trigger="click">
   <button>Click me</button>
 </snice-tooltip>
 
-<!-- Focus trigger -->
-<snice-tooltip content="Focus input" trigger="focus">
+<snice-tooltip content="Focus help" trigger="focus">
   <input type="text">
 </snice-tooltip>
 
-<!-- Manual control -->
 <snice-tooltip id="tip" content="Manual" trigger="manual">
   <span>Element</span>
 </snice-tooltip>
-<button onclick="document.querySelector('#tip').open = true">Show</button>
+<script>document.querySelector('#tip').open = true;</script>
 
-<!-- With delay -->
 <snice-tooltip content="Delayed" delay="500" hide-delay="200">
   <button>Wait</button>
 </snice-tooltip>
-
-<!-- Custom styling -->
-<snice-tooltip
-  content="Custom"
-  max-width="400"
-  offset="20"
-  arrow="false">
-  <button>Custom</button>
-</snice-tooltip>
-```
-
-## Features
-
-- Portal rendering (appends to body)
-- Smart viewport detection & auto-repositioning
-- 12 position options with alignment
-- 4 trigger modes
-- Show/hide delays
-- Arrow indicator
-- Click-outside detection (click trigger)
-- Custom max-width, offset, z-index
-- Accessibility: role="tooltip"
-- Focus restoration
-
-## Patterns
-
-**Help icon:**
-```html
-<snice-tooltip content="Help text">
-  <span>?</span>
-</snice-tooltip>
 ```
-
-**Disabled button:**
-```html
-<snice-tooltip content="Fill form first">
-  <span>
-    <button disabled>Submit</button>
-  </span>
-</snice-tooltip>
-```
-
-**Truncated text:**
-```html
-<snice-tooltip content="Full text here">
-  <div class="truncated">Full text...</div>
-</snice-tooltip>
-```
-
-**Programmatic:**
-```typescript
-const tip = document.querySelector('snice-tooltip');
-tip.show();
-tip.hide();
-tip.toggle();
-tip.updatePosition(); // After layout change
-```
-
-## Smart Positioning
-
-Auto-repositions if tooltip would overflow viewport. Tries alternative positions in order:
-- Top → Bottom → Left → Right
-- Bottom → Top → Left → Right
-- Left → Right → Top → Bottom
-- Right → Left → Top → Bottom
-
-Disable with `strict-positioning` attribute.
-
-## Notes
-
-- Disabled elements need wrapper span (no events)
-- Portal created in document.body
-- Hover doesn't work on touch devices
-- Content should be brief (not interactive)
-- Use `trigger="manual"` with `open` for programmatic control

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

@@ -0,0 +1,57 @@
+# snice-treemap
+
+Hierarchical data as nested rectangles with squarified layout and drill-down.
+
+## Properties
+
+```typescript
+data: TreemapNode = { label: '', value: 0 };
+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
+
+interface TreemapNode {
+  label: string;
+  value: number;
+  children?: TreemapNode[];
+  color?: string;
+}
+```
+
+## 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
+
+```html
+<snice-treemap id="map" show-labels show-values style="height: 400px;"></snice-treemap>
+<script>
+  document.getElementById('map').data = {
+    label: 'Root',
+    value: 0,
+    children: [
+      { label: 'A', value: 50 },
+      { label: 'B', value: 30, color: '#e74c3c' },
+      { label: 'C', value: 20, children: [
+        { label: 'C1', value: 12 },
+        { label: 'C2', value: 8 }
+      ]}
+    ]
+  };
+</script>
+
+<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})`);
+});
+```