@opendata-ai/openchart-engine 1.2.0

package/src/graphs/encoding.ts

@@ -0,0 +1,302 @@
+/**
+ * Graph encoding resolution.
+ *
+ * Maps graph encoding channels (nodeSize, nodeColor, edgeWidth, edgeColor,
+ * nodeLabel) to computed visual properties on nodes and edges. Uses d3 scales
+ * the same way scatter/bubble charts do: scaleSqrt for size, scaleOrdinal
+ * for categorical color, scaleLinear for quantitative color.
+ */
+
+import type {
+  GraphEdge,
+  GraphEncoding,
+  GraphNode,
+  ResolvedTheme,
+} from '@opendata-ai/openchart-core';
+import { max, min } from 'd3-array';
+import { scaleLinear, scaleOrdinal, scaleSqrt } from 'd3-scale';
+
+import type { CompiledGraphEdge, CompiledGraphNode } from './types';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_NODE_RADIUS = 5;
+const MIN_NODE_RADIUS = 3;
+const MAX_NODE_RADIUS = 20;
+
+const DEFAULT_EDGE_WIDTH = 1;
+const MIN_EDGE_WIDTH = 0.5;
+const MAX_EDGE_WIDTH = 4;
+
+const DEFAULT_STROKE_WIDTH = 1;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Darken a hex color by a percentage.
+ *
+ * Doesn't use d3-color (engine doesn't depend on it). Operates directly
+ * on hex RGB channels. Falls back to the original color on parse failure.
+ */
+export function darkenColor(hex: string, amount: number = 0.2): string {
+  // Strip # prefix
+  const clean = hex.replace(/^#/, '');
+  if (clean.length !== 6 && clean.length !== 3) return hex;
+
+  // Expand shorthand
+  const full =
+    clean.length === 3
+      ? clean
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : clean;
+
+  const r = Math.max(0, Math.round(parseInt(full.substring(0, 2), 16) * (1 - amount)));
+  const g = Math.max(0, Math.round(parseInt(full.substring(2, 4), 16) * (1 - amount)));
+  const b = Math.max(0, Math.round(parseInt(full.substring(4, 6), 16) * (1 - amount)));
+
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+}
+
+/**
+ * Apply opacity to a hex color, returning an rgba string.
+ */
+function hexWithOpacity(hex: string, opacity: number): string {
+  const clean = hex.replace(/^#/, '');
+  if (clean.length !== 6 && clean.length !== 3) {
+    // Non-hex input: return as-is with opacity via CSS
+    return hex;
+  }
+
+  const full =
+    clean.length === 3
+      ? clean
+          .split('')
+          .map((c) => c + c)
+          .join('')
+      : clean;
+
+  const r = parseInt(full.substring(0, 2), 16);
+  const g = parseInt(full.substring(2, 4), 16);
+  const b = parseInt(full.substring(4, 6), 16);
+
+  return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+}
+
+/**
+ * Compute the degree of each node (number of edges touching it).
+ */
+function computeDegrees(nodes: GraphNode[], edges: GraphEdge[]): Map<string, number> {
+  const degrees = new Map<string, number>();
+  for (const node of nodes) {
+    degrees.set(node.id, 0);
+  }
+  for (const edge of edges) {
+    degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + 1);
+    degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + 1);
+  }
+  return degrees;
+}
+
+// ---------------------------------------------------------------------------
+// Node visual resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve visual properties for all graph nodes.
+ *
+ * Applies nodeSize, nodeColor, and nodeLabel encoding channels from the
+ * spec to produce CompiledGraphNode objects with computed fill, radius,
+ * stroke, label, and label priority.
+ */
+export function resolveNodeVisuals(
+  nodes: GraphNode[],
+  encoding: GraphEncoding,
+  edges: GraphEdge[],
+  theme: ResolvedTheme,
+): CompiledGraphNode[] {
+  const degrees = computeDegrees(nodes, edges);
+  const maxDegree = Math.max(1, ...degrees.values());
+
+  // Build node size scale
+  let sizeScale: ((v: number) => number) | undefined;
+  if (encoding.nodeSize?.field) {
+    const field = encoding.nodeSize.field;
+    const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+
+    const sizeMin = min(values) ?? 0;
+    const sizeMax = max(values) ?? 1;
+
+    sizeScale = scaleSqrt().domain([sizeMin, sizeMax]).range([MIN_NODE_RADIUS, MAX_NODE_RADIUS]);
+  }
+
+  // Build node color scale
+  let colorFn: ((node: GraphNode) => string) | undefined;
+  if (encoding.nodeColor?.field) {
+    const field = encoding.nodeColor.field;
+    const fieldType = encoding.nodeColor.type ?? 'nominal';
+
+    if (fieldType === 'quantitative') {
+      const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+      const colorMin = min(values) ?? 0;
+      const colorMax = max(values) ?? 1;
+
+      // Use first sequential palette
+      const seqPalettes = Object.values(theme.colors.sequential);
+      const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
+      const colorScale = scaleLinear<string>()
+        .domain([colorMin, colorMax])
+        .range([palette[0], palette[palette.length - 1]]);
+
+      colorFn = (node: GraphNode) => {
+        const val = Number(node[field]);
+        return Number.isFinite(val) ? colorScale(val) : theme.colors.categorical[0];
+      };
+    } else {
+      // nominal/ordinal
+      const uniqueValues = [...new Set(nodes.map((n) => String(n[field] ?? '')))];
+      const ordinalScale = scaleOrdinal<string>()
+        .domain(uniqueValues)
+        .range(theme.colors.categorical);
+
+      colorFn = (node: GraphNode) => ordinalScale(String(node[field] ?? ''));
+    }
+  }
+
+  const defaultColor = theme.colors.categorical[0];
+
+  return nodes.map((node) => {
+    // Radius
+    let radius = DEFAULT_NODE_RADIUS;
+    if (sizeScale && encoding.nodeSize?.field) {
+      const val = Number(node[encoding.nodeSize.field]);
+      if (Number.isFinite(val)) {
+        radius = sizeScale(val);
+      }
+    }
+
+    // Color
+    const fill = colorFn ? colorFn(node) : defaultColor;
+
+    // Stroke: darken fill by 20%
+    const stroke = darkenColor(fill);
+
+    // Label
+    let label: string | undefined;
+    if (encoding.nodeLabel?.field) {
+      const labelVal = node[encoding.nodeLabel.field];
+      label = labelVal != null ? String(labelVal) : undefined;
+    } else {
+      label = node.id;
+    }
+
+    // Label priority: degree / maxDegree (0 to 1)
+    const degree = degrees.get(node.id) ?? 0;
+    const labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
+
+    // Data: spread all original node fields
+    const { id: _id, ...rest } = node;
+    const data: Record<string, unknown> = { id: node.id, ...rest };
+
+    return {
+      id: node.id,
+      radius,
+      fill,
+      stroke,
+      strokeWidth: DEFAULT_STROKE_WIDTH,
+      label,
+      labelPriority,
+      community: undefined,
+      data,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Edge visual resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve visual properties for all graph edges.
+ *
+ * Applies edgeWidth and edgeColor encoding channels to produce
+ * CompiledGraphEdge objects with computed stroke, strokeWidth, and style.
+ */
+export function resolveEdgeVisuals(
+  edges: GraphEdge[],
+  encoding: GraphEncoding,
+  theme: ResolvedTheme,
+): CompiledGraphEdge[] {
+  // Edge width scale
+  let widthScale: ((v: number) => number) | undefined;
+  if (encoding.edgeWidth?.field) {
+    const field = encoding.edgeWidth.field;
+    const values = edges.map((e) => Number(e[field])).filter((v) => Number.isFinite(v));
+
+    const widthMin = min(values) ?? 0;
+    const widthMax = max(values) ?? 1;
+
+    widthScale = scaleLinear().domain([widthMin, widthMax]).range([MIN_EDGE_WIDTH, MAX_EDGE_WIDTH]);
+  }
+
+  // Edge color scale
+  let edgeColorFn: ((edge: GraphEdge) => string) | undefined;
+  if (encoding.edgeColor?.field) {
+    const field = encoding.edgeColor.field;
+    const fieldType = encoding.edgeColor.type ?? 'nominal';
+
+    if (fieldType === 'quantitative') {
+      const values = edges.map((e) => Number(e[field])).filter((v) => Number.isFinite(v));
+      const colorMin = min(values) ?? 0;
+      const colorMax = max(values) ?? 1;
+
+      const seqPalettes = Object.values(theme.colors.sequential);
+      const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
+      const colorScale = scaleLinear<string>()
+        .domain([colorMin, colorMax])
+        .range([palette[0], palette[palette.length - 1]]);
+
+      edgeColorFn = (edge: GraphEdge) => {
+        const val = Number(edge[field]);
+        return Number.isFinite(val) ? colorScale(val) : hexWithOpacity(theme.colors.axis, 0.4);
+      };
+    } else {
+      const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? '')))];
+      const ordinalScale = scaleOrdinal<string>()
+        .domain(uniqueValues)
+        .range(theme.colors.categorical);
+
+      edgeColorFn = (edge: GraphEdge) => ordinalScale(String(edge[field] ?? ''));
+    }
+  }
+
+  const defaultEdgeColor = hexWithOpacity(theme.colors.axis, 0.4);
+
+  return edges.map((edge) => {
+    const { source, target, ...rest } = edge;
+
+    let strokeWidth = DEFAULT_EDGE_WIDTH;
+    if (widthScale && encoding.edgeWidth?.field) {
+      const val = Number(edge[encoding.edgeWidth.field]);
+      if (Number.isFinite(val)) {
+        strokeWidth = widthScale(val);
+      }
+    }
+
+    const stroke = edgeColorFn ? edgeColorFn(edge) : defaultEdgeColor;
+
+    return {
+      source,
+      target,
+      stroke,
+      strokeWidth,
+      style: 'solid' as const,
+      data: { source, target, ...rest } as Record<string, unknown>,
+    };
+  });
+}

package/src/graphs/types.ts

@@ -0,0 +1,98 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @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 { compileChart, compileGraph, compileTable } from './compile';
+
+// ---------------------------------------------------------------------------
+// Graph compilation types
+// ---------------------------------------------------------------------------
+
+export type {
+  CompiledGraphEdge,
+  CompiledGraphNode,
+  GraphCompilation,
+  SimulationConfig,
+} from './graphs/types';
+
+// ---------------------------------------------------------------------------
+// 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';
+
+// ---------------------------------------------------------------------------
+// Re-export core types for convenience
+// ---------------------------------------------------------------------------
+
+export type {
+  ChartLayout,
+  ChartSpec,
+  CompileOptions,
+  CompileTableOptions,
+  GraphLayout,
+  GraphSpec,
+  TableLayout,
+  TableSpec,
+  VizSpec,
+} from '@opendata-ai/openchart-core';

package/src/layout/axes.ts

@@ -0,0 +1,194 @@
+/**
+ * Axis computation: tick positions, labels, and axis lines.
+ *
+ * Generates ticks manually (no d3-axis) so we have full control over
+ * responsive tick density and formatting.
+ */
+
+import type {
+  AxisLabelDensity,
+  AxisLayout,
+  AxisTick,
+  Gridline,
+  LayoutStrategy,
+  Rect,
+  ResolvedTheme,
+  TextStyle,
+} from '@opendata-ai/openchart-core';
+import { abbreviateNumber, formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import type { ScaleBand } from 'd3-scale';
+import type {
+  D3CategoricalScale,
+  D3ContinuousScale,
+  ResolvedScale,
+  ResolvedScales,
+} from './scales';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Base tick counts by axis label density. */
+const TICK_COUNTS: Record<AxisLabelDensity, number> = {
+  full: 8,
+  reduced: 5,
+  minimal: 3,
+};
+
+// ---------------------------------------------------------------------------
+// Tick generation
+// ---------------------------------------------------------------------------
+
+/** Generate ticks for a continuous scale (linear, time, log). */
+function continuousTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
+  const scale = resolvedScale.scale as D3ContinuousScale;
+  const count = resolvedScale.channel.axis?.tickCount ?? TICK_COUNTS[density];
+  const ticks: unknown[] = scale.ticks(count);
+
+  return ticks.map((value: unknown) => ({
+    value,
+    position: scale(value as number & Date) as number,
+    label: formatTickLabel(value, resolvedScale),
+  }));
+}
+
+/** Generate ticks for a band/point/ordinal scale. */
+function categoricalTicks(resolvedScale: ResolvedScale, density: AxisLabelDensity): AxisTick[] {
+  const scale = resolvedScale.scale as D3CategoricalScale;
+  const domain: string[] = scale.domain();
+  const maxTicks = TICK_COUNTS[density];
+
+  // Band scales (bar charts) should always show all category labels.
+  // Only thin point/ordinal scales used for continuous-like axes (e.g. line charts).
+  let selectedValues = domain;
+  if (resolvedScale.type !== 'band' && domain.length > maxTicks) {
+    const step = Math.ceil(domain.length / maxTicks);
+    selectedValues = domain.filter((_: string, i: number) => i % step === 0);
+  }
+
+  return selectedValues.map((value: string) => {
+    // Band scales: use the center of the band
+    const bandScale = resolvedScale.type === 'band' ? (scale as ScaleBand<string>) : null;
+    const pos = bandScale
+      ? (bandScale(value) ?? 0) + bandScale.bandwidth() / 2
+      : ((scale(value) as number | undefined) ?? 0);
+
+    return {
+      value,
+      position: pos,
+      label: value,
+    };
+  });
+}
+
+/** Format a tick value based on the scale type. */
+function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
+  const formatStr = resolvedScale.channel.axis?.format;
+
+  if (resolvedScale.type === 'time') {
+    if (formatStr) return String(value); // Custom format not implemented yet
+    return formatDate(value as Date);
+  }
+
+  if (resolvedScale.type === 'linear' || resolvedScale.type === 'log') {
+    const num = value as number;
+    if (formatStr) return formatNumber(num);
+    // Abbreviate large numbers for axis labels
+    if (Math.abs(num) >= 1000) return abbreviateNumber(num);
+    return formatNumber(num);
+  }
+
+  return String(value);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Output of computeAxes. */
+export interface AxesResult {
+  x?: AxisLayout;
+  y?: AxisLayout;
+}
+
+/**
+ * Compute axis layouts with tick positions, labels, and axis lines.
+ *
+ * @param scales - Resolved scales from computeScales.
+ * @param chartArea - The chart drawing area.
+ * @param strategy - Responsive layout strategy.
+ * @param theme - Resolved theme for styling.
+ */
+export function computeAxes(
+  scales: ResolvedScales,
+  chartArea: Rect,
+  strategy: LayoutStrategy,
+  theme: ResolvedTheme,
+): AxesResult {
+  const result: AxesResult = {};
+  const density = strategy.axisLabelDensity;
+
+  const tickLabelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: theme.fonts.sizes.axisTick,
+    fontWeight: theme.fonts.weights.normal,
+    fill: theme.colors.axis,
+    lineHeight: 1.2,
+    fontVariant: 'tabular-nums',
+  };
+
+  const axisLabelStyle: TextStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: theme.fonts.sizes.body,
+    fontWeight: theme.fonts.weights.medium,
+    fill: theme.colors.text,
+    lineHeight: 1.3,
+  };
+
+  if (scales.x) {
+    const ticks =
+      scales.x.type === 'band' || scales.x.type === 'point' || scales.x.type === 'ordinal'
+        ? categoricalTicks(scales.x, density)
+        : continuousTicks(scales.x, density);
+
+    const gridlines: Gridline[] = ticks.map((t) => ({
+      position: t.position,
+      major: true,
+    }));
+
+    result.x = {
+      ticks,
+      gridlines: scales.x.channel.axis?.grid ? gridlines : [],
+      label: scales.x.channel.axis?.label,
+      labelStyle: axisLabelStyle,
+      tickLabelStyle,
+      start: { x: chartArea.x, y: chartArea.y + chartArea.height },
+      end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
+    };
+  }
+
+  if (scales.y) {
+    const ticks =
+      scales.y.type === 'band' || scales.y.type === 'point' || scales.y.type === 'ordinal'
+        ? categoricalTicks(scales.y, density)
+        : continuousTicks(scales.y, density);
+
+    const gridlines: Gridline[] = ticks.map((t) => ({
+      position: t.position,
+      major: true,
+    }));
+
+    result.y = {
+      ticks,
+      // Y-axis gridlines are shown by default (standard editorial practice)
+      gridlines,
+      label: scales.y.channel.axis?.label,
+      labelStyle: axisLabelStyle,
+      tickLabelStyle,
+      start: { x: chartArea.x, y: chartArea.y },
+      end: { x: chartArea.x, y: chartArea.y + chartArea.height },
+    };
+  }
+
+  return result;
+}