@opendata-ai/openchart-engine 3.0.0 → 6.1.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, NodeOverride, 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';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, LegendConfig, ThemeConfig, DarkMode, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, VizSpec, ScaleType, EncodingChannel, Rect, LayoutStrategy, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+export { ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, LayerSpec, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-core';
+import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
 /**
  * Graph compilation types.
@@ -129,6 +129,18 @@ interface GraphCompilation {
  * @throws Error if spec is invalid or not a chart type.
  */
 declare function compileChart(spec: unknown, options: CompileOptions): ChartLayout;
+/**
+ * Compile a LayerSpec into a single ChartLayout.
+ *
+ * Flattens nested layers, merges inherited data/encoding/transforms,
+ * compiles each leaf layer independently, unions scale domains (shared
+ * by default), and concatenates marks in layer order.
+ *
+ * @param spec - A LayerSpec with child layers.
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns A single ChartLayout with combined marks from all layers.
+ */
+declare function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLayout;
 /**
  * Compile a table spec into a TableLayout.
  *
@@ -166,7 +178,10 @@ interface NormalizedChrome {
 }
 /** A ChartSpec with all optional fields filled with sensible defaults. */
 interface NormalizedChartSpec {
-    type: ChartType;
+    /** Resolved mark type string (extracted from spec.mark). */
+    markType: MarkType;
+    /** Resolved mark definition with defaults filled in. */
+    markDef: MarkDef;
     data: DataRow[];
     encoding: Encoding;
     chrome: NormalizedChrome;
@@ -245,16 +260,6 @@ interface CompileResult {
     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.
  *
@@ -309,12 +314,16 @@ declare function compile(spec: unknown): CompileResult;
  * 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>;
+/** Continuous D3 scales (linear, time, log, pow, sqrt, symlog) that support .ticks() and .nice(). */
+type D3ContinuousScale = ScaleLinear<number, number> | ScaleTime<number, number> | ScaleLogarithmic<number, number> | ScalePower<number, number> | ScaleSymLog<number, number>;
+/** Discretizing D3 scales (quantile, quantize, threshold). */
+type D3DiscretizingScale = ScaleQuantile<number> | ScaleQuantize<number> | ScaleThreshold<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;
+type D3Scale = D3ContinuousScale | D3CategoricalScale | D3DiscretizingScale;
+/** All resolved scale type identifiers. */
+type ResolvedScaleType = ScaleType | 'sequential';
 /**
  * A resolved scale wrapping a d3 scale with type metadata.
  * We need to carry the scale type around so axes and marks know
@@ -325,7 +334,7 @@ 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';
+    type: ResolvedScaleType;
     /** The encoding channel this scale was derived from. */
     channel: EncodingChannel;
 }
@@ -374,4 +383,131 @@ declare function getChartRenderer(type: string): ChartRenderer | undefined;
  */
 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 };
+/**
+ * Bin transform: discretizes a continuous field into bins.
+ *
+ * Adds bin start (and optionally bin end) fields to each row.
+ */
+
+/**
+ * Apply a bin transform to data rows.
+ *
+ * Adds one or two fields to each row:
+ * - If `as` is a string: adds `as` with the bin start value.
+ * - If `as` is [start, end]: adds both bin start and bin end fields.
+ *
+ * @param data - Input rows.
+ * @param transform - Bin transform definition.
+ * @returns New rows with binned field(s) added.
+ */
+declare function runBin(data: DataRow[], transform: BinTransform): DataRow[];
+
+/**
+ * Calculate transform: adds a computed field to each row.
+ *
+ * Supports arithmetic operations on fields and constant values.
+ */
+
+/**
+ * Apply a calculate transform to data rows.
+ *
+ * Adds a new field with the computed value to each row.
+ *
+ * @param data - Input rows.
+ * @param transform - Calculate transform definition.
+ * @returns New rows with the calculated field added.
+ */
+declare function runCalculate(data: DataRow[], transform: CalculateTransform): DataRow[];
+
+/**
+ * Conditional encoding evaluation.
+ *
+ * Resolves conditional value definitions per-datum by evaluating
+ * predicates and returning the first matching condition's value.
+ */
+
+/**
+ * Resolve a conditional value definition for a datum.
+ *
+ * Evaluates conditions in order, returning the value from the first
+ * condition whose test passes. Falls back to the default value if
+ * no condition matches.
+ *
+ * @param datum - The data row to evaluate against.
+ * @param channelDef - The conditional value definition.
+ * @returns The resolved value, or undefined if no condition matches and no default.
+ */
+declare function resolveConditionalValue(datum: DataRow, channelDef: ConditionalValueDef): unknown;
+/**
+ * Check if a channel definition is a ConditionalValueDef.
+ */
+declare function isConditionalValueDef(def: unknown): def is ConditionalValueDef;
+
+/**
+ * Filter transform: removes rows that don't match a predicate.
+ */
+
+/**
+ * Filter data rows by a predicate.
+ *
+ * @param data - Input rows.
+ * @param predicate - Filter predicate to evaluate per row.
+ * @returns Rows that pass the predicate.
+ */
+declare function runFilter(data: DataRow[], predicate: FilterPredicate): DataRow[];
+
+/**
+ * Predicate evaluation for filter transforms and conditional encoding.
+ *
+ * Supports field predicates (equal, lt, gt, range, oneOf, valid)
+ * and logical combinators (and, or, not).
+ */
+
+/**
+ * Evaluate a filter predicate (field predicate or logical combinator) against a datum.
+ *
+ * @param datum - The data row to test.
+ * @param predicate - The filter predicate to evaluate.
+ * @returns Whether the datum passes the predicate.
+ */
+declare function evaluatePredicate(datum: DataRow, predicate: FilterPredicate): boolean;
+
+/**
+ * Time unit transform: extracts temporal components from date fields.
+ *
+ * Follows Vega-Lite time unit conventions.
+ */
+
+/**
+ * Apply a time unit transform to data rows.
+ *
+ * Parses the field as a date and extracts the specified time unit,
+ * storing the result in a new field.
+ *
+ * @param data - Input rows.
+ * @param transform - Time unit transform definition.
+ * @returns New rows with the time unit field added.
+ */
+declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): DataRow[];
+
+/**
+ * Data transform pipeline.
+ *
+ * Runs an ordered sequence of transforms (filter, bin, calculate, timeUnit)
+ * against a data array. Each transform produces a new array, feeding into
+ * the next transform in sequence.
+ */
+
+/**
+ * Run a sequence of transforms against a data array.
+ *
+ * Each transform is applied in order, producing a new data array
+ * that feeds into the next transform. The original data is not mutated.
+ *
+ * @param data - Input data rows.
+ * @param transforms - Ordered array of transform definitions.
+ * @returns Transformed data rows.
+ */
+declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
+
+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, compileLayer, compileTable, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };