snice 4.8.0 → 4.9.0

package/docs/components/network-graph.md

@@ -0,0 +1,215 @@
+# Network Graph Component
+
+The network graph component renders an SVG-based force-directed graph visualization for displaying relationships between nodes. It supports multiple layout algorithms, interactive zoom/pan, draggable nodes, and hover highlighting.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Data Format](#data-format)
+- [Events](#events)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+```html
+<snice-network-graph id="graph"></snice-network-graph>
+
+<script type="module">
+  import 'snice/components/network-graph/snice-network-graph';
+
+  const graph = document.getElementById('graph');
+  graph.data = {
+    nodes: [
+      { id: 'alice', label: 'Alice', group: 'team-a' },
+      { id: 'bob', label: 'Bob', group: 'team-b' },
+      { id: 'carol', label: 'Carol', group: 'team-a' },
+    ],
+    edges: [
+      { source: 'alice', target: 'bob', label: 'collaborates' },
+      { source: 'bob', target: 'carol' },
+      { source: 'alice', target: 'carol' },
+    ],
+  };
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Attribute | Description |
+|----------|------|---------|-----------|-------------|
+| `data` | `NetworkGraphData` | `{ nodes: [], edges: [] }` | — | Graph data (set via JS property) |
+| `layout` | `'force' \| 'circular' \| 'grid'` | `'force'` | `layout` | Layout algorithm |
+| `chargeStrength` | `number` | `-300` | `charge-strength` | Repulsion force between nodes (negative = repel) |
+| `linkDistance` | `number` | `80` | `link-distance` | Target distance between connected nodes |
+| `zoomEnabled` | `boolean` | `true` | `zoom-enabled` | Enable mouse wheel zoom and background pan |
+| `dragEnabled` | `boolean` | `true` | `drag-enabled` | Enable dragging nodes |
+| `showLabels` | `boolean` | `true` | `show-labels` | Show text labels on nodes and edges |
+| `animation` | `boolean` | `true` | `animation` | Animate force simulation |
+
+## Data Format
+
+### NetworkNode
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Unique identifier |
+| `label` | `string` | No | Display label (falls back to `id`) |
+| `group` | `string` | No | Group for automatic color coding |
+| `size` | `number` | No | Custom circle radius (overrides degree-based sizing) |
+| `color` | `string` | No | Custom fill color (overrides group color) |
+| `x` | `number` | No | Fixed X position (pins node) |
+| `y` | `number` | No | Fixed Y position (pins node) |
+
+### NetworkEdge
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source` | `string` | Yes | Source node `id` |
+| `target` | `string` | Yes | Target node `id` |
+| `label` | `string` | No | Label displayed at edge midpoint |
+| `weight` | `number` | No | Stroke width (default 1) |
+| `color` | `string` | No | Custom stroke color |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/node-click` | `{ node: NetworkNode }` | Node clicked |
+| `@snice/edge-click` | `{ edge: NetworkEdge }` | Edge clicked |
+| `@snice/node-drag` | `{ node: NetworkNode, x: number, y: number }` | Node dragged to new position |
+| `@snice/graph-zoom` | `{ scale: number, x: number, y: number }` | Zoom level changed |
+
+## Examples
+
+### Layout Types
+
+```html
+<!-- Force-directed (default) -->
+<snice-network-graph id="force" layout="force"></snice-network-graph>
+
+<!-- Circular arrangement -->
+<snice-network-graph id="circular" layout="circular"></snice-network-graph>
+
+<!-- Grid arrangement -->
+<snice-network-graph id="grid" layout="grid"></snice-network-graph>
+```
+
+### Custom Node Sizes and Colors
+
+```html
+<snice-network-graph id="custom-graph"></snice-network-graph>
+
+<script type="module">
+  document.getElementById('custom-graph').data = {
+    nodes: [
+      { id: 'server', label: 'Server', size: 20, color: 'rgb(220 38 38)' },
+      { id: 'db', label: 'Database', size: 16, color: 'rgb(37 99 235)' },
+      { id: 'client', label: 'Client', size: 10, color: 'rgb(22 163 74)' },
+    ],
+    edges: [
+      { source: 'client', target: 'server', weight: 2 },
+      { source: 'server', target: 'db', label: 'queries', weight: 4, color: 'rgb(37 99 235)' },
+    ],
+  };
+</script>
+```
+
+### Group-Based Coloring
+
+Nodes with the same `group` value are automatically assigned the same color from a 10-color palette.
+
+```javascript
+graph.data = {
+  nodes: [
+    { id: 'a', group: 'frontend' },
+    { id: 'b', group: 'backend' },
+    { id: 'c', group: 'frontend' }, // same color as 'a'
+  ],
+  edges: [
+    { source: 'a', target: 'b' },
+    { source: 'b', target: 'c' },
+  ],
+};
+```
+
+### Tuning the Force Simulation
+
+```html
+<!-- Stronger repulsion, longer links -->
+<snice-network-graph charge-strength="-500" link-distance="120"></snice-network-graph>
+
+<!-- Weaker repulsion, tighter clustering -->
+<snice-network-graph charge-strength="-100" link-distance="50"></snice-network-graph>
+```
+
+### Pinned Nodes
+
+Provide `x` and `y` on nodes to pin them at fixed positions. Double-click a dragged node to unpin it.
+
+```javascript
+graph.data = {
+  nodes: [
+    { id: 'fixed', label: 'Pinned', x: 300, y: 200 },
+    { id: 'free', label: 'Free' },
+  ],
+  edges: [{ source: 'fixed', target: 'free' }],
+};
+```
+
+### Listening to Events
+
+```javascript
+graph.addEventListener('@snice/node-click', (e) => {
+  console.log('Clicked:', e.detail.node.label);
+});
+
+graph.addEventListener('@snice/node-drag', (e) => {
+  console.log(`Dragged ${e.detail.node.id} to (${e.detail.x}, ${e.detail.y})`);
+});
+
+graph.addEventListener('@snice/graph-zoom', (e) => {
+  console.log('Zoom:', e.detail.scale);
+});
+```
+
+### Disabling Interaction
+
+```html
+<!-- Static display, no drag or zoom -->
+<snice-network-graph zoom-enabled="false" drag-enabled="false"></snice-network-graph>
+```
+
+## Interaction
+
+- **Drag nodes**: Click and drag any node to reposition it. The node becomes pinned.
+- **Unpin nodes**: Double-click a pinned node to release it back to the simulation.
+- **Pan**: Click and drag on the background to pan the view.
+- **Zoom**: Use the mouse wheel to zoom in/out, centered on the cursor.
+- **Hover**: Hovering a node highlights its connected subgraph and dims unconnected nodes.
+- **Tooltips**: Hovering shows a tooltip with the node label and connection count.
+
+## Accessibility
+
+- Container has `role="img"` with `aria-label="Network graph visualization"`
+- Keyboard navigation is not currently supported (future enhancement)
+- Color is not the sole indicator of grouping when labels are shown
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Set a height**: The component needs a height set via CSS (e.g., `height: 500px`) since it uses `contain: layout style paint`
+2. **Use groups for automatic coloring**: The 10-color palette handles most use cases
+3. **Label important nodes**: Labels provide context beyond color
+4. **Tune simulation parameters**: Adjust `charge-strength` and `link-distance` for your data density
+5. **Use weight for edge importance**: Heavier edges appear thicker
+6. **Pin key nodes**: Use `x`/`y` to anchor important nodes
+7. **Disable animation for static layouts**: Set `animation="false"` for circular/grid layouts
+8. **Keep graph sizes reasonable**: Performance is best with under 200 nodes
+9. **Listen to events**: Use node-click and edge-click for interactive dashboards
+10. **Test in both themes**: Colors and borders adapt to light/dark mode

package/docs/components/sankey.md

@@ -0,0 +1,201 @@
+# Sankey Component
+
+The sankey component renders an SVG-based Sankey diagram for visualizing flow between categories. It shows nodes connected by curved links, where link width is proportional to flow value. Ideal for energy flows, budget breakdowns, user journeys, and conversion funnels.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [Types](#types)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+```html
+<snice-sankey id="my-sankey" show-labels show-values></snice-sankey>
+
+<script type="module">
+  import 'snice/components/sankey/snice-sankey';
+
+  document.getElementById('my-sankey').data = {
+    nodes: [
+      { id: 'source', label: 'Source', color: '#2196f3' },
+      { id: 'target', label: 'Target', color: '#4caf50' }
+    ],
+    links: [
+      { source: 'source', target: 'target', value: 100 }
+    ]
+  };
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `SankeyData` | `{ nodes: [], links: [] }` | Data containing nodes and links |
+| `nodeWidth` | `number` | `20` | Width of node rectangles in pixels |
+| `nodePadding` | `number` | `10` | Vertical padding between nodes in pixels |
+| `alignment` | `'left' \| 'right' \| 'center' \| 'justify'` | `'justify'` | How leaf nodes are aligned |
+| `showLabels` | `boolean` | `true` | Whether to show node labels |
+| `showValues` | `boolean` | `true` | Whether to show node values |
+| `animation` | `boolean` | `false` | Whether to animate on initial render |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/sankey-node-click` | `{ node: SankeyNode }` | Fired when a node is clicked |
+| `@snice/sankey-link-click` | `{ link: SankeyLink }` | Fired when a link is clicked |
+| `@snice/sankey-hover` | `{ type: 'node' \| 'link', item: SankeyNode \| SankeyLink } \| null` | Fired when hover state changes |
+
+## Types
+
+```typescript
+interface SankeyData {
+  nodes: SankeyNode[];
+  links: SankeyLink[];
+}
+
+interface SankeyNode {
+  id: string;        // Unique identifier
+  label?: string;    // Display label (defaults to id)
+  color?: string;    // Node color (auto-assigned if omitted)
+}
+
+interface SankeyLink {
+  source: string;    // Source node id
+  target: string;    // Target node id
+  value: number;     // Flow value (determines link width)
+  color?: string;    // Link color (defaults to source node color)
+}
+```
+
+## Examples
+
+### Energy Flow
+
+```html
+<snice-sankey id="energy" show-labels show-values animation style="height: 400px;"></snice-sankey>
+
+<script type="module">
+  document.getElementById('energy').data = {
+    nodes: [
+      { id: 'solar', label: 'Solar', color: '#f59e0b' },
+      { id: 'wind', label: 'Wind', color: '#3b82f6' },
+      { id: 'electric', label: 'Electricity', color: '#8b5cf6' },
+      { id: 'residential', label: 'Residential', color: '#10b981' },
+      { id: 'commercial', label: 'Commercial', color: '#06b6d4' }
+    ],
+    links: [
+      { source: 'solar', target: 'electric', value: 120 },
+      { source: 'wind', target: 'electric', value: 90 },
+      { source: 'electric', target: 'residential', value: 130 },
+      { source: 'electric', target: 'commercial', value: 80 }
+    ]
+  };
+</script>
+```
+
+### Budget Breakdown
+
+```html
+<snice-sankey id="budget" show-labels show-values style="height: 300px;"></snice-sankey>
+
+<script type="module">
+  document.getElementById('budget').data = {
+    nodes: [
+      { id: 'salary', label: 'Salary', color: '#10b981' },
+      { id: 'housing', label: 'Housing', color: '#ef4444' },
+      { id: 'food', label: 'Food', color: '#f59e0b' },
+      { id: 'savings', label: 'Savings', color: '#06b6d4' }
+    ],
+    links: [
+      { source: 'salary', target: 'housing', value: 1500 },
+      { source: 'salary', target: 'food', value: 600 },
+      { source: 'salary', target: 'savings', value: 900 }
+    ]
+  };
+</script>
+```
+
+### With Event Handling
+
+```html
+<snice-sankey id="clickable" show-labels style="height: 300px;"></snice-sankey>
+<div id="output"></div>
+
+<script type="module">
+  const sankey = document.getElementById('clickable');
+  const output = document.getElementById('output');
+
+  sankey.data = {
+    nodes: [
+      { id: 'a', label: 'Source A' },
+      { id: 'b', label: 'Source B' },
+      { id: 'c', label: 'Target C' }
+    ],
+    links: [
+      { source: 'a', target: 'c', value: 50 },
+      { source: 'b', target: 'c', value: 30 }
+    ]
+  };
+
+  sankey.addEventListener('@snice/sankey-node-click', (e) => {
+    output.textContent = `Clicked node: ${e.detail.node.label}`;
+  });
+
+  sankey.addEventListener('@snice/sankey-link-click', (e) => {
+    output.textContent = `Clicked link: ${e.detail.link.source} -> ${e.detail.link.target}`;
+  });
+</script>
+```
+
+### Custom Node Width and Padding
+
+```html
+<snice-sankey id="custom" node-width="30" node-padding="20" show-labels style="height: 300px;"></snice-sankey>
+```
+
+### Alignment Options
+
+```html
+<!-- Left-aligned (sources at left) -->
+<snice-sankey alignment="left" show-labels></snice-sankey>
+
+<!-- Right-aligned (sinks at right) -->
+<snice-sankey alignment="right" show-labels></snice-sankey>
+
+<!-- Center-aligned (isolated nodes centered) -->
+<snice-sankey alignment="center" show-labels></snice-sankey>
+
+<!-- Justified (default, sinks pushed to right) -->
+<snice-sankey alignment="justify" show-labels></snice-sankey>
+```
+
+## Accessibility
+
+- **ARIA role**: The diagram container has `role="img"` for screen reader support
+- **ARIA label**: `aria-label="Sankey diagram"` describes the visualization
+- **Keyboard navigation**: Nodes and links are interactive via click events
+- **Hover feedback**: Visual dimming of non-connected elements on hover
+- **Color independence**: Labels and values provide non-color context
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1, Shadow DOM, and SVG support
+- Uses ResizeObserver for responsive sizing
+
+## Best Practices
+
+1. **Set explicit height**: The component needs a defined height (via CSS or style attribute) since it uses `display: block`
+2. **Provide labels**: Always include `label` on nodes for clarity
+3. **Use meaningful colors**: Assign colors that distinguish categories; auto-colors work for quick prototyping
+4. **Keep data manageable**: Sankey diagrams work best with 5-20 nodes and clear flow direction
+5. **Enable animation**: Use `animation` for initial presentation or when data changes
+6. **Handle events**: Use click events for drill-down or detail views
+7. **Responsive layout**: The component automatically resizes via ResizeObserver
+8. **Test dark mode**: The component uses theme variables with fallbacks for both themes

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

@@ -0,0 +1,213 @@
+# Time Range Picker
+
+The `<snice-time-range-picker>` component provides a vertically stacked time slot picker for selecting time ranges within a single day. Users can click and drag to select contiguous time ranges, or click individual slots.
+
+## Basic Usage
+
+```html
+<snice-time-range-picker
+  start-time="08:00"
+  end-time="18:00">
+</snice-time-range-picker>
+```
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `granularity` | `granularity` | `5 \| 15 \| 30 \| 60` | `15` | Time interval in minutes for each slot |
+| `startTime` | `start-time` | `string` | `'00:00'` | Start time of the day in HH:MM format |
+| `endTime` | `end-time` | `string` | `'23:59'` | End time of the day in HH:MM format |
+| `value` | `value` | `string` | `''` | JSON string of selected time ranges |
+| `disabledRanges` | `disabled-ranges` | `string` | `''` | JSON string of disabled time ranges |
+| `format` | `format` | `'12h' \| '24h'` | `'24h'` | Time display format |
+| `multiple` | `multiple` | `boolean` | `false` | Allow multiple non-contiguous range selections |
+| `readonly` | `readonly` | `boolean` | `false` | Prevent interaction but show selections |
+| `disabled` | `disabled` | `boolean` | `false` | Disable all interaction |
+
+## Time Range Format
+
+Both `value` and `disabled-ranges` use JSON arrays of time range objects:
+
+```typescript
+interface TimeRange {
+  start: string;  // "HH:MM" format
+  end: string;    // "HH:MM" format
+}
+```
+
+Example:
+```json
+[{"start": "09:00", "end": "11:00"}, {"start": "14:00", "end": "16:00"}]
+```
+
+## Events
+
+### `@snice/time-range-change`
+
+Fired when the selection changes.
+
+```javascript
+picker.addEventListener('@snice/time-range-change', (e) => {
+  console.log('Selected ranges:', e.detail.ranges);
+  // [{start: "09:00", end: "10:30"}, ...]
+});
+```
+
+**Detail:**
+- `ranges` - Array of selected `TimeRange` objects
+- `component` - Reference to the picker element
+
+### `@snice/time-range-select`
+
+Fired when a drag selection begins.
+
+```javascript
+picker.addEventListener('@snice/time-range-select', (e) => {
+  console.log('Drag started at:', e.detail.start);
+});
+```
+
+**Detail:**
+- `start` - The time where dragging started
+- `component` - Reference to the picker element
+
+### `@snice/time-range-complete`
+
+Fired when a drag selection completes.
+
+```javascript
+picker.addEventListener('@snice/time-range-complete', (e) => {
+  console.log('Completed range:', e.detail.range);
+  console.log('All ranges:', e.detail.ranges);
+});
+```
+
+**Detail:**
+- `range` - The just-completed `TimeRange`
+- `ranges` - All currently selected ranges
+- `component` - Reference to the picker element
+
+## Methods
+
+### `getSelectedRanges(): TimeRange[]`
+
+Returns an array of currently selected time ranges.
+
+```javascript
+const ranges = picker.getSelectedRanges();
+// [{start: "09:00", end: "10:30"}]
+```
+
+### `setSelectedRanges(ranges: TimeRange[]): void`
+
+Programmatically sets the selected time ranges.
+
+```javascript
+picker.setSelectedRanges([
+  { start: '09:00', end: '11:00' },
+  { start: '14:00', end: '16:00' }
+]);
+```
+
+### `clearSelection(): void`
+
+Clears all selected time ranges.
+
+```javascript
+picker.clearSelection();
+```
+
+### `isSlotDisabled(time: string): boolean`
+
+Checks if a specific time slot is disabled.
+
+```javascript
+picker.isSlotDisabled('12:00'); // true if in disabled ranges
+```
+
+## Examples
+
+### Appointment Booking
+
+```html
+<snice-time-range-picker
+  granularity="30"
+  format="12h"
+  start-time="08:00"
+  end-time="18:00"
+  disabled-ranges='[{"start":"12:00","end":"13:00"}]'>
+</snice-time-range-picker>
+```
+
+### Working Hours Configuration
+
+```html
+<snice-time-range-picker
+  multiple
+  granularity="60"
+  start-time="06:00"
+  end-time="22:00">
+</snice-time-range-picker>
+```
+
+### Fine-Grained Scheduling
+
+```html
+<snice-time-range-picker
+  granularity="5"
+  start-time="09:00"
+  end-time="10:00">
+</snice-time-range-picker>
+```
+
+### Pre-selected Schedule
+
+```html
+<snice-time-range-picker
+  granularity="30"
+  format="12h"
+  start-time="08:00"
+  end-time="18:00"
+  value='[{"start":"09:00","end":"11:30"},{"start":"14:00","end":"16:30"}]'
+  multiple>
+</snice-time-range-picker>
+```
+
+## Interaction
+
+### Mouse
+- **Click** a slot to select it individually
+- **Click and drag** across slots to select a contiguous range
+- In multiple mode, existing selections are preserved when adding new ranges
+
+### Touch
+- **Tap** a slot to select it
+- **Touch and drag** to select a range
+
+### Keyboard
+- **Enter / Space** - Toggle selection of focused slot
+- **Arrow Up / Down** - Navigate between slots
+- **Escape** - Clear all selections
+
+## Accessibility
+
+- Each slot has `role="option"` with appropriate `aria-selected` and `aria-disabled` attributes
+- Keyboard-navigable with visible focus indicators
+- Disabled slots have `tabindex="-1"` and are skipped during keyboard navigation
+
+## Styling
+
+The component uses CSS custom properties from the Snice theme system:
+
+| Variable | Usage |
+|----------|-------|
+| `--snice-color-primary` | Selected slot background |
+| `--snice-color-text-inverse` | Selected slot text |
+| `--snice-color-border` | Slot borders |
+| `--snice-color-background` | Component background |
+| `--snice-color-background-element` | Disabled slot background / hover |
+| `--snice-color-text-tertiary` | Disabled slot text |
+| `--snice-font-family` | Font family |
+
+All values include fallbacks for use without the theme loaded.