@opendata-ai/openchart-engine 6.25.4 → 6.27.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
-import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, AnimationSpec, ResolvedAnimation, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, LegendConfig, ThemeConfig, DarkMode, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, 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, SankeyLayout, SankeySpec, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, AnimationSpec, ResolvedAnimation, TileMapEncoding, TileMapPalette, LegendConfig, ThemeConfig, DarkMode, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, 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, SankeyLayout, SankeySpec, TableLayout, TableSpec, TileMapLayout, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
 import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
 /**
@@ -169,6 +169,19 @@ declare function compileGraph(spec: unknown, options: CompileOptions): GraphComp
  * @throws Error if spec is invalid or not a sankey type.
  */
 declare function compileSankey(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.SankeyLayout;
+/**
+ * Compile a tilemap spec into a TileMapLayout.
+ *
+ * Takes a raw tilemap spec, validates, normalizes, resolves theme and chrome,
+ * computes tile positions, builds tile marks with colors and labels, and
+ * returns a TileMapLayout ready for rendering.
+ *
+ * @param spec - Raw tilemap spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns TileMapLayout with computed positions and visual properties.
+ * @throws Error if spec is invalid or not a tilemap type.
+ */
+declare function compileTileMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.TileMapLayout;
 
 /**
  * Animation resolver: normalizes AnimationSpec into fully resolved config.
@@ -189,6 +202,28 @@ declare function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnim
  */
 declare function clampStaggerDelay(delay: number, elementCount: number): number;
 
+/**
+ * Internal normalized tilemap spec type used by the compilation pipeline.
+ *
+ * This mirrors NormalizedSankeySpec: all optional fields have been filled
+ * with sensible defaults. It's an engine implementation detail, not a public contract.
+ */
+
+/** A TileMapSpec with all optional fields filled with defaults. */
+interface NormalizedTileMapSpec {
+    type: 'tilemap';
+    data: Record<string, unknown>[];
+    encoding: TileMapEncoding;
+    palette: TileMapPalette;
+    chrome: NormalizedChrome;
+    legend?: LegendConfig;
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    watermark: boolean;
+    animation?: AnimationSpec;
+    valueFormat?: string;
+}
+
 /** Chrome with all string values normalized to ChromeText objects. */
 interface NormalizedChrome {
     title?: ChromeText;
@@ -197,6 +232,34 @@ interface NormalizedChrome {
     byline?: ChromeText;
     footer?: ChromeText;
 }
+/**
+ * Tracks which top-level fields the user explicitly set in their input spec.
+ *
+ * Built from the raw expandedSpec (post-breakpoint-merge, pre-normalize) so
+ * that "user wrote chrome.title" vs "user wrote nothing" is distinguishable
+ * after normalization fills in defaults.
+ *
+ * Used by sparkline display mode to decide whether to suppress chrome/axes/
+ * legend/etc. by default vs. respecting an explicit user opt-in.
+ */
+interface UserExplicit {
+    /** True if user wrote `chrome` (any non-empty chrome). */
+    chrome: boolean;
+    /** True if user wrote `legend`. */
+    legend: boolean;
+    /** True if user wrote `encoding.x.axis`. */
+    xAxis: boolean;
+    /** True if user wrote `encoding.y.axis`. */
+    yAxis: boolean;
+    /** True if user wrote `labels`. */
+    labels: boolean;
+    /** True if user wrote `animation`. */
+    animation: boolean;
+    /** True if user wrote `watermark`. */
+    watermark: boolean;
+    /** True if user wrote `crosshair`. */
+    crosshair: boolean;
+}
 /** A ChartSpec with all optional fields filled with sensible defaults. */
 interface NormalizedChartSpec {
     /** Resolved mark type string (extracted from spec.mark). */
@@ -220,6 +283,14 @@ interface NormalizedChartSpec {
     hiddenSeries: string[];
     /** Per-series visual style overrides. */
     seriesStyles: Record<string, _opendata_ai_openchart_core.SeriesStyle>;
+    /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
+    display: Display;
+    /**
+     * Which top-level fields the user explicitly set. Populated by compileChart
+     * from the raw expanded spec before normalization. NormalizeChartSpec runs
+     * with a default-empty descriptor; compileChart overwrites it post-normalize.
+     */
+    userExplicit: UserExplicit;
 }
 /** A TableSpec with all optional fields filled with sensible defaults. */
 interface NormalizedTableSpec {
@@ -255,7 +326,7 @@ interface NormalizedGraphSpec {
     watermark: boolean;
 }
 /** Discriminated union of all normalized spec types. */
-type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec;
+type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec;
 /** 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. */
@@ -499,11 +570,18 @@ declare function isConditionalValueDef(def: unknown): def is ConditionalValueDef
 
 /**
  * Filter transform: removes rows that don't match a predicate.
+ *
+ * Supports RelativeTimeRef values on comparison properties (lt, lte, gt, gte, range).
+ * These are resolved against the data extent before filtering.
  */
 
 /**
  * Filter data rows by a predicate.
  *
+ * If the predicate contains RelativeTimeRef values, they are resolved
+ * against the data extent first, then the standard evaluatePredicate
+ * logic runs per-row.
+ *
  * @param data - Input rows.
  * @param predicate - Filter predicate to evaluate per row.
  * @returns Rows that pass the predicate.
@@ -564,4 +642,4 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 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 NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clampStaggerDelay, clearRenderers, compile, compileChart, compileGraph, compileLayer, compileSankey, compileTable, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };
+export { type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, type GraphCompilation, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clampStaggerDelay, clearRenderers, compile, compileChart, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };