@opendata-ai/openchart-engine 1.2.0

package/src/charts/scatter/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Scatter / bubble chart module.
+ *
+ * Exports the scatter chart renderer and computation functions.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computeScatterMarks } from './compute';
+import { computeTrendLine } from './trendline';
+
+// ---------------------------------------------------------------------------
+// Scatter chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Scatter chart renderer.
+ *
+ * Produces point marks for each data point, optionally with size encoding
+ * for bubbles and a trend line overlay.
+ */
+export const scatterRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const pointMarks = computeScatterMarks(spec, scales, chartArea, strategy);
+  const marks: Mark[] = [...pointMarks];
+
+  // Add trend line if there are enough points
+  const trendLine = computeTrendLine(pointMarks);
+  if (trendLine) {
+    // Trend line goes behind points
+    marks.unshift(trendLine);
+  }
+
+  return marks;
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeScatterMarks } from './compute';
+export { computeTrendLine } from './trendline';

package/src/charts/scatter/trendline.ts

@@ -0,0 +1,100 @@
+/**
+ * Trend line computation for scatter plots.
+ *
+ * Computes a simple linear regression (least squares) over the
+ * point marks and returns a LineMark representing the best-fit line.
+ */
+
+import type { LineMark, MarkAria, PointMark } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TRENDLINE_COLOR = '#666666';
+const TRENDLINE_STROKE_WIDTH = 1.5;
+const TRENDLINE_DASH = '6 4';
+
+// ---------------------------------------------------------------------------
+// Linear regression
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute slope and intercept for a simple linear regression.
+ * Returns null if there aren't enough points or variance is zero.
+ */
+function linearRegression(
+  points: { x: number; y: number }[],
+): { slope: number; intercept: number } | null {
+  const n = points.length;
+  if (n < 2) return null;
+
+  let sumX = 0;
+  let sumY = 0;
+  let sumXY = 0;
+  let sumXX = 0;
+
+  for (const p of points) {
+    sumX += p.x;
+    sumY += p.y;
+    sumXY += p.x * p.y;
+    sumXX += p.x * p.x;
+  }
+
+  const denominator = n * sumXX - sumX * sumX;
+  if (denominator === 0) return null;
+
+  const slope = (n * sumXY - sumX * sumY) / denominator;
+  const intercept = (sumY - slope * sumX) / n;
+
+  return { slope, intercept };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a trend line (linear regression) over scatter point marks.
+ *
+ * Returns a single LineMark spanning the x-range of the data points,
+ * rendered as a dashed line. Returns null if regression can't be computed.
+ */
+export function computeTrendLine(marks: PointMark[]): LineMark | null {
+  if (marks.length < 2) return null;
+
+  const points = marks.map((m) => ({ x: m.cx, y: m.cy }));
+  const result = linearRegression(points);
+  if (!result) return null;
+
+  const { slope, intercept } = result;
+
+  // Find x range from marks
+  let minX = Infinity;
+  let maxX = -Infinity;
+  for (const m of marks) {
+    if (m.cx < minX) minX = m.cx;
+    if (m.cx > maxX) maxX = m.cx;
+  }
+
+  // Compute y values at the endpoints
+  const y1 = slope * minX + intercept;
+  const y2 = slope * maxX + intercept;
+
+  const aria: MarkAria = {
+    label: `Trend line: linear regression`,
+  };
+
+  return {
+    type: 'line',
+    points: [
+      { x: minX, y: y1 },
+      { x: maxX, y: y2 },
+    ],
+    stroke: TRENDLINE_COLOR,
+    strokeWidth: TRENDLINE_STROKE_WIDTH,
+    strokeDasharray: TRENDLINE_DASH,
+    data: [],
+    aria,
+  };
+}

package/src/charts/utils.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared utilities for chart mark computation.
+ *
+ * Common helpers used across multiple chart types: scale value resolution,
+ * data grouping, color lookup, and shared constants.
+ */
+
+import type { DataRow } from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
+import type { D3Scale, ResolvedScales } from '../layout/scales';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default single-series color when no color encoding is present. */
+export const DEFAULT_COLOR = '#1b7fa3';
+
+// ---------------------------------------------------------------------------
+// Scale helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a data value to a pixel position using a D3 scale.
+ *
+ * Handles time scales (parsing string dates), categorical scales
+ * (point, band, ordinal - passing string values directly), and
+ * linear/log scales (coercing to number). Returns null for values
+ * that can't be resolved (null, NaN, invalid dates, or values not
+ * in a categorical scale's domain).
+ */
+export function scaleValue(scale: D3Scale, scaleType: string, value: unknown): number | null {
+  if (value == null) return null;
+
+  if (scaleType === 'time') {
+    const date = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(date.getTime())) return null;
+    return (scale as ScaleTime<number, number>)(date);
+  }
+
+  // Categorical scales: pass string values directly
+  if (scaleType === 'point' || scaleType === 'band' || scaleType === 'ordinal') {
+    const result = (scale as ScalePoint<string> | ScaleBand<string>)(String(value));
+    return result ?? null;
+  }
+
+  const num = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(num)) return null;
+  return (scale as ScaleLinear<number, number>)(num);
+}
+
+// ---------------------------------------------------------------------------
+// Data grouping
+// ---------------------------------------------------------------------------
+
+/**
+ * Group data rows by a field value.
+ *
+ * If no field is provided, all rows are grouped under '__default__'.
+ * Returns a Map preserving insertion order.
+ */
+export function groupByField(data: DataRow[], field: string | undefined): Map<string, DataRow[]> {
+  const groups = new Map<string, DataRow[]>();
+
+  if (!field) {
+    groups.set('__default__', data);
+    return groups;
+  }
+
+  for (const row of data) {
+    const key = String(row[field] ?? '__default__');
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(row);
+    } else {
+      groups.set(key, [row]);
+    }
+  }
+
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// Color helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the color for a series/category from the resolved color scale.
+ *
+ * For single-series charts (key === '__default__'), uses the theme's
+ * first categorical color via scales.defaultColor.
+ */
+export function getColor(
+  scales: ResolvedScales,
+  key: string,
+  _index?: number,
+  fallback: string = DEFAULT_COLOR,
+): string {
+  if (scales.color && key !== '__default__') {
+    const colorScale = scales.color.scale as (v: string) => string;
+    return colorScale(key);
+  }
+  return scales.defaultColor ?? fallback;
+}
+
+/**
+ * Get color from a sequential (quantitative) color scale.
+ * Maps a numeric value to a color via linear interpolation.
+ */
+export function getSequentialColor(
+  scales: ResolvedScales,
+  value: number,
+  fallback: string = DEFAULT_COLOR,
+): string {
+  if (scales.color?.type === 'sequential') {
+    const colorScale = scales.color.scale as unknown as (v: number) => string;
+    return colorScale(value);
+  }
+  return scales.defaultColor ?? fallback;
+}

package/src/compile.ts

@@ -0,0 +1,368 @@
+/**
+ * Main compile API: the public entry points for the engine.
+ *
+ * Pipeline for charts:
+ *   validate spec -> normalize -> resolve theme -> dark mode adapt ->
+ *   compute legend -> compute dimensions (with legend space) ->
+ *   compute scales -> compute axes -> compute gridlines ->
+ *   get chart renderer -> compute marks -> compute a11y -> return ChartLayout
+ *
+ * Table compiler handles full data pipeline (sort, search, pagination, visual enhancements).
+ * Graph compiler is a stub for future implementation.
+ */
+
+import type {
+  ChartLayout,
+  CompileOptions,
+  CompileTableOptions,
+  Mark,
+  PointMark,
+  Rect,
+  RectMark,
+  ResolvedAnnotation,
+  ResolvedTheme,
+  TableLayout,
+} from '@opendata-ai/openchart-core';
+import {
+  adaptTheme,
+  generateAltText,
+  generateDataTable,
+  getBreakpoint,
+  getLayoutStrategy,
+  resolveTheme,
+} from '@opendata-ai/openchart-core';
+import { computeAnnotations } from './annotations/compute';
+import { barRenderer } from './charts/bar';
+import { columnRenderer } from './charts/column';
+import { dotRenderer } from './charts/dot';
+import { areaRenderer, lineRenderer } from './charts/line';
+import { donutRenderer, pieRenderer } from './charts/pie';
+import { type ChartRenderer, getChartRenderer, registerChartRenderer } from './charts/registry';
+import { scatterRenderer } from './charts/scatter';
+import { compile as compileSpec } from './compiler/index';
+
+// Register all built-in chart renderers. Explicit imports ensure bundlers
+// cannot tree-shake the registrations away (bare side-effect imports are
+// treated as dead code by esbuild).
+const builtinRenderers: Record<string, ChartRenderer> = {
+  line: lineRenderer,
+  area: areaRenderer,
+  bar: barRenderer,
+  column: columnRenderer,
+  scatter: scatterRenderer,
+  pie: pieRenderer,
+  donut: donutRenderer,
+  dot: dotRenderer,
+};
+for (const [type, renderer] of Object.entries(builtinRenderers)) {
+  registerChartRenderer(type, renderer);
+}
+
+import type { NormalizedChartSpec, NormalizedTableSpec } from './compiler/types';
+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 { computeGridlines } from './layout/gridlines';
+import { computeScales, type ResolvedScales } from './layout/scales';
+import { computeLegend } from './legend/compute';
+import { compileTableLayout } from './tables/compile-table';
+import { computeTooltipDescriptors } from './tooltips/compute';
+
+// ---------------------------------------------------------------------------
+// Mark obstacles for annotation collision avoidance
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute per-row bounding rects for band-scale charts (dot, bar).
+ * Each obstacle covers the full band height and x-range of marks in that row,
+ * giving the annotation nudge system awareness of data marks.
+ */
+function computeRowObstacles(marks: Mark[], scales: ResolvedScales): Rect[] {
+  if (!scales.y || scales.y.type !== 'band') return [];
+
+  // Group marks by their y-center (rounded), compute x-extent per group
+  const rows = new Map<number, { minX: number; maxX: number; bandY: number }>();
+
+  for (const mark of marks) {
+    let cy: number;
+    let left: number;
+    let right: number;
+
+    if (mark.type === 'point') {
+      const pm = mark as PointMark;
+      cy = pm.cy;
+      left = pm.cx - pm.r;
+      right = pm.cx + pm.r;
+    } else if (mark.type === 'rect') {
+      const rm = mark as RectMark;
+      cy = rm.y + rm.height / 2;
+      left = rm.x;
+      right = rm.x + rm.width;
+    } else {
+      continue;
+    }
+
+    // Round cy to group marks on the same band
+    const key = Math.round(cy);
+    const existing = rows.get(key);
+    if (existing) {
+      existing.minX = Math.min(existing.minX, left);
+      existing.maxX = Math.max(existing.maxX, right);
+    } else {
+      rows.set(key, { minX: left, maxX: right, bandY: cy });
+    }
+  }
+
+  // Get bandwidth from the band scale
+  const bandScale = scales.y.scale as { bandwidth?: () => number };
+  const bandwidth = bandScale.bandwidth?.() ?? 0;
+  if (bandwidth === 0) return [];
+
+  const obstacles: Rect[] = [];
+  for (const { minX, maxX, bandY } of rows.values()) {
+    obstacles.push({
+      x: minX,
+      y: bandY - bandwidth / 2,
+      width: maxX - minX,
+      height: bandwidth,
+    });
+  }
+
+  return obstacles;
+}
+
+// ---------------------------------------------------------------------------
+// Chart compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a chart spec into a ChartLayout.
+ *
+ * This is the main engine entry point. Takes a raw spec (any shape,
+ * validated at runtime) and compile options, produces a fully resolved
+ * ChartLayout with positions, colors, and marks ready for rendering.
+ *
+ * @param spec - Raw chart spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns ChartLayout with all computed positions.
+ * @throws Error if spec is invalid or not a chart type.
+ */
+export function compileChart(spec: unknown, options: CompileOptions): ChartLayout {
+  // Validate + normalize
+  const { spec: normalized } = compileSpec(spec);
+
+  if (normalized.type === 'table') {
+    throw new Error('compileChart received a table spec. Use compileTable instead.');
+  }
+  if (normalized.type === 'graph') {
+    throw new Error('compileChart received a graph spec. Use compileGraph instead.');
+  }
+
+  const chartSpec = normalized as NormalizedChartSpec;
+
+  // Resolve theme: merge spec-level theme with options-level overrides
+  const mergedThemeConfig = options.theme
+    ? { ...chartSpec.theme, ...options.theme }
+    : chartSpec.theme;
+  let theme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  if (options.darkMode) {
+    theme = adaptTheme(theme);
+  }
+
+  // Responsive strategy
+  const breakpoint = getBreakpoint(options.width);
+  const strategy = getLayoutStrategy(breakpoint);
+
+  // Compute legend first (needs to reserve space)
+  const preliminaryArea: Rect = {
+    x: 0,
+    y: 0,
+    width: options.width,
+    height: options.height,
+  };
+  const legendLayout = computeLegend(chartSpec, strategy, theme, preliminaryArea);
+
+  // Compute dimensions (accounts for chrome + legend)
+  const dims = computeDimensions(chartSpec, options, legendLayout, theme);
+  const chartArea = dims.chartArea;
+
+  // Recompute legend bounds relative to actual chart area.
+  // chartArea was shrunk to exclude legend space, so expand it back to include
+  // the reserved margin. This way computeLegend positions the legend outside
+  // the data area (in the margin) instead of overlapping data marks.
+  const legendArea: Rect = { ...chartArea };
+  if (legendLayout.entries.length > 0) {
+    switch (legendLayout.position) {
+      case 'top':
+        legendArea.y -= legendLayout.bounds.height + 4;
+        legendArea.height += legendLayout.bounds.height + 4;
+        break;
+      case 'bottom':
+        legendArea.height += legendLayout.bounds.height + 4;
+        break;
+      case 'right':
+      case 'bottom-right':
+        legendArea.width += legendLayout.bounds.width + 8;
+        break;
+    }
+  }
+  const finalLegend = computeLegend(chartSpec, strategy, theme, legendArea);
+
+  // Compute scales
+  const scales = computeScales(chartSpec, chartArea, chartSpec.data);
+
+  // Update color scale to use theme palette
+  if (scales.color) {
+    if (scales.color.type === 'sequential') {
+      // Sequential: use first sequential palette (or fall back to categorical endpoints)
+      const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+      (scales.color.scale as unknown as import('d3-scale').ScaleLinear<string, string>).range([
+        seqStops[0],
+        seqStops[seqStops.length - 1],
+      ]);
+    } else {
+      (scales.color.scale as import('d3-scale').ScaleOrdinal<string, string>).range(
+        theme.colors.categorical,
+      );
+    }
+  }
+
+  // Set default color for single-series charts (no color encoding)
+  scales.defaultColor = theme.colors.categorical[0];
+
+  // Pie/donut charts don't use axes or gridlines
+  const isRadial = chartSpec.type === 'pie' || chartSpec.type === 'donut';
+
+  // Compute axes (skip for radial charts)
+  const axes = isRadial
+    ? { x: undefined, y: undefined }
+    : computeAxes(scales, chartArea, strategy, theme);
+
+  // Compute gridlines (stored in axes, used by adapters via axes.y.gridlines)
+  if (!isRadial) {
+    computeGridlines(axes, chartArea);
+  }
+
+  // Get chart renderer and compute marks
+  const renderer = getChartRenderer(chartSpec.type);
+  const marks: Mark[] = renderer ? renderer(chartSpec, scales, chartArea, strategy, theme) : [];
+
+  // Compute annotations from spec, passing legend + mark bounds as obstacles for collision avoidance
+  const obstacles: Rect[] = [];
+  if (finalLegend.bounds.width > 0) {
+    obstacles.push(finalLegend.bounds);
+  }
+  obstacles.push(...computeRowObstacles(marks, scales));
+  const annotations: ResolvedAnnotation[] = computeAnnotations(
+    chartSpec,
+    scales,
+    chartArea,
+    strategy,
+    theme.isDark,
+    obstacles,
+  );
+
+  // Compute tooltip descriptors from marks and encoding
+  const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);
+
+  // Compute accessibility
+  const altText = generateAltText(
+    {
+      type: chartSpec.type,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding,
+      chrome: chartSpec.chrome,
+    },
+    chartSpec.data,
+  );
+  const dataTableFallback = generateDataTable(
+    {
+      type: chartSpec.type,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding,
+    },
+    chartSpec.data,
+  );
+
+  return {
+    area: chartArea,
+    chrome: dims.chrome,
+    axes: {
+      x: axes.x,
+      y: axes.y,
+    },
+    marks,
+    annotations,
+    legend: finalLegend,
+    tooltipDescriptors,
+    a11y: {
+      altText,
+      dataTableFallback,
+      role: 'img',
+      keyboardNavigable: marks.length > 0,
+    },
+    theme,
+    dimensions: {
+      width: options.width,
+      height: options.height,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Table compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a table spec into a TableLayout.
+ *
+ * Validates and normalizes the spec, resolves the theme, then delegates
+ * to compileTableLayout for the full pipeline: column resolution, search,
+ * sort, pagination, cell formatting, and visual enhancements.
+ *
+ * @param spec - Raw table spec.
+ * @param options - Compile options with sort, search, pagination state.
+ * @returns Fully resolved TableLayout.
+ */
+export function compileTable(spec: unknown, options: CompileTableOptions): TableLayout {
+  const { spec: normalized } = compileSpec(spec);
+
+  if (normalized.type !== 'table') {
+    throw new Error(`compileTable received a ${normalized.type} spec. Use compileChart instead.`);
+  }
+
+  const tableSpec = normalized as NormalizedTableSpec;
+
+  // Resolve theme: merge spec-level theme with options-level overrides
+  const mergedThemeConfig = options.theme
+    ? { ...tableSpec.theme, ...options.theme }
+    : tableSpec.theme;
+  let theme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  if (options.darkMode) {
+    theme = adaptTheme(theme);
+  }
+
+  return compileTableLayout(tableSpec, options, theme);
+}
+
+// ---------------------------------------------------------------------------
+// Graph compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a graph spec into a GraphCompilation.
+ *
+ * The graph pipeline resolves visual properties (size, color, stroke) for
+ * nodes and edges, assigns communities, and builds legend/tooltip/a11y data.
+ * Unlike charts, the output does NOT include x/y positions since the force
+ * simulation in the adapter handles layout at runtime.
+ *
+ * @param spec - Raw graph spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns GraphCompilation with resolved visual properties and simulation config.
+ * @throws Error if spec is invalid or not a graph type.
+ */
+export function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation {
+  return compileGraphImpl(spec, options);
+}