@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/__tests__/helpers/invariants.ts

@@ -28,6 +28,16 @@ function isCategoricalLegend(legend: LegendLayout): legend is CategoricalLegendL
   return 'entries' in legend && (!legend.type || legend.type === 'categorical');
 }
 
+/**
+ * Every legend on the layout. Falls back to the singular `legend` slot so this
+ * still works against layouts built by older code paths (and by tests that
+ * hand-assemble a ChartLayout).
+ */
+function allLegends(layout: ChartLayout): LegendLayout[] {
+  if (layout.legends?.length) return layout.legends;
+  return layout.legend ? [layout.legend] : [];
+}
+
 // ---------------------------------------------------------------------------
 // Box extraction
 // ---------------------------------------------------------------------------
@@ -51,21 +61,27 @@ export function extractBoxes(layout: ChartLayout): 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}`,
-      });
+  // Legend bounds -- EVERY legend, not just the primary. A chart can carry both
+  // a color legend and a size legend; registering only `layout.legend` would
+  // leave the overlap invariants blind to exactly the element most likely to be
+  // mis-reserved, and they would pass a chart whose size legend sits on the plot.
+  for (const legend of allLegends(layout)) {
+    const suffix = legend.channel && legend.channel !== 'color' ? `-${legend.channel}` : '';
+    boxes.push({ ...legend.bounds, name: `legend${suffix}` });
+
+    // Legend entry positions (categorical only)
+    if (isCategoricalLegend(legend) && legend.entryPositions) {
+      const rowHeight = legend.rowHeight ?? 16;
+      for (let i = 0; i < legend.entryPositions.length; i++) {
+        const pos = legend.entryPositions[i];
+        boxes.push({
+          x: pos.x,
+          y: pos.y,
+          width: pos.width,
+          height: rowHeight,
+          name: `legend${suffix}-entry-${i}`,
+        });
+      }
     }
   }
 
@@ -179,14 +195,32 @@ export function checkLayoutInvariants(
 ): string[] {
   const violations: string[] = [];
 
-  // 1. Legend doesn't intrude into chartArea (top/bottom only; right/bottom-right
+  // 1. No legend intrudes 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;
+  //
+  //    Checked for EVERY legend and every legend type. A size legend is not
+  //    categorical, and it is the one whose space is most likely to be
+  //    under-reserved -- gating this on `isCategoricalLegend` would skip it.
+  for (const legend of allLegends(layout)) {
+    if (legend.bounds.width <= 0 || legend.bounds.height <= 0) continue;
+    const pos = legend.position;
     if (pos === 'top' || pos === 'bottom') {
-      if (rectsOverlap(layout.legend.bounds, layout.area, 0.5)) {
+      if (rectsOverlap(legend.bounds, layout.area, 0.5)) {
+        const name = legend.channel ?? 'color';
+        violations.push(
+          `${name} legend intrudes into chartArea: legend=${formatRect(legend.bounds)} chartArea=${formatRect(layout.area)}`,
+        );
+      }
+    }
+  }
+
+  // 1b. Legends don't overlap each other.
+  const legends = allLegends(layout).filter((l) => l.bounds.width > 0 && l.bounds.height > 0);
+  for (let i = 0; i < legends.length; i++) {
+    for (let j = i + 1; j < legends.length; j++) {
+      if (rectsOverlap(legends[i].bounds, legends[j].bounds, 0.5)) {
         violations.push(
-          `legend intrudes into chartArea: legend=${formatRect(layout.legend.bounds)} chartArea=${formatRect(layout.area)}`,
+          `legends overlap: ${legends[i].channel ?? 'color'}=${formatRect(legends[i].bounds)} ${legends[j].channel ?? 'color'}=${formatRect(legends[j].bounds)}`,
         );
       }
     }

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

@@ -1,6 +1,7 @@
 import type { ChartLayout, LineMark } from '@opendata-ai/openchart-core';
 import { estimateTextWidth } from '@opendata-ai/openchart-core';
 import { describe, expect, test } from 'vitest';
+import { ANCHOR_OFFSET, ARROWHEAD_LENGTH, MIN_CONNECTOR_LENGTH } from '../annotations/constants';
 import { compileChart } from '../compile';
 
 describe('known layout bugs', () => {
@@ -105,9 +106,461 @@ describe('known layout bugs', () => {
     }
 
     // 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.
+    // The label sits ANCHOR_OFFSET (28px) off its anchor point on the line, which
+    // is sized to clear both the marker and the line path.
     const verticallyOverlaps = labelTop < lineMaxY && labelBottom > lineMinY;
     expect(verticallyOverlaps).toBe(false);
   });
+
+  // Regression: the collision pass calls `refreshConnector` on every annotation it
+  // moves, and that rebuilt `from`/`to` from a ray-box exit toward the target. A
+  // drop-line is not a leader — it's a vertical rule pinned to the data point's x
+  // — so the rebuild tilted it into a diagonal (which the renderer then draws with
+  // shape-rendering: crispEdges, assuming axis alignment), and the
+  // MIN_CONNECTOR_LENGTH rule could delete it outright.
+  //
+  // Two drop-lines placed close enough to collide is what makes this observable:
+  // a lone annotation is never shifted, so `refreshConnector` never runs and the
+  // bug hides. Against the unfixed code this pair yields a 12.9px-diagonal first
+  // connector and a *deleted* second one.
+  describe('drop-line connectors survive the collision pass', () => {
+    const collidingDropLines = () =>
+      compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+            { m: 'Mar', v: 48 },
+            { m: 'Apr', v: 30 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [
+            {
+              type: 'text' as const,
+              x: 'Feb',
+              y: 50,
+              text: 'First drop-line here',
+              connector: 'drop-line' as const,
+            },
+            {
+              type: 'text' as const,
+              x: 'Mar',
+              y: 48,
+              text: 'Second drop-line here',
+              connector: 'drop-line' as const,
+            },
+          ],
+        },
+        { width: 800, height: 460 },
+      ).annotations ?? [];
+
+    // One test, not three. The `x` pinning is the only assertion the generic
+    // ray-box rebuild actually breaks -- it preserves `style` through its
+    // `{ ...connector }` spread, and this geometry happens to land on
+    // `exit: 'vertical'` either way, so splitting those into their own tests just
+    // manufactured two that pass with the fix reverted.
+    test('stay vertical, with x pinned to the data point', () => {
+      const annotations = collidingDropLines();
+      expect(annotations).toHaveLength(2);
+      for (const annotation of annotations) {
+        const connector = annotation.label?.connector;
+        // Survived the min-length rule (the generic rebuild can shorten a
+        // drop-line enough to delete it outright).
+        expect(connector).toBeDefined();
+        // The whole contract of a drop-line: from.x === to.x === the point's x.
+        expect(connector?.from.x).toBeCloseTo(connector?.to.x ?? Number.NaN, 5);
+        expect(connector?.from.x).toBeCloseTo(annotation.dot?.x ?? Number.NaN, 5);
+        expect(connector?.style).toBe('drop-line');
+        expect(connector?.exit).toBe('vertical');
+      }
+    });
+  });
+
+  // Regression: the engine gated connectors on `length >= MIN_CONNECTOR_LENGTH`,
+  // but the renderer stops an ARROWED stroke `ARROWHEAD_LENGTH` (7px) short and
+  // spends that budget on the head. So an 8.1px arrowed connector cleared the 8px
+  // gate and then shipped a 1.1px stub with an arrowhead stuck on the end. Sharing
+  // the constant didn't fix it: both sides had the number, only one reasoned about
+  // it. The gate now measures what actually gets stroked.
+  describe('the connector min-length gate accounts for the arrowhead', () => {
+    const strokeFor = (arrow: boolean, dy: number) => {
+      const annotation = compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+            { m: 'Mar', v: 30 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [
+            {
+              type: 'text' as const,
+              x: 'Mar',
+              y: 30,
+              text: 'Note',
+              anchor: 'top' as const,
+              offset: { dx: 0, dy },
+              connector: arrow ? { type: 'straight' as const, arrow: true } : 'straight',
+            },
+          ],
+        },
+        { width: 800, height: 460 },
+      ).annotations?.[0];
+
+      const connector = annotation?.label?.connector;
+      if (!connector) return null;
+      const length = Math.hypot(
+        connector.to.x - connector.from.x,
+        connector.to.y - connector.from.y,
+      );
+      // What the renderer actually strokes.
+      return arrow ? length - ARROWHEAD_LENGTH : length;
+    };
+
+    test('an arrowed connector never ships a stroke shorter than the minimum', () => {
+      // dy: 6 is the case that used to slip through -- an 8.10px connector that
+      // stroked 1.10px once the head took its 7px.
+      for (let dy = 0; dy <= 8; dy++) {
+        const stroke = strokeFor(true, dy);
+        if (stroke === null) continue; // suppressed outright, which is correct
+        expect(stroke).toBeGreaterThanOrEqual(MIN_CONNECTOR_LENGTH);
+      }
+    });
+
+    test('the plain (non-arrowed) gate is unchanged', () => {
+      // The head costs nothing here, so the full length is the stroke and the
+      // original 8px rule still holds. Guards against "fixing" the arrow case by
+      // tightening the gate for everyone.
+      for (let dy = 0; dy <= 8; dy++) {
+        const stroke = strokeFor(false, dy);
+        if (stroke === null) continue;
+        expect(stroke).toBeGreaterThanOrEqual(MIN_CONNECTOR_LENGTH);
+      }
+      // And a short-but-legal plain connector still draws.
+      expect(strokeFor(false, 0)).not.toBeNull();
+    });
+  });
+
+  // Regression: `resolveTextAnnotation` bolts the lede rule on (a `subtitle`
+  // promotes the primary line to 700) BEFORE branching to the drop-line resolver,
+  // which used to resolve no subtitle at all. Net effect: authoring a subtitle on
+  // a drop-line silently threw the subtitle away but still bolded the primary --
+  // a field whose only visible effect was a mystery weight change.
+  describe('a drop-line annotation honors its subtitle', () => {
+    // Annotate Mar, not the Feb maximum: a callout on the chart's top value clamps
+    // against the chart edge and has nowhere to go, which is a separate (and
+    // legitimate) degradation. This is the ordinary case.
+    const dropLineWithSubtitle = () =>
+      compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+            { m: 'Mar', v: 30 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [
+            {
+              type: 'text' as const,
+              x: 'Mar',
+              y: 30,
+              text: 'Peak',
+              subtitle: 'the highest month',
+              connector: 'drop-line' as const,
+            },
+          ],
+        },
+        { width: 800, height: 460 },
+      ).annotations?.[0];
+
+    test('resolves the subtitle instead of dropping it', () => {
+      const annotation = dropLineWithSubtitle();
+      expect(annotation?.subtitle?.text).toBe('the highest month');
+    });
+
+    test('still promotes the primary line to a bold lede', () => {
+      expect(dropLineWithSubtitle()?.label?.style.fontWeight).toBe(700);
+    });
+
+    test('renders the subtitle below the primary line, left edges aligned', () => {
+      const annotation = dropLineWithSubtitle();
+      expect(annotation?.subtitle?.y).toBeGreaterThan(annotation?.label?.y ?? Number.NaN);
+      expect(annotation?.subtitle?.x).toBeCloseTo(annotation?.label?.x ?? Number.NaN, 5);
+    });
+
+    test('the whole block stays above the data point, so the line still drops', () => {
+      // A drop-line runs DOWN from the block to the point. The subtitle makes the
+      // block taller and wider, which made it collide with the line mark -- and the
+      // obstacle nudge then shoved it *below* the point, inverting the connector so
+      // it pointed up, away from the data, with the block sitting on the mark.
+      const annotation = dropLineWithSubtitle();
+      const bounds = annotation?.bounds;
+      const dotY = annotation?.dot?.y ?? Number.NaN;
+      expect((bounds?.y ?? Number.NaN) + (bounds?.height ?? Number.NaN)).toBeLessThanOrEqual(dotY);
+
+      const connector = annotation?.label?.connector;
+      expect(connector?.from.y).toBeLessThan(connector?.to.y ?? Number.NaN);
+    });
+
+    test('the block bounds cover the subtitle, so collisions see it', () => {
+      const annotation = dropLineWithSubtitle();
+      const bounds = annotation?.bounds;
+      const labelBounds = annotation?.label?.bounds;
+      // `bounds` is the union; `label.bounds` stays label-only (the renderer sizes
+      // the background plate from it).
+      expect(bounds?.height).toBeGreaterThan(labelBounds?.height ?? Number.NaN);
+    });
+  });
+
+  // Regression: `compute.ts` stamped `result.bounds` (the UNION of label and
+  // subtitle, which is what placement scores) into `label.bounds`, whose contract
+  // is the label-only text box. The renderer sizes the `background` plate from
+  // `label.bounds`, so an auto-placed annotation with a subtitle got a plate sized
+  // to both lines while the explicit path got one sized to the label.
+  test('auto-placed label bounds are the label box, not the label+subtitle union', () => {
+    const layout = compileChart(
+      {
+        mark: 'line' as const,
+        data: [
+          { m: 'Jan', v: 10 },
+          { m: 'Feb', v: 50 },
+          { m: 'Mar', v: 30 },
+        ],
+        encoding: {
+          x: { field: 'm' as const, type: 'ordinal' as const },
+          y: { field: 'v' as const, type: 'quantitative' as const },
+        },
+        annotations: [
+          // No anchor/offset => the auto-placement path.
+          {
+            type: 'text' as const,
+            x: 'Feb',
+            y: 50,
+            text: 'Peak',
+            subtitle: 'a considerably wider subtitle line',
+          },
+        ],
+      },
+      { width: 800, height: 460 },
+    );
+    const annotation = layout.annotations?.[0];
+    const labelBounds = annotation?.label?.bounds;
+    const unionBounds = annotation?.bounds;
+    expect(labelBounds).toBeDefined();
+    expect(unionBounds).toBeDefined();
+
+    // The subtitle is wider and sits below, so the union must be strictly bigger.
+    // If label.bounds were the union, these would be identical.
+    expect(labelBounds?.width).toBeLessThan(unionBounds?.width ?? 0);
+    expect(labelBounds?.height).toBeLessThan(unionBounds?.height ?? 0);
+  });
+
+  // Regression: `anchor: 'top'`/`'bottom'` render with textAnchor 'start', so the
+  // block used to hang entirely to the RIGHT of its data point — "above" read as
+  // "up and to the right", and authors had to hand-compute a negative dx of about
+  // half the block width to re-center it. The block now straddles the point
+  // horizontally; the TEXT inside stays left-aligned (ragged right).
+  describe('top/bottom anchored blocks straddle their data point', () => {
+    const centerOffsetFor = (annotation: Record<string, unknown>) => {
+      const layout = compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+            { m: 'Mar', v: 30 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [annotation],
+        },
+        { width: 800, height: 460 },
+      );
+      const resolved = layout.annotations?.[0];
+      const bounds = resolved?.label?.bounds;
+      const pointX = resolved?.dot?.x;
+      if (!bounds || pointX === undefined) throw new Error('annotation did not resolve');
+      return bounds.x + bounds.width / 2 - pointX;
+    };
+
+    /** The block's horizontal span expressed relative to the data point. */
+    const spanAround = (annotation: Record<string, unknown>) => {
+      const layout = compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+            { m: 'Mar', v: 30 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [annotation],
+        },
+        { width: 800, height: 460 },
+      );
+      const resolved = layout.annotations?.[0];
+      const bounds = resolved?.label?.bounds;
+      const pointX = resolved?.dot?.x;
+      if (!bounds || pointX === undefined) throw new Error('annotation did not resolve');
+      return { left: bounds.x - pointX, right: bounds.x + bounds.width - pointX };
+    };
+
+    test('a single-line top-anchored block centers on its point', () => {
+      expect(
+        centerOffsetFor({ type: 'text', x: 'Feb', y: 50, text: 'Peak here', anchor: 'top' }),
+      ).toBeCloseTo(0, 1);
+    });
+
+    test('a multi-line top-anchored block centers on its point', () => {
+      expect(
+        centerOffsetFor({
+          type: 'text',
+          x: 'Feb',
+          y: 50,
+          text: 'Hurricanes and\na strike cut',
+          anchor: 'top',
+        }),
+      ).toBeCloseTo(0, 1);
+    });
+
+    test('a multi-line bottom-anchored block centers on its point', () => {
+      expect(
+        centerOffsetFor({
+          type: 'text',
+          x: 'Feb',
+          y: 50,
+          text: 'Two lines\nhere now',
+          anchor: 'bottom',
+        }),
+      ).toBeCloseTo(0, 1);
+    });
+
+    test('the text inside stays left-aligned, not center-aligned', () => {
+      const layout = compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { m: 'Jan', v: 10 },
+            { m: 'Feb', v: 50 },
+          ],
+          encoding: {
+            x: { field: 'm' as const, type: 'ordinal' as const },
+            y: { field: 'v' as const, type: 'quantitative' as const },
+          },
+          annotations: [
+            { type: 'text' as const, x: 'Feb', y: 50, text: 'Two\nlines', anchor: 'top' as const },
+          ],
+        },
+        { width: 800, height: 460 },
+      );
+      expect(layout.annotations?.[0]?.label?.style?.textAnchor).toBe('start');
+    });
+
+    test('left/right anchors are unaffected (block sits beside the point)', () => {
+      // "Beside", not "straddling": the whole block clears the point by exactly the
+      // ANCHOR_OFFSET setback (28px), so the point lies OUTSIDE the block's x-span.
+      // A sign check alone (`centerOffset < 0`) still passes for a centered block
+      // that has merely drifted — which is the regression this guards.
+
+      const left = spanAround({ type: 'text', x: 'Feb', y: 50, text: 'Left side', anchor: 'left' });
+      // Whole block to the LEFT: its near (right) edge stops one setback short of
+      // the point, so the point never falls inside the span.
+      expect(left.right).toBeCloseTo(-ANCHOR_OFFSET, 1);
+      expect(left.left).toBeLessThan(left.right);
+
+      const right = spanAround({
+        type: 'text',
+        x: 'Feb',
+        y: 50,
+        text: 'Right side',
+        anchor: 'right',
+      });
+      // Mirror image: near (left) edge starts one setback past the point.
+      expect(right.left).toBeCloseTo(ANCHOR_OFFSET, 1);
+      expect(right.right).toBeGreaterThan(right.left);
+
+      // And the contrast that gives "beside" its meaning: a top anchor STRADDLES,
+      // i.e. the point lies strictly inside the block's x-span.
+      const top = spanAround({ type: 'text', x: 'Feb', y: 50, text: 'Left side', anchor: 'top' });
+      expect(top.left).toBeLessThan(0);
+      expect(top.right).toBeGreaterThan(0);
+    });
+  });
+
+  describe('annotation typography survives normalization', () => {
+    const baseSpec = (annotation: Record<string, unknown>) => ({
+      mark: 'line' as const,
+      data: [
+        { year: '1980', value: 0.26 },
+        { year: '2025', value: 1.17 },
+      ],
+      encoding: {
+        x: { field: 'year' as const, type: 'ordinal' as const },
+        y: { field: 'value' as const, type: 'quantitative' as const },
+      },
+      annotations: [annotation],
+    });
+
+    const styleOf = (annotation: Record<string, unknown>) => {
+      const layout = compileChart(baseSpec(annotation), { width: 800, height: 460 });
+      const style = layout.annotations?.[0]?.label?.style;
+      if (!style) throw new Error('annotation did not resolve a label style');
+      return style;
+    };
+
+    test('a subtitle promotes the primary line to a bold lede', () => {
+      const style = styleOf({
+        type: 'text',
+        x: '2025',
+        y: 1.17,
+        text: 'Peak',
+        subtitle: 'the warmest year on record',
+      });
+      expect(style.fontWeight).toBe(700);
+    });
+
+    test('a plain annotation stays regular weight', () => {
+      const style = styleOf({ type: 'text', x: '2025', y: 1.17, text: 'Peak' });
+      expect(style.fontWeight).toBe(400);
+    });
+
+    test('the default font size reaches the compiled output', () => {
+      const style = styleOf({ type: 'text', x: '2025', y: 1.17, text: 'Peak' });
+      expect(style.fontSize).toBe(13);
+    });
+
+    test('an explicit fontWeight beats the lede rule', () => {
+      const style = styleOf({
+        type: 'text',
+        x: '2025',
+        y: 1.17,
+        text: 'Peak',
+        subtitle: 'context',
+        fontWeight: 300,
+      });
+      expect(style.fontWeight).toBe(300);
+    });
+
+    test('an explicit fontSize beats the default', () => {
+      const style = styleOf({ type: 'text', x: '2025', y: 1.17, text: 'Peak', fontSize: 18 });
+      expect(style.fontSize).toBe(18);
+    });
+  });
 });