@opendata-ai/openchart-engine 6.28.6 → 7.0.0

package/src/compile.ts

@@ -19,7 +19,6 @@ import type {
   ChartSpec,
   CompileOptions,
   CompileTableOptions,
-  DataRow,
   Encoding,
   EncodingChannel,
   LayerSpec,
@@ -33,24 +32,19 @@ import type {
   Transform,
 } from '@opendata-ai/openchart-core';
 import {
-  AXIS_TITLE_TRAILING_PAD,
   adaptTheme,
-  BREAKPOINT_COMPACT_MAX,
   computeLabelBounds,
   estimateTextWidth,
   generateAltText,
   generateDataTable,
-  getAxisTitleOffset,
   getBreakpoint,
   getHeightClass,
   getLayoutStrategy,
   resolveTheme,
-  TICK_LABEL_OFFSET,
 } from '@opendata-ai/openchart-core';
 import { format as d3Format } from 'd3-format';
-import { scaleLinear } from 'd3-scale';
-import { curveMonotoneX, area as d3area, line as d3line } from 'd3-shape';
 import { computeAnnotations } from './annotations/compute';
+import { computeEndpointLabels } from './endpoint-labels/compute';
 // Side-effect import: registers all built-in chart renderers with the
 // registry on module load. Tests that clear the registry can import
 // `registerBuiltinRenderers` from `./charts/builtin` to restore defaults.
@@ -64,9 +58,16 @@ import {
 import { getChartRenderer } from './charts/registry';
 import { applyColorScaleRange } from './compile/color-scale-range';
 import { filterClippedDomains } from './compile/data-clip';
+import { compileLayer as compileLayerImpl } from './compile/layer';
 import { computeWatermarkObstacle } from './compile/watermark-obstacle';
 import { resolveAnimation } from './compiler/animation';
-import { compile as compileSpec, flattenLayers } from './compiler/index';
+import { compile as compileSpec } from './compiler/index';
+import {
+  buildSparklineAreaGradient,
+  computeTrendFromData,
+  hasExplicitColor,
+  trendColor,
+} from './compiler/sparkline-defaults';
 import type { NormalizedChartSpec, NormalizedTableSpec } from './compiler/types';
 import { compileGraph as compileGraphImpl } from './graphs/compile-graph';
 import type { GraphCompilation } from './graphs/types';
@@ -160,6 +161,63 @@ export function expandEncodingSugar(spec: Record<string, unknown>): Record<strin
 // Chart compilation
 // ---------------------------------------------------------------------------
 
+/**
+ * Inject sparkline-mode visual defaults that depend on the resolved theme.
+ *
+ * Trend-aware color (positive/negative/neutral), default endpoint dot,
+ * default area gradient, and default pill cornerRadius for bars. Each
+ * default backs off when the user has set the corresponding markDef
+ * field. Bar marks do NOT get trend coloring — the design intent is a
+ * single palette color across all bars.
+ */
+function applySparklineDefaults(
+  spec: NormalizedChartSpec,
+  theme: ResolvedTheme,
+): NormalizedChartSpec {
+  const markType = spec.markType;
+  const isLineFamily = markType === 'line' || markType === 'area';
+  const isBar = markType === 'bar';
+  if (!isLineFamily && !isBar) return spec;
+
+  const yField = spec.encoding.y && 'field' in spec.encoding.y ? spec.encoding.y.field : undefined;
+  const trend = computeTrendFromData(spec.data, yField);
+  const color = trendColor(trend, theme);
+
+  const encodingHasColor =
+    !!spec.encoding.color && (spec.encoding.color as { field?: unknown }).field !== undefined;
+  const explicit = hasExplicitColor(spec.markDef, encodingHasColor);
+
+  const newMarkDef = { ...spec.markDef };
+
+  if (isLineFamily) {
+    if (!explicit.stroke) newMarkDef.stroke = color;
+    if (markType === 'area' && !explicit.fill) {
+      newMarkDef.fill = buildSparklineAreaGradient(color);
+    }
+    // Endpoint dot is wired in the line compute path. We skip the default
+    // when the encoding has a color field, because the multi-series area
+    // path (linesFromAreas()) ignores markDef.point — the dot would be set
+    // on the spec but never rendered, and the line compute path's dot logic
+    // is per-series, not "one dot for the chart."
+    if (newMarkDef.point === undefined && !encodingHasColor) {
+      newMarkDef.point = 'last';
+    }
+  }
+
+  if (isBar) {
+    // Pill cornerRadius is safe on stacked bars too — the column compute
+    // path applies the radius only to the topmost segment via
+    // `cornerRadiusSides`, leaving the seams between segments square so
+    // they stay flush. Single-series bars get all four corners rounded
+    // since there's nothing below them to align against.
+    if (newMarkDef.cornerRadius === undefined) {
+      newMarkDef.cornerRadius = 'pill';
+    }
+  }
+
+  return { ...spec, markDef: newMarkDef };
+}
+
 /**
  * Compile a chart spec into a ChartLayout.
  *
@@ -258,8 +316,19 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const userExplicit = {
     chrome: hasChromeKeys(rawSpec.chrome) || hasChromeKeys(bpForExplicit?.chrome),
     legend: rawSpec.legend !== undefined || bpForExplicit?.legend !== undefined,
-    xAxis: rawEncoding?.x?.axis !== undefined || bpEncoding?.x?.axis !== undefined,
-    yAxis: rawEncoding?.y?.axis !== undefined || bpEncoding?.y?.axis !== undefined,
+    endpointLabels:
+      rawSpec.endpointLabels !== undefined ||
+      (bpForExplicit as Record<string, unknown> | undefined)?.endpointLabels !== undefined,
+    // Axis explicitness tracks "user opted IN to render the axis" — `axis: false`
+    // is an explicit opt-OUT and must not flip these flags on. Sparkline mode
+    // reads them to decide whether to reserve axis space; treating `false` as
+    // explicit would leave a phantom gutter for an axis that won't render.
+    xAxis:
+      (rawEncoding?.x?.axis !== undefined && rawEncoding.x.axis !== false) ||
+      (bpEncoding?.x?.axis !== undefined && bpEncoding.x.axis !== false),
+    yAxis:
+      (rawEncoding?.y?.axis !== undefined && rawEncoding.y.axis !== false) ||
+      (bpEncoding?.y?.axis !== undefined && bpEncoding.y.axis !== false),
     labels: rawSpec.labels !== undefined || bpForExplicit?.labels !== undefined,
     animation: rawSpec.animation !== undefined || bpForExplicit?.animation !== undefined,
     watermark: rawSpec.watermark !== undefined || bpForExplicit?.watermark !== undefined,
@@ -430,15 +499,15 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
   const resolvedAnimation = resolveAnimation(rawAnimationSpec);
 
-  // Crosshair: explicit user value at any level wins. In sparkline mode the
-  // default is off, otherwise default is off too (crosshair is opt-in). The
-  // value is plumbed through ChartLayout so the renderer doesn't need to
-  // re-inspect the raw spec.
+  // Crosshair: explicit user value at any level wins. Default is ON for line
+  // and area marks in full mode (the hover guideline + per-series tooltip is
+  // the standard interaction pattern for time-series charts). Sparkline mode
+  // defaults off. The value is plumbed through ChartLayout so the renderer
+  // doesn't need to re-inspect the raw spec.
   const rawCrosshair = (bpForExplicit?.crosshair ?? rawSpec.crosshair) as boolean | undefined;
-  const crosshair =
-    chartSpec.display === 'sparkline' && !chartSpec.userExplicit.crosshair
-      ? false
-      : rawCrosshair === true;
+  const isLineOrAreaMark = chartSpec.markType === 'line' || chartSpec.markType === 'area';
+  const crosshairDefault = chartSpec.display === 'sparkline' ? false : isLineOrAreaMark;
+  const crosshair = chartSpec.userExplicit.crosshair ? rawCrosshair === true : crosshairDefault;
 
   // Watermark default-off in sparkline mode unless user-explicit.
   if (chartSpec.display === 'sparkline' && !chartSpec.userExplicit.watermark) {
@@ -455,6 +524,15 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     theme = adaptTheme(theme);
   }
 
+  // Sparkline mode: inject smart defaults that depend on the resolved theme
+  // (trend-aware color, area gradient, default endpoint dot, pill cornerRadius
+  // for bars). Each default backs off when the user has set the corresponding
+  // field explicitly. Must run AFTER theme resolution (color depends on theme)
+  // and BEFORE computeDimensions (which reads markDef.point for sparkline padding).
+  if (chartSpec.display === 'sparkline') {
+    chartSpec = applySparklineDefaults(chartSpec, theme);
+  }
+
   // INVARIANT 1 — double legend pass: preliminaryArea → computeDimensions → legendArea → final
   // legend. Breaks a dims/legend dependency cycle. Do not collapse into one call.
   // Compute legend first (needs to reserve space)
@@ -483,7 +561,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
         legendArea.height += legendLayout.bounds.height + gap;
         break;
       case 'bottom':
-        legendArea.height += legendLayout.bounds.height + gap;
+        // Bottom legend sits below the x-axis tick row, not over it. Expand
+        // legendArea by xAxisHeight + legendHeight + gap so the bottom-anchored
+        // legend lands beneath the axis. Mirrors dimensions.ts which reserved
+        // the same xAxisHeight in margins.bottom.
+        legendArea.height += legendLayout.bounds.height + gap + dims.xAxisHeight;
         break;
       case 'right':
       case 'bottom-right':
@@ -512,10 +594,107 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   renderData = filterClippedDomains(renderData, chartSpec.encoding);
 
   // Build a filtered spec for scales and marks, keeping all other properties intact
-  const renderSpec = renderData !== chartSpec.data ? { ...chartSpec, data: renderData } : chartSpec;
+  let renderSpec = renderData !== chartSpec.data ? { ...chartSpec, data: renderData } : chartSpec;
+
+  // Lock the color scale domain to the unfiltered series list so palette
+  // assignments stay stable across legend toggles. Without this, hiding a
+  // series shrinks the ordinal scale's domain and shifts every remaining
+  // series down one palette index — the visible lines would mismatch the
+  // legend swatches that still represent the original assignment.
+  // Skipped when the user already supplied an explicit domain.
+  const colorEnc = chartSpec.encoding.color;
+  if (
+    chartSpec.hiddenSeries.length > 0 &&
+    colorEnc &&
+    'field' in colorEnc &&
+    colorEnc.type !== 'quantitative' &&
+    colorEnc.scale?.domain == null
+  ) {
+    const colorField = colorEnc.field;
+    const stableDomain = Array.from(new Set(chartSpec.data.map((row) => String(row[colorField]))));
+    renderSpec = {
+      ...renderSpec,
+      encoding: {
+        ...renderSpec.encoding,
+        color: {
+          ...colorEnc,
+          scale: { ...(colorEnc.scale ?? {}), domain: stableDomain },
+        },
+      },
+    };
+  }
+
+  // Inline y-axis labels render at chartArea.x with text-anchor=start. Without
+  // an inset the leftmost data point on a line/area would clip through the
+  // label glyphs (since the line begins at chartArea.x too). Inset the x-scale
+  // range start by the widest tick label width so the data starts to the right
+  // of the labels. Axes/gridlines still span the full chart area, so inline
+  // labels stay flush left where the design intends.
+  const yEnc = renderSpec.encoding?.y;
+  const yAxisCfgInline =
+    typeof yEnc?.axis === 'object' && yEnc.axis !== null
+      ? (yEnc.axis as Record<string, unknown>)
+      : undefined;
+  const yIsContinuous = yEnc?.type === 'quantitative' || yEnc?.type === 'temporal';
+  const isLineOrArea = renderSpec.markType === 'line' || renderSpec.markType === 'area';
+  const yInlineExplicit = yAxisCfgInline?.tickPosition as 'inline' | 'gutter' | undefined;
+  // Sparkline mode hides the y-axis by default, so the inline-label inset
+  // would shrink the data range without any labels actually being drawn —
+  // the line ends up starting ~30px from the left edge for no visible
+  // reason. Skip the inset unless the user explicitly opted into the
+  // y-axis (in which case the labels do render and the inset is needed).
+  const sparklineSuppressesYAxis =
+    chartSpec.display === 'sparkline' && !chartSpec.userExplicit.yAxis;
+  const yIsInline =
+    !sparklineSuppressesYAxis &&
+    (yInlineExplicit === 'inline' ||
+      (yInlineExplicit === undefined &&
+        isLineOrArea &&
+        yIsContinuous &&
+        yAxisCfgInline?.orient !== 'right'));
+  let scaleArea = chartArea;
+  if (yIsInline && yEnc && yIsContinuous && yEnc.axis !== false) {
+    const yField = yEnc.field;
+    const yFmt = yAxisCfgInline?.format as string | undefined;
+    let maxAbsVal = 0;
+    for (const row of renderSpec.data) {
+      const v = Number(row[yField]);
+      if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
+    }
+    let sample: string;
+    if (yFmt) {
+      try {
+        sample = d3Format(yFmt)(maxAbsVal);
+      } catch {
+        sample = String(maxAbsVal);
+      }
+    } else if (maxAbsVal >= 1_000_000_000) sample = '1.5B';
+    else if (maxAbsVal >= 1_000_000) sample = '1.5M';
+    else if (maxAbsVal >= 1_000) sample = '1.5K';
+    else if (maxAbsVal >= 100) sample = '100';
+    else if (maxAbsVal >= 10) sample = '10';
+    else sample = '0.0';
+    const negPrefix = renderSpec.data.some((r) => Number(r[yField]) < 0) ? '-' : '';
+    const labelEst = negPrefix + sample;
+    const labelWidth = estimateTextWidth(
+      labelEst,
+      theme.fonts.sizes.axisTick,
+      theme.fonts.weights.normal,
+    );
+    const INLINE_LABEL_BREATHING_ROOM = 8;
+    const inset = Math.ceil(labelWidth + INLINE_LABEL_BREATHING_ROOM);
+    if (inset > 0 && inset < chartArea.width) {
+      scaleArea = {
+        x: chartArea.x + inset,
+        y: chartArea.y,
+        width: chartArea.width - inset,
+        height: chartArea.height,
+      };
+    }
+  }
 
   // Compute scales
-  const scales = computeScales(renderSpec, chartArea, renderSpec.data);
+  const scales = computeScales(renderSpec, scaleArea, renderSpec.data);
 
   // Update color scale to use theme palette (only when user hasn't provided an explicit range)
   applyColorScaleRange(scales, renderSpec.encoding, theme);
@@ -541,6 +720,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
         encoding: renderSpec.encoding as Encoding,
         skipX,
         skipY,
+        markType: chartSpec.markType,
       });
 
   // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
@@ -558,6 +738,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const renderer = getChartRenderer(rendererKey);
   const marks: Mark[] = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme) : [];
 
+  // Compute the right-side endpoint labels column for multi-series line/area
+  // charts. Reads `mark.dataPoints` so it must run AFTER marks are computed.
+  // dimensions.ts already reserved the right margin via predictEndpointLabelsWidth.
+  const endpointLabels = computeEndpointLabels(chartSpec, marks, theme, chartArea, strategy);
+
   // Compute annotations from spec, passing legend + mark + brand bounds as obstacles
   const obstacles: Rect[] = [];
   if (finalLegend.bounds.width > 0) {
@@ -595,7 +780,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       data: chartSpec.data,
       encoding: chartSpec.encoding,
       chrome: chartSpec.chrome,
-    },
+    } as ChartSpec,
     chartSpec.data,
   );
   const dataTableFallback = generateDataTable(
@@ -603,7 +788,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       mark: chartSpec.markType,
       data: chartSpec.data,
       encoding: chartSpec.encoding,
-    },
+    } as ChartSpec,
     chartSpec.data,
   );
 
@@ -613,6 +798,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   return {
     area: chartArea,
     chrome: dims.chrome,
+    metrics: dims.metrics,
     axes: {
       x: axes.x,
       y: axes.y,
@@ -620,6 +806,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     marks,
     annotations,
     legend: finalLegend,
+    ...(endpointLabels.entries.length > 0 ? { endpointLabels } : {}),
     tooltipDescriptors,
     a11y: {
       altText,
@@ -644,570 +831,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 // Layer compilation
 // ---------------------------------------------------------------------------
 
-/**
- * Compile a LayerSpec into a single ChartLayout.
- *
- * Flattens nested layers, merges inherited data/encoding/transforms,
- * compiles each leaf layer independently, unions scale domains (shared
- * by default), and concatenates marks in layer order.
- *
- * @param spec - A LayerSpec with child layers.
- * @param options - Compile options (width, height, theme, darkMode).
- * @returns A single ChartLayout with combined marks from all layers.
- */
 export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLayout {
-  // Flatten nested layers into leaf ChartSpecs with merged data/encoding/transforms
-  const leaves = flattenLayers(spec);
-
-  if (leaves.length === 0) {
-    throw new Error('LayerSpec has no leaf chart specs after flattening');
-  }
-
-  // If there's only one layer, just compile it directly
-  if (leaves.length === 1) {
-    const singleSpec = buildPrimarySpec(leaves, spec);
-    return compileChart(singleSpec, options);
-  }
-
-  // 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);
-
-  const allMarks: Mark[] = [];
-  const seenLabels = new Set<string>();
-  const pLegend = primaryLayout.legend;
-  const mergedLegendEntries = 'entries' in pLegend ? [...pLegend.entries] : [];
-  for (const entry of mergedLegendEntries) {
-    seenLabels.add(entry.label);
-  }
-
-  // Sort leaves by zIndex for render order while preserving original indices
-  // for axis assignment. Default zIndex is the array position.
-  const indexedLeaves = leaves.map((leaf, i) => ({
-    leaf,
-    zIndex: (leaf as ChartSpec).zIndex ?? i,
-  }));
-  indexedLeaves.sort((a, b) => a.zIndex - b.zIndex);
-
-  for (const { leaf } of indexedLeaves) {
-    const leafLayout = compileChart(leaf as unknown, options);
-
-    allMarks.push(...leafLayout.marks);
-
-    const leafLeg = leafLayout.legend;
-    if ('entries' in leafLeg) {
-      for (const entry of leafLeg.entries) {
-        if (!seenLabels.has(entry.label)) {
-          seenLabels.add(entry.label);
-          mergedLegendEntries.push(entry);
-        }
-      }
-    }
-  }
-
-  return {
-    ...primaryLayout,
-    marks: allMarks,
-    legend: {
-      ...primaryLayout.legend,
-      ...('entries' in pLegend ? { entries: mergedLegendEntries } : {}),
-    } as typeof primaryLayout.legend,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 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
-  const yAxisFormat = (encoding.y.axis as Record<string, unknown> | undefined)?.format as
-    | string
-    | undefined;
-  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 (yAxisFormat) {
-    try {
-      const fmt = d3Format(yAxisFormat);
-      sampleLabel = fmt(maxAbsVal);
-    } catch {
-      sampleLabel = String(maxAbsVal);
-    }
-  } else {
-    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.
-  // Tick labels sit at chartEdge+6 and extend rightward by their width.
-  // The rotated title sits at chartEdge+45 and extends by half the font height.
-  // These overlap spatially, so use max (not sum) to mirror the left-margin pattern.
-  const theme = resolveTheme(layerSpec.theme ?? leaf1.theme);
-  const axisFontSize = theme.fonts?.sizes?.axisTick ?? 11;
-  const rightAxisWidth = estimateYAxisLabelWidth(leaf1.data, leaf1.encoding, axisFontSize);
-  const yAxisConfig = leaf1.encoding?.y?.axis || undefined;
-  const hasRightAxisTitle = !!yAxisConfig?.title;
-  const tickExtent = TICK_LABEL_OFFSET + rightAxisWidth;
-  const bodyFontSize = theme.fonts?.sizes?.body ?? 13;
-  const axisTitleOffset = getAxisTitleOffset(options.width);
-  const halfGlyph = Math.ceil(bodyFontSize / 2);
-  const titleExtent = hasRightAxisTitle
-    ? axisTitleOffset +
-      halfGlyph +
-      (options.width < BREAKPOINT_COMPACT_MAX ? 0 : AXIS_TITLE_TRAILING_PAD)
-    : 0;
-  const rightReserve = Math.max(tickExtent, titleExtent);
-
-  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 l0Legend = layout0.legend;
-  const l1Legend = layout1.legend;
-  const mergedLegendEntries = 'entries' in l0Legend ? [...l0Legend.entries] : [];
-  for (const entry of mergedLegendEntries) seenLabels.add(entry.label);
-  const l1Entries = 'entries' in l1Legend ? l1Legend.entries : [];
-  for (const entry of l1Entries) {
-    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);
-    }
-  }
-
-  // Determine mark render order. By default, layer 0 paints first (behind),
-  // layer 1 paints second (on top). zIndex on the original leaf specs can
-  // reverse this so e.g. a line in layer 0 renders on top of bars in layer 1.
-  const z0 = leaf0.zIndex ?? 0;
-  const z1 = leaf1.zIndex ?? 1;
-  const marks =
-    z0 <= z1 ? [...adjustedMarks0, ...taggedMarks1] : [...taggedMarks1, ...adjustedMarks0];
-
-  return {
-    ...layout0,
-    axes: {
-      x: layout0.axes.x,
-      y: layout0.axes.y,
-      y2: y2Axis,
-    },
-    marks,
-    legend: {
-      ...layout0.legend,
-      ...('entries' in l0Legend ? { entries: mergedLegendEntries } : {}),
-    } as typeof layout0.legend,
-    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.
- * Uses the first leaf's mark/encoding as the base, with layer-level chrome.
- */
-function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec {
-  // Union all data across layers for domain computation
-  const allData = leaves.flatMap((leaf) => leaf.data);
-
-  const primary = {
-    ...leaves[0],
-    data: allData,
-    // Layer-level chrome overrides leaf chrome
-    chrome: layerSpec.chrome ?? leaves[0].chrome,
-    annotations: layerSpec.annotations ?? leaves[0].annotations,
-    labels: layerSpec.labels ?? leaves[0].labels,
-    legend: layerSpec.legend ?? leaves[0].legend,
-    responsive: layerSpec.responsive ?? leaves[0].responsive,
-    theme: layerSpec.theme ?? leaves[0].theme,
-    darkMode: layerSpec.darkMode ?? leaves[0].darkMode,
-    watermark: layerSpec.watermark ?? leaves[0].watermark,
-    hiddenSeries: layerSpec.hiddenSeries ?? leaves[0].hiddenSeries,
-  };
-
-  return primary;
+  return compileLayerImpl(spec, options, compileChart);
 }
 
 // ---------------------------------------------------------------------------