@opendata-ai/openchart-engine 2.0.0 → 2.2.0

package/src/charts/utils.ts

@@ -80,6 +80,54 @@ export function groupByField(data: DataRow[], field: string | undefined): Map<st
   return groups;
 }
 
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+
+/**
+ * Sort data rows by a field value in ascending order.
+ *
+ * Type-aware: numbers compared numerically, Date objects by timestamp,
+ * string-encoded numbers parsed and compared numerically, and everything
+ * else compared lexicographically (which also handles ISO date strings).
+ * Nulls are sorted last. Returns a new array (no mutation).
+ */
+export function sortByField(data: DataRow[], field: string): DataRow[] {
+  if (data.length <= 1) return [...data];
+
+  return [...data].sort((a, b) => {
+    const aVal = a[field];
+    const bVal = b[field];
+
+    // Nulls last
+    if (aVal == null && bVal == null) return 0;
+    if (aVal == null) return 1;
+    if (bVal == null) return -1;
+
+    // Both numbers
+    if (typeof aVal === 'number' && typeof bVal === 'number') {
+      return aVal - bVal;
+    }
+
+    // Both Dates
+    if (aVal instanceof Date && bVal instanceof Date) {
+      return aVal.getTime() - bVal.getTime();
+    }
+
+    // String values: try numeric parse, then lexicographic
+    const aStr = String(aVal);
+    const bStr = String(bVal);
+
+    const aNum = Number(aStr);
+    const bNum = Number(bStr);
+    if (Number.isFinite(aNum) && Number.isFinite(bNum)) {
+      return aNum - bNum;
+    }
+
+    return aStr.localeCompare(bStr);
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Color helpers
 // ---------------------------------------------------------------------------

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;
 }
 
 /**

package/src/layout/axes.ts

@@ -56,12 +56,13 @@ function continuousTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity
 function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
   const scale = resolvedScale.scale as D3CategoricalScale;
   const domain: string[] = scale.domain();
-  const maxTicks = TICK_COUNTS[density];
+  const explicitTickCount = resolvedScale.channel.axis?.tickCount;
+  const maxTicks = explicitTickCount ?? TICK_COUNTS[density];
 
-  // Band scales (bar charts) should always show all category labels.
-  // Only thin point/ordinal scales used for continuous-like axes (e.g. line charts).
+  // Band scales (bar charts) show all category labels by default.
+  // Only thin when there's an explicit tickCount override or for point/ordinal scales.
   let selectedValues = domain;
-  if (resolvedScale.type !== 'band' && domain.length > maxTicks) {
+  if ((resolvedScale.type !== 'band' || explicitTickCount) && domain.length > maxTicks) {
     const step = Math.ceil(domain.length / maxTicks);
     selectedValues = domain.filter((_: string, i: number) => i % step === 0);
   }

package/src/layout/scales.ts

@@ -367,10 +367,15 @@ export function computeScales(
   }
 
   if (encoding.y) {
-    // For stacked columns, the y-domain needs the max category sum, not max individual value.
-    // Without this, stacked bars would clip above the chart area.
+    // For stacked columns and stacked areas, the y-domain needs the max category
+    // sum, not the max individual value. Without this, stacked marks would clip
+    // above the chart area.
     let yData = data;
-    if (spec.type === 'column' && encoding.color && encoding.y.type === 'quantitative') {
+    if (
+      (spec.type === 'column' || spec.type === 'area') &&
+      encoding.color &&
+      encoding.y.type === 'quantitative'
+    ) {
       const xField = encoding.x?.field;
       const yField = encoding.y.field;
       if (xField) {