@opendata-ai/openchart-engine 8.0.0-rc.8 → 8.0.0

package/src/graphs/types.ts

@@ -1,106 +0,0 @@
-/**
- * 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

@@ -1,177 +0,0 @@
-/**
- * @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

@@ -1,97 +0,0 @@
-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

@@ -1,192 +0,0 @@
-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');
-  });
-});