@opendata-ai/openchart-engine 7.10.0 → 7.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.10.0",
+  "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.10.0",
+    "@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__/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/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);

package/src/legend/compute.ts

@@ -494,6 +494,11 @@ export function computeLegendContent(
  * @param containerWidth - Full container width, used for responsive legend gap.
  * @param _theme - Resolved theme (reserved for future use).
  * @param xAxisHeight - Height of the x-axis, used for bottom legend positioning.
+ * @param axisGapBelowLegend - The `effectiveAxisGap` the margin stack reserved
+ *   between a top legend and the chart area (inline y-tick labels draw in that
+ *   zone, above `chartArea.y`). The top legend is lifted above it so it
+ *   occupies its reserved slot instead of colliding with the topmost tick
+ *   label. Defaults to 0 so other callers/positions are unaffected.
  * @returns Full LegendLayout with bounds.
  */
 export function placeLegend(
@@ -502,6 +507,7 @@ export function placeLegend(
   containerWidth: number,
   _theme: ResolvedTheme,
   xAxisHeight: number,
+  axisGapBelowLegend: number = 0,
 ): LegendLayout {
   const { position, entries, labelStyle, legendWidth, height, offset } = content;
 
@@ -538,7 +544,7 @@ export function placeLegend(
   } else {
     // top
     boundsX = chartArea.x + offsetDx;
-    boundsY = chartArea.y - gap - height + offsetDy;
+    boundsY = chartArea.y - axisGapBelowLegend - gap - height + offsetDy;
   }
 
   const bounds = { x: boundsX, y: boundsY, width: legendWidth, height };

package/src/legend/wrap.ts

@@ -34,6 +34,14 @@ export const ENTRY_GAP_COMPACT = 10;
 /** Default gap between legend bounds and chart area. Zero on narrow viewports. */
 export const LEGEND_GAP = 8;
 
+/**
+ * Minimum gap between the chrome/metrics block above and a top legend.
+ * Without it the legend sits flush against the subtitle (compact widths)
+ * or the metric bar (all widths) once the inline-tick overhang is placed
+ * below the legend where it belongs.
+ */
+export const TOP_LEGEND_GAP_ABOVE = 6;
+
 /** Gap between legend and chart area, responsive to container width. */
 export function legendGap(width: number): number {
   return width < COMPACT_WIDTH ? 0 : LEGEND_GAP;