snice 4.28.0 → 4.29.0

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

@@ -4,29 +4,29 @@ Full-featured audio player with playlist, shuffle, repeat, and volume control.
 
 ## Properties
 
-```typescript
-tracks: Track[] = [];
-currentTrackIndex: number = 0;
-currentTrack: string = '';            // reflected attribute, track ID
-currentTime: number = 0;             // read-only, use seek()
-duration: number = 0;
+```ts
+tracks: Track[] = [];                              // JS only
+currentTrackIndex: number = 0;                     // attr: current-track-index
+currentTrack: string = '';                         // attr: current-track, track ID
 volume: number = 1;
 muted: boolean = false;
 shuffle: boolean = false;
 repeat: 'off'|'all'|'one' = 'off';
 state: 'playing'|'paused'|'stopped'|'loading'|'error' = 'stopped';
 autoplay: boolean = false;
-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
+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;
 ```
 
-## Track Interface
+> `currentTime` and `duration` are plain class fields, not `@property`. Use `seek()` to set position.
 
-```typescript
+## Types
+
+```ts
 interface Track {
   id: string;
   title: string;
@@ -36,42 +36,50 @@ interface Track {
   src: string;
   duration?: number;
 }
+
+type RepeatMode = 'off' | 'all' | 'one';
+type PlayerState = 'playing' | 'paused' | 'stopped' | 'loading' | 'error';
 ```
 
 ## 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
+- `play()` → Start/resume (async)
+- `pause()` → Pause
+- `stop()` → Stop and reset position
+- `next()` → Next track
+- `previous()` → Previous track (restarts if >3s in)
+- `seek(time)` → Seek to seconds
+- `setVolume(volume)` → Set volume (0-1)
+- `toggleShuffle()` → Toggle shuffle
+- `setRepeat(mode)` → Set repeat mode
+- `loadTrack(index)` → Load track by index (async)
+- `getCurrentTrack()` → Current Track or null
 
 ## Events
 
-- `player-play` → `{ track }`
-- `player-pause` → `{ track }`
+- `player-play` → `{ player, track }`
+- `player-pause` → `{ player, track }`
 - `player-stop` → `{ player }`
-- `player-track-change` → `{ track }`
-- `player-track-ended` → `{ track }`
-- `player-shuffle-change` → `{ shuffle }`
-- `player-repeat-change` → `{ repeat }`
-- `player-volume-change` → `{ volume }`
-- `player-seek` → `{ time }`
-- `player-time-update` → `{ currentTime, duration }`
-- `player-error` → `{ error }`
-
-**CSS Parts:**
-- `base` - Outer player container div
-- `controls` - Playback controls and progress bar section
-- `playlist` - Playlist section with track list
-
-## Usage
+- `player-track-change` → `{ player, track }`
+- `player-track-ended` → `{ player, track }`
+- `player-shuffle-change` → `{ player, shuffle }`
+- `player-repeat-change` → `{ player, repeat }`
+- `player-volume-change` → `{ player, volume }`
+- `player-seek` → `{ player, time }`
+- `player-time-update` → `{ player, currentTime, duration }`
+- `player-error` → `{ player, error }`
+
+## CSS Parts
+
+- `base` - Outer player container
+- `controls` - Playback controls and progress bar
+- `playlist` - Playlist section
+
+## Basic Usage
+
+```typescript
+import 'snice/components/music-player/snice-music-player';
+```
 
 ```html
 <snice-music-player id="player" autoplay shuffle compact show-playlist="false"></snice-music-player>

package/docs/ai/components/nav.md

@@ -14,28 +14,18 @@ isTopLevel: boolean = false;  // attr: is-top-level, receive context updates
 
 - `update(placards, appContext?, currentRoute?, routeParams?)` - Update nav with placard data
 
-## Placard Structure
+## Slots
 
-```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;
-  description?: string;              // Accessible label/tooltip
-  tooltip?: string;
-  hotkeys?: string[];
-  helpUrl?: string;
-  searchTerms?: string[];
-  attributes?: Record<string, any>;
-  visibleOn?: Function | Function[];
-}
-```
+- `(default)` - Additional content after navigation
+
+## CSS Parts
+
+- `base` - Outer content wrapper
+- `nav` - Navigation element
+- `link` - Individual nav link
+- `icon` - Nav item icon (img or span)
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-nav id="nav" variant="flat" orientation="horizontal"></snice-nav>
@@ -51,17 +41,30 @@ nav.update([
 ], undefined, 'home');
 ```
 
-**CSS Parts:**
-- `base` - Outer content wrapper
-- `nav` - Navigation element
-- `link` - Individual nav link
-- `icon` - Nav item icon (img or span)
+## Examples
+
+```typescript
+// Hierarchical
+nav.update([
+  { name: 'products', title: 'Products', order: 0 },
+  { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
+]);
+
+// Grouped
+nav.update([
+  { name: 'home', title: 'Home', group: 'Main', order: 0 },
+  { name: 'profile', title: 'Profile', group: 'Account', order: 0 },
+]);
+
+// Conditional visibility
+nav.update([
+  { name: 'admin', title: 'Admin', visibleOn: (ctx) => ctx.user?.isAdmin },
+], { user: { isAdmin: true } });
+```
 
-## Features
+## Accessibility
 
-- Flat, hierarchical, and grouped variants
-- Active route tracking (`.nav__link--active`, `aria-current="page"`)
 - `role="navigation"` on container
-- Hotkeys via `data-hotkeys` attribute
-- Conditional visibility via `visibleOn` guards
-- Custom attributes via placard `attributes`
+- `aria-current="page"` on active item
+- `aria-label` from placard `description`
+- Focus-visible styles for keyboard navigation

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

@@ -15,33 +15,6 @@ 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
 
 - `node-click` → `{ node: NetworkNode }`
@@ -49,7 +22,13 @@ interface NetworkEdge {
 - `node-drag` → `{ node: NetworkNode, x: number, y: number }`
 - `graph-zoom` → `{ scale: number, x: number, y: number }`
 
-## Usage
+## CSS Parts
+
+- `base` - The outer graph container
+- `canvas` - The SVG element
+- `tooltip` - The hover tooltip element
+
+## Basic Usage
 
 ```html
 <snice-network-graph id="graph" layout="force" show-labels style="height:400px"></snice-network-graph>
@@ -69,20 +48,26 @@ graph.data = {
 graph.addEventListener('node-click', (e) => console.log(e.detail.node));
 ```
 
-**CSS Parts:**
-- `base` - The outer graph container
-- `canvas` - The SVG element
-- `tooltip` - The hover tooltip element
+## Examples
+
+```html
+<!-- Static display -->
+<snice-network-graph zoom-enabled="false" drag-enabled="false"></snice-network-graph>
+
+<!-- Custom force tuning -->
+<snice-network-graph charge-strength="-500" link-distance="120"></snice-network-graph>
+```
 
-## Features
+## Accessibility
 
-- 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
+- `role="img"` with `aria-label` on container
+- Hover tooltips with label and degree
 - Responsive via ResizeObserver
-- Accessible: role="img" with aria-label
+
+## Types
+
+```typescript
+interface NetworkGraphData { nodes: NetworkNode[]; edges: NetworkEdge[]; }
+interface NetworkNode { id: string; label?: string; group?: string; size?: number; color?: string; x?: number; y?: number; }
+interface NetworkEdge { source: string; target: string; label?: string; weight?: number; color?: string; }
+```

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

@@ -4,24 +4,10 @@ Bell icon with dropdown notification panel. Shows unread badge, supports dismiss
 
 ## Properties
 
-```ts
-notifications: NotificationItem[]       // Array of notification objects
-open: boolean                           // Whether the dropdown panel is visible (default: false)
-icon: string                            // Custom bell icon (URL, image file, emoji) (default: '')
-```
-
-### 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';
-}
+```typescript
+notifications: NotificationItem[] = [];  // attr: none (JS only)
+open: boolean = false;                   // Panel visibility
+icon: string = '';                       // Custom bell icon (URL, image, emoji)
 ```
 
 ## Methods
@@ -32,8 +18,8 @@ interface NotificationItem {
 
 ## Events
 
-- `notification-click` → `{ notification: NotificationItem }` - Notification item clicked
-- `notification-dismiss` → `{ id: string }` - Notification dismissed
+- `notification-click` → `{ notification: NotificationItem }` - Item clicked
+- `notification-dismiss` → `{ id: string }` - Item dismissed
 - `notification-read-all` → `void` - All marked as read
 
 ## Slots
@@ -45,13 +31,11 @@ interface NotificationItem {
 - `trigger` - The bell icon button
 - `icon` - The bell icon span
 - `panel` - The dropdown notification panel
-- `panel-header` - The panel header with title and mark-all-read action
+- `panel-header` - Panel header with title and mark-all-read action
 
 ## 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 */
@@ -62,24 +46,17 @@ interface NotificationItem {
 --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
+## Basic Usage
 
 ```html
 <snice-notification-center></snice-notification-center>
 ```
 
 ```typescript
+import 'snice/components/notification-center/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 }
@@ -89,3 +66,24 @@ nc.addEventListener('notification-click', (e) => {
   console.log('Clicked:', e.detail.notification);
 });
 ```
+
+## Accessibility
+
+- Bell icon is keyboard-focusable
+- Unread count via badge element
+- Notification items are clickable with dismiss buttons
+- "Mark all as read" action in panel header
+
+## Types
+
+```typescript
+interface NotificationItem {
+  id: string;
+  title: string;
+  message: string;
+  timestamp: string;
+  read?: boolean;
+  icon?: string;
+  type?: 'info' | 'success' | 'warning' | 'error';
+}
+```

package/docs/ai/components/order-tracker.md

@@ -4,48 +4,38 @@ Order status timeline with step indicators, tracking info, timestamps, and descr
 
 ## Properties
 
-```ts
-steps: OrderStep[] = [];                              // Timeline steps
-trackingNumber: string = '';                           // Tracking number (attr: tracking-number)
-carrier: string = '';                                  // Carrier name
-variant: 'horizontal' | 'vertical' = 'horizontal';    // Layout orientation
-```
-
-### Types
-
-```ts
-interface OrderStep {
-  label: string;
-  status: 'pending' | 'active' | 'completed';
-  timestamp?: string;
-  description?: string;
-  icon?: string;
-}
+```typescript
+steps: OrderStep[] = [];                              // attr: none (JS only)
+trackingNumber: string = '';                           // attr: tracking-number
+carrier: string = '';
+variant: 'horizontal'|'vertical' = 'horizontal';
 ```
 
 ## Events
 
-- `step-click` -> `{ step: OrderStep; index: number }`
+- `step-click` → `{ step: OrderStep, index: number }` - Step clicked
 
 ## CSS Parts
 
-`base`, `info`, `steps`, `step`, `step-indicator`, `step-content`
+- `base` - Outer tracker container
+- `info` - Tracking info section (carrier, tracking number)
+- `steps` - Steps container
+- `step` - Individual step
+- `step-indicator` - Step number/check icon
+- `step-content` - Step label, timestamp, description
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-order-tracker
-  tracking-number="1Z999AA10123456784"
-  carrier="UPS">
-</snice-order-tracker>
+<snice-order-tracker tracking-number="1Z999AA10123456784" carrier="UPS"></snice-order-tracker>
 ```
 
 ```typescript
+import 'snice/components/order-tracker/snice-order-tracker';
+
 tracker.steps = [
   { label: 'Ordered', status: 'completed', timestamp: 'Feb 20, 2026' },
-  { label: 'Confirmed', status: 'completed', timestamp: 'Feb 20, 2026' },
-  { label: 'Shipped', status: 'active', timestamp: 'Feb 22, 2026', description: 'Package left the warehouse' },
-  { label: 'Out for Delivery', status: 'pending' },
+  { label: 'Shipped', status: 'active', timestamp: 'Feb 22, 2026', description: 'Package left warehouse' },
   { label: 'Delivered', status: 'pending' }
 ];
 
@@ -53,3 +43,22 @@ tracker.addEventListener('step-click', (e) => {
   console.log(e.detail.step.label, e.detail.index);
 });
 ```
+
+## Accessibility
+
+- Steps use `role="list"` / `role="listitem"`
+- Steps are keyboard-focusable with Enter/Space activation
+- Completed steps show check icons
+
+## Types
+
+```typescript
+type OrderStepStatus = 'pending' | 'active' | 'completed';
+interface OrderStep {
+  label: string;
+  status: OrderStepStatus;
+  timestamp?: string;
+  description?: string;
+  icon?: string;
+}
+```

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

@@ -4,54 +4,42 @@ Hierarchical organizational chart with expand/collapse, avatars, and two layout
 
 ## 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[];
-}
+```typescript
+data: OrgChartNode | null = null;                    // attr: none (JS only)
+direction: 'top-down'|'left-right' = 'top-down';
+compact: boolean = false;
 ```
 
 ## Methods
 
-- `collapseNode(id: string)` -- Collapse a specific node
-- `expandNode(id: string)` -- Expand a specific node
-- `expandAll()` -- Expand all nodes
-- `collapseAll()` -- Collapse all nodes
+- `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
+- `node-click` → `{ node: OrgChartNode }` - Node clicked
+- `node-expand` → `{ node: OrgChartNode }` - Node expanded
+- `node-collapse` → `{ node: OrgChartNode }` - Node collapsed
 
-**CSS Parts:**
-- `base` - The outer chart container
-- `tree` - The tree layout wrapper
+## CSS Parts
+
+- `base` - Outer chart container
+- `tree` - Tree layout wrapper
 - `node` - Individual node cards
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-org-chart direction="top-down"></snice-org-chart>
 ```
 
 ```typescript
+import 'snice/components/org-chart/snice-org-chart';
+
 chart.data = {
-  id: 'ceo',
-  name: 'Jane Smith',
-  title: 'CEO',
-  avatar: '/avatars/jane.jpg',
+  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' }
@@ -64,3 +52,20 @@ chart.addEventListener('node-click', (e) => {
   console.log('Selected:', e.detail.node.name);
 });
 ```
+
+## Accessibility
+
+- Nodes are clickable with expand/collapse toggle buttons
+- Avatar placeholders show name initials
+
+## Types
+
+```typescript
+interface OrgChartNode {
+  id: string;
+  name: string;
+  title?: string;
+  avatar?: string;
+  children?: OrgChartNode[];
+}
+```

package/docs/ai/components/pagination.md

@@ -1,48 +1,35 @@
 # snice-pagination
 
-Pagination navigation component.
+Pagination navigation component with page numbers, ellipsis, and navigation buttons.
 
 ## Properties
 
 ```typescript
 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
+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
 
-- `goToPage(page: number)` - Navigate to page
-- `nextPage()` - Next page
-- `previousPage()` - Previous page
-- `firstPage()` - First page
-- `lastPage()` - Last page
+- `goToPage(page: number)` - Navigate to specific page
+- `nextPage()` - Go to next page
+- `previousPage()` - Go to previous page
+- `firstPage()` - Go to first page
+- `lastPage()` - Go to last page
 
 ## Events
 
-- `pagination-change` → `{ page, previousPage }`
+- `pagination-change` → `{ page: number, previousPage: number }` - Page changed
 
-## Usage
+## CSS Parts
 
-```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 Parts:**
 - `base` - Nav container
 - `button` - All navigation buttons (shared)
 - `first-button` - First page button
@@ -61,3 +48,24 @@ pagination.goToPage(5);
 --pagination-font-size: 14px;
 --pagination-border-radius: 4px;
 ```
+
+## Basic Usage
+
+```html
+<snice-pagination current="1" total="10"></snice-pagination>
+```
+
+```typescript
+import 'snice/components/pagination/snice-pagination';
+
+pagination.addEventListener('pagination-change', (e) => {
+  console.log('Page:', e.detail.page);
+});
+```
+
+## Accessibility
+
+- Uses `<nav>` with `aria-label="Pagination"`
+- Active page has `aria-current="page"`
+- Navigation buttons have `aria-label` attributes
+- Disabled state for boundary buttons