snice 4.28.0 → 4.30.0

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

package/docs/ai/components/product-card.md

@@ -4,60 +4,63 @@ Product display card with image gallery, pricing, ratings, variant selectors, an
 
 ## Properties
 
-```ts
-name: string = '';                                  // Product name
-price: number = 0;                                  // Regular price
-salePrice: number | null = null;                    // Sale price (attr: sale-price)
-currency: string = '$';                             // Currency symbol
-images: string[] = [];                              // Image URLs (gallery if multiple)
-rating: number = 0;                                 // Star rating (0-5)
-reviewCount: number = 0;                            // Review count (attr: review-count)
-variants: ProductVariant[] = [];                    // Variant selectors
-inStock: boolean = true;                            // In-stock status (attr: in-stock)
-variant: 'vertical' | 'horizontal' | 'compact' | 'featured' | 'minimal' | 'grid' = 'vertical';
-badge: string = '';                                 // Badge text (e.g. "SALE", "NEW")
-badgeVariant: 'sale' | 'new' | 'featured' = 'sale'; // Badge style (attr: badge-variant)
-loading: boolean = false;                           // Shows skeleton loading state
-favorite: boolean = false;                          // Favorite/heart state
-stockCount: number = -1;                            // Stock count (-1=hidden, <5=urgency) (attr: stock-count)
-```
-
-### Types
-
-```ts
-interface ProductVariant {
-  type: string;           // e.g. 'Size', 'Color'
-  options: string[];      // e.g. ['S','M','L'] or ['#000','#fff']
-}
+```typescript
+name: string = '';
+price: number = 0;
+salePrice: number | null = null;                     // attr: sale-price
+currency: string = '$';
+images: string[] = [];                               // attr: none (JS only)
+rating: number = 0;                                  // 0-5, supports half stars
+reviewCount: number = 0;                             // attr: review-count
+variants: ProductVariant[] = [];                     // attr: none (JS only)
+inStock: boolean = true;                             // attr: in-stock
+variant: 'vertical'|'horizontal'|'compact'|'featured'|'minimal'|'grid' = 'vertical';
+badge: string = '';                                  // Badge text (e.g. "SALE", "NEW")
+badgeVariant: 'sale'|'new'|'featured' = 'sale';     // attr: badge-variant
+loading: boolean = false;                            // Skeleton loading state
+favorite: boolean = false;                           // Heart toggle state
+stockCount: number = -1;                             // attr: stock-count, -1=hidden, <5=urgency
 ```
 
 ## Events
 
-- `add-to-cart` -> `{ name: string; price: number; salePrice: number | null; selectedVariants: Record<string, string> }`
-- `variant-select` -> `{ type: string; value: string }`
-- `image-click` -> `{ index: number; src: string }`
-- `favorite` -> `{ favorited: boolean }`
-- `quick-view` -> `void`
+- `add-to-cart` → `{ name, price, salePrice, selectedVariants: Record<string, string> }`
+- `variant-select` → `{ type: string, value: string }`
+- `image-click` → `{ index: number, src: string }`
+- `favorite` → `{ favorited: boolean }`
+- `quick-view` → `void`
 
 ## CSS Parts
 
-`base`, `gallery`, `body`, `title`, `rating`, `stars`, `price`, `price-current`, `price-original`, `discount`, `stock`, `variants`, `variant-group`, `variant-option`, `cta`, `badge`, `favorite-btn`, `image`
+- `base` - Outer card container
+- `gallery` - Image gallery area
+- `body` - Card body content
+- `title` - Product name heading
+- `rating` - Star rating area
+- `stars` - Star rating container
+- `price` - Price display area
+- `price-current` - Current price
+- `price-original` - Original price (strikethrough on sale)
+- `discount` - Discount percentage badge
+- `stock` - Stock status indicator
+- `variants` - Variant selectors area
+- `variant-group` - Variant selector group
+- `variant-option` - Individual variant option button
+- `cta` - Add-to-cart button
+- `badge` - Product badge
+- `favorite-btn` - Favorite/heart button
+- `image` - Gallery image element
 
-## Usage
+## Basic Usage
 
 ```html
-<snice-product-card
-  name="Running Shoes"
-  price="129.99"
-  sale-price="89.99"
-  rating="4.5"
-  review-count="342"
-  in-stock>
-</snice-product-card>
+<snice-product-card name="Running Shoes" price="129.99" rating="4.5" review-count="342" in-stock></snice-product-card>
 ```
 
 ```typescript
-card.images = ['shoe1.jpg', 'shoe2.jpg', 'shoe3.jpg'];
+import 'snice/components/product-card/snice-product-card';
+
+card.images = ['shoe1.jpg', 'shoe2.jpg'];
 card.variants = [
   { type: 'Size', options: ['S', 'M', 'L', 'XL'] },
   { type: 'Color', options: ['#1a1a2e', '#e94560', '#0f3460'] }
@@ -67,3 +70,17 @@ card.addEventListener('add-to-cart', (e) => {
   console.log(e.detail.name, e.detail.selectedVariants);
 });
 ```
+
+## Accessibility
+
+- Star rating has `aria-label` with numeric rating
+- Variant selectors use `role="radiogroup"` / `role="radio"` with `aria-checked`
+- Gallery navigation buttons have `aria-label`
+- Favorite button has descriptive `aria-label`
+- Out-of-stock disables CTA button
+
+## Types
+
+```typescript
+interface ProductVariant { type: string; options: string[]; }
+```

package/docs/ai/components/progress-ring.md

@@ -5,18 +5,18 @@ Determinate circular progress indicator with animated SVG ring fill and optional
 ## Properties
 
 ```typescript
-value: number = 0;                 // 0 to max
+value: number = 0;                                   // 0 to max
 max: number = 100;
 size: 'small'|'medium'|'large' = 'medium';
-thickness: number = 4;             // ring stroke width
-color: string = '';                // custom ring color (CSS value)
-showValue: boolean = false;        // attr: show-value, show percentage in center
-label: string = '';                // custom center text
+thickness: number = 4;                               // Ring stroke width
+color: string = '';                                  // Custom ring color (CSS value)
+showValue: boolean = false;                          // attr: show-value, show percentage in center
+label: string = '';                                  // Custom center text
 ```
 
 ## Events
 
-- `progress-complete` → `{ value, max, component }`
+- `progress-complete` → `{ value, max, component }` - Value reached max
 
 ## CSS Parts
 
@@ -27,28 +27,24 @@ label: string = '';                // custom center text
 - `value` - Percentage text
 - `label` - Label text
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
-<snice-progress-ring value="75"></snice-progress-ring>
-
-<!-- With percentage display -->
-<snice-progress-ring value="42" show-value></snice-progress-ring>
-
-<!-- With label -->
+<snice-progress-ring value="75" show-value></snice-progress-ring>
 <snice-progress-ring value="60" label="CPU"></snice-progress-ring>
-
-<!-- Custom color -->
 <snice-progress-ring value="80" color="#10b981" show-value></snice-progress-ring>
+<snice-progress-ring value="50" size="large" thickness="6" show-value></snice-progress-ring>
+```
 
-<!-- Sizes -->
-<snice-progress-ring value="50" size="small"></snice-progress-ring>
-<snice-progress-ring value="50" size="large" show-value></snice-progress-ring>
-
-<!-- Custom thickness -->
-<snice-progress-ring value="65" thickness="6" show-value></snice-progress-ring>
+```typescript
+import 'snice/components/progress-ring/snice-progress-ring';
 
-<!-- Custom max -->
-<snice-progress-ring value="150" max="200" show-value></snice-progress-ring>
+ring.addEventListener('progress-complete', () => {
+  console.log('Complete!');
+});
 ```
+
+## Accessibility
+
+- Uses `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Label or percentage used as `aria-label`

package/docs/ai/components/progress.md

@@ -1,6 +1,6 @@
 # snice-progress
 
-Progress indicator with linear or circular display.
+Progress indicator with linear or circular display, indeterminate mode, striped/animated styles, and labels.
 
 ## Properties
 
@@ -8,75 +8,58 @@ Progress indicator with linear or circular display.
 value: number = 0;
 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';
-showLabel: boolean = false;       // attr: show-label
-label: string = '';
+indeterminate: boolean = false;
+showLabel: boolean = false;                          // attr: show-label
+label: string = '';                                  // Custom label text
 striped: boolean = false;
 animated: boolean = false;
-thickness: number = 4;            // Stroke width for circular variant
+thickness: number = 4;                               // Circular stroke width
 ```
 
 ## Methods
 
-- `setProgress(value, max?)` - Set progress value
+- `setProgress(value: number, max?: number)` - Set progress value
 - `getPercentage()` - Get calculated percentage (0-100)
 
 ## Events
 
-- `progress-change` → `{ value, max, percentage, indeterminate }`
+- `progress-change` → `{ value, max, percentage, indeterminate }` - Value changed
+
+## CSS Parts
+
+Linear: `base`, `bar`, `label`
+Circular: `base`, `circle`, `circle-bg`, `circle-bar`, `label`
+
+## CSS Custom Properties
+
+```css
+--progress-height: 0.5rem;
+--progress-radius: 4px;
+--progress-bg: var(--snice-color-border, rgb(226 226 226));
+--progress-color: var(--snice-color-primary, rgb(37 99 235));
+--progress-animation-duration: 1.5s;
+```
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Linear -->
 <snice-progress value="50"></snice-progress>
-
-<!-- Circular -->
 <snice-progress variant="circular" value="75" size="xl"></snice-progress>
-
-<!-- Indeterminate -->
 <snice-progress indeterminate></snice-progress>
-
-<!-- With label -->
 <snice-progress value="60" show-label></snice-progress>
-<snice-progress value="60" label="Uploading..."></snice-progress>
-
-<!-- Striped and animated -->
 <snice-progress value="70" striped animated></snice-progress>
-
-<!-- Colors -->
 <snice-progress value="80" color="success"></snice-progress>
-<snice-progress value="80" color="#3b82f6"></snice-progress>
-
-<!-- Custom max -->
-<snice-progress value="3" max="10"></snice-progress>
 ```
 
 ```typescript
+import 'snice/components/progress/snice-progress';
 progress.setProgress(75);
-progress.setProgress(3, 10);
 console.log(progress.getPercentage());
 ```
 
-**CSS Parts (linear):**
-- `base` - Outer progress container
-- `bar` - The progress bar fill
-- `label` - Percentage or custom label text
-
-**CSS Parts (circular):**
-- `base` - Outer progress container
-- `circle` - The SVG element
-- `circle-bg` - Background circle stroke
-- `circle-bar` - Foreground progress arc
-- `label` - Percentage or custom label text
-
-## Features
-
-- Linear and circular variants
-- Indeterminate mode for unknown progress
-- Optional percentage or custom label
-- Striped and animated styles
-- 5 semantic + custom CSS colors
-- 6 sizes (small through xxxl)
+## Accessibility
+
+- Uses `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Label text used as `aria-label`