snice 4.27.0 → 4.29.0

package/docs/components/music-player.md

@@ -1,32 +1,25 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/music-player.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/music-player.md -->
 
 # Music Player
 `<snice-music-player>`
 
 A full-featured audio player with playlist support, shuffle, repeat modes, and volume control.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/music-player/snice-music-player';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-music-player.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `tracks` | `Track[]` | `[]` | Array of track objects |
-| `currentTrackIndex` | `number` | `0` | Index of the current track |
-| `currentTrack` | `string` | `''` | Current track ID (reflected attribute) |
-| `currentTime` | `number` | `0` | Playback position in seconds (read-only) |
-| `duration` | `number` | `0` | Track duration in seconds |
+| `tracks` | `Track[]` | `[]` | Array of track objects (set via JavaScript) |
+| `currentTrackIndex` (attr: `current-track-index`) | `number` | `0` | Index of the current track |
+| `currentTrack` (attr: `current-track`) | `string` | `''` | Current track ID |
 | `volume` | `number` | `1` | Volume level (0-1) |
 | `muted` | `boolean` | `false` | Whether audio is muted |
 | `shuffle` | `boolean` | `false` | Shuffle mode enabled |
@@ -40,6 +33,22 @@ import 'snice/components/music-player/snice-music-player';
 | `showTrackInfo` (attr: `show-track-info`) | `boolean` | `true` | Show track metadata |
 | `compact` | `boolean` | `false` | Compact layout mode |
 
+> **Note:** `currentTime` and `duration` are plain class fields (not `@property`). They are updated internally during playback. Use `seek()` to set playback position.
+
+### Track Interface
+
+```typescript
+interface Track {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: string;
+  src: string;
+  duration?: number;
+}
+```
+
 ## Methods
 
 | Method | Arguments | Description |
@@ -48,7 +57,7 @@ import 'snice/components/music-player/snice-music-player';
 | `pause()` | -- | Pause playback |
 | `stop()` | -- | Stop playback and reset position |
 | `next()` | -- | Skip to next track |
-| `previous()` | -- | Skip to previous track |
+| `previous()` | -- | Skip to previous track (restarts if >3s in) |
 | `seek()` | `time: number` | Seek to time in seconds |
 | `setVolume()` | `volume: number` | Set volume (0-1) |
 | `toggleShuffle()` | -- | Toggle shuffle mode |
@@ -60,17 +69,17 @@ import 'snice/components/music-player/snice-music-player';
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `player-play` | `{ track: Track }` | Playback started |
-| `player-pause` | `{ track: Track }` | Playback paused |
-| `player-stop` | `{ player: SniceMusicPlayerElement }` | Playback stopped |
-| `player-track-change` | `{ track: Track }` | Track changed |
-| `player-track-ended` | `{ track: Track }` | Track finished playing |
-| `player-shuffle-change` | `{ shuffle: boolean }` | Shuffle mode toggled |
-| `player-repeat-change` | `{ repeat: string }` | Repeat mode changed |
-| `player-volume-change` | `{ volume: number }` | Volume level changed |
-| `player-seek` | `{ time: number }` | Seeked to a new position |
-| `player-time-update` | `{ currentTime: number, duration: number }` | Playback time updated |
-| `player-error` | `{ error: any }` | An error occurred |
+| `player-play` | `{ player, track: Track }` | Playback started |
+| `player-pause` | `{ player, track: Track }` | Playback paused |
+| `player-stop` | `{ player }` | Playback stopped |
+| `player-track-change` | `{ player, track: Track }` | Track changed |
+| `player-track-ended` | `{ player, track: Track }` | Track finished playing |
+| `player-shuffle-change` | `{ player, shuffle: boolean }` | Shuffle mode toggled |
+| `player-repeat-change` | `{ player, repeat: RepeatMode }` | Repeat mode changed |
+| `player-volume-change` | `{ player, volume: number }` | Volume level changed |
+| `player-seek` | `{ player, time: number }` | Seeked to a new position |
+| `player-time-update` | `{ player, currentTime: number, duration: number }` | Playback time updated |
+| `player-error` | `{ player, error: Error }` | An error occurred |
 
 ## CSS Parts
 
@@ -102,10 +111,11 @@ import 'snice/components/music-player/snice-music-player';
 ```
 
 ```html
-<snice-music-player></snice-music-player>
+<snice-music-player id="player"></snice-music-player>
 ```
 
 ```typescript
+const player = document.getElementById('player');
 player.tracks = [
   { id: '1', title: 'Summer Breeze', artist: 'The Collective', src: '/audio/track1.mp3' }
 ];
@@ -115,10 +125,6 @@ player.tracks = [
 
 ### Full Player with Playlist
 
-```html
-<snice-music-player></snice-music-player>
-```
-
 ```typescript
 player.tracks = [
   {
@@ -212,17 +218,3 @@ player.addEventListener('player-error', (e) => {
   console.error('Error:', e.detail.error);
 });
 ```
-
-## Track Interface
-
-```typescript
-interface Track {
-  id: string;
-  title: string;
-  artist?: string;
-  album?: string;
-  artwork?: string;
-  src: string;
-  duration?: number;
-}
-```

package/docs/components/nav.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/nav.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/nav.md -->
 
 # Nav
 `<snice-nav>`
 
 A navigation menu that renders from placard configurations and integrates with Snice's routing system.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/nav/snice-nav';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-nav.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -32,6 +28,12 @@ import 'snice/components/nav/snice-nav';
 |--------|-----------|-------------|
 | `update()` | `placards, appContext?, currentRoute?, routeParams?` | Update navigation with placard data |
 
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Additional content rendered after the navigation |
+
 ## CSS Parts
 
 Style internal elements from outside the shadow DOM using `::part()`.
@@ -176,6 +178,14 @@ Set `is-top-level` to automatically receive placards and routes from the Snice c
 <snice-nav is-top-level></snice-nav>
 ```
 
+## Accessibility
+
+- The `<nav>` element has `role="navigation"` for screen readers
+- Active items receive `aria-current="page"`
+- Items with `description` get `aria-label` for accessible names
+- Focus-visible styles are provided for keyboard navigation
+- All navigation links are keyboard-focusable
+
 ## Placard Structure
 
 ```typescript

package/docs/components/network-graph.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/network-graph.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/network-graph.md -->
 
 # Network Graph
 `<snice-network-graph>`
 
 An SVG-based force-directed graph visualization for displaying relationships between nodes.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/network-graph/snice-network-graph';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-network-graph.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -180,6 +175,12 @@ Disable drag and zoom for a non-interactive view.
 <snice-network-graph zoom-enabled="false" drag-enabled="false"></snice-network-graph>
 ```
 
+## Accessibility
+
+- The graph container has `role="img"` with `aria-label="Network graph visualization"`
+- Hover tooltips display node label and connection count
+- Responsive via ResizeObserver
+
 ## Data Types
 
 ```typescript

package/docs/components/notification-center.md

@@ -1,43 +1,29 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/notification-center.md instead -->
-
-# Notification Center Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/notification-center.md -->
 
+# Notification Center
 `<snice-notification-center>`
 
 A bell icon with a dropdown notification panel. Displays an unread count badge, supports marking notifications as read, and allows dismissing individual items.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
-- [CSS Custom Properties](#css-custom-properties)
+- [Slots](#slots)
 - [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Types](#types)
 - [Accessibility](#accessibility)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/notification-center/snice-notification-center';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-notification-center.min.js"></script>
-```
+- [Data Types](#data-types)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `notifications` | `NotificationItem[]` | `[]` | Array of notification objects to display |
+| `notifications` | `NotificationItem[]` | `[]` | Array of notification objects to display (set via JS) |
 | `open` | `boolean` | `false` | Whether the dropdown panel is visible |
-| `icon` | `string` | `''` | Custom bell icon (URL, image file, emoji). Use slot for icon fonts. |
+| `icon` | `string` | `''` | Custom bell icon (URL, image file, or emoji). Use slot for icon fonts. |
 
 ## Methods
 
@@ -55,37 +41,11 @@ import 'snice/components/notification-center/snice-notification-center';
 | `notification-dismiss` | `{ id: string }` | Fired when a notification is dismissed |
 | `notification-read-all` | `void` | Fired when all notifications are marked as read |
 
-## CSS Custom Properties
-
-| Property | Description |
-|----------|-------------|
-| `--snice-font-family` | Font family |
-| `--snice-color-text` | Primary text color |
-| `--snice-color-primary` | Mark-all-read link color and unread highlight |
-| `--snice-color-primary-subtle` | Unread item background |
-| `--snice-color-danger` | Badge background and dismiss hover color |
-| `--snice-color-text-inverse` | Badge text color |
-| `--snice-color-text-secondary` | Message text color |
-| `--snice-color-text-tertiary` | Timestamp, empty state text, and dismiss icon color |
-| `--snice-color-border` | Panel and item border color |
-| `--snice-color-background` | Panel background color |
-| `--snice-color-background-element` | Item hover and bell hover background |
-| `--snice-shadow-lg` | Panel drop shadow |
-| `--snice-spacing-*` | Various spacing tokens |
-| `--snice-font-size-sm` | Small text size |
-| `--snice-font-size-md` | Base text size |
-| `--snice-font-weight-medium` | Medium font weight |
-| `--snice-font-weight-semibold` | Semibold font weight |
-| `--snice-font-weight-bold` | Bold font weight |
-| `--snice-border-radius-md` | Item border radius |
-| `--snice-border-radius-lg` | Panel border radius |
-| `--snice-transition-fast` | Hover transition speed |
-
 ## Slots
 
-| Slot Name | Description |
-|-----------|-------------|
-| `icon` | Custom bell icon content. Overrides the `icon` property. Useful for icon fonts (Material Symbols, Font Awesome). |
+| Name | Description |
+|------|-------------|
+| `icon` | Custom bell icon content. Overrides the `icon` property. Useful for icon fonts. |
 
 ## CSS Parts
 
@@ -103,95 +63,46 @@ snice-notification-center::part(trigger) {
   font-size: 1.5rem;
 }
 
-snice-notification-center::part(badge) {
-  background: #ef4444;
-  color: white;
-}
-
 snice-notification-center::part(panel) {
   border-radius: 0.75rem;
   box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
 }
 ```
 
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-color-primary` | Mark-all-read link color and unread highlight |
+| `--snice-color-primary-subtle` | Unread item background |
+| `--snice-color-danger` | Badge background and dismiss hover color |
+| `--snice-color-text-inverse` | Badge text color |
+| `--snice-color-text-secondary` | Message text color |
+| `--snice-color-text-tertiary` | Timestamp, empty state text, and dismiss icon color |
+| `--snice-color-border` | Panel and item border color |
+| `--snice-color-background` | Panel background color |
+| `--snice-color-background-element` | Item hover and bell hover background |
+| `--snice-shadow-lg` | Panel drop shadow |
+
 ## Basic Usage
 
 ```typescript
 import 'snice/components/notification-center/snice-notification-center';
 ```
 
-```html
-<snice-notification-center></snice-notification-center>
-```
-
-## Examples
-
-### Basic Notifications
-
-Populate the `notifications` property to display items in the dropdown panel.
-
 ```html
 <snice-notification-center id="nc"></snice-notification-center>
 
 <script type="module">
-  import 'snice/components/notification-center/snice-notification-center';
-
   const nc = document.getElementById('nc');
   nc.notifications = [
-    {
-      id: '1',
-      title: 'New message',
-      message: 'You have a new message from Sarah',
-      timestamp: '2 min ago',
-      type: 'info'
-    },
-    {
-      id: '2',
-      title: 'Build complete',
-      message: 'Production deployment succeeded',
-      timestamp: '10 min ago',
-      type: 'success',
-      read: true
-    },
-    {
-      id: '3',
-      title: 'Disk space low',
-      message: 'Server storage is at 90% capacity',
-      timestamp: '1 hour ago',
-      type: 'warning'
-    }
+    { id: '1', title: 'New message', message: 'You have a new message', timestamp: '2 min ago', type: 'info' },
+    { id: '2', title: 'Build complete', message: 'Deployment succeeded', timestamp: '10 min ago', type: 'success', read: true }
   ];
 </script>
 ```
 
-### Handling Notification Clicks
-
-Listen for the `notification-click` event to navigate or take action when a notification is clicked.
-
-```html
-<snice-notification-center id="nc"></snice-notification-center>
-
-<script type="module">
-  import 'snice/components/notification-center/snice-notification-center';
-
-  const nc = document.getElementById('nc');
-  nc.notifications = [
-    { id: '1', title: 'New order', message: 'Order #4521 placed', timestamp: 'Just now', type: 'info' },
-    { id: '2', title: 'Payment received', message: '$249.99 from Acme Corp', timestamp: '5 min ago', type: 'success' }
-  ];
-
-  nc.addEventListener('notification-click', (e) => {
-    const notification = e.detail.notification;
-    console.log('Clicked:', notification.title);
-
-    // Mark as read when clicked
-    nc.markAsRead(notification.id);
-
-    // Navigate to relevant page
-    window.location.href = `/notifications/${notification.id}`;
-  });
-</script>
-```
+## Examples
 
 ### Notification Types
 
@@ -201,8 +112,6 @@ Each `type` automatically applies a default icon if no custom `icon` is provided
 <snice-notification-center id="nc"></snice-notification-center>
 
 <script type="module">
-  import 'snice/components/notification-center/snice-notification-center';
-
   const nc = document.getElementById('nc');
   nc.notifications = [
     { id: '1', title: 'Info', message: 'System update available', timestamp: '1 min ago', type: 'info' },
@@ -213,63 +122,59 @@ Each `type` automatically applies a default icon if no custom `icon` is provided
 </script>
 ```
 
-### Dismiss and Mark All Read
-
-Use methods to manage notification state programmatically.
-
-```html
-<snice-notification-center id="nc"></snice-notification-center>
-<button id="clear-all">Clear All</button>
+### Handling Notification Clicks
 
-<script type="module">
-  import 'snice/components/notification-center/snice-notification-center';
+Listen for the `notification-click` event to navigate or take action when a notification is clicked.
 
-  const nc = document.getElementById('nc');
-  nc.notifications = [
-    { id: '1', title: 'Alert 1', message: 'First notification', timestamp: '1 min ago', type: 'info' },
-    { id: '2', title: 'Alert 2', message: 'Second notification', timestamp: '2 min ago', type: 'warning' },
-    { id: '3', title: 'Alert 3', message: 'Third notification', timestamp: '3 min ago', type: 'error' }
-  ];
+```typescript
+nc.addEventListener('notification-click', (e) => {
+  const notification = e.detail.notification;
+  console.log('Clicked:', notification.title);
+  nc.markAsRead(notification.id);
+});
+```
 
-  // Listen for individual dismissals
-  nc.addEventListener('notification-dismiss', (e) => {
-    console.log('Dismissed notification:', e.detail.id);
-  });
+### Dismiss and Mark All Read
 
-  // Listen for mark-all-read
-  nc.addEventListener('notification-read-all', () => {
-    console.log('All notifications marked as read');
-  });
+Use methods to manage notification state programmatically.
 
-  // Programmatically clear all
-  document.getElementById('clear-all').addEventListener('click', () => {
-    nc.markAllAsRead();
-  });
-</script>
+```typescript
+// Listen for individual dismissals
+nc.addEventListener('notification-dismiss', (e) => {
+  console.log('Dismissed notification:', e.detail.id);
+});
+
+// Listen for mark-all-read
+nc.addEventListener('notification-read-all', () => {
+  console.log('All notifications marked as read');
+});
+
+// Programmatically mark all as read
+nc.markAllAsRead();
 ```
 
 ### Custom Icons
 
-Override the default type-based icon with a custom emoji or text using the `icon` property.
-
-```html
-<snice-notification-center id="nc"></snice-notification-center>
-
-<script type="module">
-  import 'snice/components/notification-center/snice-notification-center';
+Override the default type-based icon with a custom emoji or text using the `icon` property on each notification item.
 
-  const nc = document.getElementById('nc');
-  nc.notifications = [
-    { id: '1', title: 'New follower', message: 'Alex started following you', timestamp: 'Just now', icon: '👤' },
-    { id: '2', title: 'Achievement unlocked', message: 'You completed 100 tasks', timestamp: '5 min ago', icon: '🏆' },
-    { id: '3', title: 'Reminder', message: 'Team standup in 15 minutes', timestamp: '10 min ago', icon: '⏰' }
-  ];
-</script>
+```typescript
+nc.notifications = [
+  { id: '1', title: 'New follower', message: 'Alex started following you', timestamp: 'Just now', icon: '\u{1F464}' },
+  { id: '2', title: 'Achievement unlocked', message: 'You completed 100 tasks', timestamp: '5 min ago', icon: '\u{1F3C6}' },
+  { id: '3', title: 'Reminder', message: 'Team standup in 15 minutes', timestamp: '10 min ago', icon: '\u{23F0}' }
+];
 ```
 
-## Types
+## Accessibility
 
-### NotificationItem
+- The bell icon is keyboard-focusable and opens the dropdown panel on click or Enter/Space
+- The unread count badge is visible for sighted users
+- Notification items in the dropdown are interactive and clickable
+- The dismiss button is accessible for keyboard navigation
+- The "Mark all as read" action is available in the panel header
+- Unread notifications are visually distinguished with a highlighted background
+
+## Data Types
 
 ```typescript
 interface NotificationItem {
@@ -282,12 +187,3 @@ interface NotificationItem {
   type?: 'info' | 'success' | 'warning' | 'error';  // Notification type (determines default icon)
 }
 ```
-
-## Accessibility
-
-- The bell icon is keyboard-focusable and opens the dropdown panel on click or Enter/Space
-- The unread count badge is visible for sighted users; the count is communicated via the badge element
-- Notification items in the dropdown are interactive and clickable
-- The dismiss button is accessible for keyboard navigation
-- The "Mark all as read" action is available as a link at the top of the panel
-- Unread notifications are visually distinguished with a highlighted background