@opendata-ai/openchart-engine 1.2.0

package/src/graphs/__tests__/encoding.test.ts

@@ -0,0 +1,314 @@
+import type {
+  GraphEdge,
+  GraphEncoding,
+  GraphNode,
+  ResolvedTheme,
+} from '@opendata-ai/openchart-core';
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { darkenColor, resolveEdgeVisuals, resolveNodeVisuals } from '../encoding';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const theme: ResolvedTheme = resolveTheme({});
+
+const basicNodes: GraphNode[] = [
+  { id: 'a', value: 10, group: 'X', name: 'Alice' },
+  { id: 'b', value: 50, group: 'X', name: 'Bob' },
+  { id: 'c', value: 100, group: 'Y', name: 'Carol' },
+];
+
+const basicEdges: GraphEdge[] = [
+  { source: 'a', target: 'b', weight: 1 },
+  { source: 'b', target: 'c', weight: 5 },
+  { source: 'a', target: 'c', weight: 10 },
+];
+
+// ---------------------------------------------------------------------------
+// resolveNodeVisuals tests
+// ---------------------------------------------------------------------------
+
+describe('resolveNodeVisuals', () => {
+  describe('node size scaling', () => {
+    it('produces varying radii when nodeSize encoding is set', () => {
+      const encoding: GraphEncoding = {
+        nodeSize: { field: 'value', type: 'quantitative' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const radii = new Set(nodes.map((n) => n.radius));
+      expect(radii.size).toBeGreaterThan(1);
+    });
+
+    it('maps min data value to min radius and max to max radius', () => {
+      const encoding: GraphEncoding = {
+        nodeSize: { field: 'value', type: 'quantitative' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const minNode = nodes.find((n) => n.data.value === 10)!;
+      const maxNode = nodes.find((n) => n.data.value === 100)!;
+
+      // Min value should get min radius (3px)
+      expect(minNode.radius).toBeCloseTo(3, 0);
+      // Max value should get max radius (20px)
+      expect(maxNode.radius).toBeCloseTo(20, 0);
+    });
+
+    it('uses default radius when no nodeSize encoding', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      for (const node of nodes) {
+        expect(node.radius).toBe(5);
+      }
+    });
+  });
+
+  describe('node color categorical mapping', () => {
+    it('assigns different colors to different categories', () => {
+      const encoding: GraphEncoding = {
+        nodeColor: { field: 'group', type: 'nominal' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const xNode = nodes.find((n) => n.data.group === 'X')!;
+      const yNode = nodes.find((n) => n.data.group === 'Y')!;
+      expect(xNode.fill).not.toBe(yNode.fill);
+    });
+
+    it('assigns same color to same category', () => {
+      const encoding: GraphEncoding = {
+        nodeColor: { field: 'group', type: 'nominal' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const xNodes = nodes.filter((n) => n.data.group === 'X');
+      expect(xNodes[0].fill).toBe(xNodes[1].fill);
+    });
+  });
+
+  describe('node color quantitative mapping', () => {
+    it('assigns colors on a continuous scale', () => {
+      const encoding: GraphEncoding = {
+        nodeColor: { field: 'value', type: 'quantitative' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      // Different values should produce different colors
+      const colors = new Set(nodes.map((n) => n.fill));
+      expect(colors.size).toBeGreaterThan(1);
+    });
+  });
+
+  describe('label priority', () => {
+    it('assigns higher priority to nodes with more connections', () => {
+      // Node 'a' connects to b and c (degree 2)
+      // Node 'b' connects to a and c (degree 2)
+      // Node 'c' connects to b and a (degree 2)
+      // All have same degree in this case, so let's create asymmetric edges
+      const asymmetricEdges: GraphEdge[] = [
+        { source: 'a', target: 'b' },
+        { source: 'a', target: 'c' },
+        { source: 'b', target: 'c' },
+        { source: 'a', target: 'a' }, // self-loop increases degree of 'a'
+      ];
+
+      const nodes = resolveNodeVisuals(basicNodes, {}, asymmetricEdges, theme);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!;
+      const nodeC = nodes.find((n) => n.id === 'c')!;
+
+      // Node 'a' has degree 4 (connected to b, c, plus 2 from self-loop)
+      // Node 'c' has degree 2
+      expect(nodeA.labelPriority).toBeGreaterThan(nodeC.labelPriority);
+    });
+
+    it('highest degree node gets priority 1.0', () => {
+      const hubEdges: GraphEdge[] = [
+        { source: 'a', target: 'b' },
+        { source: 'a', target: 'c' },
+      ];
+
+      const nodes = resolveNodeVisuals(basicNodes, {}, hubEdges, theme);
+
+      const hub = nodes.find((n) => n.id === 'a')!;
+      expect(hub.labelPriority).toBe(1.0);
+    });
+  });
+
+  describe('label resolution', () => {
+    it('uses nodeLabel field when provided', () => {
+      const encoding: GraphEncoding = {
+        nodeLabel: { field: 'name' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      expect(nodes.find((n) => n.id === 'a')!.label).toBe('Alice');
+      expect(nodes.find((n) => n.id === 'b')!.label).toBe('Bob');
+    });
+
+    it('falls back to node id when no nodeLabel encoding', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      expect(nodes.find((n) => n.id === 'a')!.label).toBe('a');
+      expect(nodes.find((n) => n.id === 'b')!.label).toBe('b');
+    });
+  });
+
+  describe('stroke color', () => {
+    it('stroke is darker than fill', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      for (const node of nodes) {
+        // Both fill and stroke should be valid color strings
+        expect(node.fill).toBeTruthy();
+        expect(node.stroke).toBeTruthy();
+        // Stroke should be different from fill (darkened)
+        expect(node.stroke).not.toBe(node.fill);
+      }
+    });
+  });
+
+  describe('defaults when no encoding specified', () => {
+    it('all nodes have same default radius', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      for (const node of nodes) {
+        expect(node.radius).toBe(5);
+      }
+    });
+
+    it('all nodes have same default color', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      const fills = new Set(nodes.map((n) => n.fill));
+      expect(fills.size).toBe(1);
+    });
+
+    it('stroke width defaults to 1', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      for (const node of nodes) {
+        expect(node.strokeWidth).toBe(1);
+      }
+    });
+  });
+
+  describe('data preservation', () => {
+    it('original node data is preserved in data field', () => {
+      const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!;
+      expect(nodeA.data.value).toBe(10);
+      expect(nodeA.data.group).toBe('X');
+      expect(nodeA.data.name).toBe('Alice');
+      expect(nodeA.data.id).toBe('a');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveEdgeVisuals tests
+// ---------------------------------------------------------------------------
+
+describe('resolveEdgeVisuals', () => {
+  describe('edge width scaling', () => {
+    it('produces varying widths when edgeWidth encoding is set', () => {
+      const encoding: GraphEncoding = {
+        edgeWidth: { field: 'weight', type: 'quantitative' },
+      };
+
+      const edges = resolveEdgeVisuals(basicEdges, encoding, theme);
+
+      const widths = new Set(edges.map((e) => e.strokeWidth));
+      expect(widths.size).toBeGreaterThan(1);
+    });
+
+    it('larger weight values produce thicker edges', () => {
+      const encoding: GraphEncoding = {
+        edgeWidth: { field: 'weight', type: 'quantitative' },
+      };
+
+      const edges = resolveEdgeVisuals(basicEdges, encoding, theme);
+
+      const heaviest = edges.find((e) => e.data.weight === 10)!;
+      const lightest = edges.find((e) => e.data.weight === 1)!;
+      expect(heaviest.strokeWidth).toBeGreaterThan(lightest.strokeWidth);
+    });
+
+    it('uses default width when no edgeWidth encoding', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      for (const edge of edges) {
+        expect(edge.strokeWidth).toBe(1);
+      }
+    });
+  });
+
+  describe('edge color', () => {
+    it('uses theme axis color with opacity when no encoding', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      for (const edge of edges) {
+        expect(edge.stroke).toContain('rgba');
+      }
+    });
+  });
+
+  describe('defaults', () => {
+    it('style defaults to solid', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      for (const edge of edges) {
+        expect(edge.style).toBe('solid');
+      }
+    });
+
+    it('source and target are preserved', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      expect(edges[0].source).toBe('a');
+      expect(edges[0].target).toBe('b');
+    });
+  });
+
+  describe('data preservation', () => {
+    it('original edge data is preserved', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      const firstEdge = edges[0];
+      expect(firstEdge.data.weight).toBe(1);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// darkenColor tests
+// ---------------------------------------------------------------------------
+
+describe('darkenColor', () => {
+  it('darkens a hex color', () => {
+    const original = '#ffffff';
+    const darkened = darkenColor(original, 0.2);
+
+    // White darkened by 20% should be #cccccc
+    expect(darkened).toBe('#cccccc');
+  });
+
+  it('handles 3-char hex shorthand', () => {
+    const result = darkenColor('#fff', 0.2);
+    expect(result).toBe('#cccccc');
+  });
+
+  it('returns original for invalid hex', () => {
+    expect(darkenColor('not-a-color')).toBe('not-a-color');
+  });
+});

package/src/graphs/community.ts

@@ -0,0 +1,92 @@
+/**
+ * Community assignment and color mapping for graph clustering.
+ *
+ * When a graph spec has layout.clustering.field, nodes are grouped into
+ * communities based on their data values for that field. Each community
+ * gets a color from the theme's categorical palette. Community colors
+ * override nodeColor encoding when clustering is active.
+ */
+
+import type { ResolvedTheme } from '@opendata-ai/openchart-core';
+import { darkenColor } from './encoding';
+import type { CompiledGraphNode } from './types';
+
+// ---------------------------------------------------------------------------
+// Community assignment
+// ---------------------------------------------------------------------------
+
+/**
+ * Assign community labels to compiled nodes based on a clustering field.
+ *
+ * Reads node.data[clusteringField] as the community label. If the field
+ * is missing on a node, community remains undefined.
+ *
+ * Mutates nodes in-place for efficiency (no copy needed since we just
+ * built them in the compilation pipeline).
+ */
+export function assignCommunities(
+  nodes: CompiledGraphNode[],
+  clusteringField: string | undefined,
+): void {
+  if (!clusteringField) return;
+
+  for (const node of nodes) {
+    const value = node.data[clusteringField];
+    node.community = value != null ? String(value) : undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Community color mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a map from community label to color.
+ *
+ * Collects unique community values (in order of first appearance),
+ * then assigns theme categorical colors round-robin.
+ */
+export function buildCommunityColorMap(
+  nodes: CompiledGraphNode[],
+  theme: ResolvedTheme,
+): Map<string, string> {
+  const colorMap = new Map<string, string>();
+  const palette = theme.colors.categorical;
+  let colorIndex = 0;
+
+  for (const node of nodes) {
+    if (node.community != null && !colorMap.has(node.community)) {
+      colorMap.set(node.community, palette[colorIndex % palette.length]);
+      colorIndex++;
+    }
+  }
+
+  return colorMap;
+}
+
+// ---------------------------------------------------------------------------
+// Apply community colors
+// ---------------------------------------------------------------------------
+
+/**
+ * Override node fill and stroke colors with community colors.
+ *
+ * Only affects nodes that have a community assignment. Nodes without
+ * a community keep their existing fill/stroke from encoding resolution.
+ *
+ * Mutates nodes in-place.
+ */
+export function applyCommunityColors(
+  nodes: CompiledGraphNode[],
+  colorMap: Map<string, string>,
+): void {
+  for (const node of nodes) {
+    if (node.community != null) {
+      const communityColor = colorMap.get(node.community);
+      if (communityColor) {
+        node.fill = communityColor;
+        node.stroke = darkenColor(communityColor);
+      }
+    }
+  }
+}

package/src/graphs/compile-graph.ts

@@ -0,0 +1,291 @@
+/**
+ * Graph compilation pipeline.
+ *
+ * Takes a raw graph spec (unknown shape), validates, normalizes, resolves
+ * encoding channels to visual properties, assigns communities, builds
+ * legend/tooltips/a11y, and returns a GraphCompilation.
+ *
+ * The pipeline mirrors compileChart's structure:
+ *   validate -> normalize -> resolve theme -> resolve visuals ->
+ *   community assignment -> legend -> tooltips -> a11y -> return
+ *
+ * Key difference from charts: the output does NOT include x/y positions.
+ * The force simulation in the adapter handles layout at runtime.
+ */
+
+import type {
+  CompileOptions,
+  LegendEntry,
+  LegendLayout,
+  ResolvedTheme,
+  TextStyle,
+  TooltipContent,
+  TooltipField,
+} from '@opendata-ai/openchart-core';
+import { adaptTheme, computeChrome, resolveTheme } from '@opendata-ai/openchart-core';
+
+import { compile as compileSpec } from '../compiler/index';
+import type { NormalizedGraphSpec } from '../compiler/types';
+import { applyCommunityColors, assignCommunities, buildCommunityColorMap } from './community';
+import { resolveEdgeVisuals, resolveNodeVisuals } from './encoding';
+import type { CompiledGraphNode, GraphCompilation, SimulationConfig } from './types';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const SWATCH_SIZE = 12;
+const SWATCH_GAP = 6;
+const ENTRY_GAP = 16;
+
+// ---------------------------------------------------------------------------
+// Legend builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a legend from community assignments or nodeColor encoding.
+ *
+ * Built manually instead of reusing computeLegend (which assumes chart
+ * encoding channels). Returns entries with color swatches and labels.
+ * Position is placeholder (adapter determines actual placement).
+ */
+function buildGraphLegend(
+  nodes: CompiledGraphNode[],
+  communityColorMap: Map<string, string>,
+  hasCommunities: boolean,
+  theme: ResolvedTheme,
+): LegendLayout {
+  const labelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: theme.fonts.sizes.small,
+    fontWeight: theme.fonts.weights.normal,
+    fill: theme.colors.text,
+    lineHeight: 1.3,
+  };
+
+  let entries: LegendEntry[];
+
+  if (hasCommunities && communityColorMap.size > 0) {
+    // One entry per community
+    entries = [...communityColorMap.entries()].map(([label, color]) => ({
+      label,
+      color,
+      shape: 'circle' as const,
+      active: true,
+    }));
+  } else {
+    // Collect unique colors from nodes (for nodeColor encoding)
+    const colorLabels = new Map<string, string>();
+    for (const node of nodes) {
+      if (!colorLabels.has(node.fill)) {
+        // Use the first node with this color as the label representative
+        colorLabels.set(node.fill, node.label ?? node.id);
+      }
+    }
+
+    // Only show legend if there are multiple colors
+    if (colorLabels.size <= 1) {
+      entries = [];
+    } else {
+      entries = [...colorLabels.entries()].map(([color, label]) => ({
+        label,
+        color,
+        shape: 'circle' as const,
+        active: true,
+      }));
+    }
+  }
+
+  return {
+    position: 'top',
+    entries,
+    bounds: { x: 0, y: 0, width: 0, height: 0 },
+    labelStyle,
+    swatchSize: SWATCH_SIZE,
+    swatchGap: SWATCH_GAP,
+    entryGap: ENTRY_GAP,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tooltip builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build tooltip descriptors for each node.
+ *
+ * Keyed by node id. Shows all data fields, label, and community.
+ */
+function buildGraphTooltips(nodes: CompiledGraphNode[]): Map<string, TooltipContent> {
+  const descriptors = new Map<string, TooltipContent>();
+
+  for (const node of nodes) {
+    const fields: TooltipField[] = [];
+
+    // Add community if present
+    if (node.community != null) {
+      fields.push({
+        label: 'Community',
+        value: node.community,
+        color: node.fill,
+      });
+    }
+
+    // Add all data fields (excluding id since it's the title)
+    for (const [key, value] of Object.entries(node.data)) {
+      if (key === 'id') continue;
+      if (value == null) continue;
+
+      fields.push({
+        label: key,
+        value: typeof value === 'number' ? value.toLocaleString() : String(value),
+      });
+    }
+
+    descriptors.set(node.id, {
+      title: node.label ?? node.id,
+      fields,
+    });
+  }
+
+  return descriptors;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a graph spec into a GraphCompilation.
+ *
+ * Pipeline:
+ * 1. Validate + normalize via the shared compiler pipeline
+ * 2. Resolve theme (merge spec + options, apply dark mode)
+ * 3. Resolve node visuals (size, color, label, stroke)
+ * 4. Assign communities if layout.clustering is set
+ * 5. Apply community colors (override nodeColor)
+ * 6. Resolve edge visuals (width, color)
+ * 7. Build legend from communities or nodeColor
+ * 8. Build tooltip descriptors for each node
+ * 9. Build a11y metadata
+ * 10. Build simulation config from spec layout
+ * 11. Build chrome from spec + theme
+ * 12. Return GraphCompilation
+ *
+ * @param spec - Raw graph spec (validated at runtime).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns GraphCompilation with resolved visual properties.
+ * @throws Error if spec is invalid or not a graph type.
+ */
+export function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation {
+  // 1. Validate + normalize
+  const { spec: normalized } = compileSpec(spec);
+
+  if (normalized.type !== 'graph') {
+    throw new Error(
+      `compileGraph received a ${normalized.type} spec. Use compileChart or compileTable instead.`,
+    );
+  }
+
+  const graphSpec = normalized as NormalizedGraphSpec;
+
+  // 2. Resolve theme
+  const mergedThemeConfig = options.theme
+    ? { ...graphSpec.theme, ...options.theme }
+    : graphSpec.theme;
+  let theme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  if (options.darkMode) {
+    theme = adaptTheme(theme);
+  }
+
+  // 3. Resolve node visuals
+  const compiledNodes = resolveNodeVisuals(
+    graphSpec.nodes,
+    graphSpec.encoding,
+    graphSpec.edges,
+    theme,
+  );
+
+  // 4. Assign communities
+  const clusteringField = graphSpec.layout.clustering?.field;
+  const hasCommunities = !!clusteringField;
+  assignCommunities(compiledNodes, clusteringField);
+
+  // 5. Apply community colors
+  let communityColorMap = new Map<string, string>();
+  if (hasCommunities) {
+    communityColorMap = buildCommunityColorMap(compiledNodes, theme);
+    applyCommunityColors(compiledNodes, communityColorMap);
+  }
+
+  // 6. Resolve edge visuals
+  const compiledEdges = resolveEdgeVisuals(graphSpec.edges, graphSpec.encoding, theme);
+
+  // 7. Build legend
+  const legend = buildGraphLegend(compiledNodes, communityColorMap, hasCommunities, theme);
+
+  // 8. Build tooltips
+  const tooltipDescriptors = buildGraphTooltips(compiledNodes);
+
+  // 9. Build a11y metadata
+  const communityCount = communityColorMap.size;
+  const altParts = [
+    `Network graph with ${compiledNodes.length} nodes and ${compiledEdges.length} edges`,
+  ];
+  if (communityCount > 0) {
+    altParts.push(`organized into ${communityCount} communities`);
+  }
+  const a11y = {
+    altText: altParts.join(', '),
+    dataTableFallback: compiledNodes.map((n) => [n.id, n.community ?? '', n.label ?? '']),
+    role: 'img',
+    keyboardNavigable: compiledNodes.length > 0,
+  };
+
+  // 10. Build simulation config
+  const maxRadius =
+    compiledNodes.length > 0
+      ? Math.max(...compiledNodes.map((n) => n.radius))
+      : DEFAULT_COLLISION_PADDING;
+  const simulationConfig: SimulationConfig = {
+    chargeStrength: graphSpec.layout.chargeStrength ?? -300,
+    linkDistance: graphSpec.layout.linkDistance ?? 30,
+    clustering: clusteringField ? { field: clusteringField, strength: 0.5 } : null,
+    alphaDecay: 0.0228,
+    velocityDecay: 0.4,
+    collisionRadius: maxRadius + 2,
+  };
+
+  // 11. Build chrome
+  const chrome = computeChrome(
+    {
+      title: graphSpec.chrome.title,
+      subtitle: graphSpec.chrome.subtitle,
+      source: graphSpec.chrome.source,
+      byline: graphSpec.chrome.byline,
+      footer: graphSpec.chrome.footer,
+    },
+    theme,
+    options.width,
+    options.measureText,
+  );
+
+  // 12. Return compilation
+  return {
+    nodes: compiledNodes,
+    edges: compiledEdges,
+    legend,
+    chrome,
+    tooltipDescriptors,
+    a11y,
+    theme,
+    dimensions: {
+      width: options.width,
+      height: options.height,
+    },
+    simulationConfig,
+  };
+}
+
+/** Default padding for collision radius when there are no nodes. */
+const DEFAULT_COLLISION_PADDING = 5;