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

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

@@ -62,11 +62,11 @@ describe('dedupeKeys', () => {
   });
 
   it('suffixes duplicates with occurrence index', () => {
-    expect(dedupeKeys(['a', 'a', 'a'])).toEqual(['a\x010', 'a\x011', 'a\x012']);
+    expect(dedupeKeys(['a', 'a', 'a'])).toEqual(['a⸱0', 'a⸱1', 'a⸱2']);
   });
 
   it('only suffixes keys that appear more than once', () => {
-    expect(dedupeKeys(['a', 'b', 'a'])).toEqual(['a\x010', 'b', 'a\x011']);
+    expect(dedupeKeys(['a', 'b', 'a'])).toEqual(['a⸱0', 'b', 'a⸱1']);
   });
 
   it('handles empty array', () => {
@@ -78,12 +78,6 @@ describe('dedupeKeys', () => {
   });
 
   it('handles multiple duplicate groups', () => {
-    expect(dedupeKeys(['x', 'y', 'x', 'y', 'z'])).toEqual([
-      'x\x010',
-      'y\x010',
-      'x\x011',
-      'y\x011',
-      'z',
-    ]);
+    expect(dedupeKeys(['x', 'y', 'x', 'y', 'z'])).toEqual(['x⸱0', 'y⸱0', 'x⸱1', 'y⸱1', 'z']);
   });
 });

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,170 @@
+/**
+ * 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('suggests the nearest column for a misspelled sankey encoding field', () => {
+    const result = validateSpec({
+      type: 'sankey',
+      data: [{ source: 'A', target: 'B', value: 10 }],
+      encoding: {
+        source: { field: 'sorce', type: 'nominal' }, // typo of "source"
+        target: { field: 'target', type: 'nominal' },
+        value: { field: 'value', type: 'quantitative' },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.source.field');
+    expect(suggestion).toContain('Did you mean "source"?');
+    expect(suggestion).toContain('target');
+  });
+
+  it('suggests the nearest column for a misspelled tilemap encoding field', () => {
+    const result = validateSpec({
+      type: 'tilemap',
+      data: [{ state: 'CA', value: 12000 }],
+      encoding: {
+        state: { field: 'state', type: 'nominal' },
+        value: { field: 'vlaue', type: 'quantitative' }, // typo of "value"
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.value.field');
+    expect(suggestion).toContain('Did you mean "value"?');
+  });
+
+  it('suggests the nearest column for a misspelled barlist encoding field', () => {
+    const result = validateSpec({
+      type: 'barlist',
+      data: [{ label: 'A', value: 42 }],
+      encoding: {
+        label: { field: 'lable', type: 'nominal' }, // typo of "label"
+        value: { field: 'value', type: 'quantitative' },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.label.field');
+    expect(suggestion).toContain('Did you mean "label"?');
+  });
+
+  it('suggests the nearest column for a misspelled optional barlist channel field', () => {
+    const result = validateSpec({
+      type: 'barlist',
+      data: [{ label: 'A', value: 42, group: 'x' }],
+      encoding: {
+        label: { field: 'label', type: 'nominal' },
+        value: { field: 'value', type: 'quantitative' },
+        color: { field: 'gruop', type: 'nominal' }, // typo of "group"
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.color.field');
+    expect(suggestion).toContain('Did you mean "group"?');
+  });
+
+  it('suggests the nearest node field for a misspelled graph encoding field', () => {
+    const result = validateSpec({
+      type: 'graph',
+      nodes: [{ id: 'a', category: 'x' }],
+      edges: [],
+      encoding: {
+        nodeColor: { field: 'catgory', type: 'nominal' }, // typo of "category"
+      },
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'encoding.nodeColor.field');
+    expect(suggestion).toContain('Did you mean "category"?');
+  });
+
+  it('suggests the nearest node id for a misspelled graph edge endpoint', () => {
+    const result = validateSpec({
+      type: 'graph',
+      nodes: [{ id: 'alpha' }, { id: 'beta' }],
+      edges: [{ source: 'alpha', target: 'betta' }], // typo of "beta"
+    });
+    expect(result.valid).toBe(false);
+    const suggestion = suggestionFor(result, 'edges[0].target');
+    expect(suggestion).toContain('Did you mean "beta"?');
+  });
+
+  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,251 @@
+/**
+ * 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);
+  });
+});
+
+describe('scale.scheme on non-chart specs', () => {
+  it('rejects any scheme on a sankey color channel as dead config', () => {
+    // Sankey never reads scale.scheme (node colors cycle theme.colors.categorical),
+    // so even a known name like "blues" must not be silently accepted.
+    for (const scheme of ['viridis', 'blues']) {
+      const result = validateSpec({
+        type: 'sankey',
+        data: [{ source: 'A', target: 'B', value: 10 }],
+        encoding: {
+          source: { field: 'source', type: 'nominal' },
+          target: { field: 'target', type: 'nominal' },
+          value: { field: 'value', type: 'quantitative' },
+          color: { field: 'source', type: 'nominal', scale: { scheme } },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const error = result.errors.find((e) => e.path === 'encoding.color.scale.scheme');
+      expect(error?.code).toBe('INVALID_VALUE');
+      expect(error?.message).toContain('has no effect');
+      expect(error?.suggestion).toContain('theme.colors.categorical');
+    }
+  });
+
+  it('rejects any scheme on a tilemap value channel, pointing at the palette prop', () => {
+    const result = validateSpec({
+      type: 'tilemap',
+      data: [{ state: 'CA', value: 12000 }],
+      encoding: {
+        state: { field: 'state', type: 'nominal' },
+        value: { field: 'value', type: 'quantitative', scale: { scheme: 'viridis' } },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'encoding.value.scale.scheme');
+    expect(error?.code).toBe('INVALID_VALUE');
+    expect(error?.message).toContain('has no effect');
+    expect(error?.suggestion).toContain('palette: "green"');
+  });
+
+  it('rejects any scheme on a barlist color channel as dead config', () => {
+    const result = validateSpec({
+      type: 'barlist',
+      data: [{ label: 'A', value: 42, group: 'x' }],
+      encoding: {
+        label: { field: 'label', type: 'nominal' },
+        value: { field: 'value', type: 'quantitative' },
+        color: { field: 'group', type: 'nominal', scale: { scheme: 'viridis' } },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'encoding.color.scale.scheme');
+    expect(error?.code).toBe('INVALID_VALUE');
+    expect(error?.message).toContain('has no effect');
+  });
+
+  it('rejects any scheme on a graph nodeColor channel as dead config', () => {
+    // Graph never reads scale.scheme (encoding.ts consumes only
+    // scale.range/scale.domain), so even a known name must not pass.
+    for (const scheme of ['viridis', 'blues']) {
+      const result = validateSpec({
+        type: 'graph',
+        nodes: [{ id: 'a', category: 'x' }],
+        edges: [],
+        encoding: {
+          nodeColor: { field: 'category', type: 'nominal', scale: { scheme } },
+        },
+      });
+      expect(result.valid).toBe(false);
+      const error = result.errors.find((e) => e.path === 'encoding.nodeColor.scale.scheme');
+      expect(error?.code).toBe('INVALID_VALUE');
+      expect(error?.message).toContain('has no effect');
+      expect(error?.suggestion).toContain('scale.range');
+    }
+  });
+});
+
+describe('scale.scheme on map specs', () => {
+  // Minimal valid TopoJSON topology with one feature
+  const topo = {
+    type: 'Topology',
+    objects: {
+      things: {
+        type: 'GeometryCollection',
+        geometries: [{ type: 'Polygon', arcs: [[0]], id: '01' }],
+      },
+    },
+    arcs: [
+      [
+        [0, 0],
+        [0, 1],
+        [1, 0],
+        [-1, -1],
+      ],
+    ],
+  };
+
+  it('rejects a scheme the map palette set does not support', () => {
+    const result = validateSpec({
+      type: 'map',
+      geo: { features: topo },
+      data: [{ id: '01', value: 5 }],
+      encoding: {
+        key: { field: 'id' },
+        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?.code).toBe('INVALID_VALUE');
+    expect(error?.message).toContain('"viridis" is not a supported map palette');
+    expect(error?.suggestion).toContain('green');
+  });
+
+  it('accepts a supported sequential palette on a map color channel', () => {
+    const result = validateSpec({
+      type: 'map',
+      geo: { features: topo },
+      data: [{ id: '01', value: 5 }],
+      encoding: {
+        key: { field: 'id' },
+        color: { field: 'value', type: 'quantitative', scale: { scheme: 'green' } },
+      },
+    });
+    expect(result.errors.filter((e) => e.path === 'encoding.color.scale.scheme')).toHaveLength(0);
+  });
+
+  it('rejects any scheme on a categorical map color channel as dead config', () => {
+    const result = validateSpec({
+      type: 'map',
+      geo: { features: topo },
+      data: [{ id: '01', region: 'south' }],
+      encoding: {
+        key: { field: 'id' },
+        color: { field: 'region', type: 'nominal', scale: { scheme: 'green' } },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'encoding.color.scale.scheme');
+    expect(error?.code).toBe('INVALID_VALUE');
+    expect(error?.message).toContain('has no effect');
+    expect(error?.suggestion).toContain('scale.range');
+  });
+
+  it('rejects an unsupported scheme on the points layer color channel', () => {
+    const result = validateSpec({
+      type: 'map',
+      geo: { features: topo },
+      data: [],
+      encoding: { key: { field: 'id' } },
+      points: {
+        data: [{ lat: 30, lon: -97, score: 1 }],
+        latitude: { field: 'lat' },
+        longitude: { field: 'lon' },
+        color: { field: 'score', type: 'quantitative', scale: { scheme: 'magma' } },
+      },
+    });
+    const error = result.errors.find((e) => e.path === 'points.color.scale.scheme');
+    expect(error?.code).toBe('INVALID_VALUE');
+    expect(error?.message).toContain('"magma" is not a supported map palette');
+  });
+});