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

package/src/graphs/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Graph compilation types.
+ *
+ * These types represent the engine output for graph specs. Unlike GraphLayout
+ * (which includes x/y positions for adapter rendering), GraphCompilation
+ * contains resolved visual properties WITHOUT positional layout. The force
+ * simulation in the adapter sets node positions at runtime.
+ */
+
+import type {
+  A11yMetadata,
+  LegendLayout,
+  ResolvedChrome,
+  ResolvedTheme,
+  TooltipContent,
+} from '@opendata-ai/openchart-core';
+
+/** A compiled graph node with resolved visual properties (no x/y position). */
+export interface CompiledGraphNode {
+  /** Node identifier from the spec. */
+  id: string;
+  /** Computed radius from nodeSize encoding (3-20px range, default 5px). */
+  radius: number;
+  /** Computed fill color from nodeColor encoding or community assignment. */
+  fill: string;
+  /** Stroke color, slightly darker than fill. */
+  stroke: string;
+  /** Stroke width in pixels. Default 1. */
+  strokeWidth: number;
+  /** Label text from nodeLabel encoding or node id. */
+  label: string | undefined;
+  /** Label priority for level-of-detail rendering (0-1, degree/maxDegree). */
+  labelPriority: number;
+  /** Community/cluster assignment from the clustering field. */
+  community: string | undefined;
+  /** Original node data (all fields from the spec node). */
+  data: Record<string, unknown>;
+}
+
+/** A compiled graph edge with resolved visual properties (no positional endpoints). */
+export interface CompiledGraphEdge {
+  /** Source node id. */
+  source: string;
+  /** Target node id. */
+  target: string;
+  /** Stroke color from edgeColor encoding or theme default. */
+  stroke: string;
+  /** Stroke width from edgeWidth encoding (0.5-4px range, default 1px). */
+  strokeWidth: number;
+  /** Line style. */
+  style: 'solid' | 'dashed' | 'dotted';
+  /** Original edge data (all fields from the spec edge). */
+  data: Record<string, unknown>;
+}
+
+/** Configuration for the force simulation, derived from the spec layout. */
+export interface SimulationConfig {
+  /** Repulsion strength between nodes. Negative = repulsion. */
+  chargeStrength: number;
+  /** Target distance between linked nodes. */
+  linkDistance: number;
+  /** Clustering configuration, or null if no clustering. */
+  clustering: { field: string; strength: number } | null;
+  /** How quickly the simulation cools. Default 0.0228. */
+  alphaDecay: number;
+  /** Velocity damping. Default 0.4. */
+  velocityDecay: number;
+  /** Collision radius: max node radius + padding. */
+  collisionRadius: number;
+  /** Extra px added to node radius for collision (default 2). */
+  collisionPadding?: number;
+  /** Link force strength override. */
+  linkStrength?: number;
+  /** Whether to apply center force (default true). */
+  centerForce?: boolean;
+}
+
+/**
+ * The complete engine output for graph specs.
+ *
+ * Contains resolved visual properties for nodes and edges, but does NOT
+ * include x/y positions. The adapter's force simulation assigns positions
+ * at runtime using the simulationConfig.
+ */
+export interface GraphCompilation {
+  /** Compiled nodes with visual properties. */
+  nodes: CompiledGraphNode[];
+  /** Compiled edges with visual properties. */
+  edges: CompiledGraphEdge[];
+  /** Legend layout (community colors or nodeColor categories). */
+  legend: LegendLayout;
+  /** Resolved chrome text elements. */
+  chrome: ResolvedChrome;
+  /** Tooltip descriptors keyed by node id. */
+  tooltipDescriptors: Map<string, TooltipContent>;
+  /** Accessibility metadata. */
+  a11y: A11yMetadata;
+  /** Resolved theme used for rendering. */
+  theme: ResolvedTheme;
+  /** Total available dimensions. */
+  dimensions: { width: number; height: number };
+  /** Force simulation configuration. */
+  simulationConfig: SimulationConfig;
+  /** Whether to show the brand watermark. */
+  watermark: boolean;
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+/**
+ * @opendata-ai/openchart-engine
+ *
+ * Headless computation engine that takes a declarative spec and produces
+ * structured layout objects (ChartLayout, TableLayout, GraphCompilation).
+ *
+ * The engine does pure math and data transformation. It knows nothing about
+ * the DOM, React, or any rendering target.
+ */
+
+// ---------------------------------------------------------------------------
+// Main compile API
+// ---------------------------------------------------------------------------
+
+export {
+  compileBarList,
+  compileChart,
+  compileGraph,
+  compileLayer,
+  compileMap,
+  compileSankey,
+  compileTable,
+  compileTileMap,
+} from './compile';
+
+// ---------------------------------------------------------------------------
+// Animation resolution
+// ---------------------------------------------------------------------------
+
+export {
+  clampStaggerDelay,
+  ENTER_DEFAULTS,
+  EXIT_DEFAULTS,
+  resolveAnimation,
+  UPDATE_DEFAULTS,
+} from './compiler/animation';
+
+// ---------------------------------------------------------------------------
+// Mark keying for data-update transitions
+// ---------------------------------------------------------------------------
+
+export { dedupeKeys, serializeKeyValue } from './compiler/keys';
+
+// ---------------------------------------------------------------------------
+// Geometry helpers for path reconstruction
+// ---------------------------------------------------------------------------
+
+export { buildAreaPath, buildLinePath } from './charts/line/curves';
+
+// ---------------------------------------------------------------------------
+// Graph compilation types
+// ---------------------------------------------------------------------------
+
+export type {
+  CompiledGraphEdge,
+  CompiledGraphNode,
+  GraphCompilation,
+  SimulationConfig,
+} from './graphs/types';
+
+// ---------------------------------------------------------------------------
+// Sankey compilation types
+// ---------------------------------------------------------------------------
+
+export type { NormalizedSankeySpec } from './sankey/types';
+
+// ---------------------------------------------------------------------------
+// TileMap compilation types
+// ---------------------------------------------------------------------------
+
+export type { NormalizedBarListSpec } from './barlist/types';
+
+export type { NormalizedMapSpec } from './geo/types';
+
+export type { NormalizedTileMapSpec } from './tilemap/types';
+
+// ---------------------------------------------------------------------------
+// Annotations
+// ---------------------------------------------------------------------------
+
+export type { AnnotationContext } from './annotations/compute';
+export {
+  ARROWHEAD_LENGTH,
+  DEFAULT_ANNOTATION_FONT_SIZE,
+  DEFAULT_LINE_HEIGHT,
+} from './annotations/constants';
+export type { AnnotationMeasureTextFn, ArrowheadPoints } from './annotations/geometry';
+export {
+  computeArrowheadPoints,
+  heuristicMeasure,
+} from './annotations/geometry';
+export type { ObstacleKind, PlacementObstacle } from './annotations/placement';
+export type { RichSpan } from './annotations/rich-text';
+export { BOLD_SPAN_FONT_WEIGHT, parseAnnotationSpans } from './annotations/rich-text';
+
+// ---------------------------------------------------------------------------
+// Compiler pipeline (spec validation, normalization, generic compile)
+// ---------------------------------------------------------------------------
+
+export type {
+  CompileResult,
+  NormalizedChartSpec,
+  NormalizedChrome,
+  NormalizedGraphSpec,
+  NormalizedSpec,
+  NormalizedTableSpec,
+  ValidationError,
+  ValidationErrorCode,
+  ValidationResult,
+} from './compiler/index';
+export {
+  compile,
+  normalizeSpec,
+  validateSpec,
+} from './compiler/index';
+
+// ---------------------------------------------------------------------------
+// Chart renderer plugin API
+// ---------------------------------------------------------------------------
+
+export type { ChartRenderer } from './charts/registry';
+export {
+  clearRenderers,
+  getChartRenderer,
+  registerChartRenderer,
+} from './charts/registry';
+
+// ---------------------------------------------------------------------------
+// Legend geometry
+// ---------------------------------------------------------------------------
+
+// Used by the vanilla mount to compute facet height growth for auto-height
+// figures; single-sourcing avoids constant divergence with facet.ts.
+export { facetMinHeight } from './layout/facet';
+// Used by the vanilla mount to compute the top-legend block when growing
+// auto-height figures; exporting it keeps the gap math single-sourced.
+export { legendGap } from './legend/wrap';
+
+// ---------------------------------------------------------------------------
+// Data transforms
+// ---------------------------------------------------------------------------
+
+export {
+  evaluatePredicate,
+  isConditionalValueDef,
+  resolveConditionalValue,
+  runBin,
+  runCalculate,
+  runFilter,
+  runTimeUnit,
+  runTransforms,
+} from './transforms';
+
+// ---------------------------------------------------------------------------
+// Re-export core types for convenience
+// ---------------------------------------------------------------------------
+
+export type {
+  BarListLayout,
+  BarListSpec,
+  ChartLayout,
+  ChartSpec,
+  CompileOptions,
+  CompileTableOptions,
+  GraphLayout,
+  GraphSpec,
+  LayerSpec,
+  MapLayout,
+  MapSpec,
+  SankeyLayout,
+  SankeySpec,
+  TableLayout,
+  TableSpec,
+  TileMapLayout,
+  TileMapSpec,
+  VizSpec,
+} from '@opendata-ai/openchart-core';

package/src/layout/__tests__/metrics.test.ts

@@ -0,0 +1,97 @@
+import type { Metric } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import {
+  computeMetricBar,
+  METRIC_BAR_INTERNALS,
+  type MetricFontSizes,
+  metricBarHeight,
+} from '../metrics';
+
+const { TOP_GAP, BOTTOM_GAP, INTER_ROW_GAP, LABEL_LINE_HEIGHT_RATIO, VALUE_LINE_HEIGHT_RATIO } =
+  METRIC_BAR_INTERNALS;
+
+const defaultFonts: MetricFontSizes = { label: 10, value: 22 };
+const largeFonts: MetricFontSizes = { label: 16, value: 32 };
+
+const metrics: Metric[] = [
+  { label: 'Revenue', value: '$1.2B', delta: '+12%', deltaTone: 'up' },
+  { label: 'Users', value: '4.5M' },
+];
+
+const area = { x: 20, width: 600 };
+
+describe('metricBarHeight', () => {
+  it('returns the expected height at default font sizes', () => {
+    const expected =
+      TOP_GAP +
+      defaultFonts.label * LABEL_LINE_HEIGHT_RATIO +
+      INTER_ROW_GAP +
+      defaultFonts.value * VALUE_LINE_HEIGHT_RATIO +
+      BOTTOM_GAP;
+    expect(metricBarHeight()).toBe(expected);
+    expect(metricBarHeight(defaultFonts)).toBe(expected);
+  });
+
+  it('grows when font sizes increase', () => {
+    const large = metricBarHeight(largeFonts);
+    expect(large).toBeGreaterThan(metricBarHeight(defaultFonts));
+  });
+
+  it('matches the formula for custom sizes', () => {
+    const expected =
+      TOP_GAP +
+      largeFonts.label * LABEL_LINE_HEIGHT_RATIO +
+      INTER_ROW_GAP +
+      largeFonts.value * VALUE_LINE_HEIGHT_RATIO +
+      BOTTOM_GAP;
+    expect(metricBarHeight(largeFonts)).toBe(expected);
+  });
+});
+
+describe('computeMetricBar', () => {
+  it('uses custom font sizes for layout positions', () => {
+    const topY = 50;
+    const defaultBar = computeMetricBar(metrics, topY, area, 400, undefined, defaultFonts)!;
+    const largeBar = computeMetricBar(metrics, topY, area, 400, undefined, largeFonts)!;
+
+    expect(defaultBar).toBeDefined();
+    expect(largeBar).toBeDefined();
+
+    expect(largeBar.height).toBeGreaterThan(defaultBar.height);
+    expect(largeBar.height).toBe(metricBarHeight(largeFonts));
+
+    expect(largeBar.cells[0].labelY).toBeGreaterThan(defaultBar.cells[0].labelY);
+    expect(largeBar.cells[0].valueY).toBeGreaterThan(defaultBar.cells[0].valueY);
+  });
+
+  it('computes labelY and valueY from font sizes', () => {
+    const topY = 50;
+    const bar = computeMetricBar(metrics, topY, area, 400, undefined, largeFonts)!;
+
+    expect(bar.cells[0].labelY).toBe(topY + TOP_GAP + largeFonts.label);
+    expect(bar.cells[0].valueY).toBe(
+      topY +
+        TOP_GAP +
+        largeFonts.label * LABEL_LINE_HEIGHT_RATIO +
+        INTER_ROW_GAP +
+        largeFonts.value,
+    );
+  });
+
+  it('uses custom font size for overflow detection', () => {
+    const tinyCell: Metric[] = [{ label: 'A', value: 'WWWWWWWWWWWWWWWWWWWWWWWWWW' }];
+    const narrowArea = { x: 0, width: 500 };
+
+    const withSmall = computeMetricBar(tinyCell, 0, narrowArea, 400, undefined, {
+      label: 10,
+      value: 12,
+    });
+    const withLarge = computeMetricBar(tinyCell, 0, narrowArea, 400, undefined, {
+      label: 10,
+      value: 40,
+    });
+
+    expect(withSmall).toBeDefined();
+    expect(withLarge).toBeUndefined();
+  });
+});

package/src/layout/__tests__/scales-highlight.test.ts

@@ -0,0 +1,192 @@
+import type { ChartSpec, LineMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const MUTED_COLOR = '#bfc3c8';
+
+const data = [
+  { date: '2020', country: 'Germany', value: 100 },
+  { date: '2020', country: 'France', value: 90 },
+  { date: '2020', country: 'Italy', value: 80 },
+  { date: '2020', country: 'Spain', value: 70 },
+  { date: '2020', country: 'Poland', value: 60 },
+  { date: '2021', country: 'Germany', value: 110 },
+  { date: '2021', country: 'France', value: 95 },
+  { date: '2021', country: 'Italy', value: 85 },
+  { date: '2021', country: 'Spain', value: 75 },
+  { date: '2021', country: 'Poland', value: 65 },
+  { date: '2022', country: 'Germany', value: 120 },
+  { date: '2022', country: 'France', value: 100 },
+  { date: '2022', country: 'Italy', value: 90 },
+  { date: '2022', country: 'Spain', value: 80 },
+  { date: '2022', country: 'Poland', value: 70 },
+];
+
+const compileOptions = { width: 600, height: 400 };
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Color partitioning
+// ---------------------------------------------------------------------------
+
+describe('highlight — color partitioning', () => {
+  it('assigns palette color to highlighted series and muted color to others', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+    const italy = marks.find((m) => m.seriesKey === 'Italy');
+
+    expect(germany).toBeDefined();
+    expect(france).toBeDefined();
+    expect(italy).toBeDefined();
+
+    // Germany should have a real palette color (not the muted gray)
+    expect(germany!.stroke).not.toBe(MUTED_COLOR);
+
+    // Non-highlighted series should get the muted color
+    expect(france!.stroke).toBe(MUTED_COLOR);
+    expect(italy!.stroke).toBe(MUTED_COLOR);
+  });
+
+  it('assigns palette colors to multiple highlighted series', () => {
+    const layout = compileChart(makeSpec(['Germany', 'France']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+    const italy = marks.find((m) => m.seriesKey === 'Italy');
+
+    // Both highlighted series should have distinct palette colors
+    expect(germany!.stroke).not.toBe(MUTED_COLOR);
+    expect(france!.stroke).not.toBe(MUTED_COLOR);
+    expect(germany!.stroke).not.toBe(france!.stroke);
+
+    // Non-highlighted series should be muted
+    expect(italy!.stroke).toBe(MUTED_COLOR);
+  });
+
+  it('assigns all series palette colors when no highlight is active', () => {
+    const layout = compileChart(makeSpec(), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    // Every series should get a real palette color
+    for (const mark of marks) {
+      expect(mark.stroke).not.toBe(MUTED_COLOR);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Z-order: muted marks sort before highlighted marks
+// ---------------------------------------------------------------------------
+
+describe('highlight — z-order', () => {
+  it('places muted series marks before highlighted series marks', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    // Find the index of the first highlighted mark and the last muted mark
+    const germanyIndex = marks.findIndex((m) => m.seriesKey === 'Germany');
+    const lastMutedIndex = marks.reduce(
+      (maxIdx, m, i) => (m.seriesKey !== 'Germany' ? Math.max(maxIdx, i) : maxIdx),
+      -1,
+    );
+
+    // All muted marks should come before the highlighted mark in the array
+    expect(germanyIndex).toBeGreaterThan(lastMutedIndex);
+  });
+
+  it('places all muted marks before all highlighted marks with multiple highlights', () => {
+    const layout = compileChart(makeSpec(['Germany', 'France']), compileOptions);
+    const marks = layout.marks as LineMark[];
+    const highlightSet = new Set(['Germany', 'France']);
+
+    const firstHighlightIndex = marks.findIndex((m) => highlightSet.has(m.seriesKey ?? ''));
+    const lastMutedIndex = marks.reduce(
+      (maxIdx, m, i) => (!highlightSet.has(m.seriesKey ?? '') ? Math.max(maxIdx, i) : maxIdx),
+      -1,
+    );
+
+    expect(firstHighlightIndex).toBeGreaterThan(lastMutedIndex);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Muted line stroke width
+// ---------------------------------------------------------------------------
+
+describe('highlight — muted line stroke width', () => {
+  it('reduces stroke width for muted series', () => {
+    const layout = compileChart(makeSpec(['Germany']), compileOptions);
+    const marks = layout.marks as LineMark[];
+
+    const germany = marks.find((m) => m.seriesKey === 'Germany');
+    const france = marks.find((m) => m.seriesKey === 'France');
+
+    expect(germany).toBeDefined();
+    expect(france).toBeDefined();
+
+    expect(germany!.strokeWidth).toBeDefined();
+    expect(france!.strokeWidth).toBeDefined();
+    expect(france!.strokeWidth).toBeLessThan(germany!.strokeWidth);
+    expect(france!.strokeWidth).toBeGreaterThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Endpoint label suppression
+// ---------------------------------------------------------------------------
+
+describe('highlight — endpoint labels', () => {
+  it('only includes highlighted series in endpoint labels', () => {
+    const spec = { ...makeSpec(['Germany']), endpointLabels: { show: true } } as ChartSpec;
+    const layout = compileChart(spec, compileOptions);
+
+    expect(layout.endpointLabels).toBeDefined();
+    expect(layout.endpointLabels!.entries.length).toBeGreaterThan(0);
+    const labelSeriesKeys = layout.endpointLabels!.entries.map((e) => e.seriesKey);
+
+    expect(labelSeriesKeys).toContain('Germany');
+    expect(labelSeriesKeys).not.toContain('France');
+    expect(labelSeriesKeys).not.toContain('Italy');
+    expect(labelSeriesKeys).not.toContain('Spain');
+    expect(labelSeriesKeys).not.toContain('Poland');
+  });
+
+  it('includes all series in endpoint labels when no highlight is active', () => {
+    const spec = makeSpec();
+    const layout = compileChart(spec, compileOptions);
+
+    expect(layout.endpointLabels).toBeDefined();
+    expect(layout.endpointLabels!.entries.length).toBeGreaterThan(0);
+    const labelSeriesKeys = layout.endpointLabels!.entries.map((e) => e.seriesKey);
+
+    expect(labelSeriesKeys).toContain('Germany');
+    expect(labelSeriesKeys).toContain('France');
+    expect(labelSeriesKeys).toContain('Italy');
+  });
+});