snice 4.9.0 → 4.10.0

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

package/docs/ai/components/rating.md

@@ -0,0 +1,56 @@
+# snice-rating
+
+Star rating input with full/half precision, custom icons, and keyboard navigation.
+
+## Properties
+
+```ts
+value: number                            // Current rating value (default: 0)
+max: number                              // Maximum stars (default: 5)
+icon: string                             // Star character (default: '\u2605')
+size: 'small' | 'medium' | 'large'      // Display size (default: 'medium')
+readonly: boolean                        // Disable interaction (default: false)
+precision: 'full' | 'half'              // Click precision (default: 'full')
+```
+
+## Events
+
+- `rating-change` -> `{ value: number }` -- Rating value changed
+
+## Keyboard
+
+- `ArrowRight` / `ArrowUp` -- Increase value
+- `ArrowLeft` / `ArrowDown` -- Decrease value
+- Step size: 1 (full) or 0.5 (half precision)
+
+## CSS Custom Properties
+
+```css
+--rating-color             /* Filled star color (default: --snice-color-warning) */
+--rating-color-empty       /* Empty star color (default: --snice-color-border) */
+--rating-size              /* Star size: small=1rem, medium=1.5rem, large=2rem */
+--snice-font-family
+--snice-transition-fast
+--snice-focus-ring-width
+--snice-focus-ring-color
+--snice-focus-ring-offset
+```
+
+## Accessibility
+
+Uses `role="radiogroup"` with individual `role="radio"` stars. Keyboard accessible when not readonly.
+
+## Usage
+
+```html
+<snice-rating value="3.5" max="5" precision="half" size="large"></snice-rating>
+<snice-rating value="4" readonly></snice-rating>
+<snice-rating icon="&#x2764;" max="10"></snice-rating>
+```
+
+```js
+const rating = document.querySelector('snice-rating');
+rating.addEventListener('rating-change', (e) => {
+  console.log('New rating:', e.detail.value);
+});
+```

package/docs/ai/components/recipe.md

@@ -0,0 +1,90 @@
+# snice-recipe
+
+Interactive recipe card with ingredient scaling, step-by-step mode, per-step timers, and nutrition facts.
+
+## Properties
+
+```ts
+title: string                            // Recipe title
+description: string                      // Short description
+image: string                            // Hero image URL
+author: string                           // Author name
+prepTime: number                         // Prep time in minutes (attr: prep-time)
+cookTime: number                         // Cook time in minutes (attr: cook-time)
+servings: number                         // Base serving count (default: 4)
+difficulty: 'easy' | 'medium' | 'hard'  // Difficulty level (default: 'medium')
+cuisine: string                          // Cuisine type (shown as tag)
+variant: 'card' | 'full'                // Display variant (default: 'full')
+ingredients: RecipeIngredient[]          // Ingredient list
+steps: RecipeStep[]                      // Instruction steps
+nutrition: RecipeNutrition | null        // Nutrition facts per serving
+tags: string[]                           // Recipe tags
+```
+
+### Types
+
+```ts
+interface RecipeIngredient {
+  name: string;
+  amount: number;
+  unit: string;
+  group?: string;                        // Group header for ingredient sections
+}
+
+interface RecipeStep {
+  text: string;
+  image?: string;                        // Step photo URL
+  tip?: string;                          // Pro tip text
+  time?: number;                         // Timer duration in minutes
+}
+
+interface RecipeNutrition {
+  calories: number;
+  protein: number;
+  carbs: number;
+  fat: number;
+  fiber?: number;
+  sodium?: number;                       // in mg
+}
+```
+
+## Methods
+
+- `setServings(count: number)` -- Adjust serving count (scales ingredients)
+- `print()` -- Print the recipe
+- `reset()` -- Reset checked ingredients, completed steps, timers, and servings
+
+## Events
+
+- `recipe-serving-change` -> `{ servings: number; previousServings: number }` -- Serving count changed
+- `recipe-step-complete` -> `{ stepIndex: number; completed: boolean }` -- Step toggled
+- `recipe-ingredient-check` -> `{ ingredientIndex: number; checked: boolean; ingredient: RecipeIngredient }` -- Ingredient checked/unchecked
+
+## CSS Parts
+
+`container`, `hero`, `header`, `meta`, `content`, `ingredients`, `steps`, `nutrition`, `controls`
+
+## Usage
+
+```js
+const recipe = document.querySelector('snice-recipe');
+recipe.title = 'Pasta Carbonara';
+recipe.prepTime = 10;
+recipe.cookTime = 20;
+recipe.servings = 4;
+recipe.difficulty = 'medium';
+recipe.cuisine = 'Italian';
+recipe.ingredients = [
+  { name: 'Spaghetti', amount: 400, unit: 'g' },
+  { name: 'Pancetta', amount: 200, unit: 'g' },
+  { name: 'Eggs', amount: 4, unit: '', group: 'Sauce' },
+  { name: 'Parmesan', amount: 100, unit: 'g', group: 'Sauce' }
+];
+recipe.steps = [
+  { text: 'Boil pasta in salted water.', time: 10 },
+  { text: 'Fry pancetta until crispy.', tip: 'Use medium heat to render fat slowly.' },
+  { text: 'Mix eggs and parmesan.' },
+  { text: 'Combine all ingredients off heat.' }
+];
+recipe.nutrition = { calories: 650, protein: 28, carbs: 72, fat: 24 };
+```

package/docs/ai/components/skeleton.md

@@ -47,11 +47,3 @@ spacing: string = '8px';
   </div>
 </div>
 ```
-
-## Features
-
-- 4 shape variants (text/circular/rectangular/rounded)
-- 3 animation styles (pulse/wave/none)
-- Custom dimensions
-- Multiple skeleton elements with spacing
-- Mimics loading content shapes

package/docs/ai/components/slider.md

@@ -1,6 +1,6 @@
 # snice-slider
 
-Range slider for numeric value selection.
+Range slider for numeric value selection. Form-associated.
 
 ## Properties
 
@@ -16,73 +16,33 @@ required: boolean = false;
 invalid: boolean = false;
 readonly: boolean = false;
 label: string = '';
-helperText: string = '';
-errorText: string = '';
+helperText: string = '';       // attr: helper-text
+errorText: string = '';        // attr: error-text
 name: string = '';
-showValue: boolean = false;
-showTicks: boolean = false;
+showValue: boolean = false;    // attr: show-value
+showTicks: boolean = false;    // attr: show-ticks
 vertical: boolean = false;
 loading: boolean = false;
 ```
 
+## Events
+
+- `slider-input` → `{ value, slider }` - During drag
+- `slider-change` → `{ value, slider }` - After drag complete
+
 ## Methods
 
 - `focus()` - Focus slider thumb
 - `blur()` - Blur slider thumb
 
-## Events
-
-- `slider-input` - {value, slider} - During drag
-- `slider-change` - {value, slider} - After drag complete
-
 ## Usage
 
 ```html
-<!-- Basic -->
 <snice-slider label="Volume" min="0" max="100"></snice-slider>
-
-<!-- With value display -->
 <snice-slider show-value value="50"></snice-slider>
-
-<!-- With ticks -->
 <snice-slider show-ticks min="0" max="10" step="1"></snice-slider>
-
-<!-- Variants -->
 <snice-slider variant="primary"></snice-slider>
-<snice-slider variant="success"></snice-slider>
-<snice-slider variant="warning"></snice-slider>
-<snice-slider variant="danger"></snice-slider>
-
-<!-- Sizes -->
 <snice-slider size="small"></snice-slider>
-<snice-slider size="medium"></snice-slider>
-<snice-slider size="large"></snice-slider>
-
-<!-- Vertical -->
 <snice-slider vertical></snice-slider>
-
-<!-- Step increments -->
 <snice-slider min="0" max="100" step="5" value="50"></snice-slider>
-
-<!-- Events -->
-<snice-slider id="slider"></snice-slider>
-<script>
-const slider = document.querySelector('#slider');
-slider.addEventListener('slider-change', (e) => {
-  console.log('Value:', e.detail.value);
-});
-</script>
 ```
-
-## Features
-
-- Form-associated custom element
-- Mouse and touch support
-- Keyboard navigation (arrows, home/end, page up/down)
-- 5 color variants
-- 3 sizes
-- Vertical orientation
-- Optional value display
-- Optional tick marks
-- Step increments
-- Accessible