@opendata-ai/openchart-engine 7.9.3 → 7.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.9.3",
+  "version": "7.10.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "7.9.3",
+    "@opendata-ai/openchart-core": "7.10.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -1365,3 +1365,168 @@ describe('quantitative axis minimum tick floor', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Compact temporal tick formats: pinned pre-change behavior
+// ---------------------------------------------------------------------------
+// These two tests pin the exact tick labels produced BEFORE the compact
+// temporal format rung lands in fitContinuousTicks. They must stay green
+// through that change:
+// - wide desktop axes have room for full-format labels, so compact never fires
+// - temporal y ticks are never compact (planner/renderer gutter agreement;
+//   see plans/compact-temporal-ticks.md)
+
+describe('compact temporal ticks: pinned pre-change output', () => {
+  const monthlyData = Array.from({ length: 12 }, (_, i) => ({
+    date: `2025-${String(i + 1).padStart(2, '0')}-01`,
+    value: 100 + i * 10,
+  }));
+
+  const monthlySpec: NormalizedChartSpec = {
+    ...lineSpec,
+    data: monthlyData,
+  };
+
+  it('desktop unchanged: monthly temporal x at ~900px keeps full-format labels', () => {
+    const wideArea = { x: 50, y: 50, width: 900, height: 300 };
+    const scales = computeScales(monthlySpec, wideArea, monthlySpec.data);
+    const axes = computeAxes(scales, wideArea, fullStrategy, theme);
+
+    expect(axes.x!.ticks.map((t) => t.label)).toEqual(['2025', 'Apr 2025', 'Jul 2025', 'Oct 2025']);
+  });
+
+  it('temporal y-axis unaffected: labels at ~360px stay full-format', () => {
+    const ySpec: NormalizedChartSpec = {
+      ...monthlySpec,
+      markType: 'point',
+      markDef: { type: 'point' },
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'date', type: 'temporal' },
+      },
+    };
+    const narrowArea = { x: 40, y: 40, width: 360, height: 300 };
+    const scales = computeScales(ySpec, narrowArea, ySpec.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    expect(axes.y!.ticks.map((t) => t.label)).toEqual(['2025', 'Apr 2025', 'Jul 2025', 'Oct 2025']);
+  });
+
+  it('temporal y-axis stays full-format even at starved heights (fallback path)', () => {
+    // Regression guard for the fallback path: compact is x-axis-only (the
+    // planner/renderer y pair must format identically), so even a height so
+    // short that fitContinuousTicks falls through to thinning must keep the
+    // year on every label — never a bare compact month like 'Oct'.
+    const ySpec: NormalizedChartSpec = {
+      ...monthlySpec,
+      markType: 'point',
+      markDef: { type: 'point' },
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'date', type: 'temporal' },
+      },
+    };
+    const starvedArea = { x: 40, y: 40, width: 360, height: 55 };
+    const scales = computeScales(ySpec, starvedArea, ySpec.data);
+    const axes = computeAxes(scales, starvedArea, fullStrategy, theme);
+
+    const labels = axes.y!.ticks.map((t) => t.label);
+    expect(labels.length).toBeGreaterThanOrEqual(2);
+    for (const label of labels) {
+      expect(label).toMatch(/\d{4}/);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Compact temporal tick formats: the fitting rung
+// ---------------------------------------------------------------------------
+// When full-format labels overlap on a temporal x-axis, fitContinuousTicks
+// tries the compact format table at the SAME count before dropping ticks.
+// Pre-change counts below were measured by running these exact inputs against
+// the unmodified engine (git stash) — see plans/compact-temporal-ticks.md.
+
+describe('compact temporal ticks: fitting rung', () => {
+  const monthlySpecOver = (
+    months: number,
+    axis?: Record<string, unknown>,
+  ): NormalizedChartSpec => ({
+    ...lineSpec,
+    data: Array.from({ length: months }, (_, i) => ({
+      date: `2025-${String(i + 1).padStart(2, '0')}-01`,
+      value: 100 + i * 10,
+    })),
+    encoding: {
+      x: { field: 'date', type: 'temporal', ...(axis ? { axis } : {}) },
+      y: { field: 'value', type: 'quantitative' },
+    },
+  });
+
+  const xLabelsAt = (spec: NormalizedChartSpec, width: number): string[] => {
+    const area = { x: 40, y: 40, width, height: 300 };
+    const scales = computeScales(spec, area, spec.data);
+    const axes = computeAxes(scales, area, fullStrategy, theme);
+    return axes.x!.ticks.map((t) => t.label);
+  };
+
+  const COMPACT_MONTH = /^[A-Z][a-z]{2}$/; // 'Feb'
+  const FULL_MONTH = /^[A-Z][a-z]{2} \d{4}$/; // 'Feb 2025'
+  const YEAR_ONLY = /^\d{4}$/; // year-boundary tick, same in both tables
+
+  it('keeps more ticks than pre-change when full labels overlap (Jan-Dec 2025 at 160px)', () => {
+    const labels = xLabelsAt(monthlySpecOver(12), 160);
+
+    // Pre-change output at this width: ['2025', 'Oct 2025'] — the overlap
+    // forced a count step-down to 2. Compact keeps all 4 quarterly ticks.
+    expect(labels).toEqual(['2025', 'Apr', 'Jul', 'Oct']);
+    expect(labels.length).toBeGreaterThan(2);
+
+    // No label carries a year except year-boundary ticks.
+    for (const label of labels) {
+      if (/\d{4}/.test(label)) expect(label).toMatch(YEAR_ONLY);
+    }
+  });
+
+  it('renders bare compact months at monthly tick granularity (Jan-Apr 2025 at 160px)', () => {
+    // End the domain mid-April: a domain ending exactly on Apr 1 includes the
+    // Apr tick only when the runner's timezone is UTC (local time scales place
+    // month boundaries at local midnight, so negative offsets push Apr 1 past
+    // the domain end).
+    const base = monthlySpecOver(4);
+    const spec = { ...base, data: [...base.data, { date: '2025-04-15', value: 145 }] };
+    const labels = xLabelsAt(spec, 160);
+
+    // Pre-change output at this width: ['2025', 'Mar 2025'] (2 ticks).
+    expect(labels).toEqual(['2025', 'Feb', 'Mar', 'Apr']);
+    expect(labels).toContain('Feb');
+  });
+
+  it('refit stays internally consistent when D3 overshoots the requested count', () => {
+    // Jan-May 2025: D3 returns 5 monthly ticks for a request of 3 (> the 1.5x
+    // overshoot tolerance), forcing the refit loop. Whatever count/format the
+    // loop lands on, the returned set must be ONE format family — never a mix
+    // of 'Feb' and 'Mar 2025'.
+    const spec = monthlySpecOver(5);
+    for (const width of [100, 140, 180, 240]) {
+      const labels = xLabelsAt(spec, width);
+      const monthLabels = labels.filter((l) => !YEAR_ONLY.test(l));
+      expect(monthLabels.length, `width ${width}`).toBeGreaterThan(0);
+      const allCompact = monthLabels.every((l) => COMPACT_MONTH.test(l));
+      const allFull = monthLabels.every((l) => FULL_MONTH.test(l));
+      expect(
+        allCompact || allFull,
+        `mixed format families at width ${width}: ${JSON.stringify(labels)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('explicit axis.format wins over compact at narrow width', () => {
+    const labels = xLabelsAt(monthlySpecOver(12, { format: '%Y-%m' }), 160);
+
+    expect(labels.length).toBeGreaterThan(0);
+    for (const label of labels) {
+      expect(label).toMatch(/^\d{4}-\d{2}$/);
+    }
+    expect(labels).toEqual(['2025-01', '2025-10']);
+  });
+});

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),
   }));
 }
 
@@ -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

@@ -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,29 +290,32 @@ 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);
 }