@opendata-ai/openchart-engine 6.20.0 → 6.21.0

package/src/compile/__tests__/watermark-obstacle.test.ts

@@ -0,0 +1,93 @@
+import type { AxisLayout, Rect, ResolvedChrome, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { AxesResult } from '../../layout/axes';
+import type { LayoutDimensions } from '../../layout/dimensions';
+import { computeWatermarkObstacle } from '../watermark-obstacle';
+
+const theme: ResolvedTheme = resolveTheme();
+
+function makeDims(overrides: Partial<LayoutDimensions> = {}): LayoutDimensions {
+  const total: Rect = { x: 0, y: 0, width: 800, height: 500 };
+  const chartArea: Rect = { x: 60, y: 80, width: 700, height: 360 };
+  const chrome: ResolvedChrome = {
+    topHeight: 80,
+    bottomHeight: 40,
+  } as ResolvedChrome;
+  return {
+    total,
+    chartArea,
+    chrome,
+    margins: { top: 80, right: 40, bottom: 40, left: 60 },
+    theme,
+    ...overrides,
+  };
+}
+
+function makeAxis(label?: string): AxisLayout {
+  return {
+    ticks: [],
+    gridlines: [],
+    label,
+    tickLabelStyle: {
+      fontFamily: theme.fonts.family,
+      fontSize: 12,
+      fontWeight: 400,
+      fill: '#000',
+      lineHeight: 1.2,
+    },
+    start: { x: 0, y: 0 },
+    end: { x: 100, y: 0 },
+  };
+}
+
+describe('computeWatermarkObstacle', () => {
+  it('returns null when watermark is disabled', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    expect(computeWatermarkObstacle(dims, false, axes, theme)).toBeNull();
+  });
+
+  it('sits below the x-axis when no bottom chrome is present', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis('value'), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // Right-aligned: total.width - padding - BRAND_RESERVE_WIDTH
+    expect(rect!.x).toBe(dims.total.width - theme.spacing.padding - BRAND_RESERVE_WIDTH);
+    expect(rect!.width).toBe(BRAND_RESERVE_WIDTH);
+    expect(rect!.height).toBe(30);
+    // Watermark sits below chart area, offset by x-axis extent + chartToFooter
+    const expectedY = dims.chartArea.y + dims.chartArea.height + 48 + theme.spacing.chartToFooter;
+    expect(rect!.y).toBe(expectedY);
+  });
+
+  it('aligns with bottom chrome when a source element is present', () => {
+    const sourceY = 20;
+    const dims = makeDims({
+      chrome: {
+        topHeight: 80,
+        bottomHeight: 40,
+        source: {
+          text: 'Source: Test',
+          x: 10,
+          y: sourceY,
+          maxWidth: 500,
+          style: {
+            fontFamily: theme.fonts.family,
+            fontSize: 10,
+            fontWeight: 400,
+            fill: '#666',
+            lineHeight: 1.2,
+          },
+        },
+      } as ResolvedChrome,
+    });
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // With axis present but no label, extent is 26.
+    // Y is chartArea.y + chartArea.height + 26 + sourceY
+    expect(rect!.y).toBe(dims.chartArea.y + dims.chartArea.height + 26 + sourceY);
+  });
+});

package/src/compile/color-scale-range.ts

@@ -0,0 +1,38 @@
+/**
+ * Apply the theme palette as the color scale range when no explicit range was provided.
+ *
+ * Sequential scales take the first/last stops of the first sequential palette
+ * (or the categorical endpoints as a fallback). Categorical scales get the
+ * full categorical palette. A user-provided `encoding.color.scale.range`
+ * always wins.
+ */
+
+import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import type { ScaleLinear, ScaleOrdinal } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/** Mutates `scales.color.scale.range` in place when no explicit palette was set. */
+export function applyColorScaleRange(
+  scales: ResolvedScales,
+  encoding: Encoding,
+  theme: ResolvedTheme,
+): void {
+  if (!scales.color) return;
+
+  const hasExplicitRange = !!(
+    encoding.color &&
+    'field' in encoding.color &&
+    (encoding.color.scale?.range as string[] | undefined)?.length
+  );
+  if (hasExplicitRange) return;
+
+  if (scales.color.type === 'sequential') {
+    const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    (scales.color.scale as unknown as ScaleLinear<string, string>).range([
+      seqStops[0],
+      seqStops[seqStops.length - 1],
+    ]);
+  } else {
+    (scales.color.scale as ScaleOrdinal<string, string>).range(theme.colors.categorical);
+  }
+}

package/src/compile/data-clip.ts

@@ -0,0 +1,33 @@
+/**
+ * Data filter for clipped scale domains.
+ *
+ * When an x or y encoding declares `scale.clip: true` with a numeric
+ * [lo, hi] domain, rows whose field value falls outside that range are
+ * dropped before scales and marks are computed. Pure and side-effect free.
+ */
+
+import type { DataRow, Encoding } from '@opendata-ai/openchart-core';
+
+/**
+ * Return a new data array with rows outside any clipped scale domain removed.
+ *
+ * Only inspects the `x` and `y` channels. Non-numeric domains and channels
+ * without `scale.clip` are passed through unchanged.
+ */
+export function filterClippedDomains(data: DataRow[], encoding: Encoding): DataRow[] {
+  let result = data;
+  for (const channel of ['x', 'y'] as const) {
+    const enc = 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];
+      result = result.filter((row) => {
+        const v = Number(row[field]);
+        return Number.isFinite(v) && v >= lo && v <= hi;
+      });
+    }
+  }
+  return result;
+}

package/src/compile/watermark-obstacle.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute the brand watermark obstacle rect.
+ *
+ * The watermark is right-aligned on the same baseline as the first bottom
+ * chrome element (source, byline, or footer), offset below the chart area
+ * by the x-axis extent (tick labels + axis title). Returns null when the
+ * watermark is disabled so callers can skip obstacle collection entirely.
+ */
+
+import type { Rect, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH } from '@opendata-ai/openchart-core';
+import type { AxesResult } from '../layout/axes';
+import type { LayoutDimensions } from '../layout/dimensions';
+
+/** Height of the watermark element used for obstacle avoidance. */
+const WATERMARK_HEIGHT = 30;
+
+/** Vertical padding below the x-axis label when an axis title is present. */
+const X_AXIS_EXTENT_WITH_LABEL = 48;
+
+/** Vertical padding below the x-axis ticks when no axis title is present. */
+const X_AXIS_EXTENT_TICKS_ONLY = 26;
+
+/**
+ * Compute the rect occupied by the watermark, or null when it is disabled.
+ *
+ * @param dims - Layout dimensions (for total width and chrome positions).
+ * @param watermark - Whether the watermark is enabled for this chart.
+ * @param axes - Computed axes (the x-axis determines how far below the chart the watermark sits).
+ * @param theme - Resolved theme (padding + fallback spacing).
+ */
+export function computeWatermarkObstacle(
+  dims: LayoutDimensions,
+  watermark: boolean,
+  axes: AxesResult,
+  theme: ResolvedTheme,
+): Rect | null {
+  if (!watermark) return null;
+
+  const chartArea = dims.chartArea;
+  const brandPadding = theme.spacing.padding;
+  const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
+  const xAxisExtent = axes.x?.label
+    ? X_AXIS_EXTENT_WITH_LABEL
+    : axes.x
+      ? X_AXIS_EXTENT_TICKS_ONLY
+      : 0;
+  const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
+  const brandY = firstBottomChrome
+    ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
+    : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
+
+  return { x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: WATERMARK_HEIGHT };
+}

package/src/compile.ts

@@ -32,7 +32,6 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
-  BRAND_RESERVE_WIDTH,
   computeLabelBounds,
   generateAltText,
   generateDataTable,
@@ -42,57 +41,21 @@ import {
   resolveTheme,
 } from '@opendata-ai/openchart-core';
 import { computeAnnotations } from './annotations/compute';
-import { barRenderer } from './charts/bar';
-import { columnRenderer } from './charts/column';
-import { dotRenderer } from './charts/dot';
-import { areaRenderer, lineRenderer } from './charts/line';
-import { donutRenderer, pieRenderer } from './charts/pie';
+// 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.
+import './charts/builtin';
 import {
   assignAnimationIndices,
   computeMarkObstacles,
   resolveRendererKey,
 } from './charts/post-process';
-import { type ChartRenderer, getChartRenderer, registerChartRenderer } from './charts/registry';
-import { ruleRenderer } from './charts/rule';
-import { scatterRenderer } from './charts/scatter';
-import { textRenderer } from './charts/text';
-import { tickRenderer } from './charts/tick';
-import { compile as compileSpec, flattenLayers } from './compiler/index';
-
-// Register all built-in chart renderers under the new Vega-Lite mark type names.
-// Explicit imports ensure bundlers cannot tree-shake the registrations away.
-//
-// Mark type mapping from old chart types:
-// - 'bar' -> barRenderer (horizontal bars, old 'bar')
-// - 'bar:vertical' is handled by columnRenderer (old 'column')
-// - 'arc' -> pieRenderer (old 'pie'); donutRenderer is also registered
-// - 'point' -> scatterRenderer (old 'scatter')
-// - 'circle' -> dotRenderer (old 'dot')
-// - 'line' and 'area' unchanged
-// - 'text', 'rule', 'tick' are new Vega-Lite mark types
-//
-// For 'bar', orientation is resolved at compile time to dispatch to the right renderer.
-// We register both barRenderer and columnRenderer; the compile function picks based on orientation.
-const builtinRenderers: Record<string, ChartRenderer> = {
-  line: lineRenderer,
-  area: areaRenderer,
-  bar: barRenderer, // horizontal bars
-  'bar:vertical': columnRenderer, // vertical bars (old 'column')
-  point: scatterRenderer, // old 'scatter'
-  arc: pieRenderer, // old 'pie' (donut handled via innerRadius)
-  'arc:donut': donutRenderer, // old 'donut'
-  circle: dotRenderer, // old 'dot'
-  lollipop: dotRenderer, // semantic alias for dot/circle
-  text: textRenderer,
-  rule: ruleRenderer,
-  tick: tickRenderer,
-  rect: columnRenderer, // rect uses column renderer (RectMark output) as baseline for heatmaps
-};
-for (const [type, renderer] of Object.entries(builtinRenderers)) {
-  registerChartRenderer(type, renderer);
-}
-
+import { getChartRenderer } from './charts/registry';
+import { applyColorScaleRange } from './compile/color-scale-range';
+import { filterClippedDomains } from './compile/data-clip';
+import { computeWatermarkObstacle } from './compile/watermark-obstacle';
 import { resolveAnimation } from './compiler/animation';
+import { compile as compileSpec, flattenLayers } from './compiler/index';
 import type { NormalizedChartSpec, NormalizedTableSpec } from './compiler/types';
 import { compileGraph as compileGraphImpl } from './graphs/compile-graph';
 import type { GraphCompilation } from './graphs/types';
@@ -307,6 +270,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     theme = adaptTheme(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)
   const preliminaryArea: Rect = {
     x: 0,
@@ -358,19 +323,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // 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;
-      });
-    }
-  }
+  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;
@@ -379,32 +332,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const scales = computeScales(renderSpec, chartArea, renderSpec.data);
 
   // Update color scale to use theme palette (only when user hasn't provided an explicit range)
-  if (scales.color) {
-    const hasExplicitRange = !!(
-      renderSpec.encoding.color &&
-      'field' in renderSpec.encoding.color &&
-      (renderSpec.encoding.color.scale?.range as string[] | undefined)?.length
-    );
-    if (scales.color.type === 'sequential') {
-      // Sequential: use first sequential palette (or fall back to categorical endpoints)
-      if (!hasExplicitRange) {
-        const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
-        (scales.color.scale as unknown as import('d3-scale').ScaleLinear<string, string>).range([
-          seqStops[0],
-          seqStops[seqStops.length - 1],
-        ]);
-      }
-    } else {
-      if (!hasExplicitRange) {
-        (scales.color.scale as import('d3-scale').ScaleOrdinal<string, string>).range(
-          theme.colors.categorical,
-        );
-      }
-    }
-  }
+  applyColorScaleRange(scales, renderSpec.encoding, theme);
 
-  // Set default color for single-series charts. If the user set a fill on the mark def
-  // (string or gradient), that takes priority over the theme's first categorical color.
+  // 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];
 
   // Arc charts (pie/donut) don't use axes or gridlines
@@ -415,7 +347,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     ? { x: undefined, y: undefined }
     : computeAxes(scales, chartArea, strategy, theme, options.measureText);
 
-  // Compute gridlines (stored in axes, used by adapters via axes.y.gridlines)
+  // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
+  // axes.y.gridlines off the same object. Do not introduce a copy-on-write.
   if (!isRadial) {
     computeGridlines(axes, chartArea);
   }
@@ -444,18 +377,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // Add brand watermark as an obstacle so annotations avoid overlapping it.
-  // The brand is right-aligned on the same baseline as the first bottom chrome element,
-  // offset below the chart area by x-axis extent (tick labels + axis title).
-  if (watermark) {
-    const brandPadding = theme.spacing.padding;
-    const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
-    const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
-    const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
-    const brandY = firstBottomChrome
-      ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
-      : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
-    obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
-  }
+  const watermarkRect = computeWatermarkObstacle(dims, watermark, axes, theme);
+  if (watermarkRect) obstacles.push(watermarkRect);
   const annotations: ResolvedAnnotation[] = computeAnnotations(
     chartSpec,
     scales,

package/src/layout/axes/thinning.ts

@@ -0,0 +1,96 @@
+/**
+ * Tick label overlap detection and density thinning.
+ *
+ * Horizontal orientation (x-axis): checks label width against adjacent
+ * positions. Vertical orientation (y-axis): checks font-based label height
+ * against adjacent positions, ignoring text width so wide numeric labels
+ * don't trigger aggressive thinning.
+ */
+
+import type { AxisTick, MeasureTextFn } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+/**
+ * Minimum gap between adjacent tick labels as a multiple of font size.
+ * At the default 12px axis font, this yields ~12px of breathing room.
+ */
+const MIN_TICK_GAP_FACTOR = 1.0;
+
+/** Always show at least this many ticks, even if they overlap. */
+const MIN_TICK_COUNT = 2;
+
+/** Measure a single label's width using real measurement or heuristic fallback. */
+export function measureLabel(
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): number {
+  return measureText
+    ? measureText(text, fontSize, fontWeight).width
+    : estimateTextWidth(text, fontSize, fontWeight);
+}
+
+/** Check whether any adjacent tick labels overlap along the axis direction. */
+export function ticksOverlap(
+  ticks: AxisTick[],
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+  orientation: 'horizontal' | 'vertical' = 'horizontal',
+): boolean {
+  if (ticks.length < 2) return false;
+  const minGap = fontSize * MIN_TICK_GAP_FACTOR;
+
+  if (orientation === 'vertical') {
+    // Y-axis: labels are stacked vertically. Check if vertical extent
+    // (based on font height) overlaps between adjacent ticks.
+    // Positions decrease going up in SVG coords, so sort ascending.
+    const sorted = [...ticks].sort((a, b) => a.position - b.position);
+    const labelHeight = fontSize * 1.2; // lineHeight
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const aBottom = sorted[i].position + labelHeight / 2;
+      const bTop = sorted[i + 1].position - labelHeight / 2;
+      if (aBottom + minGap > bTop) return true;
+    }
+    return false;
+  }
+
+  for (let i = 0; i < ticks.length - 1; i++) {
+    const aWidth = measureLabel(ticks[i].label, fontSize, fontWeight, measureText);
+    const bWidth = measureLabel(ticks[i + 1].label, fontSize, fontWeight, measureText);
+    const aRight = ticks[i].position + aWidth / 2;
+    const bLeft = ticks[i + 1].position - bWidth / 2;
+    if (aRight + minGap > bLeft) return true;
+  }
+  return false;
+}
+
+/**
+ * Thin a tick array by removing every other tick until labels don't overlap.
+ * Always keeps first and last tick. O(log n) iterations max.
+ * Returns the original array if no thinning is needed.
+ */
+export function thinTicksUntilFit(
+  ticks: AxisTick[],
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+  orientation: 'horizontal' | 'vertical' = 'horizontal',
+): AxisTick[] {
+  if (!ticksOverlap(ticks, fontSize, fontWeight, measureText, orientation)) return ticks;
+
+  let current = ticks;
+  while (current.length > MIN_TICK_COUNT) {
+    // Keep first, last, and every other tick in between
+    const thinned = [current[0]];
+    for (let i = 2; i < current.length - 1; i += 2) {
+      thinned.push(current[i]);
+    }
+    if (current.length > 1) thinned.push(current[current.length - 1]);
+    current = thinned;
+
+    if (!ticksOverlap(current, fontSize, fontWeight, measureText, orientation)) break;
+  }
+  return current;
+}