@opendata-ai/openchart-engine 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, CompileTableOptions, TableLayout, ChartType, DataRow, Encoding, ChromeText, Annotation, LabelConfig, LegendConfig, ThemeConfig, DarkMode, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, VizSpec, EncodingChannel, Rect, LayoutStrategy, Mark } from '@opendata-ai/openchart-core';
+export { ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-core';
+import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScaleBand, ScalePoint, ScaleOrdinal } from 'd3-scale';
+
+/**
+ * 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.
+ */
+
+/** A compiled graph node with resolved visual properties (no x/y position). */
+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). */
+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. */
+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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function compileChart(spec: unknown, options: CompileOptions): ChartLayout;
+/**
+ * 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.
+ */
+declare function compileTable(spec: unknown, options: CompileTableOptions): TableLayout;
+/**
+ * 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.
+ */
+declare function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation;
+
+/** Chrome with all string values normalized to ChromeText objects. */
+interface NormalizedChrome {
+    title?: ChromeText;
+    subtitle?: ChromeText;
+    source?: ChromeText;
+    byline?: ChromeText;
+    footer?: ChromeText;
+}
+/** A ChartSpec with all optional fields filled with sensible defaults. */
+interface NormalizedChartSpec {
+    type: ChartType;
+    data: DataRow[];
+    encoding: Encoding;
+    chrome: NormalizedChrome;
+    annotations: Annotation[];
+    /** Normalized label configuration with defaults applied. density and format are always set; offsets stays optional. */
+    labels: Required<Pick<LabelConfig, 'density' | 'format'>> & Pick<LabelConfig, 'offsets'>;
+    /** Legend configuration (position override). */
+    legend?: LegendConfig;
+    responsive: boolean;
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+}
+/** A TableSpec with all optional fields filled with sensible defaults. */
+interface NormalizedTableSpec {
+    type: 'table';
+    data: DataRow[];
+    columns: ColumnConfig[];
+    rowKey?: string;
+    chrome: NormalizedChrome;
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    search: boolean;
+    pagination: boolean | {
+        pageSize: number;
+    };
+    stickyFirstColumn: boolean;
+    compact: boolean;
+    responsive: boolean;
+}
+/** A GraphSpec with all optional fields filled with sensible defaults. */
+interface NormalizedGraphSpec {
+    type: 'graph';
+    nodes: GraphSpec['nodes'];
+    edges: GraphSpec['edges'];
+    encoding: GraphEncoding;
+    layout: GraphLayoutConfig;
+    chrome: NormalizedChrome;
+    annotations: Annotation[];
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+}
+/** Discriminated union of all normalized spec types. */
+type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec;
+/** Machine-readable error code for programmatic handling. */
+type ValidationErrorCode = 'MISSING_FIELD' | 'INVALID_TYPE' | 'INVALID_VALUE' | 'ENCODING_MISMATCH' | 'DATA_FIELD_MISSING' | 'EMPTY_DATA';
+/** A single validation error with context. */
+interface ValidationError {
+    /** Error message describing what's wrong. */
+    message: string;
+    /** The path to the problematic value (e.g. "encoding.x.field"). */
+    path?: string;
+    /** Machine-readable error code for programmatic handling. */
+    code: ValidationErrorCode;
+    /** Actionable suggestion for fixing the error. */
+    suggestion: string;
+}
+/** Result of spec validation. */
+interface ValidationResult {
+    /** Whether the spec is valid. */
+    valid: boolean;
+    /** Validation errors (empty if valid). */
+    errors: ValidationError[];
+    /** The validated spec cast to VizSpec, or null if invalid. */
+    normalized: _opendata_ai_openchart_core.VizSpec | null;
+}
+/** Result of the compile pipeline (validate + normalize). */
+interface CompileResult {
+    /** The normalized spec with all defaults applied. */
+    spec: NormalizedSpec;
+    /** Non-fatal warnings (e.g. type mismatches that were auto-corrected). */
+    warnings: string[];
+}
+
+/**
+ * Spec normalization: fill in defaults and infer types.
+ *
+ * Takes a validated VizSpec and produces a NormalizedSpec where:
+ * - All optional fields have sensible defaults
+ * - Chrome strings are converted to ChromeText objects
+ * - Encoding types are inferred from data if not specified
+ * - Annotations have default styles
+ */
+
+/**
+ * Normalize a validated VizSpec, filling in all defaults.
+ *
+ * @param spec - A validated VizSpec (must pass validateSpec first).
+ * @param warnings - Mutable array to collect non-fatal warnings.
+ * @returns A NormalizedSpec with all optionals filled.
+ */
+declare function normalizeSpec(spec: VizSpec, warnings?: string[]): NormalizedSpec;
+
+/**
+ * Runtime spec validation.
+ *
+ * TypeScript catches compile-time errors for specs written in code.
+ * This module catches runtime errors for specs coming from JSON, APIs,
+ * or Claude-generated output where the TypeScript compiler can't help.
+ *
+ * Every error includes a machine-readable code and an actionable suggestion
+ * so consumers (and LLMs) can fix issues programmatically.
+ */
+
+/**
+ * Validate a spec at runtime.
+ *
+ * Checks structure, required fields, encoding rules, data shape, and
+ * field type compatibility. Returns structured errors with machine-readable
+ * codes and actionable suggestions for each problem found.
+ */
+declare function validateSpec(spec: unknown): ValidationResult;
+
+/**
+ * Spec compiler: validate -> normalize pipeline.
+ *
+ * This is the first stage of the engine: take raw user input (possibly JSON
+ * from an API or Claude), validate it, fill in defaults, and produce a
+ * NormalizedSpec that the rest of the engine can work with safely.
+ */
+
+/**
+ * Compile a raw spec through the validate -> normalize pipeline.
+ *
+ * @param spec - Raw spec input (unknown type, could be anything).
+ * @returns CompileResult with the normalized spec and any warnings.
+ * @throws Error if the spec is invalid.
+ */
+declare function compile(spec: unknown): CompileResult;
+
+/**
+ * Scale computation from encoding spec + data.
+ *
+ * Creates D3 scales that map data values to pixel positions.
+ * Temporal -> scaleTime(), quantitative -> scaleLinear(),
+ * nominal/ordinal -> scaleBand() or scaleOrdinal(), depending on context.
+ */
+
+/** Continuous D3 scales (linear, time, log) that support .ticks() and .nice(). */
+type D3ContinuousScale = ScaleLinear<number, number> | ScaleTime<number, number> | ScaleLogarithmic<number, number>;
+/** Categorical D3 scales (band, point, ordinal) that support .domain() as string[]. */
+type D3CategoricalScale = ScaleBand<string> | ScalePoint<string> | ScaleOrdinal<string, string>;
+/** Union of all D3 scale types used by the engine. */
+type D3Scale = D3ContinuousScale | D3CategoricalScale;
+/**
+ * A resolved scale wrapping a d3 scale with type metadata.
+ * We need to carry the scale type around so axes and marks know
+ * how to interpret the domain/range. Consumers use the `type` discriminant
+ * to determine which D3 methods are available on the scale.
+ */
+interface ResolvedScale {
+    /** The d3 scale function. Maps domain value -> pixel position or color. */
+    scale: D3Scale;
+    /** The scale type for downstream use. */
+    type: 'linear' | 'time' | 'band' | 'ordinal' | 'point' | 'log' | 'sequential';
+    /** The encoding channel this scale was derived from. */
+    channel: EncodingChannel;
+}
+/** All resolved scales for a chart. */
+interface ResolvedScales {
+    x?: ResolvedScale;
+    y?: ResolvedScale;
+    color?: ResolvedScale;
+    size?: ResolvedScale;
+    /** Default color for single-series charts (first categorical palette color). */
+    defaultColor?: string;
+}
+
+/**
+ * Chart renderer registry.
+ *
+ * Each chart type (line, bar, column, scatter, pie, donut, dot) registers
+ * a renderer that produces marks from normalized specs and resolved scales.
+ * The registry pattern decouples chart-type logic from the compile pipeline.
+ */
+
+/**
+ * A chart renderer function.
+ *
+ * Takes a normalized spec, resolved scales, chart area, layout strategy,
+ * and the resolved theme for theme-aware styling (e.g. label colors).
+ * Returns an array of marks to render.
+ */
+type ChartRenderer = (spec: NormalizedChartSpec, scales: ResolvedScales, chartArea: Rect, strategy: LayoutStrategy, theme: ResolvedTheme) => Mark[];
+/**
+ * Register a chart renderer for a specific chart type.
+ *
+ * @param type - Chart type string (e.g. "line", "bar").
+ * @param renderer - The renderer function.
+ */
+declare function registerChartRenderer(type: string, renderer: ChartRenderer): void;
+/**
+ * Get the registered chart renderer for a type.
+ *
+ * @param type - Chart type string.
+ * @returns The renderer, or undefined if no renderer is registered.
+ */
+declare function getChartRenderer(type: string): ChartRenderer | undefined;
+/**
+ * Clear all registered renderers. Useful for testing.
+ */
+declare function clearRenderers(): void;
+
+export { type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, type GraphCompilation, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSpec, type NormalizedTableSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clearRenderers, compile, compileChart, compileGraph, compileTable, getChartRenderer, normalizeSpec, registerChartRenderer, validateSpec };