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

package/src/__tests__/encoding-sugar.test.ts

@@ -0,0 +1,390 @@
+/**
+ * Tests for encoding-level bin, timeUnit, and sort shorthand expansion.
+ *
+ * These test the Vega-Lite-aligned encoding sugar that auto-generates
+ * transforms (bin, timeUnit) and applies sort to categorical scales.
+ */
+
+import type { ScaleBand, ScaleOrdinal, ScalePoint } from 'd3-scale';
+import { describe, expect, it } from 'vitest';
+import { expandEncodingSugar } from '../compile';
+import type { NormalizedChartSpec } from '../compiler/types';
+import { computeScales } from '../layout/scales';
+
+// ---------------------------------------------------------------------------
+// expandEncodingSugar: bin
+// ---------------------------------------------------------------------------
+
+describe('expandEncodingSugar', () => {
+  describe('bin expansion', () => {
+    it('expands encoding.x.bin: true into a BinTransform', () => {
+      const spec = {
+        mark: 'bar',
+        data: [{ val: 10 }, { val: 20 }],
+        encoding: {
+          x: { field: 'val', type: 'quantitative', bin: true },
+          y: { field: 'count', type: 'quantitative' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      // Should generate a bin transform
+      expect(result.transform).toHaveLength(1);
+      expect(result.transform).toEqual([{ bin: true, field: 'val', as: 'bin_val' }]);
+
+      // Encoding field should reference the binned output
+      const encoding = result.encoding as Record<string, { field: string; bin?: unknown }>;
+      expect(encoding.x.field).toBe('bin_val');
+      // bin property should be removed from the encoding channel
+      expect(encoding.x.bin).toBeUndefined();
+    });
+
+    it('expands encoding.y.bin with BinParams', () => {
+      const spec = {
+        mark: 'bar',
+        data: [],
+        encoding: {
+          x: { field: 'cat', type: 'nominal' },
+          y: { field: 'score', type: 'quantitative', bin: { maxbins: 20 } },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      expect(result.transform).toHaveLength(1);
+      expect(result.transform).toEqual([{ bin: { maxbins: 20 }, field: 'score', as: 'bin_score' }]);
+
+      const encoding = result.encoding as Record<string, { field: string }>;
+      expect(encoding.y.field).toBe('bin_score');
+    });
+
+    it('does not expand bin: false', () => {
+      const spec = {
+        mark: 'bar',
+        data: [],
+        encoding: {
+          x: { field: 'val', type: 'quantitative', bin: false },
+          y: { field: 'count', type: 'quantitative' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      // No transform generated, spec returned as-is
+      expect(result.transform).toBeUndefined();
+      expect(result).toBe(spec);
+    });
+
+    it('prepends generated transforms before existing transforms', () => {
+      const spec = {
+        mark: 'bar',
+        data: [],
+        encoding: {
+          x: { field: 'val', type: 'quantitative', bin: true },
+          y: { field: 'count', type: 'quantitative' },
+        },
+        transform: [{ filter: { field: 'active', equal: true } }],
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      expect(result.transform).toHaveLength(2);
+      // Generated bin transform comes first
+      expect((result.transform as Array<Record<string, unknown>>)[0]).toHaveProperty('bin');
+      // User-defined filter comes after
+      expect((result.transform as Array<Record<string, unknown>>)[1]).toHaveProperty('filter');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // expandEncodingSugar: timeUnit
+  // ---------------------------------------------------------------------------
+
+  describe('timeUnit expansion', () => {
+    it('expands encoding.x.timeUnit into a TimeUnitTransform', () => {
+      const spec = {
+        mark: 'line',
+        data: [],
+        encoding: {
+          x: { field: 'date', type: 'temporal', timeUnit: 'yearmonth' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      expect(result.transform).toHaveLength(1);
+      expect(result.transform).toEqual([
+        { timeUnit: 'yearmonth', field: 'date', as: 'yearmonth_date' },
+      ]);
+
+      const encoding = result.encoding as Record<string, { field: string; timeUnit?: unknown }>;
+      expect(encoding.x.field).toBe('yearmonth_date');
+      expect(encoding.x.timeUnit).toBeUndefined();
+    });
+
+    it('expands encoding.y.timeUnit: month', () => {
+      const spec = {
+        mark: 'bar',
+        data: [],
+        encoding: {
+          x: { field: 'cat', type: 'nominal' },
+          y: { field: 'timestamp', type: 'temporal', timeUnit: 'month' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      expect(result.transform).toHaveLength(1);
+      expect(result.transform).toEqual([
+        { timeUnit: 'month', field: 'timestamp', as: 'month_timestamp' },
+      ]);
+
+      const encoding = result.encoding as Record<string, { field: string }>;
+      expect(encoding.y.field).toBe('month_timestamp');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Combined bin + timeUnit
+  // ---------------------------------------------------------------------------
+
+  describe('combined expansions', () => {
+    it('expands both bin on x and timeUnit on y', () => {
+      const spec = {
+        mark: 'point',
+        data: [],
+        encoding: {
+          x: { field: 'amount', type: 'quantitative', bin: true },
+          y: { field: 'created', type: 'temporal', timeUnit: 'year' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+
+      expect(result.transform).toHaveLength(2);
+      expect((result.transform as Array<Record<string, unknown>>)[0]).toEqual({
+        bin: true,
+        field: 'amount',
+        as: 'bin_amount',
+      });
+      expect((result.transform as Array<Record<string, unknown>>)[1]).toEqual({
+        timeUnit: 'year',
+        field: 'created',
+        as: 'year_created',
+      });
+
+      const encoding = result.encoding as Record<string, { field: string }>;
+      expect(encoding.x.field).toBe('bin_amount');
+      expect(encoding.y.field).toBe('year_created');
+    });
+
+    it('returns spec unchanged when no encoding sugar is present', () => {
+      const spec = {
+        mark: 'line',
+        data: [],
+        encoding: {
+          x: { field: 'date', type: 'temporal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+      };
+
+      const result = expandEncodingSugar(spec);
+      expect(result).toBe(spec); // Same reference, no copy needed
+    });
+
+    it('returns spec unchanged when no encoding is present', () => {
+      const spec = { mark: 'line', data: [] };
+      const result = expandEncodingSugar(spec);
+      expect(result).toBe(spec);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Sort on categorical scales
+// ---------------------------------------------------------------------------
+
+describe('categorical sort', () => {
+  const chartArea = { x: 0, y: 0, width: 400, height: 300 };
+
+  const makeBarSpec = (
+    sort: 'ascending' | 'descending' | null | undefined,
+  ): NormalizedChartSpec => ({
+    markType: 'bar',
+    markDef: { type: 'bar' },
+    data: [
+      { category: 'Banana', count: 10 },
+      { category: 'Apple', count: 30 },
+      { category: 'Cherry', count: 20 },
+    ],
+    encoding: {
+      x: { field: 'count', type: 'quantitative' },
+      y: { field: 'category', type: 'nominal', sort },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '', prefix: '' },
+    watermark: true,
+    hiddenSeries: [],
+    seriesStyles: {},
+  });
+
+  it('preserves data order by default (undefined sort)', () => {
+    const spec = makeBarSpec(undefined);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    // Data order: Banana, Apple, Cherry
+    expect(domain).toEqual(['Banana', 'Apple', 'Cherry']);
+  });
+
+  it('sorts domain ascending when sort is "ascending"', () => {
+    const spec = makeBarSpec('ascending');
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    expect(domain).toEqual(['Apple', 'Banana', 'Cherry']);
+  });
+
+  it('sorts domain descending when sort is "descending"', () => {
+    const spec = makeBarSpec('descending');
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    expect(domain).toEqual(['Cherry', 'Banana', 'Apple']);
+  });
+
+  it('preserves data order when sort is null', () => {
+    const spec = makeBarSpec(null);
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    // Data order: Banana, Apple, Cherry
+    expect(domain).toEqual(['Banana', 'Apple', 'Cherry']);
+  });
+
+  it('applies sort to point scales (nominal x on line chart)', () => {
+    const spec: NormalizedChartSpec = {
+      markType: 'line',
+      markDef: { type: 'line' },
+      data: [
+        { name: 'Zara', score: 10 },
+        { name: 'Alice', score: 20 },
+        { name: 'Mike', score: 15 },
+      ],
+      encoding: {
+        x: { field: 'name', type: 'nominal', sort: 'descending' },
+        y: { field: 'score', type: 'quantitative' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'auto', format: '', prefix: '' },
+      watermark: true,
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.x!.scale as ScalePoint<string>).domain();
+    expect(domain).toEqual(['Zara', 'Mike', 'Alice']);
+  });
+
+  it('applies sort to ordinal color scales', () => {
+    const spec: NormalizedChartSpec = {
+      markType: 'line',
+      markDef: { type: 'line' },
+      data: [
+        { date: '2020-01-01', value: 10, group: 'Gamma' },
+        { date: '2020-01-01', value: 20, group: 'Alpha' },
+        { date: '2020-01-01', value: 15, group: 'Beta' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'group', type: 'nominal', sort: 'ascending' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'auto', format: '', prefix: '' },
+      watermark: true,
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.color!.scale as ScaleOrdinal<string, string>).domain();
+    expect(domain).toEqual(['Alpha', 'Beta', 'Gamma']);
+  });
+
+  it('sorts numerically when values are numeric strings', () => {
+    const spec: NormalizedChartSpec = {
+      markType: 'bar',
+      markDef: { type: 'bar' },
+      data: [
+        { category: '10', count: 1 },
+        { category: '2', count: 2 },
+        { category: '1', count: 3 },
+      ],
+      encoding: {
+        x: { field: 'count', type: 'quantitative' },
+        y: { field: 'category', type: 'nominal', sort: 'ascending' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'auto', format: '', prefix: '' },
+      watermark: true,
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    // numeric: true in localeCompare means "1" < "2" < "10"
+    expect(domain).toEqual(['1', '2', '10']);
+  });
+
+  it('does not sort when explicit scale.domain is provided', () => {
+    const spec: NormalizedChartSpec = {
+      markType: 'bar',
+      markDef: { type: 'bar' },
+      data: [
+        { category: 'C', count: 10 },
+        { category: 'A', count: 20 },
+        { category: 'B', count: 30 },
+      ],
+      encoding: {
+        x: { field: 'count', type: 'quantitative' },
+        y: {
+          field: 'category',
+          type: 'nominal',
+          sort: 'ascending',
+          scale: { domain: ['C', 'B', 'A'] },
+        },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'auto', format: '', prefix: '' },
+      watermark: true,
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+
+    const scales = computeScales(spec, chartArea, spec.data);
+    const domain = (scales.y!.scale as ScaleBand<string>).domain();
+    // Explicit domain takes precedence over sort
+    expect(domain).toEqual(['C', 'B', 'A']);
+  });
+});

package/src/__tests__/facet.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
+import { autoColumns, computeFacetGrid } from '../layout/facet';
+
+const facetData = [
+  { year: '2020', country: 'US', value: 100 },
+  { year: '2021', country: 'US', value: 120 },
+  { year: '2020', country: 'UK', value: 80 },
+  { year: '2021', country: 'UK', value: 90 },
+  { year: '2020', country: 'DE', value: 70 },
+  { year: '2021', country: 'DE', value: 85 },
+];
+
+const facetSpec = {
+  mark: 'line' as const,
+  data: facetData,
+  encoding: {
+    x: { field: 'year', type: 'ordinal' as const },
+    y: { field: 'value', type: 'quantitative' as const },
+    facet: { field: 'country', type: 'nominal' as const },
+  },
+};
+
+describe('autoColumns', () => {
+  it('returns sqrt-based columns for moderate panel counts', () => {
+    expect(autoColumns(4, 800)).toBe(2);
+    expect(autoColumns(9, 1200)).toBe(3);
+  });
+
+  it('caps columns by available width', () => {
+    expect(autoColumns(9, 400)).toBe(2);
+  });
+
+  it('returns 1 for single panel', () => {
+    expect(autoColumns(1, 800)).toBe(1);
+  });
+
+  it('does not exceed panel count', () => {
+    expect(autoColumns(2, 2000)).toBe(2);
+  });
+});
+
+describe('computeFacetGrid', () => {
+  it('returns empty result for 0 panels', () => {
+    const result = computeFacetGrid(
+      [],
+      undefined,
+      { x: 0, y: 0, width: 600, height: 400 },
+      {
+        left: 40,
+        bottom: 30,
+      },
+    );
+    expect(result.panels).toEqual([]);
+    expect(result.columns).toBe(0);
+    expect(result.rows).toBe(0);
+  });
+
+  it('computes correct number of panels', () => {
+    const result = computeFacetGrid(
+      ['A', 'B', 'C', 'D'],
+      2,
+      { x: 0, y: 0, width: 600, height: 400 },
+      { left: 40, bottom: 30 },
+    );
+    expect(result.panels).toHaveLength(4);
+    expect(result.columns).toBe(2);
+    expect(result.rows).toBe(2);
+  });
+
+  it('assigns correct row and col indices', () => {
+    const result = computeFacetGrid(
+      ['A', 'B', 'C'],
+      2,
+      { x: 0, y: 0, width: 600, height: 400 },
+      { left: 40, bottom: 30 },
+    );
+    expect(result.panels[0]).toMatchObject({ key: 'A', row: 0, col: 0 });
+    expect(result.panels[1]).toMatchObject({ key: 'B', row: 0, col: 1 });
+    expect(result.panels[2]).toMatchObject({ key: 'C', row: 1, col: 0 });
+  });
+
+  it('panels do not overlap', () => {
+    const result = computeFacetGrid(
+      ['A', 'B', 'C', 'D', 'E', 'F'],
+      3,
+      { x: 0, y: 0, width: 800, height: 600 },
+      { left: 40, bottom: 30 },
+    );
+    for (let i = 0; i < result.panels.length; i++) {
+      for (let j = i + 1; j < result.panels.length; j++) {
+        const a = result.panels[i].area;
+        const b = result.panels[j].area;
+        const xOverlap = a.x < b.x + b.width && a.x + a.width > b.x;
+        const yOverlap = a.y < b.y + b.height && a.y + a.height > b.y;
+        expect(xOverlap && yOverlap).toBe(false);
+      }
+    }
+  });
+
+  it('degrades columns when panels would be too narrow', () => {
+    const result = computeFacetGrid(
+      ['A', 'B', 'C', 'D'],
+      4,
+      { x: 0, y: 0, width: 400, height: 400 },
+      { left: 40, bottom: 30 },
+    );
+    expect(result.columns).toBeLessThan(4);
+    for (const panel of result.panels) {
+      expect(panel.area.width).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('clamps panel height to zero for tiny containers', () => {
+    const result = computeFacetGrid(
+      ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J'],
+      1,
+      { x: 0, y: 0, width: 400, height: 100 },
+      { left: 40, bottom: 30 },
+    );
+    for (const panel of result.panels) {
+      expect(panel.area.height).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe('compileChart with facet', () => {
+  it('populates layout.facet with correct panel count', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    expect(layout.facet).toBeDefined();
+    expect(layout.facet!.panels).toHaveLength(3);
+    expect(layout.facet!.facetField).toBe('country');
+  });
+
+  it('sorts panels ascending by default', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    const keys = layout.facet!.panels.map((p) => p.key);
+    expect(keys).toEqual(['DE', 'UK', 'US']);
+  });
+
+  it('respects descending sort', () => {
+    const spec = {
+      ...facetSpec,
+      encoding: {
+        ...facetSpec.encoding,
+        facet: { ...facetSpec.encoding.facet, sort: 'descending' as const },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    const keys = layout.facet!.panels.map((p) => p.key);
+    expect(keys).toEqual(['US', 'UK', 'DE']);
+  });
+
+  it('preserves data order with sort: null', () => {
+    const spec = {
+      ...facetSpec,
+      encoding: {
+        ...facetSpec.encoding,
+        facet: { ...facetSpec.encoding.facet, sort: null },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    const keys = layout.facet!.panels.map((p) => p.key);
+    expect(keys).toEqual(['US', 'UK', 'DE']);
+  });
+
+  it('uses shared scales by default', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    expect(layout.facet!.sharedScales).toBe(true);
+  });
+
+  it('supports independent y scales via resolve', () => {
+    const spec = {
+      ...facetSpec,
+      resolve: { scale: { y: 'independent' as const } },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.facet!.sharedScales).toBe(false);
+  });
+
+  it('each panel has marks and axes', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    for (const panel of layout.facet!.panels) {
+      expect(panel.marks.length).toBeGreaterThan(0);
+      expect(panel.area.width).toBeGreaterThan(0);
+      expect(panel.area.height).toBeGreaterThan(0);
+      expect(panel.header.text).toBeTruthy();
+    }
+  });
+
+  it('figure-level axes are undefined when faceted', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    expect(layout.axes.x).toBeUndefined();
+    expect(layout.axes.y).toBeUndefined();
+  });
+
+  it('marks union includes all panel marks', () => {
+    const layout = compileChart(facetSpec, { width: 600, height: 400 });
+    const panelMarkCount = layout.facet!.panels.reduce((sum, p) => sum + p.marks.length, 0);
+    expect(layout.marks.length).toBe(panelMarkCount);
+  });
+
+  it('non-faceted spec produces no facet layout', () => {
+    const spec = {
+      mark: 'line' as const,
+      data: facetData,
+      encoding: {
+        x: { field: 'year', type: 'ordinal' as const },
+        y: { field: 'value', type: 'quantitative' as const },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.facet).toBeUndefined();
+  });
+});