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

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

@@ -2,6 +2,7 @@ import type {
   ChartSpec,
   GraphSpec,
   LayerSpec,
+  MapSpec,
   RangeAnnotation,
   RefLineAnnotation,
   SankeySpec,
@@ -9,6 +10,7 @@ import type {
   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';
@@ -195,12 +197,33 @@ describe('normalizeSpec', () => {
       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).toBe(12);
+      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', () => {
@@ -332,4 +355,45 @@ describe('normalizeSpec', () => {
       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__/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');
+  });
+});

package/src/compiler/__tests__/validate-near-miss.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Near-miss validation messages for VL idioms that are unsupported by
+ * decision. Each rejection must point the author at the openchart
+ * equivalent instead of failing with a generic type error.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { validateSpec } from '../validate';
+
+const encoding = {
+  x: { field: 'cat', type: 'nominal' },
+  y: { field: 'value', type: 'quantitative' },
+};
+const data = [
+  { cat: 'A', value: 10 },
+  { cat: 'B', value: 20 },
+];
+
+describe('near-miss validation messages', () => {
+  it('rejects data.url with a pointer to inline data', () => {
+    const result = validateSpec({ mark: 'bar', data: { url: '/data.json' }, encoding });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'data.url');
+    expect(error?.message).toContain('does not fetch remote data');
+    expect(error?.suggestion).toContain('inline');
+  });
+
+  it('rejects the string form of calculate with the structured equivalent', () => {
+    const result = validateSpec({
+      mark: 'bar',
+      data,
+      transform: [{ calculate: 'datum.a / datum.b', as: 'ratio' }],
+      encoding,
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'transform[0].calculate');
+    expect(error?.message).toContain('structured expression object');
+    expect(error?.suggestion).toContain('calculate: { op:');
+  });
+
+  it('rejects hconcat/vconcat with the side-by-side containers suggestion', () => {
+    for (const key of ['hconcat', 'vconcat']) {
+      const result = validateSpec({ [key]: [] });
+      expect(result.valid).toBe(false);
+      const error = result.errors.find((e) => e.path === key);
+      expect(error?.message).toContain(`"${key}" composition is not supported`);
+      expect(error?.suggestion).toContain('facet');
+    }
+  });
+
+  it('rejects the top-level facet operator with the facet channel suggestion', () => {
+    const result = validateSpec({
+      facet: { field: 'cat', type: 'nominal' },
+      spec: { mark: 'bar', encoding },
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'facet');
+    expect(error?.message).toContain('"facet" operator is not supported');
+    expect(error?.suggestion).toContain('encoding.facet');
+  });
+
+  it('rejects unknown scheme names with the supported list', () => {
+    const result = validateSpec({
+      mark: 'bar',
+      data,
+      encoding: {
+        ...encoding,
+        color: { field: 'value', type: 'quantitative', scale: { scheme: 'viridis' } },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'encoding.color.scale.scheme');
+    expect(error?.message).toContain('"viridis" is not a supported scheme name');
+    expect(error?.suggestion).toContain('blues');
+    expect(error?.suggestion).toContain('scale.range');
+  });
+
+  it('accepts known scheme names (resolved by sugar before validation on the compile path)', () => {
+    const result = validateSpec({
+      mark: 'bar',
+      data,
+      encoding: {
+        ...encoding,
+        color: { field: 'value', type: 'quantitative', scale: { scheme: 'blues' } },
+      },
+    });
+    expect(result.errors.filter((e) => e.path === 'encoding.color.scale.scheme')).toHaveLength(0);
+  });
+});

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

@@ -308,6 +308,122 @@ describe('validateSpec', () => {
     });
   });
 
+  describe('range marks', () => {
+    const rangeData = [
+      { country: 'Japan', y2000: 81.1, y2024: 87.9 },
+      { country: 'USA', y2000: 79.5, y2024: 81.3 },
+    ];
+
+    it('accepts a valid horizontal range spec (x + x2, nominal y)', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: rangeData,
+        encoding: {
+          y: { field: 'country', type: 'nominal' },
+          x: { field: 'y2000', type: 'quantitative' },
+          x2: { field: 'y2024' },
+        },
+      });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('accepts a valid vertical range spec (y + y2, nominal x)', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: [{ month: 'Jan', lo: 27, hi: 39 }],
+        encoding: {
+          x: { field: 'month', type: 'nominal' },
+          y: { field: 'lo', type: 'quantitative' },
+          y2: { field: 'hi' },
+        },
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('rejects a horizontal range spec without x2, naming encoding.x2', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: rangeData,
+        encoding: {
+          y: { field: 'country', type: 'nominal' },
+          x: { field: 'y2000', type: 'quantitative' },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.path === 'encoding.x2');
+      expect(err).toBeDefined();
+      expect(err!.code).toBe('MISSING_FIELD');
+      expect(err!.message).toContain('encoding.x2');
+      expect(err!.suggestion).toContain('x2: { field:');
+    });
+
+    it('rejects a vertical range spec without y2, naming encoding.y2', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: [{ month: 'Jan', lo: 27, hi: 39 }],
+        encoding: {
+          x: { field: 'month', type: 'nominal' },
+          y: { field: 'lo', type: 'quantitative' },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.path === 'encoding.y2');
+      expect(err).toBeDefined();
+      expect(err!.code).toBe('MISSING_FIELD');
+      expect(err!.message).toContain('encoding.y2');
+    });
+
+    it('rejects y2 on a horizontal range spec', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: rangeData,
+        encoding: {
+          y: { field: 'country', type: 'nominal' },
+          x: { field: 'y2000', type: 'quantitative' },
+          x2: { field: 'y2024' },
+          y2: { field: 'y2024' },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.path === 'encoding.y2');
+      expect(err).toBeDefined();
+      expect(err!.code).toBe('INVALID_VALUE');
+    });
+
+    it('rejects a range spec without any categorical axis', () => {
+      const result = validateSpec({
+        mark: 'range',
+        data: rangeData,
+        encoding: {
+          y: { field: 'y2000', type: 'quantitative' },
+          x: { field: 'y2024', type: 'quantitative' },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.code === 'ENCODING_MISMATCH');
+      expect(err).toBeDefined();
+      expect(err!.message).toContain('category axis');
+    });
+
+    it('rejects an unknown mark.style value', () => {
+      const result = validateSpec({
+        mark: { type: 'range', style: 'ribbon' },
+        data: rangeData,
+        encoding: {
+          y: { field: 'country', type: 'nominal' },
+          x: { field: 'y2000', type: 'quantitative' },
+          x2: { field: 'y2024' },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.path === 'mark.style');
+      expect(err).toBeDefined();
+      expect(err!.code).toBe('INVALID_VALUE');
+      expect(err!.message).toContain('dumbbell, arrow, bar');
+    });
+  });
+
   describe('table specs', () => {
     it('accepts a valid table spec', () => {
       const result = validateSpec({
@@ -470,4 +586,44 @@ describe('validateSpec', () => {
       expect(fieldError!.suggestion).toContain('gamma');
     });
   });
+
+  describe('transform-created fields', () => {
+    it('accepts encoding fields produced by a chained bin + aggregate (histogram)', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: [{ hours: 3.1 }, { hours: 3.4 }, { hours: 4.0 }],
+        transform: [
+          { bin: { step: 0.5 }, field: 'hours', as: 'binStart' },
+          { aggregate: [{ op: 'count', field: 'hours', as: 'finishers' }], groupby: ['binStart'] },
+        ],
+        encoding: {
+          x: { field: 'binStart', type: 'ordinal' },
+          y: { field: 'finishers', type: 'quantitative' },
+        },
+      });
+
+      expect(result.valid).toBe(true);
+      expect(result.errors.find((e) => e.code === 'DATA_FIELD_MISSING')).toBeUndefined();
+    });
+
+    it('accepts an encoding field produced by a window transform', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: [
+          { day: '1', value: 10 },
+          { day: '2', value: 20 },
+        ],
+        transform: [
+          { window: [{ op: 'cumsum', field: 'value', as: 'running' }], sort: [{ field: 'day' }] },
+        ],
+        encoding: {
+          x: { field: 'day', type: 'ordinal' },
+          y: { field: 'running', type: 'quantitative' },
+        },
+      });
+
+      expect(result.valid).toBe(true);
+      expect(result.errors.find((e) => e.code === 'DATA_FIELD_MISSING')).toBeUndefined();
+    });
+  });
 });

package/src/compiler/__tests__/vl-parity.test.ts

@@ -0,0 +1,68 @@
+/**
+ * VL-idiom guessability suite.
+ *
+ * Each fixture in fixtures/vl-parity pairs a Vega-Lite-style spec ("vl") with
+ * the canonical openchart spec ("canonical") for one accepted idiom, and
+ * asserts they compile to deep-equal ChartLayouts. Layered fixtures
+ * (layered: true) run through compileLayer to prove the same sugar works on
+ * LayerSpec children.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { CompileOptions, LayerSpec } from '@opendata-ai/openchart-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { compileChart, compileLayer } from '../../compile';
+
+interface ParityFixture {
+  file: string;
+  layered?: boolean;
+  options: CompileOptions;
+  /** Per-side option overrides (e.g. the width/height fixture compiles the VL side in a larger container). */
+  vlOptions?: CompileOptions;
+  canonicalOptions?: CompileOptions;
+  vl: Record<string, unknown>;
+  canonical: Record<string, unknown>;
+}
+
+const fixturesDir = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'vl-parity');
+const fixtures: ParityFixture[] = readdirSync(fixturesDir)
+  .filter((file) => file.endsWith('.json'))
+  .sort()
+  .map((file) => ({
+    file,
+    ...(JSON.parse(readFileSync(join(fixturesDir, file), 'utf8')) as Omit<ParityFixture, 'file'>),
+  }));
+
+let warnSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  warnSpy.mockRestore();
+});
+
+describe('VL-idiom parity fixtures', () => {
+  it('loads at least one flat and one layered fixture', () => {
+    expect(fixtures.some((f) => !f.layered)).toBe(true);
+    expect(fixtures.some((f) => f.layered)).toBe(true);
+  });
+
+  for (const fixture of fixtures) {
+    it(`${fixture.file}: VL form compiles to the same layout as the canonical form`, () => {
+      const vlLayout = fixture.layered
+        ? compileLayer(fixture.vl as unknown as LayerSpec, fixture.vlOptions ?? fixture.options)
+        : compileChart(fixture.vl, fixture.vlOptions ?? fixture.options);
+      const canonicalLayout = fixture.layered
+        ? compileLayer(
+            fixture.canonical as unknown as LayerSpec,
+            fixture.canonicalOptions ?? fixture.options,
+          )
+        : compileChart(fixture.canonical, fixture.canonicalOptions ?? fixture.options);
+      expect(vlLayout).toEqual(canonicalLayout);
+    });
+  }
+});

package/src/compiler/a11y-warnings.ts

@@ -0,0 +1,110 @@
+/**
+ * Development-time WCAG contrast diagnostics.
+ *
+ * Checks the resolved series colors and theme text tokens against WCAG 2.1
+ * thresholds and returns advisory warning strings:
+ *
+ * - 1.4.11 (non-text contrast, 3:1): adjacent stacked/grouped series pairs
+ *   and each series color against the chart background.
+ * - 1.4.3 (text contrast, 4.5:1): theme text tokens against the background.
+ *
+ * Purely advisory: this module never throws and produces nothing unless the
+ * host opts in via `compileChart(spec, { dev: true })`. The gate is a compile
+ * option, NOT an environment sniff, because the engine is isomorphic and
+ * `process.env` checks would leak a Node assumption into browser bundles.
+ */
+
+import type { MarkType, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { contrastRatio, findAccessibleColor, isOpaqueColor } from '@opendata-ai/openchart-core';
+import type { ScaleOrdinal } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/** WCAG 1.4.11 minimum for graphical objects against adjacent colors. */
+const GRAPHIC_MIN = 3;
+/** WCAG 1.4.3 minimum for normal-size text. */
+const TEXT_MIN = 4.5;
+
+/** Mark types whose series render as adjacent filled regions when stacked/grouped. */
+const ADJACENT_FILL_MARKS: ReadonlySet<MarkType> = new Set(['bar', 'area', 'arc', 'waffle']);
+
+const fmt = (ratio: number): string => `${ratio.toFixed(2)}:1`;
+
+/**
+ * Collect WCAG contrast warnings for a compiled chart.
+ *
+ * @param scales - Resolved scales (series colors come from the color scale).
+ * @param markType - Resolved mark type (adjacency only applies to filled marks).
+ * @param theme - Resolved theme (background and text tokens).
+ * @returns Advisory warning strings; empty when everything passes.
+ */
+export function collectContrastWarnings(
+  scales: ResolvedScales,
+  markType: MarkType,
+  theme: ResolvedTheme,
+): string[] {
+  const warnings: string[] = [];
+
+  // The default background is 'transparent' (the host page shows through),
+  // which makes background-relative ratios meaningless at compile time.
+  // Adjacent-series checks below don't need the background and always run.
+  const bg = theme.colors.background;
+  const bgIsCheckable = isOpaqueColor(bg);
+
+  // Resolved per-series colors in domain (render) order. Sequential color
+  // scales encode magnitude, not series identity; adjacency checks there
+  // would flag every neighboring ramp stop, so only categorical scales apply.
+  const series: Array<{ key: string; color: string }> = [];
+  if (scales.color && scales.color.type !== 'sequential') {
+    const ordinal = scales.color.scale as unknown as ScaleOrdinal<string, string>;
+    for (const key of ordinal.domain()) {
+      series.push({ key, color: ordinal(key) });
+    }
+  }
+
+  // Adjacent series pairs (stacked segments / grouped neighbors render in
+  // domain order, so consecutive series sit next to each other).
+  if (ADJACENT_FILL_MARKS.has(markType)) {
+    for (let i = 0; i < series.length - 1; i++) {
+      const a = series[i];
+      const b = series[i + 1];
+      const ratio = contrastRatio(a.color, b.color);
+      if (ratio < GRAPHIC_MIN) {
+        const suggestion = findAccessibleColor(b.color, a.color, GRAPHIC_MIN);
+        warnings.push(
+          `[openchart a11y] Adjacent series "${a.key}" (${a.color}) and "${b.key}" (${b.color}) have ${fmt(ratio)} contrast, below the 3:1 WCAG 1.4.11 minimum for graphical objects. Nearest passing color for "${b.key}": ${suggestion}.`,
+        );
+      }
+    }
+  }
+
+  if (bgIsCheckable) {
+    // Each series against the chart background.
+    for (const s of series) {
+      const ratio = contrastRatio(s.color, bg);
+      if (ratio < GRAPHIC_MIN) {
+        const suggestion = findAccessibleColor(s.color, bg, GRAPHIC_MIN);
+        warnings.push(
+          `[openchart a11y] Series "${s.key}" (${s.color}) has ${fmt(ratio)} contrast against the background (${bg}), below the 3:1 WCAG 1.4.11 minimum. Nearest passing color: ${suggestion}.`,
+        );
+      }
+    }
+
+    // Text tokens at the 4.5:1 body-text threshold. Gridline/axis rules are
+    // exempt: they are decorative per WCAG 1.4.11.
+    const textTokens: Array<{ name: string; color: string }> = [
+      { name: 'theme.colors.text', color: theme.colors.text },
+      { name: 'theme.colors.annotationText', color: theme.colors.annotationText },
+    ];
+    for (const token of textTokens) {
+      const ratio = contrastRatio(token.color, bg);
+      if (ratio < TEXT_MIN) {
+        const suggestion = findAccessibleColor(token.color, bg, TEXT_MIN);
+        warnings.push(
+          `[openchart a11y] ${token.name} (${token.color}) has ${fmt(ratio)} contrast against the background (${bg}), below the 4.5:1 WCAG 1.4.3 minimum for text. Nearest passing color: ${suggestion}.`,
+        );
+      }
+    }
+  }
+
+  return warnings;
+}