@opendata-ai/openchart-vanilla 2.0.0

package/src/graph/simulation-worker.ts

@@ -0,0 +1,265 @@
+// DedicatedWorkerGlobalScope is available at runtime in Web Workers but
+// the 'webworker' lib conflicts with 'DOM' in the main tsconfig. Declaring
+// a minimal interface here avoids adding a separate tsconfig for one file.
+interface WorkerSelf {
+  postMessage(msg: unknown): void;
+  onmessage: ((event: MessageEvent) => void) | null;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+}
+declare const self: WorkerSelf;
+
+/**
+ * Force-directed graph simulation Web Worker.
+ *
+ * BUNDLING: Built separately via `bun build` (see package.json "build" script)
+ * into dist/simulation-worker.js as a self-contained IIFE. d3-force and all
+ * its transitive deps are inlined -- no external imports in the output.
+ *
+ * IMPORTANT: This file cannot import from workspace packages (@opendata-ai/*).
+ * All needed types are defined inline or duplicated from worker-protocol.ts.
+ * The bun build step bundles this as an isolated IIFE.
+ *
+ * The companion simulation-worker-url.ts provides createSimulationWorker()
+ * which uses `new URL('./simulation-worker.ts', import.meta.url)` for Vite dev,
+ * while production consumers load the pre-built dist/simulation-worker.js.
+ */
+
+import {
+  forceCenter,
+  forceCollide,
+  forceLink,
+  forceManyBody,
+  forceSimulation,
+  forceX,
+  forceY,
+  type Simulation,
+  type SimulationNodeDatum,
+} from 'd3-force';
+
+// ---------------------------------------------------------------------------
+// Inline types (duplicated from worker-protocol.ts for bundle isolation)
+// ---------------------------------------------------------------------------
+
+interface SimNode {
+  id: string;
+  x?: number;
+  y?: number;
+  radius: number;
+  community?: string;
+}
+
+interface SimEdge {
+  source: string;
+  target: string;
+}
+
+interface SimConfig {
+  chargeStrength: number;
+  linkDistance: number;
+  clustering: { field: string; strength: number } | null;
+  alphaDecay: number;
+  velocityDecay: number;
+  collisionRadius: number;
+}
+
+type InMessage =
+  | { type: 'init'; nodes: SimNode[]; edges: SimEdge[]; config: SimConfig }
+  | { 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' };
+
+type OutMessage =
+  | { type: 'positions'; nodes: Array<{ id: string; x: number; y: number }>; alpha: number }
+  | { type: 'settled' }
+  | { type: 'error'; message: string };
+
+// ---------------------------------------------------------------------------
+// Internal simulation node (extends d3 SimulationNodeDatum)
+// ---------------------------------------------------------------------------
+
+interface InternalNode extends SimulationNodeDatum {
+  id: string;
+  radius: number;
+  community?: string;
+  fx?: number | null;
+  fy?: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Custom cluster force
+// ---------------------------------------------------------------------------
+
+/**
+ * Pulls nodes toward the centroid of their community group.
+ * Strength controls how aggressively nodes cluster (0-1, default 0.3).
+ *
+ * NOTE: Duplicated in simulation.ts (sync fallback path). This file can't
+ * import from workspace packages since it's built as a standalone IIFE.
+ * Keep both copies in sync.
+ */
+function forceCluster(nodes: InternalNode[], strength: number) {
+  return (alpha: number) => {
+    // Compute per-community centroid
+    const cx = new Map<string, number>();
+    const cy = new Map<string, number>();
+    const count = new Map<string, number>();
+
+    for (const node of nodes) {
+      if (!node.community) continue;
+      const c = node.community;
+      cx.set(c, (cx.get(c) ?? 0) + (node.x ?? 0));
+      cy.set(c, (cy.get(c) ?? 0) + (node.y ?? 0));
+      count.set(c, (count.get(c) ?? 0) + 1);
+    }
+
+    // Normalize to get mean positions
+    for (const [c, n] of count) {
+      cx.set(c, cx.get(c)! / n);
+      cy.set(c, cy.get(c)! / n);
+    }
+
+    // Pull each node toward its community centroid
+    const k = strength * alpha;
+    for (const node of nodes) {
+      if (!node.community) continue;
+      const targetX = cx.get(node.community)!;
+      const targetY = cy.get(node.community)!;
+      node.vx = (node.vx ?? 0) + (targetX - (node.x ?? 0)) * k;
+      node.vy = (node.vy ?? 0) + (targetY - (node.y ?? 0)) * k;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Worker entry point
+// ---------------------------------------------------------------------------
+
+const ctx = self;
+let simulation: Simulation<InternalNode, undefined> | null = null;
+let nodeMap: Map<string, InternalNode> = new Map();
+
+function post(msg: OutMessage): void {
+  ctx.postMessage(msg);
+}
+
+function packPositions(nodes: InternalNode[]): Array<{ id: string; x: number; y: number }> {
+  return nodes.map((n) => ({
+    id: n.id,
+    x: n.x ?? 0,
+    y: n.y ?? 0,
+  }));
+}
+
+ctx.addEventListener('message', ((event: MessageEvent<InMessage>) => {
+  const msg = event.data;
+
+  try {
+    switch (msg.type) {
+      case 'init': {
+        // Stop any existing simulation
+        if (simulation) simulation.stop();
+
+        const internalNodes: InternalNode[] = msg.nodes.map((n) => ({
+          id: n.id,
+          x: n.x,
+          y: n.y,
+          radius: n.radius,
+          community: n.community,
+        }));
+
+        nodeMap = new Map(internalNodes.map((n) => [n.id, n]));
+
+        const { config } = msg;
+
+        simulation = forceSimulation<InternalNode>(internalNodes)
+          .force(
+            'link',
+            forceLink(msg.edges.map((e) => ({ ...e })))
+              .id((d) => (d as InternalNode).id)
+              .distance(config.linkDistance),
+          )
+          .force('charge', forceManyBody().strength(config.chargeStrength))
+          .force('center', forceCenter(0, 0))
+          .force(
+            'collide',
+            forceCollide<InternalNode>().radius((d) => d.radius + 1),
+          )
+          // Weak gravity keeps disconnected nodes from drifting far from center
+          .force('gravityX', forceX<InternalNode>(0).strength(0.05))
+          .force('gravityY', forceY<InternalNode>(0).strength(0.05))
+          .alphaDecay(config.alphaDecay)
+          .velocityDecay(config.velocityDecay);
+
+        // Add clustering force if configured
+        if (config.clustering) {
+          const clusterFn = forceCluster(internalNodes, config.clustering.strength);
+          // d3 calls force functions with (alpha) on each tick
+          simulation.force('cluster', clusterFn as unknown as ReturnType<typeof forceCenter>);
+        }
+
+        simulation.on('tick', () => {
+          post({
+            type: 'positions',
+            nodes: packPositions(internalNodes),
+            alpha: simulation!.alpha(),
+          });
+        });
+
+        simulation.on('end', () => {
+          post({ type: 'settled' });
+        });
+
+        break;
+      }
+
+      case 'reheat': {
+        if (!simulation) break;
+        simulation.alpha(msg.alpha ?? 0.3).restart();
+        break;
+      }
+
+      case 'pin': {
+        const node = nodeMap.get(msg.nodeId);
+        if (node) {
+          node.fx = msg.x;
+          node.fy = msg.y;
+        }
+        break;
+      }
+
+      case 'unpin': {
+        const node = nodeMap.get(msg.nodeId);
+        if (node) {
+          node.fx = null;
+          node.fy = null;
+        }
+        break;
+      }
+
+      case 'drag': {
+        const node = nodeMap.get(msg.nodeId);
+        if (node) {
+          node.fx = msg.x;
+          node.fy = msg.y;
+        }
+        // Reheat slightly for responsive dragging
+        if (simulation && simulation.alpha() < 0.1) {
+          simulation.alpha(0.1).restart();
+        }
+        break;
+      }
+
+      case 'stop': {
+        if (simulation) simulation.stop();
+        break;
+      }
+    }
+  } catch (err) {
+    post({
+      type: 'error',
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+}) as EventListener);

package/src/graph/simulation.ts

@@ -0,0 +1,350 @@
+/**
+ * SimulationManager: spawns a Web Worker for the force simulation,
+ * or falls back to synchronous d3-force on the main thread.
+ *
+ * Synchronous fallback is used when:
+ * - Web Workers are unavailable (SSR, test environments)
+ * - Node count is below 200 (worker overhead not worth it)
+ *
+ * The sync path caps at 300 ticks to prevent blocking the main thread.
+ */
+
+import {
+  forceCenter,
+  forceCollide,
+  forceLink,
+  forceManyBody,
+  forceSimulation,
+  forceX,
+  forceY,
+  type Simulation,
+  type SimulationNodeDatum,
+} from 'd3-force';
+
+import type { SimEdge, SimNode, WorkerOutMessage, WorkerSimulationConfig } from './worker-protocol';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SYNC_THRESHOLD = 200;
+const SYNC_MAX_TICKS = 300;
+
+// ---------------------------------------------------------------------------
+// Internal node shape for sync simulation
+// ---------------------------------------------------------------------------
+
+interface SyncNode extends SimulationNodeDatum {
+  id: string;
+  radius: number;
+  community?: string;
+  fx?: number | null;
+  fy?: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Cluster force (duplicated in simulation-worker.ts for the Web Worker path.
+// Worker can't import from workspace packages, so both copies must stay in sync.)
+// ---------------------------------------------------------------------------
+
+function forceCluster(nodes: SyncNode[], strength: number) {
+  return (alpha: number) => {
+    const cx = new Map<string, number>();
+    const cy = new Map<string, number>();
+    const count = new Map<string, number>();
+
+    for (const node of nodes) {
+      if (!node.community) continue;
+      const c = node.community;
+      cx.set(c, (cx.get(c) ?? 0) + (node.x ?? 0));
+      cy.set(c, (cy.get(c) ?? 0) + (node.y ?? 0));
+      count.set(c, (count.get(c) ?? 0) + 1);
+    }
+
+    for (const [c, n] of count) {
+      cx.set(c, cx.get(c)! / n);
+      cy.set(c, cy.get(c)! / n);
+    }
+
+    const k = strength * alpha;
+    for (const node of nodes) {
+      if (!node.community) continue;
+      const targetX = cx.get(node.community)!;
+      const targetY = cy.get(node.community)!;
+      node.vx = (node.vx ?? 0) + (targetX - (node.x ?? 0)) * k;
+      node.vy = (node.vy ?? 0) + (targetY - (node.y ?? 0)) * k;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// SimulationManager
+// ---------------------------------------------------------------------------
+
+type TickCallback = (positions: Array<{ id: string; x: number; y: number }>, alpha: number) => void;
+
+type SettledCallback = () => void;
+
+export class SimulationManager {
+  private worker: Worker | null = null;
+  private syncSim: Simulation<SyncNode, undefined> | null = null;
+  private syncNodes: SyncNode[] = [];
+  private syncNodeMap: Map<string, SyncNode> = new Map();
+  private tickCb: TickCallback | null = null;
+  private settledCb: SettledCallback | null = null;
+  private destroyed = false;
+
+  // Stored for worker->sync fallback
+  private initNodes: SimNode[] = [];
+  private initEdges: SimEdge[] = [];
+  private initConfig: WorkerSimulationConfig | null = null;
+
+  private constructor() {}
+
+  /**
+   * Create a SimulationManager. Uses Web Worker for large graphs,
+   * synchronous fallback for small graphs or when Worker unavailable.
+   */
+  static create(
+    nodes: SimNode[],
+    edges: SimEdge[],
+    config: WorkerSimulationConfig,
+  ): SimulationManager {
+    const mgr = new SimulationManager();
+
+    const useWorker = typeof Worker !== 'undefined' && nodes.length >= SYNC_THRESHOLD;
+
+    if (useWorker) {
+      mgr.initWorker(nodes, edges, config);
+    } else {
+      mgr.initSync(nodes, edges, config);
+    }
+
+    return mgr;
+  }
+
+  /** Register a callback for position updates. */
+  onTick(cb: TickCallback): void {
+    this.tickCb = cb;
+  }
+
+  /** Register a callback for when the simulation has settled. */
+  onSettled(cb: SettledCallback): void {
+    this.settledCb = cb;
+  }
+
+  /** Reheat the simulation. */
+  reheat(alpha?: number): void {
+    if (this.destroyed) return;
+
+    if (this.worker) {
+      this.worker.postMessage({ type: 'reheat', alpha });
+    } else if (this.syncSim) {
+      this.syncSim.alpha(alpha ?? 0.3).restart();
+      this.runSyncTicks();
+    }
+  }
+
+  /** Pin a node to fixed x/y coordinates. */
+  pinNode(id: string, x: number, y: number): void {
+    if (this.destroyed) return;
+
+    if (this.worker) {
+      this.worker.postMessage({ type: 'pin', nodeId: id, x, y });
+    } else {
+      const node = this.syncNodeMap.get(id);
+      if (node) {
+        node.fx = x;
+        node.fy = y;
+      }
+    }
+  }
+
+  /** Unpin a node (free it from fixed position). */
+  unpinNode(id: string): void {
+    if (this.destroyed) return;
+
+    if (this.worker) {
+      this.worker.postMessage({ type: 'unpin', nodeId: id });
+    } else {
+      const node = this.syncNodeMap.get(id);
+      if (node) {
+        node.fx = null;
+        node.fy = null;
+      }
+    }
+  }
+
+  /** Drag a node (pins it and reheats slightly). */
+  dragNode(id: string, x: number, y: number): void {
+    if (this.destroyed) return;
+
+    if (this.worker) {
+      this.worker.postMessage({ type: 'drag', nodeId: id, x, y });
+    } else {
+      const node = this.syncNodeMap.get(id);
+      if (node) {
+        node.fx = x;
+        node.fy = y;
+      }
+      if (this.syncSim && this.syncSim.alpha() < 0.1) {
+        this.syncSim.alpha(0.1).restart();
+        this.runSyncTicks();
+      }
+    }
+  }
+
+  /** Tear down the simulation and release resources. */
+  destroy(): void {
+    this.destroyed = true;
+
+    if (this.worker) {
+      this.worker.postMessage({ type: 'stop' });
+      this.worker.terminate();
+      this.worker = null;
+    }
+
+    if (this.syncSim) {
+      this.syncSim.stop();
+      this.syncSim = null;
+    }
+
+    this.tickCb = null;
+    this.settledCb = null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Worker path
+  // -------------------------------------------------------------------------
+
+  private initWorker(nodes: SimNode[], edges: SimEdge[], config: WorkerSimulationConfig): void {
+    // Store for fallback if worker fails to load
+    this.initNodes = nodes;
+    this.initEdges = edges;
+    this.initConfig = config;
+
+    try {
+      const workerUrl = new URL('./simulation-worker.ts', import.meta.url);
+      this.worker = new Worker(workerUrl, { type: 'module' });
+    } catch {
+      // Worker construction failed (e.g. SSR or restrictive CSP)
+      console.warn('[SimulationManager] Worker creation failed, using sync fallback');
+      this.initSync(nodes, edges, config);
+      return;
+    }
+
+    this.worker.onmessage = (event: MessageEvent<WorkerOutMessage>) => {
+      if (this.destroyed) return;
+      const msg = event.data;
+
+      switch (msg.type) {
+        case 'positions':
+          this.tickCb?.(msg.nodes, msg.alpha);
+          break;
+        case 'settled':
+          this.settledCb?.();
+          break;
+        case 'error':
+          console.error('[SimulationManager] Worker error:', msg.message);
+          break;
+      }
+    };
+
+    this.worker.onerror = () => {
+      // Worker failed to load (e.g. MIME type error in dev, missing file).
+      // Terminate and fall back to synchronous simulation.
+      if (this.destroyed) return;
+      console.warn('[SimulationManager] Worker failed to load, falling back to sync');
+      this.worker?.terminate();
+      this.worker = null;
+      this.initSync(this.initNodes, this.initEdges, this.initConfig!);
+    };
+
+    this.worker.postMessage({ type: 'init', nodes, edges, config });
+  }
+
+  // -------------------------------------------------------------------------
+  // Synchronous fallback
+  // -------------------------------------------------------------------------
+
+  private initSync(nodes: SimNode[], edges: SimEdge[], config: WorkerSimulationConfig): void {
+    this.syncNodes = nodes.map((n) => ({
+      id: n.id,
+      x: n.x,
+      y: n.y,
+      radius: n.radius,
+      community: n.community,
+    }));
+
+    this.syncNodeMap = new Map(this.syncNodes.map((n) => [n.id, n]));
+
+    this.syncSim = forceSimulation<SyncNode>(this.syncNodes)
+      .force(
+        'link',
+        forceLink(edges.map((e) => ({ ...e })))
+          .id((d) => (d as SyncNode).id)
+          .distance(config.linkDistance),
+      )
+      .force('charge', forceManyBody().strength(config.chargeStrength))
+      .force('center', forceCenter(0, 0))
+      .force(
+        'collide',
+        forceCollide<SyncNode>().radius((d) => d.radius + 1),
+      )
+      // Weak gravity keeps disconnected nodes from drifting far from center
+      .force('gravityX', forceX<SyncNode>(0).strength(0.05))
+      .force('gravityY', forceY<SyncNode>(0).strength(0.05))
+      .alphaDecay(config.alphaDecay)
+      .velocityDecay(config.velocityDecay)
+      .stop(); // Don't auto-run; we tick manually
+
+    // Add clustering force if configured
+    if (config.clustering) {
+      const clusterFn = forceCluster(this.syncNodes, config.clustering.strength);
+      // d3 calls force functions with (alpha) on each tick
+      this.syncSim.force('cluster', clusterFn as unknown as ReturnType<typeof forceCenter>);
+    }
+
+    // Defer initial delivery: callbacks aren't wired yet at create() time
+    this.runSyncTicks(true);
+  }
+
+  /**
+   * Run ticks synchronously and fire callbacks.
+   * @param deferred - When true, deliver results via microtask. Used for the
+   *   initial run where callbacks haven't been registered yet. Subsequent
+   *   calls (reheat, drag) fire synchronously since callbacks are already set.
+   */
+  private runSyncTicks(deferred = false): void {
+    if (!this.syncSim || this.destroyed) return;
+
+    const sim = this.syncSim;
+    for (let i = 0; i < SYNC_MAX_TICKS; i++) {
+      sim.tick();
+      if (sim.alpha() < 0.001) break;
+    }
+
+    const positions = this.syncNodes.map((n) => ({
+      id: n.id,
+      x: n.x ?? 0,
+      y: n.y ?? 0,
+    }));
+    const alpha = sim.alpha();
+    const settled = alpha < 0.001;
+
+    const deliver = () => {
+      if (this.destroyed) return;
+      this.tickCb?.(positions, alpha);
+      if (settled) {
+        this.settledCb?.();
+      }
+    };
+
+    if (deferred) {
+      // Initial run: callbacks not registered yet, defer to microtask
+      queueMicrotask(deliver);
+    } else {
+      deliver();
+    }
+  }
+}