ngraph.svg 0.0.17 → 0.10.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Andrei Kashcha
+Copyright (c) 2014-2025 Andrei Kashcha
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,15 +1,369 @@
 # ngraph.svg
 
-Svg based graph rendering
+SVG-based graph visualization library with adaptive rendering. Designed for rendering large graphs with zoom-dependent detail levels, collision-based importance, and viewport culling.
 
-# install
+## Features
 
-With [npm](https://npmjs.org) do:
+- **Adaptive rendering** — nodes show different detail levels based on zoom (dots → labels → cards)
+- **Collision-based importance** — more important nodes get richer detail at lower zoom levels
+- **Property functions** — style any property with a literal, `d => val`, or `(d, ctx) => val`
+- **Performance** — element pooling, viewport culling via R-tree, batched DOM updates
+- **Force-directed layout** — integrated with ngraph.forcelayout, with layered orchestration and stress refinement
+- **Interactive controls** — pan, zoom, kinetic scrolling on mouse and touch
+- **Directed edges** — arrow markers with automatic endpoint calculation on node boundaries
 
-```
+## Installation
+
+```bash
 npm install ngraph.svg
 ```
 
-# license
+## Quick Start
+
+```js
+import createGraph from 'ngraph.graph';
+import {
+  createScene, NodeCollection, EdgeCollection, ForceLayoutAdapter
+} from 'ngraph.svg';
+
+// 1. Create a graph
+const graph = createGraph();
+graph.addNode('a', { label: 'Node A' });
+graph.addNode('b', { label: 'Node B' });
+graph.addLink('a', 'b');
+
+// 2. Create the scene
+const scene = createScene(document.getElementById('container'), {
+  panZoom: { minZoom: 0.1, maxZoom: 50 }
+});
+
+// 3. Create collections (graph binding auto-syncs nodes/edges)
+const nodeCol = new NodeCollection({
+  graph,
+  data: (graphNode) => ({
+    label: graphNode.data?.label || graphNode.id,
+  }),
+  maxScale: 2,
+  levels: [
+    { type: 'circle', radius: 2, fill: '#4a90d9' },
+    { minZoom: 2,
+      layers: [
+        { type: 'circle', radius: 4, fill: '#4a90d9' },
+        { type: 'text', text: d => d.label, fontSize: 10, fill: '#fff',
+          anchor: 'top', offset: [0, -8] },
+      ] },
+  ],
+});
+
+const edgeCol = new EdgeCollection({
+  graph,
+  nodeCollection: nodeCol,
+  directed: true,
+  color: '#666',
+  width: 1,
+  opacity: 0.5,
+});
+
+scene.addCollection(edgeCol);
+scene.addCollection(nodeCol);
+
+// 4. Layout
+const layout = new ForceLayoutAdapter(graph, { springLength: 50 });
+layout.onUpdate((positions) => {
+  nodeCol.syncPositions(positions);
+  edgeCol.syncPositions(positions);
+  scene.requestRender();
+});
+layout.start();
+```
+
+## API Reference
+
+### createScene(container, options)
+
+Creates an SVG scene for graph visualization.
+
+**Parameters:**
+- `container` — DOM element to attach the scene to
+- `options.viewBox` — initial bounds `{ left, top, right, bottom }` (default: -100 to 100)
+- `options.panZoom` — pan/zoom config `{ minZoom, maxZoom, enabled }` (default: 0.1–20)
+
+**Returns:** Scene object with properties and methods:
+- `svg` — the SVG root element
+- `root` — the transform group containing all scene content
+- `drawContext` — current DrawContext
+- `addCollection(collection)` / `removeCollection(collection)` — manage collections
+- `on(event, callback)` / `off(event, callback)` — events: `render`, `transform`, `resize`
+- `requestRender()` — request render on next animation frame
+- `getPanZoom()` — get the pan/zoom controller
+- `flyTo(x, y, scale, duration)` — animated camera movement (returns Promise)
+- `fitToView(bounds, padding)` — fit content to viewport
+- `dispose()` — clean up resources
+
+### NodeCollection
+
+Manages batched node rendering with a MapLibre-inspired styling API.
+
+```js
+const nodes = new NodeCollection({
+  graph,                            // ngraph instance (auto-binds nodes)
+  data: (graphNode) => ({...}),     // extract data from graph node
+  maxScale: 2,                      // counter-scaling cap
+
+  levels: [
+    // Level 0: always visible, no importance gating
+    { type: 'circle', radius: 2, fill: '#CFCCDF' },
+
+    // Level 1: importance-gated, any zoom
+    { importance: d => d.importance,
+      layers: [
+        { type: 'circle', radius: 3, fill: '#CFCCDF' },
+        { type: 'text', text: d => d.name, fontSize: 10, fill: '#CFCCDF',
+          anchor: 'top', offset: [0, -8] },
+      ] },
+
+    // Level 2: importance-gated, zoom >= 3.5
+    { minZoom: 3.5, importance: d => d.importance,
+      layers: [
+        { type: 'circle', radius: 4, fill: '#CFCCDF' },
+        { type: 'text', text: d => d.name, fontSize: 11, fill: '#CFCCDF',
+          anchor: 'top', offset: [0, -10] },
+        { type: 'text', text: d => d.version, fontSize: 9, fill: '#888',
+          anchor: 'bottom', offset: [0, 16], visible: d => !!d.version },
+      ] },
+  ],
+});
+```
+
+**Methods:**
+- `add({ id, x, y, data })` — add a node, returns node handle
+- `remove(nodeOrId)` — remove a node
+- `get(id)` — get node by ID
+- `setPosition(node, x, y)` — update position
+- `syncPositions(positions)` — sync positions from a `Map<id, {x, y}>`
+- `getNodeAt(screenX, screenY, drawContext)` — hit testing (returns node ID or null)
+- `getNodeShape(nodeId)` — get current shape in world coordinates (for arrow intersection)
+- `setState(nodeOrId, key, value)` — set state (affects `ctx` in property functions + CSS class)
+- `getState(nodeOrId, key)` — get state value
+- `clearState(key)` — remove a state key from all nodes
+- `beginBatch()` / `endBatch()` — batch DOM updates
+- `forEach(callback)` — iterate nodes
+- `count` — number of nodes (getter)
+- `clear()` — remove all nodes
+- `dispose()` — clean up resources
+
+### EdgeCollection
+
+Manages batched edge/line rendering.
+
+```js
+const edges = new EdgeCollection({
+  graph,                            // ngraph instance (auto-binds edges)
+  nodeCollection: nodeCol,          // for directed arrow endpoint calculation
+  directed: true,                   // add arrowhead markers
+  color: '#666',                    // literal, d => val, or (d, ctx) => val
+  width: 1,
+  opacity: 0.5,
+  arrowLength: 10,                  // screen pixels
+  arrowWidth: 5,                    // screen pixels
+});
+```
+
+**Methods:**
+- `add({ id, fromX, fromY, toX, toY, data })` — add an edge, returns edge handle
+- `remove(edgeOrId)` — remove an edge
+- `get(id)` — get edge by ID
+- `setEndpoints(edge, fromX, fromY, toX, toY)` — update geometry
+- `syncPositions(positions)` — sync endpoints from a `Map<id, {x, y}>` (handles directed arrow offsets)
+- `setState(edgeOrId, key, value)` — set state
+- `getState(edgeOrId, key)` — get state
+- `clearState(key)` — clear state from all edges
+- `beginBatch()` / `endBatch()` — batch DOM updates
+- `forEach(callback)` — iterate edges
+- `count` — number of edges (getter)
+- `clear()` — remove all edges
+- `dispose()` — clean up resources
+
+### Property Functions
+
+Every visual property (fill, radius, fontSize, opacity, etc.) can be:
+
+```js
+fill: '#CFCCDF'                                     // literal
+fill: d => d.color                                   // data-driven
+fill: (d, ctx) => ctx.highlighted ? '#fff' : d.color // data + state
+```
+
+The `ctx` object contains:
+- `zoom` — current zoom level
+- Any state keys set via `setState()` (e.g. `ctx.highlighted`, `ctx.dimmed`)
+
+### Levels
+
+Levels define zoom-dependent rendering with collision-based importance. They are ordered by `minZoom` (lowest first). At any given zoom, the highest applicable level is the candidate.
+
+**Key properties:**
+- `minZoom` — minimum zoom to show this level (default: 0)
+- `maxZoom` — maximum zoom (optional)
+- `importance` — function `d => 0..1` for collision gating. Omit for always-visible levels.
+- `layers` — array of layer definitions
+- `hitArea` — custom hit area for `render`-type layers: `{ type: 'rect', width, height }`
+
+**How collision works:** Nodes with `importance` compete for screen space. More important nodes always win. If a node collides at level N, it falls back to level N-1, and so on down to level 0 (which has no importance gating and always renders).
+
+**Shorthand** — a level with a single shape can omit the `layers` wrapper:
+
+```js
+// These are equivalent:
+{ type: 'circle', radius: 2, fill: '#CCC' }
+{ layers: [{ type: 'circle', radius: 2, fill: '#CCC' }] }
+```
+
+**Level transitions** — when a node changes level, it cross-fades over ~150ms.
+
+### Layer Types
+
+| Type | Purpose | Key Properties |
+|---|---|---|
+| `circle` | Filled circle | `radius`, `fill`, `stroke`, `strokeWidth`, `opacity`, `filter` |
+| `rect` | Rectangle | `width`, `height`, `rx`, `ry`, `fill`, `stroke`, `strokeWidth`, `opacity`, `filter` |
+| `text` | Text label | `text`, `fontSize`, `fill`, `fontFamily`, `fontWeight`, `anchor`, `offset`, `maxWidth`, `opacity` |
+| `render` | Custom SVG | `render: (data, ctx) => svgString` |
+
+All layer types support `visible: d => boolean` for conditional rendering.
+
+**Text anchoring:**
+```js
+{ type: 'text', text: d => d.name, fontSize: 10,
+  anchor: 'top',       // 'top' | 'bottom' | 'left' | 'right' | 'center'
+  offset: [0, -6] }    // [dx, dy] in counter-scaled pixels
+```
+
+**Text word-wrap:**
+```js
+{ type: 'text', text: d => d.description, fontSize: 8,
+  maxWidth: 120 }      // wraps into multiple lines using <tspan> elements
+```
+
+### ForceLayoutAdapter
+
+Wraps ngraph.forcelayout with animation loop, position smoothing, layered orchestration, and stress refinement.
+
+```js
+const layout = new ForceLayoutAdapter(graph, {
+  springLength: 30,
+  springCoefficient: 0.0008,
+  gravity: -2.0,
+  dragCoefficient: 0.04,
+  theta: 0.8,
+  timeStep: 20,
+  smoothing: 0.15,              // position interpolation (0 = very smooth, 1 = raw)
+  maxSpeed: 50,                 // max displacement per frame
+  energyThreshold: 0.003,       // convergence threshold
+  stableFramesRequired: 10,     // frames below threshold to confirm stability
+  layeredLayout: true,          // enable orchestrated layout (default)
+  stressThreshold: 0.3,         // edge stretch threshold for refinement
+  maxStressIterations: 200,
+  getNodeSize: (nodeId) => 10,  // for size-aware spacing
+  nodePadding: 4,               // padding between nodes
+  onStabilized: () => {},       // called when layout converges
+});
+```
+
+**Methods:**
+- `start()` / `stop()` — control animation loop
+- `step()` — single layout iteration (async)
+- `stabilize(maxIterations)` — run until stable (async)
+- `getNodePosition(nodeId)` — get position (async)
+- `setNodePosition(nodeId, x, y)` — set position (async)
+- `pinNode(nodeId)` / `unpinNode(nodeId)` — lock/unlock position (async)
+- `getPositions()` — get all positions as `Map<id, {x, y}>`
+- `getBounds()` — get bounding box (async)
+- `isStabilized()` / `isRunning()` — query state
+- `onUpdate(callback)` — listen for position updates (called each frame with positions Map)
+- `dispose()` — clean up
+
+**Layered orchestration** (enabled by default):
+1. Computes onion layers via iterative leaf peeling
+2. Pins all nodes, unpins only the structural core
+3. After core converges, progressively unpins outer layers
+4. Detects and refines stretched edges (stress passes)
+
+The layout automatically restarts when nodes/edges are added to the graph.
+
+### State System
+
+Both NodeCollection and EdgeCollection share the same state API. State keys appear as:
+1. Properties on the `ctx` object passed to property functions
+2. CSS classes on the SVG element (for external styling)
+
+```js
+// Set state
+nodeCol.setState('node-1', 'highlighted', true);
+edgeCol.setState('edge-1', 'dimmed', true);
+
+// Use state in property functions
+fill: (d, ctx) => ctx.highlighted ? '#fff' : '#ccc'
+opacity: (d, ctx) => ctx.dimmed ? 0.2 : 1
+
+// Clear state from all nodes/edges
+nodeCol.clearState('highlighted');
+```
+
+### Graph Binding
+
+When a `graph` option is passed to NodeCollection or EdgeCollection, the collection automatically syncs with the graph — adding/removing visual elements as nodes/edges are added/removed.
+
+NodeCollection also requires a `data` callback when using graph binding:
+
+```js
+const nodeCol = new NodeCollection({
+  graph,
+  data: (graphNode) => ({
+    name: graphNode.data?.name || graphNode.id,
+    color: graphNode.data?.color || '#4a90d9',
+  }),
+  levels: [...],
+});
+```
+
+EdgeCollection stores `fromId` and `toId` from the graph link in each edge's data automatically.
+
+### Other Exports
+
+**DrawContext** — transform/viewport state passed to all renderers:
+- `screenToScene(screenX, screenY)` / `sceneToScreen(sceneX, sceneY)` — coordinate conversion
+- `isVisible(x, y, radius)` — check viewport visibility
+- `getVisibleBounds()` — visible area in scene coordinates
+- `getNodeScreenSize(worldSize)` — world-to-screen size conversion
+
+**removeOverlaps(rects, originalPositions, options)** — R-tree based overlap removal for post-layout node positioning. Two-phase: separation, then relaxation toward original positions.
+
+**separatePair(a, b, padding)** — separate two overlapping rectangles.
+
+**intersectCircle / intersectRect / intersectShape** — shape boundary intersection for directed edge arrow placement.
+
+**computeLayers(graph)** — iterative leaf peeling (onion decomposition). Returns `{ layerMap, maxLayer }`.
+
+**computeStressedNodes(graph, layout, threshold)** — find edges deviating from ideal length. Returns `Set<nodeId>`.
+
+## Demos
+
+Run the development server:
+
+```bash
+npm run dev
+```
+
+- `demo/index.html` — random graph with adaptive detail levels
+- `demo/chinese-vocab.html` — Chinese vocabulary hierarchy visualization
+
+## Dependencies
+
+- [ngraph.graph](https://github.com/anvaka/ngraph.graph) — graph data structure
+- [ngraph.forcelayout](https://github.com/anvaka/ngraph.forcelayout) — force-directed layout
+- [rbush](https://github.com/mourner/rbush) — R-tree spatial index
+
+## License
 
 MIT

package/package.json

@@ -1,33 +1,40 @@
 {
   "name": "ngraph.svg",
-  "version": "0.0.17",
-  "description": "Svg based graph rendering",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "demo": "browserify example/basic/index.js > example/basic/bundle.js && browserify example/customNode/index.js > example/customNode/bundle.js && browserify example/customSpringLength/index.js > example/customSpringLength/bundle.js"
+  "version": "0.10.0",
+  "description": "SVG-based graph visualization library with adaptive rendering",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
   },
-  "keywords": [
-    "svg",
-    "graph",
-    "vivagraph",
-    "ngraph"
+  "files": [
+    "dist",
+    "src"
   ],
-  "author": "Andrei Kashcha",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/anvaka/ngraph.svg"
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
   },
   "dependencies": {
-    "hammerjs": "^2.0.2",
-    "ngraph.events": "1.2.1",
-    "ngraph.forcelayout": "3.3.0",
-    "simplesvg": "0.1.0",
-    "ngraph.merge": "0.0.1",
-    "wheel": "0.0.1"
+    "ngraph.forcelayout": "^3.3.1",
+    "ngraph.graph": "^20.1.1",
+    "rbush": "^3.0.1"
   },
   "devDependencies": {
-    "ngraph.graph": "20.0.0"
-  }
+    "vite": "^6.0.11"
+  },
+  "keywords": [
+    "graph",
+    "visualization",
+    "svg",
+    "ngraph",
+    "adaptive"
+  ],
+  "author": "",
+  "license": "MIT"
 }

package/src/DrawContext.js

@@ -0,0 +1,123 @@
+/**
+ * DrawContext holds transform/viewport state passed to all renderers.
+ * It provides helpers for adaptive rendering calculations.
+ */
+export default class DrawContext {
+  constructor() {
+    this.viewBox = { left: -100, top: -100, right: 100, bottom: 100 };
+    this.transform = { scale: 1, x: 0, y: 0 };
+    this.width = 0;
+    this.height = 0;
+    this.pixelRatio = typeof window !== 'undefined' ? window.devicePixelRatio : 1;
+
+    // Cached visible bounds to avoid per-node allocations
+    this._visibleBounds = { left: 0, top: 0, right: 0, bottom: 0 };
+    this._visibleBoundsDirty = true;
+
+    // Preallocated points to avoid per-call allocations
+    this._reusableScenePoint = { x: 0, y: 0 };
+    this._reusableScreenPoint = { x: 0, y: 0 };
+  }
+
+  /**
+   * Update the viewport dimensions
+   */
+  setSize(width, height) {
+    this.width = width;
+    this.height = height;
+    this._visibleBoundsDirty = true;
+  }
+
+  /**
+   * Update the viewBox bounds
+   */
+  setViewBox(left, top, right, bottom) {
+    this.viewBox.left = left;
+    this.viewBox.top = top;
+    this.viewBox.right = right;
+    this.viewBox.bottom = bottom;
+  }
+
+  /**
+   * Update the transform state
+   */
+  setTransform(scale, x, y) {
+    this.transform.scale = scale;
+    this.transform.x = x;
+    this.transform.y = y;
+    this._visibleBoundsDirty = true;
+  }
+
+  /**
+   * Calculate how many pixels a node of given size occupies on screen.
+   * This is the core metric for adaptive rendering decisions.
+   */
+  getNodeScreenSize(nodeSize) {
+    return nodeSize * this.transform.scale;
+  }
+
+  /**
+   * Convert screen coordinates to scene coordinates
+   */
+  screenToScene(screenX, screenY) {
+    const p = this._reusableScenePoint;
+    p.x = (screenX - this.transform.x) / this.transform.scale;
+    p.y = (screenY - this.transform.y) / this.transform.scale;
+    return p;
+  }
+
+  /**
+   * Convert scene coordinates to screen coordinates
+   */
+  sceneToScreen(sceneX, sceneY) {
+    const p = this._reusableScreenPoint;
+    p.x = sceneX * this.transform.scale + this.transform.x;
+    p.y = sceneY * this.transform.scale + this.transform.y;
+    return p;
+  }
+
+  /**
+   * Get the visible bounds in scene coordinates
+   */
+  /**
+   * Returns the cached visible bounds object. Callers must not modify it.
+   */
+  getVisibleBounds() {
+    this._updateVisibleBounds();
+    return this._visibleBounds;
+  }
+
+  _updateVisibleBounds() {
+    if (this._visibleBoundsDirty) {
+      this._visibleBoundsDirty = false;
+      const s = this.transform.scale;
+      const tx = this.transform.x;
+      const ty = this.transform.y;
+      this._visibleBounds.left = (0 - tx) / s;
+      this._visibleBounds.top = (0 - ty) / s;
+      this._visibleBounds.right = (this.width - tx) / s;
+      this._visibleBounds.bottom = (this.height - ty) / s;
+    }
+  }
+
+  /**
+   * Check if a point with given radius is visible in the viewport
+   */
+  isVisible(x, y, radius = 0) {
+    this._updateVisibleBounds();
+    const bounds = this._visibleBounds;
+    return (
+      x + radius >= bounds.left &&
+      x - radius <= bounds.right &&
+      y + radius >= bounds.top &&
+      y - radius <= bounds.bottom
+    );
+  }
+
+  /**
+   * Get the SVG transform string for the current state
+   */
+  getTransformString() {
+    return `translate(${this.transform.x}, ${this.transform.y}) scale(${this.transform.scale})`;
+  }
+}