snice 4.27.0 → 4.29.0

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`

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

@@ -1,6 +1,6 @@
 # snice-qr-code
 
-QR code generator with customizable styling and export.
+QR code generator with customizable styling, center overlays, and export.
 
 ## Properties
 
@@ -8,7 +8,7 @@ QR code generator with customizable styling and export.
 value: string = '';
 size: number = 200;
 errorCorrectionLevel: 'L'|'M'|'Q'|'H' = 'M';  // attr: error-correction-level
-renderMode: 'canvas'|'svg' = 'canvas';            // attr: render-mode
+renderMode: 'canvas'|'svg' = 'canvas';           // attr: render-mode
 dotStyle: 'square'|'rounded'|'dots' = 'square';  // attr: dot-style
 margin: number = 4;
 fgColor: string = '#000000';                      // attr: fg-color
@@ -24,50 +24,48 @@ textOutlineColor: string = '#ffffff';             // attr: text-outline-color
 
 ## Methods
 
-- `toSVGString()` - Export as SVG markup string (sync, only when renderMode='svg')
+- `toSVGString()` - SVG markup string (sync, only when renderMode='svg')
 - `toDataURL(type?, quality?)` - Export as data URL (async)
 - `toBlob(type?, quality?)` - Export as Blob (async)
 - `download(filename?)` - Download as image file
 
 ## CSS Custom Properties
 
-- `--qr-bg` - Container background
-- `--qr-border-radius` - Container border radius
-- `--qr-padding` - Container padding
+- `--qr-bg` - Container background (`hsl(0 0% 100%)`)
+- `--qr-border-radius` - Container border radius (`0`)
+- `--qr-padding` - Container padding (`0`)
 
-## Usage
+## CSS Parts
+
+- `base` - QR code container div
+
+## Basic Usage
 
 ```html
-<snice-qr-code value="https://example.com" size="250"></snice-qr-code>
+<snice-qr-code value="https://example.com"></snice-qr-code>
 
-<!-- Custom colors -->
-<snice-qr-code value="https://example.com" fg-color="#2196f3" bg-color="#e3f2fd"></snice-qr-code>
+<!-- Custom colors + dot style -->
+<snice-qr-code value="https://example.com" fg-color="#2196f3" dot-style="rounded"></snice-qr-code>
 
-<!-- With center image -->
+<!-- Center image overlay (use high error correction) -->
 <snice-qr-code value="https://example.com" include-image image-url="/logo.png" error-correction-level="H"></snice-qr-code>
 
-<!-- Dot styles -->
-<snice-qr-code value="https://example.com" dot-style="rounded"></snice-qr-code>
+<!-- Center text overlay -->
+<snice-qr-code value="https://example.com" center-text="SCAN" error-correction-level="H"></snice-qr-code>
+
+<!-- SVG render mode -->
+<snice-qr-code value="https://example.com" render-mode="svg"></snice-qr-code>
 ```
 
 ```typescript
-qr.value = 'https://example.com';
+const qr = document.querySelector('snice-qr-code');
 const url = await qr.toDataURL('image/png');
 const blob = await qr.toBlob('image/png');
 qr.download('qr-code.png');
+const svg = qr.toSVGString(); // only when renderMode='svg'
 ```
 
-**CSS Parts:**
-- `base` - QR code container div
-
-## Common Data Formats
+## Accessibility
 
-```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'
-```
+- Purely visual output, no interactive elements
+- Provide adjacent text or wrapper `aria-label` for screen readers

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

@@ -1,6 +1,6 @@
 # snice-qr-reader
 
-QR code scanner using device camera and ZXing WASM decoder.
+QR code scanner using device camera with real-time detection.
 
 ## Properties
 
@@ -15,10 +15,10 @@ tapStart: boolean = false;          // attr: tap-start, tap viewport to start/st
 
 ## Methods
 
-- `start()` - Start camera and scanning
+- `start()` - Start camera and scanning (async)
 - `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
+- `snap()` - Take snapshot, returns QR data string or null (async)
+- `scanImage(file: File)` - Scan QR code from image file (async)
 - `switchCamera()` - Toggle front/back camera
 
 ## Events
@@ -28,7 +28,15 @@ tapStart: boolean = false;          // attr: tap-start, tap viewport to start/st
 - `camera-ready` → `{ reader }`
 - `camera-error` → `{ error: any, reader }`
 
-## Usage
+## CSS Custom Properties
+
+- `--qr-reader-bg` - Container background (`rgb(0 0 0)`)
+- `--qr-reader-overlay` - Overlay/gradient color (`rgb(0 0 0 / 0.7)`)
+- `--qr-reader-controls-color` - Button icon/text color (`rgb(255 255 255)`)
+- `--qr-reader-btn-bg` - Button background (`rgb(0 0 0 / 0.4)`)
+- `--qr-reader-btn-hover-bg` - Button hover background (`rgb(0 0 0 / 0.6)`)
+
+## Basic Usage
 
 ```html
 <!-- Auto-start continuous scanning -->
@@ -46,28 +54,17 @@ tapStart: boolean = false;          // attr: tap-start, tap viewport to start/st
 
 ```typescript
 reader.addEventListener('qr-scan', (e) => console.log(e.detail.data));
-reader.start();
+await reader.start();
 
 // Manual snap
 const result = await reader.snap();
+
+// Scan from file
+const data = await reader.scanImage(file);
 ```
 
-## CSS Custom Properties
+## Accessibility
 
-- `--qr-reader-bg` - Container background (default: `rgb(0 0 0)`)
-- `--qr-reader-overlay` - Overlay/gradient color (default: `rgb(0 0 0 / 0.7)`)
-- `--qr-reader-controls-color` - Button icon/text color (default: `rgb(255 255 255)`)
-- `--qr-reader-btn-bg` - Button background (default: `rgb(0 0 0 / 0.4)`)
-- `--qr-reader-btn-hover-bg` - Button hover background (default: `rgb(0 0 0 / 0.6)`)
-
-## 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
+- Requires HTTPS for mobile camera access
+- Built-in control buttons with icon labels
 - Camera released on stop/dispose
-- HTTPS required for mobile

package/docs/ai/components/radio.md

@@ -1,6 +1,6 @@
 # snice-radio
 
-Form radio button input with automatic group management.
+Form radio button input with automatic group management by name.
 
 ## Properties
 
@@ -15,19 +15,19 @@ size: 'small'|'medium'|'large' = 'medium';
 name: string = '';           // Group name for mutual exclusion
 value: string = '';
 label: string = '';
-description: string = '';    // Subtitle text (block variant)
+description: string = '';    // Subtitle text (block variant only)
 ```
 
 ## Methods
 
-- `focus()` - Focus radio
+- `focus()` - Focus radio input
 - `blur()` - Remove focus
 - `click()` - Programmatic click
 - `select()` - Select and fire change event
 
 ## Events
 
-- `radio-change` → `{ checked, value, radio }`
+- `radio-change` → `{ checked: boolean, value: string, radio: SniceRadioElement }`
 
 ## Slots
 
@@ -35,15 +35,15 @@ description: string = '';    // Subtitle text (block variant)
 
 ## CSS Parts
 
-- `input` - Hidden radio input
+- `input` - Hidden native radio input
 - `radio` - Radio circle container
 - `dot` - Inner dot indicator
 - `spinner` - Loading spinner
-- `label` - Label text
 - `content` - Content wrapper (block variant)
+- `label` - Label text
 - `description` - Description text (block variant)
 
-## Usage
+## Basic Usage
 
 ```html
 <!-- Radio group -->
@@ -59,7 +59,6 @@ description: string = '';    // Subtitle text (block variant)
 <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>
 
 <!-- Block variant (card-style) -->
 <snice-radio variant="block" name="plan" value="free" label="Free" description="For individuals" checked>
@@ -76,11 +75,14 @@ radio.addEventListener('radio-change', (e) => {
 });
 ```
 
-## Features
+## Keyboard Navigation
+
+- Arrow keys navigate within group (wraps around)
+- Focused radio is auto-selected
+
+## Accessibility
 
-- Automatic radio group management by name
-- 3 sizes
-- Block variant: card-style layout with description + suffix slot
-- Loading state with spinner
-- Keyboard accessible (arrow keys navigate group, wraps around)
-- Contains native `<input type="radio">` for form participation
+- Native `<input type="radio">` for form participation
+- `aria-invalid` when invalid
+- Focus ring on keyboard navigation
+- Required indicator on label

package/docs/ai/components/range-slider.md

@@ -18,35 +18,46 @@ orientation: 'horizontal'|'vertical' = 'horizontal';
 
 ## Events
 
-- `range-change` -> `{ valueLow: number, valueHigh: number, component: SniceRangeSliderElement }`
+- `range-change` → `{ valueLow: number, valueHigh: number, component: SniceRangeSliderElement }`
 
 ## CSS Parts
 
 - `track` - The slider track
-- `range` - The highlighted range between thumbs
+- `range` - Highlighted range between thumbs
 - `thumb-low` - Low value thumb
 - `thumb-high` - High value thumb
 - `label-min` - Min label text
 - `label-max` - Max label text
 
-## Usage
+## Basic Usage
 
 ```html
-<!-- Basic -->
 <snice-range-slider value-low="20" value-high="80"></snice-range-slider>
 
-<!-- With tooltips -->
-<snice-range-slider show-tooltip value-low="25" value-high="75"></snice-range-slider>
-
-<!-- With labels -->
-<snice-range-slider show-labels min="0" max="1000"></snice-range-slider>
+<!-- With tooltips and labels -->
+<snice-range-slider show-tooltip show-labels min="0" max="1000" value-low="200" value-high="800"></snice-range-slider>
 
 <!-- Custom step -->
 <snice-range-slider min="0" max="100" step="5"></snice-range-slider>
 
 <!-- Vertical -->
 <snice-range-slider orientation="vertical" value-low="30" value-high="70"></snice-range-slider>
+```
 
-<!-- Disabled -->
-<snice-range-slider disabled value-low="20" value-high="60"></snice-range-slider>
+```typescript
+slider.addEventListener('range-change', (e) => {
+  console.log(e.detail.valueLow, e.detail.valueHigh);
+});
 ```
+
+## Keyboard Navigation
+
+- Arrow keys adjust focused thumb by step
+- Home/End move to min/max bounds
+- Each thumb independently focusable
+
+## Accessibility
+
+- `role="slider"` on each thumb with aria-valuenow/min/max
+- Focus ring on keyboard navigation
+- Track click moves nearest thumb