@opendata-ai/openchart-engine 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "2.1.0",
+  "version": "2.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": "2.1.0",
+    "@opendata-ai/openchart-core": "2.2.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -66,6 +66,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }
 
@@ -92,6 +93,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }
 
@@ -120,5 +122,6 @@ export function makeScatterSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }

package/src/__tests__/compile-chart.test.ts

@@ -260,6 +260,129 @@ describe('compileChart', () => {
       ),
     ).toThrow('compileTable');
   });
+
+  // ---------------------------------------------------------------------------
+  // hiddenSeries
+  // ---------------------------------------------------------------------------
+
+  it('hiddenSeries filters out data for hidden series from marks', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: ['UK'],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // With UK hidden, only US marks should be present.
+    // Line marks carry a series property.
+    const lineMarks = layout.marks.filter((m) => m.type === 'line');
+    for (const mark of lineMarks) {
+      if (mark.type === 'line') {
+        expect(mark.series).not.toBe('UK');
+      }
+    }
+
+    // Legend should still have entries for both series (hidden ones are dimmed, not removed)
+    expect(layout.legend.entries.length).toBe(2);
+    expect(layout.legend.entries.some((e) => e.label === 'US')).toBe(true);
+    expect(layout.legend.entries.some((e) => e.label === 'UK')).toBe(true);
+  });
+
+  it('hiddenSeries with all series hidden produces no marks', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: ['US', 'UK'],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    // No data left means no marks
+    expect(layout.marks.length).toBe(0);
+  });
+
+  it('hiddenSeries with empty array behaves normally', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: [],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.marks.length).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // scale.clip
+  // ---------------------------------------------------------------------------
+
+  it('scale.clip filters data rows outside the y-axis domain', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 5 },
+        { x: 2, y: 15 },
+        { x: 3, y: 25 },
+        { x: 4, y: 35 },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' as const },
+        y: {
+          field: 'y',
+          type: 'quantitative' as const,
+          scale: { domain: [10, 30] as [number, number], clip: true },
+        },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // Only y=15 and y=25 should remain (y=5 and y=35 are outside [10,30])
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(2);
+  });
+
+  it('scale.clip filters data rows outside the x-axis domain', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 10 },
+        { x: 5, y: 20 },
+        { x: 10, y: 30 },
+        { x: 15, y: 40 },
+      ],
+      encoding: {
+        x: {
+          field: 'x',
+          type: 'quantitative' as const,
+          scale: { domain: [3, 12] as [number, number], clip: true },
+        },
+        y: { field: 'y', type: 'quantitative' as const },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // Only x=5 and x=10 should remain
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(2);
+  });
+
+  it('scale.clip=false does not filter data even with domain set', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 5 },
+        { x: 2, y: 15 },
+        { x: 3, y: 25 },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' as const },
+        y: {
+          field: 'y',
+          type: 'quantitative' as const,
+          scale: { domain: [10, 20] as [number, number], clip: false },
+        },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // All 3 points should still be present (clip is false)
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(3);
+  });
 });
 
 describe('compileTable', () => {

package/src/compile.ts

@@ -209,8 +209,37 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
   const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea);
 
+  // Apply data filtering after legend (so legend retains all series), but before
+  // scale computation (so hidden/clipped data doesn't affect domains or marks).
+  let renderData = chartSpec.data;
+
+  // Filter hidden series: removed from rendering but kept in legend (dimmed in the adapter)
+  if (chartSpec.hiddenSeries.length > 0 && chartSpec.encoding.color) {
+    const colorField = chartSpec.encoding.color.field;
+    const hiddenSet = new Set(chartSpec.hiddenSeries);
+    renderData = renderData.filter((row) => !hiddenSet.has(String(row[colorField])));
+  }
+
+  // Filter clipped scale domains: when scale.clip is true, exclude rows outside the domain
+  for (const channel of ['x', 'y'] as const) {
+    const enc = chartSpec.encoding[channel];
+    if (!enc?.scale?.clip || !enc.scale.domain) continue;
+    const domain = enc.scale.domain;
+    const field = enc.field;
+    if (Array.isArray(domain) && domain.length === 2 && typeof domain[0] === 'number') {
+      const [lo, hi] = domain as [number, number];
+      renderData = renderData.filter((row) => {
+        const v = Number(row[field]);
+        return Number.isFinite(v) && v >= lo && v <= hi;
+      });
+    }
+  }
+
+  // Build a filtered spec for scales and marks, keeping all other properties intact
+  const renderSpec = renderData !== chartSpec.data ? { ...chartSpec, data: renderData } : chartSpec;
+
   // Compute scales
-  const scales = computeScales(chartSpec, chartArea, chartSpec.data);
+  const scales = computeScales(renderSpec, chartArea, renderSpec.data);
 
   // Update color scale to use theme palette
   if (scales.color) {
@@ -244,9 +273,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     computeGridlines(axes, chartArea);
   }
 
-  // Get chart renderer and compute marks
-  const renderer = getChartRenderer(chartSpec.type);
-  const marks: Mark[] = renderer ? renderer(chartSpec, scales, chartArea, strategy, theme) : [];
+  // Get chart renderer and compute marks (using filtered data)
+  const renderer = getChartRenderer(renderSpec.type);
+  const marks: Mark[] = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme) : [];
 
   // Compute annotations from spec, passing legend + mark bounds as obstacles for collision avoidance
   const obstacles: Rect[] = [];

package/src/compiler/normalize.ts

@@ -196,6 +196,7 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     responsive: spec.responsive ?? true,
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
+    hiddenSeries: spec.hiddenSeries ?? [],
   };
 }
 
@@ -236,6 +237,7 @@ function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGra
     edges: spec.edges,
     encoding: spec.encoding ?? {},
     layout,
+    nodeOverrides: spec.nodeOverrides,
     chrome: normalizeChrome(spec.chrome),
     annotations: normalizeAnnotations(spec.annotations),
     theme: spec.theme ?? {},

package/src/compiler/types.ts

@@ -22,6 +22,7 @@ import type {
   GraphSpec,
   LabelConfig,
   LegendConfig,
+  NodeOverride,
   ScaleConfig,
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
@@ -70,6 +71,8 @@ export interface NormalizedChartSpec {
   responsive: boolean;
   theme: ThemeConfig;
   darkMode: DarkMode;
+  /** Series names to hide from rendering. */
+  hiddenSeries: string[];
 }
 
 /** A TableSpec with all optional fields filled with sensible defaults. */
@@ -95,6 +98,7 @@ export interface NormalizedGraphSpec {
   edges: GraphSpec['edges'];
   encoding: GraphEncoding;
   layout: GraphLayoutConfig;
+  nodeOverrides?: Record<string, NodeOverride>;
   chrome: NormalizedChrome;
   annotations: Annotation[];
   theme: ThemeConfig;

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

@@ -215,6 +215,60 @@ describe('resolveNodeVisuals', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// 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
 // ---------------------------------------------------------------------------
@@ -280,6 +334,53 @@ describe('resolveEdgeVisuals', () => {
     });
   });
 
+  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);

package/src/graphs/compile-graph.ts

@@ -204,6 +204,7 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
     graphSpec.encoding,
     graphSpec.edges,
     theme,
+    graphSpec.nodeOverrides,
   );
 
   // 4. Assign communities
@@ -243,6 +244,7 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
   };
 
   // 10. Build simulation config
+  const collisionPadding = graphSpec.layout.collisionPadding ?? 2;
   const maxRadius =
     compiledNodes.length > 0
       ? Math.max(...compiledNodes.map((n) => n.radius))
@@ -253,7 +255,10 @@ export function compileGraph(spec: unknown, options: CompileOptions): GraphCompi
     clustering: clusteringField ? { field: clusteringField, strength: 0.5 } : null,
     alphaDecay: 0.0228,
     velocityDecay: 0.4,
-    collisionRadius: maxRadius + 2,
+    collisionRadius: maxRadius + collisionPadding,
+    collisionPadding,
+    linkStrength: graphSpec.layout.linkStrength,
+    centerForce: graphSpec.layout.centerForce,
   };
 
   // 11. Build chrome

package/src/graphs/encoding.ts

@@ -11,6 +11,7 @@ import type {
   GraphEdge,
   GraphEncoding,
   GraphNode,
+  NodeOverride,
   ResolvedTheme,
 } from '@opendata-ai/openchart-core';
 import { max, min } from 'd3-array';
@@ -119,6 +120,7 @@ export function resolveNodeVisuals(
   encoding: GraphEncoding,
   edges: GraphEdge[],
   theme: ResolvedTheme,
+  nodeOverrides?: Record<string, NodeOverride>,
 ): CompiledGraphNode[] {
   const degrees = computeDegrees(nodes, edges);
   const maxDegree = Math.max(1, ...degrees.values());
@@ -203,14 +205,22 @@ export function resolveNodeVisuals(
     const { id: _id, ...rest } = node;
     const data: Record<string, unknown> = { id: node.id, ...rest };
 
+    // Apply per-node overrides if present
+    const override = nodeOverrides?.[node.id];
+    const finalFill = override?.fill ?? fill;
+    const finalRadius = override?.radius ?? radius;
+    const finalStrokeWidth = override?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+    const finalStroke = override?.stroke ?? stroke;
+    const finalLabelPriority = override?.alwaysShowLabel ? Infinity : labelPriority;
+
     return {
       id: node.id,
-      radius,
-      fill,
-      stroke,
-      strokeWidth: DEFAULT_STROKE_WIDTH,
+      radius: finalRadius,
+      fill: finalFill,
+      stroke: finalStroke,
+      strokeWidth: finalStrokeWidth,
       label,
-      labelPriority,
+      labelPriority: finalLabelPriority,
       community: undefined,
       data,
     };
@@ -277,6 +287,19 @@ export function resolveEdgeVisuals(
 
   const defaultEdgeColor = hexWithOpacity(theme.colors.axis, 0.4);
 
+  // Edge style mapping (ordinal: map unique field values to solid/dashed/dotted)
+  const EDGE_STYLES: Array<'solid' | 'dashed' | 'dotted'> = ['solid', 'dashed', 'dotted'];
+  let styleFn: ((edge: GraphEdge) => 'solid' | 'dashed' | 'dotted') | undefined;
+  if (encoding.edgeStyle?.field) {
+    const field = encoding.edgeStyle.field;
+    const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? '')))];
+    const styleMap = new Map<string, 'solid' | 'dashed' | 'dotted'>();
+    for (let i = 0; i < uniqueValues.length; i++) {
+      styleMap.set(uniqueValues[i], EDGE_STYLES[i % EDGE_STYLES.length]);
+    }
+    styleFn = (edge: GraphEdge) => styleMap.get(String(edge[field] ?? '')) ?? 'solid';
+  }
+
   return edges.map((edge) => {
     const { source, target, ...rest } = edge;
 
@@ -289,13 +312,14 @@ export function resolveEdgeVisuals(
     }
 
     const stroke = edgeColorFn ? edgeColorFn(edge) : defaultEdgeColor;
+    const style = styleFn ? styleFn(edge) : ('solid' as const);
 
     return {
       source,
       target,
       stroke,
       strokeWidth,
-      style: 'solid' as const,
+      style,
       data: { source, target, ...rest } as Record<string, unknown>,
     };
   });

package/src/graphs/types.ts

@@ -67,6 +67,12 @@ export interface SimulationConfig {
   velocityDecay: number;
   /** Collision radius: max node radius + padding. */
   collisionRadius: number;
+  /** Extra px added to node radius for collision (default 2). */
+  collisionPadding?: number;
+  /** Link force strength override. */
+  linkStrength?: number;
+  /** Whether to apply center force (default true). */
+  centerForce?: boolean;
 }
 
 /**