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

package/src/__tests__/legend.test.ts

@@ -3,6 +3,7 @@ import { resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import { compileChart } from '../compile';
 import type { NormalizedChartSpec } from '../compiler/types';
+import { INLINE_TICK_OVERHANG_PAD } from '../layout/shared';
 import { computeLegend } from '../legend/compute';
 
 const specWithColor: NormalizedChartSpec = {
@@ -418,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)', () => {
@@ -510,6 +511,56 @@ describe('computeLegend', () => {
       const gap = layout.area.y - legendBottom;
       expect(gap).toBe(0);
     });
+
+    // Inline y ticks (line/area) draw their topmost label ABOVE chartArea.y,
+    // inside the inlineTickOverhang zone the margin stack reserved. The legend
+    // must sit above that zone, not flush against chartArea.y.
+    const inlineTopLegendSpec = {
+      mark: 'line' as const,
+      data: [
+        { date: '2020-01-01', value: 10, country: 'US' },
+        { date: '2021-01-01', value: 40, country: 'US' },
+        { date: '2020-01-01', value: 15, country: 'UK' },
+        { date: '2021-01-01', value: 35, country: 'UK' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+        color: { field: 'country', type: 'nominal' as const },
+      },
+      legend: { show: true, position: 'top' as const },
+    };
+
+    it('top legend clears the inline y-tick overhang at compact width', () => {
+      const layout = compileChart(inlineTopLegendSpec, { width: 360, height: 400 });
+
+      expect(layout.legend.position).toBe('top');
+      expect(layout.legend.entries.length).toBeGreaterThan(0);
+
+      const inlineTickOverhang = layout.theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD;
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      expect(legendBottom).toBeLessThanOrEqual(layout.area.y - inlineTickOverhang + 1e-6);
+
+      // Pinned placement. Before the fix the legend bottom sat flush at
+      // chartArea.y (legend bottom was 62 = chartArea.y), overlapping the
+      // topmost inline tick label; it now sits the 17px overhang higher,
+      // while the 6px minimum gap above the legend shifts chartArea down.
+      expect(layout.legend.bounds.y).toBe(31);
+    });
+
+    it('gutter y-ticks keep the legend flush at the legendGap (no overhang shift)', () => {
+      // Bar charts use gutter y-tick labels, so inlineTickOverhang is 0 and
+      // the legend keeps its legendGap-only offset from the chart area.
+      const layout = compileChart(topLegendSpec, { width: 600, height: 400 });
+
+      const legendBottom = layout.legend.bounds.y + layout.legend.bounds.height;
+      expect(layout.area.y - legendBottom).toBe(8);
+
+      // Pinned placement: 17 before the placement fix; the +6 comes from the
+      // TOP_LEGEND_GAP_ABOVE margin (not from any overhang shift — gutter
+      // ticks have no overhang, so the legend-to-chart gap above stays 8).
+      expect(layout.legend.bounds.y).toBe(23);
+    });
   });
 
   describe('entryPositions contract', () => {
@@ -602,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));
+      }
+    });
+  });
 });

package/src/__tests__/ranking-recipes.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Integration tests for the slope + bump chart recipes (plan 14).
+ *
+ * These are the exact specs published on docs/ranking-and-change.md and
+ * pinned as visual fixtures in examples/src/testing/fixtures-ranking.stories.tsx.
+ * They use only public spec surface: if a test here needs a private flag to
+ * pass, the recipe is broken.
+ */
+
+import type { ChartSpec, LineMark, PointMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+
+import { compileChart } from '../compile';
+
+// ---------------------------------------------------------------------------
+// Recipe specs (keep byte-identical to docs/ranking-and-change.md)
+// ---------------------------------------------------------------------------
+
+const slopeMarketShareSpec: ChartSpec = {
+  mark: 'line',
+  data: [
+    { year: '2019', brand: 'Samsung', share: 0.216 },
+    { year: '2024', brand: 'Samsung', share: 0.19 },
+    { year: '2019', brand: 'Huawei', share: 0.176 },
+    { year: '2024', brand: 'Huawei', share: 0.043 },
+    { year: '2019', brand: 'Apple', share: 0.139 },
+    { year: '2024', brand: 'Apple', share: 0.187 },
+    { year: '2019', brand: 'Xiaomi', share: 0.092 },
+    { year: '2024', brand: 'Xiaomi', share: 0.136 },
+    { year: '2019', brand: 'Oppo', share: 0.083 },
+    { year: '2024', brand: 'Oppo', share: 0.087 },
+  ],
+  encoding: {
+    x: { field: 'year', type: 'ordinal' },
+    y: {
+      field: 'share',
+      type: 'quantitative',
+      axis: false,
+      scale: { zero: false },
+    },
+    color: { field: 'brand', type: 'nominal' },
+  },
+  endpointLabels: {
+    ends: 'both',
+    content: 'label value',
+    format: '.0%',
+  },
+  legend: { show: false },
+  chrome: {
+    title: 'Apple and Xiaomi Split What Huawei Lost',
+    subtitle: 'Share of global smartphone shipments, 2019 vs 2024',
+    source: 'Source: IDC Worldwide Quarterly Mobile Phone Tracker',
+  },
+};
+
+const bumpConstructorsSpec: ChartSpec = {
+  mark: { type: 'line', interpolate: 'monotone', point: true },
+  data: [
+    { season: '2019', team: 'Mercedes', position: 1 },
+    { season: '2020', team: 'Mercedes', position: 1 },
+    { season: '2021', team: 'Mercedes', position: 1 },
+    { season: '2022', team: 'Mercedes', position: 3 },
+    { season: '2023', team: 'Mercedes', position: 2 },
+    { season: '2024', team: 'Mercedes', position: 4 },
+    { season: '2019', team: 'Red Bull', position: 3 },
+    { season: '2020', team: 'Red Bull', position: 2 },
+    { season: '2021', team: 'Red Bull', position: 2 },
+    { season: '2022', team: 'Red Bull', position: 1 },
+    { season: '2023', team: 'Red Bull', position: 1 },
+    { season: '2024', team: 'Red Bull', position: 3 },
+    { season: '2019', team: 'Ferrari', position: 2 },
+    { season: '2020', team: 'Ferrari', position: 6 },
+    { season: '2021', team: 'Ferrari', position: 3 },
+    { season: '2022', team: 'Ferrari', position: 2 },
+    { season: '2023', team: 'Ferrari', position: 3 },
+    { season: '2024', team: 'Ferrari', position: 2 },
+    { season: '2019', team: 'McLaren', position: 4 },
+    { season: '2020', team: 'McLaren', position: 3 },
+    { season: '2021', team: 'McLaren', position: 4 },
+    { season: '2022', team: 'McLaren', position: 5 },
+    { season: '2023', team: 'McLaren', position: 4 },
+    { season: '2024', team: 'McLaren', position: 1 },
+    { season: '2019', team: 'Alpine', position: 5 },
+    { season: '2020', team: 'Alpine', position: 5 },
+    { season: '2021', team: 'Alpine', position: 5 },
+    { season: '2022', team: 'Alpine', position: 4 },
+    { season: '2023', team: 'Alpine', position: 6 },
+    { season: '2024', team: 'Alpine', position: 6 },
+  ],
+  encoding: {
+    x: { field: 'season', type: 'ordinal' },
+    y: {
+      field: 'position',
+      type: 'quantitative',
+      scale: { reverse: true, zero: false },
+      axis: { values: [1, 2, 3, 4, 5, 6], format: 'ordinal' },
+    },
+    color: { field: 'team', type: 'nominal' },
+  },
+  endpointLabels: {
+    ends: 'both',
+    content: 'label',
+    showMarker: false,
+  },
+  legend: { show: false },
+  chrome: {
+    title: 'McLaren Went From Midfield to Champions',
+    subtitle: 'Formula 1 constructors championship, final position by season',
+    source: 'Source: FIA official standings',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Slope recipe
+// ---------------------------------------------------------------------------
+
+describe('slope chart recipe', () => {
+  it('renders both-end labels for all five series', () => {
+    const layout = compileChart(slopeMarketShareSpec, { width: 640, height: 420 });
+
+    expect(layout.endpointLabels?.entries).toHaveLength(5);
+    expect(layout.endpointLabels?.leading).toHaveLength(5);
+  });
+
+  it("composes 'name value' on one line at both ends", () => {
+    const layout = compileChart(slopeMarketShareSpec, { width: 640, height: 420 });
+
+    const left = layout.endpointLabels!.leading!.find((e) => e.seriesKey === 'Samsung');
+    expect(left!.labelLines[0]).toBe('Samsung 22%');
+    expect(left!.value).toBe('');
+
+    const right = layout.endpointLabels!.entries.find((e) => e.seriesKey === 'Samsung');
+    expect(right!.labelLines[0]).toBe('Samsung 19%');
+    expect(right!.value).toBe('');
+  });
+
+  it('renders no y axis and no gridlines', () => {
+    const layout = compileChart(slopeMarketShareSpec, { width: 640, height: 420 });
+
+    expect(layout.axes.y).toBeUndefined();
+  });
+
+  it('orders labels by value at each end (Huawei falls from 2nd to last)', () => {
+    const layout = compileChart(slopeMarketShareSpec, { width: 640, height: 420 });
+
+    const byY = (a: { labelY: number }, b: { labelY: number }) => a.labelY - b.labelY;
+    const leftOrder = [...layout.endpointLabels!.leading!].sort(byY).map((e) => e.seriesKey);
+    expect(leftOrder).toEqual(['Samsung', 'Huawei', 'Apple', 'Xiaomi', 'Oppo']);
+
+    const rightOrder = [...layout.endpointLabels!.entries].sort(byY).map((e) => e.seriesKey);
+    expect(rightOrder).toEqual(['Samsung', 'Apple', 'Xiaomi', 'Oppo', 'Huawei']);
+  });
+
+  it('keeps both-end labels and a positive plot area at 320px (compact breakpoint)', () => {
+    const layout = compileChart(slopeMarketShareSpec, { width: 320, height: 360 });
+
+    expect(layout.endpointLabels?.entries).toHaveLength(5);
+    expect(layout.endpointLabels?.leading).toHaveLength(5);
+    expect(layout.area.width).toBeGreaterThan(0);
+    // Both label columns fit inside the 320px canvas.
+    expect(layout.endpointLabels!.leadingBounds!.x).toBeGreaterThanOrEqual(0);
+    expect(
+      layout.endpointLabels!.bounds.x + layout.endpointLabels!.bounds.width,
+    ).toBeLessThanOrEqual(320);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bump recipe
+// ---------------------------------------------------------------------------
+
+describe('bump chart recipe', () => {
+  it('puts rank 1 at the top via scale.reverse', () => {
+    const layout = compileChart(bumpConstructorsSpec, { width: 640, height: 460 });
+
+    const ticks = layout.axes.y!.ticks;
+    const first = ticks.find((t) => t.value === 1);
+    const last = ticks.find((t) => t.value === 6);
+    expect(first).toBeDefined();
+    expect(last).toBeDefined();
+    expect(first!.position).toBeLessThan(last!.position);
+  });
+
+  it('labels rank ticks as ordinals, 1st through 6th top to bottom', () => {
+    const layout = compileChart(bumpConstructorsSpec, { width: 640, height: 460 });
+
+    const labels = [...layout.axes.y!.ticks]
+      .sort((a, b) => a.position - b.position)
+      .map((t) => t.label);
+    expect(labels).toEqual(['1st', '2nd', '3rd', '4th', '5th', '6th']);
+  });
+
+  it('draws a point marker at every step of every series', () => {
+    const layout = compileChart(bumpConstructorsSpec, { width: 640, height: 460 });
+
+    const points = layout.marks.filter(
+      (m): m is PointMark => m.type === 'point' && m.opacity !== 0,
+    );
+    // 5 teams x 6 seasons.
+    expect(points).toHaveLength(30);
+  });
+
+  it('orders both-end name labels by rank at each end', () => {
+    const layout = compileChart(bumpConstructorsSpec, { width: 640, height: 460 });
+
+    const byY = (a: { labelY: number }, b: { labelY: number }) => a.labelY - b.labelY;
+    // 2019: Mercedes 1st, Ferrari 2nd, Red Bull 3rd, McLaren 4th, Alpine 5th.
+    const leftOrder = [...layout.endpointLabels!.leading!].sort(byY).map((e) => e.seriesKey);
+    expect(leftOrder).toEqual(['Mercedes', 'Ferrari', 'Red Bull', 'McLaren', 'Alpine']);
+    // 2024: McLaren 1st, Ferrari 2nd, Red Bull 3rd, Mercedes 4th, Alpine 6th.
+    const rightOrder = [...layout.endpointLabels!.entries].sort(byY).map((e) => e.seriesKey);
+    expect(rightOrder).toEqual(['McLaren', 'Ferrari', 'Red Bull', 'Mercedes', 'Alpine']);
+  });
+
+  it('renders name-only labels (no value line)', () => {
+    const layout = compileChart(bumpConstructorsSpec, { width: 640, height: 460 });
+
+    for (const entry of layout.endpointLabels!.entries) {
+      expect(entry.labelLines).toEqual([entry.seriesKey]);
+      expect(entry.value).toBe('');
+    }
+  });
+
+  it('maps tied ranks to the same y (ties share a row)', () => {
+    const tieSpec: ChartSpec = {
+      ...bumpConstructorsSpec,
+      data: [
+        { season: '2023', team: 'A', position: 1 },
+        { season: '2024', team: 'A', position: 2 },
+        { season: '2023', team: 'B', position: 2 },
+        { season: '2024', team: 'B', position: 2 },
+        { season: '2023', team: 'C', position: 3 },
+        { season: '2024', team: 'C', position: 1 },
+      ],
+      encoding: {
+        ...bumpConstructorsSpec.encoding,
+        y: {
+          field: 'position',
+          type: 'quantitative',
+          scale: { reverse: true, zero: false },
+          axis: { values: [1, 2, 3], format: 'ordinal' },
+        },
+      },
+    };
+    const layout = compileChart(tieSpec, { width: 640, height: 400 });
+
+    const lines = layout.marks.filter(
+      (m): m is LineMark => m.type === 'line' && m.seriesKey != null,
+    );
+    const lastY = (key: string) => {
+      const mark = lines.find((m) => m.seriesKey === key)!;
+      const pts = mark.dataPoints ?? [];
+      return pts[pts.length - 1]!.y;
+    };
+    // A and B tie for 2nd in 2024: identical y.
+    expect(lastY('A')).toBeCloseTo(lastY('B'), 6);
+    // C is 1st, above the tied pair (smaller y = higher rank).
+    expect(lastY('C')).toBeLessThan(lastY('A'));
+  });
+});

package/src/__tests__/scales.test.ts

@@ -62,15 +62,21 @@ describe('computeScales', () => {
     expect(scales.y).toBeDefined();
     expect(scales.y!.type).toBe('linear');
 
-    // Y is inverted (SVG coordinates)
+    // Y is inverted (SVG coordinates); line charts default to zero: false
     const domain = scales.y!.scale.domain();
-    expect(domain[0]).toBeLessThanOrEqual(0); // Should include 0
+    expect(domain[0]).toBeLessThanOrEqual(10);
     expect(domain[1]).toBeGreaterThanOrEqual(50);
   });
 
-  it('includes zero in quantitative domain by default', () => {
+  it('line charts exclude zero by default (zero: false)', () => {
     const scales = computeScales(lineSpec, chartArea, lineSpec.data);
     const domain = scales.y!.scale.domain();
+    expect(domain[0]).toBeGreaterThan(0);
+  });
+
+  it('bar charts include zero by default', () => {
+    const scales = computeScales(barSpec, chartArea, barSpec.data);
+    const domain = scales.x!.scale.domain();
     expect(domain[0]).toBe(0);
   });
 

package/src/__tests__/series-search.test.ts

@@ -0,0 +1,92 @@
+/**
+ * seriesSearch compilation: band reservation and resolved content.
+ *
+ * The engine reserves an empty SVG band below chrome (and the metric bar)
+ * and exposes its rect + the searchable values on layout.seriesSearch; the
+ * vanilla adapter overlays the DOM combobox on that rect.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { compileChart } from '../compile';
+
+const searchSpec = {
+  mark: 'line' as const,
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 40, country: 'US' },
+    { date: '2020-01-01', value: 15, country: 'UK' },
+    { date: '2021-01-01', value: 35, country: 'UK' },
+    { date: '2020-01-01', value: 22, country: 'France' },
+    { date: '2021-01-01', value: 28, country: 'France' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' as const },
+    y: { field: 'value', type: 'quantitative' as const },
+    color: { field: 'country', type: 'nominal' as const },
+  },
+  chrome: { title: 'Find your country' },
+};
+
+describe('compileChart seriesSearch', () => {
+  it('omits the band when seriesSearch is not set', () => {
+    const layout = compileChart(searchSpec, { width: 600, height: 400 });
+    expect(layout.seriesSearch).toBeUndefined();
+  });
+
+  it('reserves a band below chrome and shifts the chart area down', () => {
+    const base = compileChart(searchSpec, { width: 600, height: 400 });
+    const layout = compileChart({ ...searchSpec, seriesSearch: true }, { width: 600, height: 400 });
+
+    const band = layout.seriesSearch;
+    expect(band).toBeDefined();
+    expect(band!.height).toBeGreaterThan(0);
+    expect(band!.width).toBeGreaterThan(0);
+    // Band sits below the top chrome block and above the chart area
+    expect(band!.y).toBeGreaterThanOrEqual(layout.chrome.topHeight);
+    expect(band!.y + band!.height).toBeLessThanOrEqual(layout.area.y);
+    // The reservation pushes the plot down relative to the no-search layout
+    expect(layout.area.y).toBeGreaterThan(base.area.y);
+  });
+
+  it('exposes the distinct color values and resolved placeholder', () => {
+    const layout = compileChart(
+      { ...searchSpec, seriesSearch: { placeholder: 'Find a country' } },
+      { width: 600, height: 400 },
+    );
+    expect(layout.seriesSearch?.values).toEqual(['US', 'UK', 'France']);
+    expect(layout.seriesSearch?.placeholder).toBe('Find a country');
+
+    const defaulted = compileChart(
+      { ...searchSpec, seriesSearch: true },
+      { width: 600, height: 400 },
+    );
+    expect(defaulted.seriesSearch?.placeholder).toBe('Find a series');
+  });
+
+  it('warns and disables when there is no categorical color encoding', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const layout = compileChart(
+        {
+          mark: 'line' as const,
+          data: [
+            { date: '2020-01-01', value: 10 },
+            { date: '2021-01-01', value: 40 },
+          ],
+          encoding: {
+            x: { field: 'date', type: 'temporal' as const },
+            y: { field: 'value', type: 'quantitative' as const },
+          },
+          seriesSearch: true,
+        },
+        { width: 600, height: 400 },
+      );
+      expect(layout.seriesSearch).toBeUndefined();
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('seriesSearch requires a categorical color encoding'),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});