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

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

package/src/__tests__/legend.test.ts

@@ -419,16 +419,16 @@ describe('computeLegend', () => {
       expect(legend.entries).toHaveLength(3);
     });
 
-    it('suppresses legend for default (overlap) area chart with labels', () => {
-      // v6: area defaults to overlap. Endpoint labels identify series, so
-      // the legend auto-suppresses just like line charts.
+    it('preserves legend for default (stacked) area chart', () => {
+      // v8: area stacks by default (Vega-Lite aligned). Stacked areas keep
+      // the traditional legend rather than auto-suppressing for endpoint labels.
       const areaSpec: NormalizedChartSpec = {
         ...lineWithLabels,
         markType: 'area',
         markDef: { type: 'area' },
       };
       const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
-      expect(legend.entries).toHaveLength(0);
+      expect(legend.entries).toHaveLength(3);
     });
 
     it('suppresses legend for explicit overlap area chart (stack: null)', () => {
@@ -653,4 +653,69 @@ describe('computeLegend', () => {
       expect(legend.entries).toHaveLength(3);
     });
   });
+
+  describe('swatch colors match mark colors', () => {
+    const energySpec = {
+      mark: 'waffle' as const,
+      data: [
+        { source: 'Fossil fuels', share: 60 },
+        { source: 'Renewables', share: 30 },
+        { source: 'Nuclear', share: 10 },
+      ],
+      encoding: {
+        theta: { field: 'share', type: 'quantitative' as const },
+        color: { field: 'source', type: 'nominal' as const },
+      },
+    };
+
+    /**
+     * Map each category to the fill its marks actually render with. Waffle
+     * cells carry the category in `data`, not `seriesKey`, so key off the
+     * color field.
+     */
+    function markFillByLabel(layout: ReturnType<typeof compileChart>): Map<string, string> {
+      const fills = new Map<string, string>();
+      for (const mark of layout.marks) {
+        const label = mark.data?.source;
+        const fill = 'fill' in mark ? mark.fill : undefined;
+        if (typeof label === 'string' && typeof fill === 'string') fills.set(label, fill);
+      }
+      return fills;
+    }
+
+    it('mutes the swatches of non-highlighted series alongside their marks', () => {
+      const layout = compileChart(
+        {
+          ...energySpec,
+          encoding: {
+            ...energySpec.encoding,
+            color: { ...energySpec.encoding.color, highlight: 'Renewables' },
+          },
+        },
+        { width: 600, height: 400 },
+      );
+
+      const fills = markFillByLabel(layout);
+      expect(layout.legend.entries.length).toBe(3);
+      for (const entry of layout.legend.entries) {
+        expect(entry.color).toBe(fills.get(entry.label));
+      }
+
+      // The muted pair share one gray; the highlighted series does not.
+      const highlighted = layout.legend.entries.find((e) => e.label === 'Renewables');
+      const muted = layout.legend.entries.filter((e) => e.label !== 'Renewables');
+      expect(muted.map((e) => e.color)).toEqual([muted[0].color, muted[0].color]);
+      expect(highlighted?.color).not.toBe(muted[0].color);
+    });
+
+    it('matches mark colors when no highlight is active', () => {
+      const layout = compileChart(energySpec, { width: 600, height: 400 });
+
+      const fills = markFillByLabel(layout);
+      expect(layout.legend.entries.length).toBe(3);
+      for (const entry of layout.legend.entries) {
+        expect(entry.color).toBe(fills.get(entry.label));
+      }
+    });
+  });
 });