snice 4.9.0 → 4.10.0

package/docs/ai/components/menu.md

@@ -8,7 +8,7 @@ Dropdown menu with items, dividers, and configurable trigger behavior.
 open: boolean = false;
 placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'right-start'|'right-end'|'left-start'|'left-end' = 'bottom-start';
 trigger: 'click'|'hover'|'manual' = 'click';
-closeOnSelect: boolean = true;
+closeOnSelect: boolean = true;       // attr: close-on-select
 distance: number = 4;
 ```
 
@@ -16,99 +16,67 @@ distance: number = 4;
 
 - `openMenu()` - Open the menu
 - `closeMenu()` - Close the menu
-- `toggleMenu()` - Toggle menu open/closed state
+- `toggleMenu()` - Toggle open/closed
 
-## Slots
+## Slots (menu)
 
-- `trigger` - Element that triggers the menu (required)
-- Default slot - Menu items and dividers
+- `trigger` - Trigger element (required)
+- `image-left` - Image before trigger
+- `image-right` - Image after trigger
+- `(default)` - Menu items and dividers
 
 ## Events
 
-- `menu-open` - Fired when menu opens (detail: { menu: SniceMenuElement })
-- `menu-close` - Fired when menu closes (detail: { menu: SniceMenuElement })
+- `menu-open` → `{ menu }`
+- `menu-close` → `{ menu }`
+- `menu-item-select` → `{ item, value }`
+
+## snice-menu-item
+
+```typescript
+value: string = '';
+disabled: boolean = false;
+selected: boolean = false;
+```
+
+Slots: `icon`, `(default)`, `shortcut`
+
+## snice-menu-divider
+
+Visual separator between items.
 
 ## Usage
 
 ```html
-<!-- Basic menu -->
 <snice-menu>
-  <button slot="trigger">Open Menu</button>
-  <snice-menu-item value="new">New File</snice-menu-item>
-  <snice-menu-item value="open">Open</snice-menu-item>
-  <snice-menu-divider></snice-menu-divider>
-  <snice-menu-item value="save">Save</snice-menu-item>
-</snice-menu>
-
-<!-- With icons and shortcuts -->
-<snice-menu>
-  <button slot="trigger">Edit</button>
-  <snice-menu-item value="cut">
-    <span slot="icon">✂️</span>
-    Cut
-    <span slot="shortcut">⌘X</span>
-  </snice-menu-item>
-  <snice-menu-item value="copy">
-    <span slot="icon">📋</span>
-    Copy
-    <span slot="shortcut">⌘C</span>
-  </snice-menu-item>
-  <snice-menu-item value="paste">
-    <span slot="icon">📄</span>
-    Paste
-    <span slot="shortcut">⌘V</span>
+  <button slot="trigger">File</button>
+  <snice-menu-item value="new">New</snice-menu-item>
+  <snice-menu-item value="save">
+    <span slot="icon">💾</span>
+    Save
+    <span slot="shortcut">⌘S</span>
   </snice-menu-item>
+  <snice-menu-divider></snice-menu-divider>
+  <snice-menu-item value="exit">Exit</snice-menu-item>
 </snice-menu>
 
-<!-- Different placements -->
-<snice-menu placement="top-start">...</snice-menu>
-<snice-menu placement="right-start">...</snice-menu>
-
 <!-- Hover trigger -->
 <snice-menu trigger="hover">...</snice-menu>
 
 <!-- Manual control -->
-<snice-menu trigger="manual" id="my-menu">...</snice-menu>
-<script>
-  document.getElementById('my-menu').openMenu();
-</script>
+<snice-menu trigger="manual" id="m">...</snice-menu>
+<script>document.getElementById('m').openMenu();</script>
 
-<!-- Keep open on select -->
+<!-- Keep open -->
 <snice-menu close-on-select="false">...</snice-menu>
 ```
 
-## snice-menu-item
-
-### Properties
-
-```typescript
-value: string = '';
-disabled: boolean = false;
-selected: boolean = false;
-```
-
-### Slots
-
-- `icon` - Icon before label
-- Default slot - Item label
-- `shortcut` - Keyboard shortcut text
-
-### Events
-
-- `menu-item-select` - Fired when item is clicked (detail: { item: SniceMenuItemElement, value: string })
-
-## snice-menu-divider
-
-Visual separator between menu items.
-
 ## Features
 
 - 8 placement options
-- Click, hover, or manual trigger modes
-- Auto-close on item selection (configurable)
+- Click, hover, or manual trigger
+- Auto-close on select (configurable)
 - Auto-close on outside click
-- Icon and shortcut support
-- Disabled state for items
-- Selected state for items
-- Keyboard accessible (aria roles)
-- Configurable distance from trigger
+- Icon and shortcut slots
+- Disabled/selected item states
+- ARIA roles (menu, menuitem)

package/docs/ai/components/modal.md

@@ -5,66 +5,49 @@ Dialog overlay with focus trap, backdrop dismiss, and accessibility.
 ## Properties
 
 ```typescript
-open: boolean = false;                        // Visibility state
+open: boolean = false;
 size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
-noBackdropDismiss: boolean = false;           // Prevent backdrop click close
-noEscapeDismiss: boolean = false;             // Prevent Escape key close
-noFocusTrap: boolean = false;                 // Disable focus trapping
-noCloseButton: boolean = false;               // Hide close button
-label: string = '';                           // Accessible label
+noBackdropDismiss: boolean = false;  // attr: no-backdrop-dismiss
+noEscapeDismiss: boolean = false;    // attr: no-escape-dismiss
+noFocusTrap: boolean = false;        // attr: no-focus-trap
+noCloseButton: boolean = false;      // attr: no-close-button
+label: string = '';                  // Accessible label
 ```
 
-## Methods
+## Slots
 
-```typescript
-show()   // Open modal
-close()  // Close modal
-```
+- `(default)` - Modal body content
+- `header` - Header content (title)
+- `footer` - Footer content (action buttons)
 
 ## Events
 
-```typescript
-'modal-open'   // Emitted when modal opens. Detail: { modal }
-'modal-close'  // Emitted when modal closes. Detail: { modal }
-```
+- `modal-open` → `{ modal: SniceModalElement }`
+- `modal-close` → `{ modal: SniceModalElement }`
 
-## Slots
+## Methods
 
-```html
-<snice-modal>
-  <div slot="header">Title</div>
-  <div>Body content</div>
-  <div slot="footer">Actions</div>
-</snice-modal>
-```
+- `show()` - Open modal
+- `close()` - Close modal
 
 ## Usage
 
-**Template syntax:**
-```typescript
-html`
-  <snice-modal
-    ?open=${this.isOpen}
-    label="Confirm Action"
-    @modal-close=${() => this.handleClose()}>
-    <span slot="header">Title</span>
-    <p>Content</p>
-    <div slot="footer">
-      <snice-button @click=${() => this.close()}>Cancel</snice-button>
-    </div>
-  </snice-modal>
-`
+```html
+<snice-modal label="Confirm Action">
+  <div slot="header"><h2>Confirm</h2></div>
+  <p>Are you sure?</p>
+  <div slot="footer">
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button onclick="this.closest('snice-modal').close()">Confirm</button>
+  </div>
+</snice-modal>
 ```
 
-**Imperative:**
 ```typescript
 const modal = document.querySelector('snice-modal');
 modal.show();
 modal.close();
-
-modal.addEventListener('modal-close', (e) => {
-  console.log('Modal closed');
-});
+modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
 
 ## Features

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

@@ -7,8 +7,8 @@ Full-featured audio player with playlist, shuffle, repeat, and volume control.
 ```typescript
 tracks: Track[] = [];
 currentTrackIndex: number = 0;
-currentTrack: string = ''; // reflected attribute
-currentTime: number = 0; // read-only, use seek()
+currentTrack: string = '';            // reflected attribute, track ID
+currentTime: number = 0;             // read-only, use seek()
 duration: number = 0;
 volume: number = 1;
 muted: boolean = false;
@@ -16,30 +16,14 @@ shuffle: boolean = false;
 repeat: 'off'|'all'|'one' = 'off';
 state: 'playing'|'paused'|'stopped'|'loading'|'error' = 'stopped';
 autoplay: boolean = false;
-showPlaylist: boolean = true;
-showControls: boolean = true;
-showVolume: boolean = true;
-showArtwork: boolean = true;
-showTrackInfo: boolean = true;
+showPlaylist: boolean = true;         // attr: show-playlist
+showControls: boolean = true;         // attr: show-controls
+showVolume: boolean = true;           // attr: show-volume
+showArtwork: boolean = true;          // attr: show-artwork
+showTrackInfo: boolean = true;        // attr: show-track-info
 compact: boolean = false;
 ```
 
-## Methods
-
-```typescript
-play(): Promise<void>
-pause(): void
-stop(): void
-next(): void
-previous(): void
-seek(time: number): void
-setVolume(volume: number): void
-toggleShuffle(): void
-setRepeat(mode: 'off'|'all'|'one'): void
-loadTrack(index: number): Promise<void>
-getCurrentTrack(): Track | null
-```
-
 ## Track Interface
 
 ```typescript
@@ -54,81 +38,45 @@ interface Track {
 }
 ```
 
+## Methods
+
+- `play()` - Start/resume playback (async)
+- `pause()` - Pause playback
+- `stop()` - Stop and reset position
+- `next()` - Skip to next track
+- `previous()` - Skip to previous track
+- `seek(time: number)` - Seek to time in seconds
+- `setVolume(volume: number)` - Set volume (0-1)
+- `toggleShuffle()` - Toggle shuffle mode
+- `setRepeat(mode: 'off'|'all'|'one')` - Set repeat mode
+- `loadTrack(index: number)` - Load track by index (async)
+- `getCurrentTrack()` - Returns current Track or null
+
 ## Events
 
-- `player-play` - Playback started
-- `player-pause` - Playback paused
-- `player-stop` - Playback stopped
-- `player-track-change` - Track changed
-- `player-track-ended` - Track ended
-- `player-shuffle-change` - Shuffle changed
-- `player-repeat-change` - Repeat mode changed
-- `player-volume-change` - Volume changed
-- `@snice/player-time-update` - Time updated
-- `player-error` - Error occurred
+- `player-play` → `{ track }`
+- `player-pause` → `{ track }`
+- `player-stop` → `{ track }`
+- `player-track-change` → `{ track }`
+- `player-track-ended` → `{ track }`
+- `player-shuffle-change` → `{ shuffle }`
+- `player-repeat-change` → `{ repeat }`
+- `player-volume-change` → `{ volume }`
+- `@snice/player-time-update` → `{ currentTime, duration }`
+- `player-error` → `{ error }`
 
 ## Usage
 
-```javascript
-// Set tracks
+```html
+<snice-music-player id="player" autoplay shuffle compact show-playlist="false"></snice-music-player>
+```
+
+```typescript
 player.tracks = [
-  {
-    id: '1',
-    title: 'Song Title',
-    artist: 'Artist Name',
-    album: 'Album Name',
-    artwork: 'https://example.com/art.jpg',
-    src: 'https://example.com/audio.mp3',
-    duration: 180
-  }
+  { id: '1', title: 'Song', artist: 'Artist', src: '/audio/track.mp3', duration: 180 }
 ];
-
-// Controls
 await player.play();
-player.pause();
-player.stop();
-player.next();
-player.previous();
 player.seek(30);
-
-// Volume
 player.setVolume(0.5);
-
-// Shuffle & repeat
-player.toggleShuffle();
 player.setRepeat('all');
-
-// Load track
-await player.loadTrack(2);
-
-// Get current
-const track = player.getCurrentTrack();
-
-// Get/set via currentTrack attribute
-console.log(player.currentTrack); // track ID
-player.currentTrack = 'track-2'; // loads track by ID
 ```
-
-```html
-<snice-music-player
-  autoplay
-  shuffle
-  compact
-  show-playlist="false">
-</snice-music-player>
-```
-
-## Features
-
-- HTML5 Audio API
-- Playlist support
-- Play/pause/stop/next/previous
-- Shuffle with randomization
-- Repeat modes: off, all, one
-- Volume control (vertical slider)
-- Progress bar with seek
-- Real-time updates
-- Track artwork & metadata
-- Compact mode
-- Event-driven
-- Clickable playlist

package/docs/ai/components/nav.md

@@ -7,33 +7,31 @@ Navigation menu from placard configurations, integrates with Snice routing.
 ```typescript
 variant: 'flat'|'hierarchical'|'grouped' = 'flat';
 orientation: 'horizontal'|'vertical' = 'horizontal';
-isTopLevel: boolean = false;              // Receive context updates
+isTopLevel: boolean = false;  // attr: is-top-level, receive context updates
 ```
 
 ## Methods
 
-```typescript
-update(placards, appContext?, currentRoute?, routeParams?)  // Update nav with placard data
-```
+- `update(placards, appContext?, currentRoute?, routeParams?)` - Update nav with placard data
 
 ## Placard Structure
 
 ```typescript
 interface Placard {
-  name: string;                    // Route identifier
-  title: string;                   // Display text
-  icon?: string;                   // Icon character
-  order?: number;                  // Sort order
-  parent?: string;                 // Parent name (hierarchical)
-  group?: string;                  // Group name (grouped)
-  show?: boolean;                  // Visibility
-  description?: string;            // Accessible label/tooltip
-  tooltip?: string;                // Hover tooltip
-  hotkeys?: string[];              // Keyboard shortcuts
-  helpUrl?: string;                // Help URL
-  searchTerms?: string[];          // Search keywords
-  attributes?: Record<string, any>; // Custom data attributes
-  visibleOn?: Function | Function[]; // Visibility guards
+  name: string;                      // Route identifier
+  title: string;                     // Display text
+  icon?: string;                     // Icon character
+  order?: number;                    // Sort order
+  parent?: string;                   // Parent name (hierarchical)
+  group?: string;                    // Group name (grouped)
+  show?: boolean;
+  description?: string;              // Accessible label/tooltip
+  tooltip?: string;
+  hotkeys?: string[];
+  helpUrl?: string;
+  searchTerms?: string[];
+  attributes?: Record<string, any>;
+  visibleOn?: Function | Function[];
 }
 ```
 
@@ -41,36 +39,24 @@ interface Placard {
 
 ```html
 <snice-nav id="nav" variant="flat" orientation="horizontal"></snice-nav>
+
+<!-- Auto context integration -->
+<snice-nav is-top-level></snice-nav>
 ```
 
 ```typescript
 const nav = document.querySelector('snice-nav');
-const placards = [
+nav.update([
   { name: 'home', title: 'Home', icon: '🏠', order: 0 },
-  { name: 'products', title: 'Products', icon: '📦', order: 1 },
-];
-nav.update(placards, undefined, 'home');
-```
-
-## Variants
-
-- **flat**: Simple list (default)
-- **hierarchical**: Nested with parent-child relationships
-- **grouped**: Organized into labeled groups
-
-## Context Integration
-
-```html
-<snice-nav is-top-level></snice-nav>
+  { name: 'products', title: 'Products', order: 1 },
+], undefined, 'home');
 ```
 
-Auto-receives placards, routes, and app context from Snice context system.
-
 ## Features
 
-- Active route tracking with `.nav__link--active` class
-- `aria-current="page"` on active links
+- Flat, hierarchical, and grouped variants
+- Active route tracking (`.nav__link--active`, `aria-current="page"`)
 - `role="navigation"` on container
 - Hotkeys via `data-hotkeys` attribute
-- Custom attributes via placard `attributes` property
 - Conditional visibility via `visibleOn` guards
+- Custom attributes via placard `attributes`

package/docs/ai/components/network-graph.md

@@ -7,24 +7,29 @@ SVG-based force-directed network/relationship graph visualization.
 ```typescript
 data: NetworkGraphData = { nodes: [], edges: [] };
 layout: 'force'|'circular'|'grid' = 'force';
-chargeStrength: number = -300;  // attribute: charge-strength
-linkDistance: number = 80;       // attribute: link-distance
-zoomEnabled: boolean = true;     // attribute: zoom-enabled
-dragEnabled: boolean = true;     // attribute: drag-enabled
-showLabels: boolean = true;      // attribute: show-labels
+chargeStrength: number = -300;   // attr: charge-strength
+linkDistance: number = 80;        // attr: link-distance
+zoomEnabled: boolean = true;      // attr: zoom-enabled
+dragEnabled: boolean = true;      // attr: drag-enabled
+showLabels: boolean = true;       // attr: show-labels
 animation: boolean = true;
 ```
 
 ## Types
 
 ```typescript
+interface NetworkGraphData {
+  nodes: NetworkNode[];
+  edges: NetworkEdge[];
+}
+
 interface NetworkNode {
   id: string;
   label?: string;
-  group?: string;
-  size?: number;
-  color?: string;
-  x?: number;
+  group?: string;    // Auto color-coded
+  size?: number;     // Custom radius
+  color?: string;    // Custom fill
+  x?: number;        // Fixed position (pins node)
   y?: number;
 }
 
@@ -32,56 +37,47 @@ interface NetworkEdge {
   source: string;
   target: string;
   label?: string;
-  weight?: number;
+  weight?: number;   // Stroke width
   color?: string;
 }
-
-interface NetworkGraphData {
-  nodes: NetworkNode[];
-  edges: NetworkEdge[];
-}
 ```
 
 ## Events
 
-```typescript
-'@snice/node-click': { node: NetworkNode }
-'@snice/edge-click': { edge: NetworkEdge }
-'@snice/node-drag': { node: NetworkNode; x: number; y: number }
-'@snice/graph-zoom': { scale: number; x: number; y: number }
-```
+- `@snice/node-click` → `{ node: NetworkNode }`
+- `@snice/edge-click` → `{ edge: NetworkEdge }`
+- `@snice/node-drag` → `{ node: NetworkNode, x: number, y: number }`
+- `@snice/graph-zoom` → `{ scale: number, x: number, y: number }`
 
 ## Usage
 
 ```html
-<snice-network-graph id="graph" layout="force" show-labels></snice-network-graph>
+<snice-network-graph id="graph" layout="force" show-labels style="height:400px"></snice-network-graph>
+```
+
+```typescript
+graph.data = {
+  nodes: [
+    { id: 'a', label: 'Node A', group: 'g1' },
+    { id: 'b', label: 'Node B', group: 'g2' },
+  ],
+  edges: [
+    { source: 'a', target: 'b', label: 'connects' },
+  ],
+};
 
-<script>
-  graph.data = {
-    nodes: [
-      { id: 'a', label: 'Node A', group: 'g1' },
-      { id: 'b', label: 'Node B', group: 'g2' },
-    ],
-    edges: [
-      { source: 'a', target: 'b', label: 'connects' },
-    ],
-  };
-</script>
+graph.addEventListener('@snice/node-click', (e) => console.log(e.detail.node));
 ```
 
 ## Features
 
-- Force-directed layout simulation (repulsion + attraction + centering)
-- Circular and grid static layouts
-- Zoom and pan (mouse wheel + drag on background)
+- Force-directed, circular, and grid layouts
+- Zoom/pan (mouse wheel + drag background)
 - Draggable nodes (pin on drag, double-click to unpin)
-- Curves for multi-edges between same node pairs
 - Node sizing by degree or custom `size`
-- Color coding by `group` with 10-color palette
-- Custom colors on individual nodes/edges
+- Color coding by `group` (10-color palette)
 - Edge weight as stroke width
-- Labels on nodes and edges
-- Hover highlighting (connected subgraph, dimmed unconnected)
-- Tooltips showing label and degree
-- Responsive sizing via ResizeObserver
+- Hover highlighting (connected subgraph)
+- Tooltips with label and degree
+- Responsive via ResizeObserver
 - Accessible: role="img" with aria-label