@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

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

@@ -0,0 +1,415 @@
+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 (12px)
+      expect(maxNode.radius).toBeCloseTo(12, 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');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// nodeOverrides tests
+// ---------------------------------------------------------------------------
+
+describe('nodeOverrides', () => {
+  it('overrides fill color for a specific node', () => {
+    const overrides = { a: { fill: '#ff0000' } };
+    const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme, overrides);
+
+    const nodeA = nodes.find((n) => n.id === 'a')!;
+    expect(nodeA.fill).toBe('#ff0000');
+
+    // Other nodes should not be affected
+    const nodeB = nodes.find((n) => n.id === 'b')!;
+    expect(nodeB.fill).not.toBe('#ff0000');
+  });
+
+  it('overrides radius for a specific node', () => {
+    const overrides = { b: { radius: 15 } };
+    const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme, overrides);
+
+    const nodeB = nodes.find((n) => n.id === 'b')!;
+    expect(nodeB.radius).toBe(15);
+  });
+
+  it('overrides strokeWidth and stroke', () => {
+    const overrides = { c: { strokeWidth: 3, stroke: '#00ff00' } };
+    const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme, overrides);
+
+    const nodeC = nodes.find((n) => n.id === 'c')!;
+    expect(nodeC.strokeWidth).toBe(3);
+    expect(nodeC.stroke).toBe('#00ff00');
+  });
+
+  it('alwaysShowLabel sets labelPriority to Infinity', () => {
+    const overrides = { a: { alwaysShowLabel: true } };
+    const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme, overrides);
+
+    const nodeA = nodes.find((n) => n.id === 'a')!;
+    expect(nodeA.labelPriority).toBe(Infinity);
+  });
+
+  it('does not affect nodes without overrides', () => {
+    const overrides = { a: { fill: '#ff0000', radius: 25 } };
+    const nodes = resolveNodeVisuals(basicNodes, {}, basicEdges, theme, overrides);
+
+    const nodeB = nodes.find((n) => n.id === 'b')!;
+    const nodeC = nodes.find((n) => n.id === 'c')!;
+    // Default radius
+    expect(nodeB.radius).toBe(5);
+    expect(nodeC.radius).toBe(5);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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('edge style mapping', () => {
+    it('maps field values to solid/dashed/dotted via ordinal mapping', () => {
+      const styledEdges: GraphEdge[] = [
+        { source: 'a', target: 'b', kind: 'friend' },
+        { source: 'b', target: 'c', kind: 'colleague' },
+        { source: 'a', target: 'c', kind: 'family' },
+      ];
+      const encoding: GraphEncoding = {
+        edgeStyle: { field: 'kind' },
+      };
+
+      const edges = resolveEdgeVisuals(styledEdges, encoding, theme);
+
+      // Three unique values should map to solid, dashed, dotted
+      const styles = edges.map((e) => e.style);
+      expect(styles).toContain('solid');
+      expect(styles).toContain('dashed');
+      expect(styles).toContain('dotted');
+    });
+
+    it('wraps around when more unique values than style options', () => {
+      const styledEdges: GraphEdge[] = [
+        { source: 'a', target: 'b', kind: 'one' },
+        { source: 'b', target: 'c', kind: 'two' },
+        { source: 'a', target: 'c', kind: 'three' },
+        { source: 'a', target: 'b', kind: 'four' },
+      ];
+      const encoding: GraphEncoding = {
+        edgeStyle: { field: 'kind' },
+      };
+
+      const edges = resolveEdgeVisuals(styledEdges, encoding, theme);
+
+      // 4th unique value wraps back to 'solid'
+      const fourthEdge = edges.find((e) => e.data.kind === 'four')!;
+      expect(fourthEdge.style).toBe('solid');
+    });
+
+    it('defaults to solid when no edgeStyle encoding', () => {
+      const edges = resolveEdgeVisuals(basicEdges, {}, theme);
+
+      for (const edge of edges) {
+        expect(edge.style).toBe('solid');
+      }
+    });
+  });
+
+  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);
+      }
+    }
+  }
+}