snice 4.28.0 → 4.30.0

package/docs/ai/components/metric-table.md

@@ -4,29 +4,29 @@ Compact metrics table with sparklines, color-coded values, and built-in sorting.
 
 ## Properties
 
-```typescript
-columns: MetricColumn[] = [];
-data: Record<string, any>[] = [];
-sortBy: string = '';           // attr: sort-by
-sortDirection: 'asc'|'desc' = 'desc';  // attr: sort-direction
+```ts
+columns: MetricColumn[] = [];                    // JS only
+data: Record<string, any>[] = [];                // JS only
+sortBy: string = '';
+sortDirection: 'asc'|'desc' = 'desc';
 ```
 
 ## Types
 
-```typescript
+```ts
 interface MetricColumn {
   key: string;
   label: string;
   type?: 'text'|'number'|'percent'|'currency';
-  format?: string;       // Currency code for 'currency' type (default: 'USD')
+  format?: string;       // Currency code (default: 'USD')
   sparkline?: boolean;   // Render array values as sparkline
 }
 ```
 
 ## Events
 
-- `sort-change` -> `{ sortBy: string, sortDirection: 'asc'|'desc' }`
-- `row-click` -> `{ row: Record<string, any>, index: number }`
+- `sort-change` → `{ sortBy: string, sortDirection: 'asc'|'desc' }`
+- `row-click` → `{ row: Record<string, any>, index: number }`
 
 ## CSS Parts
 
@@ -34,7 +34,11 @@ interface MetricColumn {
 - `table` - Table element
 - `row` - Table row
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/metric-table/snice-metric-table';
+```
 
 ```html
 <snice-metric-table sort-by="value"></snice-metric-table>
@@ -53,14 +57,3 @@ el.data = [
   { name: 'Bounce Rate', value: 34.2, change: -2.5, revenue: null, trend: [40, 38, 35, 33] }
 ];
 ```
-
-## Features
-
-- Column types: text, number, percent, currency
-- Inline SVG sparklines from array data
-- Positive values green, negative values red
-- Click column headers to sort (toggles asc/desc)
-- Compact row density
-- Currency formatting with locale
-- Null/undefined shown as em-dash
-- Keyboard accessible rows

package/docs/ai/components/modal.md

@@ -4,35 +4,48 @@ Dialog overlay with focus trap, backdrop dismiss, and accessibility.
 
 ## Properties
 
-```typescript
+```ts
 open: boolean = false;
 size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
 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
-noHeader: boolean = false;           // attr: no-header — hides header entirely
-noFooter: boolean = false;           // attr: no-footer — hides footer entirely
+noHeader: boolean = false;           // attr: no-header
+noFooter: boolean = false;           // attr: no-footer
 label: string = '';                  // Accessible label
 ```
 
-## Slots
+## Methods
 
-- `(default)` - Modal body content
-- `header` - Header content (title)
-- `footer` - Footer content (action buttons)
+- `show()` → Open modal
+- `close()` → Close modal
 
 ## Events
 
 - `modal-open` → `{ modal: SniceModalElement }`
 - `modal-close` → `{ modal: SniceModalElement }`
 
-## Methods
+## Slots
+
+- `(default)` - Modal body content
+- `header` - Header content (title)
+- `footer` - Footer content (action buttons)
+
+## CSS Parts
 
-- `show()` - Open modal
-- `close()` - Close modal
+- `backdrop` - Backdrop overlay
+- `panel` - Modal panel container
+- `header` - Header section
+- `close` - Close button
+- `body` - Body content section
+- `footer` - Footer section
 
-## Usage
+## Basic Usage
+
+```typescript
+import 'snice/components/modal/snice-modal';
+```
 
 ```html
 <snice-modal label="Confirm Action">
@@ -51,11 +64,7 @@ modal.close();
 modal.addEventListener('modal-close', () => console.log('Closed'));
 ```
 
-## CSS Parts
+## Keyboard Navigation
 
-- `backdrop` - The backdrop overlay
-- `panel` - The modal panel container
-- `header` - Header section
-- `close` - Close button
-- `body` - Body content section
-- `footer` - Footer section
+- Escape closes (unless `no-escape-dismiss`)
+- Tab/Shift+Tab cycle focus within modal

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;
+}
+```