snice 4.27.0 → 4.29.0

package/docs/components/qr-code.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/qr-code.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/qr-code.md -->
 
 # QR Code
-`<snice-qr-code>`
 
-A QR code generator with customizable styling, dot patterns, and image export.
+A QR code generator with customizable styling, dot patterns, center overlays, and image export.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/qr-code/snice-qr-code';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-qr-code.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -27,14 +23,14 @@ import 'snice/components/qr-code/snice-qr-code';
 | `errorCorrectionLevel` (attr: `error-correction-level`) | `'L' \| 'M' \| 'Q' \| 'H'` | `'M'` | Error correction level |
 | `renderMode` (attr: `render-mode`) | `'canvas' \| 'svg'` | `'canvas'` | Rendering mode |
 | `dotStyle` (attr: `dot-style`) | `'square' \| 'rounded' \| 'dots'` | `'square'` | Module shape style |
-| `margin` | `number` | `4` | Quiet zone size |
+| `margin` | `number` | `4` | Quiet zone size in modules |
 | `fgColor` (attr: `fg-color`) | `string` | `'#000000'` | Foreground color |
 | `bgColor` (attr: `bg-color`) | `string` | `'#ffffff'` | Background color |
-| `includeImage` (attr: `include-image`) | `boolean` | `false` | Show center image |
+| `includeImage` (attr: `include-image`) | `boolean` | `false` | Show center image overlay |
 | `imageUrl` (attr: `image-url`) | `string` | `''` | Center image URL |
-| `imageSize` (attr: `image-size`) | `number` | `40` | Center image size |
+| `imageSize` (attr: `image-size`) | `number` | `40` | Center image size in pixels |
 | `centerText` (attr: `center-text`) | `string` | `''` | Center overlay text |
-| `centerTextSize` (attr: `center-text-size`) | `number` | `16` | Center text font size |
+| `centerTextSize` (attr: `center-text-size`) | `number` | `16` | Center text font size in pixels |
 | `textFillColor` (attr: `text-fill-color`) | `string` | `'#000000'` | Center text fill color |
 | `textOutlineColor` (attr: `text-outline-color`) | `string` | `'#ffffff'` | Center text outline color |
 
@@ -42,26 +38,24 @@ import 'snice/components/qr-code/snice-qr-code';
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `toSVGString()` | -- | Export as SVG markup string (sync, only when renderMode is `'svg'`) |
-| `toDataURL()` | `type?: string, quality?: number` | Export as data URL (async) |
-| `toBlob()` | `type?: string, quality?: number` | Export as Blob (async) |
-| `download()` | `filename?: string` | Download as image file |
+| `toSVGString()` | — | Returns SVG markup string (sync, only works when `renderMode` is `'svg'`) |
+| `toDataURL()` | `type?: 'image/png' \| 'image/jpeg' \| 'image/webp' \| 'image/svg+xml', quality?: number` | Export as data URL (async) |
+| `toBlob()` | `type?: 'image/png' \| 'image/jpeg' \| 'image/webp' \| 'image/svg+xml', quality?: number` | Export as Blob (async) |
+| `download()` | `filename?: string` | Download as image file (defaults to `'qr-code.png'`) |
 
 ## CSS Custom Properties
 
 | Property | Description | Default |
 |----------|-------------|---------|
-| `--qr-bg` | Container background color | _(theme default)_ |
-| `--qr-border-radius` | Container border radius | _(theme default)_ |
-| `--qr-padding` | Container padding | _(theme default)_ |
+| `--qr-bg` | Container background color | `hsl(0 0% 100%)` |
+| `--qr-border-radius` | Container border radius | `0` |
+| `--qr-padding` | Container padding | `0` |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | QR code container holding the generated canvas or SVG |
+| Part | Description |
+|------|-------------|
+| `base` | The container div holding the generated canvas or SVG |
 
 ```css
 snice-qr-code::part(base) {
@@ -112,7 +106,7 @@ Use the `dot-style` attribute to change the module shape.
 
 ### Error Correction
 
-Use `error-correction-level` for higher resilience to damage.
+Use `error-correction-level` for higher resilience to damage. Use `'H'` when adding center overlays.
 
 ```html
 <snice-qr-code value="Important Data" error-correction-level="H"></snice-qr-code>
@@ -120,16 +114,15 @@ Use `error-correction-level` for higher resilience to damage.
 
 ### Render Mode
 
-Use `render-mode` to switch between SVG and canvas rendering.
+Use `render-mode` to switch between canvas and SVG rendering.
 
 ```html
-<snice-qr-code value="https://example.com" render-mode="canvas"></snice-qr-code>
 <snice-qr-code value="https://example.com" render-mode="svg"></snice-qr-code>
 ```
 
 ### Center Image
 
-Use `include-image` with `image-url` to overlay a logo in the center.
+Use `include-image` with `image-url` to overlay a logo in the center. Pair with high error correction.
 
 ```html
 <snice-qr-code
@@ -154,8 +147,30 @@ Use `center-text` to overlay text in the center of the QR code.
 </snice-qr-code>
 ```
 
+### Export
+
+Use the export methods to save or share the QR code programmatically.
+
+```typescript
+const qr = document.querySelector('snice-qr-code');
+
+// Data URL
+const dataURL = await qr.toDataURL('image/png');
+
+// Blob
+const blob = await qr.toBlob('image/png');
+
+// Download
+qr.download('my-qr-code.png');
+
+// SVG string (only when render-mode="svg")
+const svgMarkup = qr.toSVGString();
+```
+
 ### Common Data Formats
 
+Set `value` to standard URI schemes for common QR code use cases.
+
 ```html
 <!-- URL -->
 <snice-qr-code value="https://example.com"></snice-qr-code>
@@ -166,9 +181,6 @@ Use `center-text` to overlay text in the center of the QR code.
 <!-- Phone -->
 <snice-qr-code value="tel:+1234567890"></snice-qr-code>
 
-<!-- SMS -->
-<snice-qr-code value="sms:+1234567890?body=Hello"></snice-qr-code>
-
 <!-- WiFi -->
 <snice-qr-code value="WIFI:T:WPA;S:MyNetwork;P:password123;;"></snice-qr-code>
 
@@ -176,28 +188,8 @@ Use `center-text` to overlay text in the center of the QR code.
 <snice-qr-code value="geo:37.7749,-122.4194"></snice-qr-code>
 ```
 
-### Export
-
-```typescript
-// Data URL
-const dataURL = await qr.toDataURL('image/png');
-
-// Blob
-const blob = await qr.toBlob('image/png');
+## Accessibility
 
-// Download
-qr.download('my-qr-code.png');
-```
-
-### Dynamic Updates
-
-```html
-<input type="text" id="qrInput" placeholder="Enter text">
-<snice-qr-code></snice-qr-code>
-```
-
-```typescript
-qrInput.addEventListener('input', (e) => {
-  qr.value = e.target.value;
-});
-```
+- The QR code renders as a `<canvas>` or `<svg>` element inside a container div
+- No interactive elements; the component is purely visual output
+- Provide adjacent text or an `aria-label` on a wrapper for screen reader users to understand the encoded content

package/docs/components/qr-reader.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/qr-reader.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/qr-reader.md -->
 
 # QR Reader
-`<snice-qr-reader>`
 
-A QR code scanner using device cameras with WebAssembly-based detection.
+A QR code scanner using device cameras with real-time detection.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/qr-reader/snice-qr-reader';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-qr-reader.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -24,28 +20,28 @@ import 'snice/components/qr-reader/snice-qr-reader';
 |----------|------|---------|-------------|
 | `autoStart` (attr: `auto-start`) | `boolean` | `false` | Auto-start scanning on mount |
 | `camera` | `'front' \| 'back'` | `'back'` | Which camera to use |
-| `pickFirst` (attr: `pick-first`) | `boolean` | `false` | Scan until first hit, then stop |
-| `manualSnap` (attr: `manual-snap`) | `boolean` | `false` | Photo snapshot mode |
-| `scanSpeed` (attr: `scan-speed`) | `number` | `3` | Scan speed 1-10 (ignored with pick-first) |
-| `tapStart` (attr: `tap-start`) | `boolean` | `false` | Tap viewport to toggle scanning |
+| `pickFirst` (attr: `pick-first`) | `boolean` | `false` | Scan at max speed until first hit, then auto-stop |
+| `manualSnap` (attr: `manual-snap`) | `boolean` | `false` | Photo snapshot mode instead of continuous scanning |
+| `scanSpeed` (attr: `scan-speed`) | `number` | `3` | Scan speed 1-10 (higher = more CPU, ignored with `pick-first`) |
+| `tapStart` (attr: `tap-start`) | `boolean` | `false` | Tap viewport to toggle scanning on/off |
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `start()` | -- | Start camera and scanning |
-| `stop()` | -- | Stop scanning and release camera |
-| `snap()` | -- | Take snapshot (manual-snap mode), returns data or null |
-| `scanImage()` | `file: File` | Scan QR code from an image file |
-| `switchCamera()` | -- | Toggle between front and back camera |
+| `start()` | — | Start camera and begin scanning (async) |
+| `stop()` | — | Stop scanning and release camera |
+| `snap()` | — | Take snapshot and scan for QR code (async, returns data string or `null`) |
+| `scanImage()` | `file: File` | Scan a QR code from an image file (async, returns data string) |
+| `switchCamera()` | — | Toggle between front and back camera |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `qr-scan` | `{ data: string, timestamp: number, reader }` | QR code detected |
+| `qr-scan` | `{ data: string, timestamp: number, reader }` | QR code successfully detected |
 | `qr-error` | `{ error: any, reader }` | Scan error occurred |
-| `camera-ready` | `{ reader }` | Camera initialized |
+| `camera-ready` | `{ reader }` | Camera initialized and ready |
 | `camera-error` | `{ error: any, reader }` | Camera initialization failed |
 
 ## CSS Custom Properties
@@ -86,12 +82,14 @@ Set `auto-start` to begin scanning when the component mounts.
 
 ### Manual Control
 
+Start and stop scanning programmatically.
+
 ```html
 <snice-qr-reader></snice-qr-reader>
 ```
 
 ```typescript
-reader.start();
+await reader.start();
 reader.stop();
 ```
 
@@ -104,29 +102,25 @@ Set `pick-first` to scan at maximum speed until the first QR code is found, then
 ```
 
 ```typescript
-scanner.addEventListener('qr-scan', (e) => {
+reader.addEventListener('qr-scan', (e) => {
   console.log('Found:', e.detail.data);
   // Scanner stops and releases camera automatically
 });
-scanner.start();
+await reader.start();
 ```
 
 ### Manual Snapshot
 
-Set `manual-snap` for a photo-based scanning mode with manual trigger.
+Set `manual-snap` for a photo-based scanning mode with a manual trigger button.
 
 ```html
 <snice-qr-reader manual-snap></snice-qr-reader>
-<button>Take Photo</button>
 ```
 
 ```typescript
-reader.start(); // Opens camera viewfinder
-
-snapBtn.addEventListener('click', async () => {
-  const result = await reader.snap();
-  console.log(result ? `Found: ${result}` : 'No QR code found');
-});
+await reader.start(); // Opens camera viewfinder
+const result = await reader.snap();
+console.log(result ? `Found: ${result}` : 'No QR code found');
 ```
 
 ### Front Camera
@@ -148,24 +142,41 @@ Use `scan-speed` (1-10) to balance detection speed vs CPU usage.
 
 ### Tap to Start
 
-Set `tap-start` to let users click the viewport to toggle scanning.
+Set `tap-start` to let users tap the viewport to toggle scanning.
 
 ```html
 <snice-qr-reader tap-start></snice-qr-reader>
 ```
 
-### Error Handling
+### Scan from Image File
+
+Use `scanImage()` to detect a QR code from an uploaded image.
 
 ```typescript
-reader.addEventListener('qr-error', (e) => {
-  console.error('Scan error:', e.detail.error);
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener('change', async (e) => {
+  const result = await reader.scanImage(e.target.files[0]);
+  console.log('Found:', result);
 });
+```
+
+### Error Handling
+
+Listen for error events to handle camera and scan failures.
 
+```typescript
 reader.addEventListener('camera-error', (e) => {
   console.error('Camera error:', e.detail.error);
 });
 
-reader.addEventListener('camera-ready', () => {
-  console.log('Camera initialized');
+reader.addEventListener('qr-error', (e) => {
+  console.error('Scan error:', e.detail.error);
 });
 ```
+
+## Accessibility
+
+- Requires HTTPS for camera access on mobile devices
+- Built-in start/stop/snap buttons with icon labels
+- Camera is released when the component is disconnected or scanning is stopped
+- Visual feedback shown for scan results and errors

package/docs/components/radio.md

@@ -1,22 +1,20 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/radio.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/radio.md -->
 
 # Radio
-`<snice-radio>`
 
 A form radio button input with automatic group management by name.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/radio/snice-radio';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-radio.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -32,16 +30,16 @@ import 'snice/components/radio/snice-radio';
 | `name` | `string` | `''` | Group name for mutual exclusion |
 | `value` | `string` | `''` | Form value when selected |
 | `label` | `string` | `''` | Label text |
-| `description` | `string` | `''` | Description text below the label (block variant) |
+| `description` | `string` | `''` | Description text below the label (block variant only) |
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `focus()` | -- | Focuses the radio input |
-| `blur()` | -- | Removes focus |
-| `click()` | -- | Programmatic click |
-| `select()` | -- | Selects the radio and fires change event |
+| `focus()` | — | Focuses the radio input |
+| `blur()` | — | Removes focus |
+| `click()` | — | Programmatic click |
+| `select()` | — | Selects the radio and fires change event |
 
 ## Events
 
@@ -59,12 +57,12 @@ import 'snice/components/radio/snice-radio';
 
 | Part | Description |
 |------|-------------|
-| `input` | The hidden radio input |
+| `input` | The hidden native radio input |
 | `radio` | The radio circle container |
 | `dot` | The inner dot indicator |
 | `spinner` | The loading spinner |
-| `label` | The label text |
 | `content` | The content wrapper (block variant) |
+| `label` | The label text |
 | `description` | The description text (block variant) |
 
 ## Basic Usage
@@ -134,21 +132,9 @@ Set the `loading` attribute to show a spinner instead of the radio dot.
 <snice-radio label="Processing..." loading></snice-radio>
 ```
 
-### Form Integration
-
-Radio buttons with the same `name` automatically form a group where only one can be selected.
-
-```html
-<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>
-```
-
 ### Block Variant
 
-Use `variant="block"` to render card-style radio buttons, ideal for plan pickers or option selectors. Add a `description` for subtitle text and use the `suffix` slot for end content like badges or prices.
+Use `variant="block"` to render card-style radio buttons. Add a `description` for subtitle text and use the `suffix` slot for end content.
 
 ```html
 <snice-radio
@@ -185,14 +171,30 @@ Use `variant="block"` to render card-style radio buttons, ideal for plan pickers
 
 ### Event Handling
 
-```html
-<snice-radio id="option" name="choice" value="a" label="Option A"></snice-radio>
+Listen for `radio-change` to respond to selection changes.
 
-<script type="module">
-  import 'snice/components/radio/snice-radio';
-
-  document.getElementById('option').addEventListener('radio-change', (e) => {
+```typescript
+document.querySelectorAll('snice-radio[name="plan"]').forEach(radio => {
+  radio.addEventListener('radio-change', (e) => {
     console.log('Selected:', e.detail.value);
   });
-</script>
+});
 ```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `ArrowDown` / `ArrowRight` | Move to next radio in group |
+| `ArrowUp` / `ArrowLeft` | Move to previous radio in group |
+
+Arrow keys wrap around the group and automatically select the focused radio.
+
+## Accessibility
+
+- Contains a native `<input type="radio">` for form participation
+- Radios with the same `name` form a group with mutual exclusion
+- Focus ring shown on keyboard navigation
+- `aria-invalid` set when `invalid` is true
+- Required indicator (`*`) shown on label when `required` is true
+- Disabled state reduces opacity and prevents interaction

package/docs/components/range-slider.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/range-slider.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/range-slider.md -->
 
 # Range Slider
-`<snice-range-slider>`
 
 A two-handle slider for selecting a numeric range, with a highlighted track between the two thumbs.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/range-slider/snice-range-slider';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-range-slider.min.js"></script>
-```
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -25,11 +21,11 @@ import 'snice/components/range-slider/snice-range-slider';
 | `min` | `number` | `0` | Minimum value |
 | `max` | `number` | `100` | Maximum value |
 | `step` | `number` | `1` | Step increment |
-| `valueLow` (attr: `value-low`) | `number` | `0` | Low handle position |
-| `valueHigh` (attr: `value-high`) | `number` | `100` | High handle position |
+| `valueLow` (attr: `value-low`) | `number` | `0` | Low handle value |
+| `valueHigh` (attr: `value-high`) | `number` | `100` | High handle value |
 | `disabled` | `boolean` | `false` | Disables the slider |
 | `showTooltip` (attr: `show-tooltip`) | `boolean` | `false` | Show value tooltip on hover/drag |
-| `showLabels` (attr: `show-labels`) | `boolean` | `false` | Show min/max labels |
+| `showLabels` (attr: `show-labels`) | `boolean` | `false` | Show min/max labels below the track |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider orientation |
 
 ## Events
@@ -63,7 +59,7 @@ import 'snice/components/range-slider/snice-range-slider';
 
 ### Custom Range and Step
 
-Use the `min`, `max`, and `step` attributes to define the slider range.
+Use `min`, `max`, and `step` to define the slider range and increment.
 
 ```html
 <snice-range-slider min="0" max="1000" step="50" value-low="200" value-high="800"></snice-range-slider>
@@ -71,7 +67,7 @@ Use the `min`, `max`, and `step` attributes to define the slider range.
 
 ### Tooltips
 
-Set the `show-tooltip` attribute to display the current value on hover and drag.
+Set `show-tooltip` to display the current value on hover and drag.
 
 ```html
 <snice-range-slider show-tooltip value-low="25" value-high="75"></snice-range-slider>
@@ -79,7 +75,7 @@ Set the `show-tooltip` attribute to display the current value on hover and drag.
 
 ### Min/Max Labels
 
-Set the `show-labels` attribute to display the range boundaries below the track.
+Set `show-labels` to display the range boundaries below the track.
 
 ```html
 <snice-range-slider show-labels min="0" max="500" value-low="100" value-high="400"></snice-range-slider>
@@ -87,7 +83,7 @@ Set the `show-labels` attribute to display the range boundaries below the track.
 
 ### Vertical Orientation
 
-Set the `orientation` attribute to `"vertical"` for a vertical slider.
+Set `orientation="vertical"` for a vertical slider.
 
 ```html
 <snice-range-slider orientation="vertical" value-low="30" value-high="70"></snice-range-slider>
@@ -95,7 +91,7 @@ Set the `orientation` attribute to `"vertical"` for a vertical slider.
 
 ### Disabled
 
-Set the `disabled` attribute to prevent user interaction.
+Set `disabled` to prevent user interaction.
 
 ```html
 <snice-range-slider disabled value-low="20" value-high="60"></snice-range-slider>
@@ -103,14 +99,29 @@ Set the `disabled` attribute to prevent user interaction.
 
 ### Event Handling
 
-Listen to the `range-change` event to react to value changes.
-
-```html
-<snice-range-slider id="price-range" min="0" max="500" value-low="50" value-high="300"></snice-range-slider>
+Listen to `range-change` to react to value changes.
 
-<script>
-  document.getElementById('price-range').addEventListener('range-change', (e) => {
-    console.log(`Price range: $${e.detail.valueLow} - $${e.detail.valueHigh}`);
-  });
-</script>
+```typescript
+slider.addEventListener('range-change', (e) => {
+  console.log(`Range: ${e.detail.valueLow} - ${e.detail.valueHigh}`);
+});
 ```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `ArrowLeft` / `ArrowDown` | Decrease focused thumb by one step |
+| `ArrowRight` / `ArrowUp` | Increase focused thumb by one step |
+| `Home` | Move focused thumb to minimum (low thumb) or to low value (high thumb) |
+| `End` | Move focused thumb to high value (low thumb) or to maximum (high thumb) |
+
+Each thumb is independently focusable and constrained so low cannot exceed high.
+
+## Accessibility
+
+- Each thumb has `role="slider"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Low thumb labeled "Range minimum", high thumb labeled "Range maximum"
+- Focus ring shown on keyboard navigation
+- Supports both mouse and touch interaction
+- Track click moves the nearest thumb