@opendata-ai/openchart-engine 7.9.2 → 7.10.0

package/src/layout/axes/ticks.ts

@@ -123,16 +123,17 @@ const NUMERIC_SCALE_TYPES = new Set([
 const TEMPORAL_SCALE_TYPES = new Set(['time', 'utc']);
 
 /** Format a tick value based on the scale type. */
-function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
+function formatTickLabel(value: unknown, resolvedScale: ResolvedScale, compact = false): string {
   const axisConfig = resolvedScale.channel.axis || undefined;
   const formatStr = axisConfig?.format;
   const suffix = axisConfig?.labelSuffix ?? '';
 
   if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
+    // Explicit user axis.format always wins, compact or not.
     const temporalFmt = buildTemporalFormatter(formatStr);
     if (temporalFmt) return temporalFmt(value as Date) + suffix;
     const useUtc = resolvedScale.type === 'utc';
-    return formatDate(value as Date, undefined, undefined, useUtc) + suffix;
+    return formatDate(value as Date, undefined, undefined, useUtc, compact) + suffix;
   }
 
   if (NUMERIC_SCALE_TYPES.has(resolvedScale.type)) {
@@ -188,8 +189,15 @@ export function continuousTicks(
  * 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.
+ *
+ * `compact` switches temporal labels to the compact format table (bare '%b'
+ * months etc.); numeric and string labels ignore it.
  */
-export function buildContinuousTicks(resolvedScale: ResolvedScale, count: number): AxisTick[] {
+export function buildContinuousTicks(
+  resolvedScale: ResolvedScale,
+  count: number,
+  compact = false,
+): AxisTick[] {
   const scale = resolvedScale.scale as D3ContinuousScale;
   if (!('ticks' in scale) || typeof scale.ticks !== 'function') {
     return continuousTicks(resolvedScale, 'full');
@@ -220,7 +228,7 @@ export function buildContinuousTicks(resolvedScale: ResolvedScale, count: number
   return ticks.map((value: unknown) => ({
     value,
     position: scale(value as number & Date) as number,
-    label: formatTickLabel(value, resolvedScale),
+    label: formatTickLabel(value, resolvedScale, compact),
   }));
 }
 
@@ -256,8 +264,8 @@ export function categoricalTicks(
   if (resolvedScale.type === 'band' && orientation === 'horizontal') {
     // Horizontal band scales delegate thinning to the caller (computeAxes)
     // which knows the effective label angle after auto-rotation. Only apply
-    // an explicit tickCount cap here; density-based thinning happens
-    // downstream in thinBandTicksIfNeeded where rotation is accounted for.
+    // an explicit tickCount cap here; the angle ladder + stride safety net
+    // (see ./rotation) handle collisions downstream.
     if (explicitTickCount && domain.length > explicitTickCount) {
       const step = Math.ceil(domain.length / explicitTickCount);
       selectedValues = domain.filter((_: string, i: number) => i % step === 0);
@@ -315,7 +323,14 @@ export function categoricalTicks(
   return ticks;
 }
 
-/** Resolve explicit tick values from axis config into positioned ticks. */
+/**
+ * Resolve explicit tick values from axis config into positioned ticks.
+ *
+ * Deliberately never compact: this renders the layout planner's precomputed
+ * ticks, and planner/renderer gutter agreement holds only because both sides
+ * format identically. Making this compact without making the planner compact
+ * recreates the reserved-space divergence bug class behind the 7.9.x saga.
+ */
 export function resolveExplicitTicks(values: unknown[], resolvedScale: ResolvedScale): AxisTick[] {
   const scale = resolvedScale.scale;
   return values.map((value) => {

package/src/layout/axes.ts

@@ -27,7 +27,7 @@ import {
   X_AXIS_TITLE_BAND_ROTATED,
 } from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
-import { resolveBandTickAngle } from './axes/rotation';
+import { bandLabelStride, resolveBandTickAngle } from './axes/rotation';
 import { measureLabel, thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 import {
   buildContinuousTicks,
@@ -208,13 +208,14 @@ function ensureMinContinuousTicks(
   scale: ResolvedScales['x' | 'y'],
   ticks: AxisTick[],
   requestedCount: number,
+  compact = false,
 ): AxisTick[] {
   if (ticks.length >= MIN_QUANTITATIVE_TICKS) return ticks;
   if (!scale || !scaleSupportsTickCount(scale)) return ticks;
 
   let best = ticks;
   for (let n = Math.max(requestedCount, MIN_QUANTITATIVE_TICKS) + 1; n <= 10; n++) {
-    const candidate = buildContinuousTicks(scale, n);
+    const candidate = buildContinuousTicks(scale, n, compact);
     if (candidate.length >= MIN_QUANTITATIVE_TICKS) return candidate;
     if (candidate.length > best.length) best = candidate;
   }
@@ -260,6 +261,27 @@ function fitContinuousTicks(
   const overlaps = ticksOverlap(flooredTicks, fontSize, fontWeight, measureText, orientation);
   if (!overshoots && !overlaps) return flooredTicks;
 
+  // Compact temporal formats are a rung between "full labels overlap" and
+  // "drop a tick": at each candidate count, prefer the full format, then try
+  // the compact table at the SAME count before stepping the count down. Every
+  // returned set is internally consistent — one format family per layout pass.
+  // X-axes only: the planner/renderer y pair must keep formatting identically
+  // (see resolveExplicitTicks), so vertical axes never compact — including
+  // the fallback path below.
+  const useCompact =
+    (scale.type === 'time' || scale.type === 'utc') && orientation === 'horizontal';
+
+  const fitsCleanly = (candidate: AxisTick[]): boolean =>
+    candidate.length <= tolerance &&
+    !ticksOverlap(candidate, fontSize, fontWeight, measureText, orientation);
+
+  // Compact-saves-the-count case: full format overlapped at the initial
+  // count, but compact labels may fit without giving up a single tick.
+  if (useCompact) {
+    const compactAtInitial = buildContinuousTicks(scale, initialCount, true);
+    if (fitsCleanly(compactAtInitial)) return compactAtInitial;
+  }
+
   // 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 =
@@ -268,123 +290,45 @@ function fitContinuousTicks(
 
   // 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.
+  // fallback doesn't reintroduce the cascading-to-2-ticks bug. Bookkeeping
+  // runs against the full-format candidate, exactly as before the compact rung.
   let bestWithinFloor: AxisTick[] | undefined;
+  let bestWithinFloorCount: number | 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;
+    if (fitsCleanly(candidate)) return candidate;
+    if (useCompact) {
+      const compact = buildContinuousTicks(scale, n, true);
+      if (fitsCleanly(compact)) return compact;
+    }
+    if (candidate.length >= floor) {
+      bestWithinFloor = candidate;
+      bestWithinFloorCount = n;
     }
-    if (candidate.length >= floor) bestWithinFloor = candidate;
   }
 
   // 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 rawFallback = bestWithinFloor ?? buildContinuousTicks(scale, floor);
-  const fallback = ensureMinContinuousTicks(scale, rawFallback, floor);
+  // Compacting axes rebuild the fallback compact: if the axis is so starved
+  // that we're thinning below the floor, shorter labels are strictly better.
+  const rawFallback = useCompact
+    ? buildContinuousTicks(scale, bestWithinFloorCount ?? floor, true)
+    : (bestWithinFloor ?? buildContinuousTicks(scale, floor));
+  const fallback = ensureMinContinuousTicks(scale, rawFallback, floor, useCompact);
   return thinTicksUntilFit(fallback, fontSize, fontWeight, measureText, orientation);
 }
 
 /**
- * Horizontal footprint `[left, right]` of a rotated band tick label, in axis
- * pixels. Rotated labels are anchored at the tick position (the rotation
- * pivot), not centered on it: at a negative angle the renderer right-anchors
- * the text so it extends left of the pivot; at a positive angle it left-anchors
- * so it extends right. The horizontal projection is `width * cos(angle)`.
- *
- * Modeling the footprint as centered (the old behavior) over-estimates each
- * label's reach by half its width in the wrong direction, which made a single
- * wide label (e.g. "2026 (to wk 17)") report overlaps against neighbors that
- * actually clear it — triggering needless thinning of the whole axis.
+ * Apply the uniform band-label stride (see bandLabelStride in ./axes/rotation):
+ * keep every Nth label counting back from the LAST one, so the most recent
+ * category is always labeled. Stride 1 — the overwhelmingly common case once
+ * the angle ladder has run — keeps everything.
  */
-function labelSpanAtAngle(
-  tick: AxisTick,
-  angleDeg: number,
-  fontSize: number,
-  fontWeight: number,
-  measureText?: MeasureTextFn,
-): { left: number; right: number } {
-  const angleRad = (Math.abs(angleDeg) * Math.PI) / 180;
-  const cosA = angleRad > 0 ? Math.abs(Math.cos(angleRad)) : 1;
-  const projected = measureLabel(tick.label, fontSize, fontWeight, measureText) * cosA;
-  if (angleDeg === 0) {
-    // Horizontal labels are centered on the tick.
-    return { left: tick.position - projected / 2, right: tick.position + projected / 2 };
-  }
-  if (angleDeg < 0) {
-    // Right-anchored: pivot is the right edge, text extends left.
-    return { left: tick.position - projected, right: tick.position };
-  }
-  // Left-anchored: pivot is the left edge, text extends right.
-  return { left: tick.position, right: tick.position + projected };
-}
-
-/**
- * Thin band-scale tick labels only where they actually collide at their
- * effective angle, greedily keeping every label that clears the last one
- * retained. This preserves narrow labels that have room even when a single
- * wide label elsewhere on the axis forces some thinning near it, instead of
- * decimating the whole axis every-other. First and last labels are always
- * kept. Most grouped bar charts keep every label even at -45°.
- */
-function thinBandTicksIfNeeded(
-  ticks: AxisTick[],
-  angleDeg: number,
-  fontSize: number,
-  fontWeight: number,
-  measureText?: MeasureTextFn,
-): AxisTick[] {
-  if (ticks.length < 3) return ticks;
-  const minGap = fontSize * 0.5;
-
-  const spans = ticks.map((t) => labelSpanAtAngle(t, angleDeg, fontSize, fontWeight, measureText));
-
-  // Greedy left-to-right retention: keep a label only if its footprint clears
-  // the last kept label's right edge by minGap. Always keep the first label.
-  const keep = new Array<boolean>(ticks.length).fill(false);
-  keep[0] = true;
-  let lastRight = spans[0].right;
-  for (let i = 1; i < ticks.length; i++) {
-    if (spans[i].left >= lastRight + minGap) {
-      keep[i] = true;
-      lastRight = spans[i].right;
-    }
-  }
-
-  // Always keep the last label. If keeping it collides with previously kept
-  // labels, drop each colliding neighbor so the endpoint stays labeled. A very
-  // wide final label (long category name) projects across several bands at an
-  // angle, so clear every kept label its footprint overlaps, not just the
-  // nearest one — otherwise an earlier kept label still overlaps the endpoint.
-  //
-  // Use true pixel overlap here (no minGap comfort buffer) so a neighbor that
-  // merely falls a few pixels short of the comfort gap — but does not actually
-  // touch the endpoint label — is kept rather than sacrificed. Dropping a
-  // readable short label to seat a near-miss wide endpoint reads as arbitrary
-  // (e.g. losing "2025" beside "2026 (to wk 17)" that clears it by 2px).
+function applyBandLabelStride(ticks: AxisTick[], stride: number): AxisTick[] {
+  if (stride <= 1 || ticks.length < 3) return ticks;
   const lastIdx = ticks.length - 1;
-  if (!keep[lastIdx]) {
-    keep[lastIdx] = true;
-    for (let i = lastIdx - 1; i > 0; i--) {
-      if (!keep[i]) continue;
-      if (spans[i].right > spans[lastIdx].left) {
-        keep[i] = false;
-        continue;
-      }
-      break;
-    }
-  }
-
-  return ticks.filter((_, i) => keep[i]);
+  return ticks.filter((_, i) => (lastIdx - i) % stride === 0);
 }
 
 // ---------------------------------------------------------------------------
@@ -511,17 +455,40 @@ export function computeAxes(
       major: true,
     }));
 
-    // Determine rotation before thinning so we know the effective label
-    // footprint. Band scales auto-rotate when horizontal labels don't fit.
+    // Band-label policy: choose the shallowest angle at which every label
+    // fits (flat → -45° → -90°), then apply the uniform stride safety net —
+    // stride 1 (keep everything) except at extreme category counts. See
+    // ./axes/rotation for the geometry.
     let tickAngle = axisConfig?.labelAngle;
-    if (tickAngle === undefined && scales.x.type === 'band' && allTicks.length > 1) {
-      const bandwidth = (scales.x.scale as ScaleBand<string>).bandwidth();
+    let bandStride = 1;
+    if (scales.x.type === 'band' && allTicks.length > 1) {
+      const bandScale = scales.x.scale as ScaleBand<string>;
+      const bandwidth = bandScale.bandwidth();
+      // Anchor spacing between the ticks actually drawn — not the raw band
+      // step. categoricalTicks may have applied an explicit tickCount cap, so
+      // retained ticks can sit a multiple of the step apart, and explicit
+      // axis.values subsets can be non-uniform: collision geometry cares
+      // about the closest adjacent pair.
+      let anchorSpacing = Number.POSITIVE_INFINITY;
+      for (let i = 1; i < allTicks.length; i++) {
+        const d = Math.abs(allTicks[i].position - allTicks[i - 1].position);
+        if (d > 0 && d < anchorSpacing) anchorSpacing = d;
+      }
+      if (!Number.isFinite(anchorSpacing)) anchorSpacing = bandScale.step();
       let maxLabelWidth = 0;
       for (const t of allTicks) {
         const w = measureLabel(t.label, fontSize, fontWeight, measureText);
         if (w > maxLabelWidth) maxLabelWidth = w;
       }
-      tickAngle = resolveBandTickAngle(undefined, maxLabelWidth, bandwidth, allTicks.length);
+      tickAngle = resolveBandTickAngle(
+        axisConfig?.labelAngle,
+        maxLabelWidth,
+        bandwidth,
+        allTicks.length,
+        anchorSpacing,
+        fontSize,
+      );
+      bandStride = bandLabelStride(maxLabelWidth, tickAngle, fontSize, anchorSpacing);
     }
 
     // Thin tick labels to prevent overlap (skip for explicit tick values).
@@ -530,10 +497,7 @@ export function computeAxes(
     if (hasExplicitValues) {
       ticks = allTicks;
     } else if (scales.x.type === 'band') {
-      // Band scales: thin only when labels actually overlap at their
-      // effective angle. After rotation, most charts have room for every label.
-      const effectiveAngle = tickAngle ?? 0;
-      ticks = thinBandTicksIfNeeded(allTicks, effectiveAngle, fontSize, fontWeight, measureText);
+      ticks = applyBandLabelStride(allTicks, bandStride);
     } else if (isContinuousX) {
       ticks = fitContinuousTicks(
         scales.x,

package/src/layout/plan.ts

@@ -36,7 +36,7 @@ import { legendGap } from '../legend/wrap';
 import { yTickPositionIsInline } from './axes';
 import { resolveBandTickAngle } from './axes/rotation';
 import { buildContinuousTicks, scaleSupportsTickCount, targetTickCount } from './axes/ticks';
-import { computeScales, estimateBandwidth } from './scales';
+import { computeScales, estimateBandStep, estimateBandwidth } from './scales';
 import { bottomMargin, chromeToInput, INLINE_TICK_OVERHANG_PAD, scalePadding } from './shared';
 
 // ---------------------------------------------------------------------------
@@ -342,8 +342,21 @@ export function resolveLayoutPlan(
       // bandwidth = step * (1 - paddingInner). Uses the same override resolution
       // as buildBandScale so paddingInner/paddingOuter are honored here too.
       const bandwidth = estimateBandwidth(encoding.x?.scale, plotWidth, xLabels.length);
+      const step = estimateBandStep(encoding.x?.scale, plotWidth, xLabels.length);
+      // Mirror categoricalTicks' explicit tickCount cap: retained ticks sit a
+      // multiple of the band step apart, so the drawn labels and their anchor
+      // spacing — not the full category set — drive the angle here, matching
+      // what computeAxes measures from actual tick positions.
+      const xTickCount = xAxis?.tickCount as number | undefined;
+      let drawnLabels = xLabels;
+      let anchorSpacing = step;
+      if (xTickCount && xLabels.length > xTickCount) {
+        const capStride = Math.ceil(xLabels.length / xTickCount);
+        drawnLabels = xLabels.filter((_, i) => i % capStride === 0);
+        anchorSpacing = step * capStride;
+      }
       let maxXLabelWidth = 0;
-      for (const label of xLabels) {
+      for (const label of drawnLabels) {
         const w = measure(label, theme.fonts.sizes.axisTick, theme.fonts.weights.normal);
         if (w > maxXLabelWidth) maxXLabelWidth = w;
       }
@@ -351,7 +364,9 @@ export function resolveLayoutPlan(
         undefined,
         maxXLabelWidth,
         bandwidth,
-        xLabels.length,
+        drawnLabels.length,
+        anchorSpacing,
+        theme.fonts.sizes.axisTick,
       );
     }
 

package/src/layout/scales.ts

@@ -470,19 +470,43 @@ function evenRange(start: number, end: number, count: number): number[] {
  * each independently. step = width / (n - paddingInner + 2*paddingOuter);
  * bandwidth = step * (1 - paddingInner).
  */
+/** d3 scaleBand padding resolution: `padding` sets both, overrides win. */
+function resolveBandPadding(scaleConfig: EncodingChannel['scale'] | undefined): {
+  paddingInner: number;
+  paddingOuter: number;
+} {
+  const padding = scaleConfig?.padding ?? 0.35;
+  return {
+    paddingInner: scaleConfig?.paddingInner ?? padding,
+    paddingOuter: scaleConfig?.paddingOuter ?? padding,
+  };
+}
+
 export function estimateBandwidth(
   scaleConfig: EncodingChannel['scale'] | undefined,
   plotWidth: number,
   n: number,
+): number {
+  const { paddingInner } = resolveBandPadding(scaleConfig);
+  return estimateBandStep(scaleConfig, plotWidth, n) * (1 - paddingInner);
+}
+
+/**
+ * Estimate d3 scaleBand step (center-to-center band distance) for a given
+ * plot width and category count, using the same padding resolution as
+ * estimateBandwidth. The step — not the bandwidth — is the anchor spacing
+ * that drives rotated-label collision checks.
+ */
+export function estimateBandStep(
+  scaleConfig: EncodingChannel['scale'] | undefined,
+  plotWidth: number,
+  n: number,
 ): number {
   if (n <= 0) return 0;
-  const padding = scaleConfig?.padding ?? 0.35;
-  const paddingInner = scaleConfig?.paddingInner ?? padding;
-  const paddingOuter = scaleConfig?.paddingOuter ?? padding;
+  const { paddingInner, paddingOuter } = resolveBandPadding(scaleConfig);
   const denom = n - paddingInner + 2 * paddingOuter;
   if (denom <= 0) return 0;
-  const step = plotWidth / denom;
-  return step * (1 - paddingInner);
+  return plotWidth / denom;
 }
 
 function buildBandScale(