snice 4.27.0 → 4.29.0

package/docs/components/camera.md

@@ -1,142 +1,74 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/camera.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/camera.md -->
 
 # Camera Component
 
-Live camera feed with built-in mobile-style controls and flexible positioning.
+Live camera feed with built-in mobile-style controls, flexible positioning, aspect ratio presets, and fullscreen support.
+
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `autoStart` | `boolean` | `true` | Auto-start camera on load |
-| `facingMode` | `'user' \| 'environment'` | `'user'` | Front or back camera |
+| `autoStart` (attr: `auto-start`) | `boolean` | `true` | Auto-start camera on load |
+| `facingMode` (attr: `facing-mode`) | `'user' \| 'environment'` | `'user'` | Front or back camera |
 | `mirror` | `boolean` | `true` | Mirror video for front camera |
-| `controlsPosition` | `ControlsPosition` | `'auto'` | Control button positioning |
-| `showControls` | `boolean` | `true` | Show built-in controls |
+| `controlsPosition` (attr: `controls-position`) | `ControlsPosition` | `'auto'` | Control button positioning |
+| `showControls` (attr: `show-controls`) | `boolean` | `true` | Show built-in controls |
 | `width` | `number` | `1280` | Video width (resolution) |
 | `height` | `number` | `720` | Video height (resolution) |
-| `aspectRatio` | `string` | `'auto'` | Aspect ratio: `'auto'` (fills space), `'16:9'`, `'9:16'`, `'4:3'`, `'1:1'`, `'21:9'` |
-| `objectFit` | `'contain' \| 'cover'` | `'cover'` | How video fits container: `cover` (fills frame, may crop) or `contain` (full video, may letterbox) |
+| `aspectRatio` (attr: `aspect-ratio`) | `string` | `'auto'` | Aspect ratio: `'auto'`, `'16:9'`, `'9:16'`, `'4:3'`, `'1:1'`, `'21:9'` |
+| `objectFit` (attr: `object-fit`) | `'contain' \| 'cover'` | `'cover'` | How video fits container |
 
 ## Methods
 
-### `start(): Promise<void>`
-Start camera feed.
-
-```javascript
-await camera.start();
-```
-
-### `stop(): void`
-Stop camera and release resources.
-
-```javascript
-camera.stop();
-```
-
-### `capture(): Promise<CapturedImage>`
-Capture current frame as image.
-
-```javascript
-const image = await camera.capture();
-// Returns: { dataURL, blob, width, height, timestamp }
-```
-
-### `switchCamera(): Promise<void>`
-Toggle between front/back camera.
-
-```javascript
-await camera.switchCamera();
-```
-
-### `isActive(): boolean`
-Check if camera is running.
-
-```javascript
-if (camera.isActive()) {
-  // Camera is on
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `start()` | -- | `Promise<void>` | Start camera feed |
+| `stop()` | -- | `void` | Stop camera and release resources |
+| `capture()` | -- | `Promise<CapturedImage>` | Capture current frame as image |
+| `switchCamera()` | -- | `Promise<void>` | Toggle between front/back camera |
+| `isActive()` | -- | `boolean` | Check if camera is running |
+| `getStream()` | -- | `MediaStream \| null` | Get current media stream |
+| `enterFullscreen()` | -- | `void` | Enter fullscreen mode |
+| `exitFullscreen()` | -- | `void` | Exit fullscreen mode |
+| `toggleFullscreen()` | -- | `void` | Toggle fullscreen mode |
+
+### CapturedImage
+
+```typescript
+interface CapturedImage {
+  dataURL: string;
+  blob: Blob;
+  width: number;
+  height: number;
+  timestamp: number;
 }
 ```
 
-### `getStream(): MediaStream | null`
-Get current media stream.
-
-```javascript
-const stream = camera.getStream();
-```
-
-### `enterFullscreen(): void`
-Enter fullscreen mode.
-
-```javascript
-camera.enterFullscreen();
-```
-
-### `exitFullscreen(): void`
-Exit fullscreen mode.
-
-```javascript
-camera.exitFullscreen();
-```
-
-### `toggleFullscreen(): void`
-Toggle fullscreen mode.
-
-```javascript
-camera.toggleFullscreen();
-```
-
 ## Events
 
-### `camera-start`
-Camera started successfully.
-
-```javascript
-camera.addEventListener('camera-start', (e) => {
-  console.log('Camera on', e.detail.stream);
-});
-```
-
-### `camera-stop`
-Camera stopped.
-
-```javascript
-camera.addEventListener('camera-stop', () => {
-  console.log('Camera off');
-});
-```
-
-### `camera-capture`
-Photo captured.
-
-```javascript
-camera.addEventListener('camera-capture', (e) => {
-  const image = e.detail.image;
-  console.log(image.dataURL);
-});
-```
-
-### `camera-error`
-Camera error occurred.
-
-```javascript
-camera.addEventListener('camera-error', (e) => {
-  console.error(e.detail.error);
-});
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `camera-start` | `{ stream: MediaStream }` | Camera started successfully |
+| `camera-stop` | -- | Camera stopped |
+| `camera-capture` | `{ image: CapturedImage }` | Photo captured |
+| `camera-error` | `{ error: Error }` | Camera error occurred |
 
 ## Slots
 
-### `controls`
-Custom controls overlay area. Full viewport, positioned absolutely.
-
-```html
-<snice-camera>
-  <div slot="controls" style="position: absolute; top: 10px; left: 10px; color: white; background: rgba(0,0,0,0.5); padding: 8px 12px; border-radius: 4px;">
-    LIVE
-  </div>
-</snice-camera>
-```
+| Name | Description |
+|------|-------------|
+| `controls` | Custom controls overlay area. Full viewport, positioned absolutely. |
 
 ## CSS Custom Properties
 
@@ -155,138 +87,101 @@ Custom controls overlay area. Full viewport, positioned absolutely.
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer camera container holding the video feed |
-| `controls` | `<div>` | Built-in control buttons area (capture and switch camera) |
-
-```css
-snice-camera::part(base) {
-  border-radius: 12px;
-  overflow: hidden;
-}
-
-snice-camera::part(controls) {
-  padding: 1rem;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | Outer camera container holding the video feed |
+| `controls` | Built-in control buttons area (capture and switch camera) |
 
 ## Basic Usage
 
 ```html
-<snice-camera id="camera"></snice-camera>
-
-<script>
-  const camera = document.getElementById('camera');
-
-  // Auto-starts by default, but you can manually start
-  await camera.start();
-
-  // Capture photo
-  const image = await camera.capture();
-  console.log(image.dataURL);
-</script>
+<snice-camera></snice-camera>
 ```
 
-## Examples
-
-### Zero Config (Recommended)
+```typescript
+import 'snice/components/camera/snice-camera';
 
-```html
-<snice-camera></snice-camera>
+const image = await camera.capture();
+console.log(image.dataURL);
 ```
 
-Auto-starts camera with controls at bottom-right (portrait) or right (landscape).
+## Examples
 
 ### Back Camera
 
+Use `facing-mode="environment"` to activate the rear camera on mobile devices.
+
 ```html
 <snice-camera facing-mode="environment"></snice-camera>
 ```
 
 ### Control Positioning
 
+Use `controls-position` to place the built-in controls at different locations.
+
 ```html
-<!-- Bottom-left corner -->
 <snice-camera controls-position="bottom-left"></snice-camera>
-
-<!-- Right edge (centered) -->
 <snice-camera controls-position="right"></snice-camera>
-
-<!-- Top-right corner -->
 <snice-camera controls-position="top-right"></snice-camera>
 ```
 
-### No Mirror
+### Aspect Ratios
+
+Use `aspect-ratio` to constrain the camera display shape.
 
 ```html
-<snice-camera mirror="false"></snice-camera>
+<snice-camera aspect-ratio="16:9"></snice-camera>
+<snice-camera aspect-ratio="1:1" width="1080" height="1080"></snice-camera>
+<snice-camera aspect-ratio="9:16" object-fit="cover" width="720" height="1280"></snice-camera>
 ```
 
 ### Custom Resolution
 
+Use `width` and `height` to request a specific camera resolution.
+
 ```html
-<!-- 4K -->
 <snice-camera width="3840" height="2160"></snice-camera>
-
-<!-- Full HD -->
 <snice-camera width="1920" height="1080"></snice-camera>
-
-<!-- VGA -->
-<snice-camera width="640" height="480"></snice-camera>
 ```
 
-### Aspect Ratios
-
-```html
-<!-- 16:9 widescreen -->
-<snice-camera aspect-ratio="16:9"></snice-camera>
-
-<!-- 9:16 portrait -->
-<snice-camera aspect-ratio="9:16" width="720" height="1280"></snice-camera>
-
-<!-- 4:3 classic -->
-<snice-camera aspect-ratio="4:3"></snice-camera>
+### Fullscreen
 
-<!-- 1:1 square -->
-<snice-camera aspect-ratio="1:1" width="1080" height="1080"></snice-camera>
+Use the fullscreen methods for immersive camera views.
 
-<!-- 21:9 ultra-wide -->
-<snice-camera aspect-ratio="21:9"></snice-camera>
+```html
+<snice-camera id="cam"></snice-camera>
+<button onclick="document.getElementById('cam').toggleFullscreen()">Fullscreen</button>
 ```
 
-### Object Fit Modes
+### Custom Overlay Controls
+
+Use the `controls` slot to add custom overlays alongside or instead of the built-in controls.
 
 ```html
-<!-- Contain (default) - Shows full video with possible letterboxing -->
-<snice-camera object-fit="contain"></snice-camera>
-
-<!-- Cover - Fills entire container, may crop video -->
-<snice-camera object-fit="cover"></snice-camera>
-
-<!-- Portrait with cover for full-screen mobile -->
-<snice-camera
-  aspect-ratio="9:16"
-  object-fit="cover"
-  width="720"
-  height="1280"
-  style="height: 100vh;">
+<snice-camera>
+  <div slot="controls" style="position: absolute; top: 10px; left: 10px; color: white; background: rgba(0,0,0,0.5); padding: 8px 12px; border-radius: 4px;">
+    LIVE
+  </div>
 </snice-camera>
 ```
 
-### Fullscreen
+### Fully Custom Controls
+
+Set `show-controls="false"` and use the `controls` slot for complete control customization.
 
 ```html
-<snice-camera id="cam"></snice-camera>
-<button onclick="document.getElementById('cam').toggleFullscreen()">
-  Fullscreen
-</button>
+<snice-camera id="camera" show-controls="false">
+  <div slot="controls" style="position: absolute; bottom: 20px; left: 50%; transform: translateX(-50%); display: flex; gap: 10px;">
+    <button onclick="document.getElementById('camera').capture()">Take Photo</button>
+    <button onclick="document.getElementById('camera').switchCamera()">Flip</button>
+  </div>
+</snice-camera>
 ```
 
 ### Save Captured Image
 
+Use the `capture()` method to get images for download or upload.
+
 ```javascript
 const image = await camera.capture();
 
@@ -302,142 +197,8 @@ formData.append('photo', image.blob, 'photo.jpg');
 await fetch('/upload', { method: 'POST', body: formData });
 ```
 
-### Photo Gallery
-
-```javascript
-const gallery = [];
-
-camera.addEventListener('camera-capture', (e) => {
-  gallery.push(e.detail.image);
-  displayGallery();
-});
-
-function displayGallery() {
-  const container = document.getElementById('gallery');
-  container.innerHTML = '';
-
-  gallery.forEach(image => {
-    const img = document.createElement('img');
-    img.src = image.dataURL;
-    img.width = 200;
-    container.appendChild(img);
-  });
-}
-```
-
-### Custom Overlay Controls (With Built-in Controls)
-
-```html
-<snice-camera>
-  <div slot="controls" class="my-controls">
-    <div class="recording-indicator">● REC</div>
-    <div class="timer">00:00</div>
-  </div>
-</snice-camera>
-
-<style>
-  .my-controls {
-    position: absolute;
-    top: 20px;
-    left: 20px;
-    right: 20px;
-    display: flex;
-    justify-content: space-between;
-    color: white;
-    font-size: 14px;
-  }
-
-  .recording-indicator {
-    color: red;
-    animation: blink 1s infinite;
-  }
-</style>
-```
-
-### Fully Custom Controls (No Built-in Controls)
-
-```html
-<snice-camera id="camera" show-controls="false">
-  <div slot="controls" class="custom-controls">
-    <button class="custom-capture" onclick="document.getElementById('camera').capture()">
-      📷 Take Photo
-    </button>
-    <button class="custom-switch" onclick="document.getElementById('camera').switchCamera()">
-      🔄 Flip
-    </button>
-  </div>
-</snice-camera>
-
-<style>
-  .custom-controls {
-    position: absolute;
-    bottom: 20px;
-    left: 50%;
-    transform: translateX(-50%);
-    display: flex;
-    gap: 10px;
-  }
-
-  .custom-capture, .custom-switch {
-    padding: 12px 24px;
-    background: rgba(255, 255, 255, 0.9);
-    border: none;
-    border-radius: 8px;
-    font-size: 16px;
-    cursor: pointer;
-  }
-</style>
-```
-
-## Control Positions
-
-| Position | Description |
-|----------|-------------|
-| `'auto'` | Auto-detect: `bottom-right` (portrait), `right` (landscape) |
-| **Corners** | |
-| `'bottom-left'` | Bottom-left corner |
-| `'bottom-right'` | Bottom-right corner |
-| `'top-left'` | Top-left corner |
-| `'top-right'` | Top-right corner |
-| **Edges** | |
-| `'bottom'` | Bottom edge (centered) |
-| `'right'` | Right edge (centered) |
-| `'left'` | Left edge (centered) |
-| `'top'` | Top edge (centered) |
-
-## Built-in Controls
-
-The camera includes built-in mobile-style controls:
-
-- **Capture button** (56px) - White circle with camera icon, positioned for thumb access
-- **Switch camera button** (40px) - Auto-hides if only one camera available
-
-Controls use Material Design-style icons and are positioned based on `controlsPosition`.
-
-## Technical Details
-
-- **Resolution**: Default 720p HD (1280x720) - configurable via `width`/`height`
-- **Format**: JPEG at 0.92 quality
-- **Mirror**: Automatically mirrors front camera video (can be disabled)
-- **Orientation**: Auto-detects portrait/landscape for control positioning
-- **Aspect Ratios**: Supports 16:9, 4:3, 1:1, 21:9 presets
-- **Fullscreen**: Native browser fullscreen API support
-
-## Security
-
-- Requires HTTPS (or localhost for development)
-- Requires user permission
-- Permission prompts are browser-controlled
-- Stream automatically stops on page unload
-
 ## Accessibility
 
 - Keyboard navigation for controls
 - Visual feedback for capture
 - Error messaging
-
-## Browser Support
-
-- Modern browsers with getUserMedia API
-- Requires camera hardware
-- May not work on some mobile browsers