@opendata-ai/openchart-engine 6.28.5 → 7.0.0

package/src/__tests__/legend.test.ts

@@ -23,7 +23,14 @@ const specWithColor: NormalizedChartSpec = {
   responsive: true,
   theme: {},
   darkMode: 'off',
+  // density: 'none' historically short-circuited the legend auto-suppression
+  // table, but post-fix that switch only governs end-of-line labels. Keep
+  // density: 'none' here AND set legend.show: true so the basic legend tests
+  // still test what they want — generic legend rendering with an explicit
+  // opt-in. Tests that need to exercise auto-suppression rules use
+  // `lineWithLabels` (density: 'auto', no explicit legend.show) further down.
   labels: { density: 'none', format: '', prefix: '' },
+  legend: { show: true },
 };
 
 const specWithoutColor: NormalizedChartSpec = {
@@ -336,6 +343,9 @@ describe('computeLegend', () => {
     const lineWithLabels: NormalizedChartSpec = {
       ...specWithColor,
       labels: { density: 'auto', format: '', prefix: '' },
+      // Drop the explicit legend opt-in inherited from specWithColor so the
+      // auto-suppression truth table actually applies.
+      legend: undefined as unknown as NormalizedChartSpec['legend'],
     };
 
     it('suppresses legend for multi-series line chart with default labels', () => {
@@ -365,12 +375,26 @@ describe('computeLegend', () => {
       expect(legend.entries).toHaveLength(3);
     });
 
-    it('preserves legend when labels density is none', () => {
+    it('still applies the truth table when labels density is none', () => {
+      // labels.density: 'none' is the legacy switch for end-of-line labels
+      // only — it must not short-circuit the legend / endpoint-column truth
+      // table. So a multi-series line with density: 'none' and no explicit
+      // legend.show still gets the legend auto-suppressed (cell 1).
       const spec: NormalizedChartSpec = {
         ...lineWithLabels,
         labels: { density: 'none', format: '', prefix: '' },
       };
       const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('preserves legend when density is none AND legend.show is explicitly true', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        labels: { density: 'none', format: '', prefix: '' },
+        legend: { show: true },
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
       expect(legend.entries).toHaveLength(3);
     });
 
@@ -379,17 +403,34 @@ describe('computeLegend', () => {
       expect(legend.entries).toHaveLength(3);
     });
 
-    it('preserves legend for stacked area chart (default stacking)', () => {
+    it('preserves legend for explicitly stacked area chart (stack: "zero")', () => {
       const areaSpec: NormalizedChartSpec = {
         ...lineWithLabels,
         markType: 'area',
         markDef: { type: 'area' },
+        encoding: {
+          x: { field: 'date', type: 'temporal' },
+          y: { field: 'value', type: 'quantitative', stack: 'zero' },
+          color: { field: 'country', type: 'nominal' },
+        },
       };
       const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
       expect(legend.entries).toHaveLength(3);
     });
 
-    it('suppresses legend for unstacked area chart with labels', () => {
+    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.
+      const areaSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'area',
+        markDef: { type: 'area' },
+      };
+      const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('suppresses legend for explicit overlap area chart (stack: null)', () => {
       const areaSpec: NormalizedChartSpec = {
         ...lineWithLabels,
         markType: 'area',

package/src/annotations/__tests__/compute.test.ts

@@ -85,6 +85,117 @@ describe('computeAnnotations', () => {
       // Invalid date should result in null annotation (filtered out)
       expect(annotations).toHaveLength(0);
     });
+
+    describe('drop-line connector', () => {
+      it('produces a vertical line through the data point with end-anchored text on the left', () => {
+        const spec = makeSpec([
+          {
+            type: 'text',
+            x: '2020-01-01',
+            y: 20,
+            text: 'Peak',
+            connector: 'drop-line',
+            anchor: 'left',
+          },
+        ]);
+        const scales = computeScales(spec, chartArea, spec.data);
+        const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+        const ann = annotations[0];
+        const c = ann.label?.connector;
+        expect(c).toBeDefined();
+        expect(c?.style).toBe('drop-line');
+        // Vertical line: from.x === to.x and equals the data point's x
+        expect(c?.from.x).toBe(c?.to.x);
+        const px = resolvePosition('2020-01-01', scales.x);
+        expect(c?.from.x).toBe(px);
+        // Label sits to the left of the data point with end anchor
+        expect(ann.label?.style.textAnchor).toBe('end');
+        expect(ann.label?.x).toBeLessThan(px ?? Infinity);
+      });
+
+      it('flips a left-anchored label to the right when there is no room on the left', () => {
+        // Place a long label very near the chart-area left edge — left side is too tight
+        const spec = makeSpec([
+          {
+            type: 'text',
+            x: '2019-01-01',
+            y: 10,
+            text: 'A long annotation that needs lots of horizontal room',
+            connector: 'drop-line',
+            anchor: 'left',
+          },
+        ]);
+        const scales = computeScales(spec, chartArea, spec.data);
+        const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+        const ann = annotations[0];
+        const px = resolvePosition('2019-01-01', scales.x);
+        expect(ann.label?.style.textAnchor).toBe('start');
+        expect(ann.label?.x).toBeGreaterThan(px ?? -Infinity);
+      });
+
+      it('flips a right-anchored label to the left when there is no room on the right', () => {
+        const spec = makeSpec([
+          {
+            type: 'text',
+            x: '2022-01-01',
+            y: 40,
+            text: 'A long annotation that needs lots of horizontal room',
+            connector: 'drop-line',
+            anchor: 'right',
+          },
+        ]);
+        const scales = computeScales(spec, chartArea, spec.data);
+        const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+        const ann = annotations[0];
+        const px = resolvePosition('2022-01-01', scales.x);
+        expect(ann.label?.style.textAnchor).toBe('end');
+        expect(ann.label?.x).toBeLessThan(px ?? Infinity);
+      });
+
+      it('picks the wider side when neither side fits cleanly', () => {
+        // Tiny chart area + long label + data point near right edge means
+        // neither side can fit the full label. Left side has more room
+        // (x=50 ... px), so the auto-flip should land left.
+        const tinyArea: typeof chartArea = { x: 50, y: 20, width: 120, height: 200 };
+        const spec = makeSpec([
+          {
+            type: 'text',
+            x: '2022-01-01',
+            y: 40,
+            text: 'A genuinely long annotation label that exceeds both sides',
+            connector: 'drop-line',
+            anchor: 'right',
+          },
+        ]);
+        const scales = computeScales(spec, tinyArea, spec.data);
+        const annotations = computeAnnotations(spec, scales, tinyArea, fullStrategy);
+
+        // anchor=right but the right side is even narrower than left, so flip
+        expect(annotations[0].label?.style.textAnchor).toBe('end');
+      });
+
+      it('preserves the resolved text-anchor on multi-line drop-line labels', () => {
+        const spec = makeSpec([
+          {
+            type: 'text',
+            x: '2020-01-01',
+            y: 20,
+            text: 'Line one\nLine two',
+            connector: 'drop-line',
+            anchor: 'left',
+          },
+        ]);
+        const scales = computeScales(spec, chartArea, spec.data);
+        const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+        // Engine output retains end anchor; the renderer relies on this to
+        // not override it back to middle.
+        expect(annotations[0].label?.style.textAnchor).toBe('end');
+      });
+    });
   });
 
   describe('range annotations', () => {

package/src/annotations/__tests__/resolve-text.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Tests for the text-annotation resolver, focused on the `dot` and
+ * `subtitle` fields added in the multi-series area redesign.
+ */
+
+import type { Annotation, LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import { computeScales } from '../../layout/scales';
+import { computeAnnotations } from '../compute';
+import {
+  DARK_DOT_FILL,
+  DARK_MUTED_TEXT_FILL,
+  DARK_TEXT_FILL,
+  DEFAULT_ANNOTATION_FONT_SIZE,
+  DEFAULT_DOT_RADIUS,
+  DEFAULT_DOT_STROKE_WIDTH,
+  DEFAULT_LINE_HEIGHT,
+  LIGHT_DOT_FILL,
+  LIGHT_MUTED_TEXT_FILL,
+  LIGHT_TEXT_FILL,
+  SUBTITLE_FONT_SIZE_RATIO,
+  SUBTITLE_GAP,
+} from '../constants';
+
+const chartArea: Rect = { x: 50, y: 20, width: 500, height: 300 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+function makeSpec(annotations: Annotation[]): NormalizedChartSpec {
+  return {
+    markType: 'line',
+    markDef: { type: 'line' },
+    data: [
+      { date: '2019-01-01', value: 10 },
+      { date: '2020-01-01', value: 20 },
+      { date: '2021-01-01', value: 30 },
+      { date: '2022-01-01', value: 40 },
+    ],
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+    },
+    chrome: {},
+    annotations,
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+describe('text annotation: dot', () => {
+  it('does not populate dot when not specified', () => {
+    const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'No dot' }]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    expect(annotations[0].dot).toBeUndefined();
+  });
+
+  it('populates dot with default styling when dot: true (light mode)', () => {
+    const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'With dot', dot: true }]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy, false);
+
+    const dot = annotations[0].dot;
+    expect(dot).toBeDefined();
+    expect(dot!.radius).toBe(DEFAULT_DOT_RADIUS);
+    expect(dot!.strokeWidth).toBe(DEFAULT_DOT_STROKE_WIDTH);
+    expect(dot!.fill).toBe(LIGHT_DOT_FILL);
+    expect(dot!.stroke).toBe(LIGHT_TEXT_FILL);
+  });
+
+  it('populates dot with dark-mode defaults when isDark is true', () => {
+    const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'Dark', dot: true }]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy, true);
+
+    const dot = annotations[0].dot;
+    expect(dot).toBeDefined();
+    expect(dot!.fill).toBe(DARK_DOT_FILL);
+    expect(dot!.stroke).toBe(DARK_TEXT_FILL);
+  });
+
+  it('respects user-supplied dot style overrides', () => {
+    const spec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'Custom dot',
+        dot: { radius: 8, fill: '#ff00ff', stroke: '#00ff00', strokeWidth: 4 },
+      },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const dot = annotations[0].dot;
+    expect(dot).toBeDefined();
+    expect(dot!.radius).toBe(8);
+    expect(dot!.fill).toBe('#ff00ff');
+    expect(dot!.stroke).toBe('#00ff00');
+    expect(dot!.strokeWidth).toBe(4);
+  });
+
+  it('partial dot overrides merge with defaults', () => {
+    const spec = makeSpec([
+      { type: 'text', x: '2020-01-01', y: 20, text: 'Partial', dot: { radius: 3 } },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const dot = annotations[0].dot;
+    expect(dot).toBeDefined();
+    expect(dot!.radius).toBe(3);
+    // Other fields fall back to defaults.
+    expect(dot!.fill).toBe(LIGHT_DOT_FILL);
+    expect(dot!.stroke).toBe(LIGHT_TEXT_FILL);
+    expect(dot!.strokeWidth).toBe(DEFAULT_DOT_STROKE_WIDTH);
+  });
+
+  it('dot coordinates match the connector "to" endpoint exactly', () => {
+    const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'Co-render', dot: true }]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const resolved = annotations[0];
+    expect(resolved.dot).toBeDefined();
+    expect(resolved.label?.connector).toBeDefined();
+    expect(resolved.dot!.x).toBe(resolved.label!.connector!.to.x);
+    expect(resolved.dot!.y).toBe(resolved.label!.connector!.to.y);
+  });
+
+  it('dot coordinates apply user connectorOffset.to', () => {
+    const withoutOffset = computeAnnotations(
+      makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'A', dot: true }]),
+      computeScales(makeSpec([]), chartArea, []),
+      chartArea,
+      fullStrategy,
+    );
+    const baseDot = withoutOffset[0].dot!;
+
+    const withOffsetSpec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'A',
+        dot: true,
+        connectorOffset: { to: { dx: 10, dy: -5 } },
+      },
+    ]);
+    const scales2 = computeScales(withOffsetSpec, chartArea, withOffsetSpec.data);
+    const withOffset = computeAnnotations(withOffsetSpec, scales2, chartArea, fullStrategy);
+    const offsetDot = withOffset[0].dot!;
+
+    // The user's connector offset shifts the data-side endpoint, so the dot
+    // should track it. Exact equality with connector.to must hold.
+    expect(offsetDot.x).toBe(withOffset[0].label!.connector!.to.x);
+    expect(offsetDot.y).toBe(withOffset[0].label!.connector!.to.y);
+    // And it should differ from the un-offset case (sanity check).
+    expect(offsetDot.x).not.toBe(baseDot.x);
+  });
+});
+
+describe('text annotation: subtitle', () => {
+  it('does not populate subtitle when not specified', () => {
+    const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'No subtitle' }]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    expect(annotations[0].subtitle).toBeUndefined();
+  });
+
+  it('populates subtitle with muted styling and smaller font (light mode)', () => {
+    const spec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'Primary',
+        subtitle: 'Methodology note',
+      },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy, false);
+
+    const sub = annotations[0].subtitle;
+    expect(sub).toBeDefined();
+    expect(sub!.text).toBe('Methodology note');
+    expect(sub!.style.fill).toBe(LIGHT_MUTED_TEXT_FILL);
+    expect(sub!.style.fontSize).toBe(
+      Math.round(DEFAULT_ANNOTATION_FONT_SIZE * SUBTITLE_FONT_SIZE_RATIO),
+    );
+  });
+
+  it('populates subtitle with dark-mode muted color when isDark', () => {
+    const spec = makeSpec([
+      { type: 'text', x: '2020-01-01', y: 20, text: 'Primary', subtitle: 'Note' },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy, true);
+
+    expect(annotations[0].subtitle!.style.fill).toBe(DARK_MUTED_TEXT_FILL);
+  });
+
+  it('positions subtitle directly below single-line primary text', () => {
+    const spec = makeSpec([
+      { type: 'text', x: '2020-01-01', y: 20, text: 'One line', subtitle: 'sub' },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const label = annotations[0].label!;
+    const sub = annotations[0].subtitle!;
+    const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+    const expectedY = label.y + fontSize * DEFAULT_LINE_HEIGHT * 1 + SUBTITLE_GAP;
+    expect(sub.y).toBe(expectedY);
+    expect(sub.x).toBe(label.x);
+  });
+
+  it('positions subtitle below all primary lines when text contains newlines', () => {
+    const spec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'Line one\nLine two\nLine three',
+        subtitle: 'after multi-line',
+      },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const label = annotations[0].label!;
+    const sub = annotations[0].subtitle!;
+    const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+    const expectedY = label.y + fontSize * DEFAULT_LINE_HEIGHT * 3 + SUBTITLE_GAP;
+    expect(sub.y).toBe(expectedY);
+  });
+
+  it('subtitle font size scales with custom primary fontSize', () => {
+    const spec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'Big',
+        fontSize: 20,
+        subtitle: 'small',
+      },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    expect(annotations[0].subtitle!.style.fontSize).toBe(Math.round(20 * SUBTITLE_FONT_SIZE_RATIO));
+  });
+});
+
+describe('text annotation: dot + subtitle co-resolution', () => {
+  it('both fields resolve simultaneously without interfering', () => {
+    const spec = makeSpec([
+      {
+        type: 'text',
+        x: '2020-01-01',
+        y: 20,
+        text: 'Big moment',
+        subtitle: 'Adjusted for inflation',
+        dot: true,
+      },
+    ]);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+    const resolved = annotations[0];
+    expect(resolved.dot).toBeDefined();
+    expect(resolved.subtitle).toBeDefined();
+    // Connector + dot still co-render at the same point.
+    expect(resolved.dot!.x).toBe(resolved.label!.connector!.to.x);
+    expect(resolved.dot!.y).toBe(resolved.label!.connector!.to.y);
+  });
+});

package/src/annotations/constants.ts

@@ -22,6 +22,26 @@ export const DARK_TEXT_FILL = '#d1d5db';
 export const LIGHT_REFLINE_STROKE = '#888888';
 export const DARK_REFLINE_STROKE = '#9ca3af';
 
+// Muted text fill for annotation subtitles (~60% perceived contrast vs primary)
+export const LIGHT_MUTED_TEXT_FILL = '#6b7280';
+export const DARK_MUTED_TEXT_FILL = '#9ca3af';
+
+// Background fills used as the default "open ring" dot interior
+export const LIGHT_DOT_FILL = '#ffffff';
+export const DARK_DOT_FILL = '#0a0a0a';
+
+/** Default annotation dot radius in pixels. */
+export const DEFAULT_DOT_RADIUS = 5;
+
+/** Default annotation dot stroke width in pixels. */
+export const DEFAULT_DOT_STROKE_WIDTH = 2;
+
+/** Vertical gap (px) between the primary annotation text and its subtitle. */
+export const SUBTITLE_GAP = 2;
+
+/** Subtitle font size multiplier (relative to primary annotation font size). */
+export const SUBTITLE_FONT_SIZE_RATIO = 0.85;
+
 /** Default label offset when using anchor directions. */
 export const ANCHOR_OFFSET = 8;