@opendata-ai/openchart-engine 1.2.0

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

@@ -0,0 +1,228 @@
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { applyCommunityColors, assignCommunities, buildCommunityColorMap } from '../community';
+import type { CompiledGraphNode } from '../types';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const theme = resolveTheme({});
+
+function makeNodes(): CompiledGraphNode[] {
+  return [
+    {
+      id: 'a',
+      radius: 5,
+      fill: '#aaa',
+      stroke: '#888',
+      strokeWidth: 1,
+      label: 'A',
+      labelPriority: 0.5,
+      community: undefined,
+      data: { id: 'a', group: 'X', department: 'eng' },
+    },
+    {
+      id: 'b',
+      radius: 5,
+      fill: '#bbb',
+      stroke: '#999',
+      strokeWidth: 1,
+      label: 'B',
+      labelPriority: 0.3,
+      community: undefined,
+      data: { id: 'b', group: 'X', department: 'eng' },
+    },
+    {
+      id: 'c',
+      radius: 5,
+      fill: '#ccc',
+      stroke: '#aaa',
+      strokeWidth: 1,
+      label: 'C',
+      labelPriority: 0.8,
+      community: undefined,
+      data: { id: 'c', group: 'Y', department: 'sales' },
+    },
+    {
+      id: 'd',
+      radius: 5,
+      fill: '#ddd',
+      stroke: '#bbb',
+      strokeWidth: 1,
+      label: 'D',
+      labelPriority: 0.2,
+      community: undefined,
+      data: { id: 'd' }, // no group field
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// assignCommunities tests
+// ---------------------------------------------------------------------------
+
+describe('assignCommunities', () => {
+  it('assigns community labels from the specified field', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    expect(nodes[0].community).toBe('X');
+    expect(nodes[1].community).toBe('X');
+    expect(nodes[2].community).toBe('Y');
+  });
+
+  it('leaves community undefined when field is missing on a node', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    // Node 'd' doesn't have the 'group' field
+    expect(nodes[3].community).toBeUndefined();
+  });
+
+  it('does nothing when clusteringField is undefined', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, undefined);
+
+    for (const node of nodes) {
+      expect(node.community).toBeUndefined();
+    }
+  });
+
+  it('handles non-string field values by converting to string', () => {
+    const nodes = makeNodes();
+    // Add a numeric field value
+    nodes[0].data.numericGroup = 42;
+    assignCommunities(nodes, 'numericGroup');
+
+    expect(nodes[0].community).toBe('42');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildCommunityColorMap tests
+// ---------------------------------------------------------------------------
+
+describe('buildCommunityColorMap', () => {
+  it('creates a color for each unique community', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    expect(colorMap.size).toBe(2);
+    expect(colorMap.has('X')).toBe(true);
+    expect(colorMap.has('Y')).toBe(true);
+  });
+
+  it('uses categorical palette colors', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    const colors = [...colorMap.values()];
+    const palette = theme.colors.categorical;
+
+    // First two communities should get first two palette colors
+    expect(colors[0]).toBe(palette[0]);
+    expect(colors[1]).toBe(palette[1]);
+  });
+
+  it('returns empty map when no communities assigned', () => {
+    const nodes = makeNodes();
+    // Don't assign communities
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+
+    expect(colorMap.size).toBe(0);
+  });
+
+  it('wraps around palette when more communities than colors', () => {
+    // Create enough nodes with unique communities to exceed palette size
+    const manyNodes: CompiledGraphNode[] = [];
+    const paletteSize = theme.colors.categorical.length;
+
+    for (let i = 0; i < paletteSize + 2; i++) {
+      manyNodes.push({
+        id: `n${i}`,
+        radius: 5,
+        fill: '#ccc',
+        stroke: '#aaa',
+        strokeWidth: 1,
+        label: `Node ${i}`,
+        labelPriority: 0,
+        community: `community-${i}`,
+        data: { id: `n${i}` },
+      });
+    }
+
+    const colorMap = buildCommunityColorMap(manyNodes, theme);
+
+    expect(colorMap.size).toBe(paletteSize + 2);
+    // The (paletteSize + 1)th community should wrap to palette[0]
+    const wrappedColor = [...colorMap.values()][paletteSize];
+    expect(wrappedColor).toBe(theme.colors.categorical[0]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyCommunityColors tests
+// ---------------------------------------------------------------------------
+
+describe('applyCommunityColors', () => {
+  it('overrides node fill with community color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    const xColor = colorMap.get('X')!;
+
+    applyCommunityColors(nodes, colorMap);
+
+    expect(nodes[0].fill).toBe(xColor);
+    expect(nodes[1].fill).toBe(xColor);
+  });
+
+  it('overrides node stroke with darkened community color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    const originalStroke0 = nodes[0].stroke;
+
+    applyCommunityColors(nodes, colorMap);
+
+    // Stroke should have changed from original
+    expect(nodes[0].stroke).not.toBe(originalStroke0);
+    // Stroke should be different from fill (darkened)
+    expect(nodes[0].stroke).not.toBe(nodes[0].fill);
+  });
+
+  it('leaves nodes without communities unchanged', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const originalFill = nodes[3].fill;
+    const originalStroke = nodes[3].stroke;
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    applyCommunityColors(nodes, colorMap);
+
+    // Node 'd' has no group field, community is undefined
+    expect(nodes[3].fill).toBe(originalFill);
+    expect(nodes[3].stroke).toBe(originalStroke);
+  });
+
+  it('nodes in the same community have the same color', () => {
+    const nodes = makeNodes();
+    assignCommunities(nodes, 'group');
+
+    const colorMap = buildCommunityColorMap(nodes, theme);
+    applyCommunityColors(nodes, colorMap);
+
+    // Nodes a and b are both in community 'X'
+    expect(nodes[0].fill).toBe(nodes[1].fill);
+    expect(nodes[0].stroke).toBe(nodes[1].stroke);
+  });
+});

package/src/graphs/__tests__/compile-graph.test.ts

@@ -0,0 +1,315 @@
+import { describe, expect, it } from 'vitest';
+import { compileGraph } from '../compile-graph';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+function makeBasicGraphSpec() {
+  return {
+    type: 'graph' as const,
+    nodes: [
+      { id: 'a', group: 'X', value: 10, name: 'Alice' },
+      { id: 'b', group: 'X', value: 20, name: 'Bob' },
+      { id: 'c', group: 'Y', value: 30, name: 'Carol' },
+      { id: 'd', group: 'Y', value: 40, name: 'Dave' },
+    ],
+    edges: [
+      { source: 'a', target: 'b', weight: 1 },
+      { source: 'b', target: 'c', weight: 2 },
+      { source: 'c', target: 'd', weight: 3 },
+      { source: 'a', target: 'c', weight: 1 },
+    ],
+  };
+}
+
+function makeEncodedGraphSpec() {
+  return {
+    ...makeBasicGraphSpec(),
+    encoding: {
+      nodeSize: { field: 'value', type: 'quantitative' as const },
+      nodeColor: { field: 'group', type: 'nominal' as const },
+      nodeLabel: { field: 'name' },
+      edgeWidth: { field: 'weight', type: 'quantitative' as const },
+    },
+  };
+}
+
+function makeClusteredGraphSpec() {
+  return {
+    ...makeBasicGraphSpec(),
+    layout: {
+      type: 'force' as const,
+      clustering: { field: 'group' },
+      chargeStrength: -200,
+      linkDistance: 50,
+    },
+  };
+}
+
+const compileOptions = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Full pipeline tests
+// ---------------------------------------------------------------------------
+
+describe('compileGraph', () => {
+  it('returns a valid GraphCompilation shape', () => {
+    const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+    expect(result.nodes).toBeDefined();
+    expect(result.edges).toBeDefined();
+    expect(result.legend).toBeDefined();
+    expect(result.chrome).toBeDefined();
+    expect(result.tooltipDescriptors).toBeDefined();
+    expect(result.a11y).toBeDefined();
+    expect(result.theme).toBeDefined();
+    expect(result.dimensions).toBeDefined();
+    expect(result.simulationConfig).toBeDefined();
+  });
+
+  it('compiles correct number of nodes and edges', () => {
+    const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+    expect(result.nodes).toHaveLength(4);
+    expect(result.edges).toHaveLength(4);
+  });
+
+  it('has correct total dimensions', () => {
+    const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+    expect(result.dimensions.width).toBe(600);
+    expect(result.dimensions.height).toBe(400);
+  });
+
+  it('nodes have resolved visual properties', () => {
+    const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+    for (const node of result.nodes) {
+      expect(node.id).toBeTruthy();
+      expect(node.radius).toBeGreaterThan(0);
+      expect(node.fill).toBeTruthy();
+      expect(node.stroke).toBeTruthy();
+      expect(node.strokeWidth).toBeGreaterThan(0);
+      expect(node.data).toBeDefined();
+    }
+  });
+
+  it('edges have resolved visual properties', () => {
+    const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+    for (const edge of result.edges) {
+      expect(edge.source).toBeTruthy();
+      expect(edge.target).toBeTruthy();
+      expect(edge.stroke).toBeTruthy();
+      expect(edge.strokeWidth).toBeGreaterThan(0);
+      expect(edge.style).toBe('solid');
+      expect(edge.data).toBeDefined();
+    }
+  });
+
+  describe('with encoding', () => {
+    it('applies nodeSize encoding to produce varying radii', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const radii = result.nodes.map((n) => n.radius);
+      const uniqueRadii = new Set(radii);
+      expect(uniqueRadii.size).toBeGreaterThan(1);
+    });
+
+    it('applies nodeColor encoding to produce varying fill colors', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const groupXNode = result.nodes.find((n) => n.data.group === 'X')!;
+      const groupYNode = result.nodes.find((n) => n.data.group === 'Y')!;
+      expect(groupXNode.fill).not.toBe(groupYNode.fill);
+    });
+
+    it('applies nodeLabel encoding for labels', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const alice = result.nodes.find((n) => n.id === 'a')!;
+      expect(alice.label).toBe('Alice');
+    });
+
+    it('applies edgeWidth encoding to produce varying stroke widths', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const widths = result.edges.map((e) => e.strokeWidth);
+      const uniqueWidths = new Set(widths);
+      expect(uniqueWidths.size).toBeGreaterThan(1);
+    });
+  });
+
+  describe('with community clustering', () => {
+    it('assigns communities to nodes', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      const groupXNodes = result.nodes.filter((n) => n.community === 'X');
+      const groupYNodes = result.nodes.filter((n) => n.community === 'Y');
+      expect(groupXNodes).toHaveLength(2);
+      expect(groupYNodes).toHaveLength(2);
+    });
+
+    it('community colors override node colors', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      // Nodes in the same community should share a color
+      const xNodes = result.nodes.filter((n) => n.community === 'X');
+      expect(xNodes[0].fill).toBe(xNodes[1].fill);
+
+      // Different communities should have different colors
+      const yNode = result.nodes.find((n) => n.community === 'Y')!;
+      expect(xNodes[0].fill).not.toBe(yNode.fill);
+    });
+
+    it('legend entries match communities', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      expect(result.legend.entries).toHaveLength(2);
+      const labels = result.legend.entries.map((e) => e.label).sort();
+      expect(labels).toEqual(['X', 'Y']);
+    });
+  });
+
+  describe('tooltips', () => {
+    it('generates tooltip descriptors for each node', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.tooltipDescriptors.size).toBe(4);
+      expect(result.tooltipDescriptors.has('a')).toBe(true);
+      expect(result.tooltipDescriptors.has('b')).toBe(true);
+      expect(result.tooltipDescriptors.has('c')).toBe(true);
+      expect(result.tooltipDescriptors.has('d')).toBe(true);
+    });
+
+    it('tooltip has a title and data fields', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      const tooltip = result.tooltipDescriptors.get('a')!;
+      expect(tooltip.title).toBeTruthy();
+      expect(tooltip.fields.length).toBeGreaterThan(0);
+    });
+
+    it('tooltip includes community when clustering is active', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      const tooltip = result.tooltipDescriptors.get('a')!;
+      const communityField = tooltip.fields.find((f) => f.label === 'Community');
+      expect(communityField).toBeDefined();
+      expect(communityField!.value).toBe('X');
+    });
+  });
+
+  describe('a11y', () => {
+    it('generates descriptive alt text', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.a11y.altText).toContain('4 nodes');
+      expect(result.a11y.altText).toContain('4 edges');
+    });
+
+    it('alt text mentions communities when clustering is active', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      expect(result.a11y.altText).toContain('communities');
+    });
+
+    it('has a data table fallback', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.a11y.dataTableFallback).toHaveLength(4);
+    });
+
+    it('is keyboard navigable when nodes exist', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.a11y.keyboardNavigable).toBe(true);
+    });
+  });
+
+  describe('simulationConfig', () => {
+    it('reflects default layout parameters', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.simulationConfig.chargeStrength).toBe(-300);
+      expect(result.simulationConfig.linkDistance).toBe(30);
+      expect(result.simulationConfig.alphaDecay).toBeCloseTo(0.0228);
+      expect(result.simulationConfig.velocityDecay).toBeCloseTo(0.4);
+    });
+
+    it('reflects custom layout parameters', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      expect(result.simulationConfig.chargeStrength).toBe(-200);
+      expect(result.simulationConfig.linkDistance).toBe(50);
+    });
+
+    it('includes clustering config when set', () => {
+      const result = compileGraph(makeClusteredGraphSpec(), compileOptions);
+
+      expect(result.simulationConfig.clustering).not.toBeNull();
+      expect(result.simulationConfig.clustering!.field).toBe('group');
+    });
+
+    it('clustering is null when not set', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      expect(result.simulationConfig.clustering).toBeNull();
+    });
+
+    it('collision radius accounts for max node radius', () => {
+      const result = compileGraph(makeBasicGraphSpec(), compileOptions);
+
+      const maxRadius = Math.max(...result.nodes.map((n) => n.radius));
+      expect(result.simulationConfig.collisionRadius).toBe(maxRadius + 2);
+    });
+  });
+
+  describe('chrome', () => {
+    it('resolves chrome text elements', () => {
+      const spec = {
+        ...makeBasicGraphSpec(),
+        chrome: {
+          title: 'Network Graph',
+          source: 'Test Data',
+        },
+      };
+      const result = compileGraph(spec, compileOptions);
+
+      expect(result.chrome.title).toBeDefined();
+      expect(result.chrome.title!.text).toBe('Network Graph');
+      expect(result.chrome.source).toBeDefined();
+      expect(result.chrome.source!.text).toBe('Test Data');
+    });
+  });
+
+  describe('dark mode', () => {
+    it('applies dark mode theme when option is set', () => {
+      const result = compileGraph(makeBasicGraphSpec(), { ...compileOptions, darkMode: true });
+
+      expect(result.theme.isDark).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws for non-graph specs', () => {
+      const chartSpec = {
+        type: 'scatter' as const,
+        data: [{ x: 1, y: 2 }],
+        encoding: {
+          x: { field: 'x', type: 'quantitative' as const },
+          y: { field: 'y', type: 'quantitative' as const },
+        },
+      };
+
+      expect(() => compileGraph(chartSpec, compileOptions)).toThrow(
+        /compileGraph received a scatter spec/,
+      );
+    });
+
+    it('throws for invalid specs', () => {
+      expect(() => compileGraph({}, compileOptions)).toThrow();
+    });
+  });
+});