snice 4.8.0 → 4.10.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

@@ -0,0 +1,187 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/network-graph.md instead)
+
+# Network Graph
+`<snice-network-graph>`
+
+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" style="height: 400px;"></snice-network-graph>
+
+<script type="module">
+  document.getElementById('graph').data = {
+    nodes: [
+      { id: 'alice', label: 'Alice', group: 'team-a' },
+      { id: 'bob', label: 'Bob', group: 'team-b' },
+    ],
+    edges: [
+      { source: 'alice', target: 'bob', label: 'collaborates' },
+    ],
+  };
+</script>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/network-graph/snice-network-graph';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-network-graph.min.js"></script>
+```
+
+## Examples
+
+### Layout Types
+
+Use the `layout` attribute to switch between layout algorithms.
+
+```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" style="height: 400px;"></snice-network-graph>
+
+<script type="module">
+  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)' },
+      { 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 },
+    ],
+  };
+</script>
+```
+
+### Group-Based Coloring
+
+Nodes with the same `group` value are automatically assigned the same color.
+
+```typescript
+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
+
+Use `charge-strength` and `link-distance` to adjust node spacing.
+
+```html
+<snice-network-graph charge-strength="-500" link-distance="120"></snice-network-graph>
+<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.
+
+```typescript
+graph.data = {
+  nodes: [
+    { id: 'fixed', label: 'Pinned', x: 300, y: 200 },
+    { id: 'free', label: 'Free' },
+  ],
+  edges: [{ source: 'fixed', target: 'free' }],
+};
+```
+
+### Event Handling
+
+```typescript
+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);
+});
+```
+
+### Static Display
+
+Disable drag and zoom for a non-interactive view.
+
+```html
+<snice-network-graph zoom-enabled="false" drag-enabled="false"></snice-network-graph>
+```
+
+## 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;
+}
+```
+
+## Properties
+
+| 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 |
+
+## 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 |
+| `@snice/graph-zoom` | `{ scale: number, x: number, y: number }` | Zoom changed |