@opendata-ai/openchart-engine 7.6.1 → 7.8.0

package/src/compile.ts

@@ -22,8 +22,12 @@ import type {
   CompileTableOptions,
   Encoding,
   EncodingChannel,
+  FacetChannel,
+  FacetPanelLayout,
   LayerSpec,
+  LayoutStrategy,
   Mark,
+  ResolvedAnimation,
   ResolvedAnnotation,
   ResolvedTheme,
   TableLayout,
@@ -44,6 +48,7 @@ import {
 import { computeAnnotations } from './annotations/compute';
 import { type AnnotationMeasureTextFn, heuristicMeasure } from './annotations/geometry';
 import type { PlacementObstacle } from './annotations/placement';
+import { thinAnnotations } from './annotations/thinning';
 import { computeEndpointLabels } from './endpoint-labels/compute';
 // Side-effect import: registers all built-in chart renderers with the
 // registry on module load. Tests that clear the registry can import
@@ -56,6 +61,7 @@ import {
   resolveRendererKey,
 } from './charts/post-process';
 import { getChartRenderer } from './charts/registry';
+import { groupByField } from './charts/utils';
 import { applyColorScaleRange } from './compile/color-scale-range';
 import { filterClippedDomains } from './compile/data-clip';
 import { compileLayer as compileLayerImpl } from './compile/layer';
@@ -73,6 +79,7 @@ import { compileGraph as compileGraphImpl } from './graphs/compile-graph';
 import type { GraphCompilation } from './graphs/types';
 import { computeAxes } from './layout/axes';
 import { computeDimensions } from './layout/dimensions';
+import { computeFacetGrid } from './layout/facet';
 import { computeGridlines } from './layout/gridlines';
 import { createMeasureFn, resolveLayoutPlan } from './layout/plan';
 import { computeScales } from './layout/scales';
@@ -585,6 +592,24 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     };
   }
 
+  // ---------------------------------------------------------------------------
+  // Faceted compilation: when encoding.facet is present, take the faceted path
+  // ---------------------------------------------------------------------------
+  const facetChannel = renderSpec.encoding.facet;
+  if (facetChannel?.field) {
+    return compileFaceted(
+      chartSpec,
+      renderSpec,
+      facetChannel,
+      options,
+      theme,
+      strategy,
+      watermark,
+      resolvedAnimation,
+      crosshair,
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // Layout plan: measure real labels, freeze gutter + chrome + legend content
   // ---------------------------------------------------------------------------
@@ -639,8 +664,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Compute scales
   const scales = computeScales(renderSpec, scaleArea, renderSpec.data);
 
-  // Update color scale to use theme palette (only when user hasn't provided an explicit range)
-  applyColorScaleRange(scales, renderSpec.encoding, theme);
+  // Update color scale to use theme palette (only when user hasn't provided an explicit range).
+  // When highlight is active, assign palette colors to highlighted series and mute the rest.
+  applyColorScaleRange(scales, renderSpec.encoding, theme, renderSpec.highlight);
 
   // INVARIANT 3 -- post-hoc defaultColor: must run AFTER computeScales since resolution needs
   // theme context. Do not move into computeScales (would require threading theme through).
@@ -692,7 +718,14 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Compute the right-side endpoint labels column for multi-series line/area
   // charts. Reads `mark.dataPoints` so it must run AFTER marks are computed.
   // dimensions.ts already reserved the right margin via predictEndpointLabelsWidth.
-  const endpointLabels = computeEndpointLabels(chartSpec, marks, theme, chartArea, strategy);
+  const endpointLabels = computeEndpointLabels(
+    chartSpec,
+    marks,
+    theme,
+    chartArea,
+    strategy,
+    plan.endpointLabelsDemoted,
+  );
 
   // Compute annotations from spec, passing legend + mark + brand bounds as obstacles
   const obstacles: PlacementObstacle[] = [];
@@ -721,7 +754,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     ? (text, font) => options.measureText!(text, font.fontSize, font.fontWeight).width
     : heuristicMeasure;
 
-  const annotations: ResolvedAnnotation[] = computeAnnotations(chartSpec, {
+  let annotations: ResolvedAnnotation[] = computeAnnotations(chartSpec, {
     scales,
     chartArea,
     strategy,
@@ -729,8 +762,21 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     obstacles,
     svg: { width: dims.total.width, height: dims.total.height },
     measure: annotationMeasure,
+    autoThin: chartSpec.autoThin,
   });
 
+  // Auto-thinning: demote overlapping text annotations to footnote markers.
+  // Pass the full spec annotations (not filtered to text-only) so index
+  // alignment with the resolved array is preserved.
+  let footnotes: import('@opendata-ai/openchart-core').AnnotationFootnote[] | undefined;
+  if (chartSpec.autoThin && annotations.length > 1) {
+    const result = thinAnnotations(annotations, chartSpec.annotations, annotationMeasure);
+    annotations = result.annotations;
+    if (result.footnotes.length > 0) {
+      footnotes = result.footnotes;
+    }
+  }
+
   // Compute tooltip descriptors from marks and encoding
   const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);
 
@@ -756,9 +802,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Assign animationIndex for stagger ordering when animation is enabled
   assignAnimationIndices(marks, resolvedAnimation);
 
+  const chrome = footnotes ? { ...dims.chrome, footnotes } : dims.chrome;
+
   return {
     area: chartArea,
-    chrome: dims.chrome,
+    chrome,
     metrics: dims.metrics,
     axes: {
       x: axes.x,
@@ -788,6 +836,267 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   };
 }
 
+// ---------------------------------------------------------------------------
+// Faceted (small-multiples) compilation
+// ---------------------------------------------------------------------------
+
+function compileFaceted(
+  chartSpec: NormalizedChartSpec,
+  renderSpec: NormalizedChartSpec,
+  facetChannel: FacetChannel,
+  options: CompileOptions,
+  theme: ResolvedTheme,
+  strategy: LayoutStrategy,
+  watermark: boolean,
+  resolvedAnimation: ResolvedAnimation | undefined,
+  crosshair: boolean,
+): ChartLayout {
+  const measure = createMeasureFn(options.measureText);
+
+  // Strip facet from encoding before passing to per-panel pipeline (panels
+  // don't know they're faceted -- they compile as regular single charts).
+  const panelEncoding = { ...renderSpec.encoding };
+  delete (panelEncoding as Record<string, unknown>).facet;
+  const panelSpec = { ...renderSpec, encoding: panelEncoding };
+  const panelChartSpec = { ...chartSpec, encoding: panelEncoding };
+
+  // Partition data by facet field
+  const groups = groupByField(renderSpec.data, facetChannel.field);
+  const facetValues = Array.from(groups.keys());
+  if (facetChannel.sort !== null) {
+    const dir = facetChannel.sort === 'descending' ? -1 : 1;
+    facetValues.sort((a, b) => dir * a.localeCompare(b));
+  }
+
+  // Compute figure-level chrome and dimensions using the full dataset
+  // (no facet channel so it compiles normally). We use a representative
+  // single-panel spec to get chrome + legend measurements.
+  const plan = resolveLayoutPlan(
+    panelChartSpec,
+    panelSpec,
+    options,
+    theme,
+    strategy,
+    watermark,
+    measure,
+  );
+  const legendStub = placeLegend(
+    plan.legendContent,
+    { x: 0, y: 0, width: options.width, height: options.height },
+    options.width,
+    theme,
+    plan.xAxisExtent,
+  );
+  const dims = computeDimensions(
+    panelChartSpec,
+    options,
+    legendStub,
+    theme,
+    strategy,
+    watermark,
+    plan,
+  );
+  const chartArea = dims.chartArea;
+
+  const finalLegend = placeLegend(
+    plan.legendContent,
+    chartArea,
+    options.width,
+    theme,
+    plan.xAxisExtent,
+  );
+
+  // Estimate y-axis gutter width (used as left reservation for outer axes)
+  const leftReservation = plan.leftGutter;
+  // Estimate x-axis extent (used as bottom reservation for outer axes)
+  const bottomReservation = plan.xAxisExtent;
+
+  // Compute facet grid geometry
+  const grid = computeFacetGrid(facetValues, facetChannel.columns, chartArea, {
+    left: leftReservation,
+    bottom: bottomReservation,
+  });
+
+  // Resolve scale for determining if we use 'independent' or 'shared'
+  const resolveConfig = chartSpec.resolve;
+  const yResolve = resolveConfig?.scale?.y ?? 'shared';
+  const xResolve = resolveConfig?.scale?.x ?? 'shared';
+
+  // Compute shared scale domains from the full dataset (when shared)
+  const fullScales = computeScales(panelSpec, chartArea, renderSpec.data);
+  const sharedXDomain =
+    xResolve === 'shared' && fullScales.x ? fullScales.x.scale.domain() : undefined;
+  const sharedYDomain =
+    yResolve === 'shared' && fullScales.y ? fullScales.y.scale.domain() : undefined;
+
+  const isRadial = chartSpec.markType === 'arc';
+  const rendererKey = resolveRendererKey(
+    renderSpec.markType,
+    panelEncoding as Encoding,
+    renderSpec.markDef,
+  );
+  const renderer = getChartRenderer(rendererKey);
+
+  const allMarks: Mark[] = [];
+  const panelLayouts: FacetPanelLayout[] = [];
+
+  for (const gridPanel of grid.panels) {
+    const panelData = groups.get(gridPanel.key) ?? [];
+    const panelSpecLocal = { ...panelSpec, data: panelData };
+
+    // Inject shared domains via scale.domain on the encoding channels
+    let panelEnc = { ...panelEncoding } as Record<string, unknown>;
+    if (sharedXDomain && panelEnc.x) {
+      const xCh = panelEnc.x as Record<string, unknown>;
+      panelEnc = {
+        ...panelEnc,
+        x: { ...xCh, scale: { ...((xCh.scale as object) ?? {}), domain: sharedXDomain } },
+      };
+    }
+    if (sharedYDomain && panelEnc.y) {
+      const yCh = panelEnc.y as Record<string, unknown>;
+      panelEnc = {
+        ...panelEnc,
+        y: { ...yCh, scale: { ...((yCh.scale as object) ?? {}), domain: sharedYDomain } },
+      };
+    }
+    const panelSpecWithDomains = {
+      ...panelSpecLocal,
+      encoding: panelEnc as unknown as typeof panelSpec.encoding,
+    };
+
+    // Compute scales for this panel's area
+    const panelScales = computeScales(panelSpecWithDomains, gridPanel.area, panelData);
+    applyColorScaleRange(panelScales, panelSpecWithDomains.encoding, theme, renderSpec.highlight);
+    panelScales.defaultColor =
+      chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
+
+    // Outer-axis economy: only leftmost column gets y ticks, only bottom row gets x ticks.
+    // Exception: when scales are independent, every panel needs its own axis ticks.
+    const isLeftCol = gridPanel.col === 0;
+    const isBottomRow = gridPanel.row === grid.rows - 1;
+
+    const panelAxes = isRadial
+      ? { x: undefined, y: undefined }
+      : computeAxes(panelScales, gridPanel.area, strategy, theme, options.measureText, {
+          data: panelData,
+          encoding: panelSpecWithDomains.encoding as Encoding,
+          skipX: xResolve === 'shared' ? !isBottomRow : false,
+          skipY: yResolve === 'shared' ? !isLeftCol : false,
+          markType: chartSpec.markType,
+          totalWidth: gridPanel.area.width,
+        });
+
+    if (!isRadial) {
+      computeGridlines(panelAxes, gridPanel.area);
+    }
+
+    // Compute marks for this panel
+    const panelMarks: Mark[] = renderer
+      ? renderer(
+          panelSpecWithDomains,
+          panelScales,
+          gridPanel.area,
+          strategy,
+          theme,
+          gridPanel.area.width,
+        )
+      : [];
+
+    // Compute annotations for this panel
+    const annotationMeasure: AnnotationMeasureTextFn = options.measureText
+      ? (text, font) => options.measureText!(text, font.fontSize, font.fontWeight).width
+      : heuristicMeasure;
+    const panelAnnotations = computeAnnotations(panelSpecWithDomains, {
+      scales: panelScales,
+      chartArea: gridPanel.area,
+      strategy,
+      isDark: theme.isDark,
+      obstacles: [],
+      svg: { width: options.width, height: options.height },
+      measure: annotationMeasure,
+      autoThin: panelSpecWithDomains.autoThin,
+    });
+
+    allMarks.push(...panelMarks);
+
+    panelLayouts.push({
+      key: gridPanel.key,
+      area: gridPanel.area,
+      marks: panelMarks,
+      axes: { x: panelAxes.x, y: panelAxes.y },
+      annotations: panelAnnotations,
+      header: {
+        text: gridPanel.key,
+        x: gridPanel.headerPos.x,
+        y: gridPanel.headerPos.y,
+        fontSize: theme.fonts.sizes.body,
+        fontWeight: theme.fonts.weights.medium,
+      },
+    });
+  }
+
+  // Compute tooltip descriptors from all marks across panels
+  const tooltipDescriptors = computeTooltipDescriptors(panelChartSpec, allMarks);
+
+  // A11y: mention faceting in alt text
+  const panelCount = facetValues.length;
+  const baseAltText = generateAltText(
+    {
+      mark: chartSpec.markType,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding,
+      chrome: chartSpec.chrome,
+    } as ChartSpec,
+    chartSpec.data,
+  );
+  const altText = `${baseAltText} Faceted into ${panelCount} panels by ${facetChannel.field}.`;
+
+  const dataTableFallback = generateDataTable(
+    {
+      mark: chartSpec.markType,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding,
+    } as ChartSpec,
+    chartSpec.data,
+  );
+
+  // Assign animation indices across all panels
+  assignAnimationIndices(allMarks, resolvedAnimation);
+
+  // Figure-level axes are null (axes live in panels)
+  // Figure-level marks are the union of all panel marks (for tooltip/keyboard nav)
+  return {
+    area: chartArea,
+    chrome: dims.chrome,
+    metrics: dims.metrics,
+    axes: { x: undefined, y: undefined },
+    marks: allMarks,
+    annotations: [],
+    legend: finalLegend,
+    tooltipDescriptors,
+    a11y: {
+      altText,
+      dataTableFallback,
+      role: 'img',
+      keyboardNavigable: allMarks.length > 0,
+    },
+    theme,
+    dimensions: { width: options.width, height: options.height },
+    animation: resolvedAnimation,
+    watermark,
+    display: chartSpec.display,
+    crosshair,
+    measureText: options.measureText,
+    facet: {
+      panels: panelLayouts,
+      facetField: facetChannel.field,
+      columns: grid.columns,
+      sharedScales: yResolve === 'shared' && xResolve === 'shared',
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Layer compilation
 // ---------------------------------------------------------------------------

package/src/compiler/__tests__/normalize-highlight.test.ts

@@ -0,0 +1,103 @@
+import type { ChartSpec } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compile } from '../index';
+import { normalizeSpec } from '../normalize';
+import type { NormalizedChartSpec } from '../types';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const data = [
+  { date: '2020', country: 'Germany', value: 100 },
+  { date: '2020', country: 'France', value: 90 },
+  { date: '2020', country: 'Italy', value: 80 },
+  { date: '2021', country: 'Germany', value: 110 },
+  { date: '2021', country: 'France', value: 95 },
+  { date: '2021', country: 'Italy', value: 85 },
+];
+
+function makeSpec(highlight?: string | string[]): ChartSpec {
+  const colorChannel: Record<string, unknown> = {
+    field: 'country',
+    type: 'nominal',
+  };
+  if (highlight !== undefined) {
+    colorChannel.highlight = highlight;
+  }
+  return {
+    mark: 'line',
+    data,
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: colorChannel,
+    },
+  } as ChartSpec;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('normalizeSpec — highlight', () => {
+  it('normalizes a single string highlight to an array', () => {
+    const result = normalizeSpec(makeSpec('Germany')) as NormalizedChartSpec;
+    expect(result.highlight).toEqual(['Germany']);
+  });
+
+  it('preserves an array highlight as-is', () => {
+    const result = normalizeSpec(makeSpec(['Germany', 'France'])) as NormalizedChartSpec;
+    expect(result.highlight).toEqual(['Germany', 'France']);
+  });
+
+  it('defaults to an empty array when no highlight is specified', () => {
+    const result = normalizeSpec(makeSpec()) as NormalizedChartSpec;
+    expect(result.highlight).toEqual([]);
+  });
+
+  it('defaults to an empty array when there is no color encoding', () => {
+    const spec: ChartSpec = {
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const result = normalizeSpec(spec) as NormalizedChartSpec;
+    expect(result.highlight).toEqual([]);
+  });
+
+  it('warns when a highlight value does not appear in data', () => {
+    const { warnings } = compile(makeSpec(['Spain']));
+    const highlightWarning = warnings.find((w) => w.includes('Spain') && w.includes('highlight'));
+    expect(highlightWarning).toBeDefined();
+  });
+
+  it('does not warn when all highlight values appear in data', () => {
+    const { warnings } = compile(makeSpec(['Germany', 'France']));
+    const highlightWarning = warnings.find((w) => w.includes('highlight'));
+    expect(highlightWarning).toBeUndefined();
+  });
+
+  it('warns when highlight is combined with explicit scale.range', () => {
+    const spec: ChartSpec = {
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: {
+          field: 'country',
+          type: 'nominal',
+          highlight: ['Germany'],
+          scale: { range: ['red', 'blue', 'green'] },
+        },
+      },
+    };
+    const { warnings } = compile(spec);
+    const rangeWarning = warnings.find((w) => w.includes('scale.range') && w.includes('highlight'));
+    expect(rangeWarning).toBeDefined();
+  });
+});

package/src/compiler/__tests__/validate-highlight.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+import { validateSpec } from '../validate';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const data = [
+  { date: '2020', country: 'Germany', value: 100 },
+  { date: '2020', country: 'France', value: 90 },
+  { date: '2020', country: 'Italy', value: 80 },
+  { date: '2021', country: 'Germany', value: 110 },
+  { date: '2021', country: 'France', value: 95 },
+  { date: '2021', country: 'Italy', value: 85 },
+];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('validateSpec — highlight channel', () => {
+  it('accepts highlight on a nominal color channel with valid values', () => {
+    const result = validateSpec({
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal', highlight: ['Germany'] },
+      },
+    });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('accepts highlight as a single string (not array)', () => {
+    const result = validateSpec({
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal', highlight: 'Germany' },
+      },
+    });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('accepts highlight with multiple valid values', () => {
+    const result = validateSpec({
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal', highlight: ['Germany', 'France'] },
+      },
+    });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('rejects highlight on a quantitative color channel', () => {
+    const result = validateSpec({
+      mark: 'point',
+      data: [
+        { x: 1, y: 2, temp: 30 },
+        { x: 3, y: 4, temp: 50 },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+        color: { field: 'temp', type: 'quantitative', highlight: ['30'] },
+      },
+    });
+    expect(result.valid).toBe(false);
+    const highlightError = result.errors.find((e) => e.message.toLowerCase().includes('highlight'));
+    expect(highlightError).toBeDefined();
+    // Implementation may use ENCODING_MISMATCH or INVALID_VALUE
+    expect(['ENCODING_MISMATCH', 'INVALID_VALUE']).toContain(highlightError!.code);
+  });
+
+  it('does not reject highlight with unknown values at the validation level', () => {
+    // Unknown highlight values are a warning (surfaced during normalization),
+    // not a validation error. The spec should still pass validation.
+    const result = validateSpec({
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal', highlight: ['Spain'] },
+      },
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('does not produce highlight errors when no highlight is specified', () => {
+    const result = validateSpec({
+      mark: 'line',
+      data,
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal' },
+      },
+    });
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+});