@ngx-km/graph 0.0.1 → 0.0.2

package/README.md

@@ -1,16 +1,16 @@
 # @ngx-km/graph
 
-Main graph visualization library combining all sub-libraries into a unified component.
+Angular 19+ library for creating interactive graph visualizations with custom node components.
 
 ## Features
 
-- Unified graph component integrating grid, layout, path-finding, and path-drawing
-- Custom Angular components as nodes
-- Type-safe node and relationship definitions
-- Automatic layout with ELK.js
-- Intelligent path routing between nodes
-- Custom path pill components
-- Reactive input handling with position preservation
+- Use any Angular component as a node
+- Automatic graph layout (hierarchical, force-directed, stress)
+- Obstacle-aware path routing between nodes
+- Infinite canvas with pan and zoom
+- Draggable nodes with position tracking
+- Custom labels on paths (pill components)
+- Fully type-safe API
 
 ## Installation
 
@@ -18,26 +18,342 @@ Main graph visualization library combining all sub-libraries into a unified comp
 npm install @ngx-km/graph
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { GraphComponent } from '@ngx-km/graph';
+import { Component } from '@angular/core';
+import { GraphComponent, GraphNode, GraphRelationship } from '@ngx-km/graph';
+import { MyNodeComponent } from './my-node.component';
 
 @Component({
+  selector: 'app-root',
+  standalone: true,
   imports: [GraphComponent],
   template: `
     <ngx-graph
       [nodes]="nodes"
       [relationships]="relationships"
-      [nodeComponent]="MyNodeComponent">
-    </ngx-graph>
-  `
+    />
+  `,
+  styles: [`
+    :host { display: block; width: 100%; height: 100vh; }
+  `]
 })
-export class MyComponent {}
+export class AppComponent {
+  nodes: GraphNode<MyNodeData>[] = [
+    { id: '1', component: MyNodeComponent, data: { label: 'Node 1' } },
+    { id: '2', component: MyNodeComponent, data: { label: 'Node 2' } },
+    { id: '3', component: MyNodeComponent, data: { label: 'Node 3' } },
+  ];
+
+  relationships: GraphRelationship[] = [
+    { id: 'e1', sourceId: '1', targetId: '2' },
+    { id: 'e2', sourceId: '2', targetId: '3' },
+  ];
+}
 ```
 
-## Running unit tests
+## Creating Node Components
 
-```bash
-nx test ngx-graph
+Node components receive data via the `GRAPH_NODE_DATA` injection token:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { GRAPH_NODE_DATA } from '@ngx-km/graph';
+
+interface MyNodeData {
+  label: string;
+  status?: 'active' | 'inactive';
+}
+
+@Component({
+  selector: 'app-my-node',
+  standalone: true,
+  template: `
+    <div class="node" [class.active]="data?.status === 'active'">
+      {{ data?.label }}
+    </div>
+  `,
+  styles: [`
+    .node {
+      padding: 16px 24px;
+      background: white;
+      border: 2px solid #e5e7eb;
+      border-radius: 8px;
+      font-weight: 500;
+    }
+    .node.active {
+      border-color: #10b981;
+      background: #ecfdf5;
+    }
+  `]
+})
+export class MyNodeComponent {
+  data = inject<MyNodeData>(GRAPH_NODE_DATA, { optional: true });
+}
 ```
+
+## API Reference
+
+### Inputs
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `nodes` | `GraphNode<T>[]` | Array of node definitions |
+| `relationships` | `GraphRelationship<T>[]` | Array of relationship definitions |
+| `config` | `GraphConfig` | Configuration object |
+
+### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `nodePositionChange` | `NodePositionChangeEvent` | Emitted when a node is dragged |
+| `viewportChange` | `ViewportState` | Emitted on pan/zoom |
+
+### Public Methods
+
+```typescript
+// Get a reference to the graph component
+@ViewChild(GraphComponent) graph!: GraphComponent;
+
+// Fit all content to viewport
+this.graph.fitToView(fitZoom?: boolean, padding?: number);
+
+// Center viewport on a specific node
+this.graph.centerOnNode(nodeId: string);
+
+// Scroll node into view with minimal pan
+this.graph.scrollToNode(nodeId: string, padding?: number);
+
+// Check if node is visible in viewport
+this.graph.isNodeVisible(nodeId: string, padding?: number): boolean;
+
+// Force recalculate layout
+this.graph.recalculateLayout();
+```
+
+## Interfaces
+
+### GraphNode
+
+```typescript
+interface GraphNode<T = unknown> {
+  id: string;                    // Unique identifier
+  component: Type<unknown>;      // Angular component to render
+  data?: T;                      // Data passed to component
+  x?: number;                    // Initial X position (optional)
+  y?: number;                    // Initial Y position (optional)
+}
+```
+
+### GraphRelationship
+
+```typescript
+interface GraphRelationship<T = unknown> {
+  id: string;                    // Unique identifier
+  sourceId: string;              // Source node ID
+  targetId: string;              // Target node ID
+  type?: 'one-way' | 'two-way';  // Arrow direction
+  data?: T;                      // Data passed to pill component
+  sourceAnchorSide?: 'top' | 'right' | 'bottom' | 'left';
+  targetAnchorSide?: 'top' | 'right' | 'bottom' | 'left';
+}
+```
+
+## Configuration
+
+### Full Configuration Example
+
+```typescript
+import { GraphConfig } from '@ngx-km/graph';
+
+const config: GraphConfig = {
+  // Grid settings
+  grid: {
+    backgroundMode: 'dots',      // 'dots' | 'lines' | 'none'
+    cellSize: 20,
+    panEnabled: true,
+    zoomEnabled: true,
+    dragEnabled: true,
+    minZoom: 0.1,
+    maxZoom: 3,
+  },
+
+  // Layout settings
+  layout: {
+    algorithm: 'layered',        // 'layered' | 'force' | 'stress'
+    direction: 'DOWN',           // 'DOWN' | 'UP' | 'LEFT' | 'RIGHT'
+    nodeSpacing: 50,
+    layerSpacing: 100,
+    autoLayout: true,
+    preservePositions: true,
+    fitPadding: 40,
+  },
+
+  // Path settings
+  paths: {
+    pathType: 'orthogonal',      // 'orthogonal' | 'bezier' | 'straight'
+    strokeColor: '#6366f1',
+    strokeWidth: 2,
+    strokePattern: 'solid',      // 'solid' | 'dashed' | 'dotted'
+    cornerRadius: 8,
+    arrowSize: 10,
+    obstaclePadding: 20,
+  },
+
+  // Optional: Component for path labels
+  pillComponent: MyPillComponent,
+};
+```
+
+### Layout Algorithms
+
+| Algorithm | Best For |
+|-----------|----------|
+| `layered` | Hierarchical structures, flowcharts, org charts |
+| `force` | Networks, social graphs, unstructured data |
+| `stress` | General purpose, good edge length consistency |
+
+### Path Types
+
+| Type | Description |
+|------|-------------|
+| `orthogonal` | Right-angle paths that avoid obstacles |
+| `bezier` | Smooth curved paths |
+| `straight` | Direct lines between nodes |
+
+## Pill Components
+
+Add labels or controls to paths using pill components:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { GRAPH_RELATIONSHIP_DATA } from '@ngx-km/graph';
+
+interface EdgeData {
+  label: string;
+}
+
+@Component({
+  selector: 'app-edge-pill',
+  standalone: true,
+  template: `
+    <div class="pill">{{ data?.label }}</div>
+  `,
+  styles: [`
+    .pill {
+      padding: 4px 12px;
+      background: #6366f1;
+      color: white;
+      border-radius: 12px;
+      font-size: 12px;
+    }
+  `]
+})
+export class EdgePillComponent {
+  data = inject<EdgeData>(GRAPH_RELATIONSHIP_DATA, { optional: true });
+}
+```
+
+Use it in config:
+
+```typescript
+const config: GraphConfig = {
+  pillComponent: EdgePillComponent,
+};
+```
+
+## Reactive Data Updates
+
+Both node and relationship data support Angular Signals for reactive updates:
+
+```typescript
+import { signal } from '@angular/core';
+
+// Data as signals - component updates automatically
+nodes: GraphNode[] = [
+  {
+    id: '1',
+    component: MyNodeComponent,
+    data: signal({ label: 'Node 1', count: 0 }),
+  },
+];
+
+// Update data reactively
+updateNode() {
+  const nodeData = this.nodes[0].data as WritableSignal<MyNodeData>;
+  nodeData.update(d => ({ ...d, count: d.count + 1 }));
+}
+```
+
+## Complete Example
+
+```typescript
+import { Component, signal } from '@angular/core';
+import {
+  GraphComponent,
+  GraphNode,
+  GraphRelationship,
+  GraphConfig,
+} from '@ngx-km/graph';
+import { MyNodeComponent } from './my-node.component';
+import { EdgePillComponent } from './edge-pill.component';
+
+@Component({
+  selector: 'app-workflow',
+  standalone: true,
+  imports: [GraphComponent],
+  template: `
+    <ngx-graph
+      #graph
+      [nodes]="nodes"
+      [relationships]="relationships"
+      [config]="config"
+      (nodePositionChange)="onNodeMoved($event)"
+    />
+    <button (click)="graph.fitToView(true)">Fit to View</button>
+  `,
+})
+export class WorkflowComponent {
+  nodes: GraphNode[] = [
+    { id: 'start', component: MyNodeComponent, data: { label: 'Start', type: 'start' } },
+    { id: 'process', component: MyNodeComponent, data: { label: 'Process', type: 'task' } },
+    { id: 'decision', component: MyNodeComponent, data: { label: 'Approve?', type: 'decision' } },
+    { id: 'end', component: MyNodeComponent, data: { label: 'End', type: 'end' } },
+  ];
+
+  relationships: GraphRelationship[] = [
+    { id: 'e1', sourceId: 'start', targetId: 'process' },
+    { id: 'e2', sourceId: 'process', targetId: 'decision' },
+    { id: 'e3', sourceId: 'decision', targetId: 'end', data: { label: 'Yes' } },
+  ];
+
+  config: GraphConfig = {
+    layout: {
+      algorithm: 'layered',
+      direction: 'DOWN',
+      nodeSpacing: 60,
+      layerSpacing: 120,
+    },
+    paths: {
+      pathType: 'orthogonal',
+      strokeColor: '#6366f1',
+      cornerRadius: 8,
+    },
+    pillComponent: EdgePillComponent,
+  };
+
+  onNodeMoved(event: NodePositionChangeEvent) {
+    console.log(`Node ${event.nodeId} moved to (${event.x}, ${event.y})`);
+  }
+}
+```
+
+## Requirements
+
+- Angular 19+
+- TypeScript 5.4+
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ngx-km/graph",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "dependencies": {
-    "@ngx-km/grid": "^0.0.1",
-    "@ngx-km/layout": "^0.0.1",
-    "@ngx-km/path-finding": "^0.0.1",
-    "@ngx-km/path-drawing": "^0.0.1",
+    "@ngx-km/grid": "^0.0.2",
+    "@ngx-km/layout": "^0.0.2",
+    "@ngx-km/path-finding": "^0.0.2",
+    "@ngx-km/path-drawing": "^0.0.2",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {