@opendata-ai/openchart-engine 6.20.0 → 6.22.0

package/src/layout/axes.ts

@@ -2,7 +2,8 @@
  * Axis computation: tick positions, labels, and axis lines.
  *
  * Generates ticks manually (no d3-axis) so we have full control over
- * responsive tick density and formatting.
+ * responsive tick density and formatting. Tick generation and label
+ * thinning live in sibling modules under ./axes/.
  */
 
 import type {
@@ -16,33 +17,26 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import {
-  abbreviateNumber,
-  buildD3Formatter,
-  buildTemporalFormatter,
-  estimateTextWidth,
-  formatDate,
-  formatNumber,
-} from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
-import type {
-  D3CategoricalScale,
-  D3ContinuousScale,
-  ResolvedScale,
-  ResolvedScales,
-} from './scales';
+import { measureLabel, thinTicksUntilFit, ticksOverlap } from './axes/thinning';
+import {
+  buildContinuousTicks,
+  categoricalTicks,
+  continuousTicks,
+  resolveExplicitTicks,
+  scaleSupportsTickCount,
+  targetTickCount,
+} from './axes/ticks';
+import type { ResolvedScales } from './scales';
+
+// Re-export pure helpers so external consumers (and tests) continue to import
+// them from './layout/axes'.
+export { thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Base tick counts by axis label density. */
-const TICK_COUNTS: Record<AxisLabelDensity, number> = {
-  full: 12,
-  reduced: 8,
-  minimal: 4,
-};
-
 /**
  * Height thresholds for reducing y-axis tick density.
  * Below these pixel heights, we step down the density regardless of the
@@ -59,15 +53,6 @@ const HEIGHT_REDUCED_THRESHOLD = 200;
 const WIDTH_MINIMAL_THRESHOLD = 150;
 const WIDTH_REDUCED_THRESHOLD = 300;
 
-/**
- * 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;
-
 /** Ordered densities from most to fewest ticks. */
 const DENSITY_ORDER: AxisLabelDensity[] = ['full', 'reduced', 'minimal'];
 
@@ -106,217 +91,94 @@ export function effectiveDensity(
   return density;
 }
 
-// ---------------------------------------------------------------------------
-// Label overlap detection and thinning
-// ---------------------------------------------------------------------------
-
-/** Measure a single label's width using real measurement or heuristic fallback. */
-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;
-  }
+/**
+ * Floor tick count for continuous axes when the axis is long enough to show
+ * more than a min/max pair. Keeps the editorial ~5 target when possible.
+ * Very short axes bypass this floor and can legitimately fall to 2.
+ */
+const CONTINUOUS_TICK_FLOOR = 4;
 
-  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;
-}
+/**
+ * How much D3 is allowed to overshoot what we asked for before we treat the
+ * output as "too dense" and step down. D3's `scale.ticks(n)` only produces
+ * nice step sizes (1, 2, 5 × 10^k, or calendar units for time), so a request
+ * for n=6 can come back with 12 quarterly dates or 10 step-5 values. Accepting
+ * up to 1.5× target catches the obvious overshoots without trimming acceptable
+ * ones.
+ *
+ * The reference point stays fixed to the initial requested count even as we
+ * iterate downward — we're measuring "did this candidate land near the target
+ * the caller actually wanted?", not "is the candidate near what we just asked
+ * for on this iteration?". If a candidate at n=3 returns 8 ticks, it's still
+ * a 1.3× overshoot of the target-6, which is fine.
+ */
+const OVERSHOOT_TOLERANCE = 1.5;
 
 /**
- * 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.
+ * Fit continuous ticks by re-requesting progressively fewer ticks from the
+ * scale. D3's `scale.ticks(n)` always returns evenly-spaced round values, so
+ * stepping `n` down keeps spacing uniform — unlike middle-pruning which can
+ * strand the last tick next to an endpoint and cascade to 2 ticks.
+ *
+ * Two conditions trigger a step-down:
+ *   1. The label heuristic detects overlap at the initial count.
+ *   2. D3 overshot the requested count by more than OVERSHOOT_TOLERANCE.
+ *      (Time scales jump between calendar units; linear scales jump between
+ *      nice step sizes. Either can return 2× what we asked for.)
+ *
+ * Falls back to overlap-safe thinning on the best-so-far candidate if no
+ * count produces a clean fit. The fallback starts from the smallest candidate
+ * that still meets the floor, so `thinTicksUntilFit` never receives the
+ * overshot initial set (which was the bug this function exists to avoid).
  */
-export function thinTicksUntilFit(
-  ticks: AxisTick[],
+function fitContinuousTicks(
+  scale: ResolvedScales['x' | 'y'],
+  initialTicks: AxisTick[],
+  initialCount: number,
   fontSize: number,
   fontWeight: number,
+  axisLength: number,
+  orientation: 'horizontal' | 'vertical',
   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;
-}
-
-// ---------------------------------------------------------------------------
-// Tick generation
-// ---------------------------------------------------------------------------
-
-/** Generate ticks for a continuous scale (linear, time, log, pow, sqrt, symlog). */
-function continuousTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): 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 ?? TICK_COUNTS[density];
-  const rawTicks: unknown[] = scale.ticks(count);
-
-  const ticks = rawTicks.map((value: unknown) => ({
-    value,
-    position: scale(value as number & Date) as number,
-    label: formatTickLabel(value, resolvedScale),
-  }));
-
-  return ticks;
-}
-
-/** Generate ticks for a band/point/ordinal scale. */
-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;
-}
-
-/** 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);
+  if (!scale || !scaleSupportsTickCount(scale)) return initialTicks;
+
+  const tolerance = initialCount * OVERSHOOT_TOLERANCE;
+  const overshoots = initialTicks.length > tolerance;
+  const overlaps = ticksOverlap(initialTicks, fontSize, fontWeight, measureText, orientation);
+  if (!overshoots && !overlaps) return initialTicks;
+
+  // Enforce the floor only when the axis is long enough to fit that many
+  // labels without overlap. Very short axes can fall below.
+  const minThreshold =
+    orientation === 'vertical' ? HEIGHT_MINIMAL_THRESHOLD : WIDTH_MINIMAL_THRESHOLD;
+  const floor = axisLength >= minThreshold ? CONTINUOUS_TICK_FLOOR : 2;
+
+  // Track the smallest candidate that meets the floor. If no candidate fits
+  // cleanly, we thin this instead of the overshot `initialTicks` so the
+  // fallback doesn't reintroduce the cascading-to-2-ticks bug.
+  let bestWithinFloor: AxisTick[] | undefined;
+  for (let n = initialCount - 1; n >= 2; n--) {
+    const candidate = buildContinuousTicks(scale, n);
+    const candidateOvershoots = candidate.length > tolerance;
+    const candidateOverlaps = ticksOverlap(
+      candidate,
+      fontSize,
+      fontWeight,
+      measureText,
+      orientation,
+    );
+    if (!candidateOvershoots && !candidateOverlaps) {
+      return candidate;
     }
-    // Abbreviate large numbers for axis labels
-    if (Math.abs(num) >= 1000) return abbreviateNumber(num);
-    return formatNumber(num);
+    if (candidate.length >= floor) bestWithinFloor = candidate;
   }
 
-  return String(value);
-}
-
-/** Resolve explicit tick values from axis config into positioned ticks. */
-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),
-    };
-  });
+  // No candidate fit cleanly. Thin whatever most recently met the floor; if
+  // nothing did, synthesize a floor-count set directly from the scale so we
+  // never hand the overshot initialTicks to the middle-pruning thinner.
+  const fallback = bestWithinFloor ?? buildContinuousTicks(scale, floor);
+  return thinTicksUntilFit(fallback, fontSize, fontWeight, measureText, orientation);
 }
 
 // ---------------------------------------------------------------------------
@@ -385,19 +247,21 @@ export function computeAxes(
 
   if (scales.x) {
     const axisConfig = scales.x.channel.axis;
+    const isContinuousX =
+      scales.x.type !== 'band' && scales.x.type !== 'point' && scales.x.type !== 'ordinal';
+
+    const xTargetCount = isContinuousX
+      ? targetTickCount(chartArea.width, xDensity, 'x')
+      : undefined;
 
     // Use explicit tick values from axis config if provided
     let allTicks: AxisTick[];
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.x);
-    } else if (
-      scales.x.type === 'band' ||
-      scales.x.type === 'point' ||
-      scales.x.type === 'ordinal'
-    ) {
+    } else if (!isContinuousX) {
       allTicks = categoricalTicks(scales.x, xDensity);
     } else {
-      allTicks = continuousTicks(scales.x, xDensity);
+      allTicks = continuousTicks(scales.x, xDensity, xTargetCount);
     }
 
     // Gridlines use the full tick set so they remain visible even when labels
@@ -410,9 +274,25 @@ export function computeAxes(
     // Thin tick labels to prevent overlap (skip for band scales which use
     // auto-rotation, and when the user set an explicit tickCount or values).
     const shouldThin = scales.x.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
-    const ticks = shouldThin
-      ? thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText)
-      : allTicks;
+    let ticks: AxisTick[];
+    if (!shouldThin) {
+      ticks = allTicks;
+    } else if (isContinuousX) {
+      // Continuous x-axis: re-request ticks at a lower count on overlap so
+      // time-scale quartile/monthly jumps don't leave a too-dense axis.
+      ticks = fitContinuousTicks(
+        scales.x,
+        allTicks,
+        xTargetCount ?? allTicks.length,
+        fontSize,
+        fontWeight,
+        chartArea.width,
+        'horizontal',
+        measureText,
+      );
+    } else {
+      ticks = thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText);
+    }
 
     // Auto-rotate labels when band scale labels would overlap.
     // Uses max label width (not average) since one long label is enough to overlap.
@@ -454,26 +334,45 @@ export function computeAxes(
 
   if (scales.y) {
     const axisConfig = scales.y.channel.axis;
+    const isContinuousY =
+      scales.y.type !== 'band' && scales.y.type !== 'point' && scales.y.type !== 'ordinal';
+
+    // Target count from pixels-per-tick when we have a continuous y-axis.
+    const yTargetCount = isContinuousY
+      ? targetTickCount(chartArea.height, yDensity, 'y')
+      : undefined;
 
     // Use explicit tick values from axis config if provided
     let allTicks: AxisTick[];
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.y);
-    } else if (
-      scales.y.type === 'band' ||
-      scales.y.type === 'point' ||
-      scales.y.type === 'ordinal'
-    ) {
+    } else if (!isContinuousY) {
       allTicks = categoricalTicks(scales.y, yDensity);
     } else {
-      allTicks = continuousTicks(scales.y, yDensity);
+      allTicks = continuousTicks(scales.y, yDensity, yTargetCount);
     }
 
     // Thin tick labels to prevent overlap (skip for band scales, explicit tickCount, and values).
     const shouldThin = scales.y.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
-    const ticks = shouldThin
-      ? thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText, 'vertical')
-      : allTicks;
+    let ticks: AxisTick[];
+    if (!shouldThin) {
+      ticks = allTicks;
+    } else if (isContinuousY) {
+      // Continuous y-axis: re-request ticks at a lower count on overlap so
+      // spacing stays uniform and we don't collapse to min/max.
+      ticks = fitContinuousTicks(
+        scales.y,
+        allTicks,
+        yTargetCount ?? allTicks.length,
+        fontSize,
+        fontWeight,
+        chartArea.height,
+        'vertical',
+        measureText,
+      );
+    } else {
+      ticks = thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText, 'vertical');
+    }
 
     // Gridlines match the tick set so every gridline has a label.
     const gridlines: Gridline[] = ticks.map((t) => ({