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

package/src/__tests__/facet.test.ts

@@ -1,359 +0,0 @@
-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);
-    expect(layout.facet!.direction).toBe('wrap');
-  });
-
-  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();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Row faceting
-// ---------------------------------------------------------------------------
-
-const rowSpec = {
-  mark: 'bar' as const,
-  data: facetData,
-  encoding: {
-    x: { field: 'value', type: 'quantitative' as const },
-    y: { field: 'country', type: 'nominal' as const },
-    row: { field: 'year', type: 'nominal' as const },
-  },
-};
-
-describe('compileChart with row faceting', () => {
-  it('produces facet layout with direction row', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 400 });
-    expect(layout.facet).toBeDefined();
-    expect(layout.facet!.direction).toBe('row');
-    expect(layout.facet!.columns).toBe(1);
-  });
-
-  it('creates one panel per unique row value', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 400 });
-    expect(layout.facet!.panels).toHaveLength(2);
-  });
-
-  it('defaults x to shared, y to independent', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 400 });
-    expect(layout.facet!.sharedScales).toBe(false);
-  });
-
-  it('strips x-axis from non-bottom panels', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 600 });
-    const panels = layout.facet!.panels;
-    expect(panels[0].axes.x?.ticks ?? []).toHaveLength(0);
-    const bottomPanel = panels[panels.length - 1];
-    expect(bottomPanel.axes.x?.ticks.length).toBeGreaterThan(0);
-  });
-
-  it('keeps y-axis on all panels', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 600 });
-    for (const panel of layout.facet!.panels) {
-      expect(panel.axes.y).toBeDefined();
-    }
-  });
-
-  it('left-aligns headers', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 400 });
-    for (const panel of layout.facet!.panels) {
-      expect(panel.header.textAnchor).toBe('start');
-      expect(panel.header.x).toBe(panel.area.x);
-    }
-  });
-
-  it('allows overriding y to shared via resolve', () => {
-    const spec = {
-      ...rowSpec,
-      resolve: { scale: { y: 'shared' as const } },
-    };
-    const layout = compileChart(spec, { width: 600, height: 400 });
-    expect(layout.facet!.sharedScales).toBe(true);
-  });
-
-  it('each panel has marks', () => {
-    const layout = compileChart(rowSpec, { width: 600, height: 600 });
-    for (const panel of layout.facet!.panels) {
-      expect(panel.marks.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Column faceting
-// ---------------------------------------------------------------------------
-
-const colSpec = {
-  mark: 'bar' as const,
-  data: facetData,
-  encoding: {
-    x: { field: 'country', type: 'nominal' as const },
-    y: { field: 'value', type: 'quantitative' as const },
-    column: { field: 'year', type: 'nominal' as const },
-  },
-};
-
-describe('compileChart with column faceting', () => {
-  it('produces facet layout with direction column', () => {
-    const layout = compileChart(colSpec, { width: 800, height: 400 });
-    expect(layout.facet).toBeDefined();
-    expect(layout.facet!.direction).toBe('column');
-    expect(layout.facet!.columns).toBe(2);
-  });
-
-  it('defaults y to shared, x to independent', () => {
-    const layout = compileChart(colSpec, { width: 800, height: 400 });
-    expect(layout.facet!.sharedScales).toBe(false);
-    // Verify the directional resolve: y-axis ticks should be stripped from
-    // non-leftmost panels (shared y), x-axis ticks should appear on all panels
-    // (independent x).
-    const panels = layout.facet!.panels;
-    if (panels.length > 1) {
-      const rightPanel = panels[1];
-      expect(rightPanel.axes.y?.ticks ?? []).toHaveLength(0);
-    }
-    const leftPanel = panels[0];
-    expect(leftPanel.axes.y?.ticks?.length).toBeGreaterThan(0);
-  });
-
-  it('strips y-axis from non-leftmost panels', () => {
-    const layout = compileChart(colSpec, { width: 800, height: 400 });
-    const panels = layout.facet!.panels;
-    expect(panels[0].axes.y?.ticks?.length).toBeGreaterThan(0);
-    if (panels.length > 1) {
-      expect(panels[1].axes.y?.ticks ?? []).toHaveLength(0);
-    }
-  });
-
-  it('allows overriding x to shared via resolve', () => {
-    const spec = {
-      ...colSpec,
-      resolve: { scale: { x: 'shared' as const } },
-    };
-    const layout = compileChart(spec, { width: 800, height: 400 });
-    expect(layout.facet!.sharedScales).toBe(true);
-  });
-
-  it('centers headers (not left-aligned)', () => {
-    const layout = compileChart(colSpec, { width: 800, height: 400 });
-    for (const panel of layout.facet!.panels) {
-      expect(panel.header.textAnchor).toBeUndefined();
-    }
-  });
-
-  it('creates panels in a single row', () => {
-    const layout = compileChart(colSpec, { width: 800, height: 400 });
-    for (const panel of layout.facet!.panels) {
-      expect(panel.header.text).toBeTruthy();
-    }
-    expect(layout.facet!.panels).toHaveLength(2);
-  });
-});

package/src/__tests__/helpers/invariants.ts

@@ -1,299 +0,0 @@
-/**
- * Layout invariant assertions.
- *
- * Extracts bounding boxes from a compiled ChartLayout and checks that
- * layout elements don't overlap where they shouldn't.
- */
-
-import type {
-  CategoricalLegendLayout,
-  ChartLayout,
-  LegendLayout,
-  Rect,
-} from '@opendata-ai/openchart-core';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface NamedRect extends Rect {
-  name: string;
-}
-
-// ---------------------------------------------------------------------------
-// Type guards
-// ---------------------------------------------------------------------------
-
-function isCategoricalLegend(legend: LegendLayout): legend is CategoricalLegendLayout {
-  return 'entries' in legend && (!legend.type || legend.type === 'categorical');
-}
-
-/**
- * Every legend on the layout. Falls back to the singular `legend` slot so this
- * still works against layouts built by older code paths (and by tests that
- * hand-assemble a ChartLayout).
- */
-function allLegends(layout: ChartLayout): LegendLayout[] {
-  if (layout.legends?.length) return layout.legends;
-  return layout.legend ? [layout.legend] : [];
-}
-
-// ---------------------------------------------------------------------------
-// Box extraction
-// ---------------------------------------------------------------------------
-
-const CHROME_KEYS = [
-  'eyebrow',
-  'title',
-  'subtitle',
-  'source',
-  'byline',
-  'footer',
-  'brand',
-] as const;
-
-/**
- * Extracts every layout element's bounding box as a NamedRect.
- */
-export function extractBoxes(layout: ChartLayout): NamedRect[] {
-  const boxes: NamedRect[] = [];
-
-  // Chart area
-  boxes.push({ ...layout.area, name: 'chartArea' });
-
-  // Legend bounds -- EVERY legend, not just the primary. A chart can carry both
-  // a color legend and a size legend; registering only `layout.legend` would
-  // leave the overlap invariants blind to exactly the element most likely to be
-  // mis-reserved, and they would pass a chart whose size legend sits on the plot.
-  for (const legend of allLegends(layout)) {
-    const suffix = legend.channel && legend.channel !== 'color' ? `-${legend.channel}` : '';
-    boxes.push({ ...legend.bounds, name: `legend${suffix}` });
-
-    // Legend entry positions (categorical only)
-    if (isCategoricalLegend(legend) && legend.entryPositions) {
-      const rowHeight = legend.rowHeight ?? 16;
-      for (let i = 0; i < legend.entryPositions.length; i++) {
-        const pos = legend.entryPositions[i];
-        boxes.push({
-          x: pos.x,
-          y: pos.y,
-          width: pos.width,
-          height: rowHeight,
-          name: `legend${suffix}-entry-${i}`,
-        });
-      }
-    }
-  }
-
-  // X-axis label band
-  if (layout.axes.x?.extent && layout.axes.x.extent > 0) {
-    boxes.push({
-      x: layout.area.x,
-      y: layout.area.y + layout.area.height,
-      width: layout.area.width,
-      height: layout.axes.x.extent,
-      name: 'x-axis-labels',
-    });
-  }
-
-  // Y-axis label band
-  if (layout.axes.y?.extent && layout.axes.y.extent > 0) {
-    boxes.push({
-      x: layout.area.x - layout.axes.y.extent,
-      y: layout.area.y,
-      width: layout.axes.y.extent,
-      height: layout.area.height,
-      name: 'y-axis-labels',
-    });
-  }
-
-  // Chrome elements store y as the TOP edge of the text box (renderers convert
-  // to the alphabetic baseline via textAscent), so y is the box top directly.
-  for (const key of CHROME_KEYS) {
-    const el = layout.chrome[key];
-    if (el) {
-      const h = el.style.fontSize * el.style.lineHeight;
-      boxes.push({ x: el.x, y: el.y, width: el.maxWidth, height: h, name: key });
-    }
-  }
-
-  // Annotation bounds
-  for (let i = 0; i < layout.annotations.length; i++) {
-    const annotation = layout.annotations[i];
-    if (annotation.bounds) {
-      boxes.push({ ...annotation.bounds, name: `annotation-${i}` });
-    }
-  }
-
-  // Endpoint labels
-  if (layout.endpointLabels?.bounds) {
-    boxes.push({ ...layout.endpointLabels.bounds, name: 'endpoint-labels' });
-  }
-
-  return boxes;
-}
-
-// ---------------------------------------------------------------------------
-// Overlap check
-// ---------------------------------------------------------------------------
-
-/**
- * Throws if two rects overlap by more than epsilon pixels.
- */
-export function assertNoOverlap(a: NamedRect, b: NamedRect, epsilon = 0.5): void {
-  const overlaps =
-    a.x < b.x + b.width - epsilon &&
-    a.x + a.width > b.x + epsilon &&
-    a.y < b.y + b.height - epsilon &&
-    a.y + a.height > b.y + epsilon;
-
-  if (overlaps) {
-    throw new Error(
-      `Overlap detected between "${a.name}" and "${b.name}": ` +
-        `a=${JSON.stringify({ x: a.x, y: a.y, width: a.width, height: a.height })}, ` +
-        `b=${JSON.stringify({ x: b.x, y: b.y, width: b.width, height: b.height })}`,
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Containment helper
-// ---------------------------------------------------------------------------
-
-function isContained(inner: Rect, outer: Rect, tolerance: number): boolean {
-  return (
-    inner.x >= outer.x - tolerance &&
-    inner.y >= outer.y - tolerance &&
-    inner.x + inner.width <= outer.x + outer.width + tolerance &&
-    inner.y + inner.height <= outer.y + outer.height + tolerance
-  );
-}
-
-function rectsOverlap(a: Rect, b: Rect, epsilon: number): boolean {
-  return (
-    a.x < b.x + b.width - epsilon &&
-    a.x + a.width > b.x + epsilon &&
-    a.y < b.y + b.height - epsilon &&
-    a.y + a.height > b.y + epsilon
-  );
-}
-
-function formatRect(r: Rect): string {
-  return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height });
-}
-
-// ---------------------------------------------------------------------------
-// Full invariant check
-// ---------------------------------------------------------------------------
-
-/**
- * Returns a list of violation strings. Empty when clean.
- */
-export function checkLayoutInvariants(
-  layout: ChartLayout,
-  opts: { svgWidth: number; svgHeight: number },
-): string[] {
-  const violations: string[] = [];
-
-  // 1. No legend intrudes into chartArea (top/bottom only; right/bottom-right
-  //    use area.width reduction, so overlap is a horizontal concern checked by rule 4)
-  //
-  //    Checked for EVERY legend and every legend type. A size legend is not
-  //    categorical, and it is the one whose space is most likely to be
-  //    under-reserved -- gating this on `isCategoricalLegend` would skip it.
-  for (const legend of allLegends(layout)) {
-    if (legend.bounds.width <= 0 || legend.bounds.height <= 0) continue;
-    const pos = legend.position;
-    if (pos === 'top' || pos === 'bottom') {
-      if (rectsOverlap(legend.bounds, layout.area, 0.5)) {
-        const name = legend.channel ?? 'color';
-        violations.push(
-          `${name} legend intrudes into chartArea: legend=${formatRect(legend.bounds)} chartArea=${formatRect(layout.area)}`,
-        );
-      }
-    }
-  }
-
-  // 1b. Legends don't overlap each other.
-  const legends = allLegends(layout).filter((l) => l.bounds.width > 0 && l.bounds.height > 0);
-  for (let i = 0; i < legends.length; i++) {
-    for (let j = i + 1; j < legends.length; j++) {
-      if (rectsOverlap(legends[i].bounds, legends[j].bounds, 0.5)) {
-        violations.push(
-          `legends overlap: ${legends[i].channel ?? 'color'}=${formatRect(legends[i].bounds)} ${legends[j].channel ?? 'color'}=${formatRect(legends[j].bounds)}`,
-        );
-      }
-    }
-  }
-
-  // 2. Every legend entryPosition box lies inside legend bounds
-  if (isCategoricalLegend(layout.legend) && layout.legend.entryPositions) {
-    const rowHeight = layout.legend.rowHeight ?? 16;
-    // Entry width includes trailing entryGap; the last entry in a row doesn't
-    // need that gap to fit inside bounds, so allow entryGap as extra tolerance.
-    const gapTolerance = layout.legend.entryGap + 1;
-    for (let i = 0; i < layout.legend.entryPositions.length; i++) {
-      const pos = layout.legend.entryPositions[i];
-      const entryBox: Rect = {
-        x: pos.x,
-        y: pos.y,
-        width: pos.width,
-        height: rowHeight,
-      };
-      if (!isContained(entryBox, layout.legend.bounds, gapTolerance)) {
-        violations.push(
-          `legend entry ${i} outside legend bounds: entry=${formatRect(entryBox)} bounds=${formatRect(layout.legend.bounds)}`,
-        );
-      }
-    }
-  }
-
-  // 3. X-axis label band doesn't intersect bottom chrome
-  const xExtent = layout.axes.x?.extent;
-  if (xExtent && xExtent > 0) {
-    const xAxisBand: Rect = {
-      x: layout.area.x,
-      y: layout.area.y + layout.area.height,
-      width: layout.area.width,
-      height: xExtent,
-    };
-    const bottomChromeKeys = ['source', 'byline', 'footer'] as const;
-    for (const key of bottomChromeKeys) {
-      const el = layout.chrome[key];
-      if (el) {
-        const h = el.style.fontSize * el.style.lineHeight;
-        const chromeBox: Rect = { x: el.x, y: el.y, width: el.maxWidth, height: h };
-        if (rectsOverlap(xAxisBand, chromeBox, 0.5)) {
-          violations.push(
-            `x-axis labels intersect ${key}: xAxis=${formatRect(xAxisBand)} ${key}=${formatRect(chromeBox)}`,
-          );
-        }
-      }
-    }
-  }
-
-  // 4. All boxes stay within SVG viewport
-  const viewport: Rect = {
-    x: 0,
-    y: 0,
-    width: opts.svgWidth,
-    height: opts.svgHeight,
-  };
-  const allBoxes = extractBoxes(layout);
-  for (const box of allBoxes) {
-    if (!isContained(box, viewport, 2)) {
-      violations.push(
-        `${box.name} outside SVG viewport: box=${formatRect(box)} viewport=${formatRect(viewport)}`,
-      );
-    }
-  }
-
-  // 5. Reserved margins cover drawn content
-  if (layout.area.y < layout.chrome.topHeight - 1) {
-    violations.push(
-      `top chrome overflows into chart area: area.y=${layout.area.y} chrome.topHeight=${layout.chrome.topHeight}`,
-    );
-  }
-
-  return violations;
-}