@opendata-ai/openchart-engine 7.2.4 → 7.3.0

package/src/compile.ts

@@ -3,8 +3,9 @@
  *
  * Pipeline for charts:
  *   validate spec -> normalize -> resolve theme -> dark mode adapt ->
- *   compute legend -> compute dimensions (with legend space) ->
- *   compute scales -> compute axes -> compute gridlines ->
+ *   filter data -> resolveLayoutPlan (measure real labels) ->
+ *   compute dimensions (with plan) -> placeLegend ->
+ *   compute scales -> compute axes (with pinned ticks) -> compute gridlines ->
  *   get chart renderer -> compute marks -> compute a11y -> return ChartLayout
  *
  * Table compiler handles full data pipeline (sort, search, pagination, visual enhancements).
@@ -23,7 +24,6 @@ import type {
   EncodingChannel,
   LayerSpec,
   Mark,
-  Rect,
   ResolvedAnnotation,
   ResolvedTheme,
   TableLayout,
@@ -34,7 +34,6 @@ import type {
 import {
   adaptTheme,
   computeLabelBounds,
-  estimateTextWidth,
   generateAltText,
   generateDataTable,
   getBreakpoint,
@@ -42,8 +41,9 @@ import {
   getLayoutStrategy,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
 import { computeAnnotations } from './annotations/compute';
+import { type AnnotationMeasureTextFn, heuristicMeasure } from './annotations/geometry';
+import type { PlacementObstacle } from './annotations/placement';
 import { computeEndpointLabels } from './endpoint-labels/compute';
 // Side-effect import: registers all built-in chart renderers with the
 // registry on module load. Tests that clear the registry can import
@@ -74,9 +74,9 @@ import type { GraphCompilation } from './graphs/types';
 import { computeAxes } from './layout/axes';
 import { computeDimensions } from './layout/dimensions';
 import { computeGridlines } from './layout/gridlines';
+import { createMeasureFn, resolveLayoutPlan } from './layout/plan';
 import { computeScales } from './layout/scales';
-import { computeLegend } from './legend/compute';
-import { legendGap } from './legend/wrap';
+import { placeLegend } from './legend/compute';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
 import { compileTileMap as compileTileMapImpl } from './tilemap/compile-tilemap';
@@ -533,70 +533,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     chartSpec = applySparklineDefaults(chartSpec, theme);
   }
 
-  // INVARIANT 1 — double legend pass: preliminaryArea → computeDimensions → legendArea → final
-  // legend. Breaks a dims/legend dependency cycle. Do not collapse into one call.
-  // Compute legend first (needs to reserve space)
-  const preliminaryArea: Rect = {
-    x: 0,
-    y: 0,
-    width: options.width,
-    height: options.height,
-  };
-  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea, watermark);
-
-  // Compute dimensions (accounts for chrome + legend + responsive strategy)
-  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy, watermark);
-  const chartArea = dims.chartArea;
-
-  // Recompute legend bounds relative to actual chart area.
-  // chartArea was shrunk to exclude legend space, so expand it back to include
-  // the reserved margin. This way computeLegend positions the legend outside
-  // the data area (in the margin) instead of overlapping data marks.
-  //
-  // Top/bottom legends align their left edge to the plot area (chartArea.x),
-  // so the legend sits above/below the y-axis guide rather than flush against
-  // the container edge.
-  //
-  // Width runs from the new left origin (chartArea.x) to the container's right
-  // padding, so the rendered legend never paints past the right edge / over the
-  // endpoint-label column. This is narrower than the first pass (which used the
-  // full container at preliminaryArea.width = options.width), so on a chart with
-  // BOTH a wide y-axis gutter AND a legend that nearly fills its row, the second
-  // pass can wrap to one more row than the first pass reserved in margins.top —
-  // the extra row protrudes slightly into the chrome gap. That graceful failure
-  // (a few px of vertical crowding, still on-canvas) is preferable to the
-  // alternative (chips clipped off the right edge of the SVG). The maxRows cap
-  // (default 2 for top legends) bounds the worst case to a single extra row.
-  const legendArea: Rect = { ...chartArea };
-  if ('entries' in legendLayout && legendLayout.entries.length > 0) {
-    const legendInnerWidth = options.width - theme.spacing.padding - chartArea.x;
-    const gap = legendGap(options.width);
-    switch (legendLayout.position) {
-      case 'top':
-        legendArea.x = chartArea.x;
-        legendArea.width = legendInnerWidth;
-        legendArea.y -= legendLayout.bounds.height + gap;
-        legendArea.height += legendLayout.bounds.height + gap;
-        break;
-      case 'bottom':
-        legendArea.x = chartArea.x;
-        legendArea.width = legendInnerWidth;
-        // Bottom legend sits below the x-axis tick row, not over it. Expand
-        // legendArea by xAxisHeight + legendHeight + gap so the bottom-anchored
-        // legend lands beneath the axis. Mirrors dimensions.ts which reserved
-        // the same xAxisHeight in margins.bottom.
-        legendArea.height += legendLayout.bounds.height + gap + dims.xAxisHeight;
-        break;
-      case 'right':
-      case 'bottom-right':
-        legendArea.width += legendLayout.bounds.width + 8;
-        break;
-    }
-  }
-  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea, watermark);
-
-  // Apply data filtering after legend (so legend retains all series), but before
-  // scale computation (so hidden/clipped data doesn't affect domains or marks).
+  // ---------------------------------------------------------------------------
+  // Data filtering: move BEFORE layout plan so the plan measures real labels
+  // from the filtered data set. Legend retains all series via chartSpec
+  // (unfiltered); scales and marks use renderSpec (filtered).
+  // ---------------------------------------------------------------------------
   let renderData = chartSpec.data;
 
   // Filter hidden series: removed from rendering but kept in legend (dimmed in the adapter)
@@ -619,7 +560,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Lock the color scale domain to the unfiltered series list so palette
   // assignments stay stable across legend toggles. Without this, hiding a
   // series shrinks the ordinal scale's domain and shifts every remaining
-  // series down one palette index — the visible lines would mismatch the
+  // series down one palette index -- the visible lines would mismatch the
   // legend swatches that still represent the original assignment.
   // Skipped when the user already supplied an explicit domain.
   const colorEnc = chartSpec.encoding.color;
@@ -644,73 +585,53 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     };
   }
 
-  // Inline y-axis labels render at chartArea.x with text-anchor=start. Without
-  // an inset the leftmost data point on a line/area would clip through the
-  // label glyphs (since the line begins at chartArea.x too). Inset the x-scale
-  // range start by the widest tick label width so the data starts to the right
-  // of the labels. Axes/gridlines still span the full chart area, so inline
-  // labels stay flush left where the design intends.
-  const yEnc = renderSpec.encoding?.y;
-  const yAxisCfgInline =
-    typeof yEnc?.axis === 'object' && yEnc.axis !== null
-      ? (yEnc.axis as Record<string, unknown>)
-      : undefined;
-  const yIsContinuous = yEnc?.type === 'quantitative' || yEnc?.type === 'temporal';
-  const isLineOrArea = renderSpec.markType === 'line' || renderSpec.markType === 'area';
-  const yInlineExplicit = yAxisCfgInline?.tickPosition as 'inline' | 'gutter' | undefined;
-  // Sparkline mode hides the y-axis by default, so the inline-label inset
-  // would shrink the data range without any labels actually being drawn —
-  // the line ends up starting ~30px from the left edge for no visible
-  // reason. Skip the inset unless the user explicitly opted into the
-  // y-axis (in which case the labels do render and the inset is needed).
-  const sparklineSuppressesYAxis =
-    chartSpec.display === 'sparkline' && !chartSpec.userExplicit.yAxis;
-  const yIsInline =
-    !sparklineSuppressesYAxis &&
-    (yInlineExplicit === 'inline' ||
-      (yInlineExplicit === undefined &&
-        isLineOrArea &&
-        yIsContinuous &&
-        yAxisCfgInline?.orient !== 'right'));
+  // ---------------------------------------------------------------------------
+  // Layout plan: measure real labels, freeze gutter + chrome + legend content
+  // ---------------------------------------------------------------------------
+  const measure = createMeasureFn(options.measureText);
+  const plan = resolveLayoutPlan(
+    chartSpec,
+    renderSpec,
+    options,
+    theme,
+    strategy,
+    watermark,
+    measure,
+  );
+
+  // Compute dimensions (accounts for chrome + legend + responsive strategy).
+  // The plan provides measured leftGutter, xAxisExtent, and chrome so
+  // dimensions.ts skips its guess blocks.
+  const legendStub = placeLegend(
+    plan.legendContent,
+    { x: 0, y: 0, width: options.width, height: options.height },
+    options.width,
+    theme,
+    plan.xAxisExtent,
+  );
+  const dims = computeDimensions(chartSpec, options, legendStub, theme, strategy, watermark, plan);
+  const chartArea = dims.chartArea;
+
+  // Place legend in its final position relative to the computed chart area.
+  const finalLegend = placeLegend(
+    plan.legendContent,
+    chartArea,
+    options.width,
+    theme,
+    plan.xAxisExtent,
+  );
+
+  // Inline y-axis labels: inset the x-scale range start by the widest tick
+  // label width so data marks start to the right of the labels. The plan
+  // already measured the real tick labels.
   let scaleArea = chartArea;
-  if (yIsInline && yEnc && yIsContinuous && yEnc.axis !== false) {
-    const yField = yEnc.field;
-    const yFmt = yAxisCfgInline?.format as string | undefined;
-    let maxAbsVal = 0;
-    for (const row of renderSpec.data) {
-      const v = Number(row[yField]);
-      if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
-    }
-    let sample: string;
-    if (yFmt) {
-      try {
-        sample = d3Format(yFmt)(maxAbsVal);
-      } catch {
-        sample = String(maxAbsVal);
-      }
-    } else if (maxAbsVal >= 1_000_000_000) sample = '1.5B';
-    else if (maxAbsVal >= 1_000_000) sample = '1.5M';
-    else if (maxAbsVal >= 1_000) sample = '1.5K';
-    else if (maxAbsVal >= 100) sample = '100';
-    else if (maxAbsVal >= 10) sample = '10';
-    else sample = '0.0';
-    const negPrefix = renderSpec.data.some((r) => Number(r[yField]) < 0) ? '-' : '';
-    const labelEst = negPrefix + sample;
-    const labelWidth = estimateTextWidth(
-      labelEst,
-      theme.fonts.sizes.axisTick,
-      theme.fonts.weights.normal,
-    );
-    const INLINE_LABEL_BREATHING_ROOM = 8;
-    const inset = Math.ceil(labelWidth + INLINE_LABEL_BREATHING_ROOM);
-    if (inset > 0 && inset < chartArea.width) {
-      scaleArea = {
-        x: chartArea.x + inset,
-        y: chartArea.y,
-        width: chartArea.width - inset,
-        height: chartArea.height,
-      };
-    }
+  if (plan.inlineYLabelInset > 0 && plan.inlineYLabelInset < chartArea.width) {
+    scaleArea = {
+      x: chartArea.x + plan.inlineYLabelInset,
+      y: chartArea.y,
+      width: chartArea.width - plan.inlineYLabelInset,
+      height: chartArea.height,
+    };
   }
 
   // Compute scales
@@ -719,7 +640,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Update color scale to use theme palette (only when user hasn't provided an explicit range)
   applyColorScaleRange(scales, renderSpec.encoding, theme);
 
-  // INVARIANT 3 — post-hoc defaultColor: must run AFTER computeScales since resolution needs
+  // INVARIANT 3 -- post-hoc defaultColor: must run AFTER computeScales since resolution needs
   // theme context. Do not move into computeScales (would require threading theme through).
   // fill wins for bar/area/arc marks; stroke wins for line marks (the stroke IS the color).
   scales.defaultColor =
@@ -741,8 +662,14 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
         skipX,
         skipY,
         markType: chartSpec.markType,
+        totalWidth: options.width,
+        precomputedYTicks: plan.yTickValues.length > 0 ? plan.yTickValues : undefined,
       });
 
+  // Intentional post-hoc mutation: axes must resolve before we know the x-axis extent.
+  const xAxisExtent = axes.x?.extent ?? 0;
+  dims.chrome.bottomAnchorY = chartArea.y + chartArea.height + xAxisExtent;
+
   // INVARIANT 2 — computeGridlines mutates `axes` in place. Downstream consumers read
   // axes.y.gridlines off the same object. Do not introduce a copy-on-write.
   if (!isRadial) {
@@ -764,31 +691,41 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const endpointLabels = computeEndpointLabels(chartSpec, marks, theme, chartArea, strategy);
 
   // Compute annotations from spec, passing legend + mark + brand bounds as obstacles
-  const obstacles: Rect[] = [];
+  const obstacles: PlacementObstacle[] = [];
   if (finalLegend.bounds.width > 0) {
-    obstacles.push(finalLegend.bounds);
+    obstacles.push({ ...finalLegend.bounds, kind: 'legend' });
   }
   obstacles.push(...computeMarkObstacles(marks, scales));
 
   // Add visible data label bounds as obstacles so annotations avoid overlapping them
   for (const mark of marks) {
     if ('label' in mark && mark.label?.visible) {
-      obstacles.push(computeLabelBounds(mark.label));
+      obstacles.push({ ...computeLabelBounds(mark.label), kind: 'data-label' });
     }
   }
 
   // Add brand watermark as an obstacle so annotations avoid overlapping it.
   const watermarkRect = computeWatermarkObstacle(dims, watermark, axes, theme);
-  if (watermarkRect) obstacles.push(watermarkRect);
-  const annotations: ResolvedAnnotation[] = computeAnnotations(
-    chartSpec,
+  if (watermarkRect) obstacles.push({ ...watermarkRect, kind: 'watermark' });
+
+  // Add endpoint label bounds as obstacles
+  if (endpointLabels.entries.length > 0 && endpointLabels.bounds.width > 0) {
+    obstacles.push({ ...endpointLabels.bounds, kind: 'endpoint-label' });
+  }
+
+  const annotationMeasure: AnnotationMeasureTextFn = options.measureText
+    ? (text, font) => options.measureText!(text, font.fontSize, font.fontWeight).width
+    : heuristicMeasure;
+
+  const annotations: ResolvedAnnotation[] = computeAnnotations(chartSpec, {
     scales,
     chartArea,
     strategy,
-    theme.isDark,
+    isDark: theme.isDark,
     obstacles,
-    { width: dims.total.width, height: dims.total.height },
-  );
+    svg: { width: dims.total.width, height: dims.total.height },
+    measure: annotationMeasure,
+  });
 
   // Compute tooltip descriptors from marks and encoding
   const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);

package/src/index.ts

@@ -53,6 +53,15 @@ export type { NormalizedBarListSpec } from './barlist/types';
 
 export type { NormalizedTileMapSpec } from './tilemap/types';
 
+// ---------------------------------------------------------------------------
+// Annotations
+// ---------------------------------------------------------------------------
+
+export type { AnnotationContext } from './annotations/compute';
+export type { AnnotationMeasureTextFn } from './annotations/geometry';
+export { heuristicMeasure } from './annotations/geometry';
+export type { ObstacleKind, PlacementObstacle } from './annotations/placement';
+
 // ---------------------------------------------------------------------------
 // Compiler pipeline (spec validation, normalization, generic compile)
 // ---------------------------------------------------------------------------

package/src/layout/axes.ts

@@ -19,6 +19,13 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
+import {
+  axisTitleOffset,
+  computeXAxisExtentFromLabels,
+  estimateTextWidth,
+  getAxisTitleOffset,
+  X_AXIS_TITLE_BAND_ROTATED,
+} from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
 import { measureLabel, thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 import {
@@ -273,6 +280,15 @@ export interface AxesDataContext {
    * marks default to `'gutter'`.
    */
   markType?: import('@opendata-ai/openchart-core').MarkType;
+  /** Total container width for axis title offset threshold checks. */
+  totalWidth?: number;
+  /**
+   * Pinned y-axis tick values from the layout plan. When provided, the y-axis
+   * uses these values (via resolveExplicitTicks) instead of generating fresh
+   * ticks, so the labels match exactly what the gutter was measured for.
+   * User-specified `axis.values` still takes priority.
+   */
+  precomputedYTicks?: unknown[];
 }
 
 /**
@@ -440,6 +456,15 @@ export function computeAxes(
     let allTicks: AxisTick[];
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.y);
+    } else if (
+      dataContext?.precomputedYTicks &&
+      dataContext.precomputedYTicks.length > 0 &&
+      isContinuousY
+    ) {
+      // Pinned ticks from the layout plan -- use the same resolution path as
+      // explicit user values so the labels match exactly what the gutter was
+      // measured for.
+      allTicks = resolveExplicitTicks(dataContext.precomputedYTicks, scales.y);
     } else if (!isContinuousY) {
       const yFieldName = dataContext?.encoding.y?.field;
       const yLabelField = axisConfig?.labelField;
@@ -458,7 +483,8 @@ export function computeAxes(
     // Thin tick labels to prevent overlap (skip for band scales and explicit tick values).
     // When tickCount is set, we still thin if D3 overshot the requested count
     // (common with log scales where ticks(4) can return 26 values).
-    const shouldThinY = scales.y.type !== 'band' && !axisConfig?.values;
+    const shouldThinY =
+      scales.y.type !== 'band' && !axisConfig?.values && !dataContext?.precomputedYTicks?.length;
     let ticks: AxisTick[];
     if (!shouldThinY) {
       ticks = allTicks;
@@ -525,5 +551,71 @@ export function computeAxes(
     };
   }
 
+  const totalWidth = dataContext?.totalWidth ?? chartArea.x + chartArea.width;
+
+  if (result.x) {
+    let rotatedHeight: number | undefined;
+    if (result.x.tickAngle && Math.abs(result.x.tickAngle) > 10) {
+      const angleRad = Math.abs(result.x.tickAngle) * (Math.PI / 180);
+      let maxLabelWidth = 40;
+      for (const tick of result.x.ticks) {
+        const w = estimateTextWidth(
+          tick.label,
+          result.x.tickLabelStyle.fontSize,
+          result.x.tickLabelStyle.fontWeight,
+        );
+        if (w > maxLabelWidth) maxLabelWidth = w;
+      }
+      rotatedHeight = Math.min(maxLabelWidth * Math.sin(angleRad) + 6, 120);
+    }
+
+    if (rotatedHeight != null) {
+      result.x.extent = result.x.label ? rotatedHeight + X_AXIS_TITLE_BAND_ROTATED : rotatedHeight;
+    } else {
+      result.x.extent = computeXAxisExtentFromLabels({
+        labels: result.x.ticks.map((t) => t.label),
+        tickAngle: result.x.tickAngle,
+        hasTitle: !!result.x.label,
+        tickFontSize: result.x.tickLabelStyle.fontSize,
+        tickFontWeight: result.x.tickLabelStyle.fontWeight,
+        xAxisHeight: theme.spacing.xAxisHeight,
+      });
+    }
+
+    if (result.x.label) {
+      result.x.titlePosition = {
+        x: chartArea.x + chartArea.width / 2,
+        y: chartArea.y + chartArea.height + (rotatedHeight != null ? rotatedHeight + 14 : 35),
+      };
+    }
+  }
+
+  if (result.y?.label && result.y.labelStyle) {
+    const isRight = result.y.orient === 'right';
+    if (isRight) {
+      const titleOff = getAxisTitleOffset(totalWidth);
+      result.y.titlePosition = {
+        x: chartArea.x + chartArea.width + titleOff,
+        y: chartArea.y + chartArea.height / 2,
+        angle: 90,
+      };
+    } else {
+      const maxTickLabelWidth = result.y.ticks.reduce((max, t) => {
+        const w = estimateTextWidth(
+          t.label,
+          result.y!.tickLabelStyle.fontSize,
+          result.y!.tickLabelStyle.fontWeight ?? 400,
+        );
+        return Math.max(max, w);
+      }, 0);
+      const titleOff = axisTitleOffset(maxTickLabelWidth, result.y.labelStyle.fontSize, totalWidth);
+      result.y.titlePosition = {
+        x: chartArea.x - titleOff,
+        y: chartArea.y + chartArea.height / 2,
+        angle: -90,
+      };
+    }
+  }
+
   return result;
 }