@opendata-ai/openchart-vanilla 2.0.0

package/src/graph/spatial-index.ts

@@ -0,0 +1,121 @@
+/**
+ * Spatial index for fast node hit-testing.
+ *
+ * Wraps d3-quadtree to provide findNearest (accounts for node radius)
+ * and findInRect queries. Tracks a generation counter to avoid unnecessary
+ * rebuilds when positions haven't changed.
+ */
+
+import { type Quadtree, quadtree } from 'd3-quadtree';
+import type { PositionedNode } from './types';
+
+export class SpatialIndex {
+  private tree: Quadtree<PositionedNode> | null = null;
+  private nodes: PositionedNode[] = [];
+  private maxRadius = 0;
+  private generation = 0;
+
+  /** Rebuild the quadtree from the current set of positioned nodes. */
+  rebuild(nodes: PositionedNode[]): void {
+    this.nodes = nodes;
+    this.maxRadius = 0;
+    for (const n of nodes) {
+      if (n.radius > this.maxRadius) this.maxRadius = n.radius;
+    }
+
+    this.tree = quadtree<PositionedNode>()
+      .x((d) => d.x)
+      .y((d) => d.y)
+      .addAll(nodes);
+    this.generation++;
+  }
+
+  /** Current generation counter. Increments on each rebuild. */
+  getGeneration(): number {
+    return this.generation;
+  }
+
+  /**
+   * Find the nearest node to (x, y) within maxDistance.
+   * Accounts for node radius: a hit occurs if the point is inside
+   * the node circle (distance to center < node.radius), or if the
+   * edge-to-edge distance is within maxDistance.
+   */
+  findNearest(x: number, y: number, maxDistance: number = Infinity): PositionedNode | null {
+    if (!this.tree || this.nodes.length === 0) return null;
+
+    // The effective search radius for the quadtree needs to include
+    // the largest node radius, because we might be "inside" a large node
+    // whose center is far from our search point.
+    const searchRadius = maxDistance + this.maxRadius;
+
+    let best: PositionedNode | null = null;
+    let bestEffectiveDist = maxDistance + this.maxRadius + 1;
+
+    this.tree.visit((node, x0, y0, x1, y1) => {
+      // Closest point in this quad to our target
+      const closestX = Math.max(x0, Math.min(x, x1));
+      const closestY = Math.max(y0, Math.min(y, y1));
+      const quadDist = Math.hypot(closestX - x, closestY - y);
+
+      // Prune: if the closest edge of this quad is beyond searchRadius, skip
+      if (quadDist > searchRadius) return true;
+
+      // Check leaf data
+      if (!node.length) {
+        let current = node;
+        do {
+          const d = current.data;
+          if (d) {
+            const dist = Math.hypot(d.x - x, d.y - y);
+            // Effective distance: subtract the node's radius.
+            // If we're inside the circle, effective distance is 0.
+            const effectiveDist = Math.max(0, dist - d.radius);
+            if (effectiveDist <= maxDistance && effectiveDist < bestEffectiveDist) {
+              bestEffectiveDist = effectiveDist;
+              best = d;
+            }
+          }
+        } while ((current = current.next!));
+      }
+
+      return false;
+    });
+
+    return best;
+  }
+
+  /** Find all nodes whose centers fall within the given rectangle. */
+  findInRect(x1: number, y1: number, x2: number, y2: number): PositionedNode[] {
+    if (!this.tree) return [];
+
+    const minX = Math.min(x1, x2);
+    const minY = Math.min(y1, y2);
+    const maxX = Math.max(x1, x2);
+    const maxY = Math.max(y1, y2);
+
+    const results: PositionedNode[] = [];
+
+    this.tree.visit((node, qx0, qy0, qx1, qy1) => {
+      // If quad doesn't overlap the search rect, skip
+      if (qx0 > maxX || qx1 < minX || qy0 > maxY || qy1 < minY) {
+        return true;
+      }
+
+      // Check leaf nodes
+      if (!node.length) {
+        let current = node;
+        do {
+          const d = current.data;
+          if (d && d.x >= minX && d.x <= maxX && d.y >= minY && d.y <= maxY) {
+            results.push(d);
+          }
+        } while ((current = current.next!));
+      }
+
+      return false;
+    });
+
+    return results;
+  }
+}

package/src/graph/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared types for the graph adapter.
+ *
+ * These extend the engine's compiled types with positional information set by
+ * the force simulation at runtime. The engine produces CompiledGraphNode/Edge
+ * objects with visual properties but no x/y coords. After simulation, we get
+ * PositionedNode/Edge that the canvas renderer can draw.
+ */
+
+import type { ResolvedTheme } from '@opendata-ai/openchart-core';
+import type { CompiledGraphEdge, CompiledGraphNode } from '@opendata-ai/openchart-engine';
+
+/** A compiled node with simulation-assigned x/y position. */
+export interface PositionedNode extends CompiledGraphNode {
+  x: number;
+  y: number;
+}
+
+/** A compiled edge with resolved source/target screen positions. */
+export interface PositionedEdge extends CompiledGraphEdge {
+  sourceX: number;
+  sourceY: number;
+  targetX: number;
+  targetY: number;
+}
+
+/**
+ * Complete render state passed to the canvas renderer each frame.
+ *
+ * Assembled by the graph mount from simulation positions, interaction state,
+ * and theme. The renderer is stateless -- it draws whatever this says.
+ */
+export interface GraphRenderState {
+  nodes: PositionedNode[];
+  edges: PositionedEdge[];
+  transform: { x: number; y: number; k: number };
+  hoveredNodeId: string | null;
+  selectedNodeIds: Set<string>;
+  adjacencyMap: Map<string, Set<string>>;
+  theme: ResolvedTheme;
+  searchMatches: Set<string> | null;
+  /** True during active pan/zoom gestures. Renderer skips labels and glow. */
+  isGesturing: boolean;
+}

package/src/graph/worker-protocol.ts

@@ -0,0 +1,67 @@
+/**
+ * Message protocol between the main thread and the simulation Web Worker.
+ *
+ * Defines the shape of messages going in both directions, plus the internal
+ * node/edge types the simulation works with. These are intentionally simple
+ * and independent from the engine's compiled types so the worker can be
+ * built as a standalone IIFE without workspace imports.
+ */
+
+// ---------------------------------------------------------------------------
+// Simulation data shapes (used internally by worker + sync fallback)
+// ---------------------------------------------------------------------------
+
+/** Minimal node shape for the force simulation. */
+export interface SimNode {
+  id: string;
+  x?: number;
+  y?: number;
+  radius: number;
+  community?: string;
+}
+
+/** Minimal edge shape for the force simulation. */
+export interface SimEdge {
+  source: string;
+  target: string;
+}
+
+/** Inline simulation config (mirrors engine SimulationConfig). */
+export interface WorkerSimulationConfig {
+  chargeStrength: number;
+  linkDistance: number;
+  clustering: { field: string; strength: number } | null;
+  alphaDecay: number;
+  velocityDecay: number;
+  collisionRadius: number;
+}
+
+// ---------------------------------------------------------------------------
+// Main -> Worker messages
+// ---------------------------------------------------------------------------
+
+export type WorkerInMessage =
+  | {
+      type: 'init';
+      nodes: SimNode[];
+      edges: SimEdge[];
+      config: WorkerSimulationConfig;
+    }
+  | { type: 'reheat'; alpha?: number }
+  | { type: 'pin'; nodeId: string; x: number; y: number }
+  | { type: 'unpin'; nodeId: string }
+  | { type: 'drag'; nodeId: string; x: number; y: number }
+  | { type: 'stop' };
+
+// ---------------------------------------------------------------------------
+// Worker -> Main messages
+// ---------------------------------------------------------------------------
+
+export type WorkerOutMessage =
+  | {
+      type: 'positions';
+      nodes: Array<{ id: string; x: number; y: number }>;
+      alpha: number;
+    }
+  | { type: 'settled' }
+  | { type: 'error'; message: string };

package/src/graph/zoom.ts

@@ -0,0 +1,104 @@
+/**
+ * Immutable zoom transform for graph pan/zoom.
+ *
+ * Provides coordinate conversion between screen space (canvas pixels)
+ * and graph space (simulation coordinates). All mutations return new
+ * instances rather than modifying in place.
+ */
+
+import type { PositionedNode } from './types';
+
+export class ZoomTransform {
+  constructor(
+    readonly x: number,
+    readonly y: number,
+    readonly k: number,
+  ) {}
+
+  /** Convert screen coordinates to graph coordinates. */
+  screenToGraph(sx: number, sy: number): { x: number; y: number } {
+    return {
+      x: (sx - this.x) / this.k,
+      y: (sy - this.y) / this.k,
+    };
+  }
+
+  /** Convert graph coordinates to screen coordinates. */
+  graphToScreen(gx: number, gy: number): { x: number; y: number } {
+    return {
+      x: gx * this.k + this.x,
+      y: gy * this.k + this.y,
+    };
+  }
+
+  /**
+   * Zoom to a target scale, keeping the given screen-space pivot
+   * point fixed (content under the cursor stays under the cursor).
+   */
+  zoomAt(targetK: number, pivotX: number, pivotY: number): ZoomTransform {
+    // The graph point under the pivot should remain at the same screen position.
+    // Before: pivotX = gx * k + x  =>  gx = (pivotX - x) / k
+    // After:  pivotX = gx * targetK + newX  =>  newX = pivotX - gx * targetK
+    const gx = (pivotX - this.x) / this.k;
+    const gy = (pivotY - this.y) / this.k;
+    return new ZoomTransform(pivotX - gx * targetK, pivotY - gy * targetK, targetK);
+  }
+
+  /** Pan by a screen-space delta. */
+  pan(dx: number, dy: number): ZoomTransform {
+    return new ZoomTransform(this.x + dx, this.y + dy, this.k);
+  }
+
+  /**
+   * Compute a transform that fits all nodes within the given canvas
+   * dimensions with the specified padding.
+   */
+  static fitBounds(
+    nodes: PositionedNode[],
+    canvasW: number,
+    canvasH: number,
+    padding: number = 40,
+  ): ZoomTransform {
+    if (nodes.length === 0) {
+      return ZoomTransform.identity();
+    }
+
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+
+    for (const n of nodes) {
+      const r = n.radius;
+      if (n.x - r < minX) minX = n.x - r;
+      if (n.y - r < minY) minY = n.y - r;
+      if (n.x + r > maxX) maxX = n.x + r;
+      if (n.y + r > maxY) maxY = n.y + r;
+    }
+
+    const graphW = maxX - minX;
+    const graphH = maxY - minY;
+
+    if (graphW === 0 && graphH === 0) {
+      // All nodes at the same point; just center
+      return new ZoomTransform(canvasW / 2 - minX, canvasH / 2 - minY, 1);
+    }
+
+    const availW = canvasW - padding * 2;
+    const availH = canvasH - padding * 2;
+    const k = Math.min(availW / graphW, availH / graphH);
+
+    // Center the graph in the canvas
+    const cx = (minX + maxX) / 2;
+    const cy = (minY + maxY) / 2;
+    const tx = canvasW / 2 - cx * k;
+    const ty = canvasH / 2 - cy * k;
+
+    return new ZoomTransform(tx, ty, k);
+  }
+
+  /** Identity transform (no pan, no zoom). */
+  static identity(): ZoomTransform {
+    return new ZoomTransform(0, 0, 1);
+  }
+}