snice 4.27.0 → 4.29.0

package/docs/components/podcast-player.md

@@ -1,41 +1,26 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/podcast-player.md instead -->
-
-# Podcast Player Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/podcast-player.md -->
 
+# Podcast Player
 `<snice-podcast-player>`
 
 A full-featured podcast player with playback controls, playback speed adjustment, episode list, chapter support, RSS feed parsing, sleep timer, and position memory via localStorage.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Types](#types)
 - [Accessibility](#accessibility)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/podcast-player/snice-podcast-player';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-podcast-player.min.js"></script>
-```
+- [Data Types](#data-types)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `src` | `string` | `''` | Audio source URL for direct playback |
-| `fromRss` (attr: `from-rss`) | `string` | `''` | RSS feed URL. Fetches and displays the episode list automatically |
+| `fromRss` (attr: `from-rss`) | `string` | `''` | RSS feed URL. Fetches and displays episode list automatically |
 | `title` | `string` | `''` | Episode title |
 | `show` | `string` | `''` | Show or podcast name |
 | `artwork` | `string` | `''` | Artwork image URL |
@@ -47,9 +32,9 @@ import 'snice/components/podcast-player/snice-podcast-player';
 | `duration` | `number` | `0` | Episode duration in seconds |
 | `volume` | `number` | `1` | Volume level (range: 0 to 1) |
 | `muted` | `boolean` | `false` | Whether audio is muted |
-| `state` | `PodcastPlayerState` | `'stopped'` | Current playback state (read-only) |
-| `episodes` | `PodcastEpisode[]` | `[]` | Array of episodes (set via JavaScript) |
-| `currentEpisodeIndex` (attr: `current-episode-index`) | `number` | `0` | Index of the currently active episode |
+| `state` | `PodcastPlayerState` | `'stopped'` | Current playback state (not a decorated property) |
+| `episodes` | `PodcastEpisode[]` | `[]` | Array of episodes (set via JS) |
+| `currentEpisodeIndex` (attr: `current-episode-index`) | `number` | `-1` | Index of the currently active episode |
 | `sleepTimer` (attr: `sleep-timer`) | `number` | `0` | Sleep timer duration in minutes (0 = disabled) |
 
 ## Methods
@@ -70,10 +55,10 @@ import 'snice/components/podcast-player/snice-podcast-player';
 | `podcast-play` | `{ player, episode }` | Fired when playback starts |
 | `podcast-pause` | `{ player, episode }` | Fired when playback is paused |
 | `podcast-ended` | `{ player, episode }` | Fired when the current episode ends |
-| `podcast-time-update` | `{ player, currentTime, duration }` | Fired periodically during playback with current time |
+| `podcast-time-update` | `{ player, currentTime, duration }` | Fired periodically during playback |
 | `podcast-rate-change` | `{ player, rate }` | Fired when the playback speed changes |
 | `podcast-episode-change` | `{ player, episode, index }` | Fired when a different episode is selected |
-| `podcast-feed-loaded` | `{ player, feed: RSSFeedData }` | Fired when an RSS feed has been parsed successfully |
+| `podcast-feed-loaded` | `{ player, feed: RSSFeedData }` | Fired when an RSS feed has been parsed |
 
 ## CSS Parts
 
@@ -91,10 +76,6 @@ snice-podcast-player::part(base) {
   background: #1a1a2e;
   color: white;
 }
-
-snice-podcast-player::part(controls) {
-  padding: 1rem;
-}
 ```
 
 ## Basic Usage
@@ -108,33 +89,18 @@ import 'snice/components/podcast-player/snice-podcast-player';
   src="/audio/episode.mp3"
   title="Episode 1"
   show="My Podcast"
+  artwork="/images/cover.jpg"
 ></snice-podcast-player>
 ```
 
 ## Examples
 
-### Single Episode Playback
-
-Play a single episode by setting the source URL directly.
-
-```html
-<snice-podcast-player
-  src="/audio/episode-42.mp3"
-  title="Episode 42: Web Components"
-  show="The Dev Podcast"
-  artwork="/images/dev-podcast-cover.jpg"
-  description="A deep dive into modern web component patterns."
-></snice-podcast-player>
-```
-
 ### RSS Feed Mode
 
-Load an entire podcast from an RSS feed. The player automatically parses the feed to populate the show name, artwork, and episode list.
+Load an entire podcast from an RSS feed.
 
 ```html
-<snice-podcast-player
-  from-rss="https://example.com/podcast/feed.xml"
-></snice-podcast-player>
+<snice-podcast-player from-rss="https://example.com/podcast/feed.xml"></snice-podcast-player>
 ```
 
 ```typescript
@@ -146,55 +112,34 @@ player.addEventListener('podcast-feed-loaded', (e) => {
 
 ### Episode List with Chapters
 
-Provide an array of episodes with chapter markers for enhanced navigation.
-
-```html
-<snice-podcast-player></snice-podcast-player>
-```
+Provide episodes with chapter markers for enhanced navigation.
 
 ```typescript
 player.show = 'Tech Weekly';
-player.artwork = '/images/tech-weekly.jpg';
-
 player.episodes = [
   {
     title: 'Episode 1: Getting Started',
     src: '/audio/ep1.mp3',
     duration: 1800,
-    pubDate: '2025-01-15',
     chapters: [
       { title: 'Intro', startTime: 0 },
       { title: 'Main Topic', startTime: 120 },
-      { title: 'Q&A', startTime: 1200 },
-      { title: 'Outro', startTime: 1700 }
+      { title: 'Q&A', startTime: 1200 }
     ]
   },
-  {
-    title: 'Episode 2: Advanced Patterns',
-    src: '/audio/ep2.mp3',
-    duration: 2400,
-    pubDate: '2025-01-22'
-  },
-  {
-    title: 'Episode 3: Performance Tips',
-    src: '/audio/ep3.mp3',
-    duration: 2100,
-    pubDate: '2025-01-29'
-  }
+  { title: 'Episode 2: Advanced Patterns', src: '/audio/ep2.mp3', duration: 2400 }
 ];
-
 player.loadEpisode(0);
 ```
 
-### Playback Speed and Skip Duration
+### Custom Skip and Speed
 
-Customize skip intervals and playback speed for different listening preferences.
+Customize skip intervals and initial playback speed.
 
 ```html
 <snice-podcast-player
   src="/audio/interview.mp3"
-  title="Interview with the Author"
-  show="Book Club Podcast"
+  title="Interview"
   skip-forward="15"
   skip-back="10"
   playback-rate="1.5"
@@ -206,22 +151,13 @@ Customize skip intervals and playback speed for different listening preferences.
 Listen for playback events to integrate with analytics or custom UI.
 
 ```typescript
-player.addEventListener('podcast-play', () => {
-  console.log('Playing');
-});
-
-player.addEventListener('podcast-pause', () => {
-  console.log('Paused');
-});
+player.addEventListener('podcast-play', () => console.log('Playing'));
+player.addEventListener('podcast-pause', () => console.log('Paused'));
+player.addEventListener('podcast-ended', () => console.log('Finished'));
 
 player.addEventListener('podcast-time-update', (e) => {
-  const { currentTime, duration } = e.detail;
-  const percent = Math.round((currentTime / duration) * 100);
-  console.log(`Playing: ${percent}%`);
-});
-
-player.addEventListener('podcast-ended', () => {
-  console.log('Finished');
+  const percent = Math.round((e.detail.currentTime / e.detail.duration) * 100);
+  console.log(`Progress: ${percent}%`);
 });
 
 player.addEventListener('podcast-episode-change', (e) => {
@@ -229,9 +165,17 @@ player.addEventListener('podcast-episode-change', (e) => {
 });
 ```
 
-## Types
+## Accessibility
+
+- Playback controls (play/pause, skip forward/back) are keyboard accessible
+- Progress bar supports seeking via click
+- Playback speed selector cycles through common speeds (0.5x through 2x)
+- Volume control provides mute toggle and level adjustment
+- Episode list items are interactive and indicate the currently playing episode
+- The player remembers playback position via localStorage, restoring it on reload
+- Chapter markers provide named navigation points within an episode
 
-### PodcastEpisode
+## Data Types
 
 ```typescript
 interface PodcastEpisode {
@@ -243,42 +187,20 @@ interface PodcastEpisode {
   duration?: number;               // Duration in seconds
   chapters?: PodcastChapter[];     // Chapter markers
 }
-```
-
-### PodcastChapter
 
-```typescript
 interface PodcastChapter {
-  title: string;          // Chapter title
-  startTime: number;      // Start time in seconds
-  endTime?: number;       // End time in seconds
-  artwork?: string;       // Chapter-specific artwork URL
+  title: string;                   // Chapter title
+  startTime: number;               // Start time in seconds
+  endTime?: number;                // End time in seconds
+  artwork?: string;                // Chapter-specific artwork URL
 }
-```
-
-### RSSFeedData
 
-```typescript
 interface RSSFeedData {
-  title: string;                   // Podcast title from feed
-  artwork?: string;                // Show artwork URL from feed
-  description?: string;            // Show description from feed
-  episodes: PodcastEpisode[];      // Parsed episode list
+  title: string;
+  artwork?: string;
+  description?: string;
+  episodes: PodcastEpisode[];
 }
-```
 
-### PodcastPlayerState
-
-```typescript
 type PodcastPlayerState = 'playing' | 'paused' | 'stopped' | 'loading' | 'error';
 ```
-
-## Accessibility
-
-- Playback controls (play/pause, skip forward/back) are keyboard accessible
-- The progress bar supports seeking via click or drag
-- Playback speed selector allows choosing from common speed options (0.5x through 2x)
-- Volume control provides mute toggle and level adjustment
-- Episode list items are interactive and indicate the currently playing episode
-- The player remembers playback position via localStorage, restoring it on reload
-- Chapter markers provide named navigation points within an episode

package/docs/components/pricing-table.md

@@ -1,77 +1,84 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/pricing-table.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/pricing-table.md -->
 
-# Pricing Table Component
+# Pricing Table
+`<snice-pricing-table>`
 
-The pricing table component displays plan comparisons in a card or table layout, with support for monthly/annual billing toggle, highlighted plans, badges, and declarative child elements.
+A pricing comparison component with cards or table layout, monthly/annual billing toggle, highlighted plans, badges, and declarative child elements.
 
 ## Table of Contents
 - [Properties](#properties)
+- [Components](#components)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Child Elements](#child-elements)
 - [Accessibility](#accessibility)
+- [Data Types](#data-types)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `plans` | `PricingPlan[]` | `[]` | Plan data array (for programmatic usage) |
+| `plans` | `PricingPlan[]` | `[]` | Plan data array (set via JS for programmatic usage) |
 | `variant` | `'cards' \| 'table'` | `'cards'` | Layout variant |
 | `annual` | `boolean` | `false` | Whether to show annual pricing |
 
-### PricingPlan Interface
+## Components
 
-```typescript
-interface PricingPlan {
-  name: string;
-  price: number;
-  annualPrice?: number;        // Enables the billing toggle when set
-  period?: string;             // e.g. '/mo' (default: '/mo')
-  currency?: string;           // e.g. '$' (default: '$')
-  description?: string;
-  features: PricingFeature[];
-  cta: string;                 // Call-to-action button text
-  ctaVariant?: 'primary' | 'secondary' | 'outline';
-  highlighted?: boolean;       // Emphasize this plan
-  badge?: string;              // e.g. 'Popular', 'Best Value'
-}
+### `<snice-plan>`
 
-interface PricingFeature {
-  name: string;
-  included: boolean | string;  // true/false for check/x, string for custom value
-}
-```
+Declarative child element for defining plans.
 
-## Events
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Plan name |
+| `price` | `string` | Monthly price |
+| `annual-price` | `string` | Annual price (enables billing toggle) |
+| `period` | `string` | Billing period label (default: '/mo') |
+| `currency` | `string` | Currency symbol (default: '$') |
+| `description` | `string` | Plan description |
+| `cta` | `string` | Call-to-action button text |
+| `cta-variant` | `'primary' \| 'secondary' \| 'outline'` | Button variant |
+| `highlighted` | `boolean` | Emphasize this plan |
+| `badge` | `string` | Badge text (e.g. 'Popular') |
 
-#### `plan-select`
-Fired when a plan's call-to-action button is clicked.
+### `<snice-feature>`
 
-**Event Detail:**
-```typescript
-{
-  plan: PricingPlan;           // The selected plan object
-  index: number;               // Plan index (0-based)
-  billing: 'monthly' | 'annual';  // Current billing period
-}
-```
+Declarative child element for defining plan features.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `excluded` | `boolean` | Mark feature as not included (shows X instead of check) |
+| `value` | `string` | Custom display value (e.g. '1GB', '100GB') |
+
+The text content of `<snice-feature>` is used as the feature name.
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `plan-select` | `{ plan: PricingPlan, index: number, billing: 'monthly' \| 'annual' }` | Fired when a plan's CTA button is clicked |
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | The outer container |
-| `cards` | The cards layout container |
-| `card` | Individual plan card |
-| `cta` | Call-to-action button |
-| `toggle` | Billing toggle switch area |
-| `table-wrapper` | Table layout wrapper |
-| `table` | The comparison table element |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | The outer container |
+| `cards` | `<div>` | The cards layout container |
+| `card` | `<div>` | Individual plan card |
+| `cta` | `<button>` | Call-to-action button |
+| `toggle` | `<div>` | Billing toggle switch area |
+| `table-wrapper` | `<div>` | Table layout wrapper |
+| `table` | `<table>` | The comparison table element |
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/pricing-table/snice-pricing-table';
+```
+
 ```html
 <snice-pricing-table>
   <snice-plan name="Free" price="0" cta="Get Started">
@@ -85,13 +92,9 @@ Fired when a plan's call-to-action button is clicked.
 </snice-pricing-table>
 ```
 
-```typescript
-import 'snice/components/pricing-table/snice-pricing-table';
-```
-
 ## Examples
 
-### Cards Layout with Billing Toggle
+### Cards with Billing Toggle
 
 Use `annual-price` on plans to enable the monthly/annual billing toggle.
 
@@ -101,26 +104,23 @@ Use `annual-price` on plans to enable the monthly/annual billing toggle.
     <snice-feature>5 projects</snice-feature>
     <snice-feature value="1GB">Storage</snice-feature>
     <snice-feature excluded>Priority support</snice-feature>
-    <snice-feature excluded>API access</snice-feature>
   </snice-plan>
   <snice-plan name="Pro" price="29" annual-price="24" highlighted badge="Popular" cta="Start Trial" cta-variant="primary">
     <snice-feature>Unlimited projects</snice-feature>
     <snice-feature value="100GB">Storage</snice-feature>
     <snice-feature>Priority support</snice-feature>
-    <snice-feature>API access</snice-feature>
   </snice-plan>
   <snice-plan name="Enterprise" price="99" annual-price="79" cta="Contact Sales">
     <snice-feature>Unlimited projects</snice-feature>
     <snice-feature value="Unlimited">Storage</snice-feature>
     <snice-feature>Priority support</snice-feature>
-    <snice-feature>API access</snice-feature>
   </snice-plan>
 </snice-pricing-table>
 ```
 
 ### Table Layout
 
-Use the `variant="table"` attribute for a comparison table view.
+Use `variant="table"` for a feature comparison table view.
 
 ```html
 <snice-pricing-table variant="table">
@@ -129,7 +129,7 @@ Use the `variant="table"` attribute for a comparison table view.
     <snice-feature value="5GB">Storage</snice-feature>
     <snice-feature excluded>Analytics</snice-feature>
   </snice-plan>
-  <snice-plan name="Business" price="49" cta="Choose Business" highlighted badge="Best Value" cta-variant="primary">
+  <snice-plan name="Business" price="49" cta="Choose Business" highlighted badge="Best Value">
     <snice-feature>50 users</snice-feature>
     <snice-feature value="50GB">Storage</snice-feature>
     <snice-feature>Analytics</snice-feature>
@@ -141,101 +141,58 @@ Use the `variant="table"` attribute for a comparison table view.
 
 Set plans via JavaScript for dynamic pricing data.
 
-```html
-<snice-pricing-table id="pricing"></snice-pricing-table>
-
-<script type="module">
-  import 'snice/components/pricing-table/snice-pricing-table';
-
-  const table = document.getElementById('pricing');
-  table.plans = [
-    {
-      name: 'Free',
-      price: 0,
-      cta: 'Get Started',
-      features: [
-        { name: '5 projects', included: true },
-        { name: 'API access', included: false },
-        { name: 'Storage', included: '1GB' }
-      ]
-    },
-    {
-      name: 'Pro',
-      price: 29,
-      annualPrice: 24,
-      cta: 'Start Trial',
-      ctaVariant: 'primary',
-      highlighted: true,
-      badge: 'Popular',
-      features: [
-        { name: 'Unlimited projects', included: true },
-        { name: 'API access', included: true },
-        { name: 'Storage', included: '100GB' }
-      ]
-    }
-  ];
-
-  table.addEventListener('plan-select', (e) => {
-    console.log(`Selected: ${e.detail.plan.name} (${e.detail.billing})`);
-  });
-</script>
-```
-
-### Handling Plan Selection
-
-```html
-<snice-pricing-table id="plans">
-  <snice-plan name="Monthly" price="15" cta="Subscribe" cta-variant="primary">
-    <snice-feature>All features included</snice-feature>
-    <snice-feature>Email support</snice-feature>
-  </snice-plan>
-  <snice-plan name="Annual" price="12" cta="Save 20%" cta-variant="primary" highlighted badge="Save 20%">
-    <snice-feature>All features included</snice-feature>
-    <snice-feature>Priority support</snice-feature>
-  </snice-plan>
-</snice-pricing-table>
-
-<script type="module">
-  const table = document.getElementById('plans');
-  table.addEventListener('plan-select', (e) => {
-    const { plan, billing } = e.detail;
-    // Navigate to checkout
-    window.location.href = `/checkout?plan=${plan.name.toLowerCase()}&billing=${billing}`;
-  });
-</script>
+```typescript
+table.plans = [
+  {
+    name: 'Free', price: 0, cta: 'Get Started',
+    features: [
+      { name: '5 projects', included: true },
+      { name: 'API access', included: false },
+      { name: 'Storage', included: '1GB' }
+    ]
+  },
+  {
+    name: 'Pro', price: 29, annualPrice: 24, cta: 'Start Trial',
+    ctaVariant: 'primary', highlighted: true, badge: 'Popular',
+    features: [
+      { name: 'Unlimited projects', included: true },
+      { name: 'API access', included: true },
+      { name: 'Storage', included: '100GB' }
+    ]
+  }
+];
+
+table.addEventListener('plan-select', (e) => {
+  console.log(`Selected: ${e.detail.plan.name} (${e.detail.billing})`);
+});
 ```
 
-## Child Elements
-
-The pricing table supports declarative usage via `<snice-plan>` and `<snice-feature>` child elements as an alternative to setting the `plans` property.
-
-### `<snice-plan>`
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Plan name |
-| `price` | `string` | Monthly price |
-| `annual-price` | `string` | Annual price (enables billing toggle) |
-| `period` | `string` | Billing period label (default: '/mo') |
-| `currency` | `string` | Currency symbol (default: '$') |
-| `description` | `string` | Plan description |
-| `cta` | `string` | Call-to-action button text |
-| `cta-variant` | `'primary' \| 'secondary' \| 'outline'` | Button variant |
-| `highlighted` | `boolean` | Emphasize this plan |
-| `badge` | `string` | Badge text (e.g. 'Popular') |
-
-### `<snice-feature>`
+## Accessibility
 
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `excluded` | `boolean` | Mark feature as not included (shows X instead of check) |
-| `value` | `string` | Custom display value (e.g. '1GB', '100GB') |
+- Tab through plans and activate CTA buttons with Enter or Space
+- Plan names, prices, and feature inclusion states are announced to screen readers
+- The billing toggle is keyboard accessible with `role="radiogroup"`
+- Highlighted plans are visually distinguished through styling
 
-The text content of `<snice-feature>` is used as the feature name.
+## Data Types
 
-## Accessibility
+```typescript
+interface PricingPlan {
+  name: string;
+  price: number;
+  annualPrice?: number;            // Enables billing toggle when set
+  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;
+  badge?: string;
+}
 
-- **Keyboard support**: Tab through plans and activate CTA buttons with Enter or Space
-- **Screen readers**: Plan names, prices, and feature inclusion states are announced
-- **Highlighted plans**: Visually emphasized plans are distinguishable through styling, not color alone
-- **Billing toggle**: The monthly/annual toggle is keyboard accessible
+interface PricingFeature {
+  name: string;
+  included: boolean | string;      // true/false for check/x, string for custom value
+}
+```