snice 4.9.0 → 4.11.0

package/docs/components/nav.md

@@ -1,239 +1,176 @@
-# Navigation Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/nav.md instead)
 
-The `<snice-nav>` component renders navigation menus from placard configurations. It integrates with Snice's routing system and supports multiple display variants.
+# Nav
+`<snice-nav>`
+
+A navigation menu that renders from placard configurations and integrates with Snice's routing system.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/nav/snice-nav';
+```
+
 ```html
-<snice-nav id="mainNav" variant="flat" orientation="horizontal"></snice-nav>
+<snice-nav id="nav" variant="flat" orientation="horizontal"></snice-nav>
 
 <script type="module">
-  import 'snice/components/nav/snice-nav';
-
-  const nav = document.querySelector('#mainNav');
-
-  const placards = [
+  const nav = document.getElementById('nav');
+  nav.update([
     { name: 'home', title: 'Home', icon: '🏠', order: 0 },
     { name: 'products', title: 'Products', icon: '📦', order: 1 },
-    { name: 'about', title: 'About', icon: 'ℹ️', order: 2 },
-  ];
-
-  nav.update(placards, undefined, 'home');
+    { name: 'about', title: 'About', order: 2 },
+  ], undefined, 'home');
 </script>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `variant` | `'flat' \| 'hierarchical' \| 'grouped'` | `'flat'` | Display style for navigation |
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
-| `isTopLevel` | `boolean` | `false` | Whether to receive context updates |
-
-## Methods
-
-### `update(placards, appContext?, currentRoute?, routeParams?): void`
-Update the navigation with new placard data and routing information.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-nav.update(
-  placards,           // Array of placard objects
-  appContext,         // Optional app context
-  'products',         // Current route
-  { id: '123' }       // Route parameters
-);
+import 'snice/components/nav/snice-nav';
 ```
 
-## Placard Structure
-
-```typescript
-interface Placard {
-  name: string;              // Unique identifier and route
-  title: string;             // Display text
-  icon?: string;             // Icon character/emoji
-  order?: number;            // Sort order
-  parent?: string;           // Parent placard name (for hierarchical)
-  group?: string;            // Group name (for grouped variant)
-  show?: boolean;            // Whether to show the item
-  description?: string;      // Accessible label and tooltip
-  tooltip?: string;          // Hover tooltip
-  hotkeys?: string[];        // Keyboard shortcuts
-  helpUrl?: string;          // Help documentation URL
-  searchTerms?: string[];    // Search keywords
-  attributes?: Record<string, any>; // Custom data attributes
-  visibleOn?: Function | Function[]; // Visibility guards
-}
-```
-
-## Variants
-
-### Flat (Default)
-Simple horizontal or vertical list of navigation items.
-
-```html
-<snice-nav variant="flat"></snice-nav>
-```
-
-### Hierarchical
-Nested navigation with parent-child relationships.
-
-```html
-<snice-nav variant="hierarchical"></snice-nav>
-```
-
-```javascript
-const placards = [
-  { name: 'products', title: 'Products', order: 0 },
-  { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
-  { name: 'clothing', title: 'Clothing', parent: 'products', order: 1 },
-];
-```
-
-### Grouped
-Navigation items organized into labeled groups.
-
+**CDN**
 ```html
-<snice-nav variant="grouped"></snice-nav>
-```
-
-```javascript
-const placards = [
-  { name: 'home', title: 'Home', group: 'Main', order: 0 },
-  { name: 'about', title: 'About', group: 'Main', order: 1 },
-  { name: 'settings', title: 'Settings', group: 'Account', order: 2 },
-];
+<script src="snice-runtime.min.js"></script>
+<script src="snice-nav.min.js"></script>
 ```
 
 ## Examples
 
-### Basic Navigation
+### Flat Navigation
+
+The default variant renders a simple list of navigation items.
 
 ```html
-<snice-nav id="nav"></snice-nav>
+<snice-nav id="flatNav" variant="flat"></snice-nav>
 
 <script type="module">
-  import 'snice/components/nav/snice-nav';
-
-  const nav = document.querySelector('#nav');
-
-  const placards = [
+  document.getElementById('flatNav').update([
     { name: 'home', title: 'Home', order: 0 },
     { name: 'products', title: 'Products', order: 1 },
     { name: 'services', title: 'Services', order: 2 },
     { name: 'contact', title: 'Contact', order: 3 },
-  ];
-
-  nav.update(placards, undefined, 'home');
+  ]);
 </script>
 ```
 
-### With Icons
-
-```javascript
-const placards = [
-  { name: 'dashboard', title: 'Dashboard', icon: '📊', order: 0 },
-  { name: 'analytics', title: 'Analytics', icon: '📈', order: 1 },
-  { name: 'reports', title: 'Reports', icon: '📋', order: 2 },
-  { name: 'settings', title: 'Settings', icon: '⚙️', order: 3 },
-];
-
-nav.update(placards);
-```
+### Hierarchical Navigation
 
-### Hierarchical Menu
+Use the `parent` property on placards to create nested navigation.
 
-```javascript
-const placards = [
-  { name: 'products', title: 'Products', order: 0 },
-  { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
-  { name: 'computers', title: 'Computers', parent: 'electronics', order: 0 },
-  { name: 'phones', title: 'Phones', parent: 'electronics', order: 1 },
-  { name: 'clothing', title: 'Clothing', parent: 'products', order: 1 },
-];
+```html
+<snice-nav id="hierNav" variant="hierarchical"></snice-nav>
 
-const nav = document.querySelector('snice-nav');
-nav.variant = 'hierarchical';
-nav.update(placards);
+<script type="module">
+  document.getElementById('hierNav').update([
+    { name: 'products', title: 'Products', order: 0 },
+    { name: 'electronics', title: 'Electronics', parent: 'products', order: 0 },
+    { name: 'clothing', title: 'Clothing', parent: 'products', order: 1 },
+  ]);
+</script>
 ```
 
 ### Grouped Navigation
 
-```javascript
-const placards = [
-  { name: 'home', title: 'Home', group: 'Main', order: 0 },
-  { name: 'dashboard', title: 'Dashboard', group: 'Main', order: 1 },
-  { name: 'profile', title: 'Profile', group: 'Account', order: 0 },
-  { name: 'settings', title: 'Settings', group: 'Account', order: 1 },
-  { name: 'help', title: 'Help', group: 'Support', order: 0 },
-];
-
-const nav = document.querySelector('snice-nav');
-nav.variant = 'grouped';
-nav.update(placards);
+Use the `group` property on placards to organize items into labeled groups.
+
+```html
+<snice-nav id="groupNav" variant="grouped"></snice-nav>
+
+<script type="module">
+  document.getElementById('groupNav').update([
+    { name: 'home', title: 'Home', group: 'Main', order: 0 },
+    { name: 'dashboard', title: 'Dashboard', group: 'Main', order: 1 },
+    { name: 'profile', title: 'Profile', group: 'Account', order: 0 },
+    { name: 'settings', title: 'Settings', group: 'Account', order: 1 },
+  ]);
+</script>
 ```
 
-### With Keyboard Shortcuts
+### Vertical Orientation
+
+Use `orientation="vertical"` for sidebar-style navigation.
 
-```javascript
-const placards = [
-  { name: 'home', title: 'Home', hotkeys: ['h', 'Ctrl+H'], order: 0 },
-  { name: 'search', title: 'Search', hotkeys: ['/', 'Ctrl+K'], order: 1 },
-];
+```html
+<snice-nav variant="flat" orientation="vertical"></snice-nav>
+```
 
-nav.update(placards);
+### With Icons
 
-// Access hotkeys via data attribute
-const links = nav.shadowRoot.querySelectorAll('[data-hotkeys]');
+```typescript
+nav.update([
+  { name: 'dashboard', title: 'Dashboard', icon: '📊', order: 0 },
+  { name: 'analytics', title: 'Analytics', icon: '📈', order: 1 },
+  { name: 'settings', title: 'Settings', icon: '⚙️', order: 2 },
+]);
 ```
 
 ### Conditional Visibility
 
-```javascript
-const placards = [
+Use `visibleOn` guards to conditionally show navigation items.
+
+```typescript
+nav.update([
   { name: 'home', title: 'Home', order: 0 },
   {
     name: 'admin',
     title: 'Admin',
     order: 1,
-    visibleOn: (appContext) => appContext.user?.isAdmin
+    visibleOn: (ctx) => ctx.user?.isAdmin
   },
-];
-
-nav.update(placards, { user: { isAdmin: true } });
+], { user: { isAdmin: true } });
 ```
 
 ### Active Route Tracking
 
-```javascript
-// Update current route
-nav.update(placards, undefined, 'products');
+Pass the current route to highlight the active item.
 
-// The corresponding nav item will have 'nav__link--active' class
-// and aria-current="page" attribute
+```typescript
+nav.update(placards, undefined, 'products');
+// The active item receives 'nav__link--active' class and aria-current="page"
 ```
 
-## Accessibility
+### Context Integration
 
-- `role="navigation"` on nav container
-- `aria-current="page"` on active links
-- `aria-label` from placard descriptions
-- Keyboard navigation support
-- Screen reader friendly
-
-## Integration with Snice Context
-
-When `isTopLevel` is true, the nav component automatically receives updates from the Snice context system:
+Set `is-top-level` to automatically receive placards and routes from the Snice context system.
 
 ```html
 <snice-nav is-top-level></snice-nav>
 ```
 
-The context provides:
-- Placards from routing configuration
-- Current route and parameters
-- Application context for visibility guards
+## Placard Structure
+
+```typescript
+interface Placard {
+  name: string;                      // Route identifier
+  title: string;                     // Display text
+  icon?: string;                     // Icon character/emoji
+  order?: number;                    // Sort order
+  parent?: string;                   // Parent name (hierarchical)
+  group?: string;                    // Group name (grouped)
+  show?: boolean;                    // Visibility flag
+  description?: string;              // Accessible label and tooltip
+  tooltip?: string;                  // Hover tooltip
+  hotkeys?: string[];                // Keyboard shortcuts
+  helpUrl?: string;                  // Help documentation URL
+  searchTerms?: string[];            // Search keywords
+  attributes?: Record<string, any>;  // Custom data attributes
+  visibleOn?: Function | Function[]; // Visibility guard functions
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'flat' \| 'hierarchical' \| 'grouped'` | `'flat'` | Navigation display style |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
+| `isTopLevel` (attr: `is-top-level`) | `boolean` | `false` | Receive context updates automatically |
 
-## Browser Support
+## Methods
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `update()` | `placards, appContext?, currentRoute?, routeParams?` | Update navigation with placard data |

package/docs/components/network-graph.md

@@ -1,108 +1,64 @@
-# Network Graph Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/network-graph.md instead)
 
-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.
+# Network Graph
+`<snice-network-graph>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Data Format](#data-format)
-- [Events](#events)
-- [Examples](#examples)
-- [Accessibility](#accessibility)
-- [Best Practices](#best-practices)
+An SVG-based force-directed graph visualization for displaying relationships between nodes.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/network-graph/snice-network-graph';
+```
+
 ```html
-<snice-network-graph id="graph"></snice-network-graph>
+<snice-network-graph id="graph" style="height: 400px;"></snice-network-graph>
 
 <script type="module">
-  import 'snice/components/network-graph/snice-network-graph';
-
-  const graph = document.getElementById('graph');
-  graph.data = {
+  document.getElementById('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 |
+## Importing
 
-## Events
+**ESM (bundler)**
+```typescript
+import 'snice/components/network-graph/snice-network-graph';
+```
 
-| 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 |
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-network-graph.min.js"></script>
+```
 
 ## 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>
+Use the `layout` attribute to switch between layout algorithms.
 
-<!-- Grid arrangement -->
-<snice-network-graph id="grid" layout="grid"></snice-network-graph>
+```html
+<snice-network-graph layout="force" style="height: 400px;"></snice-network-graph>
+<snice-network-graph layout="circular" style="height: 400px;"></snice-network-graph>
+<snice-network-graph layout="grid" style="height: 400px;"></snice-network-graph>
 ```
 
 ### Custom Node Sizes and Colors
 
 ```html
-<snice-network-graph id="custom-graph"></snice-network-graph>
+<snice-network-graph id="custom" style="height: 400px;"></snice-network-graph>
 
 <script type="module">
-  document.getElementById('custom-graph').data = {
+  document.getElementById('custom').data = {
     nodes: [
       { id: 'server', label: 'Server', size: 20, color: 'rgb(220 38 38)' },
       { id: 'db', label: 'Database', size: 16, color: 'rgb(37 99 235)' },
@@ -110,7 +66,7 @@ The network graph component renders an SVG-based force-directed graph visualizat
     ],
     edges: [
       { source: 'client', target: 'server', weight: 2 },
-      { source: 'server', target: 'db', label: 'queries', weight: 4, color: 'rgb(37 99 235)' },
+      { source: 'server', target: 'db', label: 'queries', weight: 4 },
     ],
   };
 </script>
@@ -118,9 +74,9 @@ The network graph component renders an SVG-based force-directed graph visualizat
 
 ### Group-Based Coloring
 
-Nodes with the same `group` value are automatically assigned the same color from a 10-color palette.
+Nodes with the same `group` value are automatically assigned the same color.
 
-```javascript
+```typescript
 graph.data = {
   nodes: [
     { id: 'a', group: 'frontend' },
@@ -136,19 +92,18 @@ graph.data = {
 
 ### Tuning the Force Simulation
 
+Use `charge-strength` and `link-distance` to adjust node spacing.
+
 ```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.
+Provide `x` and `y` on nodes to pin them at fixed positions.
 
-```javascript
+```typescript
 graph.data = {
   nodes: [
     { id: 'fixed', label: 'Pinned', x: 300, y: 200 },
@@ -158,9 +113,9 @@ graph.data = {
 };
 ```
 
-### Listening to Events
+### Event Handling
 
-```javascript
+```typescript
 graph.addEventListener('@snice/node-click', (e) => {
   console.log('Clicked:', e.detail.node.label);
 });
@@ -174,42 +129,59 @@ graph.addEventListener('@snice/graph-zoom', (e) => {
 });
 ```
 
-### Disabling Interaction
+### Static Display
+
+Disable drag and zoom for a non-interactive view.
 
 ```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
+## Data Types
+
+```typescript
+interface NetworkGraphData {
+  nodes: NetworkNode[];
+  edges: NetworkEdge[];
+}
+
+interface NetworkNode {
+  id: string;
+  label?: string;
+  group?: string;   // Auto color-coded
+  size?: number;     // Custom radius
+  color?: string;    // Custom fill color
+  x?: number;        // Fixed X position
+  y?: number;        // Fixed Y position
+}
+
+interface NetworkEdge {
+  source: string;
+  target: string;
+  label?: string;
+  weight?: number;   // Stroke width
+  color?: string;
+}
+```
 
-## Browser Support
+## Properties
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `NetworkGraphData` | `{ nodes: [], edges: [] }` | Graph data (set via JS) |
+| `layout` | `'force' \| 'circular' \| 'grid'` | `'force'` | Layout algorithm |
+| `chargeStrength` (attr: `charge-strength`) | `number` | `-300` | Node repulsion force |
+| `linkDistance` (attr: `link-distance`) | `number` | `80` | Target distance between connected nodes |
+| `zoomEnabled` (attr: `zoom-enabled`) | `boolean` | `true` | Enable zoom and pan |
+| `dragEnabled` (attr: `drag-enabled`) | `boolean` | `true` | Enable dragging nodes |
+| `showLabels` (attr: `show-labels`) | `boolean` | `true` | Show node and edge labels |
+| `animation` | `boolean` | `true` | Animate force simulation |
 
-## Best Practices
+## Events
 
-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
+| 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 |
+| `@snice/graph-zoom` | `{ scale: number, x: number, y: number }` | Zoom changed |