snice 4.8.0 → 4.10.0

package/docs/components/qr-reader.md

@@ -1,337 +1,162 @@
-# QR Reader Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/qr-reader.md instead)
 
-`<snice-qr-reader>` provides QR code scanning functionality using device cameras with WebAssembly-based QR detection.
+# QR Reader
+`<snice-qr-reader>`
 
-## Features
-
-- **Camera Access**: Use front or back camera for QR code scanning
-- **Real-time Detection**: Continuous scanning with ZXing WASM decoder
-- **Auto-start**: Optional automatic camera activation on mount
-- **Event-based**: Emits events for successful scans, errors, and camera status
-- **Responsive**: Adapts to container size with proper aspect ratio
-- **Configurable Speed**: Adjust scan speed for performance vs detection speed trade-off
+A QR code scanner using device cameras with WebAssembly-based detection.
 
 ## Basic Usage
 
-```html
-<snice-qr-reader auto-start></snice-qr-reader>
-
-<script>
-  const reader = document.querySelector('snice-qr-reader');
-
-  reader.addEventListener('qr-scan', (event) => {
-    console.log('QR Code:', event.detail.data);
-  });
-</script>
+```typescript
+import 'snice/components/qr-reader/snice-qr-reader';
 ```
 
-## Properties
-
-### `auto-start`
-- **Type**: `boolean`
-- **Default**: `false`
-- **Description**: Automatically start scanning when component is mounted
-
 ```html
 <snice-qr-reader auto-start></snice-qr-reader>
-```
-
-### `camera`
-- **Type**: `'front' | 'back'`
-- **Default**: `'back'`
-- **Description**: Which camera to use for scanning
 
-```html
-<snice-qr-reader camera="front"></snice-qr-reader>
+<script type="module">
+  document.querySelector('snice-qr-reader').addEventListener('qr-scan', (e) => {
+    console.log('QR Code:', e.detail.data);
+  });
+</script>
 ```
 
-### `pick-first`
-- **Type**: `boolean`
-- **Default**: `false`
-- **Description**: Scan continuously at maximum speed until first successful QR code detection, then stop and shut down camera. Ignores `scan-speed` setting.
+## Importing
 
-```html
-<!-- Scan at max speed until first QR hit, then stop -->
-<snice-qr-reader pick-first></snice-qr-reader>
+**ESM (bundler)**
+```typescript
+import 'snice/components/qr-reader/snice-qr-reader';
 ```
 
-### `manual-snap`
-- **Type**: `boolean`
-- **Default**: `false`
-- **Description**: Photo snapshot mode. Opens camera as a live viewfinder, and you manually trigger snapshot attempts by clicking the snap button.
-
+**CDN**
 ```html
-<!-- Manual photo snapshot mode -->
-<snice-qr-reader manual-snap></snice-qr-reader>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-qr-reader.min.js"></script>
 ```
 
-### `scan-speed`
-- **Type**: `number`
-- **Default**: `3`
-- **Description**: Scan speed from 1-10. Higher values = faster QR detection but more CPU usage. Lower values = slower detection but better performance. **Note**: Ignored when `pick-first` is enabled (always scans at max speed).
-
-```html
-<!-- Slow scan (better performance) -->
-<snice-qr-reader scan-speed="1"></snice-qr-reader>
-
-<!-- Medium scan (balanced, default) -->
-<snice-qr-reader scan-speed="3"></snice-qr-reader>
+## Examples
 
-<!-- Fast scan (faster detection) -->
-<snice-qr-reader scan-speed="10"></snice-qr-reader>
-```
+### Auto-Start
 
-### `tap-start`
-- **Type**: `boolean`
-- **Default**: `false`
-- **Description**: Enable tap/click interaction on the camera viewport to start/stop scanning. When enabled, clicking or tapping anywhere on the video preview will toggle scanning on/off.
+Set `auto-start` to begin scanning when the component mounts.
 
 ```html
-<!-- Enable tap to start/stop -->
-<snice-qr-reader tap-start></snice-qr-reader>
-```
-
-## Methods
-
-### `start()`
-Start the camera and begin scanning for QR codes (or open camera for manual-snap mode).
-
-```javascript
-const reader = document.querySelector('snice-qr-reader');
-reader.start();
-```
-
-### `stop()`
-Stop scanning and release the camera.
-
-```javascript
-reader.stop();
-```
-
-### `snap()`
-Take a snapshot and check for QR codes (manual-snap mode only).
-
-```javascript
-const result = await reader.snap(); // Returns QR data or null
-```
-
-## Events
-
-### `qr-scan`
-Fired when a QR code is successfully detected.
-
-**Detail Properties:**
-- `data` (string): The decoded QR code content
-- `timestamp` (number): Unix timestamp of the scan
-- `reader` (SniceQRReader): Reference to the component
-
-```javascript
-reader.addEventListener('qr-scan', (event) => {
-  console.log('Data:', event.detail.data);
-  console.log('Time:', new Date(event.detail.timestamp));
-});
-```
-
-### `qr-error`
-Fired when an error occurs during scanning.
-
-**Detail Properties:**
-- `error` (any): Error object or message
-- `reader` (SniceQRReader): Reference to the component
-
-```javascript
-reader.addEventListener('qr-error', (event) => {
-  console.error('Error:', event.detail.error);
-});
-```
-
-### `camera-ready`
-Fired when the camera has been successfully initialized and is ready to scan.
-
-**Detail Properties:**
-- `reader` (SniceQRReader): Reference to the component
-
-```javascript
-reader.addEventListener('camera-ready', (event) => {
-  console.log('Camera is ready');
-});
-```
-
-### `camera-error`
-Fired when camera initialization fails.
-
-**Detail Properties:**
-- `error` (any): Error object or message
-- `reader` (SniceQRReader): Reference to the component
-
-```javascript
-reader.addEventListener('camera-error', (event) => {
-  console.error('Camera error:', event.detail.error);
-});
+<snice-qr-reader auto-start></snice-qr-reader>
 ```
 
-## Examples
-
 ### Manual Control
 
 ```html
 <snice-qr-reader id="reader"></snice-qr-reader>
-<button onclick="startReading()">Start</button>
-<button onclick="stopReading()">Stop</button>
-<div id="result"></div>
-
-<script>
-  const reader = document.getElementById('reader');
-  const result = document.getElementById('result');
-
-  function startReading() {
-    reader.start();
-  }
-
-  function stopReading() {
-    reader.stop();
-  }
-
-  reader.addEventListener('qr-scan', (e) => {
-    result.textContent = `Scanned: ${e.detail.data}`;
-  });
-</script>
+<button onclick="document.getElementById('reader').start()">Start</button>
+<button onclick="document.getElementById('reader').stop()">Stop</button>
 ```
 
 ### Pick-First (One-Shot)
 
+Set `pick-first` to scan at maximum speed until the first QR code is found, then auto-stop.
+
 ```html
 <snice-qr-reader id="scanner" pick-first></snice-qr-reader>
 
-<script>
+<script type="module">
   const scanner = document.getElementById('scanner');
-
   scanner.addEventListener('qr-scan', (e) => {
-    // Process the scan
-    processQRCode(e.detail.data);
-
-    // Scanner automatically stops and shuts down camera
+    console.log('Found:', e.detail.data);
+    // Scanner stops and releases camera automatically
   });
-
-  // Start scanning at max speed
   scanner.start();
 </script>
 ```
 
 ### Manual Snapshot
 
+Set `manual-snap` for a photo-based scanning mode with manual trigger.
+
 ```html
 <snice-qr-reader id="snapReader" manual-snap></snice-qr-reader>
 <button id="snapBtn">Take Photo</button>
 
-<script>
+<script type="module">
   const reader = document.getElementById('snapReader');
-  const btn = document.getElementById('snapBtn');
-
-  // Open camera
-  reader.start();
+  reader.start(); // Opens camera viewfinder
 
-  // Manually trigger snapshot
-  btn.addEventListener('click', async () => {
+  document.getElementById('snapBtn').addEventListener('click', async () => {
     const result = await reader.snap();
-    if (result) {
-      console.log('QR Code:', result);
-    } else {
-      console.log('No QR code found');
-    }
+    console.log(result ? `Found: ${result}` : 'No QR code found');
   });
 </script>
 ```
 
 ### Front Camera
 
+Use `camera="front"` for self-scanning scenarios.
+
 ```html
 <snice-qr-reader camera="front" auto-start></snice-qr-reader>
-
-<script>
-  // Useful for self-scanning scenarios
-  document.querySelector('snice-qr-reader')
-    .addEventListener('qr-scan', (e) => {
-      validateTicket(e.detail.data);
-    });
-</script>
 ```
 
-### Error Handling
-
-```html
-<snice-qr-reader id="reader" auto-start></snice-qr-reader>
-<div id="status"></div>
-
-<script>
-  const reader = document.getElementById('reader');
-  const status = document.getElementById('status');
-
-  reader.addEventListener('qr-scan', (e) => {
-    status.textContent = `✓ Scanned: ${e.detail.data}`;
-    status.style.color = 'green';
-  });
+### Scan Speed
 
-  reader.addEventListener('qr-error', (e) => {
-    status.textContent = `✗ Error: ${e.detail.error}`;
-    status.style.color = 'red';
+Use `scan-speed` (1-10) to balance detection speed vs CPU usage.
 
-    // Retry after error
-    setTimeout(() => reader.start(), 2000);
-  });
-</script>
+```html
+<snice-qr-reader scan-speed="1" auto-start></snice-qr-reader>
+<snice-qr-reader scan-speed="10" auto-start></snice-qr-reader>
 ```
 
-## Styling
+### Tap to Start
 
-The component uses CSS custom properties for theming:
+Set `tap-start` to let users click the viewport to toggle scanning.
 
-```css
-snice-qr-reader {
-  --qr-reader-border: var(--snice-color-border, #e5e7eb);
-  --qr-reader-bg: var(--snice-color-bg, #ffffff);
-  --qr-reader-text: var(--snice-color-text, #1f2937);
-
-  /* Size */
-  width: 100%;
-  max-width: 600px;
-}
+```html
+<snice-qr-reader tap-start></snice-qr-reader>
 ```
 
-## Browser Support
+### Error Handling
 
-- Requires `getUserMedia` API support
-- Uses WebAssembly for QR detection (ZXing)
-- Works on modern browsers (Chrome, Firefox, Safari, Edge)
-- Mobile browser camera access requires HTTPS
+```typescript
+const reader = document.querySelector('snice-qr-reader');
 
-## Implementation Details
+reader.addEventListener('qr-error', (e) => {
+  console.error('Scan error:', e.detail.error);
+});
 
-### QR Detection
-Uses ZXing-C++ WebAssembly build for fast, accurate QR code detection:
-- **License**: Apache 2.0 (ZXing-C++) + MIT (zxing-wasm)
-- **Format Support**: QR Code, Micro QR Code
-- **Performance**: ~60fps scanning on modern devices
+reader.addEventListener('camera-error', (e) => {
+  console.error('Camera error:', e.detail.error);
+});
 
-### Camera Management
-- Requests user permission for camera access
-- Automatically releases camera when component is destroyed
-- Handles camera errors gracefully with fallback messages
+reader.addEventListener('camera-ready', () => {
+  console.log('Camera initialized');
+});
+```
 
-### Privacy
-- Camera feed stays in the browser (no uploads)
-- QR data is only emitted via events
-- Camera is released when scanning stops
+## Properties
 
-## Related Components
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `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 |
 
-- `<snice-qr-code>` - Generate QR codes
-- `<snice-camera>` - General camera capture component
+## Events
 
-## License
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `qr-scan` | `{ data: string, timestamp: number, reader }` | QR code detected |
+| `qr-error` | `{ error: any, reader }` | Scan error occurred |
+| `camera-ready` | `{ reader }` | Camera initialized |
+| `camera-error` | `{ error: any, reader }` | Camera initialization failed |
 
-QR detection powered by:
-- **ZXing-C++**: Apache License 2.0
-- **zxing-wasm**: MIT License
+## Methods
 
-See `components/qr-reader/ZXING-LICENSE` for full license text.
+| 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 |

package/docs/components/radio.md

@@ -0,0 +1,151 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/radio.md instead)
+
+# Radio
+`<snice-radio>`
+
+A form radio button input with automatic group management by name.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/radio/snice-radio';
+```
+
+```html
+<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>
+```
+
+## Importing
+
+**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>
+```
+
+## Examples
+
+### Pre-selected
+
+Set the `checked` attribute to pre-select a radio button.
+
+```html
+<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>
+```
+
+### Sizes
+
+Use the `size` attribute to change the radio button size.
+
+```html
+<snice-radio label="Small" size="small"></snice-radio>
+<snice-radio label="Medium" size="medium"></snice-radio>
+<snice-radio label="Large" size="large"></snice-radio>
+```
+
+### Disabled
+
+Set the `disabled` attribute to prevent interaction.
+
+```html
+<snice-radio label="Unavailable" disabled></snice-radio>
+<snice-radio label="Selected but disabled" checked disabled></snice-radio>
+```
+
+### Required
+
+Set the `required` attribute to mark the field as required in forms.
+
+```html
+<snice-radio name="terms" value="accept" label="I accept the terms" required></snice-radio>
+```
+
+### Invalid
+
+Set the `invalid` attribute to show validation error styling.
+
+```html
+<snice-radio label="Invalid selection" invalid></snice-radio>
+```
+
+### Loading
+
+Set the `loading` attribute to show a spinner instead of the radio dot.
+
+```html
+<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>
+```
+
+### Event Handling
+
+```html
+<snice-radio id="option" name="choice" value="a" label="Option A"></snice-radio>
+
+<script type="module">
+  import 'snice/components/radio/snice-radio';
+
+  document.getElementById('option').addEventListener('radio-change', (e) => {
+    console.log('Selected:', e.detail.value);
+  });
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `checked` | `boolean` | `false` | Whether the radio is selected |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `loading` | `boolean` | `false` | Shows spinner instead of dot |
+| `required` | `boolean` | `false` | Marks as required for forms |
+| `invalid` | `boolean` | `false` | Shows invalid state styling |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Radio button size |
+| `name` | `string` | `''` | Group name for mutual exclusion |
+| `value` | `string` | `''` | Form value when selected |
+| `label` | `string` | `''` | Label text |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `radio-change` | `{ checked: boolean, value: string, radio: SniceRadioElement }` | Fired when the selection changes |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | -- | Focuses the radio input |
+| `blur()` | -- | Removes focus |
+| `click()` | -- | Programmatic click |
+| `select()` | -- | Selects the radio and fires change event |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | The hidden radio input |
+| `radio` | The radio circle container |
+| `dot` | The inner dot indicator |
+| `spinner` | The loading spinner |
+| `label` | The label text |