@opendata-ai/openchart-vanilla 7.2.3 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-vanilla",
-  "version": "7.2.3",
+  "version": "7.3.0",
   "description": "Vanilla JS renderer for openchart: SVG charts, HTML tables, force-directed graphs",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -50,8 +50,8 @@
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
-    "@opendata-ai/openchart-core": "7.2.3",
-    "@opendata-ai/openchart-engine": "7.2.3",
+    "@opendata-ai/openchart-core": "7.3.0",
+    "@opendata-ai/openchart-engine": "7.3.0",
     "d3-force": "^3.0.0",
     "d3-quadtree": "^3.0.1"
   },

package/src/__tests__/known-bugs-render.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Red-locked tests for known layout bugs.
+ *
+ * These use `test.fails(...)` so they pass today (the assertion is inverted).
+ * When the underlying bug is fixed, the test will start failing, signaling
+ * that the red-lock can be converted to a normal passing test.
+ */
+
+import type { CategoricalLegendLayout } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { compileChart } from '@opendata-ai/openchart-engine';
+import { describe, expect, test } from 'vitest';
+import { renderLegend } from '../renderers/legend';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Collect distinct y-attribute values from <text> elements, sorted ascending. */
+function distinctLabelYValues(svg: SVGElement): number[] {
+  const texts = svg.querySelectorAll('text');
+  const ySet = new Set<number>();
+  for (const t of texts) {
+    const y = t.getAttribute('y');
+    if (y != null) ySet.add(Number(y));
+  }
+  return [...ySet].sort((a, b) => a - b);
+}
+
+// ---------------------------------------------------------------------------
+// Constants (mirrors packages/engine/src/legend/wrap.ts)
+// ---------------------------------------------------------------------------
+
+const SWATCH_SIZE = 12;
+const SWATCH_GAP = 6;
+const ENTRY_GAP = 16;
+const ENGINE_ROW_HEIGHT = SWATCH_SIZE + 4; // 16 - what the engine reserves
+const LEGEND_PADDING = 8;
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const entries: CategoricalLegendLayout['entries'] = [
+  { label: 'United States of America', color: '#1f77b4', shape: 'square', active: true },
+  { label: 'United Kingdom', color: '#ff7f0e', shape: 'square', active: true },
+  { label: 'Federal Republic of Germany', color: '#2ca02c', shape: 'square', active: true },
+  { label: 'French Republic', color: '#d62728', shape: 'square', active: true },
+  { label: 'Kingdom of Spain', color: '#9467bd', shape: 'square', active: true },
+  { label: 'Republic of Italy', color: '#8c564b', shape: 'square', active: true },
+  { label: 'Kingdom of Netherlands', color: '#e377c2', shape: 'square', active: true },
+  { label: 'Swiss Confederation', color: '#7f7f7f', shape: 'square', active: true },
+];
+
+const labelStyle = {
+  fontSize: 11,
+  lineHeight: 1.3,
+  fontWeight: 400 as const,
+  fontFamily: 'sans-serif',
+  fill: '#333',
+};
+
+/**
+ * Compute row count by simulating the same wrap logic the engine uses
+ * (measureLegendWrap in packages/engine/src/legend/wrap.ts).
+ */
+function computeRowCount(maxWidth: number): number {
+  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 > maxWidth && rowWidth > 0) {
+      rowCount++;
+      rowWidth = entryWidth;
+    } else {
+      rowWidth += entryWidth;
+    }
+  }
+  return rowCount;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('known layout bugs', () => {
+  // Red-locked: fixed by docs/plans/04-resolved-layout-contract.md
+  test.fails('5a.1: legend row advancement matches engine row height', () => {
+    const boundsWidth = 400;
+    const rowCount = computeRowCount(boundsWidth);
+    const boundsHeight = rowCount * ENGINE_ROW_HEIGHT + LEGEND_PADDING * 2;
+
+    const legendFixture: CategoricalLegendLayout = {
+      position: 'top',
+      entries,
+      swatchSize: SWATCH_SIZE,
+      swatchGap: SWATCH_GAP,
+      entryGap: ENTRY_GAP,
+      swatchChipFill: '#f0f0f0',
+      labelStyle,
+      bounds: { x: 0, y: 0, width: boundsWidth, height: boundsHeight },
+    };
+
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    renderLegend(svg, legendFixture);
+
+    const yValues = distinctLabelYValues(svg);
+    // With 4 rows we expect 4 distinct y-values. Consecutive rows should
+    // differ by ENGINE_ROW_HEIGHT (16). The renderer uses swatchSize + 6 = 18,
+    // so this assertion will fail until the drift is fixed.
+    expect(yValues.length).toBeGreaterThanOrEqual(2);
+    for (let i = 1; i < yValues.length; i++) {
+      const gap = yValues[i] - yValues[i - 1];
+      expect(gap).toBe(ENGINE_ROW_HEIGHT);
+    }
+  });
+
+  // Red-locked: fixed by docs/plans/04-resolved-layout-contract.md and docs/plans/03-measure-then-freeze-layout.md
+  test.fails('5a.2: rows drawn by renderer match rows reserved by engine', () => {
+    // Build a line spec with 8 series whose labels vary in length.
+    const countries = [
+      'United States of America',
+      'United Kingdom',
+      'Federal Republic of Germany',
+      'French Republic',
+      'Kingdom of Spain',
+      'Republic of Italy',
+      'Kingdom of Netherlands',
+      'Swiss Confederation',
+    ];
+
+    const data = countries.flatMap((country) => [
+      { date: '2020-01-01', value: 10, country },
+      { date: '2021-01-01', value: 20, country },
+    ]);
+
+    const spec = {
+      mark: 'line' as const,
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+        color: { field: 'country', type: 'nominal' as const },
+      },
+      legend: { position: 'top' as const },
+    };
+
+    // Try widths 500-700 to find one where the legend wraps AND the
+    // bounds.width narrowing causes extra rows in the renderer.
+    let foundMismatch = false;
+
+    for (let width = 500; width <= 700; width += 10) {
+      const layout = compileChart(spec, { width, height: 400 });
+      const legend = layout.legend as CategoricalLegendLayout;
+      if (!legend || !legend.entries || legend.entries.length === 0) continue;
+
+      // Rows reserved by the engine
+      const effectivePadding = width < 420 ? 2 : LEGEND_PADDING;
+      const rowsReserved = Math.round(
+        (legend.bounds.height - effectivePadding * 2) / ENGINE_ROW_HEIGHT,
+      );
+      if (rowsReserved <= 1) continue; // only interesting when wrapping occurs
+
+      // Render and count rows drawn
+      const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      renderLegend(svg, legend);
+      const yValues = distinctLabelYValues(svg);
+      const rowsDrawn = yValues.length;
+
+      if (rowsDrawn !== rowsReserved) {
+        foundMismatch = true;
+        // This is the bug: the renderer drew more rows than the engine reserved.
+        expect(rowsDrawn).toBe(rowsReserved);
+        return;
+      }
+    }
+
+    // If no width triggered a mismatch, fail so test.fails still inverts.
+    // If this path fires, widen the width range above.
+    expect(foundMismatch).toBe(true);
+  });
+});

package/src/measure-text.ts

@@ -7,6 +7,7 @@
  */
 
 import type { MeasureTextFn } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
 
 export function createMeasureText(): MeasureTextFn {
   let canvas: HTMLCanvasElement | null = null;
@@ -23,7 +24,10 @@ export function createMeasureText(): MeasureTextFn {
     }
     if (!ctx) {
       // Fallback: heuristic estimation
-      return { width: text.length * fontSize * 0.6, height: fontSize * 1.2 };
+      return {
+        width: estimateTextWidth(text, fontSize, fontWeight ?? 400),
+        height: fontSize * 1.2,
+      };
     }
 
     const weight = fontWeight ?? 400;
@@ -35,3 +39,9 @@ export function createMeasureText(): MeasureTextFn {
     };
   };
 }
+
+let shared: MeasureTextFn | null = null;
+export function sharedMeasureText(): MeasureTextFn {
+  if (!shared) shared = createMeasureText();
+  return shared;
+}

package/src/renderers/annotations.ts

@@ -214,14 +214,7 @@ function renderAnnotation(
     const lineHeight = fontSize * (annotation.label.style.lineHeight ?? 1.3);
     const isMultiLine = lines.length > 1;
 
-    // Multi-line text: drop-line connectors keep the resolved side anchor so
-    // the label hugs the vertical line. Other connectors center the text for
-    // a cleaner look.
     if (isMultiLine) {
-      const isDropLine = annotation.label.connector?.style === 'drop-line';
-      if (!isDropLine) {
-        text.setAttribute('text-anchor', 'middle');
-      }
       for (let i = 0; i < lines.length; i++) {
         const tspan = createSVGElement('tspan');
         setAttrs(tspan, { x: annotation.label.x, dy: i === 0 ? 0 : lineHeight });
@@ -235,20 +228,35 @@ function renderAnnotation(
     // Render background rect behind text if specified, otherwise use
     // paint-order stroke halo to knock out lines behind text
     if (annotation.label.background) {
-      const charWidth = fontSize * 0.55;
-      const maxLineWidth = Math.max(...lines.map((l) => l.length)) * charWidth;
-      const totalHeight = lines.length * lineHeight;
       const pad = 3;
-      const bgX = isMultiLine
-        ? annotation.label.x - maxLineWidth / 2 - pad
-        : annotation.label.x - pad;
+      let bgX: number;
+      let bgY: number;
+      let bgW: number;
+      let bgH: number;
+
+      if (annotation.label.bounds) {
+        const b = annotation.label.bounds;
+        bgX = b.x - pad;
+        bgY = b.y - pad;
+        bgW = b.width + pad * 2;
+        bgH = b.height + pad * 2;
+      } else {
+        const charWidth = fontSize * 0.55;
+        const maxLineWidth = Math.max(...lines.map((l) => l.length)) * charWidth;
+        const totalHeight = lines.length * lineHeight;
+        bgX = isMultiLine ? annotation.label.x - maxLineWidth / 2 - pad : annotation.label.x - pad;
+        bgY = annotation.label.y - fontSize + (lineHeight - fontSize) / 2 - pad;
+        bgW = maxLineWidth + pad * 2;
+        bgH = totalHeight + pad * 2;
+      }
+
       const bgRect = createSVGElement('rect');
       bgRect.setAttribute('class', 'oc-annotation-bg');
       setAttrs(bgRect, {
         x: bgX,
-        y: annotation.label.y - fontSize + (lineHeight - fontSize) / 2 - pad,
-        width: maxLineWidth + pad * 2,
-        height: totalHeight + pad * 2,
+        y: bgY,
+        width: bgW,
+        height: bgH,
         fill: annotation.label.background,
         rx: 2,
       });

package/src/renderers/axes.ts

@@ -242,9 +242,18 @@ function renderAxis(
     applyTextStyle(axisLabel, axis.labelStyle);
     axisLabel.textContent = axis.label;
 
-    if (orientation === 'x') {
-      // Position axis title below tick labels. For rotated labels, compute
-      // the vertical extent of the rotated ticks and place the title below.
+    const tp = axis.titlePosition;
+    if (tp) {
+      const attrs: Record<string, string | number> = {
+        x: tp.x,
+        y: tp.y,
+        'text-anchor': 'middle',
+      };
+      if (tp.angle) {
+        attrs.transform = `rotate(${tp.angle}, ${tp.x}, ${tp.y})`;
+      }
+      setAttrs(axisLabel, attrs);
+    } else if (orientation === 'x') {
       let titleY = area.y + area.height + 35;
       if (axis.tickAngle && Math.abs(axis.tickAngle) > 10) {
         const angleRad = Math.abs(axis.tickAngle) * (Math.PI / 180);
@@ -266,7 +275,6 @@ function renderAxis(
         'text-anchor': 'middle',
       });
     } else if (isRight) {
-      // Rotated right y-axis label (tighter offset on compact viewports)
       const titleOffset = getAxisTitleOffset(layout.dimensions.width);
       const titleX = area.x + area.width + titleOffset;
       setAttrs(axisLabel, {
@@ -276,11 +284,6 @@ function renderAxis(
         transform: `rotate(90, ${titleX}, ${area.y + area.height / 2})`,
       });
     } else {
-      // Rotated left y-axis label.
-      // Compute a dynamic offset so the title clears the widest tick label.
-      // The title is rotated and centered, so axisTitleOffset() adds its own
-      // half-glyph height on top of the gap (otherwise large title fonts overlap
-      // the tick labels — the gap is visible clearance, not center-to-edge).
       const maxTickLabelWidth = axis.ticks.reduce((max, t) => {
         const w = estimateTextWidth(
           t.label,

package/src/renderers/brand.ts

@@ -4,7 +4,7 @@
 
 import type { ChartLayout } from '@opendata-ai/openchart-core';
 import { BRAND_FONT_SIZE, BRAND_MIN_WIDTH } from '@opendata-ai/openchart-core';
-import { computeXAxisExtent, createSVGElement, setAttrs, XLINK_NS } from './svg-dom';
+import { createSVGElement, setAttrs, XLINK_NS } from './svg-dom';
 
 const BRAND_URL = 'https://tryopendata.ai';
 
@@ -24,8 +24,7 @@ export function renderBrand(parent: SVGElement, layout: ChartLayout): void {
 
   // Vertically align with the first bottom chrome element.
   const { chrome } = layout;
-  const xAxisExtent = computeXAxisExtent(layout);
-  const bottomOffset = layout.area.y + layout.area.height + xAxisExtent;
+  const bottomOffset = chrome.bottomAnchorY ?? layout.area.y + layout.area.height;
   const firstBottom = chrome.source ?? chrome.byline ?? chrome.footer;
   // When no bottom chrome items exist, derive a fallback offset that still
   // clears any bottom-positioned legend so the brand watermark doesn't

package/src/renderers/chrome.ts

@@ -8,7 +8,7 @@ import type {
   ResolvedChromeElement,
 } from '@opendata-ai/openchart-core';
 import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
-import { applyTextStyle, computeXAxisExtent, createSVGElement, setAttrs } from './svg-dom';
+import { applyTextStyle, createSVGElement, setAttrs } from './svg-dom';
 
 function renderChromeElement(
   parent: SVGElement,
@@ -87,10 +87,7 @@ export function renderChrome(parent: SVGElement, layout: ChartLayout): void {
     renderChromeElement(g, chrome.subtitle, 'oc-subtitle', 'subtitle', measureText);
   }
 
-  // Bottom chrome starts below x-axis labels/title, not at chart area bottom.
-  // Accounts for rotated tick labels which need more vertical space.
-  const xAxisExtent = computeXAxisExtent(layout);
-  const bottomOffset = layout.area.y + layout.area.height + xAxisExtent;
+  const bottomOffset = layout.chrome.bottomAnchorY ?? layout.area.y + layout.area.height;
   if (chrome.source) {
     renderChromeElement(
       g,

package/src/renderers/legend.ts

@@ -19,14 +19,18 @@ export function renderLegend(parent: SVGElement, legend: LegendLayout): void {
   g.setAttribute('aria-label', 'Chart legend');
 
   const isHorizontal = legend.position === 'top' || legend.position === 'bottom';
+  const positions = 'entryPositions' in legend ? legend.entryPositions : undefined;
   let offsetX = legend.bounds.x;
   let offsetY = legend.bounds.y;
 
   for (let i = 0; i < legend.entries.length; i++) {
     const entry = legend.entries[i];
 
-    // Pre-check: wrap to next line if this entry would overflow bounds
-    if (isHorizontal && i > 0) {
+    const pos = positions?.[i];
+    if (pos) {
+      offsetX = pos.x;
+      offsetY = pos.y;
+    } else if (isHorizontal && i > 0) {
       const labelWidth = estimateTextWidth(
         entry.label,
         legend.labelStyle.fontSize,
@@ -116,17 +120,21 @@ export function renderLegend(parent: SVGElement, legend: LegendLayout): void {
 
     g.appendChild(entryG);
 
-    // Advance position for next entry
-    if (isHorizontal) {
-      const labelWidth = estimateTextWidth(
-        entry.label,
-        legend.labelStyle.fontSize,
-        legend.labelStyle.fontWeight,
-      );
-      const entryWidth = legend.swatchSize + legend.swatchGap + labelWidth + legend.entryGap;
-      offsetX += entryWidth;
-    } else {
-      offsetY += legend.swatchSize + legend.entryGap;
+    if (!pos) {
+      if (isHorizontal) {
+        const labelWidth = estimateTextWidth(
+          entry.label,
+          legend.labelStyle.fontSize,
+          legend.labelStyle.fontWeight,
+        );
+        const entryWidth = legend.swatchSize + legend.swatchGap + labelWidth + legend.entryGap;
+        offsetX += entryWidth;
+      } else {
+        offsetY +=
+          'rowHeight' in legend && legend.rowHeight
+            ? legend.rowHeight
+            : legend.swatchSize + legend.entryGap;
+      }
     }
   }
 

package/src/renderers/svg-dom.ts

@@ -4,8 +4,7 @@
  * Pure, stateless utilities. No layout/theme knowledge.
  */
 
-import type { ChartLayout, TextStyle } from '@opendata-ai/openchart-core';
-import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import type { TextStyle } from '@opendata-ai/openchart-core';
 
 export const SVG_NS = 'http://www.w3.org/2000/svg';
 export const XLINK_NS = 'http://www.w3.org/1999/xlink';
@@ -39,28 +38,3 @@ export function applyTextStyle(el: SVGElement, style: TextStyle): void {
     el.setAttribute('font-variant', style.fontVariant);
   }
 }
-
-/**
- * Compute the vertical extent of x-axis labels below the chart area.
- * Accounts for rotated tick labels which need more vertical space.
- */
-export function computeXAxisExtent(layout: ChartLayout): number {
-  const xAxis = layout.axes.x;
-  if (!xAxis) return 0;
-
-  if (xAxis.tickAngle && Math.abs(xAxis.tickAngle) > 10) {
-    // Rotated labels: estimate height from the longest tick label.
-    const fontSize = xAxis.tickLabelStyle.fontSize;
-    const fontWeight = xAxis.tickLabelStyle.fontWeight;
-    const angleRad = Math.abs(xAxis.tickAngle) * (Math.PI / 180);
-    let maxLabelWidth = 40;
-    for (const tick of xAxis.ticks) {
-      const w = estimateTextWidth(tick.label, fontSize, fontWeight);
-      if (w > maxLabelWidth) maxLabelWidth = w;
-    }
-    const rotatedHeight = Math.min(maxLabelWidth * Math.sin(angleRad) + 6, 120);
-    return xAxis.label ? rotatedHeight + 20 : rotatedHeight;
-  }
-
-  return xAxis.label ? 48 : 26;
-}