snice 4.8.0 → 4.10.0

package/docs/components/book.md

@@ -0,0 +1,184 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/book.md instead)
+
+# Book Component
+
+The book component displays content as a page-flipping book with realistic 3D page-turn animations. It supports spread (two-page) and single-page modes, a customizable cover page, keyboard and touch navigation, and programmatic page control.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Slots](#slots)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [CSS Parts](#css-parts)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-book>
+  <div>Page 1 content</div>
+  <div>Page 2 content</div>
+  <div>Page 3 content</div>
+</snice-book>
+```
+
+```typescript
+import 'snice/components/book/snice-book';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `currentPage` (attr: `current-page`) | `number` | `0` | Current page number (0-indexed) |
+| `mode` | `'single' \| 'spread'` | `'spread'` | Display mode: single page or two-page spread |
+| `coverImage` (attr: `cover-image`) | `string` | `''` | URL for the cover page image |
+| `title` | `string` | `''` | Book title displayed on the cover |
+| `author` | `string` | `''` | Author name displayed on the cover |
+| `totalPages` | `number` | _(read-only)_ | Total number of pages (count of slotted child elements) |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Page elements. Each child element becomes one page in the book. |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `goToPage()` | `page: number` | Navigate to a specific page. In spread mode, auto-aligns to the correct spread. |
+| `nextPage()` | -- | Advance forward by 1 page (single mode) or 2 pages (spread mode) |
+| `prevPage()` | -- | Go back by 1 page (single mode) or 2 pages (spread mode) |
+| `firstPage()` | -- | Jump to the first page (page 0) |
+| `lastPage()` | -- | Jump to the last page |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `page-turn` | `{ page: number, direction: 'forward' \| 'backward' }` | Fired when a page turn completes |
+| `page-flip-start` | `{ fromPage: number, toPage: number, direction: 'forward' \| 'backward' }` | Fired when a page flip animation starts |
+| `page-flip-end` | `{ page: number, direction: 'forward' \| 'backward' }` | Fired when a page flip animation finishes |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--book-bg` | Page background color |
+| `--book-text` | Primary text color |
+| `--book-text-secondary` | Secondary text color |
+| `--book-border` | Border color |
+| `--book-primary` | Primary accent color |
+| `--book-shadow` | Book shadow |
+| `--book-page-bg` | Individual page background |
+| `--book-page-line` | Ruled line color on pages |
+| `--book-spine-bg` | Spine color |
+| `--book-cover-bg` | Cover background color |
+| `--book-flip-duration` | Flip animation duration (default: `0.6s`) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `spine` | The book spine element |
+| `pages` | The pages container |
+| `nav` | The navigation controls bar |
+
+## Examples
+
+### Basic Book with Cover
+
+Use the `title`, `author`, and `cover-image` attributes to create a book with a styled cover page.
+
+```html
+<snice-book title="The Great Gatsby" author="F. Scott Fitzgerald" cover-image="/covers/gatsby.jpg">
+  <div>In my younger and more vulnerable years my father gave me some advice...</div>
+  <div>Chapter 2 content here...</div>
+  <div>Chapter 3 content here...</div>
+  <div>Chapter 4 content here...</div>
+</snice-book>
+```
+
+### Single Page Mode
+
+Use `mode="single"` for narrow viewports or when you want one page visible at a time.
+
+```html
+<snice-book mode="single" title="User Guide">
+  <div>Welcome to the application...</div>
+  <div>Getting started with your first project...</div>
+  <div>Advanced features and configuration...</div>
+</snice-book>
+```
+
+### Spread Mode (Two-Page View)
+
+The default `mode="spread"` displays two pages side by side like an open book.
+
+```html
+<snice-book mode="spread" title="Photo Album" author="Jane Doe">
+  <div><img src="/photos/1.jpg" alt="Vacation day 1"></div>
+  <div><img src="/photos/2.jpg" alt="Vacation day 2"></div>
+  <div><img src="/photos/3.jpg" alt="Vacation day 3"></div>
+  <div><img src="/photos/4.jpg" alt="Vacation day 4"></div>
+</snice-book>
+```
+
+### Programmatic Navigation
+
+Use methods to control the book from JavaScript.
+
+```html
+<snice-book id="tutorial-book" title="Tutorial">
+  <div>Step 1: Install the package</div>
+  <div>Step 2: Import the component</div>
+  <div>Step 3: Add it to your HTML</div>
+  <div>Step 4: Customize with properties</div>
+</snice-book>
+
+<button onclick="document.getElementById('tutorial-book').prevPage()">Previous</button>
+<button onclick="document.getElementById('tutorial-book').nextPage()">Next</button>
+
+<script type="module">
+  import 'snice/components/book/snice-book';
+
+  const book = document.getElementById('tutorial-book');
+  book.addEventListener('page-turn', (e) => {
+    console.log(`Turned to page ${e.detail.page} (${e.detail.direction})`);
+  });
+</script>
+```
+
+### Rich HTML Content Pages
+
+Each page can contain arbitrary HTML including text, images, and interactive elements.
+
+```html
+<snice-book title="Product Catalog" mode="spread">
+  <div style="padding: 2rem;">
+    <h2>Introduction</h2>
+    <p>Browse our latest collection of premium products.</p>
+  </div>
+  <div style="padding: 2rem;">
+    <h3>Widget Pro</h3>
+    <img src="/products/widget-pro.jpg" alt="Widget Pro" style="width: 100%;">
+    <p>Our most popular product. Starting at $29.99.</p>
+  </div>
+  <div style="padding: 2rem;">
+    <h3>Gadget X</h3>
+    <img src="/products/gadget-x.jpg" alt="Gadget X" style="width: 100%;">
+    <p>Next-generation performance. Starting at $49.99.</p>
+  </div>
+</snice-book>
+```
+
+## Accessibility
+
+- **Keyboard support**: Arrow Right/Down to go to the next page, Arrow Left/Up for the previous page, Home for the first page, End for the last page
+- **Focus management**: The book is focusable and responds to keyboard input when focused
+- **Screen readers**: Page turn events and navigation controls provide feedback on the current position
+- **Touch support**: Swipe gestures on touch devices for natural page turning

package/docs/components/breadcrumbs.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/breadcrumbs.md instead)
+
 # Breadcrumbs Components
 
 The breadcrumbs components provide navigation trail indicators showing the user's current location within a hierarchy. Supports icons, custom separators, collapsing for long trails, and multiple sizes.

package/docs/components/button.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/button.md instead)
+
 # Button Component
 
 The button component provides an interactive element for user actions. It supports multiple variants, sizes, states (loading, disabled), styles (outline, pill, circle), icons, and can function as both a button and link.
@@ -25,6 +27,7 @@ import 'snice/components/button/snice-button';
 |----------|------|---------|-------------|
 | `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'text'` | `'default'` | Visual style variant |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Button type for form integration |
 | `disabled` | `boolean` | `false` | Disable the button |
 | `loading` | `boolean` | `false` | Show loading spinner |
 | `outline` | `boolean` | `false` | Use outline style |
@@ -77,6 +80,18 @@ The `icon` slot allows you to use external CSS-based icon fonts (like Material S
 
 > **Note**: When using the `icon` slot, the slotted content takes precedence over the `icon` property. The `iconPlacement` property still controls positioning.
 
+## Events
+
+#### `button-click`
+Fired when the button is clicked.
+
+**Event Detail:**
+```typescript
+{
+  originalEvent: MouseEvent;
+}
+```
+
 ## Methods
 
 #### `focus(options?: FocusOptions): void`

package/docs/components/calendar.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/calendar.md instead)
+
 # Calendar Component
 
 Display and select dates with event support.

package/docs/components/camera-annotate.md

@@ -0,0 +1,188 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/camera-annotate.md instead)
+
+# 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/camera.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/camera.md instead)
+
 # Camera Component
 
 Live camera feed with built-in mobile-style controls and flexible positioning.

package/docs/components/candlestick.md

@@ -0,0 +1,198 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/candlestick.md instead)
+
+# 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/card.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/card.md instead)
+
 # Card Component
 
 The card component provides a container for grouped content with support for headers, footers, different visual styles, interactive states, and responsive sizing.