@opendata-ai/openchart-engine 6.19.3 → 6.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.19.3",
+  "version": "6.20.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.19.3",
+    "@opendata-ai/openchart-core": "6.20.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/legend.test.ts

@@ -1,6 +1,7 @@
 import type { LayoutStrategy, Rect, ResolvedTheme } from '@opendata-ai/openchart-core';
 import { resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
 import type { NormalizedChartSpec } from '../compiler/types';
 import { computeLegend } from '../legend/compute';
 
@@ -393,4 +394,42 @@ describe('computeLegend', () => {
       expect(legend.bounds.width).toBe(0);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Characterization test (refactor/v7-cohesion step 1):
+  // Pins the 4px gap between a top-positioned legend and the chart area,
+  // as enforced at packages/engine/src/compile.ts:331. Refactor step 4 will
+  // consolidate legend row-wrapping geometry; this test guards the spacing
+  // invariant through that change.
+  // ---------------------------------------------------------------------------
+  describe('top legend spacing', () => {
+    it('places the legend exactly 4px above the chart area', () => {
+      const spec = {
+        mark: 'bar' as const,
+        data: [
+          { name: 'A', value: 10, group: 'X' },
+          { name: 'A', value: 20, group: 'Y' },
+          { name: 'B', value: 30, group: 'X' },
+          { name: 'B', value: 25, group: 'Y' },
+        ],
+        encoding: {
+          x: { field: 'name', type: 'nominal' as const },
+          y: { field: 'value', type: 'quantitative' as const },
+          color: { field: 'group', type: 'nominal' as const },
+        },
+        legend: { position: 'top' as const },
+      };
+
+      const layout = compileChart(spec, { width: 600, height: 400 });
+
+      expect(layout.legend.position).toBe('top');
+      expect(layout.legend.entries.length).toBeGreaterThan(0);
+      expect(layout.legend.bounds.height).toBeGreaterThan(0);
+
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      const gap = layout.area.y - legendBottom;
+      // Pin value matches the literal at compile.ts:331 (legendArea.y -= legendLayout.bounds.height + 4)
+      expect(gap).toBe(4);
+    });
+  });
 });

package/src/charts/_shared/format-label-value.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared numeric value formatter for data labels.
+ *
+ * Used by bar, column, and dot label computation to display a value:
+ * abbreviated (K/M/B/T) for magnitudes >= 1000, otherwise the default
+ * numeric format.
+ */
+
+import { abbreviateNumber, formatNumber } from '@opendata-ai/openchart-core';
+
+/** Format a label value for display (abbreviate large numbers). */
+export function formatLabelValue(value: number): string {
+  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
+  return formatNumber(value);
+}

package/src/charts/bar/__tests__/gradient-orient.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Characterization tests for horizontal-bar gradient auto-orientation.
+ *
+ * Part of refactor/v7-cohesion step 1. Pins the behavior of
+ * `orientGradientForHorizontalBar` in `packages/engine/src/charts/bar/compute.ts`:
+ * when a user supplies the default vertical gradient (top-to-bottom) as a
+ * horizontal-bar fill, the engine rotates it to horizontal (left-to-right) so
+ * the gradient follows the bar's data direction. Vertical bars (columns) keep
+ * the gradient unchanged. Explicit non-default coordinates are never rewritten.
+ *
+ * These tests protect the behavior through upcoming refactors that may consolidate
+ * gradient logic across bar/column/stacked variants.
+ */
+
+import type { ChartSpec, LinearGradient, RectMark } from '@opendata-ai/openchart-core';
+import { isGradientDef } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../../compile';
+
+// A default-vertical linear gradient (no explicit coords — defaults resolve to
+// x1:0, y1:0, x2:0, y2:1 which is the "top-to-bottom" default).
+const defaultVerticalGradient: LinearGradient = {
+  gradient: 'linear',
+  stops: [
+    { offset: 0, color: '#1b7fa3', opacity: 0.4 },
+    { offset: 1, color: '#1b7fa3' },
+  ],
+};
+
+function firstGradientRectFill(marks: RectMark[]): LinearGradient {
+  const mark = marks.find((m) => m.type === 'rect' && isGradientDef(m.fill));
+  if (!mark) throw new Error('expected at least one RectMark with a gradient fill');
+  const fill = mark.fill;
+  if (!isGradientDef(fill) || fill.gradient !== 'linear') {
+    throw new Error('expected a linear gradient fill');
+  }
+  return fill as LinearGradient;
+}
+
+describe('horizontal bar gradient auto-orientation', () => {
+  it('rotates the default vertical gradient to horizontal on horizontal bars', () => {
+    const spec: ChartSpec = {
+      mark: { type: 'bar', fill: defaultVerticalGradient },
+      data: [
+        { category: 'A', value: 10 },
+        { category: 'B', value: 20 },
+        { category: 'C', value: 30 },
+      ],
+      // Horizontal bar: x is quantitative, y is nominal
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal' },
+      },
+    };
+
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    const grad = firstGradientRectFill(layout.marks as RectMark[]);
+
+    // Horizontal gradient: x1 != x2, y1 == y2
+    expect(grad.x1).toBe(0);
+    expect(grad.y1).toBe(0);
+    expect(grad.x2).toBe(1);
+    expect(grad.y2).toBe(0);
+    expect(grad.x1).not.toBe(grad.x2);
+    expect(grad.y1).toBe(grad.y2);
+  });
+
+  it('leaves the default vertical gradient unchanged on vertical (column) bars', () => {
+    const spec: ChartSpec = {
+      mark: { type: 'bar', fill: defaultVerticalGradient },
+      data: [
+        { category: 'A', value: 10 },
+        { category: 'B', value: 20 },
+        { category: 'C', value: 30 },
+      ],
+      // Vertical bar (column): x is nominal, y is quantitative
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    const grad = firstGradientRectFill(layout.marks as RectMark[]);
+
+    // Vertical gradient preserved: x1 == x2 (both 0), y1 != y2 (0 vs 1)
+    expect(grad.x1 ?? 0).toBe(0);
+    expect(grad.x2 ?? 0).toBe(0);
+    expect(grad.y1 ?? 0).toBe(0);
+    expect(grad.y2 ?? 1).toBe(1);
+    expect(grad.x1 ?? 0).toBe(grad.x2 ?? 0);
+    expect(grad.y1 ?? 0).not.toBe(grad.y2 ?? 1);
+  });
+
+  it('leaves an explicitly-oriented gradient unchanged on horizontal bars', () => {
+    // Explicit non-default direction — user knows what they want, the engine
+    // must not rewrite it. Here we pass a diagonal gradient.
+    const explicitDiagonal: LinearGradient = {
+      gradient: 'linear',
+      x1: 0,
+      y1: 0,
+      x2: 1,
+      y2: 1,
+      stops: [
+        { offset: 0, color: '#1b7fa3' },
+        { offset: 1, color: '#ff6600' },
+      ],
+    };
+
+    const spec: ChartSpec = {
+      mark: { type: 'bar', fill: explicitDiagonal },
+      data: [{ category: 'A', value: 10 }],
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal' },
+      },
+    };
+
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    const grad = firstGradientRectFill(layout.marks as RectMark[]);
+
+    expect(grad.x1).toBe(0);
+    expect(grad.y1).toBe(0);
+    expect(grad.x2).toBe(1);
+    expect(grad.y2).toBe(1);
+  });
+});

package/src/charts/bar/compute.ts

@@ -17,11 +17,12 @@ import type {
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
+import { isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
+import { formatLabelValue } from '../_shared/format-label-value';
 import { getColor, getSequentialColor, groupByField } from '../utils';
 
 /**
@@ -53,12 +54,6 @@ function orientGradientForHorizontalBar(grad: GradientDef): GradientDef {
 
 const MIN_BAR_WIDTH = 1;
 
-/** Format a bar value for display (abbreviate large numbers). */
-function formatBarValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -221,7 +216,7 @@ function computeStackedBars(
       const barWidth = Math.max(Math.abs(xRight - xLeft), MIN_BAR_WIDTH);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatBarValue(rawValue)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(rawValue)}`,
       };
 
       marks.push({
@@ -291,7 +286,7 @@ function computeGroupedBars(
       const subY = bandY + groupIndex * (subBandHeight + gap);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatBarValue(value)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
       };
 
       marks.push({
@@ -341,7 +336,7 @@ function computeColoredBars(
     const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
 
     const aria: MarkAria = {
-      label: `${category}, ${groupKey}: ${formatBarValue(value)}`,
+      label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
     };
 
     marks.push({
@@ -401,7 +396,7 @@ function computeSimpleBars(
     const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
 
     const aria: MarkAria = {
-      label: `${category}: ${formatBarValue(value)}`,
+      label: `${category}: ${formatLabelValue(value)}`,
     };
 
     marks.push({

package/src/charts/bar/labels.ts

@@ -18,24 +18,17 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
   buildD3Formatter,
   estimateTextWidth,
-  formatNumber,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
+import { formatLabelValue } from '../_shared/format-label-value';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Format a bar value for display (abbreviate large numbers). */
-function formatBarValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
-
 /** Suffix multipliers mirroring core's abbreviateNumber output (K/M/B/T). */
 const SUFFIX_MULTIPLIERS: Record<string, number> = {
   K: 1_000,
@@ -124,7 +117,7 @@ export function computeBarLabels(
     if (formatter && Number.isFinite(rawNum)) {
       valuePart = formatter(rawNum);
     } else if (Number.isFinite(rawNum)) {
-      valuePart = formatBarValue(rawNum);
+      valuePart = formatLabelValue(rawNum);
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;

package/src/charts/column/compute.ts

@@ -20,11 +20,12 @@ import type {
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
+import { isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
+import { formatLabelValue } from '../_shared/format-label-value';
 import { getColor, getSequentialColor, groupByField } from '../utils';
 
 // ---------------------------------------------------------------------------
@@ -33,12 +34,6 @@ import { getColor, getSequentialColor, groupByField } from '../utils';
 
 const MIN_COLUMN_HEIGHT = 1;
 
-/** Format a column value for display (abbreviate large numbers). */
-function formatColumnValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -199,7 +194,7 @@ function computeSimpleColumns(
     const y = value >= 0 ? yPos : baseline;
 
     const aria: MarkAria = {
-      label: `${category}: ${formatColumnValue(value)}`,
+      label: `${category}: ${formatLabelValue(value)}`,
     };
 
     marks.push({
@@ -250,7 +245,7 @@ function computeColoredColumns(
     const y = value >= 0 ? yPos : baseline;
 
     const aria: MarkAria = {
-      label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+      label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
     };
 
     marks.push({
@@ -320,7 +315,7 @@ function computeGroupedColumns(
       const subX = bandX + groupIndex * (subBandWidth + gap);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
       };
 
       marks.push({
@@ -389,7 +384,7 @@ function computeStackedColumns(
       const columnHeight = Math.max(Math.abs(yBottom - yTop), MIN_COLUMN_HEIGHT);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatColumnValue(rawValue)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(rawValue)}`,
       };
 
       marks.push({

package/src/charts/column/labels.ts

@@ -18,23 +18,12 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
   buildD3Formatter,
   estimateTextWidth,
-  formatNumber,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Format a column value for display (abbreviate large numbers). */
-function formatColumnValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
+import { formatLabelValue } from '../_shared/format-label-value';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -82,7 +71,7 @@ export function computeColumnLabels(
     if (formatter && Number.isFinite(rawNum)) {
       valuePart = formatter(rawNum);
     } else if (Number.isFinite(rawNum)) {
-      valuePart = formatColumnValue(rawNum);
+      valuePart = formatLabelValue(rawNum);
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;

package/src/charts/dot/labels.ts

@@ -18,23 +18,12 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
   buildD3Formatter,
   estimateTextWidth,
-  formatNumber,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Format a dot value for display (abbreviate large numbers). */
-function formatDotValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
+import { formatLabelValue } from '../_shared/format-label-value';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -81,7 +70,7 @@ export function computeDotLabels(
     if (formatter && Number.isFinite(rawNum)) {
       valuePart = formatter(rawNum);
     } else if (Number.isFinite(rawNum)) {
-      valuePart = formatDotValue(rawNum);
+      valuePart = formatLabelValue(rawNum);
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;

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