@opendata-ai/openchart-engine 7.6.1 → 7.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.6.1",
+  "version": "7.7.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "7.6.1",
+    "@opendata-ai/openchart-core": "7.7.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -68,6 +68,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     },
     annotations: [],
     responsive: true,
+    autoThin: true,
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '', prefix: '' },
@@ -75,6 +76,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     seriesStyles: {},
     watermark: true,
     display: 'full',
+    highlight: [],
     userExplicit: {
       chrome: false,
       legend: false,
@@ -110,6 +112,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     chrome: {},
     annotations: [],
     responsive: true,
+    autoThin: true,
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '', prefix: '' },
@@ -117,6 +120,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     seriesStyles: {},
     watermark: true,
     display: 'full',
+    highlight: [],
     userExplicit: {
       chrome: false,
       legend: false,
@@ -154,6 +158,7 @@ export function makeScatterSpec(): NormalizedChartSpec {
     chrome: {},
     annotations: [],
     responsive: true,
+    autoThin: true,
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '', prefix: '' },
@@ -161,6 +166,7 @@ export function makeScatterSpec(): NormalizedChartSpec {
     seriesStyles: {},
     watermark: true,
     display: 'full',
+    highlight: [],
     userExplicit: {
       chrome: false,
       legend: false,

package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap

@@ -231,6 +231,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
           "fill": "#ffffff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 11,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "end",
@@ -264,6 +265,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
           "fill": "#ffffff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 11,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "end",
@@ -297,6 +299,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
           "fill": "#ffffff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 11,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "end",
@@ -315,6 +318,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
   ],
   "metrics": undefined,
   "theme": {
+    "_tokenPairs": undefined,
     "borderRadius": 2,
     "chrome": {
       "byline": {
@@ -458,6 +462,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
       },
     },
     "isDark": false,
+    "seriesStrategy": "palette",
     "spacing": {
       "axisMargin": 6,
       "chartToFooter": 8,
@@ -861,6 +866,8 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
       "fontWeight": 600,
       "lineHeight": 1.25,
     },
+    "leading": undefined,
+    "leadingBounds": undefined,
     "swatchChipFill": "rgba(0,0,0,0.04)",
     "swatchSize": 18,
     "valueGap": 4,
@@ -868,6 +875,7 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
       "fill": "#71717a",
       "fontFamily": ""Inter Variable", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif",
       "fontSize": 12,
+      "fontVariant": "tabular-nums",
       "fontWeight": 400,
       "lineHeight": 1.25,
     },
@@ -1326,6 +1334,7 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
   ],
   "metrics": undefined,
   "theme": {
+    "_tokenPairs": undefined,
     "borderRadius": 2,
     "chrome": {
       "byline": {
@@ -1469,6 +1478,7 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
       },
     },
     "isDark": false,
+    "seriesStrategy": "palette",
     "spacing": {
       "axisMargin": 6,
       "chartToFooter": 8,
@@ -1800,6 +1810,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
           "fill": "#0000ff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 10,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "middle",
@@ -1844,6 +1855,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
           "fill": "#0000ff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 10,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "middle",
@@ -1888,6 +1900,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
           "fill": "#0000ff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 10,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "middle",
@@ -1932,6 +1945,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
           "fill": "#0000ff",
           "fontFamily": "system-ui, -apple-system, sans-serif",
           "fontSize": 10,
+          "fontVariant": "tabular-nums",
           "fontWeight": 600,
           "lineHeight": 1.2,
           "textAnchor": "middle",
@@ -1950,6 +1964,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
   ],
   "metrics": undefined,
   "theme": {
+    "_tokenPairs": undefined,
     "borderRadius": 2,
     "chrome": {
       "byline": {
@@ -2093,6 +2108,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
       },
     },
     "isDark": false,
+    "seriesStrategy": "palette",
     "spacing": {
       "axisMargin": 6,
       "chartToFooter": 8,

package/src/__tests__/axes.test.ts

@@ -668,9 +668,10 @@ describe('axis config properties', () => {
     const scales = computeScales(lineSpec, chartArea, lineSpec.data);
     const axes = computeAxes(scales, chartArea, fullStrategy, theme);
 
-    // All new properties should be undefined when not set
+    // All new properties should be undefined when not set (except domainLine,
+    // which defaults to false for non-grounded marks like line)
     expect(axes.x!.orient).toBeUndefined();
-    expect(axes.x!.domainLine).toBeUndefined();
+    expect(axes.x!.domainLine).toBe(false);
     expect(axes.x!.tickMarks).toBeUndefined();
     expect(axes.x!.offset).toBeUndefined();
     expect(axes.x!.titlePadding).toBeUndefined();

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

package/src/annotations/__tests__/compute.test.ts

@@ -672,6 +672,24 @@ describe('computeAnnotations', () => {
 
       expect(annotations).toHaveLength(0);
     });
+
+    it('keeps annotations at compact breakpoint when autoThin is on', () => {
+      const spec = makeSpec([{ type: 'text', x: '2020-01-01', y: 20, text: 'Kept' }]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, {
+        scales,
+        chartArea,
+        strategy: compactStrategy,
+        isDark: false,
+        obstacles: [],
+        svg: { width: 320, height: 300 },
+        measure: (text, font) => text.length * font.fontSize * 0.6,
+        autoThin: true,
+      });
+
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].label!.text).toBe('Kept');
+    });
   });
 
   describe('multiple annotations', () => {

package/src/annotations/__tests__/thinning.test.ts

@@ -0,0 +1,137 @@
+import type { Annotation, ResolvedAnnotation, TextAnnotation } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { thinAnnotations } from '../thinning';
+
+const measure = (text: string, font: { fontSize: number }) => text.length * font.fontSize * 0.6;
+
+function makeResolved(
+  x: number,
+  y: number,
+  text: string,
+  overrides?: Partial<ResolvedAnnotation>,
+): ResolvedAnnotation {
+  return {
+    type: 'text',
+    label: {
+      x,
+      y,
+      text,
+      visible: true,
+      style: { fontSize: 12, fontWeight: 400, textAnchor: 'start', lineHeight: 1.3 },
+    },
+    ...overrides,
+  } as ResolvedAnnotation;
+}
+
+function makeSpec(text: string, overrides?: Partial<TextAnnotation>): TextAnnotation {
+  return {
+    type: 'text',
+    x: 0,
+    y: 0,
+    text,
+    ...overrides,
+  } as TextAnnotation;
+}
+
+describe('thinAnnotations', () => {
+  it('returns unchanged when 0 or 1 annotations', () => {
+    const single = [makeResolved(100, 100, 'A')];
+    const result = thinAnnotations(single, [makeSpec('A')], measure);
+    expect(result.footnotes).toHaveLength(0);
+    expect(result.annotations).toBe(single);
+  });
+
+  it('keeps non-overlapping annotations in place', () => {
+    const annotations = [makeResolved(0, 0, 'First'), makeResolved(500, 500, 'Second')];
+    const specs: Annotation[] = [makeSpec('First'), makeSpec('Second')];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(0);
+    expect(result.annotations[0].footnoteIndex).toBeUndefined();
+    expect(result.annotations[1].footnoteIndex).toBeUndefined();
+  });
+
+  it('demotes overlapping annotations to footnotes', () => {
+    const annotations = [
+      makeResolved(100, 100, 'First label'),
+      makeResolved(105, 100, 'Second label'),
+    ];
+    const specs: Annotation[] = [makeSpec('First label'), makeSpec('Second label')];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(1);
+    expect(result.footnotes[0]).toEqual({ index: 1, text: 'Second label' });
+    expect(result.annotations[1].footnoteIndex).toBe(1);
+    expect(result.annotations[0].footnoteIndex).toBeUndefined();
+  });
+
+  it('respects priority ordering (lower priority kept first)', () => {
+    const annotations = [
+      makeResolved(100, 100, 'Low priority'),
+      makeResolved(105, 100, 'High priority'),
+    ];
+    const specs: Annotation[] = [
+      makeSpec('Low priority', { priority: 10 }),
+      makeSpec('High priority', { priority: 1 }),
+    ];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(1);
+    expect(result.footnotes[0].text).toBe('Low priority');
+    expect(result.annotations[1].footnoteIndex).toBeUndefined();
+    expect(result.annotations[0].footnoteIndex).toBe(1);
+  });
+
+  it('pins annotations with responsive: false', () => {
+    const annotations = [makeResolved(100, 100, 'Pinned'), makeResolved(105, 100, 'Candidate')];
+    const specs: Annotation[] = [makeSpec('Pinned', { responsive: false }), makeSpec('Candidate')];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(1);
+    expect(result.footnotes[0].text).toBe('Candidate');
+    expect(result.annotations[0].footnoteIndex).toBeUndefined();
+  });
+
+  it('does not thin non-text annotations', () => {
+    const annotations: ResolvedAnnotation[] = [
+      {
+        type: 'refline',
+        line: { start: { x: 0, y: 0 }, end: { x: 100, y: 0 } },
+      } as ResolvedAnnotation,
+      makeResolved(100, 100, 'Text'),
+    ];
+    const specs: Annotation[] = [{ type: 'refline', y: 0 }, makeSpec('Text')];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(0);
+  });
+
+  it('assigns sequential footnote indices', () => {
+    const annotations = [
+      makeResolved(100, 100, 'Keep this'),
+      makeResolved(105, 100, 'Demote 1'),
+      makeResolved(110, 100, 'Demote 2'),
+    ];
+    const specs: Annotation[] = [makeSpec('Keep this'), makeSpec('Demote 1'), makeSpec('Demote 2')];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(2);
+    expect(result.footnotes[0].index).toBe(1);
+    expect(result.footnotes[1].index).toBe(2);
+  });
+
+  it('maintains correct index alignment with mixed annotation types', () => {
+    const annotations: ResolvedAnnotation[] = [
+      {
+        type: 'refline',
+        line: { start: { x: 0, y: 0 }, end: { x: 100, y: 0 } },
+      } as ResolvedAnnotation,
+      makeResolved(100, 100, 'First text'),
+      makeResolved(105, 100, 'Second text'),
+    ];
+    const specs: Annotation[] = [
+      { type: 'refline', y: 0 },
+      makeSpec('First text', { priority: 1 }),
+      makeSpec('Second text', { priority: 10 }),
+    ];
+    const result = thinAnnotations(annotations, specs, measure);
+    expect(result.footnotes).toHaveLength(1);
+    expect(result.footnotes[0].text).toBe('Second text');
+    expect(result.annotations[1].footnoteIndex).toBeUndefined();
+    expect(result.annotations[2].footnoteIndex).toBe(1);
+  });
+});

package/src/annotations/compute.ts

@@ -47,6 +47,8 @@ export interface AnnotationContext {
   svg: { width: number; height: number };
   measure: AnnotationMeasureTextFn;
   debugPlacement?: boolean;
+  /** When true, annotations that overlap are demoted to footnote markers instead of being hidden. */
+  autoThin?: boolean;
 }
 
 /**
@@ -105,7 +107,7 @@ export function computeAnnotations(
     };
   }
 
-  const isCompact = ctx.strategy.annotationPosition === 'tooltip-only';
+  const isCompact = ctx.strategy.annotationPosition === 'tooltip-only' && !ctx.autoThin;
 
   const svgRect: Rect = { x: 0, y: 0, width: ctx.svg.width, height: ctx.svg.height };
   const annotations: ResolvedAnnotation[] = [];