snice 4.8.0 → 4.10.0

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

@@ -0,0 +1,83 @@
+# snice-network-graph
+
+SVG-based force-directed network/relationship graph visualization.
+
+## Properties
+
+```typescript
+data: NetworkGraphData = { nodes: [], edges: [] };
+layout: 'force'|'circular'|'grid' = 'force';
+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;    // Auto color-coded
+  size?: number;     // Custom radius
+  color?: string;    // Custom fill
+  x?: number;        // Fixed position (pins node)
+  y?: number;
+}
+
+interface NetworkEdge {
+  source: string;
+  target: string;
+  label?: string;
+  weight?: number;   // Stroke width
+  color?: string;
+}
+```
+
+## Events
+
+- `@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 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' },
+  ],
+};
+
+graph.addEventListener('@snice/node-click', (e) => console.log(e.detail.node));
+```
+
+## Features
+
+- Force-directed, circular, and grid layouts
+- Zoom/pan (mouse wheel + drag background)
+- Draggable nodes (pin on drag, double-click to unpin)
+- Node sizing by degree or custom `size`
+- Color coding by `group` (10-color palette)
+- Edge weight as stroke width
+- Hover highlighting (connected subgraph)
+- Tooltips with label and degree
+- Responsive via ResizeObserver
+- Accessible: role="img" with aria-label

package/docs/ai/components/notification-center.md

@@ -0,0 +1,79 @@
+# snice-notification-center
+
+Bell icon with dropdown notification panel. Shows unread badge, supports dismiss and mark-as-read.
+
+## Properties
+
+```ts
+notifications: NotificationItem[]       // Array of notification objects
+```
+
+### NotificationItem
+
+```ts
+interface NotificationItem {
+  id: string;
+  title: string;
+  message: string;
+  timestamp: string;
+  read?: boolean;
+  icon?: string;                         // Emoji/text icon (auto-set by type if omitted)
+  type?: 'info' | 'success' | 'warning' | 'error';
+}
+```
+
+## Methods
+
+- `markAsRead(id: string)` -- Mark single notification as read
+- `markAllAsRead()` -- Mark all notifications as read
+- `dismiss(id: string)` -- Remove notification from list
+
+## Events
+
+- `notification-click` -> `{ notification: NotificationItem }` -- Notification item clicked
+- `notification-dismiss` -> `{ id: string }` -- Notification dismissed
+- `notification-read-all` -> `void` -- All marked as read
+
+## CSS Custom Properties
+
+```css
+--snice-font-family
+--snice-color-text
+--snice-color-primary              /* Mark all read link, unread highlight */
+--snice-color-primary-subtle       /* Unread item background */
+--snice-color-danger               /* Badge background, dismiss hover */
+--snice-color-text-inverse         /* Badge text */
+--snice-color-text-secondary       /* Message text */
+--snice-color-text-tertiary        /* Timestamp, empty state, dismiss icon */
+--snice-color-border               /* Panel, item borders */
+--snice-color-background           /* Panel background */
+--snice-color-background-element   /* Item hover, bell hover */
+--snice-shadow-lg                  /* Panel shadow */
+--snice-spacing-*
+--snice-font-size-sm
+--snice-font-size-md
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-font-weight-bold
+--snice-border-radius-md
+--snice-border-radius-lg
+--snice-transition-fast
+```
+
+## Usage
+
+```html
+<snice-notification-center></snice-notification-center>
+```
+
+```js
+const nc = document.querySelector('snice-notification-center');
+nc.notifications = [
+  { id: '1', title: 'New message', message: 'You have a new message', timestamp: '2 min ago', type: 'info' },
+  { id: '2', title: 'Deployed', message: 'Build succeeded', timestamp: '5 min ago', type: 'success', read: true }
+];
+
+nc.addEventListener('notification-click', (e) => {
+  console.log('Clicked:', e.detail.notification);
+});
+```

package/docs/ai/components/org-chart.md

@@ -0,0 +1,62 @@
+# snice-org-chart
+
+Hierarchical organizational chart with expand/collapse, avatars, and two layout directions.
+
+## Properties
+
+```ts
+data: OrgChartNode | null                // Root node of the tree
+direction: 'top-down' | 'left-right'     // Layout direction (default: 'top-down')
+compact: boolean                         // Compact node display (default: false)
+```
+
+### OrgChartNode
+
+```ts
+interface OrgChartNode {
+  id: string;
+  name: string;
+  title?: string;                        // Job title / role
+  avatar?: string;                       // Avatar image URL
+  children?: OrgChartNode[];
+}
+```
+
+## Methods
+
+- `collapseNode(id: string)` -- Collapse a specific node
+- `expandNode(id: string)` -- Expand a specific node
+- `expandAll()` -- Expand all nodes
+- `collapseAll()` -- Collapse all nodes
+
+## Events
+
+- `node-click` -> `{ node: OrgChartNode }` -- Node clicked
+- `node-expand` -> `{ node: OrgChartNode }` -- Node expanded
+- `node-collapse` -> `{ node: OrgChartNode }` -- Node collapsed
+
+## Usage
+
+```html
+<snice-org-chart direction="top-down"></snice-org-chart>
+```
+
+```js
+const chart = document.querySelector('snice-org-chart');
+chart.data = {
+  id: 'ceo',
+  name: 'Jane Smith',
+  title: 'CEO',
+  avatar: '/avatars/jane.jpg',
+  children: [
+    { id: 'cto', name: 'Bob Jones', title: 'CTO', children: [
+      { id: 'dev1', name: 'Alice', title: 'Engineer' }
+    ]},
+    { id: 'cfo', name: 'Carol White', title: 'CFO' }
+  ]
+};
+
+chart.addEventListener('node-click', (e) => {
+  console.log('Selected:', e.detail.node.name);
+});
+```

package/docs/ai/components/pagination.md

@@ -5,46 +5,44 @@ Pagination navigation component.
 ## Properties
 
 ```typescript
-current: number = 1;         // Active page
-total: number = 1;           // Total pages
-siblings: number = 1;        // Pages shown each side of current
-showFirst: boolean = true;   // Show first button
-showLast: boolean = true;    // Show last button
-showPrev: boolean = true;    // Show previous button
-showNext: boolean = true;    // Show next button
+current: number = 1;
+total: number = 1;
+siblings: number = 1;               // Pages shown each side of current
+showFirst: boolean = true;          // attr: show-first
+showLast: boolean = true;           // attr: show-last
+showPrev: boolean = true;           // attr: show-prev
+showNext: boolean = true;           // attr: show-next
 size: 'small'|'medium'|'large' = 'medium';
 variant: 'default'|'rounded'|'text' = 'default';
 ```
 
 ## Methods
 
-```typescript
-goToPage(page: number)   // Navigate to page
-nextPage()               // Next page
-previousPage()           // Previous page
-firstPage()              // First page
-lastPage()               // Last page
-```
+- `goToPage(page: number)` - Navigate to page
+- `nextPage()` - Next page
+- `previousPage()` - Previous page
+- `firstPage()` - First page
+- `lastPage()` - Last page
 
 ## Events
 
-```typescript
-'pagination-change' // { page, previousPage }
-```
+- `pagination-change` → `{ page, previousPage }`
 
 ## Usage
 
 ```html
 <snice-pagination current="1" total="10"></snice-pagination>
+<snice-pagination total="20" siblings="3" variant="rounded" size="large"></snice-pagination>
 ```
 
 ```typescript
 pagination.addEventListener('pagination-change', (e) => {
   console.log(e.detail.page);
 });
+pagination.goToPage(5);
 ```
 
-## CSS Variables
+## CSS Custom Properties
 
 ```css
 --pagination-gap: 4px;

package/docs/ai/components/pdf-viewer.md

@@ -0,0 +1,57 @@
+# snice-pdf-viewer
+
+PDF document viewer with toolbar (page navigation, zoom, fit modes, download, print). Uses PDF.js loaded from CDN.
+
+## Properties
+
+```ts
+src: string                              // PDF file URL
+page: number                             // Current page (default: 1)
+zoom: number                             // Zoom level (default: 1, range: 0.25-5)
+fit: 'width' | 'height' | 'page'        // Fit mode (default: 'width')
+readonly totalPages: number              // Total pages in document
+```
+
+## Methods
+
+- `goToPage(page: number)` -- Navigate to specific page
+- `nextPage()` -- Go to next page
+- `prevPage()` -- Go to previous page
+- `print()` -- Open PDF in new window for printing
+- `download()` -- Trigger PDF file download
+
+## Events
+
+- `page-change` -> `{ page: number; totalPages: number }` -- Page navigation
+- `pdf-loaded` -> `{ totalPages: number }` -- Document loaded successfully
+- `pdf-error` -> `{ error: string }` -- Loading or rendering error
+
+## Keyboard Shortcuts
+
+- `ArrowRight` / `PageDown` -- Next page
+- `ArrowLeft` / `PageUp` -- Previous page
+- `Ctrl/Cmd +` -- Zoom in
+- `Ctrl/Cmd -` -- Zoom out
+
+## Usage
+
+```html
+<snice-pdf-viewer
+  src="/documents/report.pdf"
+  fit="width"
+  zoom="1"
+></snice-pdf-viewer>
+```
+
+```js
+const viewer = document.querySelector('snice-pdf-viewer');
+viewer.src = '/documents/report.pdf';
+
+viewer.addEventListener('pdf-loaded', (e) => {
+  console.log('Pages:', e.detail.totalPages);
+});
+
+viewer.addEventListener('page-change', (e) => {
+  console.log(`Page ${e.detail.page} of ${e.detail.totalPages}`);
+});
+```