snice 4.9.0 → 4.11.0

package/docs/components/treemap.md

@@ -1,101 +1,83 @@
-# Treemap Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/treemap.md instead)
 
-The treemap component renders hierarchical data as nested rectangles using an SVG-based squarified treemap layout algorithm. Each rectangle's area is proportional to its value, making it ideal for visualizing the relative sizes of categories within a hierarchy.
+# Treemap
+`<snice-treemap>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Examples](#examples)
-- [Accessibility](#accessibility)
-- [Best Practices](#best-practices)
+Renders hierarchical data as nested rectangles using a squarified treemap layout. Each rectangle's area is proportional to its value.
 
 ## Basic Usage
 
-```html
-<snice-treemap id="my-treemap" show-labels show-values></snice-treemap>
+```typescript
+import 'snice/components/treemap/snice-treemap';
+```
 
-<script type="module">
-  import 'snice/components/treemap/snice-treemap';
+```html
+<snice-treemap id="usage" show-labels show-values style="height: 400px;"></snice-treemap>
 
-  const treemap = document.getElementById('my-treemap');
-  treemap.data = {
+<script>
+  document.getElementById('usage').data = {
     label: 'Disk Usage',
     value: 0,
     children: [
       { label: 'Documents', value: 45 },
       { label: 'Photos', value: 30 },
       { label: 'Videos', value: 80 },
-      { label: 'Music', value: 25 },
+      { label: 'Music', value: 25 }
     ]
   };
 </script>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `data` | `TreemapNode` | `{ label: '', value: 0 }` | Hierarchical data to display |
-| `show-labels` | `boolean` | `true` | Show text labels on rectangles |
-| `show-values` | `boolean` | `false` | Show numeric values on rectangles |
-| `color-scheme` | `TreemapColorScheme` | `'default'` | Color scheme for rectangles |
-| `padding` | `number` | `2` | Padding between rectangles in pixels |
-| `animation` | `boolean` | `true` | Enable animated transitions |
-
-### TreemapNode Interface
+## Importing
 
+**ESM (bundler)**
 ```typescript
-interface TreemapNode {
-  label: string;        // Display name
-  value: number;        // Numeric value (leaf nodes)
-  children?: TreemapNode[];  // Child nodes (parent value computed from children)
-  color?: string;       // Optional custom color (overrides color scheme)
-}
+import 'snice/components/treemap/snice-treemap';
 ```
 
-### Color Schemes
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-treemap.min.js"></script>
+```
 
-| Scheme | Description |
-|--------|-------------|
-| `default` | Tableau 10 categorical palette |
-| `blue` | Sequential blues |
-| `green` | Sequential greens |
-| `purple` | Sequential purples |
-| `orange` | Sequential oranges |
-| `warm` | Warm reds/oranges |
-| `cool` | Cool teals/blues |
-| `rainbow` | Multi-hue categorical |
+## Examples
 
-## Methods
+### Color Schemes
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `drillDown` | `(node: TreemapNode) => void` | Drill into a node's children |
-| `drillUp` | `() => void` | Go back one level |
-| `drillToRoot` | `() => void` | Reset to root level |
+Use the `color-scheme` attribute to change the palette.
 
-The `drillPath` getter returns the current drill-down path as a `TreemapNode[]`.
+```html
+<snice-treemap color-scheme="blue" show-labels></snice-treemap>
+<snice-treemap color-scheme="warm" show-labels></snice-treemap>
+<snice-treemap color-scheme="rainbow" show-labels></snice-treemap>
+```
 
-## Events
+### Custom Node Colors
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `@snice/treemap-click` | `{ node: TreemapNode, depth: number }` | Fired when a rectangle is clicked |
-| `@snice/treemap-hover` | `{ node: TreemapNode, depth: number } \| null` | Fired on hover (null on leave) |
-| `@snice/treemap-drill` | `{ node: TreemapNode, path: TreemapNode[] }` | Fired when drill level changes |
+Set the `color` property on individual nodes to override the scheme.
 
-## Examples
+```javascript
+treemap.data = {
+  label: 'Budget',
+  value: 0,
+  children: [
+    { label: 'Rent', value: 1500, color: '#e74c3c' },
+    { label: 'Food', value: 600, color: '#2ecc71' },
+    { label: 'Transport', value: 300, color: '#3498db' }
+  ]
+};
+```
 
 ### Drillable Hierarchy
 
+Click a rectangle with children to drill into it. A breadcrumb trail appears for navigation.
+
 ```html
-<snice-treemap id="org" show-labels></snice-treemap>
+<snice-treemap id="org" show-labels style="height: 400px;"></snice-treemap>
 
-<script type="module">
-  const treemap = document.getElementById('org');
-  treemap.data = {
+<script>
+  document.getElementById('org').data = {
     label: 'Company',
     value: 0,
     children: [
@@ -105,7 +87,7 @@ The `drillPath` getter returns the current drill-down path as a `TreemapNode[]`.
         children: [
           { label: 'Frontend', value: 20 },
           { label: 'Backend', value: 25 },
-          { label: 'DevOps', value: 10 },
+          { label: 'DevOps', value: 10 }
         ]
       },
       {
@@ -113,86 +95,61 @@ The `drillPath` getter returns the current drill-down path as a `TreemapNode[]`.
         value: 0,
         children: [
           { label: 'Enterprise', value: 30 },
-          { label: 'SMB', value: 15 },
+          { label: 'SMB', value: 15 }
         ]
       },
-      { label: 'HR', value: 10 },
+      { label: 'HR', value: 10 }
     ]
   };
-
-  treemap.addEventListener('@snice/treemap-drill', (e) => {
-    console.log('Drilled to:', e.detail.path.map(n => n.label).join(' > '));
-  });
 </script>
 ```
 
-Click a rectangle with children to drill in. A breadcrumb trail appears for navigation.
-
-### Custom Colors
+### Programmatic Navigation
 
-```html
-<snice-treemap id="budget" show-labels show-values></snice-treemap>
-
-<script type="module">
-  document.getElementById('budget').data = {
-    label: 'Budget',
-    value: 0,
-    children: [
-      { label: 'Rent', value: 1500, color: '#e74c3c' },
-      { label: 'Food', value: 600, color: '#2ecc71' },
-      { label: 'Transport', value: 300, color: '#3498db' },
-      { label: 'Savings', value: 500, color: '#1abc9c' },
-    ]
-  };
-</script>
-```
-
-### Color Schemes
-
-```html
-<snice-treemap color-scheme="blue" show-labels></snice-treemap>
-<snice-treemap color-scheme="warm" show-labels></snice-treemap>
-<snice-treemap color-scheme="rainbow" show-labels></snice-treemap>
+```javascript
+const treemap = document.querySelector('snice-treemap');
+treemap.drillDown(node);   // Drill into a node
+treemap.drillUp();          // Go back one level
+treemap.drillToRoot();      // Reset to root
+console.log(treemap.drillPath); // Current path
 ```
 
-### Listening to Events
-
-```html
-<snice-treemap id="events" show-labels></snice-treemap>
+## Properties
 
-<script type="module">
-  const map = document.getElementById('events');
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `TreemapNode` | `{ label: '', value: 0 }` | Hierarchical data |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Show text labels |
+| `showValues` (attr: `show-values`) | `boolean` | `false` | Show numeric values |
+| `colorScheme` (attr: `color-scheme`) | `'default' \| 'blue' \| 'green' \| 'purple' \| 'orange' \| 'warm' \| 'cool' \| 'rainbow'` | `'default'` | Color scheme |
+| `padding` | `number` | `2` | Padding between rectangles (px) |
+| `animation` | `boolean` | `true` | Enable transitions |
 
-  map.addEventListener('@snice/treemap-click', (e) => {
-    console.log('Clicked:', e.detail.node.label);
-  });
+### TreemapNode Interface
 
-  map.addEventListener('@snice/treemap-hover', (e) => {
-    if (e.detail) {
-      console.log('Hovering:', e.detail.node.label);
-    }
-  });
-</script>
+```typescript
+interface TreemapNode {
+  label: string;
+  value: number;
+  children?: TreemapNode[];
+  color?: string;
+}
 ```
 
-## Accessibility
-
-- **ARIA role**: The treemap container has `role="img"` with `aria-label` from the root data label
-- **Keyboard**: Breadcrumb buttons are focusable and keyboard-accessible
-- **Tooltips**: Hover tooltips show node label and value
+## Events
 
-## Browser Support
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `treemap-click` | `{ node: TreemapNode, depth: number }` | Rectangle clicked |
+| `treemap-hover` | `{ node: TreemapNode, depth: number } \| null` | Hover enter (null on leave) |
+| `treemap-drill` | `{ node: TreemapNode, path: TreemapNode[] }` | Drill level changed |
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1, Shadow DOM, and ResizeObserver support
+## Methods
 
-## Best Practices
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `drillDown()` | `node: TreemapNode` | Drill into a node's children |
+| `drillUp()` | -- | Go back one level |
+| `drillToRoot()` | -- | Reset to root level |
 
-1. **Provide meaningful labels**: Each node should have a descriptive label
-2. **Use appropriate color schemes**: Categorical data works well with `default` or `rainbow`; sequential data with `blue`, `green`, etc.
-3. **Set a fixed height**: The treemap needs a defined height on the host element (e.g., `snice-treemap { height: 400px; }`)
-4. **Limit depth**: More than 2-3 levels of hierarchy can be hard to navigate; use drill-down for deep trees
-5. **Balance node counts**: Very many small nodes become unreadable; consider grouping small values
-6. **Custom colors**: Use the `color` property on nodes for domain-specific coloring (e.g., red for expenses, green for income)
-7. **Responsive**: The treemap auto-resizes via ResizeObserver; place it in a flexible container
-8. **Show values selectively**: Enable `show-values` when exact numbers matter; labels alone are often sufficient
+The `drillPath` getter returns the current drill-down path as `TreemapNode[]`.

package/docs/components/video-player.md

@@ -0,0 +1,336 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/video-player.md instead)
+
+# Video Player Component
+
+The video player component provides a full-featured video player with custom controls, keyboard shortcuts, picture-in-picture support, fullscreen mode, playback speed selection, and multiple visual variants. It wraps the native HTML video element with a polished, consistent UI.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Methods](#methods)
+- [Events](#events)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-video-player src="video.mp4" poster="poster.jpg"></snice-video-player>
+```
+
+```typescript
+import 'snice/components/video-player/snice-video-player';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `''` | Video source URL |
+| `poster` | `string` | `''` | Poster image URL shown before playback |
+| `autoplay` | `boolean` | `false` | Automatically start playback |
+| `muted` | `boolean` | `false` | Mute the video |
+| `loop` | `boolean` | `false` | Loop playback continuously |
+| `controls` | `boolean` | `true` | Show the custom control bar |
+| `playbackRate` (attr: `playback-rate`) | `number` | `1` | Playback speed multiplier |
+| `currentTime` (attr: `current-time`) | `number` | `0` | Current playback position in seconds |
+| `volume` | `number` | `1` | Volume level from 0 (silent) to 1 (full) |
+| `variant` | `'default' \| 'minimal' \| 'cinema'` | `'default'` | Visual style variant |
+| `duration` | `number` | _(read-only)_ | Video duration in seconds, set from video metadata |
+
+### Variants
+
+| Variant | Description |
+|---------|-------------|
+| `default` | Full controls with progress bar, playback speed selector, and PiP button |
+| `minimal` | Simplified controls without rate or PiP buttons |
+| `cinema` | Larger controls, no border radius, with box shadow for a theater-like appearance |
+
+## Slots
+
+| Slot Name | Description |
+|-----------|-------------|
+| (default) | `<source>` elements for providing multiple video formats |
+
+## Methods
+
+#### `play(): Promise<void>`
+Start video playback.
+
+```typescript
+await player.play();
+```
+
+#### `pause(): void`
+Pause video playback.
+
+```typescript
+player.pause();
+```
+
+#### `toggle(): void`
+Toggle between play and pause.
+
+```typescript
+player.toggle();
+```
+
+#### `seekTo(time: number): void`
+Seek to a specific time in seconds.
+
+```typescript
+player.seekTo(30); // Jump to 30 seconds
+```
+
+#### `requestFullscreen(): Promise<void>`
+Enter fullscreen mode.
+
+```typescript
+await player.requestFullscreen();
+```
+
+#### `exitFullscreen(): Promise<void>`
+Exit fullscreen mode.
+
+```typescript
+await player.exitFullscreen();
+```
+
+#### `requestPictureInPicture(): Promise<void>`
+Toggle picture-in-picture mode.
+
+```typescript
+await player.requestPictureInPicture();
+```
+
+#### `setPlaybackRate(rate: number): void`
+Set the playback speed.
+
+```typescript
+player.setPlaybackRate(1.5); // 1.5x speed
+```
+
+## Events
+
+### `video-play`
+Fired when playback starts.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+}
+```
+
+### `video-pause`
+Fired when playback is paused.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+}
+```
+
+### `video-ended`
+Fired when the video finishes playing.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+}
+```
+
+### `video-time-update`
+Fired periodically during playback with current position.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+  currentTime: number;
+  duration: number;
+}
+```
+
+### `video-fullscreen-change`
+Fired when fullscreen mode is toggled.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+  fullscreen: boolean;
+}
+```
+
+### `video-volume-change`
+Fired when volume or mute state changes.
+
+**Event Detail:**
+```typescript
+{
+  player: SniceVideoPlayerElement;
+  volume: number;
+  muted: boolean;
+}
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| Space / K | Toggle play/pause |
+| F | Toggle fullscreen |
+| M | Toggle mute |
+| ArrowRight | Seek forward 5 seconds |
+| ArrowLeft | Seek backward 5 seconds |
+| ArrowUp | Volume up 10% |
+| ArrowDown | Volume down 10% |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--snice-color-primary` | Progress bar fill color | `rgb(37 99 235)` |
+| `--snice-border-radius-lg` | Container border radius | `0.5rem` |
+| `--snice-transition-fast` | Control button transitions | `150ms` |
+| `--snice-transition-medium` | Controls bar fade transition | `250ms` |
+| `--snice-shadow-lg` | Cinema variant box shadow | _(theme default)_ |
+| `--snice-focus-ring-width` | Focus ring width for control buttons | _(theme default)_ |
+| `--snice-focus-ring-color` | Focus ring color for control buttons | _(theme default)_ |
+
+## Examples
+
+### Basic Video Player
+
+Play a single video file with a poster image.
+
+```html
+<snice-video-player
+  src="https://example.com/video.mp4"
+  poster="https://example.com/poster.jpg"
+></snice-video-player>
+```
+
+### Multiple Sources
+
+Provide multiple video formats for broader browser compatibility using slotted `<source>` elements.
+
+```html
+<snice-video-player poster="poster.jpg">
+  <source src="video.webm" type="video/webm">
+  <source src="video.mp4" type="video/mp4">
+</snice-video-player>
+```
+
+### Cinema Variant
+
+Use the `cinema` variant for a theater-like presentation with larger controls and box shadow.
+
+```html
+<snice-video-player
+  src="movie.mp4"
+  poster="movie-poster.jpg"
+  variant="cinema"
+></snice-video-player>
+```
+
+### Minimal Variant
+
+Use the `minimal` variant for a cleaner player with simplified controls.
+
+```html
+<snice-video-player
+  src="tutorial.mp4"
+  variant="minimal"
+></snice-video-player>
+```
+
+### Autoplay Muted
+
+Autoplay requires the video to be muted in most browsers.
+
+```html
+<snice-video-player
+  src="background-loop.mp4"
+  autoplay
+  muted
+  loop
+></snice-video-player>
+```
+
+### Event Handling
+
+Listen for player events to build custom behavior.
+
+```html
+<snice-video-player id="my-player" src="video.mp4"></snice-video-player>
+<p id="status">Ready</p>
+
+<script type="module">
+  import type { SniceVideoPlayerElement } from 'snice/components/video-player/snice-video-player.types';
+
+  const player = document.getElementById('my-player') as SniceVideoPlayerElement;
+  const status = document.getElementById('status');
+
+  player.addEventListener('video-play', () => {
+    status.textContent = 'Playing';
+  });
+
+  player.addEventListener('video-pause', () => {
+    status.textContent = 'Paused';
+  });
+
+  player.addEventListener('video-ended', () => {
+    status.textContent = 'Finished';
+  });
+
+  player.addEventListener('video-time-update', (e) => {
+    const { currentTime, duration } = e.detail;
+    const percent = Math.round((currentTime / duration) * 100);
+    status.textContent = `Playing: ${percent}%`;
+  });
+</script>
+```
+
+### Programmatic Control
+
+Control the player using JavaScript methods.
+
+```html
+<snice-video-player id="controlled-player" src="video.mp4" controls="false"></snice-video-player>
+
+<button onclick="document.getElementById('controlled-player').play()">Play</button>
+<button onclick="document.getElementById('controlled-player').pause()">Pause</button>
+<button onclick="document.getElementById('controlled-player').seekTo(0)">Restart</button>
+<button onclick="document.getElementById('controlled-player').setPlaybackRate(2)">2x Speed</button>
+```
+
+## Accessibility
+
+- **Keyboard support**: Full keyboard control with Space/K for play/pause, F for fullscreen, M for mute, and arrow keys for seeking and volume
+- **Focus indicators**: All control buttons have visible focus rings for keyboard navigation
+- **ARIA attributes**: Control buttons have appropriate ARIA labels describing their actions
+- **Screen reader support**: Current time, duration, and playback state are conveyed to assistive technology
+- **Reduced motion**: Transitions respect `prefers-reduced-motion` for users sensitive to animations
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+- Picture-in-Picture requires browser support (Chrome, Edge, Safari; limited in Firefox)
+
+## Best Practices
+
+1. **Provide a poster image**: Show a meaningful thumbnail before playback starts
+2. **Offer multiple sources**: Use `<source>` elements with WebM and MP4 for broad compatibility
+3. **Respect autoplay policies**: Autoplay requires `muted` in most browsers
+4. **Use appropriate variants**: Choose `minimal` for embedded tutorials, `cinema` for featured content
+5. **Add keyboard hints**: Consider showing keyboard shortcuts in a tooltip or help section
+6. **Handle playback errors**: Listen for error events and show fallback messaging
+7. **Set reasonable defaults**: Start with controls visible and volume at a comfortable level