@opendata-ai/openchart-engine 2.9.1 → 2.11.0

package/src/compile.ts

@@ -25,9 +25,12 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
+  BRAND_RESERVE_WIDTH,
+  computeLabelBounds,
   generateAltText,
   generateDataTable,
   getBreakpoint,
+  getHeightClass,
   getLayoutStrategy,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
@@ -74,14 +77,41 @@ import { computeTooltipDescriptors } from './tooltips/compute';
 // ---------------------------------------------------------------------------
 
 /**
- * Compute per-row bounding rects for band-scale charts (dot, bar).
- * Each obstacle covers the full band height and x-range of marks in that row,
- * giving the annotation nudge system awareness of data marks.
+ * Compute bounding rects from marks to use as obstacles for annotation nudging.
+ *
+ * For band-scale charts (bar, dot): groups marks by band row and returns
+ * a single obstacle per row spanning the full band height and x-range.
+ *
+ * For other charts (column, scatter): returns individual mark bounds so
+ * annotations avoid overlapping any visible data mark.
  */
-function computeRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
-  if (!scales.y || scales.y.type !== 'band') return [];
+function computeMarkObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
+  // Band-scale y-axis: group marks by row for efficient obstacle computation
+  if (scales.y?.type === 'band') {
+    return computeBandRowObstacles(marks, scales);
+  }
+
+  // All other charts: use individual rect/point mark bounds as obstacles
+  const obstacles: Rect[] = [];
+  for (const mark of marks) {
+    if (mark.type === 'rect') {
+      const rm = mark as RectMark;
+      obstacles.push({ x: rm.x, y: rm.y, width: rm.width, height: rm.height });
+    } else if (mark.type === 'point') {
+      const pm = mark as PointMark;
+      obstacles.push({
+        x: pm.cx - pm.r,
+        y: pm.cy - pm.r,
+        width: pm.r * 2,
+        height: pm.r * 2,
+      });
+    }
+  }
+  return obstacles;
+}
 
-  // Group marks by their y-center (rounded), compute x-extent per group
+/** Group band-scale marks by row, returning one obstacle per band. */
+function computeBandRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
   const rows = new Map<number, { minX: number; maxX: number; bandY: number }>();
 
   for (const mark of marks) {
@@ -115,7 +145,7 @@ function computeRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
   }
 
   // Get bandwidth from the band scale
-  const bandScale = scales.y.scale as { bandwidth?: () => number };
+  const bandScale = scales.y!.scale as { bandwidth?: () => number };
   const bandwidth = bandScale.bandwidth?.() ?? 0;
   if (bandwidth === 0) return [];
 
@@ -163,7 +193,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
 
   // Responsive strategy
   const breakpoint = getBreakpoint(options.width);
-  const strategy = getLayoutStrategy(breakpoint);
+  const heightClass = getHeightClass(options.height);
+  const strategy = getLayoutStrategy(breakpoint, heightClass);
 
   // Apply breakpoint-conditional overrides from the original spec
   const rawSpec = spec as Record<string, unknown>;
@@ -230,8 +261,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   };
   const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea);
 
-  // Compute dimensions (accounts for chrome + legend)
-  const dims = computeDimensions(chartSpec, options, legendLayout, theme);
+  // Compute dimensions (accounts for chrome + legend + responsive strategy)
+  const dims = computeDimensions(chartSpec, options, legendLayout, theme, strategy);
   const chartArea = dims.chartArea;
 
   // Recompute legend bounds relative to actual chart area.
@@ -313,7 +344,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Compute axes (skip for radial charts)
   const axes = isRadial
     ? { x: undefined, y: undefined }
-    : computeAxes(scales, chartArea, strategy, theme);
+    : computeAxes(scales, chartArea, strategy, theme, options.measureText);
 
   // Compute gridlines (stored in axes, used by adapters via axes.y.gridlines)
   if (!isRadial) {
@@ -324,12 +355,31 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const renderer = getChartRenderer(renderSpec.type);
   const marks: Mark[] = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme) : [];
 
-  // Compute annotations from spec, passing legend + mark bounds as obstacles for collision avoidance
+  // Compute annotations from spec, passing legend + mark + brand bounds as obstacles
   const obstacles: Rect[] = [];
   if (finalLegend.bounds.width > 0) {
     obstacles.push(finalLegend.bounds);
   }
-  obstacles.push(...computeRowObstacles(marks, scales));
+  obstacles.push(...computeMarkObstacles(marks, scales));
+
+  // Add visible data label bounds as obstacles so annotations avoid overlapping them
+  for (const mark of marks) {
+    if (mark.type !== 'area' && mark.label?.visible) {
+      obstacles.push(computeLabelBounds(mark.label));
+    }
+  }
+
+  // Add brand watermark as an obstacle so annotations avoid overlapping it.
+  // The brand is right-aligned on the same baseline as the first bottom chrome element,
+  // offset below the chart area by x-axis extent (tick labels + axis title).
+  const brandPadding = theme.spacing.padding;
+  const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
+  const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
+  const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
+  const brandY = firstBottomChrome
+    ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
+    : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
+  obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
   const annotations: ResolvedAnnotation[] = computeAnnotations(
     chartSpec,
     scales,

package/src/layout/axes.ts

@@ -11,6 +11,7 @@ import type {
   AxisTick,
   Gridline,
   LayoutStrategy,
+  MeasureTextFn,
   Rect,
   ResolvedTheme,
   TextStyle,
@@ -18,6 +19,7 @@ import type {
 import {
   abbreviateNumber,
   buildD3Formatter,
+  estimateTextWidth,
   formatDate,
   formatNumber,
 } from '@opendata-ai/openchart-core';
@@ -56,6 +58,15 @@ const HEIGHT_REDUCED_THRESHOLD = 200;
 const WIDTH_MINIMAL_THRESHOLD = 150;
 const WIDTH_REDUCED_THRESHOLD = 300;
 
+/**
+ * Minimum gap between adjacent tick labels as a multiple of font size.
+ * At the default 12px axis font, this yields ~12px of breathing room.
+ */
+const MIN_TICK_GAP_FACTOR = 1.0;
+
+/** Always show at least this many ticks, even if they overlap. */
+const MIN_TICK_COUNT = 2;
+
 /** Ordered densities from most to fewest ticks. */
 const DENSITY_ORDER: AxisLabelDensity[] = ['full', 'reduced', 'minimal'];
 
@@ -94,25 +105,106 @@ export function effectiveDensity(
   return density;
 }
 
+// ---------------------------------------------------------------------------
+// Label overlap detection and thinning
+// ---------------------------------------------------------------------------
+
+/** Measure a single label's width using real measurement or heuristic fallback. */
+function measureLabel(
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): number {
+  return measureText
+    ? measureText(text, fontSize, fontWeight).width
+    : estimateTextWidth(text, fontSize, fontWeight);
+}
+
+/** Check whether any adjacent tick labels overlap horizontally. */
+export function ticksOverlap(
+  ticks: AxisTick[],
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): boolean {
+  if (ticks.length < 2) return false;
+  const minGap = fontSize * MIN_TICK_GAP_FACTOR;
+  for (let i = 0; i < ticks.length - 1; i++) {
+    const aWidth = measureLabel(ticks[i].label, fontSize, fontWeight, measureText);
+    const bWidth = measureLabel(ticks[i + 1].label, fontSize, fontWeight, measureText);
+    const aRight = ticks[i].position + aWidth / 2;
+    const bLeft = ticks[i + 1].position - bWidth / 2;
+    if (aRight + minGap > bLeft) return true;
+  }
+  return false;
+}
+
+/**
+ * Thin a tick array by removing every other tick until labels don't overlap.
+ * Always keeps first and last tick. O(log n) iterations max.
+ * Returns the original array if no thinning is needed.
+ */
+export function thinTicksUntilFit(
+  ticks: AxisTick[],
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): AxisTick[] {
+  if (!ticksOverlap(ticks, fontSize, fontWeight, measureText)) return ticks;
+
+  let current = ticks;
+  while (current.length > MIN_TICK_COUNT) {
+    // Keep first, last, and every other tick in between
+    const thinned = [current[0]];
+    for (let i = 2; i < current.length - 1; i += 2) {
+      thinned.push(current[i]);
+    }
+    if (current.length > 1) thinned.push(current[current.length - 1]);
+    current = thinned;
+
+    if (!ticksOverlap(current, fontSize, fontWeight, measureText)) break;
+  }
+  return current;
+}
+
 // ---------------------------------------------------------------------------
 // Tick generation
 // ---------------------------------------------------------------------------
 
 /** Generate ticks for a continuous scale (linear, time, log). */
-function continuousTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
+function continuousTicks(
+  resolvedScale: ResolvedScale,
+  density: AxisLabelDensity,
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): AxisTick[] {
   const scale = resolvedScale.scale as D3ContinuousScale;
-  const count = resolvedScale.channel.axis?.tickCount ?? TICK_COUNTS[density];
-  const ticks: unknown[] = scale.ticks(count);
+  const explicitCount = resolvedScale.channel.axis?.tickCount;
+  const count = explicitCount ?? TICK_COUNTS[density];
+  const rawTicks: unknown[] = scale.ticks(count);
 
-  return ticks.map((value: unknown) => ({
+  const ticks = rawTicks.map((value: unknown) => ({
     value,
     position: scale(value as number & Date) as number,
     label: formatTickLabel(value, resolvedScale),
   }));
+
+  // Respect explicit tickCount: user asked for this many, don't override
+  if (explicitCount) return ticks;
+
+  return thinTicksUntilFit(ticks, fontSize, fontWeight, measureText);
 }
 
 /** Generate ticks for a band/point/ordinal scale. */
-function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
+function categoricalTicks(
+  resolvedScale: ResolvedScale,
+  density: AxisLabelDensity,
+  fontSize: number,
+  fontWeight: number,
+  measureText?: MeasureTextFn,
+): AxisTick[] {
   const scale = resolvedScale.scale as D3CategoricalScale;
   const domain: string[] = scale.domain();
   const explicitTickCount = resolvedScale.channel.axis?.tickCount;
@@ -126,7 +218,7 @@ function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensit
     selectedValues = domain.filter((_: string, i: number) => i % step === 0);
   }
 
-  return selectedValues.map((value: string) => {
+  const ticks = selectedValues.map((value: string) => {
     // Band scales: use the center of the band
     const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
     const pos = bandScale
@@ -139,6 +231,13 @@ function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensit
       label: value,
     };
   });
+
+  // For non-band scales without explicit tickCount, thin based on label width
+  if (resolvedScale.type !== 'band' && !explicitTickCount) {
+    return thinTicksUntilFit(ticks, fontSize, fontWeight, measureText);
+  }
+
+  return ticks;
 }
 
 /** Format a tick value based on the scale type. */
@@ -181,12 +280,14 @@ export interface AxesResult {
  * @param chartArea - The chart drawing area.
  * @param strategy - Responsive layout strategy.
  * @param theme - Resolved theme for styling.
+ * @param measureText - Optional real text measurement from the adapter.
  */
 export function computeAxes(
   scales: ResolvedScales,
   chartArea: Rect,
   strategy: LayoutStrategy,
   theme: ResolvedTheme,
+  measureText?: MeasureTextFn,
 ): AxesResult {
   const result: AxesResult = {};
   const baseDensity = strategy.axisLabelDensity;
@@ -223,24 +324,43 @@ export function computeAxes(
     lineHeight: 1.3,
   };
 
+  const { fontSize } = tickLabelStyle;
+  const { fontWeight } = tickLabelStyle;
+
   if (scales.x) {
     const ticks =
       scales.x.type === 'band' || scales.x.type === 'point' || scales.x.type === 'ordinal'
-        ? categoricalTicks(scales.x, xDensity)
-        : continuousTicks(scales.x, xDensity);
+        ? categoricalTicks(scales.x, xDensity, fontSize, fontWeight, measureText)
+        : continuousTicks(scales.x, xDensity, fontSize, fontWeight, measureText);
 
     const gridlines: Gridline[] = ticks.map((t) => ({
       position: t.position,
       major: true,
     }));
 
+    // Auto-rotate labels when band scale labels would overlap.
+    // Uses max label width (not average) since one long label is enough to overlap.
+    let tickAngle = scales.x.channel.axis?.tickAngle;
+    if (tickAngle === undefined && scales.x.type === 'band' && ticks.length > 1) {
+      const bandwidth = (scales.x.scale as ScaleBand<string>).bandwidth();
+      let maxLabelWidth = 0;
+      for (const t of ticks) {
+        const w = measureLabel(t.label, fontSize, fontWeight, measureText);
+        if (w > maxLabelWidth) maxLabelWidth = w;
+      }
+      // If the widest label exceeds 85% of the bandwidth, rotate to avoid overlap
+      if (maxLabelWidth > bandwidth * 0.85) {
+        tickAngle = -45;
+      }
+    }
+
     result.x = {
       ticks,
       gridlines: scales.x.channel.axis?.grid ? gridlines : [],
       label: scales.x.channel.axis?.label,
       labelStyle: axisLabelStyle,
       tickLabelStyle,
-      tickAngle: scales.x.channel.axis?.tickAngle,
+      tickAngle,
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
     };
@@ -249,8 +369,8 @@ export function computeAxes(
   if (scales.y) {
     const ticks =
       scales.y.type === 'band' || scales.y.type === 'point' || scales.y.type === 'ordinal'
-        ? categoricalTicks(scales.y, yDensity)
-        : continuousTicks(scales.y, yDensity);
+        ? categoricalTicks(scales.y, yDensity, fontSize, fontWeight, measureText)
+        : continuousTicks(scales.y, yDensity, fontSize, fontWeight, measureText);
 
     const gridlines: Gridline[] = ticks.map((t) => ({
       position: t.position,

package/src/layout/dimensions.ts

@@ -5,11 +5,16 @@
  * LayoutDimensions with the total area, chrome layout, chart drawing area,
  * and margins. The chart area is what's left after subtracting chrome,
  * legend space, and axis margins.
+ *
+ * Padding and chrome scale down at smaller container sizes to maximize
+ * the usable chart area. When the chart area is still too small after
+ * scaling, chrome is progressively stripped as a fallback.
  */
 
 import type {
   CompileOptions,
   Encoding,
+  LayoutStrategy,
   LegendLayout,
   Margins,
   Rect,
@@ -53,6 +58,23 @@ function chromeToInput(chrome: NormalizedChrome): import('@opendata-ai/openchart
   };
 }
 
+/**
+ * Scale padding based on the smaller container dimension.
+ * At >= 500px, padding is unchanged. At <= 200px, padding is halved (min 4px).
+ * Linear interpolation between 200-500px.
+ */
+function scalePadding(basePadding: number, width: number, height: number): number {
+  const minDim = Math.min(width, height);
+  if (minDim >= 500) return basePadding;
+  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
+  const t = (minDim - 200) / 300;
+  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
+}
+
+/** Minimum chart area dimensions before guardrails kick in. */
+const MIN_CHART_WIDTH = 60;
+const MIN_CHART_HEIGHT = 40;
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -64,6 +86,7 @@ function chromeToInput(chrome: NormalizedChrome): import('@opendata-ai/openchart
  * @param options - Compile options (width, height, theme, darkMode).
  * @param legendLayout - Pre-computed legend layout (used to reserve space).
  * @param theme - Already-resolved theme (resolved once in compileChart).
+ * @param strategy - Responsive layout strategy (controls chrome mode).
  * @returns LayoutDimensions with chart area rect.
  */
 export function computeDimensions(
@@ -71,14 +94,23 @@ export function computeDimensions(
   options: CompileOptions,
   legendLayout: LegendLayout,
   theme: ResolvedTheme,
+  strategy?: LayoutStrategy,
 ): LayoutDimensions {
   const { width, height } = options;
 
-  const padding = theme.spacing.padding;
+  const padding = scalePadding(theme.spacing.padding, width, height);
   const axisMargin = theme.spacing.axisMargin;
+  const chromeMode = strategy?.chromeMode ?? 'full';
 
-  // Compute chrome
-  const chrome = computeChrome(chromeToInput(spec.chrome), theme, width, options.measureText);
+  // Compute chrome with mode and scaled padding
+  const chrome = computeChrome(
+    chromeToInput(spec.chrome),
+    theme,
+    width,
+    options.measureText,
+    chromeMode,
+    padding,
+  );
 
   // Start with the total rect
   const total: Rect = { x: 0, y: 0, width, height };
@@ -216,12 +248,53 @@ export function computeDimensions(
   }
 
   // Chart area is what's left after margins
-  const chartArea: Rect = {
+  let chartArea: Rect = {
     x: margins.left,
     y: margins.top,
     width: Math.max(0, width - margins.left - margins.right),
     height: Math.max(0, height - margins.top - margins.bottom),
   };
 
+  // Guardrail: if chart area is too small, progressively strip chrome
+  if (
+    (chartArea.width < MIN_CHART_WIDTH || chartArea.height < MIN_CHART_HEIGHT) &&
+    chromeMode !== 'hidden'
+  ) {
+    // Try compact first, then hidden
+    const fallbackMode = chromeMode === 'full' ? 'compact' : 'hidden';
+    const fallbackChrome = computeChrome(
+      chromeToInput(spec.chrome),
+      theme,
+      width,
+      options.measureText,
+      fallbackMode as 'compact' | 'hidden',
+      padding,
+    );
+
+    // Recalculate top/bottom margins with stripped chrome
+    const newTop = padding + fallbackChrome.topHeight + axisMargin;
+    const topDelta = margins.top - newTop;
+    const newBottom = padding + fallbackChrome.bottomHeight + xAxisHeight;
+    const bottomDelta = margins.bottom - newBottom;
+
+    if (topDelta > 0 || bottomDelta > 0) {
+      margins.top =
+        newTop +
+        (legendLayout.entries.length > 0 && legendLayout.position === 'top'
+          ? legendLayout.bounds.height + 4
+          : 0);
+      margins.bottom = newBottom;
+
+      chartArea = {
+        x: margins.left,
+        y: margins.top,
+        width: Math.max(0, width - margins.left - margins.right),
+        height: Math.max(0, height - margins.top - margins.bottom),
+      };
+
+      return { total, chrome: fallbackChrome, chartArea, margins, theme };
+    }
+  }
+
   return { total, chrome, chartArea, margins, theme };
 }

package/src/legend/compute.ts

@@ -7,6 +7,9 @@
  *
  * The legend is computed early (before marks) so the chartArea accounts
  * for legend space. Entries come from data + encoding, not marks.
+ *
+ * Overflow protection: when there are too many entries for the available
+ * space, entries are truncated and a "+N more" indicator is appended.
  */
 
 import type {
@@ -17,7 +20,7 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
 
@@ -31,6 +34,12 @@ const ENTRY_GAP = 16;
 const LEGEND_PADDING = 8;
 const LEGEND_RIGHT_WIDTH = 120;
 
+/** Max fraction of chart area height for right-positioned legends. */
+const RIGHT_LEGEND_MAX_HEIGHT_RATIO = 0.4;
+
+/** Max number of rows for top-positioned legends before truncation. */
+const TOP_LEGEND_MAX_ROWS = 2;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -68,6 +77,57 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
   }));
 }
 
+/**
+ * Calculate how many entries fit within a given number of horizontal rows.
+ */
+function entriesThatFit(
+  entries: LegendEntry[],
+  maxWidth: number,
+  maxRows: number,
+  labelStyle: TextStyle,
+): number {
+  let row = 1;
+  let rowWidth = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const labelWidth = estimateTextWidth(
+      entries[i].label,
+      labelStyle.fontSize,
+      labelStyle.fontWeight,
+    );
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+
+    if (rowWidth + entryWidth > maxWidth && rowWidth > 0) {
+      row++;
+      rowWidth = entryWidth;
+      if (row > maxRows) return i;
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  return entries.length;
+}
+
+/**
+ * Truncate entries and add a "+N more" indicator if needed.
+ */
+function truncateEntries(entries: LegendEntry[], maxCount: number): LegendEntry[] {
+  if (maxCount >= entries.length || maxCount <= 0) return entries;
+
+  const truncated = entries.slice(0, maxCount);
+  const remaining = entries.length - maxCount;
+  truncated.push({
+    label: `+${remaining} more`,
+    color: '#999999',
+    shape: 'square',
+    active: false,
+    overflow: true,
+  });
+
+  return truncated;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -87,8 +147,8 @@ export function computeLegend(
   theme: ResolvedTheme,
   chartArea: Rect,
 ): LegendLayout {
-  // Legend explicitly hidden via show: false
-  if (spec.legend?.show === false) {
+  // Legend explicitly hidden via show: false, or height strategy says no legend
+  if (spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return {
       position: 'top',
       entries: [],
@@ -106,7 +166,7 @@ export function computeLegend(
     };
   }
 
-  const entries = extractColorEntries(spec, theme);
+  let entries = extractColorEntries(spec, theme);
 
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
@@ -143,6 +203,21 @@ export function computeLegend(
       SWATCH_SIZE + SWATCH_GAP + maxLabelWidth + LEGEND_PADDING * 2,
     );
     const entryHeight = Math.max(SWATCH_SIZE, labelStyle.fontSize * labelStyle.lineHeight);
+
+    // Apply max height ratio (default 40% of chart area, strategy can override)
+    const maxHeightRatio =
+      strategy.legendMaxHeight > 0 ? strategy.legendMaxHeight : RIGHT_LEGEND_MAX_HEIGHT_RATIO;
+    const maxLegendHeight = chartArea.height * maxHeightRatio;
+
+    // Calculate how many entries fit
+    const maxEntries = Math.max(
+      1,
+      Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4)),
+    );
+    if (entries.length > maxEntries) {
+      entries = truncateEntries(entries, maxEntries);
+    }
+
     const legendHeight =
       entries.length * entryHeight + (entries.length - 1) * 4 + LEGEND_PADDING * 2;
     const clampedHeight = Math.min(legendHeight, chartArea.height);
@@ -173,13 +248,36 @@ export function computeLegend(
     };
   }
 
-  // Top/bottom-positioned legend: horizontal flow
+  // Top/bottom-positioned legend: horizontal flow with overflow protection.
+  // Reserve space on the right so legend entries don't overlap the brand watermark.
+  const availableWidth = chartArea.width - LEGEND_PADDING * 2 - BRAND_RESERVE_WIDTH;
+  const maxFit = entriesThatFit(entries, availableWidth, TOP_LEGEND_MAX_ROWS, labelStyle);
+
+  if (maxFit < entries.length) {
+    entries = truncateEntries(entries, maxFit);
+  }
+
   const totalWidth = entries.reduce((sum, entry) => {
     const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
     return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
   }, 0);
 
-  const legendHeight = SWATCH_SIZE + LEGEND_PADDING * 2;
+  // Calculate actual row count for height
+  let rowCount = 1;
+  let rowWidth = 0;
+  for (const entry of entries) {
+    const labelWidth = estimateTextWidth(entry.label, labelStyle.fontSize, labelStyle.fontWeight);
+    const entryWidth = SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
+    if (rowWidth + entryWidth > availableWidth && rowWidth > 0) {
+      rowCount++;
+      rowWidth = entryWidth;
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  const rowHeight = SWATCH_SIZE + 4;
+  const legendHeight = rowCount * rowHeight + LEGEND_PADDING * 2;
 
   // Apply user-provided legend offset
   const offsetDx = spec.legend?.offset?.dx ?? 0;
@@ -194,7 +292,7 @@ export function computeLegend(
         (resolvedPosition === 'bottom'
           ? chartArea.y + chartArea.height - legendHeight
           : chartArea.y) + offsetDy,
-      width: Math.min(totalWidth, chartArea.width),
+      width: Math.min(totalWidth, availableWidth),
       height: legendHeight,
     },
     labelStyle,