snice 4.8.0 → 4.9.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v4.7.0
+ * snice v4.8.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.8.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.8.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.8.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/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/funnel.md

@@ -0,0 +1,86 @@
+# snice-funnel
+
+SVG-based funnel chart for conversion tracking and pipeline visualization.
+
+## Properties
+
+```typescript
+data: FunnelStage[] = [];           // Array of { label, value, color? }
+variant: 'default'|'gradient' = 'default';
+orientation: 'vertical'|'horizontal' = 'vertical';
+showLabels: boolean = true;         // attribute: show-labels
+showValues: boolean = true;         // attribute: show-values
+showPercentages: boolean = true;    // attribute: show-percentages
+animation: boolean = false;
+```
+
+## Types
+
+```typescript
+interface FunnelStage {
+  label: string;
+  value: number;
+  color?: string;
+}
+```
+
+## Methods
+
+```typescript
+setStages(stages: FunnelStage[]): void;
+exportImage(format?: 'png' | 'svg'): string;  // returns data URL
+```
+
+## Events
+
+```typescript
+'funnel-click': CustomEvent<{ stage: FunnelStage; index: number }>
+'funnel-hover': CustomEvent<{ stage: FunnelStage; index: number }>
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-funnel id="f1"></snice-funnel>
+<script>
+  document.getElementById('f1').data = [
+    { label: 'Visitors', value: 10000 },
+    { label: 'Leads', value: 5000 },
+    { label: 'Customers', value: 500 },
+  ];
+</script>
+
+<!-- Gradient variant -->
+<snice-funnel variant="gradient"></snice-funnel>
+
+<!-- Horizontal -->
+<snice-funnel orientation="horizontal"></snice-funnel>
+
+<!-- Custom colors -->
+data = [
+  { label: 'A', value: 100, color: 'rgb(37 99 235)' },
+  { label: 'B', value: 50, color: 'rgb(22 163 74)' },
+]
+
+<!-- Hide elements -->
+<snice-funnel show-labels="false" show-values="false"></snice-funnel>
+
+<!-- With animation -->
+<snice-funnel animation></snice-funnel>
+```
+
+## Features
+
+- SVG trapezoid shapes per stage
+- Vertical (default) and horizontal orientation
+- 2 variants: default (distinct colors), gradient (opacity fade)
+- Custom color per stage, falls back to theme palette
+- Labels, values (auto-formatted K/M), percentages
+- Tooltip on hover
+- Click + hover events
+- Keyboard accessible (Enter/Space)
+- ARIA: role="img" on SVG, role="button" + aria-label on stages
+- CSS animation on initial render
+- Responsive via SVG viewBox
+- Works without theme (CSS fallbacks)

package/docs/ai/components/network-graph.md

@@ -0,0 +1,87 @@
+# snice-network-graph
+
+SVG-based force-directed network/relationship graph visualization.
+
+## Properties
+
+```typescript
+data: NetworkGraphData = { nodes: [], edges: [] };
+layout: 'force'|'circular'|'grid' = 'force';
+chargeStrength: number = -300;  // attribute: charge-strength
+linkDistance: number = 80;       // attribute: link-distance
+zoomEnabled: boolean = true;     // attribute: zoom-enabled
+dragEnabled: boolean = true;     // attribute: drag-enabled
+showLabels: boolean = true;      // attribute: show-labels
+animation: boolean = true;
+```
+
+## Types
+
+```typescript
+interface NetworkNode {
+  id: string;
+  label?: string;
+  group?: string;
+  size?: number;
+  color?: string;
+  x?: number;
+  y?: number;
+}
+
+interface NetworkEdge {
+  source: string;
+  target: string;
+  label?: string;
+  weight?: number;
+  color?: string;
+}
+
+interface NetworkGraphData {
+  nodes: NetworkNode[];
+  edges: NetworkEdge[];
+}
+```
+
+## Events
+
+```typescript
+'@snice/node-click': { node: NetworkNode }
+'@snice/edge-click': { edge: NetworkEdge }
+'@snice/node-drag': { node: NetworkNode; x: number; y: number }
+'@snice/graph-zoom': { scale: number; x: number; y: number }
+```
+
+## Usage
+
+```html
+<snice-network-graph id="graph" layout="force" show-labels></snice-network-graph>
+
+<script>
+  graph.data = {
+    nodes: [
+      { id: 'a', label: 'Node A', group: 'g1' },
+      { id: 'b', label: 'Node B', group: 'g2' },
+    ],
+    edges: [
+      { source: 'a', target: 'b', label: 'connects' },
+    ],
+  };
+</script>
+```
+
+## Features
+
+- Force-directed layout simulation (repulsion + attraction + centering)
+- Circular and grid static layouts
+- Zoom and pan (mouse wheel + drag on background)
+- Draggable nodes (pin on drag, double-click to unpin)
+- Curves for multi-edges between same node pairs
+- Node sizing by degree or custom `size`
+- Color coding by `group` with 10-color palette
+- Custom colors on individual nodes/edges
+- Edge weight as stroke width
+- Labels on nodes and edges
+- Hover highlighting (connected subgraph, dimmed unconnected)
+- Tooltips showing label and degree
+- Responsive sizing via ResizeObserver
+- Accessible: role="img" with aria-label

package/docs/ai/components/sankey.md

@@ -0,0 +1,63 @@
+# snice-sankey
+
+SVG-based Sankey diagram for flow visualization between categories.
+
+## Properties
+
+```typescript
+data: SankeyData = { nodes: [], links: [] };
+nodeWidth: number = 20;
+nodePadding: number = 10;
+alignment: 'left'|'right'|'center'|'justify' = 'justify';
+showLabels: boolean = true;
+showValues: boolean = true;
+animation: boolean = false;
+```
+
+## Types
+
+```typescript
+interface SankeyData {
+  nodes: SankeyNode[];
+  links: SankeyLink[];
+}
+interface SankeyNode { id: string; label?: string; color?: string; }
+interface SankeyLink { source: string; target: string; value: number; color?: string; }
+```
+
+## Events
+
+- `@snice/sankey-node-click` - `{ node: SankeyNode }` - Node clicked
+- `@snice/sankey-link-click` - `{ link: SankeyLink }` - Link clicked
+- `@snice/sankey-hover` - `{ type: 'node'|'link', item: SankeyNode|SankeyLink } | null` - Hover change
+
+## Usage
+
+```html
+<snice-sankey id="my-sankey" show-labels show-values animation></snice-sankey>
+
+<script>
+  document.getElementById('my-sankey').data = {
+    nodes: [
+      { id: 'a', label: 'Source', color: '#2196f3' },
+      { id: 'b', label: 'Target', color: '#4caf50' }
+    ],
+    links: [
+      { source: 'a', target: 'b', value: 100 }
+    ]
+  };
+</script>
+```
+
+## Features
+
+- SVG rendering with curved bezier link paths
+- Sankey layout algorithm with iterative node relaxation
+- Link width proportional to flow value
+- Hover highlighting (dims non-connected nodes/links)
+- Tooltips on hover for nodes and links
+- Responsive sizing via ResizeObserver
+- Animation on initial render
+- 4 alignment modes
+- Custom node/link colors
+- Accessible: role="img" with aria-label

package/docs/ai/components/time-range-picker.md

@@ -0,0 +1,78 @@
+# snice-time-range-picker
+
+Vertically stacked time slot picker with click-and-drag range selection.
+
+## Properties
+
+```typescript
+granularity: 5 | 15 | 30 | 60 = 15;       // Slot interval in minutes
+startTime: string = '00:00';               // Day start (attribute: start-time)
+endTime: string = '23:59';                 // Day end (attribute: end-time)
+value: string = '';                        // JSON array of TimeRange[]
+disabledRanges: string = '';               // JSON array of TimeRange[] (attribute: disabled-ranges)
+format: '12h' | '24h' = '24h';            // Time display format
+multiple: boolean = false;                 // Allow multiple non-contiguous ranges
+readonly: boolean = false;
+disabled: boolean = false;
+```
+
+## Types
+
+```typescript
+interface TimeRange { start: string; end: string; }
+```
+
+## Methods
+
+- `getSelectedRanges(): TimeRange[]` - Get current selections
+- `setSelectedRanges(ranges: TimeRange[]): void` - Set selections programmatically
+- `clearSelection(): void` - Clear all selections
+- `isSlotDisabled(time: string): boolean` - Check if time slot is disabled
+
+## Events
+
+- `@snice/time-range-change` - `{ranges: TimeRange[], component}`
+- `@snice/time-range-select` - `{start: string, component}` - Drag begins
+- `@snice/time-range-complete` - `{range: TimeRange, ranges: TimeRange[], component}` - Drag ends
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-time-range-picker start-time="08:00" end-time="18:00"></snice-time-range-picker>
+
+<!-- 12h format, 30min granularity -->
+<snice-time-range-picker granularity="30" format="12h"></snice-time-range-picker>
+
+<!-- With disabled ranges -->
+<snice-time-range-picker
+  disabled-ranges='[{"start":"12:00","end":"13:00"}]'>
+</snice-time-range-picker>
+
+<!-- Pre-selected value -->
+<snice-time-range-picker
+  value='[{"start":"09:00","end":"11:00"}]'>
+</snice-time-range-picker>
+
+<!-- Multiple selection -->
+<snice-time-range-picker multiple></snice-time-range-picker>
+
+<!-- Event handling -->
+<script>
+picker.addEventListener('@snice/time-range-change', (e) => {
+  console.log(e.detail.ranges);
+});
+</script>
+```
+
+## Features
+
+- Click and drag to select time ranges
+- Single click for individual slot
+- Keyboard navigation (Enter/Space to select, arrows to navigate, Escape to clear)
+- Configurable granularity (5/15/30/60 min)
+- 12h/24h time format
+- Disabled time slots
+- Multiple selection mode
+- Touch support
+- ARIA attributes for accessibility

package/docs/ai/components/treemap.md

@@ -0,0 +1,78 @@
+# snice-treemap
+
+SVG-based treemap visualization for hierarchical data as nested rectangles.
+
+## Properties
+
+```typescript
+data: TreemapNode = { label: '', value: 0 };
+showLabels: boolean = true;       // attribute: show-labels
+showValues: boolean = false;      // attribute: show-values
+colorScheme: TreemapColorScheme = 'default'; // attribute: color-scheme
+padding: number = 2;
+animation: boolean = true;
+drillPath: TreemapNode[];         // read-only, current drill path
+```
+
+## Types
+
+```typescript
+interface TreemapNode {
+  label: string;
+  value: number;
+  children?: TreemapNode[];
+  color?: string;
+}
+
+type TreemapColorScheme = 'default' | 'blue' | 'green' | 'purple' | 'orange' | 'warm' | 'cool' | 'rainbow';
+```
+
+## Methods
+
+```typescript
+drillDown(node: TreemapNode): void;  // drill into node's children
+drillUp(): void;                      // go back one level
+drillToRoot(): void;                  // reset to root
+```
+
+## Events
+
+```typescript
+'@snice/treemap-click': CustomEvent<{ node: TreemapNode; depth: number }>;
+'@snice/treemap-hover': CustomEvent<{ node: TreemapNode; depth: number } | null>;
+'@snice/treemap-drill': CustomEvent<{ node: TreemapNode; path: TreemapNode[] }>;
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-treemap show-labels show-values></snice-treemap>
+
+<!-- Color scheme -->
+<snice-treemap show-labels color-scheme="blue"></snice-treemap>
+
+<!-- Set data via JS -->
+<script>
+  treemap.data = {
+    label: 'Root',
+    value: 0,
+    children: [
+      { label: 'A', value: 50 },
+      { label: 'B', value: 30 },
+      { label: 'C', value: 20 },
+    ]
+  };
+</script>
+```
+
+## Features
+
+- Squarified treemap layout algorithm for optimal aspect ratios
+- 8 color schemes + custom per-node colors
+- Drill-down into child nodes with breadcrumb navigation
+- Tooltips on hover
+- Labels auto-hide when rectangles are too small
+- Responsive sizing via ResizeObserver
+- Animated transitions
+- Accessible: role="img" with aria-label