snice 4.28.0 → 4.30.0

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

package/docs/ai/components/rating.md

@@ -1,55 +1,40 @@
 # snice-rating
 
-Star rating input with full/half precision, custom icons, and keyboard navigation.
+Interactive 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')
+```typescript
+value: number = 0;
+max: number = 5;
+icon: string = '★';
+size: 'small'|'medium'|'large' = 'medium';
+readonly: boolean = false;
+precision: 'full'|'half' = '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)
+- `rating-change` → `{ value: number }`
 
 ## 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
-```
+- `--rating-color` - Filled star color (`var(--snice-color-warning)`)
+- `--rating-color-empty` - Empty star color (`var(--snice-color-border)`)
+- `--rating-size` - Star size (auto-set by `size`: small=1rem, medium=1.5rem, large=2rem)
+
+## CSS Parts
 
-**CSS Parts:**
 - `base` - Outer rating container
 - `star` - Individual star/icon element
 
-## Accessibility
-
-Uses `role="radiogroup"` with individual `role="radio"` stars. Keyboard accessible when not readonly.
-
-## Usage
+## Basic Usage
 
 ```html
-<snice-rating value="3.5" max="5" precision="half" size="large"></snice-rating>
+<snice-rating value="3.5" precision="half" max="5"></snice-rating>
 <snice-rating value="4" readonly></snice-rating>
-<snice-rating icon="&#x2764;" max="10"></snice-rating>
+<snice-rating icon="❤" value="3" max="5"></snice-rating>
+<snice-rating value="4" size="large"></snice-rating>
 ```
 
 ```typescript
@@ -57,3 +42,14 @@ rating.addEventListener('rating-change', (e) => {
   console.log('New rating:', e.detail.value);
 });
 ```
+
+## Keyboard Navigation
+
+- ArrowRight/Up: increase by step (1 or 0.5)
+- ArrowLeft/Down: decrease by step
+
+## Accessibility
+
+- `role="radiogroup"` with `role="radio"` per star
+- Not focusable when readonly
+- Focus ring on keyboard navigation

package/docs/ai/components/receipt.md

@@ -5,36 +5,33 @@ Transaction receipt display with items, totals, payment info, and multiple visua
 ## Properties
 
 ```typescript
-receiptNumber: string = ''                  // attribute: receipt-number
-date: string = ''                           // Transaction date
-currency: string = 'USD'                    // ISO 4217 currency code
-locale: string = ''                         // Intl.NumberFormat locale
-merchant: ReceiptMerchant = { name: '' }    // Merchant info (JS only)
-items: ReceiptItem[] = []                   // Line items (JS only)
-tax: number = 0                             // Single tax amount (absolute)
-taxes: ReceiptTaxLine[] = []                // Multiple tax lines (JS only)
-subtotal: number = 0                        // Auto-computed from items if 0
-total: number = 0                           // Auto-computed as subtotal + tax - discount + tip if 0
-tip: number = 0                             // Tip/gratuity amount
-discount: number = 0                        // Discount amount
-discountLabel: string = 'Discount'          // attribute: discount-label
-paymentMethod: string = ''                  // attribute: payment-method
-paymentDetails: string = ''                 // attribute: payment-details
-variant: ReceiptVariant = 'standard'        // 'standard'|'thermal'|'modern'|'minimal'|'detailed'
-showQr: boolean = false                     // attribute: show-qr — show QR slot
-qrData: string = ''                         // attribute: qr-data
-qrPosition: QrPosition = 'bottom'           // attribute: qr-position — 'top'|'bottom'|'footer'
-thankYou: string = 'Thank you...'           // attribute: thank-you
-cashier: string = ''                        // Cashier name
-terminalId: string = ''                     // attribute: terminal-id
+receiptNumber: string = '';                  // attr: receipt-number
+date: string = '';
+currency: string = 'USD';
+locale: string = '';                         // Intl.NumberFormat locale
+merchant: ReceiptMerchant = { name: '' };    // JS only
+items: ReceiptItem[] = [];                   // JS only
+tax: number = 0;
+taxes: ReceiptTaxLine[] = [];                // JS only, overrides tax
+subtotal: number = 0;                        // auto-computed from items if 0
+total: number = 0;                           // auto-computed if 0
+tip: number = 0;
+discount: number = 0;
+discountLabel: string = 'Discount';          // attr: discount-label
+paymentMethod: string = '';                  // attr: payment-method
+paymentDetails: string = '';                 // attr: payment-details
+variant: 'standard'|'thermal'|'modern'|'minimal'|'detailed' = 'standard';
+showQr: boolean = false;                     // attr: show-qr
+qrData: string = '';                         // attr: qr-data
+qrPosition: 'top'|'bottom'|'footer' = 'bottom'; // attr: qr-position
+thankYou: string = 'Thank you for your purchase!'; // attr: thank-you
+cashier: string = '';
+terminalId: string = '';                     // attr: terminal-id
 ```
 
 ## Types
 
 ```typescript
-type ReceiptVariant = 'standard' | 'thermal' | 'modern' | 'minimal' | 'detailed';
-type QrPosition = 'top' | 'bottom' | 'footer';
-
 interface ReceiptMerchant {
   name: string; address?: string; logo?: string;
   phone?: string; email?: string; website?: string; taxId?: string;
@@ -43,101 +40,31 @@ interface ReceiptItem {
   name: string; quantity: number; price: number;
   sku?: string; discount?: number; note?: string;
 }
-interface ReceiptTaxLine {
-  label: string; rate?: number; amount: number;
-}
+interface ReceiptTaxLine { label: string; rate?: number; amount: number; }
 ```
 
+## Methods
+
+- `print()` - Opens print dialog
+
 ## Slots
 
 - `(default)` - Footer content below thank-you message
 - `qr` - QR code content (shown when `show-qr` is set)
 - `barcode` - Barcode content
 
-## Methods
-
-- `print()` - Opens print dialog
-
 ## CSS Parts
 
-```
-::part(base)              /* Main container */
-::part(header)            /* Merchant section */
-::part(logo)              /* Merchant logo */
-::part(merchant-name)     /* Merchant name */
-::part(merchant-address)  /* Merchant address */
-::part(merchant-contact)  /* Phone/email/website line */
-::part(meta)              /* Receipt # / date / cashier / terminal */
-::part(receipt-number)    /* Receipt number value */
-::part(date)              /* Date value */
-::part(items-header)      /* Column header row */
-::part(items)             /* Items list */
-::part(item)              /* Individual item row */
-::part(item-name)         /* Item name */
-::part(item-qty)          /* Item quantity */
-::part(item-price)        /* Item price */
-::part(item-sku)          /* Item SKU (detailed variant) */
-::part(totals)            /* Totals section */
-::part(subtotal-row)      /* Subtotal line */
-::part(tax-row)           /* Tax line(s) */
-::part(discount-row)      /* Discount line */
-::part(tip-row)           /* Tip line */
-::part(total-row)         /* Grand total line */
-::part(payment)           /* Payment section */
-::part(payment-method)    /* Payment method text */
-::part(payment-details)   /* Auth code / change etc */
-::part(footer)            /* Footer section */
-::part(thank-you)         /* Thank-you message */
-::part(qr-container)      /* QR code wrapper */
-::part(barcode-area)      /* Barcode wrapper */
-::part(divider)           /* Section dividers */
-```
+- `base` - Root container
+- `divider` - Section dividers
+- `header`, `logo`, `merchant-name`, `merchant-address`, `merchant-contact` - Merchant section
+- `meta`, `receipt-number`, `date` - Metadata section
+- `items-header`, `items`, `item`, `item-name`, `item-sku`, `item-qty`, `item-price` - Items section
+- `totals`, `subtotal-row`, `discount-row`, `tax-row`, `tip-row`, `total-row` - Totals section
+- `payment`, `payment-method`, `payment-details` - Payment section
+- `qr-container`, `barcode-area`, `footer`, `thank-you` - Footer section
 
-## CSS Custom Properties
-
-```css
---receipt-max-width          /* 22rem */
---receipt-padding            /* 1.5rem */
---receipt-bg                 /* background */
---receipt-text               /* text color */
---receipt-text-secondary     /* secondary text */
---receipt-text-tertiary      /* tertiary text */
---receipt-border             /* border color */
---receipt-bg-element         /* element background */
---receipt-header-bg          /* header background */
---receipt-accent             /* accent color (modern) */
---receipt-font-family        /* font override */
---receipt-merchant-font-size /* 1.25rem */
---receipt-item-font-size     /* 0.9375rem */
---receipt-meta-font-size     /* 0.8125rem */
---receipt-total-font-size    /* 1.125rem */
---receipt-total-font-weight  /* 700 */
---receipt-footer-font-size   /* 0.8125rem */
---receipt-divider-style      /* dashed */
---receipt-divider-color      /* border color */
---receipt-divider-width      /* 1px */
---receipt-border-radius      /* 8px */
---receipt-border-color       /* border */
---receipt-shadow             /* none */
---receipt-thermal-font       /* Courier New, monospace */
---receipt-thermal-width      /* 18rem */
---receipt-thermal-bg         /* rgb(255 255 248) */
---receipt-modern-radius      /* 12px */
---receipt-modern-shadow      /* 0 4px 24px ... */
---receipt-modern-section-bg  /* element bg */
---receipt-modern-section-radius /* 8px */
---receipt-qr-size            /* 6rem */
-```
-
-## Variants
-
-- `standard` — Clean receipt with merchant header, items, totals, dashed dividers
-- `thermal` — Monospace, narrow-width, dotted separators, thermal printer aesthetic
-- `modern` — Card-based, rounded sections, shadows, accent-colored total
-- `minimal` — Stripped to essentials, no logo/address, uppercase merchant, thin dividers
-- `detailed` — Wide, grid meta, SKU/notes/per-item discounts, thick borders
-
-## Usage
+## Basic Usage
 
 ```html
 <snice-receipt
@@ -146,14 +73,6 @@ interface ReceiptTaxLine {
   payment-method="Visa **** 4242"
   variant="standard">
 </snice-receipt>
-
-<!-- Thermal -->
-<snice-receipt variant="thermal"></snice-receipt>
-
-<!-- Modern with QR -->
-<snice-receipt variant="modern" show-qr qr-position="bottom">
-  <snice-qr-code slot="qr" value="https://receipt.example.com/4521"></snice-qr-code>
-</snice-receipt>
 ```
 
 ```typescript
@@ -165,21 +84,25 @@ receipt.items = [
 receipt.tax = 1.15;
 receipt.tip = 2.00;
 
-// Detailed with tax breakdown
-receipt.variant = 'detailed';
+// Multiple taxes
 receipt.taxes = [
   { label: 'State Tax', rate: 6, amount: 3.00 },
   { label: 'City Tax', rate: 2, amount: 1.00 }
 ];
-receipt.items = [{ name: 'Widget', quantity: 1, price: 50, sku: 'WDG-001', note: 'Gift wrapped' }];
 ```
 
+## Variants
+
+- `standard` - Clean receipt with dashed dividers
+- `thermal` - Monospace, narrow-width, thermal printer aesthetic
+- `modern` - Card-based, rounded sections, shadows
+- `minimal` - Stripped to essentials
+- `detailed` - Wide, grid meta, SKU/notes/per-item discounts
+
 ## Notes
 
-- Subtotal auto-computed from items (with per-item discount subtracted) if not explicitly set
-- Total auto-computed as subtotal + tax - discount + tip if not explicitly set
-- `taxes` array takes precedence over single `tax` property
-- Quantity badge hidden when quantity is 1
-- SKU, notes, per-item discounts only visible in `detailed` variant
-- Thermal variant prints narrow; modern removes shadows for print
-- `@media print` styles included for all variants
+- Subtotal auto-computed from items if not set
+- Total auto-computed as subtotal + tax - discount + tip if not set
+- `taxes` array overrides single `tax` property
+- SKU, notes, per-item discounts only in `detailed` variant
+- Print styles included for all variants