@opendata-ai/openchart-engine 6.19.3 → 6.21.0

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;
+}

package/src/layout/axes/ticks.ts

@@ -0,0 +1,266 @@
+/**
+ * Tick generation: produces raw AxisTick[] from a resolved scale.
+ *
+ * Pure with respect to layout dimensions — positions come from the scale,
+ * not from the chart area. Density thinning lives in ./thinning.ts.
+ */
+
+import type { AxisLabelDensity, AxisTick } from '@opendata-ai/openchart-core';
+import {
+  abbreviateNumber,
+  buildD3Formatter,
+  buildTemporalFormatter,
+  formatDate,
+  formatNumber,
+} from '@opendata-ai/openchart-core';
+import type { ScaleBand } from 'd3-scale';
+import type { D3CategoricalScale, D3ContinuousScale, ResolvedScale } from '../scales';
+
+/**
+ * Target pixels-per-tick for continuous axes. The target count is computed as
+ * `axisLength / PX_PER_TICK[density]` and then clamped into the count range.
+ *
+ * Rationale:
+ * - Observable Plot uses 50px/tick on y, 80px/tick on x as its baseline.
+ * - ONS editorial guidance recommends 6-10 y-gridlines at desktop, 3-6 mobile.
+ * - The Economist / FT / NYT typically show 4-6 labeled y-ticks on finished charts.
+ *
+ * Y gets tighter spacing than X because vertical label extent is the font height
+ * (~14px) versus horizontal label extent which can be 60-100px for dates/abbreviated
+ * numbers. X uses wider spacing so labels don't need aggressive rotation or thinning.
+ *
+ * "full" is the publication-ready default; "reduced" and "minimal" step down as the
+ * responsive breakpoint system shifts to smaller containers.
+ *
+ * @internal — these are tuning constants, not part of the configuration API.
+ * Consumers should configure tick density through `axis.tickCount` on the spec.
+ */
+const Y_PX_PER_TICK: Record<AxisLabelDensity, number> = {
+  full: 55,
+  reduced: 90,
+  minimal: 140,
+};
+
+const X_PX_PER_TICK: Record<AxisLabelDensity, number> = {
+  full: 110,
+  reduced: 160,
+  minimal: 220,
+};
+
+/**
+ * Count clamps per density. The lower bound keeps a chart from collapsing to
+ * a single label on very short axes; the upper bound stops tall/wide charts
+ * from growing a ladder of ticks past the point of editorial usefulness.
+ *
+ * The upper bound is deliberately <=6 for y on standard tiers: D3's
+ * `scale.ticks(n)` only produces "nice" step sizes (1, 2, 5 × 10^k), and for
+ * many domains the jump from step=10 to step=5 happens between count 6 and 7.
+ * Requesting 7 can give back 10, which reads as visually dense. Capping at 6
+ * keeps the editorial ~5 gridline average regardless of domain shape.
+ *
+ * @internal — see PX_PER_TICK comment.
+ */
+const Y_TICK_COUNT_RANGE: Record<AxisLabelDensity, [number, number]> = {
+  full: [4, 6],
+  reduced: [3, 5],
+  minimal: [2, 3],
+};
+
+const X_TICK_COUNT_RANGE: Record<AxisLabelDensity, [number, number]> = {
+  full: [3, 6],
+  reduced: [3, 5],
+  minimal: [2, 3],
+};
+
+/**
+ * Fallback tick counts for callers that don't have an axis length handy
+ * (categorical band-scale thinning uses this as a cap, and `continuousTicks`
+ * uses it when no `targetCount` is provided).
+ *
+ * @internal
+ */
+const TICK_COUNTS: Record<AxisLabelDensity, number> = {
+  full: 7,
+  reduced: 5,
+  minimal: 3,
+};
+
+/**
+ * Compute a target tick count for a continuous axis from its pixel length and
+ * density tier. Uses the Plot-style pixels-per-tick heuristic, then clamps
+ * into the density's count range.
+ */
+export function targetTickCount(
+  axisLength: number,
+  density: AxisLabelDensity,
+  orientation: 'x' | 'y',
+): number {
+  const pxPerTick = orientation === 'y' ? Y_PX_PER_TICK[density] : X_PX_PER_TICK[density];
+  const [min, max] =
+    orientation === 'y' ? Y_TICK_COUNT_RANGE[density] : X_TICK_COUNT_RANGE[density];
+  const raw = Math.round(axisLength / pxPerTick);
+  return Math.max(min, Math.min(max, raw));
+}
+
+/** Set of continuous numeric scale types that should format as numbers. */
+const NUMERIC_SCALE_TYPES = new Set([
+  'linear',
+  'log',
+  'pow',
+  'sqrt',
+  'symlog',
+  'quantile',
+  'quantize',
+  'threshold',
+]);
+
+/** Set of temporal scale types. */
+const TEMPORAL_SCALE_TYPES = new Set(['time', 'utc']);
+
+/** Format a tick value based on the scale type. */
+function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
+  const formatStr = resolvedScale.channel.axis?.format;
+
+  if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
+    const temporalFmt = buildTemporalFormatter(formatStr);
+    if (temporalFmt) return temporalFmt(value as Date);
+    const useUtc = resolvedScale.type === 'utc';
+    return formatDate(value as Date, undefined, undefined, useUtc);
+  }
+
+  if (NUMERIC_SCALE_TYPES.has(resolvedScale.type)) {
+    const num = value as number;
+    if (formatStr) {
+      const fmt = buildD3Formatter(formatStr);
+      if (fmt) return fmt(num);
+    }
+    // Abbreviate large numbers for axis labels
+    if (Math.abs(num) >= 1000) return abbreviateNumber(num);
+    return formatNumber(num);
+  }
+
+  return String(value);
+}
+
+/**
+ * Generate ticks for a continuous scale (linear, time, log, pow, sqrt, symlog).
+ *
+ * `targetCount` lets callers that know the axis pixel length pass a
+ * density-appropriate count (see `targetTickCount`). When omitted, falls back
+ * to the coarse `TICK_COUNTS` tier, which is only used by tests and callers
+ * that don't have an axis length.
+ */
+export function continuousTicks(
+  resolvedScale: ResolvedScale,
+  density: AxisLabelDensity,
+  targetCount?: number,
+): AxisTick[] {
+  const scale = resolvedScale.scale as D3ContinuousScale;
+
+  // Discretizing scales (quantile, quantize, threshold) don't have .ticks().
+  // Use their domain thresholds as ticks instead.
+  if (!('ticks' in scale) || typeof scale.ticks !== 'function') {
+    const domain = scale.domain() as unknown[];
+    return domain.map((value: unknown) => ({
+      value,
+      position: (scale as D3ContinuousScale)(value as number & Date) as number,
+      label: formatTickLabel(value, resolvedScale),
+    }));
+  }
+
+  const explicitCount = resolvedScale.channel.axis?.tickCount;
+  const count = explicitCount ?? targetCount ?? TICK_COUNTS[density];
+  return buildContinuousTicks(resolvedScale, count);
+}
+
+/**
+ * Build positioned, labeled ticks for a continuous scale at an exact count.
+ * Exposed so callers that need to re-request ticks at a lower count (for
+ * overlap-driven density adaptation) can regenerate without manual pruning.
+ * D3's `scale.ticks(n)` always returns evenly-spaced round values, so
+ * requesting a smaller `n` never produces squished neighbors — unlike
+ * "keep first+last, drop middle" pruning which can stack the last tick
+ * next to an endpoint and cascade to 2 ticks.
+ */
+export function buildContinuousTicks(resolvedScale: ResolvedScale, count: number): AxisTick[] {
+  const scale = resolvedScale.scale as D3ContinuousScale;
+  if (!('ticks' in scale) || typeof scale.ticks !== 'function') {
+    return continuousTicks(resolvedScale, 'full');
+  }
+  const raw: unknown[] = scale.ticks(count);
+  return raw.map((value: unknown) => ({
+    value,
+    position: scale(value as number & Date) as number,
+    label: formatTickLabel(value, resolvedScale),
+  }));
+}
+
+/** True if this scale supports regenerating ticks at an arbitrary count. */
+export function scaleSupportsTickCount(resolvedScale: ResolvedScale): boolean {
+  const scale = resolvedScale.scale as D3ContinuousScale;
+  return 'ticks' in scale && typeof scale.ticks === 'function';
+}
+
+/** Generate ticks for a band/point/ordinal scale. */
+export function categoricalTicks(
+  resolvedScale: ResolvedScale,
+  density: AxisLabelDensity,
+): AxisTick[] {
+  const scale = resolvedScale.scale as D3CategoricalScale;
+  const domain: string[] = scale.domain();
+  const explicitTickCount = resolvedScale.channel.axis?.tickCount;
+  const maxTicks = explicitTickCount ?? TICK_COUNTS[density];
+
+  // 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' || explicitTickCount) && domain.length > maxTicks) {
+    const step = Math.ceil(domain.length / maxTicks);
+    selectedValues = domain.filter((_: string, i: number) => i % step === 0);
+  }
+
+  const ticks = selectedValues.map((value: string) => {
+    // Band scales: use the center of the band
+    const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
+    const pos = bandScale
+      ? (bandScale(value) ?? 0) + bandScale.bandwidth() / 2
+      : ((scale(value) as number | undefined) ?? 0);
+
+    return {
+      value,
+      position: pos,
+      label: value,
+    };
+  });
+
+  return ticks;
+}
+
+/** Resolve explicit tick values from axis config into positioned ticks. */
+export function resolveExplicitTicks(values: unknown[], resolvedScale: ResolvedScale): AxisTick[] {
+  const scale = resolvedScale.scale;
+  return values.map((value) => {
+    let position: number;
+    if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
+      const d = value instanceof Date ? value : new Date(String(value));
+      position = (scale as D3ContinuousScale)(d as number & Date) as number;
+    } else if (
+      resolvedScale.type === 'band' ||
+      resolvedScale.type === 'point' ||
+      resolvedScale.type === 'ordinal'
+    ) {
+      const s = String(value);
+      const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
+      position = bandScale
+        ? (bandScale(s) ?? 0) + bandScale.bandwidth() / 2
+        : ((scale(s as string & number) as number | undefined) ?? 0);
+    } else {
+      position = (scale as D3ContinuousScale)(value as number & Date) as number;
+    }
+    return {
+      value,
+      position,
+      label: formatTickLabel(value, resolvedScale),
+    };
+  });
+}