snice 4.8.0 → 4.9.0

package/docs/components/camera-annotate.md

@@ -0,0 +1,186 @@
+# Camera Annotate Component
+
+The camera annotate component combines camera capture with freehand drawing and labeled annotations. It provides a workflow for taking pictures, drawing shapes on them, and adding descriptive labels to each annotation.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Examples](#examples)
+- [Annotation Workflow](#annotation-workflow)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+```html
+<snice-camera-annotate></snice-camera-annotate>
+```
+
+```typescript
+import 'snice/components/camera-annotate/snice-camera-annotate';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'camera' \| 'annotate'` | `'camera'` | Current mode of the component |
+| `auto-rotate-colors` | `boolean` | `true` | Automatically cycle through preset colors for each new annotation |
+| `show-labels-panel` | `boolean` | `true` | Show the sidebar panel with annotation labels |
+
+## Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `capture()` | `Promise<void>` | Capture current camera frame and switch to annotate mode |
+| `exportImage(options?)` | `string` | Export annotated image as data URL. Options: `{ includeLabels?: boolean }` |
+| `exportAnnotations()` | `AnnotationData` | Export all annotation data as a serializable object |
+| `importAnnotations(data)` | `void` | Load annotation data from a previously exported object |
+| `clearAnnotations()` | `void` | Remove all annotations and strokes |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/capture` | `{ dataURL, width, height }` | Fired when an image is captured from the camera |
+| `@snice/annotate` | `{ annotation }` | Fired when a new annotation (shape) is drawn |
+| `@snice/annotation-change` | `{ annotations }` | Fired when annotations are modified (add, remove, visibility, label) |
+
+## Examples
+
+### Default Camera Annotator
+
+```html
+<snice-camera-annotate></snice-camera-annotate>
+```
+
+### Without Labels Panel
+
+```html
+<snice-camera-annotate show-labels-panel="false"></snice-camera-annotate>
+```
+
+### Manual Color Selection
+
+```html
+<snice-camera-annotate auto-rotate-colors="false"></snice-camera-annotate>
+```
+
+### Listening to Events
+
+```html
+<snice-camera-annotate id="annotator"></snice-camera-annotate>
+
+<script type="module">
+  const annotator = document.getElementById('annotator');
+
+  annotator.addEventListener('@snice/capture', (e) => {
+    console.log('Captured:', e.detail.width, 'x', e.detail.height);
+  });
+
+  annotator.addEventListener('@snice/annotate', (e) => {
+    console.log('New annotation:', e.detail.annotation.id);
+  });
+
+  annotator.addEventListener('@snice/annotation-change', (e) => {
+    console.log('Total annotations:', e.detail.annotations.length);
+  });
+</script>
+```
+
+### Save and Load Annotations
+
+```html
+<snice-camera-annotate id="annotator"></snice-camera-annotate>
+
+<script type="module">
+  const annotator = document.getElementById('annotator');
+
+  // Save
+  function saveAnnotations() {
+    const data = annotator.exportAnnotations();
+    localStorage.setItem('annotations', JSON.stringify(data));
+  }
+
+  // Load
+  function loadAnnotations() {
+    const json = localStorage.getItem('annotations');
+    if (json) {
+      annotator.importAnnotations(JSON.parse(json));
+    }
+  }
+</script>
+```
+
+### Export Image
+
+```html
+<snice-camera-annotate id="annotator"></snice-camera-annotate>
+<button onclick="downloadImage()">Download</button>
+
+<script type="module">
+  function downloadImage() {
+    const annotator = document.getElementById('annotator');
+
+    // Without labels on the image
+    const imageOnly = annotator.exportImage();
+
+    // With labels rendered on the image
+    const withLabels = annotator.exportImage({ includeLabels: true });
+
+    // Download
+    const a = document.createElement('a');
+    a.href = withLabels;
+    a.download = 'annotated.png';
+    a.click();
+  }
+</script>
+```
+
+## Annotation Workflow
+
+1. **Camera Mode**: The component starts showing a live camera feed
+2. **Capture**: Click the "Capture" button to take a photo
+3. **Annotate Mode**: Draw shapes on the captured image using freehand strokes
+4. **Label**: Type labels for each annotation in the sidebar
+5. **Manage**: Show/hide individual annotations, toggle all, or delete specific ones
+6. **Export**: Save annotation data as JSON or export the annotated image
+7. **Retake**: Click "Retake" to return to camera mode and start fresh
+
+### Color System
+
+- **Preset Palette**: 12 preset colors displayed as swatches in the sidebar
+- **Auto Rotate**: When enabled (default), each new annotation automatically gets the next color from the palette
+- **Manual Selection**: Click any color swatch to set the active drawing color
+
+### Visual Highlighting
+
+When you hover over an annotation label in the sidebar:
+- The corresponding shape is highlighted at full opacity
+- All other shapes dim to 20% opacity with a grayscale filter
+- This makes it easy to identify which shape belongs to which label
+
+## Accessibility
+
+- Color swatches have title attributes showing the hex value
+- Annotation visibility toggles have descriptive title text
+- Delete buttons have clear title labels
+- The sidebar scrolls independently when annotations exceed available space
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires camera access via `getUserMedia`
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Grant camera permissions**: Ensure users have allowed camera access for the capture workflow
+2. **Add labels promptly**: Label annotations as you draw them for better organization
+3. **Use auto-rotate colors**: Keeps annotations visually distinct without manual color selection
+4. **Export regularly**: Save annotation data to prevent loss on page refresh
+5. **Use the sidebar**: Hovering labels helps verify which shape corresponds to which annotation
+6. **Clear before starting fresh**: Use clearAnnotations() or "Retake" to reset
+7. **Export with labels**: When sharing annotated images, include labels for context

package/docs/components/candlestick.md

@@ -0,0 +1,196 @@
+# Candlestick Chart Component
+
+The candlestick chart component renders an SVG-based OHLC (Open-High-Low-Close) financial chart, commonly used for stock market and cryptocurrency price visualization. It supports volume bars, crosshair overlay, zoom/pan, tooltips, and responsive sizing.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+```html
+<snice-candlestick id="chart"></snice-candlestick>
+
+<script type="module">
+  import 'snice/components/candlestick/snice-candlestick';
+
+  const chart = document.getElementById('chart');
+  chart.data = [
+    { date: '2024-01-01', open: 100, high: 110, low: 95, close: 105, volume: 500000 },
+    { date: '2024-01-02', open: 105, high: 115, low: 100, close: 98, volume: 600000 },
+    { date: '2024-01-03', open: 98, high: 108, low: 93, close: 107, volume: 450000 },
+  ];
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `CandleData[]` | `[]` | Array of candlestick data points |
+| `show-volume` | `boolean` | `false` | Show volume bars below the price chart |
+| `show-grid` | `boolean` | `true` | Show horizontal grid lines |
+| `show-crosshair` | `boolean` | `true` | Show crosshair overlay on hover |
+| `bullish-color` | `string` | `''` | Custom color for bullish candles (close >= open) |
+| `bearish-color` | `string` | `''` | Custom color for bearish candles (close < open) |
+| `time-format` | `string` | `'auto'` | Date format: `'auto'`, `'date'`, `'time'`, `'datetime'`, `'month'`, `'year'` |
+| `y-axis-format` | `string` | `'number'` | Y-axis format: `'number'`, `'currency'`, `'percent'` |
+| `zoom-enabled` | `boolean` | `true` | Enable scroll-to-zoom and drag-to-pan |
+| `animation` | `boolean` | `true` | Animate candle appearance on data change |
+
+### CandleData Interface
+
+```typescript
+interface CandleData {
+  date: string | number | Date;   // Timestamp or date string
+  open: number;                     // Opening price
+  high: number;                     // Highest price
+  low: number;                      // Lowest price
+  close: number;                    // Closing price
+  volume?: number;                  // Trading volume (optional)
+}
+```
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `resetZoom()` | `() => void` | Reset zoom to show all data points |
+| `zoomTo()` | `(startIndex: number, endIndex: number) => void` | Zoom to a specific index range |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/candle-click` | `{ candle: CandleData, index: number }` | A candle was clicked |
+| `@snice/candle-hover` | `{ candle: CandleData, index: number }` | Mouse entered a candle |
+| `@snice/crosshair-move` | `{ price: number, date: string, x: number, y: number }` | Crosshair position changed |
+
+## Examples
+
+### With Volume Bars
+
+```html
+<snice-candlestick id="vol-chart" show-volume></snice-candlestick>
+```
+
+### Custom Colors
+
+```html
+<snice-candlestick bullish-color="#0088ff" bearish-color="#ff6600"></snice-candlestick>
+```
+
+### Currency Format (Stock Prices)
+
+```html
+<snice-candlestick id="stock-chart" y-axis-format="currency" show-volume></snice-candlestick>
+
+<script>
+  stockChart.data = [
+    { date: '2024-01-02', open: 42500, high: 42850, low: 42200, close: 42700, volume: 15000000 },
+    // ...
+  ];
+</script>
+```
+
+### Minimal (No Grid, No Crosshair)
+
+```html
+<snice-candlestick show-grid="false" show-crosshair="false"></snice-candlestick>
+```
+
+### Zoom Controls
+
+```html
+<button onclick="chart.resetZoom()">Reset Zoom</button>
+<button onclick="chart.zoomTo(0, 30)">First 30 Days</button>
+<snice-candlestick id="chart" zoom-enabled></snice-candlestick>
+```
+
+### Listening to Events
+
+```html
+<snice-candlestick id="chart"></snice-candlestick>
+
+<script>
+  chart.addEventListener('@snice/candle-click', (e) => {
+    console.log('Clicked candle:', e.detail.candle);
+    console.log('Index:', e.detail.index);
+  });
+
+  chart.addEventListener('@snice/crosshair-move', (e) => {
+    console.log('Price at cursor:', e.detail.price);
+    console.log('Date at cursor:', e.detail.date);
+  });
+</script>
+```
+
+### Dynamic Data Updates
+
+```html
+<snice-candlestick id="live-chart" show-volume></snice-candlestick>
+
+<script>
+  // Add new candle every 5 seconds
+  setInterval(() => {
+    const data = [...liveChart.data];
+    const last = data[data.length - 1];
+    const change = (Math.random() - 0.5) * 10;
+    const open = last.close;
+    const close = open + change;
+    data.push({
+      date: new Date(),
+      open,
+      high: Math.max(open, close) + Math.random() * 3,
+      low: Math.min(open, close) - Math.random() * 3,
+      close,
+      volume: Math.floor(Math.random() * 1000000)
+    });
+    liveChart.data = data;
+  }, 5000);
+</script>
+```
+
+## CSS Custom Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--snice-candlestick-bullish` | `rgb(22 163 74)` (green) | Bullish candle color |
+| `--snice-candlestick-bearish` | `rgb(220 38 38)` (red) | Bearish candle color |
+
+You can also override colors globally using these CSS custom properties:
+
+```css
+snice-candlestick {
+  --snice-candlestick-bullish: #26a69a;
+  --snice-candlestick-bearish: #ef5350;
+}
+```
+
+## Accessibility
+
+- **ARIA role**: The SVG has `role="img"` for screen reader identification
+- **ARIA label**: Includes data point count in `aria-label`
+- **Keyboard**: Zoom and pan are mouse-driven; use `resetZoom()` and `zoomTo()` methods for programmatic control
+- **Color contrast**: Default bullish (green) and bearish (red) colors meet WCAG AA standards
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Set data via property**: Data is an array of objects, set via JavaScript (`chart.data = [...]`), not as an HTML attribute
+2. **Include volume data**: Even if not displayed, volume data enriches tooltips
+3. **Use appropriate time formats**: Match `time-format` to your data granularity (intraday = `'time'`, daily = `'date'`, monthly = `'month'`)
+4. **Give the chart height**: The component needs an explicit height (set via CSS or a container)
+5. **Limit visible candles**: For large datasets, the chart auto-limits visible candles; use `zoomTo()` for specific ranges
+6. **Handle events**: Use `@snice/candle-click` for drill-down, `@snice/crosshair-move` for real-time price readout
+7. **Custom colors**: Use `bullish-color` / `bearish-color` or CSS custom properties for theme integration
+8. **Responsive**: The chart uses `ResizeObserver` and redraws on container resize

package/docs/components/funnel.md

@@ -0,0 +1,191 @@
+# Funnel Component
+
+The funnel component renders an SVG-based funnel/conversion chart, ideal for visualizing pipeline stages, conversion funnels, and drop-off analysis. Each stage is rendered as a trapezoid shape that narrows proportionally to its value.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+```html
+<snice-funnel id="my-funnel"></snice-funnel>
+
+<script type="module">
+  import 'snice/components/funnel/snice-funnel';
+
+  const funnel = document.getElementById('my-funnel');
+  funnel.data = [
+    { label: 'Visitors', value: 10000 },
+    { label: 'Leads', value: 5000 },
+    { label: 'Opportunities', value: 2000 },
+    { label: 'Customers', value: 500 },
+  ];
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `FunnelStage[]` | `[]` | Array of stage objects with label, value, and optional color |
+| `variant` | `'default' \| 'gradient'` | `'default'` | Color variant - default uses distinct colors, gradient uses opacity fade |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Funnel layout direction |
+| `show-labels` | `boolean` | `true` | Whether to display stage labels |
+| `show-values` | `boolean` | `true` | Whether to display stage values |
+| `show-percentages` | `boolean` | `true` | Whether to display conversion percentages |
+| `animation` | `boolean` | `false` | Whether to animate stages on initial render |
+
+### FunnelStage Interface
+
+```typescript
+interface FunnelStage {
+  label: string;     // Stage name (e.g., "Visitors")
+  value: number;     // Numeric value for the stage
+  color?: string;    // Optional custom color (CSS color string)
+}
+```
+
+## Methods
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `setStages(stages)` | `void` | Set funnel data programmatically (alternative to setting `data` property) |
+| `exportImage(format?)` | `string` | Export the funnel as a data URL. Format: `'png'` (default) or `'svg'` |
+
+### Export Example
+
+```javascript
+const funnel = document.getElementById('my-funnel');
+
+// Export as SVG
+const svgDataUrl = funnel.exportImage('svg');
+
+// Export as PNG
+const pngDataUrl = funnel.exportImage('png');
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `funnel-click` | `{ stage: FunnelStage, index: number }` | Fired when a stage is clicked |
+| `funnel-hover` | `{ stage: FunnelStage, index: number }` | Fired when a stage is hovered |
+
+```javascript
+funnel.addEventListener('funnel-click', (e) => {
+  console.log('Clicked stage:', e.detail.stage.label);
+  console.log('Stage index:', e.detail.index);
+});
+```
+
+## Examples
+
+### Conversion Funnel
+
+```html
+<snice-funnel id="conversion"></snice-funnel>
+<script>
+  document.getElementById('conversion').data = [
+    { label: 'Website Visits', value: 50000 },
+    { label: 'Sign Ups', value: 12000 },
+    { label: 'Trial Started', value: 5000 },
+    { label: 'Paid', value: 1500 },
+    { label: 'Retained', value: 800 },
+  ];
+</script>
+```
+
+### Gradient Variant
+
+The gradient variant uses decreasing opacity of the primary color for a smoother visual effect.
+
+```html
+<snice-funnel id="gradient-funnel" variant="gradient"></snice-funnel>
+```
+
+### Custom Colors
+
+```html
+<snice-funnel id="colored-funnel"></snice-funnel>
+<script>
+  document.getElementById('colored-funnel').data = [
+    { label: 'Awareness', value: 10000, color: 'rgb(37 99 235)' },
+    { label: 'Interest', value: 6000, color: 'rgb(22 163 74)' },
+    { label: 'Decision', value: 2500, color: 'rgb(234 179 8)' },
+    { label: 'Action', value: 1000, color: 'rgb(220 38 38)' },
+  ];
+</script>
+```
+
+### Horizontal Layout
+
+```html
+<snice-funnel id="horizontal" orientation="horizontal"></snice-funnel>
+```
+
+### With Animation
+
+```html
+<snice-funnel id="animated" animation></snice-funnel>
+```
+
+### Minimal Display
+
+```html
+<snice-funnel id="minimal" show-labels="false" show-percentages="false"></snice-funnel>
+```
+
+### Event Handling
+
+```html
+<snice-funnel id="interactive"></snice-funnel>
+<div id="output"></div>
+
+<script>
+  const funnel = document.getElementById('interactive');
+  const output = document.getElementById('output');
+
+  funnel.data = [
+    { label: 'Step 1', value: 1000 },
+    { label: 'Step 2', value: 600 },
+    { label: 'Step 3', value: 200 },
+  ];
+
+  funnel.addEventListener('funnel-click', (e) => {
+    output.textContent = `Clicked: ${e.detail.stage.label} (${e.detail.stage.value})`;
+  });
+</script>
+```
+
+## Accessibility
+
+- **ARIA role**: The SVG has `role="img"` with `aria-label="Funnel chart"`
+- **Interactive stages**: Each stage has `role="button"` and `tabindex="0"` for keyboard navigation
+- **ARIA labels**: Each stage has a descriptive `aria-label` including the label, value, and percentage
+- **Keyboard support**: Stages can be activated with Enter or Space keys
+- **Focus styles**: Visible focus ring on keyboard navigation
+- **Color contrast**: Default colors meet WCAG AA standards
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Order data by value**: Place the largest value first for a natural funnel shape
+2. **Use meaningful labels**: Stage labels should clearly describe each step in the process
+3. **Limit stages**: 3-7 stages works best visually; more than 8 becomes hard to read
+4. **Choose colors wisely**: Use custom colors to match your brand or highlight important stages
+5. **Include percentages**: Conversion percentages help users understand drop-off rates
+6. **Use animation sparingly**: Enable animation for initial page load or dashboard reveals
+7. **Consider orientation**: Vertical works well for sidebar placement; horizontal for wide layouts
+8. **Handle click events**: Use click events to drill down into stage details
+9. **Format values**: Large numbers are automatically formatted (K/M notation)
+10. **Test responsiveness**: The SVG scales with its container width