snice 4.8.0 → 4.10.0

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

@@ -0,0 +1,94 @@
+# snice-podcast-player
+
+Full-featured podcast player with playback controls, episode list, chapters, RSS feed support, sleep timer, and position memory via localStorage.
+
+## 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;
+}
+```
+
+## 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
+
+## 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
+
+## 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>
+```
+
+```js
+const player = document.querySelector('snice-podcast-player');
+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 }
+    ]
+  }
+];
+player.loadEpisode(0);
+```

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

@@ -0,0 +1,87 @@
+# snice-pricing-table
+
+Pricing comparison with cards or table layout, monthly/annual toggle, and declarative child elements.
+
+## 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
+}
+```
+
+## Child Elements
+
+Supports declarative usage via `<snice-plan>` and `<snice-feature>`:
+
+**`<snice-plan>`** attributes: `name`, `price`, `annual-price`, `period`, `currency`, `description`, `cta`, `cta-variant`, `highlighted` (boolean), `badge`
+
+**`<snice-feature>`** attributes: `excluded` (boolean), `value` (string for custom display)
+
+## Events
+
+- `plan-select` -> `{ plan: PricingPlan; index: number; billing: 'monthly' | 'annual' }` -- CTA button clicked
+
+## CSS Parts
+
+`base`, `cards`, `card`, `cta`, `toggle`, `table-wrapper`, `table`
+
+## 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>
+```
+
+```js
+// Programmatic
+const table = document.querySelector('snice-pricing-table');
+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 }
+  ]}
+];
+
+table.addEventListener('plan-select', (e) => {
+  console.log(`Selected ${e.detail.plan.name} (${e.detail.billing})`);
+});
+```

package/docs/ai/components/progress.md

@@ -10,78 +10,62 @@ max: number = 100;
 variant: 'linear'|'circular' = 'linear';
 indeterminate: boolean = false;
 size: 'small'|'medium'|'large'|'xl'|'xxl'|'xxxl' = 'medium';
-color: 'primary'|'success'|'warning'|'error'|'info'|string = 'primary';  // semantic or any CSS color
-showLabel: boolean = false;
+color: 'primary'|'success'|'warning'|'error'|'info'|string = 'primary';
+showLabel: boolean = false;       // attr: show-label
 label: string = '';
 striped: boolean = false;
 animated: boolean = false;
-thickness: number = 4;  // Stroke width for circular variant
+thickness: number = 4;            // Stroke width for circular variant
 ```
 
 ## Methods
 
 - `setProgress(value, max?)` - Set progress value
-- `getPercentage()` - Get calculated percentage
+- `getPercentage()` - Get calculated percentage (0-100)
 
 ## Events
 
-- `progress-change` - {value, max, percentage, indeterminate}
+- `progress-change` → `{ value, max, percentage, indeterminate }`
 
 ## Usage
 
 ```html
-<!-- Basic linear -->
+<!-- Linear -->
 <snice-progress value="50"></snice-progress>
 
 <!-- Circular -->
-<snice-progress variant="circular" value="75"></snice-progress>
+<snice-progress variant="circular" value="75" size="xl"></snice-progress>
 
-<!-- Indeterminate (loading) -->
+<!-- Indeterminate -->
 <snice-progress indeterminate></snice-progress>
-<snice-progress variant="circular" indeterminate></snice-progress>
 
 <!-- With label -->
 <snice-progress value="60" show-label></snice-progress>
 <snice-progress value="60" label="Uploading..."></snice-progress>
 
-<!-- Custom max -->
-<snice-progress value="3" max="10"></snice-progress>
-
 <!-- Striped and animated -->
-<snice-progress value="70" striped></snice-progress>
 <snice-progress value="70" striped animated></snice-progress>
 
-<!-- Color variants -->
-<snice-progress value="80" color="primary"></snice-progress>
+<!-- Colors -->
 <snice-progress value="80" color="success"></snice-progress>
-
-<!-- Custom colors -->
 <snice-progress value="80" color="#3b82f6"></snice-progress>
-<snice-progress value="80" color="rgb(59, 130, 246)"></snice-progress>
-
-<!-- Sizes -->
-<snice-progress value="50" size="small"></snice-progress>
-<snice-progress value="50" size="medium"></snice-progress>
-<snice-progress value="50" size="large"></snice-progress>
-
-<!-- Dynamic updates -->
-<snice-progress id="prog" value="0"></snice-progress>
-<script>
-const prog = document.querySelector('#prog');
-let val = 0;
-setInterval(() => {
-  val = (val + 10) % 100;
-  prog.value = val;
-}, 500);
-</script>
+
+<!-- Custom max -->
+<snice-progress value="3" max="10"></snice-progress>
+```
+
+```typescript
+const prog = document.querySelector('snice-progress');
+prog.setProgress(75);
+prog.setProgress(3, 10);
+console.log(prog.getPercentage());
 ```
 
 ## Features
 
-- Linear or circular variant
+- Linear and circular variants
 - Indeterminate mode for unknown progress
-- Optional percentage label or custom text
+- Optional percentage or custom label
 - Striped and animated styles
-- 5 color variants
-- 6 sizes
-- Reactive value updates
+- 5 semantic + custom CSS colors
+- 6 sizes (small through xxxl)

package/docs/ai/components/qr-code.md

@@ -7,105 +7,58 @@ QR code generator with customizable styling and export.
 ```typescript
 value: string = '';
 size: number = 200;
-errorCorrectionLevel: 'L'|'M'|'Q'|'H' = 'M';
-renderMode: 'canvas'|'svg' = 'canvas';
+errorCorrectionLevel: 'L'|'M'|'Q'|'H' = 'M';  // attr: error-correction-level
+renderMode: 'canvas'|'svg' = 'svg';              // attr: render-mode
+dotStyle: 'square'|'rounded'|'dots' = 'square';  // attr: dot-style
 margin: number = 4;
-fgColor: string = '#000000';
-bgColor: string = '#ffffff';
-includeImage: boolean = false;
-imageUrl: string = '';
-imageSize: number = 40;
-dotStyle: 'square'|'rounded'|'dots' = 'square';
-centerText: string = '';
-centerTextSize: number = 16;
-textFillColor: string = '#000000';
-textOutlineColor: string = '#ffffff';
+fgColor: string = '#000000';                      // attr: fg-color
+bgColor: string = '#ffffff';                      // attr: bg-color
+includeImage: boolean = false;                    // attr: include-image
+imageUrl: string = '';                            // attr: image-url
+imageSize: number = 40;                           // attr: image-size
+centerText: string = '';                          // attr: center-text
+centerTextSize: number = 16;                      // attr: center-text-size
+textFillColor: string = '#000000';                // attr: text-fill-color
+textOutlineColor: string = '#ffffff';             // attr: text-outline-color
 ```
 
 ## Methods
 
-```typescript
-toDataURL(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<string>
-toBlob(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<Blob>
-download(filename?: string): void
-```
+- `toDataURL(type?, quality?)` - Export as data URL (async)
+- `toBlob(type?, quality?)` - Export as Blob (async)
+- `download(filename?)` - Download as image file
 
 ## Usage
 
-```javascript
-// Basic
-qr.value = 'https://example.com';
-qr.size = 200;
-
-// Custom colors
-qr.fgColor = '#2196f3';
-qr.bgColor = '#e3f2fd';
+```html
+<snice-qr-code value="https://example.com" size="250"></snice-qr-code>
 
-// Error correction
-qr.errorCorrectionLevel = 'H'; // L|M|Q|H
+<!-- Custom colors -->
+<snice-qr-code value="https://example.com" fg-color="#2196f3" bg-color="#e3f2fd"></snice-qr-code>
 
-// Canvas mode
-qr.renderMode = 'canvas';
+<!-- With center image -->
+<snice-qr-code value="https://example.com" include-image image-url="/logo.png" error-correction-level="H"></snice-qr-code>
 
-// With image overlay
-qr.includeImage = true;
-qr.imageUrl = 'logo.png';
-qr.imageSize = 50;
+<!-- Dot styles -->
+<snice-qr-code value="https://example.com" dot-style="rounded"></snice-qr-code>
+```
 
-// Export
-const dataURL = await qr.toDataURL('image/png', 0.92);
+```typescript
+const qr = document.querySelector('snice-qr-code');
+qr.value = 'https://example.com';
+const url = await qr.toDataURL('image/png');
 const blob = await qr.toBlob('image/png');
 qr.download('qr-code.png');
 ```
 
-```html
-<snice-qr-code
-  value="https://example.com"
-  size="250"
-  fg-color="#000000"
-  bg-color="#ffffff"
-  error-correction-level="M"
-  render-mode="svg">
-</snice-qr-code>
-```
-
-## Common Formats
+## Common Data Formats
 
-```javascript
-// URL
-qr.value = 'https://example.com';
-
-// Email
-qr.value = 'mailto:name@example.com';
-
-// Phone
-qr.value = 'tel:+1234567890';
-
-// SMS
-qr.value = 'sms:+1234567890?body=Hello';
-
-// WiFi
-qr.value = 'WIFI:T:WPA;S:NetworkName;P:password;;';
-
-// vCard
-qr.value = `BEGIN:VCARD
-VERSION:3.0
-FN:John Doe
-TEL:+1234567890
-EMAIL:john@example.com
-END:VCARD`;
-
-// Location
-qr.value = 'geo:37.7749,-122.4194';
+```typescript
+// URL:   'https://example.com'
+// Email: 'mailto:name@example.com'
+// Phone: 'tel:+1234567890'
+// SMS:   'sms:+1234567890?body=Hello'
+// WiFi:  'WIFI:T:WPA;S:NetworkName;P:password;;'
+// Geo:   'geo:37.7749,-122.4194'
+// vCard: 'BEGIN:VCARD\nVERSION:3.0\nFN:Name\nEND:VCARD'
 ```
-
-## Features
-
-- SVG/Canvas rendering
-- Custom colors
-- Error correction levels
-- Image overlay
-- Export (PNG/JPEG/WebP)
-- Download
-- Adjustable margin
-- Multiple data formats

package/docs/ai/components/qr-reader.md

@@ -2,75 +2,65 @@
 
 QR code scanner using device camera and ZXing WASM decoder.
 
-## API
-
-### Properties
-- `auto-start: boolean = false` - Auto-start scanning on mount
-- `camera: 'front'|'back' = 'back'` - Camera selection
-- `pick-first: boolean = false` - Scan at max speed until first hit, then stop and shutdown
-- `manual-snap: boolean = false` - Photo mode: open camera, manually trigger snapshots
-- `scan-speed: number = 3` - Scan speed 1-10 (higher = faster, more CPU). Ignored when pick-first=true
-- `tap-start: boolean = false` - Enable tap/click on viewport to start/stop scanning
-
-### Methods
-- `start()` - Start camera/scanning
-- `stop()` - Stop camera/scanning
-- `snap()` - Take snapshot (manual-snap mode)
+## Properties
+
+```typescript
+autoStart: boolean = false;         // attr: auto-start
+camera: 'front'|'back' = 'back';
+pickFirst: boolean = false;         // attr: pick-first, scan until first hit then stop
+manualSnap: boolean = false;        // attr: manual-snap, photo snapshot mode
+scanSpeed: number = 3;              // attr: scan-speed, 1-10 (ignored when pick-first)
+tapStart: boolean = false;          // attr: tap-start, tap viewport to start/stop
+```
+
+## Methods
+
+- `start()` - Start camera and scanning
+- `stop()` - Stop scanning and release camera
+- `snap()` - Take snapshot (manual-snap mode), returns QR data or null
 - `scanImage(file: File)` - Scan QR code from image file
-- `switchCamera()` - Toggle between front/back camera
+- `switchCamera()` - Toggle front/back camera
+
+## Events
 
-### Events
-- `qr-scan` - detail: `{data: string, timestamp: number, reader: SniceQRReader}`
-- `qr-error` - detail: `{error: any, reader: SniceQRReader}`
-- `camera-ready` - detail: `{reader: SniceQRReader}`
-- `camera-error` - detail: `{error: any, reader: SniceQRReader}`
+- `qr-scan` → `{ data: string, timestamp: number, reader }`
+- `qr-error` → `{ error: any, reader }`
+- `camera-ready` → `{ reader }`
+- `camera-error` → `{ error: any, reader }`
 
 ## Usage
 
 ```html
+<!-- Auto-start continuous scanning -->
 <snice-qr-reader auto-start></snice-qr-reader>
-<script>
-  reader.addEventListener('qr-scan', e => console.log(e.detail.data));
-</script>
+
+<!-- One-shot: scan until first hit -->
+<snice-qr-reader pick-first></snice-qr-reader>
+
+<!-- Manual snapshot mode -->
+<snice-qr-reader manual-snap></snice-qr-reader>
+
+<!-- Tap to start/stop -->
+<snice-qr-reader tap-start></snice-qr-reader>
 ```
 
-## Implementation
-
-### File Structure
-- `snice-qr-reader.ts` - Main component (camera, scanning loop)
-- `qr-worker.ts` - Web Worker for QR detection
-- `qr-decoder.ts` - ZXing WASM wrapper (legacy)
-- `zxing-reader.mjs` - ZXing ES module
-- `zxing_reader.wasm` - WASM binary
-- `ZXING-LICENSE` - Apache 2.0 + MIT
-
-### QR Detection
-Uses ZXing WASM decoder exclusively for universal browser support.
-
-### Camera Loop
-```ts
-private scanFrame() {
-  ctx.drawImage(video, 0, 0, width, height);
-  const imageData = ctx.getImageData(0, 0, width, height);
-  worker.postMessage({ type: 'decode', imageData });
-  // Worker responds with result in background thread
-  requestAnimationFrame(() => this.scanFrame());
-}
+```typescript
+const reader = document.querySelector('snice-qr-reader');
+reader.addEventListener('qr-scan', (e) => console.log(e.detail.data));
+reader.start();
+
+// Manual snap
+const result = await reader.snap();
 ```
 
-### Lifecycle
-- `@ready` - Init worker, auto-start if enabled
-- `@dispose` - Stop scan, release camera, terminate worker
-- Scan loop uses requestAnimationFrame
-- QR detection runs in Web Worker (non-blocking)
-- Only emits event if QR data changed
-
-## License
-- ZXing-C++: Apache 2.0
-- zxing-wasm: MIT
-- See ZXING-LICENSE file
-
-## Browser Requirements
-- getUserMedia API
-- WebAssembly support
-- HTTPS for mobile
+## Features
+
+- ZXing WASM decoder (Apache 2.0 + MIT)
+- Web Worker for non-blocking detection
+- Front/back camera switching
+- Configurable scan speed (1-10)
+- Pick-first mode (max speed, auto-stop)
+- Manual snapshot mode
+- Tap-to-start interaction
+- Camera released on stop/dispose
+- HTTPS required for mobile

package/docs/ai/components/radio.md

@@ -1,81 +1,69 @@
 # snice-radio
 
-Form radio button input with grouping.
+Form radio button input with automatic group management.
 
 ## Properties
 
 ```typescript
 checked: boolean = false;
 disabled: boolean = false;
+loading: boolean = false;
 required: boolean = false;
 invalid: boolean = false;
 size: 'small'|'medium'|'large' = 'medium';
-name: string = '';
+name: string = '';           // Group name for mutual exclusion
 value: string = '';
 label: string = '';
-loading: boolean = false;
 ```
 
 ## Methods
 
 - `focus()` - Focus radio
-- `blur()` - Blur radio
+- `blur()` - Remove focus
 - `click()` - Programmatic click
-- `select()` - Programmatic selection
+- `select()` - Select and fire change event
 
 ## Events
 
-- `radio-change` - {checked, value, radio}
+- `radio-change` → `{ checked, value, radio }`
+
+## CSS Parts
+
+- `input` - Hidden radio input
+- `radio` - Radio circle container
+- `dot` - Inner dot indicator
+- `spinner` - Loading spinner
+- `label` - Label text
 
 ## Usage
 
 ```html
-<!-- Basic radio group -->
+<!-- Radio group -->
 <snice-radio name="color" value="red" label="Red"></snice-radio>
 <snice-radio name="color" value="green" label="Green"></snice-radio>
-<snice-radio name="color" value="blue" label="Blue"></snice-radio>
-
-<!-- Pre-selected -->
-<snice-radio name="size" value="s" label="Small"></snice-radio>
-<snice-radio name="size" value="m" label="Medium" checked></snice-radio>
-<snice-radio name="size" value="l" label="Large"></snice-radio>
-
-<!-- Disabled -->
-<snice-radio label="Unavailable" disabled></snice-radio>
-<snice-radio label="Selected but disabled" checked disabled></snice-radio>
-
-<!-- Required -->
-<snice-radio name="accept" value="yes" label="Accept" required></snice-radio>
-
-<!-- Invalid -->
-<snice-radio label="Invalid option" invalid></snice-radio>
+<snice-radio name="color" value="blue" label="Blue" checked></snice-radio>
 
 <!-- Sizes -->
 <snice-radio label="Small" size="small"></snice-radio>
-<snice-radio label="Medium" size="medium"></snice-radio>
 <snice-radio label="Large" size="large"></snice-radio>
 
-<!-- Form integration -->
-<form>
-  <snice-radio name="plan" value="free" label="Free"></snice-radio>
-  <snice-radio name="plan" value="pro" label="Pro"></snice-radio>
-  <snice-radio name="plan" value="enterprise" label="Enterprise"></snice-radio>
-</form>
-
-<!-- Event handling -->
-<snice-radio id="rb" name="opt" value="a"></snice-radio>
-<script>
-document.querySelector('#rb').addEventListener('radio-change', (e) => {
+<!-- States -->
+<snice-radio label="Disabled" disabled></snice-radio>
+<snice-radio label="Loading" loading></snice-radio>
+<snice-radio label="Invalid" invalid></snice-radio>
+<snice-radio label="Required" required></snice-radio>
+```
+
+```typescript
+radio.addEventListener('radio-change', (e) => {
   console.log('Selected:', e.detail.value);
 });
-</script>
 ```
 
 ## Features
 
-- Form-associated custom element
 - Automatic radio group management by name
 - 3 sizes
+- Loading state with spinner
 - Keyboard accessible (arrow keys navigate group)
-- Change events
-- Invalid state styling
+- Form-associated custom element