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

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,146 @@ 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();
+    });
+  });
+
+  describe('row/column facet validation', () => {
+    it('validates row channel field and type', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          row: { field: 'nonexistent', type: 'nominal' },
+        },
+      });
+      expect(result.errors.some((e) => e.path === 'encoding.row.field')).toBe(true);
+    });
+
+    it('rejects row with invalid type', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          row: { field: 'country', type: 'quantitative' as 'nominal' },
+        },
+      });
+      expect(result.errors.some((e) => e.path === 'encoding.row.type')).toBe(true);
+    });
+
+    it('rejects row + facet together', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          row: { field: 'country', type: 'nominal' },
+          facet: { field: 'country', type: 'nominal' },
+        },
+      });
+      expect(result.errors.some((e) => e.message.includes('encoding.row and encoding.facet'))).toBe(
+        true,
+      );
+    });
+
+    it('rejects row + column together', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          row: { field: 'country', type: 'nominal' },
+          column: { field: 'date', type: 'ordinal' },
+        },
+      });
+      expect(
+        result.errors.some((e) => e.message.includes('encoding.row and encoding.column')),
+      ).toBe(true);
+    });
+
+    it('accepts valid row channel', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          row: { field: 'country', type: 'nominal' },
+        },
+      });
+      expect(result.errors.filter((e) => e.path?.startsWith('encoding.row'))).toHaveLength(0);
+    });
+
+    it('rejects column + facet together', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'country', type: 'nominal' },
+          column: { field: 'country', type: 'nominal' },
+          facet: { field: 'country', type: 'nominal' },
+        },
+      });
+      expect(
+        result.errors.some((e) => e.message.includes('encoding.column and encoding.facet')),
+      ).toBe(true);
+    });
+
+    it('accepts valid column channel', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: validLineData,
+        encoding: {
+          x: { field: 'country', type: 'nominal' },
+          y: { field: 'value', type: 'quantitative' },
+          column: { field: 'country', type: 'nominal' },
+        },
+      });
+      expect(result.errors.filter((e) => e.path?.startsWith('encoding.column'))).toHaveLength(0);
+    });
+  });
 });

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;
+}

package/src/compiler/keys.ts

@@ -28,22 +28,23 @@ export function serializeKeyValue(v: unknown): string {
  *
  * Only keys that appear more than once get suffixed. Unique keys pass
  * through unchanged so keys remain human-readable when possible.
- * Uses SOH (\x01) as separator to avoid collisions with real data values.
+ * Uses U+2E31 (word separator middle dot) as separator - XML-safe and
+ * unlikely to appear in real data values.
  */
+const KEY_DEDUP_SEP = '⸱';
+
 export function dedupeKeys(keys: string[]): string[] {
-  // Count occurrences
   const counts = new Map<string, number>();
   for (const k of keys) {
     counts.set(k, (counts.get(k) ?? 0) + 1);
   }
 
-  // Assign suffixes only to duplicates
   const seen = new Map<string, number>();
   const result: string[] = [];
   for (const k of keys) {
     if (counts.get(k)! > 1) {
       const idx = seen.get(k) ?? 0;
-      result.push(`${k}\x01${idx}`);
+      result.push(`${k}${KEY_DEDUP_SEP}${idx}`);
       seen.set(k, idx + 1);
     } else {
       result.push(k);