snice 4.28.0 → 4.29.0

package/docs/ai/components/paint.md

@@ -1,126 +1,88 @@
 # snice-paint
 
-Self-contained drawing canvas with built-in toolbar.
+Self-contained drawing canvas with built-in toolbar for colors, brush size, eraser, undo/redo, and clear.
 
 ## Properties
 
 ```typescript
-colors: string[] = ['#3b82f6','#ef4444','#10b981','#f59e0b','#8b5cf6','#ec4899','#e2e8f0','#1e293b'];
 color: string = '#3b82f6';
-strokeWidth: number = 3;
-minStrokeWidth: number = 1;
-maxStrokeWidth: number = 20;
+strokeWidth: number = 3;                              // attr: stroke-width
+minStrokeWidth: number = 1;                           // attr: min-stroke-width
+maxStrokeWidth: number = 20;                          // attr: max-stroke-width
 controls: string = 'colors,size,eraser,undo,redo,clear';
-backgroundColor: string = '#ffffff';
-colorSelects: number = 0; // extra color-picker dots in palette
+backgroundColor: string = '#ffffff';                  // attr: background-color
+colorSelects: number = 0;                             // attr: color-selects, extra color picker dots
 disabled: boolean = false;
+colors: string[];  // getter/setter, default: ['#3b82f6','#ef4444','#10b981','#f59e0b','#8b5cf6','#ec4899','#e2e8f0','#1e293b']
 ```
 
-## Controls
-
-Comma-separated in `controls` attribute:
-- `colors` — color swatch grid
-- `size` — brush size slider
-- `eraser` — eraser toggle
-- `undo` — undo button
-- `redo` — redo button
-- `clear` — clear button
-
 ## Methods
 
-```typescript
-undo(): void
-redo(): void
-clear(): void
-toDataURL(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): string
-toBlob(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<Blob>
-download(filename?: string): void
-getStrokes(): PaintStroke[]
-setStrokes(strokes: PaintStroke[]): void
-```
-
-## PaintStroke
-
-```typescript
-interface PaintStroke {
-  id: string;
-  tool: 'pen' | 'eraser';
-  color: string;
-  width: number;
-  points: Point[];
-  timestamp: number;
-}
-```
+- `undo()` - Undo last stroke
+- `redo()` - Redo last undone stroke
+- `clear()` - Clear canvas
+- `toDataURL(type?, quality?)` - Export as data URL
+- `toBlob(type?, quality?)` - Export as Blob (async)
+- `download(filename?)` - Download as image file
+- `getStrokes()` - Get copy of all strokes
+- `setStrokes(strokes)` - Replace all strokes
 
 ## Events
 
-- `paint-start` — Drawing started (detail: { point })
-- `paint-end` — Stroke completed (detail: { stroke })
-- `paint-clear` — Canvas cleared
-- `paint-undo` — Undo performed
-- `paint-redo` — Redo performed
-- `color-select` — Custom color picked (detail: { color, index })
+- `paint-start` → `{ point: Point }` - Drawing started
+- `paint-end` → `{ stroke: PaintStroke }` - Stroke completed
+- `paint-clear` → `{}` - Canvas cleared
+- `paint-undo` → `{}` - Undo performed
+- `paint-redo` → `{}` - Redo performed
+- `color-select` → `{ color: string, index: number }` - Custom color picked
 
 ## Slots
 
-| Slot | Behavior | Description |
-|------|----------|-------------|
-| `toolbar-start` | Additive | Content prepended above default controls |
-| `colors` | Replaces default | Replaces built-in color swatches |
-| `size` | Replaces default | Replaces built-in size slider |
-| `tools` | Additive | Custom tool buttons (between eraser and undo/redo) |
-| `toolbar-end` | Additive | Content appended below default controls |
+- `toolbar-start` - Content prepended before default controls
+- `colors` - Replaces built-in color swatches
+- `size` - Replaces built-in size slider
+- `tools` - Custom tool buttons (between eraser and undo/redo)
+- `toolbar-end` - Content appended after default controls
 
-Toolbar auto-shows when any slot has content, even if `controls=""`.
+## CSS Parts
 
-**CSS Parts:**
-- `base` - The outer paint container
-- `toolbar` - The toolbar with controls
-- `canvas-wrap` - The canvas wrapper element
-- `canvas` - The drawing canvas element
+- `base` - Outer paint container
+- `toolbar` - Toolbar with controls
+- `canvas-wrap` - Canvas wrapper element
+- `canvas` - Drawing canvas element
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-paint></snice-paint>
-
-<!-- Custom colors -->
-<snice-paint colors='["#ff0000","#00ff00","#0000ff"]'></snice-paint>
-
-<!-- Minimal controls -->
-<snice-paint controls="colors,undo"></snice-paint>
-
-<!-- Custom size range -->
-<snice-paint min-stroke-width="2" max-stroke-width="50"></snice-paint>
 ```
 
 ```typescript
+import 'snice/components/paint/snice-paint';
+
 // Export
 paint.download('artwork.png');
-const url = paint.toDataURL();
-
-// Save/load
 const strokes = paint.getStrokes();
 paint.setStrokes(strokes);
 ```
 
-```html
-<!-- Custom color pickers in palette -->
-<snice-paint color-selects="2"></snice-paint>
-
-<!-- Custom tools -->
-<snice-paint>
-  <button slot="tools" onclick="...">Rectangle</button>
-  <button slot="tools" onclick="...">Circle</button>
-</snice-paint>
-
-<!-- Replace color picker -->
-<snice-paint>
-  <input slot="colors" type="color" onchange="this.closest('snice-paint').color = this.value">
-</snice-paint>
-
-<!-- Add save button -->
-<snice-paint>
-  <button slot="toolbar-end" onclick="this.closest('snice-paint').download()">Save</button>
-</snice-paint>
+## Accessibility
+
+- Canvas supports pointer events for drawing
+- Toolbar buttons have title attributes for tooltips
+- Disabled state prevents all drawing interaction
+
+## Types
+
+```typescript
+interface Point { x: number; y: number; }
+interface PaintStroke {
+  id: string;
+  tool: 'pen' | 'eraser';
+  color: string;
+  width: number;
+  points: Point[];
+  timestamp: number;
+}
+type PaintControl = 'colors' | 'size' | 'eraser' | 'undo' | 'redo' | 'clear';
 ```

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

@@ -1,61 +1,60 @@
 # snice-pdf-viewer
 
-PDF document viewer with toolbar (page navigation, zoom, fit modes, download, print). Uses a vendored PDF.js bundle.
+PDF document viewer with toolbar for page navigation, zoom, fit modes, download, and print. Uses vendored PDF.js.
 
 ## 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
+```typescript
+src: string = '';                                    // PDF file URL
+page: number = 1;                                    // Current page number
+zoom: number = 1;                                    // Zoom level (0.25-5)
+fit: 'width'|'height'|'page' = 'width';             // Fit mode
+readonly totalPages: number = 0;                     // 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
+- `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
-
-**CSS Parts:**
-- `base` - The outer viewer container
-- `toolbar` - The navigation and zoom toolbar
-- `viewport` - The PDF page display area
+- `page-change` → `{ page: number, totalPages: number }` - Page navigation
+- `pdf-loaded` → `{ totalPages: number }` - Document loaded
+- `pdf-error` → `{ error: string }` - Loading or rendering error
 
-## Keyboard Shortcuts
+## CSS Parts
 
-- `ArrowRight` / `PageDown` -- Next page
-- `ArrowLeft` / `PageUp` -- Previous page
-- `Ctrl/Cmd +` -- Zoom in
-- `Ctrl/Cmd -` -- Zoom out
+- `base` - Outer viewer container
+- `toolbar` - Navigation and zoom toolbar
+- `viewport` - PDF page display area
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-pdf-viewer
-  src="/documents/report.pdf"
-  fit="width"
-  zoom="1"
-></snice-pdf-viewer>
+<snice-pdf-viewer src="/documents/report.pdf" fit="width"></snice-pdf-viewer>
 ```
 
 ```typescript
-viewer.src = '/documents/report.pdf';
+import 'snice/components/pdf-viewer/snice-pdf-viewer';
 
 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}`);
-});
 ```
+
+## Keyboard Navigation
+
+- `ArrowRight` / `PageDown` - Next page
+- `ArrowLeft` / `PageUp` - Previous page
+- `Ctrl/Cmd +` - Zoom in
+- `Ctrl/Cmd -` - Zoom out
+
+## Accessibility
+
+- Container is keyboard-focusable with `tabindex="0"`
+- Toolbar buttons have title attributes
+- Page input allows direct page navigation

package/docs/ai/components/permission-matrix.md

@@ -5,31 +5,36 @@ Role/permission grid with checkbox toggles for managing access control.
 ## Properties
 
 ```typescript
-roles: PermissionRole[] = [];        // { id, name, description? }
-permissions: Permission[] = [];      // { id, name, group?, description? }
-matrix: PermissionMatrix = {};       // { [roleId]: string[] } (permission IDs)
+roles: PermissionRole[] = [];        // attr: none (JS only)
+permissions: Permission[] = [];      // attr: none (JS only)
+matrix: PermissionMatrix = {};       // attr: none (JS only), { [roleId]: string[] }
 readonly: boolean = false;
 ```
 
+## Methods
+
+- `getMatrix()` - Returns deep copy of current matrix
+- `setMatrix(matrix: PermissionMatrix)` - Replace entire matrix
+- `hasPermission(roleId: string, permId: string)` - Check if role has permission
+
 ## Events
 
-- `permission-toggle` -> `{ roleId: string, permissionId: string, granted: boolean }`
-- `matrix-change` -> `{ matrix: PermissionMatrix }`
+- `permission-toggle` → `{ roleId: string, permissionId: string, granted: boolean }` - Checkbox toggled
+- `matrix-change` → `{ matrix: PermissionMatrix }` - Matrix updated
 
-## Methods
+## CSS Parts
 
-- `getMatrix()` - Returns deep copy of current matrix
-- `setMatrix(matrix)` - Replace entire matrix
-- `hasPermission(roleId, permId)` - Check if role has permission
+- `base` - Outer container
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-permission-matrix id="pm"></snice-permission-matrix>
-<snice-permission-matrix id="pm-ro" readonly></snice-permission-matrix>
 ```
 
 ```typescript
+import 'snice/components/permission-matrix/snice-permission-matrix';
+
 pm.roles = [
   { id: 'admin', name: 'Admin', description: 'Full access' },
   { id: 'editor', name: 'Editor' },
@@ -46,28 +51,18 @@ pm.matrix = {
   editor: ['create', 'read', 'update'],
   viewer: ['read']
 };
-
-// Listen for changes
-pm.addEventListener('permission-toggle', (e) => {
-  console.log(e.detail.roleId, e.detail.permissionId, e.detail.granted);
-});
-
-// Query
-pm.hasPermission('admin', 'delete'); // true
-pm.getMatrix(); // returns deep copy
 ```
 
-## CSS Parts
+## Accessibility
 
-- `base` - Outer container
+- Table uses `role="grid"` with `aria-label`
+- Checkboxes have accessible labels (e.g., "Grant Create for Admin")
+- Readonly mode shows check/dash indicators instead of checkboxes
 
-## Features
+## Types
 
-- Rows = roles, columns = permissions
-- Checkbox toggles for editable mode
-- Check/dash indicators for readonly mode
-- Role descriptions shown inline
-- Permission descriptions in headers
-- Sticky first column and header row
-- Accessible ARIA labels on checkboxes
-- Deep-copy getMatrix() for safe reads
+```typescript
+interface PermissionRole { id: string; name: string; description?: string; }
+interface Permission { id: string; name: string; group?: string; description?: string; }
+type PermissionMatrix = { [roleId: string]: string[] };
+```

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

@@ -4,95 +4,89 @@ Full-featured podcast player with playback controls, episode list, chapters, RSS
 
 ## Properties
 
-```ts
-src: string                              // Audio source URL
-fromRss: string                          // RSS feed URL (attr: from-rss)
-title: string                            // Episode title
-show: string                             // Show/podcast name
-artwork: string                          // Artwork image URL
-description: string                      // Episode description
-playbackRate: number                     // Speed 0.5-2 (default: 1, attr: playback-rate)
-skipForward: number                      // Skip forward seconds (default: 30, attr: skip-forward)
-skipBack: number                         // Skip back seconds (default: 15, attr: skip-back)
-currentTime: number                      // Current playback position (attr: current-time)
-duration: number                         // Episode duration in seconds
-volume: number                           // Volume 0-1 (default: 1)
-muted: boolean                           // Muted state
-state: PodcastPlayerState                // 'playing'|'paused'|'stopped'|'loading'|'error'
-episodes: PodcastEpisode[]               // Episode list
-currentEpisodeIndex: number              // Active episode index (attr: current-episode-index)
-sleepTimer: number                       // Sleep timer minutes (attr: sleep-timer)
-```
-
-### Types
-
-```ts
-interface PodcastEpisode {
-  title: string;
-  src: string;
-  artwork?: string;
-  description?: string;
-  pubDate?: string;
-  duration?: number;
-  chapters?: PodcastChapter[];
-}
-
-interface PodcastChapter {
-  title: string;
-  startTime: number;
-  endTime?: number;
-  artwork?: string;
-}
+```typescript
+src: string = '';                                    // Audio source URL
+fromRss: string = '';                                // RSS feed URL (attr: from-rss)
+title: string = '';                                  // Episode title
+show: string = '';                                   // Show/podcast name
+artwork: string = '';                                // Artwork image URL
+description: string = '';                            // Episode description
+playbackRate: number = 1;                            // Speed 0.5-2 (attr: playback-rate)
+skipForward: number = 30;                            // Skip forward seconds (attr: skip-forward)
+skipBack: number = 15;                               // Skip back seconds (attr: skip-back)
+currentTime: number = 0;                             // Current position (attr: current-time)
+duration: number = 0;                                // Duration in seconds
+volume: number = 1;                                  // Volume 0-1
+muted: boolean = false;
+state: PodcastPlayerState;                           // 'playing'|'paused'|'stopped'|'loading'|'error' (not decorated)
+episodes: PodcastEpisode[] = [];                     // attr: none (JS only)
+currentEpisodeIndex: number = -1;                    // attr: current-episode-index
+sleepTimer: number = 0;                              // Sleep timer minutes (attr: sleep-timer)
 ```
 
 ## Methods
 
-- `play()` -- Start playback (async)
-- `pause()` -- Pause playback
-- `toggle()` -- Toggle play/pause
-- `seekTo(time: number)` -- Seek to time in seconds
-- `setPlaybackRate(rate: number)` -- Set speed (0.5-2)
-- `loadEpisode(index: number)` -- Load and switch to episode by index
+- `play()` - Start playback (async)
+- `pause()` - Pause playback
+- `toggle()` - Toggle play/pause
+- `seekTo(time: number)` - Seek to time in seconds
+- `setPlaybackRate(rate: number)` - Set speed (0.5-2)
+- `loadEpisode(index: number)` - Load and switch to episode by index
 
 ## Events
 
-- `podcast-play` -> `{ player, episode }` -- Playback started
-- `podcast-pause` -> `{ player, episode }` -- Playback paused
-- `podcast-ended` -> `{ player, episode }` -- Episode ended
-- `podcast-time-update` -> `{ player, currentTime, duration }` -- Time update
-- `podcast-rate-change` -> `{ player, rate }` -- Playback rate changed
-- `podcast-episode-change` -> `{ player, episode, index }` -- Episode switched
-- `podcast-feed-loaded` -> `{ player, feed: RSSFeedData }` -- RSS feed parsed
+- `podcast-play` → `{ player, episode }` - Playback started
+- `podcast-pause` → `{ player, episode }` - Playback paused
+- `podcast-ended` → `{ player, episode }` - Episode ended
+- `podcast-time-update` → `{ player, currentTime, duration }` - Time update
+- `podcast-rate-change` → `{ player, rate }` - Playback rate changed
+- `podcast-episode-change` → `{ player, episode, index }` - Episode switched
+- `podcast-feed-loaded` → `{ player, feed: RSSFeedData }` - RSS feed parsed
 
-**CSS Parts:**
-- `base` - Outer player container div
+## CSS Parts
+
+- `base` - Outer player container
 - `info` - Artwork and metadata section
-- `controls` - Playback controls and progress bar section
+- `controls` - Playback controls and progress bar
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Direct source -->
-<snice-podcast-player
-  src="/audio/episode.mp3"
-  title="Episode 1"
-  show="My Podcast"
-  artwork="/images/cover.jpg"
-></snice-podcast-player>
-
-<!-- From RSS feed -->
-<snice-podcast-player from-rss="https://example.com/feed.xml"></snice-podcast-player>
+<snice-podcast-player src="/audio/episode.mp3" title="Episode 1" show="My Podcast"></snice-podcast-player>
 ```
 
 ```typescript
+import 'snice/components/podcast-player/snice-podcast-player';
+
+// From RSS feed
+// <snice-podcast-player from-rss="https://example.com/feed.xml"></snice-podcast-player>
+
+// Programmatic episodes
 player.episodes = [
   { title: 'Ep 1', src: '/audio/ep1.mp3', duration: 1800 },
   { title: 'Ep 2', src: '/audio/ep2.mp3', duration: 2400,
-    chapters: [
-      { title: 'Intro', startTime: 0 },
-      { title: 'Main Topic', startTime: 120 }
-    ]
+    chapters: [{ title: 'Intro', startTime: 0 }, { title: 'Main', startTime: 120 }]
   }
 ];
 player.loadEpisode(0);
 ```
+
+## Accessibility
+
+- Play/pause, skip, and speed controls are keyboard accessible
+- Progress bar supports click seeking
+- Volume control with mute toggle
+- Episode list items indicate currently playing episode
+- Position memory via localStorage
+
+## Types
+
+```typescript
+interface PodcastEpisode {
+  title: string; src: string; artwork?: string; description?: string;
+  pubDate?: string; duration?: number; chapters?: PodcastChapter[];
+}
+interface PodcastChapter { title: string; startTime: number; endTime?: number; artwork?: string; }
+interface RSSFeedData { title: string; artwork?: string; description?: string; episodes: PodcastEpisode[]; }
+type PodcastPlayerState = 'playing' | 'paused' | 'stopped' | 'loading' | 'error';
+```

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

@@ -4,82 +4,71 @@ Pricing comparison with cards or table layout, monthly/annual toggle, and declar
 
 ## Properties
 
-```ts
-plans: PricingPlan[]                     // Plan data array
-variant: 'cards' | 'table'              // Layout variant (default: 'cards')
-annual: boolean                          // Show annual pricing (default: false)
-```
-
-### Types
-
-```ts
-interface PricingPlan {
-  name: string;
-  price: number;
-  annualPrice?: number;                  // Annual price (enables billing toggle)
-  period?: string;                       // e.g. '/mo' (default: '/mo')
-  currency?: string;                     // e.g. '$' (default: '$')
-  description?: string;
-  features: PricingFeature[];
-  cta: string;                           // Button text
-  ctaVariant?: 'primary' | 'secondary' | 'outline';
-  highlighted?: boolean;                 // Emphasize this plan
-  badge?: string;                        // e.g. 'Popular'
-}
-
-interface PricingFeature {
-  name: string;
-  included: boolean | string;            // true/false for check/x, string for custom value
-}
+```typescript
+plans: PricingPlan[] = [];                           // attr: none (JS only)
+variant: 'cards'|'table' = 'cards';
+annual: boolean = false;                             // Show annual pricing
 ```
 
-## Child Elements
-
-Supports declarative usage via `<snice-plan>` and `<snice-feature>`:
+## Components
 
-**`<snice-plan>`** attributes: `name`, `price`, `annual-price`, `period`, `currency`, `description`, `cta`, `cta-variant`, `highlighted` (boolean), `badge`
+**`<snice-plan>`** - Declarative plan child element.
+Attributes: `name`, `price`, `annual-price`, `period`, `currency`, `description`, `cta`, `cta-variant`, `highlighted` (boolean), `badge`
 
-**`<snice-feature>`** attributes: `excluded` (boolean), `value` (string for custom display)
+**`<snice-feature>`** - Declarative feature child element.
+Attributes: `excluded` (boolean), `value` (string for custom display)
 
 ## Events
 
-- `plan-select` -> `{ plan: PricingPlan; index: number; billing: 'monthly' | 'annual' }` -- CTA button clicked
+- `plan-select` → `{ plan: PricingPlan, index: number, billing: 'monthly'|'annual' }` - CTA clicked
 
 ## CSS Parts
 
-`base`, `cards`, `card`, `cta`, `toggle`, `table-wrapper`, `table`
+- `base` - Outer container
+- `cards` - Cards layout container
+- `card` - Individual plan card
+- `cta` - Call-to-action button
+- `toggle` - Billing toggle switch area
+- `table-wrapper` - Table layout wrapper
+- `table` - Comparison table element
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Declarative -->
 <snice-pricing-table>
   <snice-plan name="Free" price="0" cta="Get Started">
     <snice-feature>5 projects</snice-feature>
     <snice-feature excluded>API access</snice-feature>
-    <snice-feature value="1GB">Storage</snice-feature>
   </snice-plan>
   <snice-plan name="Pro" price="29" annual-price="24" highlighted badge="Popular" cta="Start Trial">
     <snice-feature>Unlimited projects</snice-feature>
     <snice-feature>API access</snice-feature>
-    <snice-feature value="100GB">Storage</snice-feature>
   </snice-plan>
 </snice-pricing-table>
 ```
 
 ```typescript
-table.plans = [
-  { name: 'Free', price: 0, cta: 'Get Started', features: [
-    { name: '5 projects', included: true },
-    { name: 'API access', included: false }
-  ]},
-  { name: 'Pro', price: 29, annualPrice: 24, cta: 'Start Trial', highlighted: true, badge: 'Popular', features: [
-    { name: 'Unlimited projects', included: true },
-    { name: 'API access', included: true }
-  ]}
-];
+import 'snice/components/pricing-table/snice-pricing-table';
 
 table.addEventListener('plan-select', (e) => {
   console.log(`Selected ${e.detail.plan.name} (${e.detail.billing})`);
 });
 ```
+
+## Accessibility
+
+- Tab through plans and activate CTA buttons with Enter/Space
+- Billing toggle is keyboard accessible with `role="radiogroup"`
+- Highlighted plans are visually distinguished
+
+## Types
+
+```typescript
+interface PricingPlan {
+  name: string; price: number; annualPrice?: number; period?: string;
+  currency?: string; description?: string; features: PricingFeature[];
+  cta: string; ctaVariant?: 'primary'|'secondary'|'outline';
+  highlighted?: boolean; badge?: string;
+}
+interface PricingFeature { name: string; included: boolean | string; }
+```