@opendata-ai/openchart-engine 7.2.3 → 7.3.0

package/src/__tests__/compile-layer.test.ts

@@ -391,6 +391,55 @@ describe('compileLayer', () => {
     expect(layout.axes.x).toBeDefined();
   });
 
+  it('positions y2 axis title on the right side of the chart', () => {
+    const spec: LayerSpec = {
+      resolve: { scale: { y: 'independent' } },
+      layer: [
+        {
+          mark: 'bar' as const,
+          data: [
+            { year: '2025', revenue: 10_000_000 },
+            { year: '2026', revenue: 15_000_000 },
+          ],
+          encoding: {
+            x: { field: 'year', type: 'ordinal' as const },
+            y: { field: 'revenue', type: 'quantitative' as const, axis: { title: 'Revenue ($)' } },
+          },
+        },
+        {
+          mark: 'line' as const,
+          data: [
+            { year: '2025', enrollment: 30_000 },
+            { year: '2026', enrollment: 40_000 },
+          ],
+          encoding: {
+            x: { field: 'year', type: 'ordinal' as const },
+            y: {
+              field: 'enrollment',
+              type: 'quantitative' as const,
+              axis: { title: 'Enrollment' },
+            },
+          },
+        },
+      ],
+    };
+
+    const layout = compileLayer(spec, compileOpts);
+    const y1Title = layout.axes.y!.titlePosition;
+    const y2Title = layout.axes.y2!.titlePosition;
+
+    expect(y1Title).toBeDefined();
+    expect(y2Title).toBeDefined();
+
+    // y1 title should be left of chart area, y2 title should be right
+    expect(y1Title!.x).toBeLessThan(layout.area.x);
+    expect(y2Title!.x).toBeGreaterThan(layout.area.x + layout.area.width);
+
+    // y2 title should rotate clockwise (90), y1 counter-clockwise (-90)
+    expect(y1Title!.angle).toBe(-90);
+    expect(y2Title!.angle).toBe(90);
+  });
+
   it('tags layer-1 marks with yScale y2', () => {
     const spec: LayerSpec = {
       resolve: { scale: { y: 'independent' } },

package/src/__tests__/dimensions.test.ts

@@ -182,7 +182,11 @@ describe('computeDimensions', () => {
       ],
       encoding: {
         x: { field: 'date', type: 'temporal' },
-        y: { field: 'value', type: 'quantitative', axis: { title: 'Revenue ($)' } },
+        y: {
+          field: 'value',
+          type: 'quantitative',
+          axis: { title: 'Revenue ($)', format: ',.0f' },
+        },
       },
     };
 
@@ -199,7 +203,8 @@ describe('computeDimensions', () => {
       lightTheme,
     );
 
-    // Larger numeric values produce wider tick labels (e.g. "1.5M" vs "0.0"),
+    // Explicit format ",.0f" on large values produces "2,000,000" tick labels
+    // that are much wider than the abbreviated "0.0" from small values,
     // so the y-axis title margin should grow to keep clearance
     expect(dimsLarge.margins.left).toBeGreaterThan(dimsSmall.margins.left);
   });

package/src/__tests__/helpers/invariants.ts

@@ -0,0 +1,267 @@
+/**
+ * Layout invariant assertions.
+ *
+ * Extracts bounding boxes from a compiled ChartLayout and checks that
+ * layout elements don't overlap where they shouldn't.
+ */
+
+import type {
+  CategoricalLegendLayout,
+  ChartLayout,
+  LegendLayout,
+  Rect,
+} from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface NamedRect extends Rect {
+  name: string;
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+function isCategoricalLegend(legend: LegendLayout): legend is CategoricalLegendLayout {
+  return 'entries' in legend && (!legend.type || legend.type === 'categorical');
+}
+
+// ---------------------------------------------------------------------------
+// Box extraction
+// ---------------------------------------------------------------------------
+
+const CHROME_KEYS = [
+  'eyebrow',
+  'title',
+  'subtitle',
+  'source',
+  'byline',
+  'footer',
+  'brand',
+] as const;
+
+/**
+ * Extracts every layout element's bounding box as a NamedRect.
+ */
+export function extractBoxes(layout: ChartLayout): NamedRect[] {
+  const boxes: NamedRect[] = [];
+
+  // Chart area
+  boxes.push({ ...layout.area, name: 'chartArea' });
+
+  // Legend bounds
+  boxes.push({ ...layout.legend.bounds, name: 'legend' });
+
+  // Legend entry positions (categorical only)
+  if (isCategoricalLegend(layout.legend) && layout.legend.entryPositions) {
+    const rowHeight = layout.legend.rowHeight ?? 16;
+    for (let i = 0; i < layout.legend.entryPositions.length; i++) {
+      const pos = layout.legend.entryPositions[i];
+      boxes.push({
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: rowHeight,
+        name: `legend-entry-${i}`,
+      });
+    }
+  }
+
+  // X-axis label band
+  if (layout.axes.x?.extent && layout.axes.x.extent > 0) {
+    boxes.push({
+      x: layout.area.x,
+      y: layout.area.y + layout.area.height,
+      width: layout.area.width,
+      height: layout.axes.x.extent,
+      name: 'x-axis-labels',
+    });
+  }
+
+  // Y-axis label band
+  if (layout.axes.y?.extent && layout.axes.y.extent > 0) {
+    boxes.push({
+      x: layout.area.x - layout.axes.y.extent,
+      y: layout.area.y,
+      width: layout.axes.y.extent,
+      height: layout.area.height,
+      name: 'y-axis-labels',
+    });
+  }
+
+  // Chrome elements: y interpretation depends on dominantBaseline.
+  // 'hanging' = y is top of text; 'auto' = y is baseline (ascender ~80% of fontSize).
+  for (const key of CHROME_KEYS) {
+    const el = layout.chrome[key];
+    if (el) {
+      const h = el.style.fontSize * el.style.lineHeight;
+      const top = el.style.dominantBaseline === 'hanging' ? el.y : el.y - el.style.fontSize * 0.8;
+      boxes.push({ x: el.x, y: top, width: el.maxWidth, height: h, name: key });
+    }
+  }
+
+  // Annotation bounds
+  for (let i = 0; i < layout.annotations.length; i++) {
+    const annotation = layout.annotations[i];
+    if (annotation.bounds) {
+      boxes.push({ ...annotation.bounds, name: `annotation-${i}` });
+    }
+  }
+
+  // Endpoint labels
+  if (layout.endpointLabels?.bounds) {
+    boxes.push({ ...layout.endpointLabels.bounds, name: 'endpoint-labels' });
+  }
+
+  return boxes;
+}
+
+// ---------------------------------------------------------------------------
+// Overlap check
+// ---------------------------------------------------------------------------
+
+/**
+ * Throws if two rects overlap by more than epsilon pixels.
+ */
+export function assertNoOverlap(a: NamedRect, b: NamedRect, epsilon = 0.5): void {
+  const overlaps =
+    a.x < b.x + b.width - epsilon &&
+    a.x + a.width > b.x + epsilon &&
+    a.y < b.y + b.height - epsilon &&
+    a.y + a.height > b.y + epsilon;
+
+  if (overlaps) {
+    throw new Error(
+      `Overlap detected between "${a.name}" and "${b.name}": ` +
+        `a=${JSON.stringify({ x: a.x, y: a.y, width: a.width, height: a.height })}, ` +
+        `b=${JSON.stringify({ x: b.x, y: b.y, width: b.width, height: b.height })}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Containment helper
+// ---------------------------------------------------------------------------
+
+function isContained(inner: Rect, outer: Rect, tolerance: number): boolean {
+  return (
+    inner.x >= outer.x - tolerance &&
+    inner.y >= outer.y - tolerance &&
+    inner.x + inner.width <= outer.x + outer.width + tolerance &&
+    inner.y + inner.height <= outer.y + outer.height + tolerance
+  );
+}
+
+function rectsOverlap(a: Rect, b: Rect, epsilon: number): boolean {
+  return (
+    a.x < b.x + b.width - epsilon &&
+    a.x + a.width > b.x + epsilon &&
+    a.y < b.y + b.height - epsilon &&
+    a.y + a.height > b.y + epsilon
+  );
+}
+
+function formatRect(r: Rect): string {
+  return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height });
+}
+
+// ---------------------------------------------------------------------------
+// Full invariant check
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a list of violation strings. Empty when clean.
+ */
+export function checkLayoutInvariants(
+  layout: ChartLayout,
+  opts: { svgWidth: number; svgHeight: number },
+): string[] {
+  const violations: string[] = [];
+
+  // 1. Legend doesn't intrude into chartArea (top/bottom only; right/bottom-right
+  //    use area.width reduction, so overlap is a horizontal concern checked by rule 4)
+  if (isCategoricalLegend(layout.legend)) {
+    const pos = layout.legend.position;
+    if (pos === 'top' || pos === 'bottom') {
+      if (rectsOverlap(layout.legend.bounds, layout.area, 0.5)) {
+        violations.push(
+          `legend intrudes into chartArea: legend=${formatRect(layout.legend.bounds)} chartArea=${formatRect(layout.area)}`,
+        );
+      }
+    }
+  }
+
+  // 2. Every legend entryPosition box lies inside legend bounds
+  if (isCategoricalLegend(layout.legend) && layout.legend.entryPositions) {
+    const rowHeight = layout.legend.rowHeight ?? 16;
+    // Entry width includes trailing entryGap; the last entry in a row doesn't
+    // need that gap to fit inside bounds, so allow entryGap as extra tolerance.
+    const gapTolerance = layout.legend.entryGap + 1;
+    for (let i = 0; i < layout.legend.entryPositions.length; i++) {
+      const pos = layout.legend.entryPositions[i];
+      const entryBox: Rect = {
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: rowHeight,
+      };
+      if (!isContained(entryBox, layout.legend.bounds, gapTolerance)) {
+        violations.push(
+          `legend entry ${i} outside legend bounds: entry=${formatRect(entryBox)} bounds=${formatRect(layout.legend.bounds)}`,
+        );
+      }
+    }
+  }
+
+  // 3. X-axis label band doesn't intersect bottom chrome
+  const xExtent = layout.axes.x?.extent;
+  if (xExtent && xExtent > 0) {
+    const xAxisBand: Rect = {
+      x: layout.area.x,
+      y: layout.area.y + layout.area.height,
+      width: layout.area.width,
+      height: xExtent,
+    };
+    const bottomChromeKeys = ['source', 'byline', 'footer'] as const;
+    for (const key of bottomChromeKeys) {
+      const el = layout.chrome[key];
+      if (el) {
+        const h = el.style.fontSize * el.style.lineHeight;
+        const top = el.style.dominantBaseline === 'hanging' ? el.y : el.y - el.style.fontSize * 0.8;
+        const chromeBox: Rect = { x: el.x, y: top, width: el.maxWidth, height: h };
+        if (rectsOverlap(xAxisBand, chromeBox, 0.5)) {
+          violations.push(
+            `x-axis labels intersect ${key}: xAxis=${formatRect(xAxisBand)} ${key}=${formatRect(chromeBox)}`,
+          );
+        }
+      }
+    }
+  }
+
+  // 4. All boxes stay within SVG viewport
+  const viewport: Rect = {
+    x: 0,
+    y: 0,
+    width: opts.svgWidth,
+    height: opts.svgHeight,
+  };
+  const allBoxes = extractBoxes(layout);
+  for (const box of allBoxes) {
+    if (!isContained(box, viewport, 2)) {
+      violations.push(
+        `${box.name} outside SVG viewport: box=${formatRect(box)} viewport=${formatRect(viewport)}`,
+      );
+    }
+  }
+
+  // 5. Reserved margins cover drawn content
+  if (layout.area.y < layout.chrome.topHeight - 1) {
+    violations.push(
+      `top chrome overflows into chart area: area.y=${layout.area.y} chrome.topHeight=${layout.chrome.topHeight}`,
+    );
+  }
+
+  return violations;
+}

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

@@ -0,0 +1,113 @@
+import type { ChartLayout, LineMark } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { describe, expect, test } from 'vitest';
+import { compileChart } from '../compile';
+
+describe('known layout bugs', () => {
+  test('annotation label does not overlap the line it annotates', () => {
+    // Generate ~25 smooth sine-wave data points over two years
+    const data: { date: string; value: number }[] = [];
+    const startDate = new Date('2022-01-01');
+    for (let i = 0; i < 25; i++) {
+      const d = new Date(startDate);
+      d.setDate(d.getDate() + i * 30); // ~monthly
+      // Sine wave: value ranges ~20-80 with a peak near i=6 (mid-2022)
+      const value = 50 + 30 * Math.sin((i / 25) * 2 * Math.PI);
+      data.push({ date: d.toISOString().slice(0, 10), value });
+    }
+
+    // The peak is near i=6 (~July 2022), where sin peaks
+    const peakIndex = 6;
+    const peakDate = data[peakIndex].date;
+    const peakValue = data[peakIndex].value;
+
+    const spec = {
+      mark: 'line' as const,
+      data,
+      encoding: {
+        x: { field: 'date' as const, type: 'temporal' as const },
+        y: { field: 'value' as const, type: 'quantitative' as const },
+      },
+      annotations: [
+        {
+          type: 'text' as const,
+          x: peakDate,
+          y: peakValue,
+          text: 'Peak season',
+        },
+      ],
+    };
+
+    const layout: ChartLayout = compileChart(spec, { width: 600, height: 400 });
+
+    // Find the annotation
+    const annotation = layout.annotations[0];
+    expect(annotation).toBeDefined();
+    expect(annotation.label).toBeDefined();
+
+    const label = annotation.label!;
+    const fontSize = label.style.fontSize;
+    const fontWeight = label.style.fontWeight;
+
+    // Estimate the label bounding box
+    const labelWidth = estimateTextWidth(label.text, fontSize, fontWeight);
+    const labelHeight = fontSize * 1.3;
+
+    // Label bounding box (y is the baseline, so top of text is y - fontSize)
+    const labelLeft =
+      label.style.textAnchor === 'middle'
+        ? label.x - labelWidth / 2
+        : label.style.textAnchor === 'end'
+          ? label.x - labelWidth
+          : label.x;
+    const labelRight = labelLeft + labelWidth;
+    const labelTop = label.y - fontSize;
+    const labelBottom = labelTop + labelHeight;
+
+    // Find the LineMark
+    const lineMark = layout.marks.find((m): m is LineMark => m.type === 'line');
+    expect(lineMark).toBeDefined();
+
+    const points = lineMark!.points;
+
+    // Find line segments that fall within the label's x-range
+    let lineMinY = Infinity;
+    let lineMaxY = -Infinity;
+
+    for (let i = 0; i < points.length - 1; i++) {
+      const p1 = points[i];
+      const p2 = points[i + 1];
+
+      // Check if this segment overlaps the label's x-range
+      const segLeft = Math.min(p1.x, p2.x);
+      const segRight = Math.max(p1.x, p2.x);
+
+      if (segRight >= labelLeft && segLeft <= labelRight) {
+        // This segment is within the label's x-range
+        // Find the y-range of the line within the label's x-span
+        const overlapLeft = Math.max(segLeft, labelLeft);
+        const overlapRight = Math.min(segRight, labelRight);
+
+        // Interpolate y values at the overlap boundaries
+        const segWidth = p2.x - p1.x;
+        if (Math.abs(segWidth) < 0.001) {
+          lineMinY = Math.min(lineMinY, p1.y, p2.y);
+          lineMaxY = Math.max(lineMaxY, p1.y, p2.y);
+        } else {
+          const t1 = (overlapLeft - p1.x) / segWidth;
+          const t2 = (overlapRight - p1.x) / segWidth;
+          const y1 = p1.y + t1 * (p2.y - p1.y);
+          const y2 = p1.y + t2 * (p2.y - p1.y);
+          lineMinY = Math.min(lineMinY, y1, y2);
+          lineMaxY = Math.max(lineMaxY, y1, y2);
+        }
+      }
+    }
+
+    // The label bounding box should NOT vertically overlap with the line's y-range.
+    // Today the label sits only ANCHOR_OFFSET (8px) from its anchor point ON the line,
+    // so the label box almost certainly overlaps the line path.
+    const verticallyOverlaps = labelTop < lineMaxY && labelBottom > lineMinY;
+    expect(verticallyOverlaps).toBe(false);
+  });
+});