@opendata-ai/openchart-vanilla 2.1.0 → 2.2.1

package/src/graph-mount.ts

@@ -35,13 +35,21 @@ export interface GraphMountOptions {
   theme?: ThemeConfig;
   darkMode?: DarkMode;
   responsive?: boolean;
+  /** Show the built-in tooltip on node/edge hover. Defaults to true. */
+  tooltip?: boolean;
+  /** Show the built-in legend. Defaults to true. */
+  legend?: boolean;
   onNodeClick?: (node: Record<string, unknown>) => void;
   onNodeDoubleClick?: (node: Record<string, unknown>) => void;
+  onNodeHover?: (node: Record<string, unknown> | null) => void;
+  onEdgeHover?: (edge: Record<string, unknown> | null) => void;
   onSelectionChange?: (nodeIds: string[]) => void;
 }
 
 export interface GraphInstance {
   update(spec: GraphSpec): void;
+  /** Re-compile encoding/legend/chrome without restarting the simulation. Preserves node positions. */
+  updateVisuals(spec: GraphSpec): void;
   search(query: string): void;
   clearSearch(): void;
   zoomToFit(): void;
@@ -107,6 +115,7 @@ export function createGraph(
   let positionedEdges: PositionedEdge[] = [];
   let adjacencyMap = new Map<string, Set<string>>();
   let hoveredNodeId: string | null = null;
+  let hoveredEdgeId: string | null = null;
   let selectedNodeIds = new Set<string>();
   let animFrameId: number | null = null;
   let needsRender = false;
@@ -185,6 +194,61 @@ export function createGraph(
     return node?.data ?? {};
   }
 
+  /**
+   * Point-to-line-segment distance for edge hit testing.
+   * Returns the shortest distance from point (px, py) to the segment (ax, ay)-(bx, by).
+   */
+  function pointToSegmentDist(
+    px: number,
+    py: number,
+    ax: number,
+    ay: number,
+    bx: number,
+    by: number,
+  ): number {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lenSq = dx * dx + dy * dy;
+    if (lenSq === 0) return Math.hypot(px - ax, py - ay);
+    const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / lenSq));
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+  }
+
+  /**
+   * Find the edge closest to a graph-space point, within a threshold.
+   * Returns an edge key "source->target" or null.
+   */
+  function hitTestEdge(graphX: number, graphY: number, threshold: number): string | null {
+    let bestDist = threshold;
+    let bestEdgeId: string | null = null;
+
+    for (const edge of positionedEdges) {
+      const dist = pointToSegmentDist(
+        graphX,
+        graphY,
+        edge.sourceX,
+        edge.sourceY,
+        edge.targetX,
+        edge.targetY,
+      );
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestEdgeId = `${edge.source}->${edge.target}`;
+      }
+    }
+
+    return bestEdgeId;
+  }
+
+  /**
+   * Look up edge data by edge id ("source->target").
+   */
+  function edgeDataById(edgeId: string): Record<string, unknown> | null {
+    const [source, target] = edgeId.split('->');
+    const edge = compilation.edges.find((e) => e.source === source && e.target === target);
+    return edge?.data ?? null;
+  }
+
   // ---------------------------------------------------------------------------
   // DOM creation
   // ---------------------------------------------------------------------------
@@ -218,10 +282,12 @@ export function createGraph(
     wrapper.appendChild(canvas);
 
     // Legend
-    legendEl = document.createElement('div');
-    legendEl.className = 'viz-graph-legend';
-    renderLegend();
-    wrapper.appendChild(legendEl);
+    if (options?.legend !== false) {
+      legendEl = document.createElement('div');
+      legendEl.className = 'viz-graph-legend';
+      renderLegend();
+      wrapper.appendChild(legendEl);
+    }
 
     container.appendChild(wrapper);
 
@@ -289,6 +355,9 @@ export function createGraph(
       alphaDecay: config.alphaDecay,
       velocityDecay: config.velocityDecay,
       collisionRadius: config.collisionRadius,
+      collisionPadding: config.collisionPadding,
+      linkStrength: config.linkStrength,
+      centerForce: config.centerForce,
     });
 
     simulation.onTick((positions, _alpha) => {
@@ -365,6 +434,7 @@ export function createGraph(
         edges: positionedEdges,
         transform: { x: transform.x, y: transform.y, k: transform.k },
         hoveredNodeId,
+        hoveredEdgeId,
         selectedNodeIds,
         adjacencyMap,
         theme: compilation.theme,
@@ -383,7 +453,9 @@ export function createGraph(
   function initInteraction(): void {
     if (!canvas) return;
 
-    tooltipManager = createTooltipManager(wrapper!);
+    if (options?.tooltip !== false) {
+      tooltipManager = createTooltipManager(wrapper!);
+    }
 
     interactionManager = new GraphInteractionManager(canvas, spatialIndex, {
       onTransformChange(_transform) {
@@ -396,8 +468,20 @@ export function createGraph(
         needsRender = true;
         scheduleRender();
 
+        // Fire onNodeHover callback
+        if (nodeId) {
+          options?.onNodeHover?.(nodeDataById(nodeId));
+        } else {
+          options?.onNodeHover?.(null);
+        }
+
         // Show or hide tooltip
         if (nodeId && tooltipManager) {
+          // Clear edge hover when hovering a node
+          if (hoveredEdgeId) {
+            hoveredEdgeId = null;
+            options?.onEdgeHover?.(null);
+          }
           const content = compilation.tooltipDescriptors.get(nodeId);
           if (content) {
             const node = positionedNodes.find((n) => n.id === nodeId);
@@ -406,10 +490,46 @@ export function createGraph(
               tooltipManager.show(content, screen.x, screen.y);
             }
           }
-        } else {
+        } else if (!nodeId) {
+          // Tooltip hiding handled in onBackgroundHover (edge may show tooltip)
+          // If no edge hover happens, tooltip stays hidden
           tooltipManager?.hide();
         }
       },
+      onBackgroundHover(graphX, graphY, screenX, screenY) {
+        // Edge hit testing: check proximity to edge line segments
+        const transform = interactionManager?.getTransform();
+        const threshold = 5 / (transform?.k ?? 1); // 5px in screen space
+        const edgeId = hitTestEdge(graphX, graphY, threshold);
+
+        if (edgeId !== hoveredEdgeId) {
+          hoveredEdgeId = edgeId;
+          needsRender = true;
+          scheduleRender();
+
+          if (edgeId) {
+            const data = edgeDataById(edgeId);
+            options?.onEdgeHover?.(data);
+
+            // Show edge tooltip
+            if (tooltipManager && data) {
+              const fields = Object.entries(data)
+                .filter(([key]) => key !== 'source' && key !== 'target')
+                .filter(([, value]) => value != null)
+                .map(([key, value]) => ({
+                  label: key,
+                  value: typeof value === 'number' ? value.toLocaleString() : String(value),
+                }));
+
+              const [source, target] = edgeId.split('->');
+              tooltipManager.show({ title: `${source} → ${target}`, fields }, screenX, screenY);
+            }
+          } else {
+            options?.onEdgeHover?.(null);
+            tooltipManager?.hide();
+          }
+        }
+      },
       onSelectionChange(nodeIds) {
         selectedNodeIds = new Set(nodeIds);
         needsRender = true;
@@ -567,10 +687,56 @@ export function createGraph(
 
     // Reset state
     hoveredNodeId = null;
+    hoveredEdgeId = null;
     selectedNodeIds = new Set();
     searchManager.clearSearch();
   }
 
+  function updateVisuals(newSpec: GraphSpec): void {
+    if (destroyed) return;
+    currentSpec = newSpec;
+
+    // Build a position lookup from current positioned nodes
+    const posMap = new Map<string, { x: number; y: number }>();
+    for (const node of positionedNodes) {
+      posMap.set(node.id, { x: node.x, y: node.y });
+    }
+
+    // Recompile with new spec (encoding, chrome, nodeOverrides, etc.)
+    compilation = compile();
+    adjacencyMap = buildAdjacencyMap(compilation.edges);
+
+    // Transfer positions to new compiled nodes
+    positionedNodes = compilation.nodes.map((node) => {
+      const pos = posMap.get(node.id) ?? { x: 0, y: 0 };
+      return { ...node, x: pos.x, y: pos.y };
+    });
+
+    // Rebuild positioned edges from existing positions
+    positionedEdges = compilation.edges.map((edge) => {
+      const src = posMap.get(edge.source) ?? { x: 0, y: 0 };
+      const tgt = posMap.get(edge.target) ?? { x: 0, y: 0 };
+      return {
+        ...edge,
+        sourceX: src.x,
+        sourceY: src.y,
+        targetX: tgt.x,
+        targetY: tgt.y,
+      };
+    });
+
+    // Rebuild spatial index with updated visuals
+    spatialIndex.rebuild(positionedNodes);
+
+    // Update DOM chrome/legend
+    renderChrome();
+    renderLegend();
+
+    // Re-render canvas without restarting simulation
+    needsRender = true;
+    scheduleRender();
+  }
+
   function teardownSubsystems(): void {
     if (animFrameId !== null) {
       cancelAnimationFrame(animFrameId);
@@ -631,6 +797,7 @@ export function createGraph(
     // Return a no-op instance so callers don't crash
     return {
       update() {},
+      updateVisuals() {},
       search() {},
       clearSearch() {},
       zoomToFit() {},
@@ -651,6 +818,7 @@ export function createGraph(
 
   return {
     update,
+    updateVisuals,
     search,
     clearSearch,
     zoomToFit,

package/src/index.ts

@@ -17,9 +17,9 @@ export type {
   TableSpec,
   VizSpec,
 } from '@opendata-ai/openchart-engine';
-export type { PNGExportOptions } from './export';
+export type { JPGExportOptions, PNGExportOptions } from './export';
 // Export utilities
-export { exportCSV, exportPNG, exportSVG } from './export';
+export { exportCSV, exportJPG, exportPNG, exportSVG } from './export';
 // Graph simulation worker
 export { createSimulationWorker } from './graph/simulation-worker-url';
 export type { GraphInstance, GraphMountOptions } from './graph-mount';

package/src/mount.ts

@@ -26,7 +26,7 @@ import type {
   TooltipContent,
 } from '@opendata-ai/openchart-core';
 import { compileChart } from '@opendata-ai/openchart-engine';
-import { exportCSV, exportPNG, exportSVG, type PNGExportOptions } from './export';
+import { exportCSV, exportJPG, exportPNG, exportSVG, type JPGExportOptions } from './export';
 import { observeResize } from './resize-observer';
 import { renderChartSVG } from './svg-renderer';
 import { createTooltipManager, type TooltipManager } from './tooltip';
@@ -46,8 +46,8 @@ export interface MountOptions extends ChartEventHandlers {
   responsive?: boolean;
 }
 
-export interface ExportOptions extends PNGExportOptions {
-  // Extensible for future formats
+export interface ExportOptions extends JPGExportOptions {
+  // Extensible for future formats (extends JPGExportOptions which extends PNGExportOptions)
 }
 
 export interface ChartInstance {
@@ -58,8 +58,9 @@ export interface ChartInstance {
   /** Export the chart. */
   export(format: 'svg'): string;
   export(format: 'png', options?: ExportOptions): Promise<Blob>;
+  export(format: 'jpg', options?: ExportOptions): Promise<Blob>;
   export(format: 'csv'): string;
-  export(format: 'svg' | 'png' | 'csv', options?: ExportOptions): string | Promise<Blob>;
+  export(format: 'svg' | 'png' | 'jpg' | 'csv', options?: ExportOptions): string | Promise<Blob>;
   /** Remove all DOM elements and disconnect observers. */
   destroy(): void;
   /** The current compiled layout (for hooks / debugging). */
@@ -1096,13 +1097,16 @@ function wireSeriesLabelDrag(
 
 /**
  * Wire click handlers on legend entries to toggle series visibility.
- * Optionally calls onLegendToggle when a series is toggled.
+ * Fires onEdit with { type: 'legend-toggle', series, hidden } for each toggle,
+ * and optionally calls the legacy onLegendToggle callback.
+ * Legend entries for hidden series stay visible but dimmed (opacity 0.3).
  * Returns a cleanup function.
  */
 function wireLegendInteraction(
   svg: SVGElement,
   _layout: ChartLayout,
   onLegendToggle?: (series: string, visible: boolean) => void,
+  onEdit?: (edit: ElementEdit) => void,
 ): () => void {
   const legendEntries = svg.querySelectorAll('[data-legend-index]');
   const cleanups: Array<() => void> = [];
@@ -1120,11 +1124,13 @@ function wireLegendInteraction(
         entry.setAttribute('opacity', '1');
         entry.setAttribute('aria-label', `${label}: visible`);
         onLegendToggle?.(label, true);
+        onEdit?.({ type: 'legend-toggle', series: label, hidden: false });
       } else {
         hiddenSeries.add(label);
         entry.setAttribute('opacity', '0.3');
         entry.setAttribute('aria-label', `${label}: hidden`);
         onLegendToggle?.(label, false);
+        onEdit?.({ type: 'legend-toggle', series: label, hidden: true });
       }
 
       // Toggle visibility of marks with matching series.
@@ -1448,7 +1454,12 @@ export function createChart(
     );
 
     // Wire legend interactivity
-    cleanupLegend = wireLegendInteraction(svgElement, currentLayout, options?.onLegendToggle);
+    cleanupLegend = wireLegendInteraction(
+      svgElement,
+      currentLayout,
+      options?.onLegendToggle,
+      options?.onEdit,
+    );
 
     // Wire chart event handlers (mark click/hover/leave, annotation click)
     if (
@@ -1546,9 +1557,10 @@ export function createChart(
 
   function doExport(format: 'svg'): string;
   function doExport(format: 'png', exportOptions?: ExportOptions): Promise<Blob>;
+  function doExport(format: 'jpg', exportOptions?: ExportOptions): Promise<Blob>;
   function doExport(format: 'csv'): string;
   function doExport(
-    format: 'svg' | 'png' | 'csv',
+    format: 'svg' | 'png' | 'jpg' | 'csv',
     exportOptions?: ExportOptions,
   ): string | Promise<Blob> {
     if (!svgElement) {
@@ -1560,6 +1572,8 @@ export function createChart(
         return exportSVG(svgElement);
       case 'png':
         return exportPNG(svgElement, exportOptions);
+      case 'jpg':
+        return exportJPG(svgElement, exportOptions);
       case 'csv':
         return exportCSV(
           'data' in currentSpec && Array.isArray(currentSpec.data) ? currentSpec.data : [],