@opendata-ai/openchart-engine 7.9.3 → 7.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.9.3",
+  "version": "7.11.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.11.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/__tests__/dimensions.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from 'vitest';
 import { compileChart } from '../compile';
 import type { NormalizedChartSpec } from '../compiler/types';
 import { computeDimensions } from '../layout/dimensions';
+import { INLINE_TICK_OVERHANG_PAD } from '../layout/shared';
 import { legendGap } from '../legend/wrap';
 
 const baseSpec: NormalizedChartSpec = {
@@ -596,16 +597,60 @@ describe('computeDimensions', () => {
     // topAxisGap). This means the chart area gains back ~axisMargin (6px)
     // that would otherwise be redundant spacing.
     //
-    // The top margin with legend includes: legendHeight(28) + legendGap(8)
-    // + inlineTickOverhang(17) instead of the no-legend topAxisGap(23).
-    // Net: margin delta = 28 + 8 + 17 - 23 = 30px.
-    // If axisMargin were doubling up: 28 + 8 + 23 - 23 = 36px.
+    // The top margin with legend includes: gapAbove(6) + legendHeight(28)
+    // + legendGap(8) + inlineTickOverhang(17) instead of the no-legend
+    // topAxisGap(23). Net: margin delta = 6 + 28 + 8 + 17 - 23 = 36px.
+    // If axisMargin were doubling up: 6 + 28 + 8 + 23 - 23 = 42px.
     const topMarginDelta = dimsWithTopLegend.margins.top - dimsNoLegend.margins.top;
     expect(topMarginDelta).toBeLessThan(topLegend.bounds.height + legendGap(600) + 1);
     // With a legend present, the chart area should still be shorter
     expect(dimsWithTopLegend.chartArea.height).toBeLessThan(dimsNoLegend.chartArea.height);
   });
 
+  it('returns effectiveAxisGap on the primary return path', () => {
+    const overhang = lightTheme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD;
+
+    // With a top legend only the inline-tick overhang separates legend and
+    // chart area (placeLegend consumes this to lift the legend above it).
+    const withTopLegend = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      topLegend,
+      lightTheme,
+    );
+    expect(withTopLegend.effectiveAxisGap).toBe(overhang);
+
+    // Without a top legend the full topAxisGap applies.
+    const noLegend = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+    expect(noLegend.effectiveAxisGap).toBe(lightTheme.spacing.axisMargin + overhang);
+  });
+
+  it('returns effectiveAxisGap on the chrome-strip guardrail path', () => {
+    // A cramped height forces the guardrail early-return with stripped chrome.
+    const talkativeSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      chrome: {
+        title: { text: 'A chart title that occupies chrome space' },
+        subtitle: { text: 'A subtitle that gets stripped in compact chrome' },
+        source: { text: 'Source: somewhere' },
+      },
+    };
+    const dims = computeDimensions(
+      talkativeSpec,
+      { width: 600, height: 120 },
+      topLegend,
+      lightTheme,
+    );
+    // Prove the guardrail fired: compact chrome drops the subtitle.
+    expect(dims.chrome.subtitle).toBeUndefined();
+    expect(dims.effectiveAxisGap).toBe(lightTheme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD);
+  });
+
   it('tightens legend gap on narrow viewports', () => {
     const wideDims = computeDimensions(
       baseSpec,

package/src/__tests__/legend.test.ts

@@ -3,6 +3,7 @@ import { resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import { compileChart } from '../compile';
 import type { NormalizedChartSpec } from '../compiler/types';
+import { INLINE_TICK_OVERHANG_PAD } from '../layout/shared';
 import { computeLegend } from '../legend/compute';
 
 const specWithColor: NormalizedChartSpec = {
@@ -510,6 +511,56 @@ describe('computeLegend', () => {
       const gap = layout.area.y - legendBottom;
       expect(gap).toBe(0);
     });
+
+    // Inline y ticks (line/area) draw their topmost label ABOVE chartArea.y,
+    // inside the inlineTickOverhang zone the margin stack reserved. The legend
+    // must sit above that zone, not flush against chartArea.y.
+    const inlineTopLegendSpec = {
+      mark: 'line' as const,
+      data: [
+        { date: '2020-01-01', value: 10, country: 'US' },
+        { date: '2021-01-01', value: 40, country: 'US' },
+        { date: '2020-01-01', value: 15, country: 'UK' },
+        { date: '2021-01-01', value: 35, country: 'UK' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+        color: { field: 'country', type: 'nominal' as const },
+      },
+      legend: { show: true, position: 'top' as const },
+    };
+
+    it('top legend clears the inline y-tick overhang at compact width', () => {
+      const layout = compileChart(inlineTopLegendSpec, { width: 360, height: 400 });
+
+      expect(layout.legend.position).toBe('top');
+      expect(layout.legend.entries.length).toBeGreaterThan(0);
+
+      const inlineTickOverhang = layout.theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD;
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      expect(legendBottom).toBeLessThanOrEqual(layout.area.y - inlineTickOverhang + 1e-6);
+
+      // Pinned placement. Before the fix the legend bottom sat flush at
+      // chartArea.y (legend bottom was 62 = chartArea.y), overlapping the
+      // topmost inline tick label; it now sits the 17px overhang higher,
+      // while the 6px minimum gap above the legend shifts chartArea down.
+      expect(layout.legend.bounds.y).toBe(31);
+    });
+
+    it('gutter y-ticks keep the legend flush at the legendGap (no overhang shift)', () => {
+      // Bar charts use gutter y-tick labels, so inlineTickOverhang is 0 and
+      // the legend keeps its legendGap-only offset from the chart area.
+      const layout = compileChart(topLegendSpec, { width: 600, height: 400 });
+
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      expect(layout.area.y - legendBottom).toBe(8);
+
+      // Pinned placement: 17 before the placement fix; the +6 comes from the
+      // TOP_LEGEND_GAP_ABOVE margin (not from any overhang shift — gutter
+      // ticks have no overhang, so the legend-to-chart gap above stays 8).
+      expect(layout.legend.bounds.y).toBe(23);
+    });
   });
 
   describe('entryPositions contract', () => {

package/src/compile.ts

@@ -640,12 +640,15 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const chartArea = options.frozenChartArea ?? dims.chartArea;
 
   // Place legend in its final position relative to the computed chart area.
+  // effectiveAxisGap lifts a top legend above the inline-tick overhang zone
+  // the margin stack reserved below it.
   const finalLegend = placeLegend(
     plan.legendContent,
     chartArea,
     options.width,
     theme,
     plan.xAxisExtent,
+    dims.effectiveAxisGap,
   );
 
   // Inline y-axis labels: inset the x-scale range start by the widest tick
@@ -898,12 +901,14 @@ function compileFaceted(
   );
   const chartArea = dims.chartArea;
 
+  // Same effectiveAxisGap threading as the regular (non-faceted) path.
   const finalLegend = placeLegend(
     plan.legendContent,
     chartArea,
     options.width,
     theme,
     plan.xAxisExtent,
+    dims.effectiveAxisGap,
   );
 
   // Estimate y-axis gutter width (used as left reservation for outer axes)

package/src/index.ts

@@ -112,6 +112,14 @@ export {
   registerChartRenderer,
 } from './charts/registry';
 
+// ---------------------------------------------------------------------------
+// Legend geometry
+// ---------------------------------------------------------------------------
+
+// Used by the vanilla mount to compute the top-legend block when growing
+// auto-height figures; exporting it keeps the gap math single-sourced.
+export { legendGap } from './legend/wrap';
+
 // ---------------------------------------------------------------------------
 // Data transforms
 // ---------------------------------------------------------------------------

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

package/src/layout/dimensions.ts

@@ -44,7 +44,7 @@ import { format as d3Format } from 'd3-format';
 import type { NormalizedChartSpec } from '../compiler/types';
 import { isEndsBoth, predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { countColorSeries, resolveSuppression } from '../legend/suppression';
-import { legendGap } from '../legend/wrap';
+import { legendGap, TOP_LEGEND_GAP_ABOVE } from '../legend/wrap';
 import { yTickPositionIsInline } from './axes';
 import { computeMetricBar, type MetricFontSizes, metricBarHeight } from './metrics';
 import type { LayoutPlan } from './plan';
@@ -82,6 +82,14 @@ export interface LayoutDimensions {
    * second legend pass) can position elements below the axis row.
    */
   xAxisHeight: number;
+  /**
+   * The axis gap the margin stack placed between the top legend (or chrome,
+   * when there is no top legend) and the chart area. With a top legend this
+   * is the inline-tick overhang, and `placeLegend` must receive it as
+   * `axisGapBelowLegend` so the legend sits above the reserved tick zone
+   * instead of flush against `chartArea.y` (where inline y-tick labels draw).
+   */
+  effectiveAxisGap: number;
 }
 
 /** Minimum chart area dimensions before guardrails kick in. */
@@ -254,7 +262,15 @@ export function computeDimensions(
       height: Math.max(0, height - margins.top - margins.bottom),
     };
 
-    return { total, chrome, chartArea, margins, theme, xAxisHeight: xAxisSpace };
+    return {
+      total,
+      chrome,
+      chartArea,
+      margins,
+      theme,
+      xAxisHeight: xAxisSpace,
+      effectiveAxisGap: 0,
+    };
   }
 
   // Start with the total rect
@@ -664,18 +680,23 @@ export function computeDimensions(
     if (legendPos === 'right' || legendPos === 'bottom-right') {
       margins.right += legendBoundsWidth + 8;
     } else if (legendPos === 'top') {
-      margins.top += legendHeight + gap;
+      // TOP_LEGEND_GAP_ABOVE keeps the legend from sitting flush against the
+      // subtitle/metric bar now that the axis gap sits BELOW the legend.
+      margins.top += TOP_LEGEND_GAP_ABOVE + legendHeight + gap;
     }
     // 'bottom' is intentionally not handled here -- see bottomLegendReservation
     // above.
   }
 
-  // topAxisGap sits between the legend (or chrome, if no legend) and the
-  // chart area. When a top legend is present, the legendGap already provides
-  // breathing room, so only the inlineTickOverhang is needed (the axisMargin
-  // component would double up with legendGap). Without a top legend, the
-  // full topAxisGap (axisMargin + inlineTickOverhang) applies.
-  margins.top += hasTopLegend ? inlineTickOverhang : topAxisGap;
+  // effectiveAxisGap sits between the legend (or chrome, if no legend) and
+  // the chart area. When a top legend is present, the legendGap already
+  // provides breathing room, so only the inlineTickOverhang is needed (the
+  // axisMargin component would double up with legendGap). Without a top
+  // legend, the full topAxisGap (axisMargin + inlineTickOverhang) applies.
+  // The value is returned so placeLegend can position the top legend above
+  // this reserved zone (inline y-tick labels draw inside it).
+  const effectiveAxisGap = hasTopLegend ? inlineTickOverhang : topAxisGap;
+  margins.top += effectiveAxisGap;
 
   // Chart area is what's left after margins
   let chartArea: Rect = {
@@ -719,7 +740,10 @@ export function computeDimensions(
 
     if (topDelta > 0 || bottomDelta > 0) {
       const gap = legendGap(width);
-      margins.top = newTop + (hasTopLegend ? legendHeight + gap : 0) + fallbackEffectiveAxisGap;
+      margins.top =
+        newTop +
+        (hasTopLegend ? TOP_LEGEND_GAP_ABOVE + legendHeight + gap : 0) +
+        fallbackEffectiveAxisGap;
       margins.bottom = newBottom;
 
       chartArea = {
@@ -765,6 +789,7 @@ export function computeDimensions(
         theme,
         metrics: fallbackMetrics,
         xAxisHeight,
+        effectiveAxisGap: fallbackEffectiveAxisGap,
       };
     }
   }
@@ -773,8 +798,9 @@ export function computeDimensions(
   //   topPad
   //   chrome.topHeight              (title / subtitle / eyebrow)
   //   tentativeMetricsHeight        (KPI bar — placed here)
-  //   [optional top legend band]
-  //   topAxisGap                    (axisMargin + inlineTickOverhang)
+  //   [optional top legend band     (TOP_LEGEND_GAP_ABOVE + legend + legendGap)]
+  //   effectiveAxisGap              (inlineTickOverhang with a top legend,
+  //                                  else axisMargin + inlineTickOverhang)
   //   chartArea
   // The metric bar belongs with chrome, above the legend, so its y is
   // computed off chrome.topHeight only — not the full legend-inclusive
@@ -801,6 +827,7 @@ export function computeDimensions(
     theme,
     metrics: resolvedMetrics,
     xAxisHeight,
+    effectiveAxisGap,
   };
 }
 

package/src/layout/plan.ts

@@ -32,7 +32,7 @@ import { format as d3Format } from 'd3-format';
 import type { NormalizedChartSpec } from '../compiler/types';
 import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
 import { computeLegendContent, type LegendContent } from '../legend/compute';
-import { legendGap } from '../legend/wrap';
+import { legendGap, TOP_LEGEND_GAP_ABOVE } from '../legend/wrap';
 import { yTickPositionIsInline } from './axes';
 import { resolveBandTickAngle } from './axes/rotation';
 import { buildContinuousTicks, scaleSupportsTickCount, targetTickCount } from './axes/ticks';
@@ -395,7 +395,8 @@ export function resolveLayoutPlan(
     const effectiveTopAxisGap = hasTopLegend ? inlineTickOverhang : topAxisGap;
 
     let topMargin = topPad + chrome.topHeight;
-    if (hasTopLegend) topMargin += legendContent.height + gap;
+    // Mirrors the dimensions.ts margin stack: min gap above the top legend.
+    if (hasTopLegend) topMargin += TOP_LEGEND_GAP_ABOVE + legendContent.height + gap;
     topMargin += effectiveTopAxisGap;
 
     const bMargin = bottomMargin(chrome.bottomHeight, padding, xAxisExtent);