@opendata-ai/openchart-engine 6.1.5 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.1.5",
+  "version": "6.2.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.1.5",
+    "@opendata-ai/openchart-core": "6.2.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

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

@@ -141,6 +141,62 @@ describe('compileGraph', () => {
     });
   });
 
+  describe('with explicit scale domain/range', () => {
+    it('uses explicit domain and range for nominal nodeColor', () => {
+      const spec = {
+        ...makeBasicGraphSpec(),
+        encoding: {
+          nodeColor: {
+            field: 'group',
+            type: 'nominal' as const,
+            scale: {
+              domain: ['X', 'Y'],
+              range: ['#ff0000', '#00ff00'],
+            },
+          },
+        },
+      };
+      const result = compileGraph(spec, compileOptions);
+
+      const xNode = result.nodes.find((n) => n.data.group === 'X')!;
+      const yNode = result.nodes.find((n) => n.data.group === 'Y')!;
+      expect(xNode.fill).toBe('#ff0000');
+      expect(yNode.fill).toBe('#00ff00');
+    });
+
+    it('falls back to auto-derived domain when scale is omitted', () => {
+      const result = compileGraph(makeEncodedGraphSpec(), compileOptions);
+
+      const xNode = result.nodes.find((n) => n.data.group === 'X')!;
+      const yNode = result.nodes.find((n) => n.data.group === 'Y')!;
+      // Should still produce different colors (auto-derived)
+      expect(xNode.fill).not.toBe(yNode.fill);
+    });
+
+    it('explicit domain controls color ordering', () => {
+      // Reversed domain order should swap colors
+      const spec = {
+        ...makeBasicGraphSpec(),
+        encoding: {
+          nodeColor: {
+            field: 'group',
+            type: 'nominal' as const,
+            scale: {
+              domain: ['Y', 'X'],
+              range: ['#ff0000', '#00ff00'],
+            },
+          },
+        },
+      };
+      const result = compileGraph(spec, compileOptions);
+
+      const xNode = result.nodes.find((n) => n.data.group === 'X')!;
+      const yNode = result.nodes.find((n) => n.data.group === 'Y')!;
+      expect(xNode.fill).toBe('#00ff00');
+      expect(yNode.fill).toBe('#ff0000');
+    });
+  });
+
   describe('with community clustering', () => {
     it('assigns communities to nodes', () => {
       const result = compileGraph(makeClusteredGraphSpec(), compileOptions);

package/src/graphs/compile-graph.ts

@@ -54,6 +54,7 @@ function buildGraphLegend(
   communityColorMap: Map<string, string>,
   hasCommunities: boolean,
   theme: ResolvedTheme,
+  nodeColorField?: string,
 ): LegendLayout {
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
@@ -74,20 +75,24 @@ function buildGraphLegend(
       active: true,
     }));
   } else {
-    // Collect unique colors from nodes (for nodeColor encoding)
-    const colorLabels = new Map<string, string>();
+    // Build legend from nodeColor encoding: group by the color field value
+    // so each legend entry shows the categorical value (e.g. "Dataset", "bls")
+    // rather than an arbitrary node label.
+    const categoryColors = 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);
+      const category = nodeColorField
+        ? String(node.data[nodeColorField] ?? node.label ?? node.id)
+        : (node.label ?? node.id);
+      if (!categoryColors.has(category)) {
+        categoryColors.set(category, node.fill);
       }
     }
 
-    // Only show legend if there are multiple colors
-    if (colorLabels.size <= 1) {
+    // Only show legend if there are multiple categories
+    if (categoryColors.size <= 1) {
       entries = [];
     } else {
-      entries = [...colorLabels.entries()].map(([color, label]) => ({
+      entries = [...categoryColors.entries()].map(([label, color]) => ({
         label,
         color,
         shape: 'circle' as const,
@@ -207,14 +212,17 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
     graphSpec.nodeOverrides,
   );
 
-  // 4. Assign communities
+  // 4. Assign communities (for force simulation grouping)
   const clusteringField = graphSpec.layout.clustering?.field;
   const hasCommunities = !!clusteringField;
   assignCommunities(compiledNodes, clusteringField);
 
-  // 5. Apply community colors
+  // 5. Apply community colors only when no explicit nodeColor encoding is set.
+  // When the consumer specifies nodeColor (e.g. by nodeType or provider), that
+  // encoding should drive both fill colors and legend entries.
+  const hasNodeColorEncoding = !!graphSpec.encoding.nodeColor?.field;
   let communityColorMap = new Map<string, string>();
-  if (hasCommunities) {
+  if (hasCommunities && !hasNodeColorEncoding) {
     communityColorMap = buildCommunityColorMap(compiledNodes, theme);
     applyCommunityColors(compiledNodes, communityColorMap);
   }
@@ -222,8 +230,15 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
   // 6. Resolve edge visuals
   const compiledEdges = resolveEdgeVisuals(graphSpec.edges, graphSpec.encoding, theme);
 
-  // 7. Build legend
-  const legend = buildGraphLegend(compiledNodes, communityColorMap, hasCommunities, theme);
+  // 7. Build legend (use nodeColor encoding colors when present, community otherwise)
+  const useCommunitiesForLegend = hasCommunities && !hasNodeColorEncoding;
+  const legend = buildGraphLegend(
+    compiledNodes,
+    communityColorMap,
+    useCommunitiesForLegend,
+    theme,
+    graphSpec.encoding.nodeColor?.field,
+  );
 
   // 8. Build tooltips
   const tooltipDescriptors = buildGraphTooltips(compiledNodes);

package/src/graphs/encoding.ts

@@ -142,6 +142,7 @@ export function resolveNodeVisuals(
   if (encoding.nodeColor?.field) {
     const field = encoding.nodeColor.field;
     const fieldType = encoding.nodeColor.type ?? 'nominal';
+    const scaleConfig = encoding.nodeColor.scale;
 
     if (fieldType === 'quantitative') {
       const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
@@ -151,9 +152,17 @@ export function resolveNodeVisuals(
       // Use first sequential palette
       const seqPalettes = Object.values(theme.colors.sequential);
       const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
-      const colorScale = scaleLinear<string>()
-        .domain([colorMin, colorMax])
-        .range([palette[0], palette[palette.length - 1]]);
+
+      const domain =
+        scaleConfig?.domain && scaleConfig.domain.length === 2
+          ? (scaleConfig.domain as [number, number])
+          : [colorMin, colorMax];
+      const range =
+        scaleConfig?.range && scaleConfig.range.length >= 2
+          ? (scaleConfig.range as string[])
+          : [palette[0], palette[palette.length - 1]];
+
+      const colorScale = scaleLinear<string>().domain(domain).range(range);
 
       colorFn = (node: GraphNode) => {
         const val = Number(node[field]);
@@ -161,10 +170,16 @@ export function resolveNodeVisuals(
       };
     } else {
       // nominal/ordinal
-      const uniqueValues = [...new Set(nodes.map((n) => String(n[field] ?? '')))];
-      const ordinalScale = scaleOrdinal<string>()
-        .domain(uniqueValues)
-        .range(theme.colors.categorical);
+      const domain =
+        scaleConfig?.domain && Array.isArray(scaleConfig.domain)
+          ? (scaleConfig.domain as string[])
+          : [...new Set(nodes.map((n) => String(n[field] ?? '')))];
+      const range =
+        scaleConfig?.range && scaleConfig.range.length > 0
+          ? (scaleConfig.range as string[])
+          : theme.colors.categorical;
+
+      const ordinalScale = scaleOrdinal<string>().domain(domain).range(range);
 
       colorFn = (node: GraphNode) => ordinalScale(String(node[field] ?? ''));
     }
@@ -259,6 +274,7 @@ export function resolveEdgeVisuals(
   if (encoding.edgeColor?.field) {
     const field = encoding.edgeColor.field;
     const fieldType = encoding.edgeColor.type ?? 'nominal';
+    const scaleConfig = encoding.edgeColor.scale;
 
     if (fieldType === 'quantitative') {
       const values = edges.map((e) => Number(e[field])).filter((v) => Number.isFinite(v));
@@ -267,19 +283,33 @@ export function resolveEdgeVisuals(
 
       const seqPalettes = Object.values(theme.colors.sequential);
       const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
-      const colorScale = scaleLinear<string>()
-        .domain([colorMin, colorMax])
-        .range([palette[0], palette[palette.length - 1]]);
+
+      const domain =
+        scaleConfig?.domain && scaleConfig.domain.length === 2
+          ? (scaleConfig.domain as [number, number])
+          : [colorMin, colorMax];
+      const range =
+        scaleConfig?.range && scaleConfig.range.length >= 2
+          ? (scaleConfig.range as string[])
+          : [palette[0], palette[palette.length - 1]];
+
+      const colorScale = scaleLinear<string>().domain(domain).range(range);
 
       edgeColorFn = (edge: GraphEdge) => {
         const val = Number(edge[field]);
         return Number.isFinite(val) ? colorScale(val) : hexWithOpacity(theme.colors.axis, 0.4);
       };
     } else {
-      const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? '')))];
-      const ordinalScale = scaleOrdinal<string>()
-        .domain(uniqueValues)
-        .range(theme.colors.categorical);
+      const domain =
+        scaleConfig?.domain && Array.isArray(scaleConfig.domain)
+          ? (scaleConfig.domain as string[])
+          : [...new Set(edges.map((e) => String(e[field] ?? '')))];
+      const range =
+        scaleConfig?.range && scaleConfig.range.length > 0
+          ? (scaleConfig.range as string[])
+          : theme.colors.categorical;
+
+      const ordinalScale = scaleOrdinal<string>().domain(domain).range(range);
 
       edgeColorFn = (edge: GraphEdge) => ordinalScale(String(edge[field] ?? ''));
     }