@opendata-ai/openchart-engine 6.24.2 → 6.25.0

package/src/compile.ts

@@ -19,6 +19,8 @@ import type {
   ChartSpec,
   CompileOptions,
   CompileTableOptions,
+  DataRow,
+  Encoding,
   EncodingChannel,
   LayerSpec,
   Mark,
@@ -33,6 +35,7 @@ import type {
 import {
   adaptTheme,
   computeLabelBounds,
+  estimateTextWidth,
   generateAltText,
   generateDataTable,
   getBreakpoint,
@@ -40,6 +43,8 @@ import {
   getLayoutStrategy,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
+import { scaleLinear } from 'd3-scale';
+import { curveMonotoneX, area as d3area, line as d3line } from 'd3-shape';
 import { computeAnnotations } from './annotations/compute';
 // Side-effect import: registers all built-in chart renderers with the
 // registry on module load. Tests that clear the registry can import
@@ -338,8 +343,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   // INVARIANT 3 — post-hoc defaultColor: must run AFTER computeScales since resolution needs
   // theme context. Do not move into computeScales (would require threading theme through).
-  // If the user set a fill on the mark def, it takes priority over the theme's first categorical.
-  scales.defaultColor = chartSpec.markDef.fill ?? theme.colors.categorical[0];
+  // fill wins for bar/area/arc marks; stroke wins for line marks (the stroke IS the color).
+  scales.defaultColor =
+    chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
 
   // Arc charts (pie/donut) don't use axes or gridlines
   const isRadial = chartSpec.markType === 'arc';
@@ -473,13 +479,15 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
     return compileChart(singleSpec, options);
   }
 
-  // Build primary spec with unioned data for shared scale computation.
-  // The primary layout provides chrome, axes, dimensions, legend, and a11y.
+  // Branch: independent y-scales produce dual-axis layout
+  if (spec.resolve?.scale?.y === 'independent') {
+    return compileLayerIndependent(leaves, spec, options);
+  }
+
+  // Shared scales (default): union data and compile together
   const primarySpec = buildPrimarySpec(leaves, spec);
   const primaryLayout = compileChart(primarySpec, options);
 
-  // Compile each leaf layer independently but with the full unioned data
-  // so they all share the same scale domains.
   const allMarks: Mark[] = [];
   const seenLabels = new Set<string>();
   const mergedLegendEntries = [...primaryLayout.legend.entries];
@@ -488,14 +496,10 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
   }
 
   for (const leaf of leaves) {
-    // Compile each leaf with its own data so marks correspond to its rows only.
-    // Scale domains may differ slightly between layers, but this prevents
-    // duplicate marks from feeding unioned data into every renderer.
     const leafLayout = compileChart(leaf as unknown, options);
 
     allMarks.push(...leafLayout.marks);
 
-    // Deduplicate legend entries across layers
     for (const entry of leafLayout.legend.entries) {
       if (!seenLabels.has(entry.label)) {
         seenLabels.add(entry.label);
@@ -514,6 +518,434 @@ export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLay
   };
 }
 
+// ---------------------------------------------------------------------------
+// Independent y-scale compilation (dual-axis charts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate the pixel width needed for a right-side y-axis based on data values.
+ * Mirrors the left-margin estimation logic in computeDimensions.
+ */
+function estimateYAxisLabelWidth(
+  data: DataRow[],
+  encoding: Encoding | undefined,
+  baseFontSize: number,
+): number {
+  if (!encoding?.y) return 40;
+  const yEnc = encoding.y;
+  const yField = yEnc.field;
+  if (!yField) return 40;
+
+  const yType = yEnc.type;
+  if (yType === 'nominal' || yType === 'ordinal') {
+    let maxWidth = 0;
+    for (const row of data) {
+      const label = String(row[yField] ?? '');
+      const w = estimateTextWidth(label, baseFontSize, 400);
+      if (w > maxWidth) maxWidth = w;
+    }
+    return maxWidth > 0 ? maxWidth + 10 : 40;
+  }
+
+  // Quantitative/temporal: estimate from the largest value
+  let maxAbsVal = 0;
+  for (const row of data) {
+    const v = Number(row[yField]);
+    if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
+  }
+  let sampleLabel: string;
+  if (maxAbsVal >= 1_000_000_000) sampleLabel = '1.5B';
+  else if (maxAbsVal >= 1_000_000) sampleLabel = '1.5M';
+  else if (maxAbsVal >= 1_000) sampleLabel = '1.5K';
+  else if (maxAbsVal >= 100) sampleLabel = '100';
+  else if (maxAbsVal >= 10) sampleLabel = '10';
+  else sampleLabel = '0.0';
+  const hasNeg = data.some((r) => Number(r[yField]) < 0);
+  const labelEst = (hasNeg ? '-' : '') + sampleLabel;
+  return estimateTextWidth(labelEst, baseFontSize, 400) + 10;
+}
+
+/**
+ * Compile a LayerSpec with independent y-scales (dual-axis chart).
+ *
+ * Layer 0 gets the left y-axis, layer 1 gets the right y-axis.
+ * Both layers share the x-axis. Limited to exactly 2 layers.
+ */
+function compileLayerIndependent(
+  leaves: ChartSpec[],
+  layerSpec: LayerSpec,
+  options: CompileOptions,
+): ChartLayout {
+  if (leaves.length > 2) {
+    throw new Error(
+      'Independent y-scales support at most 2 layers (left and right y-axis). ' +
+        `Got ${leaves.length} layers.`,
+    );
+  }
+
+  const leaf0 = leaves[0];
+  const leaf1 = leaves[1];
+
+  // Validate x-field types are compatible
+  const xType0 = leaf0.encoding?.x?.type;
+  const xType1 = leaf1.encoding?.x?.type;
+  if (xType0 && xType1 && xType0 !== xType1) {
+    throw new Error(
+      `Dual-axis charts require matching x-field types across layers. ` +
+        `Layer 0 has '${xType0}', layer 1 has '${xType1}'.`,
+    );
+  }
+
+  // Estimate right-axis label width to reserve margin space
+  const theme = resolveTheme(layerSpec.theme ?? leaf1.theme);
+  const axisFontSize = theme.fonts?.sizes?.axisTick ?? 11;
+  const rightAxisWidth = estimateYAxisLabelWidth(leaf1.data, leaf1.encoding, axisFontSize);
+  // Add space for the rotated axis title if present (match left-axis 45px clearance)
+  const hasRightAxisTitle = !!leaf1.encoding?.y?.axis?.title;
+  const rightReserve = rightAxisWidth + (hasRightAxisTitle ? 45 : 0);
+
+  const optionsWithReserve: CompileOptions = {
+    ...options,
+    rightAxisReserve: rightReserve,
+  };
+
+  // Union x-data so both layers see the full x-domain.
+  // Each layer keeps its own y-data for independent y-scales.
+  const xField0 = leaf0.encoding?.x?.field;
+  const xField1 = leaf1.encoding?.x?.field;
+  const unionXValues = new Set<unknown>();
+  if (xField0) for (const row of leaf0.data) unionXValues.add(row[xField0]);
+  if (xField1) for (const row of leaf1.data) unionXValues.add(row[xField1]);
+
+  // Add missing x-values from leaf1 into leaf0's data as stub rows,
+  // and vice versa, so both scales see the full x-domain.
+  let leaf0WithUnionX = ensureXDomainCoverage(leaf0, xField0, unionXValues);
+  let leaf1WithUnionX = ensureXDomainCoverage(leaf1, xField1, unionXValues);
+
+  // Align y-domains so zero maps to the same pixel position on both axes
+  const aligned = alignYDomains(leaf0WithUnionX, leaf1WithUnionX);
+  if (aligned) {
+    leaf0WithUnionX = withYDomain(leaf0WithUnionX, aligned.domain0);
+    leaf1WithUnionX = withYDomain(leaf1WithUnionX, aligned.domain1);
+  }
+
+  // Compile layer 0 as the primary layout (chrome, x-axis, left y-axis)
+  const primary0 = buildPrimarySpec([leaf0WithUnionX], layerSpec);
+  const layout0 = compileChart(primary0, optionsWithReserve);
+
+  // Compile layer 1 independently for its own y-axis and marks.
+  // Keep chrome identical to layer 0 so both compile against the same chart area dimensions.
+  // layout1's chrome is never rendered -- we spread layout0 into the final return value.
+  const primary1 = buildPrimarySpec([leaf1WithUnionX], layerSpec);
+  primary1.annotations = [];
+  const layout1 = compileChart(primary1, optionsWithReserve);
+
+  // Extract layer 1's y-axis, reposition it to the right side
+  const y2Axis = layout1.axes.y
+    ? {
+        ...layout1.axes.y,
+        orient: 'right' as const,
+        gridlines: [], // Only left y-axis produces gridlines
+        start: {
+          x: layout0.area.x + layout0.area.width,
+          y: layout0.area.y,
+        },
+        end: {
+          x: layout0.area.x + layout0.area.width,
+          y: layout0.area.y + layout0.area.height,
+        },
+      }
+    : undefined;
+
+  // Build a per-category x-position map from whichever layer uses a band scale (bars).
+  // Band-scale tick positions are band centers -- the canonical x positions that both
+  // layers should align to. Line/area marks use a point scale and land at different pixels.
+  // We remap line/area mark x-coordinates by looking up each data row's x-field value
+  // in the band-center map, replacing point-scale positions with exact band centers.
+  const layer0HasBars = layout0.marks.some((m) => m.type === 'rect');
+  const layer1HasBars = layout1.marks.some((m) => m.type === 'rect');
+
+  // Build category → band-center-pixel map from the bar layer's x-axis ticks
+  const bandCenterByCategory = new Map<string, number>();
+  if (layer0HasBars && layout0.axes.x?.ticks) {
+    for (const tick of layout0.axes.x.ticks) {
+      bandCenterByCategory.set(String(tick.label), tick.position);
+    }
+  } else if (layer1HasBars && layout1.axes.x?.ticks) {
+    for (const tick of layout1.axes.x.ticks) {
+      bandCenterByCategory.set(String(tick.label), tick.position);
+    }
+  }
+
+  // Remap line/area/point mark x-coordinates to band centers using data rows.
+  // The SVG path strings are kept as-is (the smooth curve is close enough to correct
+  // after a small x-shift). Only the discrete coordinate arrays and dot positions
+  // are remapped so tooltips and point markers land on bar centers.
+  const remapMarkX = (xField: string | undefined, mark: Mark): Mark => {
+    if (!xField || bandCenterByCategory.size === 0) return mark;
+    if (mark.type === 'line') {
+      const newPoints = mark.points.map((p, i) => {
+        const bx = bandCenterByCategory.get(String(mark.data[i]?.[xField] ?? ''));
+        return bx !== undefined ? { ...p, x: bx } : p;
+      });
+      const newDataPoints = mark.dataPoints?.map((dp, i) => {
+        const bx = bandCenterByCategory.get(String(mark.data[i]?.[xField] ?? ''));
+        return bx !== undefined ? { ...dp, x: bx } : dp;
+      });
+      // Regenerate the smooth monotone path from remapped points so the rendered
+      // line passes through bar centers with the same curve quality as the original.
+      // Uses curveMonotoneX regardless of the original interpolation -- preserving the
+      // user-specified curve across x-remapping would require re-resolving the mark's
+      // interpolation setting, which isn't stored on LineMark post-compilation.
+      const newPath =
+        d3line<{ x: number; y: number }>()
+          .x((p) => p.x)
+          .y((p) => p.y)
+          .curve(curveMonotoneX)(newPoints) ?? undefined;
+      return { ...mark, points: newPoints, dataPoints: newDataPoints, path: newPath };
+    }
+    if (mark.type === 'area') {
+      const newTopPoints = mark.topPoints.map((p, i) => {
+        const bx = bandCenterByCategory.get(String(mark.data[i]?.[xField] ?? ''));
+        return bx !== undefined ? { ...p, x: bx } : p;
+      });
+      const newBottomPoints = mark.bottomPoints.map((p, i) => {
+        const bx = bandCenterByCategory.get(String(mark.data[i]?.[xField] ?? ''));
+        return bx !== undefined ? { ...p, x: bx } : p;
+      });
+      const newDataPoints = mark.dataPoints?.map((dp, i) => {
+        const bx = bandCenterByCategory.get(String(mark.data[i]?.[xField] ?? ''));
+        return bx !== undefined ? { ...dp, x: bx } : dp;
+      });
+      // Regenerate area fill path and top-line stroke path from remapped points.
+      const areaGen = d3area<{ x: number; yTop: number; yBottom: number }>()
+        .x((p) => p.x)
+        .y0((p) => p.yBottom)
+        .y1((p) => p.yTop)
+        .curve(curveMonotoneX);
+      const topLineGen = d3line<{ x: number; yTop: number }>()
+        .x((p) => p.x)
+        .y((p) => p.yTop)
+        .curve(curveMonotoneX);
+      const combined = newTopPoints.map((tp, i) => ({
+        x: tp.x,
+        yTop: tp.y,
+        yBottom: newBottomPoints[i]?.y ?? tp.y,
+      }));
+      const newPath = areaGen(combined) ?? '';
+      const newTopPath = topLineGen(combined) ?? '';
+      return {
+        ...mark,
+        topPoints: newTopPoints,
+        bottomPoints: newBottomPoints,
+        dataPoints: newDataPoints,
+        path: newPath,
+        topPath: newTopPath,
+      };
+    }
+    if (mark.type === 'point') {
+      const bx = bandCenterByCategory.get(String(mark.data[xField] ?? ''));
+      return bx !== undefined ? { ...mark, cx: bx } : mark;
+    }
+    return mark;
+  };
+
+  // Apply remapping to whichever layer has line/area marks (point scale)
+  const adjustedMarks0 =
+    bandCenterByCategory.size > 0 && !layer0HasBars
+      ? layout0.marks.map((m) => remapMarkX(xField0, m))
+      : layout0.marks;
+
+  // Tag layer 1 marks with yScale: 'y2' and remap x if needed
+  const taggedMarks1 = layout1.marks.map((mark) => {
+    const tagged = { ...mark, yScale: 'y2' as const };
+    if (bandCenterByCategory.size > 0 && !layer1HasBars) {
+      return remapMarkX(xField1, tagged) as typeof tagged;
+    }
+    return tagged;
+  });
+
+  // Merge legend entries with deduplication
+  const seenLabels = new Set<string>();
+  const mergedLegendEntries = [...layout0.legend.entries];
+  for (const entry of mergedLegendEntries) seenLabels.add(entry.label);
+  for (const entry of layout1.legend.entries) {
+    if (!seenLabels.has(entry.label)) {
+      seenLabels.add(entry.label);
+      mergedLegendEntries.push(entry);
+    }
+  }
+
+  // Merge tooltip descriptors. Layer 1 marks are appended after layer 0's marks,
+  // so their render indices start at layout0.marks.length. The descriptor keys
+  // for discrete marks (rect, point, arc) are "type-${index}" where index is the
+  // mark's position in the final combined array. Re-key them with the correct offset.
+  const l0Count = layout0.marks.length;
+  const mergedTooltips = new Map(layout0.tooltipDescriptors);
+  for (const [key, value] of layout1.tooltipDescriptors) {
+    const match = /^(rect|point|arc)-(\d+)$/.exec(key);
+    if (match) {
+      const offsetKey = `${match[1]}-${Number(match[2]) + l0Count}`;
+      mergedTooltips.set(offsetKey, value);
+    } else {
+      // Line/area tooltips are keyed by series name, not index -- pass through as-is
+      mergedTooltips.set(key, value);
+    }
+  }
+
+  return {
+    ...layout0,
+    axes: {
+      x: layout0.axes.x,
+      y: layout0.axes.y,
+      y2: y2Axis,
+    },
+    marks: [...adjustedMarks0, ...taggedMarks1],
+    legend: {
+      ...layout0.legend,
+      entries: mergedLegendEntries,
+    },
+    tooltipDescriptors: mergedTooltips,
+  };
+}
+
+/**
+ * Ensure a leaf's data covers the full x-domain by adding stub rows for
+ * missing x-values. This keeps scales consistent across layers without
+ * injecting scale.domain directly.
+ */
+function ensureXDomainCoverage(
+  leaf: ChartSpec,
+  xField: string | undefined,
+  allXValues: Set<unknown>,
+): ChartSpec {
+  if (!xField || allXValues.size === 0) return leaf;
+
+  const existingXValues = new Set<unknown>();
+  for (const row of leaf.data) existingXValues.add(row[xField]);
+
+  const missingRows: DataRow[] = [];
+  for (const xVal of allXValues) {
+    if (!existingXValues.has(xVal)) {
+      missingRows.push({ [xField]: xVal });
+    }
+  }
+
+  if (missingRows.length === 0) return leaf;
+
+  return {
+    ...leaf,
+    data: [...leaf.data, ...missingRows],
+  };
+}
+
+/**
+ * Compute aligned y-domains for two layers so that zero maps to the same
+ * pixel position on both axes. Returns explicit [min, max] domains for each
+ * layer, or undefined if alignment isn't applicable (non-quantitative axes,
+ * or neither domain spans zero).
+ */
+function alignYDomains(
+  leaf0: ChartSpec,
+  leaf1: ChartSpec,
+): { domain0: [number, number]; domain1: [number, number] } | undefined {
+  const yEnc0 = leaf0.encoding?.y;
+  const yEnc1 = leaf1.encoding?.y;
+  if (!yEnc0 || !yEnc1) return undefined;
+  if (yEnc0.type !== 'quantitative' || yEnc1.type !== 'quantitative') return undefined;
+
+  // Skip if either layer has an explicit domain already set by the user
+  if (yEnc0.scale?.domain || yEnc1.scale?.domain) return undefined;
+
+  const includeZero0 = yEnc0.scale?.zero !== false;
+  const includeZero1 = yEnc1.scale?.zero !== false;
+
+  const vals0 = leaf0.data.map((r) => Number(r[yEnc0.field])).filter(Number.isFinite);
+  const vals1 = leaf1.data.map((r) => Number(r[yEnc1.field])).filter(Number.isFinite);
+  if (vals0.length === 0 || vals1.length === 0) return undefined;
+
+  // Compute nice domains for each (mirroring buildLinearScale behavior)
+  const niced = (vals: number[], includeZero: boolean): [number, number] => {
+    let lo = Math.min(...vals);
+    let hi = Math.max(...vals);
+    if (includeZero) {
+      lo = Math.min(0, lo);
+      hi = Math.max(0, hi);
+    }
+    const s = scaleLinear().domain([lo, hi]);
+    s.nice();
+    const [dLo, dHi] = s.domain();
+    return [dLo, dHi];
+  };
+
+  const [min0, max0] = niced(vals0, includeZero0);
+  const [min1, max1] = niced(vals1, includeZero1);
+
+  const span0 = max0 - min0;
+  const span1 = max1 - min1;
+  if (span0 === 0 || span1 === 0) return undefined;
+
+  // Zero fraction: how far up from the bottom zero sits (0 = bottom, 1 = top).
+  // Only align when BOTH domains naturally contain zero. If one axis is entirely
+  // positive or entirely negative (zero is outside the domain), forcing alignment
+  // would push the other axis into an unnatural range. In that case, let each
+  // axis render its natural domain independently.
+  const zf0 = (0 - min0) / span0;
+  const zf1 = (0 - min1) / span1;
+
+  const zeroInDomain0 = zf0 >= -0.001 && zf0 <= 1.001;
+  const zeroInDomain1 = zf1 >= -0.001 && zf1 <= 1.001;
+  if (!zeroInDomain0 || !zeroInDomain1) return undefined;
+
+  // If both zeros are at the same position (within tolerance), no adjustment needed
+  if (Math.abs(zf0 - zf1) < 0.001) {
+    return { domain0: [min0, max0], domain1: [min1, max1] };
+  }
+
+  // Align by extending domains so zero sits at the same proportional position.
+  // Keep the niced boundaries on the side that doesn't need extending, and
+  // compute the exact extended boundary (no re-nicing) so zero stays locked.
+  const targetZf = Math.max(zf0, zf1);
+
+  const align = (dMin: number, dMax: number, currentZf: number): [number, number] => {
+    if (Math.abs(currentZf - targetZf) < 0.001) return [dMin, dMax];
+
+    if (targetZf > currentZf) {
+      // Need more negative range: newMin = -(targetZf / (1 - targetZf)) * dMax
+      const newMin = -(targetZf / (1 - targetZf)) * dMax;
+      return [newMin, dMax];
+    }
+    // Need more positive range: newMax = -dMin * (1 - targetZf) / targetZf
+    const newMax = (-dMin * (1 - targetZf)) / targetZf;
+    return [dMin, newMax];
+  };
+
+  const domain0 = align(min0, max0, zf0);
+  const domain1 = align(min1, max1, zf1);
+
+  return { domain0, domain1 };
+}
+
+/**
+ * Inject an explicit y-scale domain override into a leaf spec.
+ */
+function withYDomain(leaf: ChartSpec, domain: [number, number]): ChartSpec {
+  if (!leaf.encoding?.y) return leaf;
+  return {
+    ...leaf,
+    encoding: {
+      ...leaf.encoding,
+      y: {
+        ...leaf.encoding.y,
+        scale: {
+          ...leaf.encoding.y.scale,
+          domain,
+        },
+      },
+    },
+  };
+}
+
 /**
  * Build the primary ChartSpec from all leaves for shared compilation.
  * Unions all data rows across layers so scales see the full domain.

package/src/layout/axes.ts

@@ -314,13 +314,14 @@ export function computeAxes(
     }
 
     const axisTitle = axisConfig?.title;
+    const xLabelColor = axisConfig?.labelColor;
 
     result.x = {
       ticks,
       gridlines: axisConfig?.grid ? gridlines : [],
       label: axisTitle,
-      labelStyle: axisLabelStyle,
-      tickLabelStyle,
+      labelStyle: xLabelColor ? { ...axisLabelStyle, fill: xLabelColor } : axisLabelStyle,
+      tickLabelStyle: xLabelColor ? { ...tickLabelStyle, fill: xLabelColor } : tickLabelStyle,
       tickAngle,
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
@@ -387,14 +388,15 @@ export function computeAxes(
 
     const axisTitle = axisConfig?.title;
     const tickAngle = axisConfig?.labelAngle;
+    const yLabelColor = axisConfig?.labelColor;
 
     result.y = {
       ticks,
       // Y-axis gridlines are shown by default (standard editorial practice)
       gridlines,
       label: axisTitle,
-      labelStyle: axisLabelStyle,
-      tickLabelStyle,
+      labelStyle: yLabelColor ? { ...axisLabelStyle, fill: yLabelColor } : axisLabelStyle,
+      tickLabelStyle: yLabelColor ? { ...tickLabelStyle, fill: yLabelColor } : tickLabelStyle,
       tickAngle,
       start: { x: chartArea.x, y: chartArea.y },
       end: { x: chartArea.x, y: chartArea.y + chartArea.height },

package/src/layout/dimensions.ts

@@ -317,6 +317,11 @@ export function computeDimensions(
     margins.left = Math.max(margins.left, padding + rotatedLabelMargin);
   }
 
+  // Reserve space for a secondary (right) y-axis in dual-axis charts
+  if (options.rightAxisReserve && options.rightAxisReserve > 0) {
+    margins.right += options.rightAxisReserve;
+  }
+
   // Reserve legend space
   if (legendLayout.entries.length > 0) {
     const gap = legendGap(width);