@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/compiler/__tests__/normalize.test.ts

@@ -0,0 +1,399 @@
+import type {
+  ChartSpec,
+  GraphSpec,
+  LayerSpec,
+  MapSpec,
+  RangeAnnotation,
+  RefLineAnnotation,
+  SankeySpec,
+  TableSpec,
+  TextAnnotation,
+} from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedMapSpec } from '../../geo/types';
+import type { NormalizedSankeySpec } from '../../sankey/types';
+import { normalizeSpec } from '../normalize';
+import type { NormalizedChartSpec, NormalizedGraphSpec, NormalizedTableSpec } from '../types';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const lineSpec: ChartSpec = {
+  mark: 'line',
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 20, country: 'UK' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' },
+    y: { field: 'value', type: 'quantitative' },
+  },
+  chrome: {
+    title: 'GDP Growth',
+    subtitle: { text: 'Over time', style: { fontSize: 16 } },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('normalizeSpec', () => {
+  describe('chart spec normalization', () => {
+    it('fills default values for optionals', () => {
+      const warnings: string[] = [];
+      const result = normalizeSpec(lineSpec, warnings) as NormalizedChartSpec;
+
+      expect(result.responsive).toBe(true);
+      expect(result.darkMode).toBe('off');
+      expect(result.annotations).toEqual([]);
+      expect(result.theme).toEqual({});
+      expect(result.labels).toEqual({
+        density: 'auto',
+        format: '',
+        prefix: '',
+        offsets: undefined,
+      });
+    });
+
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(lineSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: ChartSpec = { ...lineSpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
+    it('preserves explicit values', () => {
+      const spec: ChartSpec = {
+        ...lineSpec,
+        responsive: false,
+        darkMode: 'force',
+      };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+
+      expect(result.responsive).toBe(false);
+      expect(result.darkMode).toBe('force');
+    });
+
+    it('normalizes chrome strings to ChromeText objects', () => {
+      const result = normalizeSpec(lineSpec) as NormalizedChartSpec;
+
+      // Plain string becomes ChromeText
+      expect(result.chrome.title).toEqual({ text: 'GDP Growth' });
+      // ChromeText with style is preserved
+      expect(result.chrome.subtitle).toEqual({
+        text: 'Over time',
+        style: { fontSize: 16 },
+      });
+      // Undefined fields stay undefined
+      expect(result.chrome.source).toBeUndefined();
+    });
+
+    it('infers encoding types from data when not specified', () => {
+      const warnings: string[] = [];
+      const spec: ChartSpec = {
+        mark: 'point',
+        data: [
+          { x: 10, y: 20 },
+          { x: 30, y: 40 },
+        ],
+        encoding: {
+          // No type specified, should be inferred as quantitative
+          x: { field: 'x', type: 'quantitative' },
+          // biome-ignore lint/suspicious/noExplicitAny: intentionally omitting `type` to test inference
+          y: { field: 'y' } as any,
+        },
+      };
+
+      const result = normalizeSpec(spec, warnings) as NormalizedChartSpec;
+      expect(result.encoding.y?.type).toBe('quantitative');
+      expect(warnings.some((w) => w.includes('Inferred'))).toBe(true);
+    });
+
+    it('infers temporal type from date strings', () => {
+      const warnings: string[] = [];
+      const spec: ChartSpec = {
+        mark: 'line',
+        data: [
+          { date: '2020-01-01', value: 10 },
+          { date: '2021-06-15', value: 20 },
+        ],
+        encoding: {
+          // biome-ignore lint/suspicious/noExplicitAny: intentionally omitting `type` to test inference
+          x: { field: 'date' } as any,
+          y: { field: 'value', type: 'quantitative' },
+        },
+      };
+
+      const result = normalizeSpec(spec, warnings) as NormalizedChartSpec;
+      expect(result.encoding.x?.type).toBe('temporal');
+    });
+
+    it('warns on type mismatch (temporal declared as nominal)', () => {
+      const warnings: string[] = [];
+      const spec: ChartSpec = {
+        mark: 'line',
+        data: [
+          { date: '2020-01-01', value: 10 },
+          { date: '2021-06-15', value: 20 },
+        ],
+        encoding: {
+          x: { field: 'date', type: 'nominal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+      };
+
+      normalizeSpec(spec, warnings);
+      expect(warnings.some((w) => w.includes('looks temporal but was declared as nominal'))).toBe(
+        true,
+      );
+    });
+
+    it('preserves explicit label config', () => {
+      const spec: ChartSpec = {
+        ...lineSpec,
+        labels: { density: 'none', format: ',.0f' },
+      };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      expect(result.labels).toEqual({
+        density: 'none',
+        format: ',.0f',
+        prefix: '',
+        offsets: undefined,
+      });
+    });
+
+    it('fills partial label config with defaults', () => {
+      const spec: ChartSpec = {
+        ...lineSpec,
+        labels: { density: 'endpoints' },
+      };
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      expect(result.labels).toEqual({
+        density: 'endpoints',
+        format: '',
+        prefix: '',
+        offsets: undefined,
+      });
+    });
+
+    it('normalizes annotations with default styles', () => {
+      const spec: ChartSpec = {
+        ...lineSpec,
+        annotations: [
+          { type: 'refline', y: 15 },
+          { type: 'text', x: '2020-01-01', y: 10, text: 'Start' },
+          { type: 'range', y1: 10, y2: 20 },
+        ],
+      };
+
+      const result = normalizeSpec(spec) as NormalizedChartSpec;
+      const refline = result.annotations[0] as RefLineAnnotation;
+      expect(refline.style).toBe('dashed');
+      expect(refline.strokeWidth).toBe(1);
+
+      // Normalize must NOT stamp typography onto text annotations. The
+      // annotation layer owns fontSize (DEFAULT_ANNOTATION_FONT_SIZE) and
+      // fontWeight (the lede rule, which promotes a subtitle-bearing primary
+      // line to bold only when the author left the weight unset). Defaulting
+      // them here makes `fontWeight` always defined, so the lede rule can
+      // never fire and the size default can never apply.
+      const text = result.annotations[1] as TextAnnotation;
+      expect(text.fontSize).toBeUndefined();
+      expect(text.fontWeight).toBeUndefined();
+      expect(text.opacity).toBe(1);
+
+      const range = result.annotations[2] as RangeAnnotation;
+      expect(range.opacity).toBe(0.1);
+    });
+
+    it('preserves author-set annotation typography through normalization', () => {
+      const spec: ChartSpec = {
+        ...lineSpec,
+        annotations: [
+          { type: 'text', x: '2020-01-01', y: 10, text: 'Start', fontSize: 18, fontWeight: 300 },
+        ],
+      };
+
+      const text = (normalizeSpec(spec) as NormalizedChartSpec).annotations[0] as TextAnnotation;
+      expect(text.fontSize).toBe(18);
+      expect(text.fontWeight).toBe(300);
+    });
+  });
+
+  describe('table spec normalization', () => {
+    it('fills default values', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+      };
+
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.search).toBe(false);
+      expect(result.pagination).toBe(false);
+      expect(result.stickyFirstColumn).toBe(false);
+      expect(result.compact).toBe(false);
+      expect(result.responsive).toBe(true);
+      expect(result.darkMode).toBe('off');
+    });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: TableSpec = {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedTableSpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('graph spec normalization', () => {
+    it('fills default values', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+      };
+
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.encoding).toEqual({});
+      expect(result.layout).toEqual({ type: 'force', chargeStrength: -300, linkDistance: 30 });
+      expect(result.annotations).toEqual([]);
+      expect(result.darkMode).toBe('off');
+    });
+
+    it('watermark defaults to true when not specified', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: GraphSpec = {
+        type: 'graph',
+        nodes: [{ id: 'a' }, { id: 'b' }],
+        edges: [{ source: 'a', target: 'b' }],
+        watermark: false,
+      };
+      const result = normalizeSpec(spec) as NormalizedGraphSpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('sankey spec normalization', () => {
+    const baseSankeySpec: SankeySpec = {
+      type: 'sankey',
+      data: [{ source: 'A', target: 'B', value: 10 }],
+      encoding: {
+        source: { field: 'source' },
+        target: { field: 'target' },
+        value: { field: 'value' },
+      },
+    };
+
+    it('watermark defaults to true when not specified', () => {
+      const result = normalizeSpec(baseSankeySpec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('watermark respects explicit false', () => {
+      const spec: SankeySpec = { ...baseSankeySpec, watermark: false };
+      const result = normalizeSpec(spec) as NormalizedSankeySpec;
+      expect(result.watermark).toBe(false);
+    });
+  });
+
+  describe('layer spec normalization', () => {
+    const baseLeaf: ChartSpec = {
+      mark: 'line',
+      data: [{ x: 1, y: 2 }],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+      },
+    };
+
+    it('watermark defaults to true for layer leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf] };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(true);
+    });
+
+    it('layer-level watermark: false propagates to leaves', () => {
+      const layerSpec: LayerSpec = { layer: [baseLeaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      expect(result.watermark).toBe(false);
+    });
+
+    it('leaf-level watermark overrides layer-level', () => {
+      const leaf: ChartSpec = { ...baseLeaf, watermark: true };
+      const layerSpec: LayerSpec = { layer: [leaf], watermark: false };
+      const result = normalizeSpec(layerSpec) as NormalizedChartSpec;
+      // Leaf explicitly sets true, which should be preserved
+      expect(result.watermark).toBe(true);
+    });
+  });
+
+  describe('map spec normalization', () => {
+    const mapSpec: MapSpec = {
+      type: 'map',
+      geo: {
+        features: {
+          type: 'Topology',
+          objects: { x: { type: 'GeometryCollection', geometries: [] } },
+          arcs: [],
+        },
+      },
+      data: [],
+      encoding: {
+        key: { field: 'id', type: 'nominal' },
+        color: { field: 'value', type: 'quantitative' },
+      },
+    };
+
+    it('adds focus: null when not specified', () => {
+      const result = normalizeSpec(mapSpec) as NormalizedMapSpec;
+      expect(result.geo.focus).toBeNull();
+    });
+
+    it('preserves explicit focus value', () => {
+      const specWithFocus: MapSpec = {
+        ...mapSpec,
+        geo: { ...mapSpec.geo, focus: '36' },
+      };
+      const result = normalizeSpec(specWithFocus) as NormalizedMapSpec;
+      expect(result.geo.focus).toBe('36');
+    });
+
+    it('preserves focus: null (explicit clear)', () => {
+      const specWithNull: MapSpec = {
+        ...mapSpec,
+        geo: { ...mapSpec.geo, focus: null },
+      };
+      const result = normalizeSpec(specWithNull) as NormalizedMapSpec;
+      expect(result.geo.focus).toBeNull();
+    });
+  });
+});

package/src/compiler/__tests__/sparkline-defaults.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for sparkline default resolution.
+ *
+ * Focus: the trend signal must be honest about noisy series and short
+ * series. Naive `last - first` would mislabel `[100, 50, 200, 60, 101]`
+ * as up; a regression slope with deadband correctly reads it as neutral.
+ */
+
+import type { MarkDef, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import {
+  buildSparklineAreaGradient,
+  computeTrend,
+  computeTrendFromData,
+  hasExplicitColor,
+  trendColor,
+} from '../sparkline-defaults';
+
+const baseTheme = {
+  colors: {
+    categorical: ['#1b7fa3', '#aaa'],
+    positive: '#16a34a',
+    negative: '#dc2626',
+  },
+} as unknown as ResolvedTheme;
+
+describe('computeTrend', () => {
+  it('classifies clear up-trend as "up"', () => {
+    expect(computeTrend([1, 2, 3, 4, 5])).toBe('up');
+  });
+
+  it('classifies clear down-trend as "down"', () => {
+    expect(computeTrend([5, 4, 3, 2, 1])).toBe('down');
+  });
+
+  it('classifies flat series as "neutral"', () => {
+    expect(computeTrend([10, 10, 10, 10])).toBe('neutral');
+  });
+
+  it('classifies noisy non-monotonic series with no meaningful net trend as "neutral"', () => {
+    // Symmetric oscillation around the mean — the regression slope works
+    // out to (almost) zero. Naive `last - first` heuristics would classify
+    // this incorrectly; the regression sees no net direction.
+    // Palindromic series — mirrors around the midpoint, so the regression
+    // slope is mathematically zero regardless of the noise amplitude.
+    expect(computeTrend([100, 105, 95, 102, 95, 105, 100])).toBe('neutral');
+  });
+
+  it('classifies a real trend with noise as the net direction', () => {
+    // ~10% net rise over 20 steps with realistic chop — should still read up.
+    const series = [
+      100, 102, 99, 103, 101, 104, 103, 106, 104, 107, 105, 108, 107, 109, 108, 110, 109, 111, 110,
+      112,
+    ];
+    expect(computeTrend(series)).toBe('up');
+  });
+
+  it('returns "neutral" for empty series', () => {
+    expect(computeTrend([])).toBe('neutral');
+  });
+
+  it('returns "neutral" for single-point series', () => {
+    expect(computeTrend([42])).toBe('neutral');
+  });
+
+  it('returns "neutral" when all values are non-finite', () => {
+    expect(computeTrend([NaN, NaN, Infinity])).toBe('neutral');
+  });
+
+  it('skips non-finite values and classifies remaining', () => {
+    expect(computeTrend([NaN, 1, 2, 3, 4, NaN])).toBe('up');
+  });
+
+  it('treats very small relative slope as "neutral" (deadband)', () => {
+    // Slope is real but tiny relative to the mean.
+    expect(computeTrend([1000, 1000.5, 1001, 1001.2])).toBe('neutral');
+  });
+});
+
+describe('computeTrendFromData', () => {
+  it('reads y values from data rows', () => {
+    const data = [
+      { date: 'a', value: 1 },
+      { date: 'b', value: 2 },
+      { date: 'c', value: 3 },
+    ];
+    expect(computeTrendFromData(data, 'value')).toBe('up');
+  });
+
+  it('returns "neutral" when yField is missing', () => {
+    expect(computeTrendFromData([{ a: 1 }, { a: 2 }], undefined)).toBe('neutral');
+  });
+
+  it('coerces string numbers and skips non-numeric values', () => {
+    const data = [{ v: '5' }, { v: 'not a number' }, { v: '4' }, { v: '3' }];
+    expect(computeTrendFromData(data, 'v')).toBe('down');
+  });
+});
+
+describe('trendColor', () => {
+  it('returns positive for up', () => {
+    expect(trendColor('up', baseTheme)).toBe('#16a34a');
+  });
+  it('returns negative for down', () => {
+    expect(trendColor('down', baseTheme)).toBe('#dc2626');
+  });
+  it('returns palette[0] for neutral', () => {
+    expect(trendColor('neutral', baseTheme)).toBe('#1b7fa3');
+  });
+});
+
+describe('hasExplicitColor', () => {
+  it('returns both false when markDef has no fill/stroke and no color encoding', () => {
+    expect(hasExplicitColor({ type: 'line' }, false)).toEqual({ fill: false, stroke: false });
+  });
+  it('returns fill=true when markDef.fill is set, leaves stroke false', () => {
+    expect(hasExplicitColor({ type: 'line', fill: '#ff00ff' } as MarkDef, false)).toEqual({
+      fill: true,
+      stroke: false,
+    });
+  });
+  it('returns stroke=true when markDef.stroke is set, leaves fill false', () => {
+    expect(hasExplicitColor({ type: 'line', stroke: '#ff00ff' } as MarkDef, false)).toEqual({
+      fill: false,
+      stroke: true,
+    });
+  });
+  it('returns both true when both markDef.fill and markDef.stroke are set', () => {
+    expect(
+      hasExplicitColor({ type: 'line', fill: '#ff00ff', stroke: '#00ffff' } as MarkDef, false),
+    ).toEqual({ fill: true, stroke: true });
+  });
+  it('returns both true when encoding.color is present (color scale drives both)', () => {
+    expect(hasExplicitColor({ type: 'line' }, true)).toEqual({ fill: true, stroke: true });
+  });
+});
+
+describe('buildSparklineAreaGradient', () => {
+  it('builds a top-to-bottom gradient with 0.35 -> 0 opacity in the trend color', () => {
+    const grad = buildSparklineAreaGradient('#16a34a');
+    expect(grad).toEqual({
+      gradient: 'linear',
+      x1: 0,
+      y1: 0,
+      x2: 0,
+      y2: 1,
+      stops: [
+        { offset: 0, color: '#16a34a', opacity: 0.35 },
+        { offset: 1, color: '#16a34a', opacity: 0 },
+      ],
+    });
+  });
+});

package/src/compiler/__tests__/validate-did-you-mean.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Levenshtein "did you mean" repair hints for misspelled field references.
+ *
+ * When a spec references a field that is not a column in the provided data,
+ * validation suggests the nearest actual column (by edit distance) so an LLM
+ * or author can self-correct a typo in one step. Short/unrelated names must
+ * NOT produce a spurious suggestion.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { validateSpec } from '../validate';
+
+const data = [
+  { region: 'West', revenue: 100, quarter: '2024-Q1' },
+  { region: 'East', revenue: 200, quarter: '2024-Q2' },
+];
+
+/** Pull the suggestion for the field-missing error on the given path. */
+function suggestionFor(result: ReturnType<typeof validateSpec>, path: string): string {
+  const error = result.errors.find((e) => e.path === path);
+  return error?.suggestion ?? '';
+}
+
+describe('did-you-mean field suggestions', () => {
+  it('suggests the nearest column for a one-edit typo in an encoding field', () => {
+    const result = validateSpec({
+      mark: 'bar',
+      data,
+      encoding: {
+        x: { field: 'region', type: 'nominal' },
+        y: { field: 'reveune', type: 'quantitative' }, // typo of "revenue"
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.y.field');
+    expect(suggestion).toContain('Did you mean "revenue"?');
+    // The full available-column list is still present alongside the hint.
+    expect(suggestion).toContain('revenue');
+    expect(suggestion).toContain('region');
+  });
+
+  it('does not invent a suggestion for a field with no close match', () => {
+    const result = validateSpec({
+      mark: 'bar',
+      data,
+      encoding: {
+        x: { field: 'region', type: 'nominal' },
+        y: { field: 'xyzqwerty', type: 'quantitative' },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.y.field');
+    expect(suggestion).not.toContain('Did you mean');
+    // Still lists the real columns so the author can pick the right one.
+    expect(suggestion).toContain('revenue');
+  });
+
+  it('suggests the nearest column for a misspelled table column key', () => {
+    const result = validateSpec({
+      type: 'table',
+      data,
+      columns: [{ key: 'quater' }], // typo of "quarter"
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'columns[0].key');
+    expect(suggestion).toContain('Did you mean "quarter"?');
+  });
+
+  it('does not match on a short unrelated field where the edit distance exceeds the threshold', () => {
+    const shortData = [
+      { a: 1, b: 2 },
+      { a: 3, b: 4 },
+    ];
+    const result = validateSpec({
+      mark: 'bar',
+      data: shortData,
+      encoding: {
+        x: { field: 'zzz', type: 'nominal' },
+        y: { field: 'a', type: 'quantitative' },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.x.field');
+    expect(suggestion).not.toContain('Did you mean');
+  });
+});