snice 4.8.0 → 4.10.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.7.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.7.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.7.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v4.7.0
+ * snice v4.9.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/docs/ai/DEVELOPMENT.md

@@ -89,7 +89,7 @@ All CDN builds use the shared runtime (external `snice` imports). Load `snice-ru
 - IIFE: `.js` + `.min.js`
 - Sourcemaps + README
 
-**Size:** Runtime ~18KB gzip, components ~1-27KB each
+**Size:** Runtime ~18KB gzip, components ~1-93KB each
 
 **Features:**
 - Shared runtime (external snice imports)

package/docs/ai/api.md

@@ -35,12 +35,12 @@
 ## Properties
 
 ```typescript
-@property(options?: { type?, attribute?, reflect? })
+@property(options?: { type?, attribute?, converter?, hasChanged? })
 // Syncs with attributes, triggers re-render
 // Types: String (default), Number, Boolean, Object, Array
 
 @watch(...propertyNames: string[])
-// Called on property change: (oldVal, newVal) => void
+// Called on property change: (oldVal, newVal, propertyName) => void
 ```
 
 ## Lifecycle
@@ -274,6 +274,9 @@ import {
   observe,
   ready, dispose, moved, adopted,
   Router,
-  debounce, throttle, once, memoize
+  debounce, throttle, once, memoize,
+  useNativeElementControllers,   // Enable controller= on native HTML elements
+  cleanupNativeElementControllers,
+  attachController, detachController, getController
 } from 'snice';
 ```

package/docs/ai/components/accordion.md

@@ -131,39 +131,6 @@ item.collapse();
 - Accessibility: aria-expanded, button roles
 - Smooth animations
 
-## Common Patterns
-
-**FAQ:**
-```html
-<snice-accordion>
-  <snice-accordion-item item-id="q1">
-    <span slot="header">Question?</span>
-    <p>Answer.</p>
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-**Settings:**
-```html
-<snice-accordion multiple>
-  <snice-accordion-item item-id="general">
-    <span slot="header">General</span>
-    <!-- Settings form -->
-  </snice-accordion-item>
-</snice-accordion>
-```
-
-**Lazy loading:**
-```typescript
-accordion.addEventListener('accordion-open', async (e) => {
-  if (!loaded[e.detail.itemId]) {
-    const data = await fetch(`/api/${e.detail.itemId}`);
-    // Update content
-    loaded[e.detail.itemId] = true;
-  }
-});
-```
-
 ## Notes
 
 - Items are light DOM children (not slotted)
@@ -171,4 +138,3 @@ accordion.addEventListener('accordion-open', async (e) => {
 - Item IDs auto-generated if not provided
 - Disabled items cannot be toggled
 - Header slot required for trigger content
-- Full ARIA support for screen readers

package/docs/ai/components/app-tiles.md

@@ -0,0 +1,77 @@
+# snice-app-tiles
+
+App launcher grid like Google's app drawer or a phone home screen.
+
+## Properties
+
+```typescript
+// snice-app-tiles
+tiles: AppTile[] = [];           // Programmatic tile data
+columns: number = 4;             // Grid columns
+size: 'sm' | 'md' | 'lg' = 'md'; // Tile size
+variant: 'grid' | 'list' = 'grid'; // Layout variant
+
+// AppTile interface
+interface AppTile {
+  id: string;
+  name: string;
+  icon: string;       // URL, emoji, or Material Symbols ligature name
+  color?: string;     // Background color for letter/ligature fallback
+  href?: string;      // Navigate on click
+  badge?: string;     // Badge content (uses snice-badge)
+}
+```
+
+## Child Element
+
+`<snice-app-tile>` — declarative child for defining tiles in HTML.
+
+- `name` - Tile label
+- `icon` - URL, emoji, or Material Symbols ligature
+- `color` - Background color
+- `href` - Navigation URL
+- `badge` - Badge content
+
+## Events
+
+- `tile-click` -> `{ tile: AppTile, index: number }`
+
+## Icon Resolution
+
+1. No icon -> letter fallback (first char of name, colored circle)
+2. `img://` prefix or URL/path -> `<img>` element
+3. Emoji (no ASCII letters) -> emoji display
+4. ASCII text -> Material Symbols ligature
+
+## Usage
+
+```html
+<!-- Declarative -->
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Mail" icon="mail" color="rgb(220 38 38)"></snice-app-tile>
+  <snice-app-tile name="Calendar" icon="calendar_today" color="rgb(37 99 235)"></snice-app-tile>
+  <snice-app-tile name="Drive" icon="folder" color="rgb(234 88 12)" badge="3"></snice-app-tile>
+</snice-app-tiles>
+
+<!-- Programmatic with image icons -->
+<snice-app-tiles id="tiles" columns="3"></snice-app-tiles>
+<script>
+  const tiles = document.querySelector('#tiles');
+  tiles.tiles = [
+    { id: '1', name: 'Chrome', icon: 'https://example.com/chrome.svg' },
+    { id: '2', name: 'Slack', icon: 'https://example.com/slack.svg' },
+  ];
+</script>
+
+<!-- Letter fallback (no icon) -->
+<snice-app-tiles columns="3">
+  <snice-app-tile name="Slack" color="rgb(97 31 105)"></snice-app-tile>
+  <snice-app-tile name="GitHub" color="rgb(82 82 82)"></snice-app-tile>
+</snice-app-tiles>
+
+<!-- List variant -->
+<snice-app-tiles columns="1" variant="list">
+  <snice-app-tile name="Dashboard" icon="dashboard"></snice-app-tile>
+  <snice-app-tile name="Settings" icon="settings"></snice-app-tile>
+</snice-app-tiles>
+```

package/docs/ai/components/audio-recorder.md

@@ -12,6 +12,7 @@ showControls: boolean = true;
 showVisualizer: boolean = true;
 maxDuration: number = 0;
 showTimer: boolean = true;
+showPlayback: boolean = true;
 ```
 
 ## Methods
@@ -26,6 +27,7 @@ getState(): 'inactive'|'recording'|'paused'
 getDuration(): number
 isRecording(): boolean
 download(filename?: string): void
+reset(): void
 ```
 
 ## AudioRecording

package/docs/ai/components/badge.md

@@ -17,6 +17,13 @@ pulse: boolean = false;
 offset: number = 0;
 ```
 
+## Methods
+
+- `setBadgeContent(content)` - Set text content
+- `setBadgeCount(count)` - Set numeric count
+- `showDot()` - Switch to dot mode
+- `hide()` - Clear all content
+
 ## Usage
 
 ```html

package/docs/ai/components/book.md

@@ -0,0 +1,78 @@
+# snice-book
+
+Page-flipping book component with spread/single modes, cover page, touch/keyboard navigation, and animated page turns.
+
+## Properties
+
+```ts
+currentPage: number = 0          // attr: current-page
+mode: BookMode = 'spread'        // attr: mode — 'single' | 'spread'
+coverImage: string = ''          // attr: cover-image — URL for cover page image
+title: string = ''               // Book title shown on cover
+author: string = ''              // Author name shown on cover
+readonly totalPages: number      // Getter, count of slotted page elements
+```
+
+## Slots
+
+- `(default)` — Page elements; each child becomes one page
+
+## Events
+
+- `page-turn` -> `{ page: number, direction: 'forward' | 'backward' }`
+- `page-flip-start` -> `{ fromPage: number, toPage: number, direction: 'forward' | 'backward' }`
+- `page-flip-end` -> `{ page: number, direction: 'forward' | 'backward' }`
+
+## Methods
+
+- `goToPage(page: number): void` — Navigate to specific page (auto-aligns to spread in spread mode)
+- `nextPage(): void` — Advance by 1 (single) or 2 (spread) pages
+- `prevPage(): void` — Go back by 1 or 2 pages
+- `firstPage(): void` — Jump to page 0
+- `lastPage(): void` — Jump to last page
+
+## CSS Custom Properties
+
+```css
+--book-bg           /* Page background */
+--book-text          /* Text color */
+--book-text-secondary /* Secondary text */
+--book-border        /* Border color */
+--book-primary       /* Primary accent */
+--book-shadow        /* Book shadow */
+--book-page-bg       /* Individual page background */
+--book-page-line     /* Ruled line color */
+--book-spine-bg      /* Spine color */
+--book-cover-bg      /* Cover background */
+--book-flip-duration /* Flip animation duration, default 0.6s */
+```
+
+## CSS Parts
+
+- `spine` — The book spine element
+- `pages` — The pages container
+- `nav` — Navigation controls bar
+
+## Keyboard
+
+- ArrowRight/ArrowDown — Next page
+- ArrowLeft/ArrowUp — Previous page
+- Home — First page
+- End — Last page
+
+## Usage
+
+```html
+<snice-book title="My Book" author="Jane Doe" cover-image="/cover.jpg" mode="spread">
+  <div>Page 1 content</div>
+  <div>Page 2 content</div>
+  <div>Page 3 content</div>
+  <div>Page 4 content</div>
+</snice-book>
+```
+
+```js
+const book = document.querySelector('snice-book');
+book.goToPage(2);
+book.addEventListener('page-turn', e => console.log(e.detail.page));
+```

package/docs/ai/components/button.md

@@ -7,6 +7,7 @@ Interactive button with variants and states.
 ```typescript
 variant: 'default'|'primary'|'success'|'warning'|'danger'|'text' = 'default';
 size: 'small'|'medium'|'large' = 'medium';
+type: 'button'|'submit'|'reset' = 'button';
 disabled: boolean = false;
 loading: boolean = false;
 outline: boolean = false;
@@ -23,6 +24,10 @@ iconPlacement: 'start'|'end' = 'start';
 
 - `icon` - Custom icon content (overrides `icon` property)
 
+## Events
+
+- `button-click` → `{ originalEvent: MouseEvent }`
+
 ## Methods
 
 - `focus(options?)` - Focus button

package/docs/ai/components/camera-annotate.md

@@ -0,0 +1,82 @@
+# snice-camera-annotate
+
+Image annotation component combining camera capture + freehand drawing + labeled annotations.
+
+## Properties
+
+```typescript
+mode: 'camera' | 'annotate' = 'camera';
+autoRotateColors: boolean = true;    // attribute: auto-rotate-colors
+showLabelsPanel: boolean = true;     // attribute: show-labels-panel
+```
+
+## Methods
+
+```typescript
+capture(): Promise<void>;
+exportImage(options?: { includeLabels?: boolean }): string;
+exportAnnotations(): AnnotationData;
+importAnnotations(data: AnnotationData): void;
+clearAnnotations(): void;
+```
+
+## Events
+
+```typescript
+'@snice/capture'           → { dataURL: string; width: number; height: number }
+'@snice/annotate'          → { annotation: Annotation }
+'@snice/annotation-change' → { annotations: Annotation[] }
+```
+
+## Types
+
+```typescript
+interface Annotation {
+  id: string;
+  strokeId: string;
+  label: string;
+  color: string;
+  visible: boolean;
+  timestamp: number;
+}
+
+interface AnnotationData {
+  annotations: Annotation[];
+  strokes: AnnotationStroke[];
+  imageWidth: number;
+  imageHeight: number;
+}
+
+interface AnnotationStroke {
+  id: string;
+  color: string;
+  width: number;
+  points: { x: number; y: number }[];
+  timestamp: number;
+}
+```
+
+## Usage
+
+```html
+<!-- Default -->
+<snice-camera-annotate></snice-camera-annotate>
+
+<!-- No sidebar -->
+<snice-camera-annotate show-labels-panel="false"></snice-camera-annotate>
+
+<!-- Manual color selection -->
+<snice-camera-annotate auto-rotate-colors="false"></snice-camera-annotate>
+```
+
+## Features
+
+- Camera capture → freehand draw → label workflow
+- 12-color preset palette with auto-rotation
+- Sidebar labels linked to drawn shapes
+- Hover label highlights shape, dims others (opacity 0.2 + grayscale)
+- Show/hide individual and bulk annotations
+- Export image with/without rendered labels
+- Save/load annotation data (JSON)
+- Undo last stroke
+- Adjustable stroke width

package/docs/ai/components/candlestick.md

@@ -0,0 +1,79 @@
+# snice-candlestick
+
+SVG-based OHLC candlestick chart for financial data visualization.
+
+## Properties
+
+```typescript
+data: CandleData[] = [];              // {date, open, high, low, close, volume?}
+showVolume: boolean = false;           // Show volume bars below chart
+showGrid: boolean = true;             // Show horizontal grid lines
+showCrosshair: boolean = true;        // Show crosshair on hover
+bullishColor: string = '';            // Custom bullish (close >= open) color
+bearishColor: string = '';            // Custom bearish (close < open) color
+timeFormat: 'auto'|'date'|'time'|'datetime'|'month'|'year' = 'auto';
+yAxisFormat: 'number'|'currency'|'percent' = 'number';
+zoomEnabled: boolean = true;          // Enable scroll zoom and drag pan
+animation: boolean = true;            // Animate candle appearance
+```
+
+## Types
+
+```typescript
+interface CandleData {
+  date: string | number | Date;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+```
+
+## Methods
+
+```typescript
+resetZoom(): void;                     // Show all data
+zoomTo(startIndex: number, endIndex: number): void;  // Zoom to range
+```
+
+## Events
+
+```typescript
+'@snice/candle-click': { candle: CandleData; index: number }
+'@snice/candle-hover': { candle: CandleData; index: number }
+'@snice/crosshair-move': { price: number; date: string; x: number; y: number }
+```
+
+## Usage
+
+```html
+<snice-candlestick id="chart" show-volume></snice-candlestick>
+
+<script>
+  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 },
+  ];
+</script>
+```
+
+## Features
+
+- SVG candlestick bodies with wicks (high/low shadows)
+- Green bullish / red bearish coloring (customizable)
+- Optional volume bars below price chart
+- Horizontal grid lines
+- Y-axis price labels (number/currency/percent)
+- X-axis date labels with smart formatting
+- Crosshair with price/date readout
+- OHLC + volume tooltip on hover
+- Scroll to zoom, drag to pan
+- Responsive via ResizeObserver
+- Entrance animation with staggered delays
+- Accessible: role="img" with aria-label
+
+## CSS Custom Properties
+
+- `--snice-candlestick-bullish` — bullish candle color (default: green)
+- `--snice-candlestick-bearish` — bearish candle color (default: red)

package/docs/ai/components/chart.md

@@ -111,36 +111,12 @@ chart.datasets = [{
   backgroundColor: '#2196f3'
 }];
 
-// Radar chart
-chart.type = 'radar';
-chart.datasets = [
-  { label: 'Team A', data: [80, 90, 70, 85, 75], borderColor: '#2196f3' },
-  { label: 'Team B', data: [70, 85, 80, 75, 85], borderColor: '#4caf50' }
-];
-chart.labels = ['Speed', 'Strength', 'Agility', 'Defense', 'Skill'];
-
-// Mixed chart
-chart.type = 'mixed';
-chart.datasets = [
-  { label: 'Bar', type: 'bar', data: [10, 20, 30], backgroundColor: '#2196f3' },
-  { label: 'Line', type: 'line', data: [15, 25, 20], borderColor: '#4caf50' }
-];
-
 // Options
 chart.options = {
   legend: { position: 'bottom', clickable: true },
-  tooltip: {
-    trigger: 'hover',
-    format: (value, datasetIndex, pointIndex) => `Value: ${value}`
-  },
   animation: { enabled: true, duration: 1000 },
   yAxis: { min: 0, max: 100, ticks: 5, grid: true }
 };
-
-// Methods
-chart.addDataset({ label: 'New', data: [1, 2, 3] });
-chart.toggleDataset(0);
-const svg = chart.exportImage('svg');
 ```
 
 ```html

package/docs/ai/components/chat.md

@@ -47,49 +47,6 @@ Slack-style chat interface with messages, typing indicators, reactions, and file
 - `file` - File attachment
 - `system` - System notification
 
-## CSS Variables
-
-```css
---snice-chat-height
---snice-chat-border-radius
---snice-chat-text-color
---snice-chat-background
---snice-chat-border-color
---snice-chat-author-color
---snice-chat-timestamp-color
---snice-chat-system-color
---snice-chat-placeholder-color
---snice-chat-scrollbar-color
---snice-chat-scrollbar-hover-color
---snice-chat-avatar-background
---snice-chat-avatar-text-color
---snice-chat-attachment-border
---snice-chat-attachment-background
---snice-chat-attachment-icon-background
---snice-chat-attachment-icon-color
---snice-chat-reaction-background
---snice-chat-reaction-border
---snice-chat-reaction-hover-background
---snice-chat-reaction-active-background
---snice-chat-reaction-active-color
---snice-chat-reaction-active-border
---snice-chat-actions-background
---snice-chat-action-color
---snice-chat-action-hover-background
---snice-chat-typing-color
---snice-chat-typing-dot-color
---snice-chat-input-background
---snice-chat-input-container-background
---snice-chat-input-border
---snice-chat-input-focus-border
---snice-chat-button-color
---snice-chat-button-hover-background
---snice-chat-send-color
---snice-chat-send-background
---snice-chat-send-hover-background
---snice-chat-empty-color
-```
-
 ## Types
 
 ```typescript
@@ -123,67 +80,22 @@ interface MessageReaction {
 }
 ```
 
-## Example
+## Usage
 
 ```javascript
 const chat = document.querySelector('snice-chat');
 
 // Add message
 chat.addMessage({
-  type: 'text',
-  content: 'Hello!',
-  author: 'Alice',
-  avatar: 'https://example.com/alice.jpg',
-  timestamp: new Date(),
-  formats: [],
-});
-
-// Add image
-chat.addMessage({
-  type: 'image',
-  content: '',
-  author: 'Bob',
-  timestamp: new Date(),
-  formats: [],
-  attachment: {
-    type: 'image',
-    url: 'https://example.com/image.jpg',
-    name: 'photo.jpg',
-  },
+  type: 'text', content: 'Hello!', author: 'Alice', timestamp: new Date(), formats: [],
 });
 
-// Add reaction
-chat.addEventListener('message-react', (e) => {
-  const message = chat.messages.find((m) => m.id === e.detail.messageId);
-  const reactions = message.reactions || [];
-  reactions.push({ emoji: e.detail.emoji, count: 1, users: [chat.currentUser] });
-  chat.updateMessage(e.detail.messageId, { reactions });
+// Handle send
+chat.addEventListener('message-send', (e) => {
+  chat.addMessage({ type: 'text', content: e.detail.message, author: 'You', timestamp: new Date(), formats: [] });
 });
 
-// Typing indicator
+// Typing indicators
 chat.addTypingIndicator('Alice');
-setTimeout(() => chat.removeTypingIndicator('Alice'), 2000);
-
-// Send message
-chat.addEventListener('message-send', (e) => {
-  chat.addMessage({
-    type: 'text',
-    content: e.detail.message,
-    author: 'You',
-    timestamp: new Date(),
-    formats: [],
-  });
-});
+chat.removeTypingIndicator('Alice');
 ```
-
-## Features
-
-- Text, image, file, system messages
-- Edit, delete, react to messages
-- Typing indicators
-- User avatars with initials fallback
-- Timestamps
-- Auto-scroll to new messages
-- File upload support
-- Emoji reactions with counts
-- Message actions (edit, delete)