@opendata-ai/openchart-engine 6.19.3 → 6.21.0

package/src/layout/axes.ts

@@ -2,7 +2,8 @@
  * Axis computation: tick positions, labels, and axis lines.
  *
  * Generates ticks manually (no d3-axis) so we have full control over
- * responsive tick density and formatting.
+ * responsive tick density and formatting. Tick generation and label
+ * thinning live in sibling modules under ./axes/.
  */
 
 import type {
@@ -16,33 +17,26 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import {
-  abbreviateNumber,
-  buildD3Formatter,
-  buildTemporalFormatter,
-  estimateTextWidth,
-  formatDate,
-  formatNumber,
-} from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
-import type {
-  D3CategoricalScale,
-  D3ContinuousScale,
-  ResolvedScale,
-  ResolvedScales,
-} from './scales';
+import { measureLabel, thinTicksUntilFit, ticksOverlap } from './axes/thinning';
+import {
+  buildContinuousTicks,
+  categoricalTicks,
+  continuousTicks,
+  resolveExplicitTicks,
+  scaleSupportsTickCount,
+  targetTickCount,
+} from './axes/ticks';
+import type { ResolvedScales } from './scales';
+
+// Re-export pure helpers so external consumers (and tests) continue to import
+// them from './layout/axes'.
+export { thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Base tick counts by axis label density. */
-const TICK_COUNTS: Record<AxisLabelDensity, number> = {
-  full: 12,
-  reduced: 8,
-  minimal: 4,
-};
-
 /**
  * Height thresholds for reducing y-axis tick density.
  * Below these pixel heights, we step down the density regardless of the
@@ -59,15 +53,6 @@ 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'];
 
@@ -106,217 +91,94 @@ 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 along the axis direction. */
-export function ticksOverlap(
-  ticks: AxisTick[],
-  fontSize: number,
-  fontWeight: number,
-  measureText?: MeasureTextFn,
-  orientation: 'horizontal' | 'vertical' = 'horizontal',
-): boolean {
-  if (ticks.length < 2) return false;
-  const minGap = fontSize * MIN_TICK_GAP_FACTOR;
-
-  if (orientation === 'vertical') {
-    // Y-axis: labels are stacked vertically. Check if vertical extent
-    // (based on font height) overlaps between adjacent ticks.
-    // Positions decrease going up in SVG coords, so sort ascending.
-    const sorted = [...ticks].sort((a, b) => a.position - b.position);
-    const labelHeight = fontSize * 1.2; // lineHeight
-    for (let i = 0; i < sorted.length - 1; i++) {
-      const aBottom = sorted[i].position + labelHeight / 2;
-      const bTop = sorted[i + 1].position - labelHeight / 2;
-      if (aBottom + minGap > bTop) return true;
-    }
-    return false;
-  }
+/**
+ * Floor tick count for continuous axes when the axis is long enough to show
+ * more than a min/max pair. Keeps the editorial ~5 target when possible.
+ * Very short axes bypass this floor and can legitimately fall to 2.
+ */
+const CONTINUOUS_TICK_FLOOR = 4;
 
-  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;
-}
+/**
+ * How much D3 is allowed to overshoot what we asked for before we treat the
+ * output as "too dense" and step down. D3's `scale.ticks(n)` only produces
+ * nice step sizes (1, 2, 5 × 10^k, or calendar units for time), so a request
+ * for n=6 can come back with 12 quarterly dates or 10 step-5 values. Accepting
+ * up to 1.5× target catches the obvious overshoots without trimming acceptable
+ * ones.
+ *
+ * The reference point stays fixed to the initial requested count even as we
+ * iterate downward — we're measuring "did this candidate land near the target
+ * the caller actually wanted?", not "is the candidate near what we just asked
+ * for on this iteration?". If a candidate at n=3 returns 8 ticks, it's still
+ * a 1.3× overshoot of the target-6, which is fine.
+ */
+const OVERSHOOT_TOLERANCE = 1.5;
 
 /**
- * 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.
+ * Fit continuous ticks by re-requesting progressively fewer ticks from the
+ * scale. D3's `scale.ticks(n)` always returns evenly-spaced round values, so
+ * stepping `n` down keeps spacing uniform — unlike middle-pruning which can
+ * strand the last tick next to an endpoint and cascade to 2 ticks.
+ *
+ * Two conditions trigger a step-down:
+ *   1. The label heuristic detects overlap at the initial count.
+ *   2. D3 overshot the requested count by more than OVERSHOOT_TOLERANCE.
+ *      (Time scales jump between calendar units; linear scales jump between
+ *      nice step sizes. Either can return 2× what we asked for.)
+ *
+ * Falls back to overlap-safe thinning on the best-so-far candidate if no
+ * count produces a clean fit. The fallback starts from the smallest candidate
+ * that still meets the floor, so `thinTicksUntilFit` never receives the
+ * overshot initial set (which was the bug this function exists to avoid).
  */
-export function thinTicksUntilFit(
-  ticks: AxisTick[],
+function fitContinuousTicks(
+  scale: ResolvedScales['x' | 'y'],
+  initialTicks: AxisTick[],
+  initialCount: number,
   fontSize: number,
   fontWeight: number,
+  axisLength: number,
+  orientation: 'horizontal' | 'vertical',
   measureText?: MeasureTextFn,
-  orientation: 'horizontal' | 'vertical' = 'horizontal',
 ): AxisTick[] {
-  if (!ticksOverlap(ticks, fontSize, fontWeight, measureText, orientation)) 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, orientation)) break;
-  }
-  return current;
-}
-
-// ---------------------------------------------------------------------------
-// Tick generation
-// ---------------------------------------------------------------------------
-
-/** Generate ticks for a continuous scale (linear, time, log, pow, sqrt, symlog). */
-function continuousTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
-  const scale = resolvedScale.scale as D3ContinuousScale;
-
-  // Discretizing scales (quantile, quantize, threshold) don't have .ticks().
-  // Use their domain thresholds as ticks instead.
-  if (!('ticks' in scale) || typeof scale.ticks !== 'function') {
-    const domain = scale.domain() as unknown[];
-    return domain.map((value: unknown) => ({
-      value,
-      position: (scale as D3ContinuousScale)(value as number & Date) as number,
-      label: formatTickLabel(value, resolvedScale),
-    }));
-  }
-
-  const explicitCount = resolvedScale.channel.axis?.tickCount;
-  const count = explicitCount ?? TICK_COUNTS[density];
-  const rawTicks: unknown[] = scale.ticks(count);
-
-  const ticks = rawTicks.map((value: unknown) => ({
-    value,
-    position: scale(value as number & Date) as number,
-    label: formatTickLabel(value, resolvedScale),
-  }));
-
-  return ticks;
-}
-
-/** Generate ticks for a band/point/ordinal scale. */
-function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
-  const scale = resolvedScale.scale as D3CategoricalScale;
-  const domain: string[] = scale.domain();
-  const explicitTickCount = resolvedScale.channel.axis?.tickCount;
-  const maxTicks = explicitTickCount ?? TICK_COUNTS[density];
-
-  // Band scales (bar charts) show all category labels by default.
-  // Only thin when there's an explicit tickCount override or for point/ordinal scales.
-  let selectedValues = domain;
-  if ((resolvedScale.type !== 'band' || explicitTickCount) && domain.length > maxTicks) {
-    const step = Math.ceil(domain.length / maxTicks);
-    selectedValues = domain.filter((_: string, i: number) => i % step === 0);
-  }
-
-  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
-      ? (bandScale(value) ?? 0) + bandScale.bandwidth() / 2
-      : ((scale(value) as number | undefined) ?? 0);
-
-    return {
-      value,
-      position: pos,
-      label: value,
-    };
-  });
-
-  return ticks;
-}
-
-/** Set of continuous numeric scale types that should format as numbers. */
-const NUMERIC_SCALE_TYPES = new Set([
-  'linear',
-  'log',
-  'pow',
-  'sqrt',
-  'symlog',
-  'quantile',
-  'quantize',
-  'threshold',
-]);
-
-/** Set of temporal scale types. */
-const TEMPORAL_SCALE_TYPES = new Set(['time', 'utc']);
-
-/** Format a tick value based on the scale type. */
-function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
-  const formatStr = resolvedScale.channel.axis?.format;
-
-  if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
-    const temporalFmt = buildTemporalFormatter(formatStr);
-    if (temporalFmt) return temporalFmt(value as Date);
-    const useUtc = resolvedScale.type === 'utc';
-    return formatDate(value as Date, undefined, undefined, useUtc);
-  }
-
-  if (NUMERIC_SCALE_TYPES.has(resolvedScale.type)) {
-    const num = value as number;
-    if (formatStr) {
-      const fmt = buildD3Formatter(formatStr);
-      if (fmt) return fmt(num);
+  if (!scale || !scaleSupportsTickCount(scale)) return initialTicks;
+
+  const tolerance = initialCount * OVERSHOOT_TOLERANCE;
+  const overshoots = initialTicks.length > tolerance;
+  const overlaps = ticksOverlap(initialTicks, fontSize, fontWeight, measureText, orientation);
+  if (!overshoots && !overlaps) return initialTicks;
+
+  // 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 =
+    orientation === 'vertical' ? HEIGHT_MINIMAL_THRESHOLD : WIDTH_MINIMAL_THRESHOLD;
+  const floor = axisLength >= minThreshold ? CONTINUOUS_TICK_FLOOR : 2;
+
+  // 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.
+  let bestWithinFloor: AxisTick[] | 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;
     }
-    // Abbreviate large numbers for axis labels
-    if (Math.abs(num) >= 1000) return abbreviateNumber(num);
-    return formatNumber(num);
+    if (candidate.length >= floor) bestWithinFloor = candidate;
   }
 
-  return String(value);
-}
-
-/** Resolve explicit tick values from axis config into positioned ticks. */
-function resolveExplicitTicks(values: unknown[], resolvedScale: ResolvedScale): AxisTick[] {
-  const scale = resolvedScale.scale;
-  return values.map((value) => {
-    let position: number;
-    if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
-      const d = value instanceof Date ? value : new Date(String(value));
-      position = (scale as D3ContinuousScale)(d as number & Date) as number;
-    } else if (
-      resolvedScale.type === 'band' ||
-      resolvedScale.type === 'point' ||
-      resolvedScale.type === 'ordinal'
-    ) {
-      const s = String(value);
-      const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
-      position = bandScale
-        ? (bandScale(s) ?? 0) + bandScale.bandwidth() / 2
-        : ((scale(s as string & number) as number | undefined) ?? 0);
-    } else {
-      position = (scale as D3ContinuousScale)(value as number & Date) as number;
-    }
-    return {
-      value,
-      position,
-      label: formatTickLabel(value, resolvedScale),
-    };
-  });
+  // 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 fallback = bestWithinFloor ?? buildContinuousTicks(scale, floor);
+  return thinTicksUntilFit(fallback, fontSize, fontWeight, measureText, orientation);
 }
 
 // ---------------------------------------------------------------------------
@@ -385,19 +247,21 @@ export function computeAxes(
 
   if (scales.x) {
     const axisConfig = scales.x.channel.axis;
+    const isContinuousX =
+      scales.x.type !== 'band' && scales.x.type !== 'point' && scales.x.type !== 'ordinal';
+
+    const xTargetCount = isContinuousX
+      ? targetTickCount(chartArea.width, xDensity, 'x')
+      : undefined;
 
     // Use explicit tick values from axis config if provided
     let allTicks: AxisTick[];
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.x);
-    } else if (
-      scales.x.type === 'band' ||
-      scales.x.type === 'point' ||
-      scales.x.type === 'ordinal'
-    ) {
+    } else if (!isContinuousX) {
       allTicks = categoricalTicks(scales.x, xDensity);
     } else {
-      allTicks = continuousTicks(scales.x, xDensity);
+      allTicks = continuousTicks(scales.x, xDensity, xTargetCount);
     }
 
     // Gridlines use the full tick set so they remain visible even when labels
@@ -410,9 +274,25 @@ export function computeAxes(
     // Thin tick labels to prevent overlap (skip for band scales which use
     // auto-rotation, and when the user set an explicit tickCount or values).
     const shouldThin = scales.x.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
-    const ticks = shouldThin
-      ? thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText)
-      : allTicks;
+    let ticks: AxisTick[];
+    if (!shouldThin) {
+      ticks = allTicks;
+    } else if (isContinuousX) {
+      // Continuous x-axis: re-request ticks at a lower count on overlap so
+      // time-scale quartile/monthly jumps don't leave a too-dense axis.
+      ticks = fitContinuousTicks(
+        scales.x,
+        allTicks,
+        xTargetCount ?? allTicks.length,
+        fontSize,
+        fontWeight,
+        chartArea.width,
+        'horizontal',
+        measureText,
+      );
+    } else {
+      ticks = thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText);
+    }
 
     // Auto-rotate labels when band scale labels would overlap.
     // Uses max label width (not average) since one long label is enough to overlap.
@@ -454,26 +334,45 @@ export function computeAxes(
 
   if (scales.y) {
     const axisConfig = scales.y.channel.axis;
+    const isContinuousY =
+      scales.y.type !== 'band' && scales.y.type !== 'point' && scales.y.type !== 'ordinal';
+
+    // Target count from pixels-per-tick when we have a continuous y-axis.
+    const yTargetCount = isContinuousY
+      ? targetTickCount(chartArea.height, yDensity, 'y')
+      : undefined;
 
     // Use explicit tick values from axis config if provided
     let allTicks: AxisTick[];
     if (axisConfig?.values) {
       allTicks = resolveExplicitTicks(axisConfig.values, scales.y);
-    } else if (
-      scales.y.type === 'band' ||
-      scales.y.type === 'point' ||
-      scales.y.type === 'ordinal'
-    ) {
+    } else if (!isContinuousY) {
       allTicks = categoricalTicks(scales.y, yDensity);
     } else {
-      allTicks = continuousTicks(scales.y, yDensity);
+      allTicks = continuousTicks(scales.y, yDensity, yTargetCount);
     }
 
     // Thin tick labels to prevent overlap (skip for band scales, explicit tickCount, and values).
     const shouldThin = scales.y.type !== 'band' && !axisConfig?.tickCount && !axisConfig?.values;
-    const ticks = shouldThin
-      ? thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText, 'vertical')
-      : allTicks;
+    let ticks: AxisTick[];
+    if (!shouldThin) {
+      ticks = allTicks;
+    } else if (isContinuousY) {
+      // Continuous y-axis: re-request ticks at a lower count on overlap so
+      // spacing stays uniform and we don't collapse to min/max.
+      ticks = fitContinuousTicks(
+        scales.y,
+        allTicks,
+        yTargetCount ?? allTicks.length,
+        fontSize,
+        fontWeight,
+        chartArea.height,
+        'vertical',
+        measureText,
+      );
+    } else {
+      ticks = thinTicksUntilFit(allTicks, fontSize, fontWeight, measureText, 'vertical');
+    }
 
     // Gridlines match the tick set so every gridline has a label.
     const gridlines: Gridline[] = ticks.map((t) => ({

package/src/legend/compute.ts

@@ -23,14 +23,12 @@ import type {
 import { BRAND_RESERVE_WIDTH, estimateTextWidth } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
+import { ENTRY_GAP, measureLegendWrap, SWATCH_GAP, SWATCH_SIZE } from './wrap';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const SWATCH_SIZE = 12;
-const SWATCH_GAP = 6;
-const ENTRY_GAP = 16;
 const LEGEND_PADDING = 8;
 const LEGEND_RIGHT_WIDTH = 120;
 
@@ -92,38 +90,6 @@ 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.
  */
@@ -310,10 +276,10 @@ export function computeLegend(
       : spec.legend?.columns != null
         ? Math.ceil(entries.length / spec.legend.columns)
         : TOP_LEGEND_MAX_ROWS;
-  const maxFit = entriesThatFit(entries, availableWidth, maxRows, labelStyle);
+  const { fittingCount } = measureLegendWrap(entries, availableWidth, labelStyle, maxRows);
 
-  if (maxFit < entries.length) {
-    entries = truncateEntries(entries, maxFit);
+  if (fittingCount < entries.length) {
+    entries = truncateEntries(entries, fittingCount);
   }
 
   const totalWidth = entries.reduce((sum, entry) => {
@@ -321,19 +287,8 @@ export function computeLegend(
     return sum + SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP;
   }, 0);
 
-  // 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;
-    }
-  }
+  // Calculate actual row count for height (recompute after truncation).
+  const { rowCount } = measureLegendWrap(entries, availableWidth, labelStyle);
 
   const rowHeight = SWATCH_SIZE + 4;
   const legendHeight = rowCount * rowHeight + LEGEND_PADDING * 2;

package/src/legend/wrap.ts

@@ -0,0 +1,94 @@
+/**
+ * Legend row-wrap geometry.
+ *
+ * Shared helper for measuring how legend entries flow across horizontal rows
+ * when wrapped at a max width. Both the main legend compute and the sankey
+ * legend compile use this to size their legends — the main legend uses
+ * `fittingCount` for truncation decisions, while sankey uses `rowCount` to
+ * reserve vertical height.
+ *
+ * The geometry matches the existing layout exactly: each entry occupies
+ * SWATCH_SIZE + SWATCH_GAP + labelWidth + ENTRY_GAP pixels, a new row is
+ * started when the accumulated row width plus the next entry would exceed
+ * maxWidth (and the current row is non-empty), and rowWidths captures the
+ * in-row accumulated width at the point of wrapping.
+ */
+
+import type { LegendEntry, TextStyle } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+//
+// Single source of truth for legend row geometry. Both compute.ts and the
+// sankey compile site import these so the wrap math here can never drift from
+// the layout math at the call sites.
+
+export const SWATCH_SIZE = 12;
+export const SWATCH_GAP = 6;
+export const ENTRY_GAP = 16;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface LegendWrapResult {
+  /** Total number of rows the entries occupy when wrapped at maxWidth. */
+  rowCount: number;
+  /** Entries that fit within maxRows (for truncation). Equals entries.length when maxRows is not set or all entries fit. */
+  fittingCount: number;
+  /** Width (in px) of each row — callers can use for alignment. */
+  rowWidths: number[];
+}
+
+/**
+ * Measure how legend entries wrap across rows at a given max width.
+ *
+ * @param entries - Legend entries to measure.
+ * @param maxWidth - Maximum width (in px) available for a single row.
+ * @param labelStyle - Text style used to estimate label widths.
+ * @param maxRows - Optional cap used only for the `fittingCount` truncation decision. When provided, `fittingCount` will be the index of the first entry that would spill onto a row beyond `maxRows`. `rowCount` is always the real row count regardless of this cap.
+ */
+export function measureLegendWrap(
+  entries: LegendEntry[],
+  maxWidth: number,
+  labelStyle: TextStyle,
+  maxRows?: number,
+): LegendWrapResult {
+  if (entries.length === 0) {
+    return { rowCount: 0, fittingCount: 0, rowWidths: [] };
+  }
+
+  let rowCount = 1;
+  let rowWidth = 0;
+  const rowWidths: number[] = [];
+  let fittingCount = entries.length;
+  let fittingCountLocked = false;
+
+  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) {
+      rowWidths.push(rowWidth);
+      rowCount++;
+      rowWidth = entryWidth;
+      if (!fittingCountLocked && maxRows != null && rowCount > maxRows) {
+        fittingCount = i;
+        fittingCountLocked = true;
+      }
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+
+  // Flush the final row width so rowWidths has one entry per row.
+  rowWidths.push(rowWidth);
+
+  return { rowCount, fittingCount, rowWidths };
+}