@timeplus/vistral 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,999 @@
+import * as React from 'react';
+import React__default from 'react';
+import { Chart, MarkNode } from '@antv/g2';
+
+/**
+ * VistralSpec — declarative grammar types for streaming visualizations.
+ *
+ * These types define a renderer-agnostic specification that can be compiled
+ * down to AntV G2 options (or other backends in the future).
+ */
+/** Accessor function for computed encodings. */
+type EncodeFn = (datum: Record<string, unknown>) => unknown;
+/** Default maximum number of data items kept in memory for streaming charts. */
+declare const DEFAULT_MAX_ITEMS = 1000;
+/** Streaming data management configuration. */
+interface StreamingSpec {
+    /** Maximum number of data items to keep in memory. Default: DEFAULT_MAX_ITEMS (1000) */
+    maxItems?: number;
+    /** How incoming data is merged with existing data. Default: 'append' */
+    mode?: 'append' | 'replace';
+    /** Minimum interval (ms) between render updates. Default: 0 */
+    throttle?: number;
+}
+/** Temporal bounding — controls how time-windowed data is managed. */
+interface TemporalSpec {
+    /** Temporal binding mode. */
+    mode: 'axis' | 'frame' | 'key';
+    /** Field used for temporal binding. */
+    field: string | string[];
+    /** Time range in minutes (axis-mode only). */
+    range?: number | 'Infinity';
+    /** Key field for de-duplication (key-mode only). */
+    keyField?: string;
+}
+/** Encoding channels map visual properties to data fields or accessor fns. */
+interface EncodeSpec {
+    x?: string | EncodeFn;
+    y?: string | EncodeFn;
+    color?: string | EncodeFn;
+    size?: string | EncodeFn;
+    shape?: string | EncodeFn;
+    opacity?: string | EncodeFn;
+    series?: string | EncodeFn;
+    /** Additional custom channels. */
+    [channel: string]: string | EncodeFn | undefined;
+}
+/** Scale configuration for a single encoding channel. */
+interface ScaleSpec {
+    type?: string;
+    domain?: unknown[];
+    range?: unknown[];
+    nice?: boolean;
+    clamp?: boolean;
+    padding?: number;
+    /** Date/time format mask. */
+    mask?: string;
+    [option: string]: unknown;
+}
+/** Data or visual transform applied before rendering. */
+interface TransformSpec {
+    type: string;
+    [option: string]: unknown;
+}
+/** Coordinate system configuration. */
+interface CoordinateSpec {
+    type?: string;
+    transforms?: Array<{
+        type: string;
+        [option: string]: unknown;
+    }>;
+    [option: string]: unknown;
+}
+/** Visual style properties for marks, labels, and annotations. */
+interface StyleSpec {
+    fill?: string;
+    stroke?: string;
+    lineWidth?: number;
+    opacity?: number;
+    shape?: string;
+    [property: string]: unknown;
+}
+/** Label configuration for a mark. */
+interface LabelSpec {
+    text?: string | EncodeFn;
+    format?: string | ((value: unknown) => string);
+    overlapHide?: boolean;
+    selector?: string;
+    style?: StyleSpec;
+    [option: string]: unknown;
+}
+/** Tooltip configuration scoped to a single mark. */
+interface MarkTooltipSpec {
+    title?: string | ((datum: Record<string, unknown>) => string);
+    items?: TooltipItemSpec[];
+}
+/** A single mark (geometric element) in the visualization. */
+interface MarkSpec {
+    type: string;
+    encode?: EncodeSpec;
+    scales?: Record<string, ScaleSpec>;
+    transforms?: TransformSpec[];
+    style?: StyleSpec;
+    labels?: LabelSpec[];
+    tooltip?: MarkTooltipSpec | false;
+    animate?: boolean;
+}
+/** Label formatting options for an axis. */
+interface AxisLabelSpec {
+    format?: string | ((value: unknown) => string);
+    maxLength?: number;
+    rotate?: number;
+}
+/** Configuration for a single axis channel. */
+interface AxisChannelSpec {
+    title?: string | false;
+    grid?: boolean;
+    line?: boolean;
+    labels?: AxisLabelSpec;
+}
+/** Axis configuration for x and y channels. */
+interface AxesSpec {
+    x?: AxisChannelSpec | false;
+    y?: AxisChannelSpec | false;
+}
+/** Legend configuration. */
+interface LegendSpec {
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    interactive?: boolean;
+}
+/** A single item within a tooltip. */
+interface TooltipItemSpec {
+    field: string;
+    name?: string;
+    format?: (value: unknown) => string;
+}
+/** Top-level tooltip configuration. */
+interface TooltipSpec {
+    title?: string | ((datum: Record<string, unknown>) => string);
+    items?: TooltipItemSpec[];
+}
+/** A reference mark / annotation overlaid on the chart. */
+interface AnnotationSpec {
+    type: string;
+    value?: unknown;
+    style?: StyleSpec;
+    label?: string;
+    encode?: EncodeSpec;
+}
+/** An interaction behaviour attached to the chart. */
+interface InteractionSpec {
+    type: string;
+    [option: string]: unknown;
+}
+/**
+ * VistralSpec — the top-level declarative specification for a streaming
+ * visualization. This is the single object a user hands to the library.
+ */
+interface VistralSpec {
+    /** Streaming data management. */
+    streaming?: StreamingSpec;
+    /** Temporal bounding configuration. */
+    temporal?: TemporalSpec;
+    /** One or more marks (geometric elements) to render. */
+    marks: MarkSpec[];
+    /** Shared scale definitions (keyed by channel name). */
+    scales?: Record<string, ScaleSpec>;
+    /** Data transforms applied before mark-level transforms. */
+    transforms?: TransformSpec[];
+    /** Coordinate system. */
+    coordinate?: CoordinateSpec;
+    /** Axis configuration. */
+    axes?: AxesSpec;
+    /** Legend configuration, or false to disable. */
+    legend?: LegendSpec | false;
+    /** Tooltip configuration, or false to disable. */
+    tooltip?: TooltipSpec | false;
+    /** Theme name. */
+    theme?: 'dark' | 'light';
+    /** Annotations overlaid on the chart. */
+    annotations?: AnnotationSpec[];
+    /** Interaction behaviours. */
+    interactions?: InteractionSpec[];
+    /** Enable/disable animation globally. */
+    animate?: boolean;
+}
+
+/**
+ * Core types for the stream visualization library
+ */
+type ColumnType = 'string' | 'number' | 'datetime' | 'boolean' | 'array' | 'object' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'float32' | 'float64' | 'datetime64';
+interface ColumnDefinition {
+    name: string;
+    type: ColumnType | string;
+    nullable?: boolean;
+}
+type DataRow = Record<string, unknown> | unknown[];
+interface StreamDataSource {
+    /** Column definitions/schema */
+    columns: ColumnDefinition[];
+    /** Data rows */
+    data: DataRow[];
+    /** Whether the data is streaming (continuously updated) */
+    isStreaming?: boolean;
+}
+type TemporalMode = 'axis' | 'frame' | 'key';
+interface TemporalConfig {
+    /** Temporal binding mode */
+    mode: TemporalMode;
+    /** Field used for temporal binding */
+    field: string | string[];
+    /** Time range in minutes (for axis mode only) */
+    range?: number | 'Infinity';
+}
+interface ChartConfigBase {
+    /** Chart type identifier */
+    chartType: string;
+    /** Custom color palette */
+    colors?: string[];
+    /** Temporal binding configuration */
+    temporal?: TemporalConfig;
+    /** Maximum number of data items to keep for streaming. Defaults to DEFAULT_MAX_ITEMS (1000). */
+    maxItems?: number;
+}
+interface TimeSeriesConfig extends ChartConfigBase {
+    chartType: 'line' | 'area';
+    /** X-axis field (time field) */
+    xAxis: string;
+    /** Y-axis field (numeric field) */
+    yAxis: string;
+    /** Color/series grouping field */
+    color?: string;
+    /** X-axis title */
+    xTitle?: string;
+    /** Y-axis title */
+    yTitle?: string;
+    /** Y-axis range */
+    yRange?: {
+        min?: number | null;
+        max?: number | null;
+    };
+    /** Show data labels */
+    dataLabel?: boolean;
+    /** Show all labels or just last */
+    showAll?: boolean;
+    /** Show legend */
+    legend?: boolean;
+    /** Show gridlines */
+    gridlines?: boolean;
+    /** Show data points */
+    points?: boolean;
+    /** Line style */
+    lineStyle?: 'curve' | 'straight';
+    /** Decimal places */
+    fractionDigits?: number;
+    /** Unit configuration */
+    unit?: {
+        position: 'left' | 'right';
+        value: string;
+    };
+    /** X-axis format mask */
+    xFormat?: string;
+    /** Y-axis tick label max characters */
+    yTickLabel?: {
+        maxChar: number;
+    };
+}
+interface BarColumnConfig extends ChartConfigBase {
+    chartType: 'bar' | 'column';
+    /** X-axis field */
+    xAxis: string;
+    /** Y-axis field */
+    yAxis: string;
+    /** Color/grouping field */
+    color?: string;
+    /** Group type for multi-series */
+    groupType?: 'stack' | 'dodge';
+    /** X-axis title */
+    xTitle?: string;
+    /** Y-axis title */
+    yTitle?: string;
+    /** Show data labels */
+    dataLabel?: boolean;
+    /** Show legend */
+    legend?: boolean;
+    /** Show gridlines */
+    gridlines?: boolean;
+    /** Decimal places */
+    fractionDigits?: number;
+    /** Unit configuration */
+    unit?: {
+        position: 'left' | 'right';
+        value: string;
+    };
+    /** X-axis tick label max characters */
+    xTickLabel?: {
+        maxChar: number;
+    };
+    /** Y-axis tick label max characters */
+    yTickLabel?: {
+        maxChar: number;
+    };
+}
+interface SingleValueConfig extends ChartConfigBase {
+    chartType: 'singleValue';
+    /** Value field */
+    yAxis: string;
+    /** Font size */
+    fontSize?: number;
+    /** Value color */
+    color?: string;
+    /** Decimal places */
+    fractionDigits?: number;
+    /** Show sparkline */
+    sparkline?: boolean;
+    /** Sparkline color */
+    sparklineColor?: string;
+    /** Show delta/change indicator */
+    delta?: boolean;
+    /** Color for positive changes */
+    increaseColor?: string;
+    /** Color for negative changes */
+    decreaseColor?: string;
+    /** Unit configuration */
+    unit?: {
+        position: 'left' | 'right';
+        value: string;
+    };
+}
+interface TableConfig extends ChartConfigBase {
+    chartType: 'table';
+    /** Column styles and visibility */
+    tableStyles?: Record<string, {
+        name?: string;
+        show?: boolean;
+        width?: number;
+        miniChart?: 'none' | 'sparkline';
+        color?: {
+            type: 'none' | 'scale' | 'condition';
+            colorScale?: string;
+            conditions?: Array<{
+                operator: 'gt' | 'lt' | 'eq' | 'gte' | 'lte';
+                value: number;
+                color: string;
+            }>;
+        };
+    }>;
+    /** Enable text wrapping */
+    tableWrap?: boolean;
+}
+interface OHLCConfig extends ChartConfigBase {
+    chartType: 'ohlc' | 'candlestick';
+    /** Time field */
+    time: string;
+    /** Open price field */
+    open: string;
+    /** High price field */
+    high: string;
+    /** Low price field */
+    low: string;
+    /** Close price field */
+    close: string;
+    /** Bullish candle color */
+    bullishColor?: string;
+    /** Bearish candle color */
+    bearishColor?: string;
+}
+interface GeoChartConfig extends ChartConfigBase {
+    chartType: 'geo';
+    /** Longitude field name */
+    longitude: string;
+    /** Latitude field name */
+    latitude: string;
+    /** Color field for point coloring */
+    color?: string;
+    /** Size configuration for points */
+    size?: {
+        key?: string;
+        min?: number;
+        max?: number;
+    };
+    /** Initial map center [lat, lng] */
+    center?: [number, number];
+    /** Initial zoom level (1-18) */
+    zoom?: number;
+    /** Map tile provider */
+    tileProvider?: 'openstreetmap' | 'cartodb-dark' | 'cartodb-light';
+    /** Show zoom controls */
+    showZoomControl?: boolean;
+    /** Show center coordinates */
+    showCenterDisplay?: boolean;
+    /** Point opacity (0-1) */
+    pointOpacity?: number;
+    /** Default point color */
+    pointColor?: string;
+}
+type ChartConfig = TimeSeriesConfig | BarColumnConfig | SingleValueConfig | TableConfig | OHLCConfig | GeoChartConfig;
+interface ColorPalette {
+    label: string;
+    values: string[];
+    keyColor: number;
+    keyColorValue: string;
+}
+interface ColumnStatistics {
+    min?: number | {
+        value: number;
+    };
+    max?: number | {
+        value: number;
+    };
+    categories?: Record<string, number>;
+    count?: number;
+}
+interface ProcessedDataSource {
+    data: DataRow[];
+    header: ColumnDefinition[];
+    x: {
+        index: number;
+        values?: string[];
+        isTime?: boolean;
+        offset?: number;
+        min?: number;
+        max?: number;
+    };
+    y: {
+        index: number;
+        min?: number;
+        max?: number;
+    };
+    z: {
+        index: number;
+        values: string[];
+    };
+    xTransform: (value: unknown) => unknown;
+}
+
+/**
+ * Single Value Chart Component
+ * Displays a single metric with optional sparkline and delta indicator
+ */
+
+interface SingleValueChartProps {
+    /** Chart configuration */
+    config: SingleValueConfig;
+    /** Data source */
+    data: StreamDataSource;
+    /** Theme */
+    theme?: 'dark' | 'light';
+    /** Container className */
+    className?: string;
+    /** Container style */
+    style?: React__default.CSSProperties;
+}
+/**
+ * Get default configuration for single value chart
+ */
+declare function getSingleValueDefaults(columns: {
+    name: string;
+    type: string;
+}[]): Partial<SingleValueConfig> | null;
+/**
+ * Single Value Chart Component
+ */
+declare const SingleValueChart: React__default.FC<SingleValueChartProps>;
+
+/**
+ * Streaming Data Table Component
+ * Displays tabular data with streaming update support
+ */
+
+interface DataTableProps {
+    /** Chart configuration */
+    config: TableConfig;
+    /** Data source */
+    data: StreamDataSource;
+    /** Theme */
+    theme?: 'dark' | 'light';
+    /** Container className */
+    className?: string;
+    /** Container style */
+    style?: React__default.CSSProperties;
+    /** Callback when configuration changes (e.g., column resize) */
+    onConfigChange?: (config: TableConfig) => void;
+    /** Max rows to display */
+    maxRows?: number;
+}
+/**
+ * Get default table configuration
+ */
+declare function getTableDefaults(columns: {
+    name: string;
+    type: string;
+}[]): Partial<TableConfig>;
+/**
+ * Streaming Data Table Component
+ */
+declare const DataTable: React__default.FC<DataTableProps>;
+
+/**
+ * Geo Chart Component
+ * Displays geographic points on a map with streaming support
+ */
+
+interface GeoChartProps {
+    /** Chart configuration */
+    config: GeoChartConfig;
+    /** Data source */
+    data: StreamDataSource;
+    /** Theme */
+    theme?: 'dark' | 'light';
+    /** Container className */
+    className?: string;
+    /** Container style */
+    style?: React__default.CSSProperties;
+    /** Maximum data points for streaming. Defaults to config.maxItems or DEFAULT_MAX_ITEMS. */
+    maxItems?: number;
+}
+/**
+ * Get default configuration for geo chart
+ */
+declare function getGeoChartDefaults(columns: ColumnDefinition[]): Partial<GeoChartConfig> | null;
+/**
+ * GeoChart Component
+ */
+declare const GeoChart: React__default.FC<GeoChartProps>;
+
+/**
+ * StreamChart - Universal Streaming Chart Component
+ * Automatically renders the appropriate chart based on configuration
+ */
+
+interface StreamChartProps {
+    /** Chart configuration */
+    config: ChartConfig;
+    /** Data source with columns and data */
+    data: StreamDataSource;
+    /** Color theme */
+    theme?: 'dark' | 'light';
+    /** Show data table instead of chart */
+    showTable?: boolean;
+    /** Container className */
+    className?: string;
+    /** Container style */
+    style?: React__default.CSSProperties;
+    /** Callback when configuration changes */
+    onConfigChange?: (config: ChartConfig) => void;
+}
+/**
+ * StreamChart Component
+ *
+ * Universal chart component for streaming data visualization.
+ * Automatically renders the appropriate chart based on the config.chartType property.
+ *
+ * @example
+ * ```tsx
+ * <StreamChart
+ *   config={{
+ *     chartType: 'line',
+ *     xAxis: 'timestamp',
+ *     yAxis: 'value',
+ *     legend: true,
+ *   }}
+ *   data={{
+ *     columns: [
+ *       { name: 'timestamp', type: 'datetime64' },
+ *       { name: 'value', type: 'float64' },
+ *     ],
+ *     data: [...],
+ *   }}
+ *   theme="dark"
+ * />
+ * ```
+ */
+declare const StreamChart: React__default.FC<StreamChartProps>;
+
+/**
+ * VistralChart — a React component that renders any VistralSpec using the
+ * Spec Engine and AntV G2.
+ *
+ * It accepts a declarative `VistralSpec` and an optional `StreamDataSource`,
+ * normalises the data, translates the spec to G2 options via `buildG2Options`,
+ * and manages the full G2 chart lifecycle (create / update / destroy).
+ *
+ * Streaming is supported through the imperative `ChartHandle` exposed via
+ * `React.forwardRef` — callers can `append`, `replace`, or `clear` data at
+ * any time.
+ */
+
+/** Imperative handle exposed via `ref` on `<VistralChart>`. */
+interface ChartHandle {
+    /** Append rows to the internal data buffer and re-render. */
+    append: (rows: unknown[][] | Record<string, unknown>[]) => void;
+    /** Replace the entire data buffer and re-render. */
+    replace: (rows: unknown[][] | Record<string, unknown>[]) => void;
+    /** Clear the data buffer and re-render. */
+    clear: () => void;
+    /** Direct access to the underlying G2 Chart instance (or null). */
+    g2: Chart | null;
+}
+/** Props accepted by `<VistralChart>`. */
+interface VistralChartProps {
+    /** The declarative spec describing what to render. */
+    spec: VistralSpec;
+    /** Optional initial / declarative data source. */
+    source?: StreamDataSource;
+    /** Explicit pixel width (defaults to 100 % of container). */
+    width?: number;
+    /** Explicit pixel height (defaults to 100 % of container). */
+    height?: number;
+    /** Additional CSS class for the wrapper div. */
+    className?: string;
+    /** Additional inline styles for the wrapper div. */
+    style?: React__default.CSSProperties;
+    /** Called once the chart is ready with its imperative handle. */
+    onReady?: (handle: ChartHandle) => void;
+}
+/**
+ * `VistralChart` renders a VistralSpec declaratively. It manages the G2
+ * chart lifecycle and exposes an imperative `ChartHandle` via ref for
+ * streaming updates.
+ */
+declare const VistralChart: React__default.ForwardRefExoticComponent<VistralChartProps & React__default.RefAttributes<ChartHandle>>;
+
+/**
+ * Color palettes for stream visualization
+ */
+
+declare const singleColorPalettes: ColorPalette[];
+declare const multiColorPalettes: ColorPalette[];
+declare const allPalettes: ColorPalette[];
+declare const DEFAULT_PALETTE: ColorPalette;
+/**
+ * Find a color palette by its values array
+ */
+declare function findPaletteByValues(values: string[], defaultPalette?: ColorPalette): ColorPalette;
+/**
+ * Find a color palette by label
+ */
+declare function findPaletteByLabel(label: string, defaultPalette?: ColorPalette): ColorPalette;
+/**
+ * Get the key color from a palette with optional opacity
+ */
+declare function getPaletteKeyColor(label: string, opacity?: number): string;
+/**
+ * Generate colors for a given number of series from a palette
+ */
+declare function getSeriesColors(palette: ColorPalette, count: number): string[];
+interface ChartTheme {
+    backgroundColor: string;
+    textColor: string;
+    gridColor: string;
+    axisColor: string;
+    tooltipBackground: string;
+    tooltipTextColor: string;
+    fontFamily: string;
+}
+declare const darkTheme: ChartTheme;
+declare const lightTheme: ChartTheme;
+type ThemeName = 'dark' | 'light';
+declare function getTheme(name: ThemeName): ChartTheme;
+
+/**
+ * Hook to manage AntV G2 chart instance
+ */
+declare function useChart(options?: {
+    height?: number;
+    padding?: number;
+}): {
+    chart: Chart | null;
+    chartRef: React.RefObject<HTMLDivElement>;
+    isMouseOver: boolean;
+    activeColor: number;
+    setActiveColor: React.Dispatch<React.SetStateAction<number>>;
+};
+/**
+ * Hook to process streaming data source
+ */
+declare function useDataSource(source: StreamDataSource | null, xKey: string, yKey: string, zKey?: string): ProcessedDataSource | null;
+/**
+ * Hook to track streaming data updates
+ */
+declare function useStreamingData<T>(initialData: T[], maxItems?: number): {
+    data: T[];
+    append: (items: T | T[]) => void;
+    replace: (items: T[]) => void;
+    clear: () => void;
+};
+/**
+ * Hook to handle resize detection
+ */
+declare function useResizeObserver(callback: (entry: ResizeObserverEntry) => void): React.RefObject<HTMLDivElement>;
+/**
+ * Hook to manage chart theme
+ */
+declare function useChartTheme(theme?: 'dark' | 'light'): {
+    theme: "dark" | "light";
+    setTheme: React.Dispatch<React.SetStateAction<"dark" | "light">>;
+    toggleTheme: () => void;
+    isDark: boolean;
+};
+/**
+ * Hook to track last update time
+ */
+declare function useLastUpdated(data: unknown[]): Date | null;
+/**
+ * Hook for sparkline data management
+ */
+declare function useSparklineData(value: number | null, limit?: number): {
+    data: {
+        value: number;
+    }[];
+    trend: 'up' | 'down' | 'stable';
+};
+/**
+ * Hook to manage chart animation state
+ */
+declare function useChartAnimation(enabled?: boolean): {
+    isAnimating: boolean;
+    startAnimation: () => void;
+    stopAnimation: () => void;
+    animationEnabled: boolean;
+};
+/**
+ * Hook to debounce a value
+ */
+declare function useDebouncedValue<T>(value: T, delay?: number): T;
+/**
+ * Hook to track previous value
+ */
+declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * Hook to determine default chart configuration based on data schema
+ */
+declare function useAutoConfig(columns: {
+    name: string;
+    type: string;
+}[]): () => {
+    suggestedXAxis: string;
+    suggestedYAxis: string;
+    suggestedColor: string;
+    hasTimeSeries: boolean;
+    hasCategorical: boolean;
+};
+
+/**
+ * Utility functions for stream visualization
+ */
+
+/**
+ * Check if a column type is numeric
+ */
+declare function isNumericColumn(type: string): boolean;
+/**
+ * Check if a column type is datetime
+ */
+declare function isDateTimeColumn(type: string): boolean;
+/**
+ * Check if a column type is string
+ */
+declare function isStringColumn(type: string): boolean;
+/**
+ * Check if a column type is boolean
+ */
+declare function isBooleanColumn(type: string): boolean;
+/**
+ * Determine automatic time format mask based on domain range
+ */
+declare function getTimeMask(domainMin: number | Date, domainMax: number | Date): string;
+/**
+ * Clamp a number between min and max values
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Truncate a string with ellipsis if too long
+ */
+declare function truncateWithEllipsis(str: string, maxLength: number): string;
+/**
+ * Format a number with locale formatting
+ */
+declare function formatNumber(num: number, digits?: number): string;
+/**
+ * Format a large number with abbreviation (k, m, b, t)
+ */
+declare function abbreviateNumber(num: number, decPlaces?: number): string;
+/**
+ * Format duration from milliseconds to human readable
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Format bytes to human readable size
+ */
+declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * Debounce function execution
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Get value from a data row by column index or name
+ */
+declare function getRowValue(row: DataRow, column: number | string): unknown;
+/**
+ * Convert a row to array format if it's an object
+ */
+declare function rowToArray(row: DataRow, columns: ColumnDefinition[]): unknown[];
+/**
+ * Find column index by name
+ */
+declare function findColumnIndex(columns: ColumnDefinition[], name: string): number;
+/**
+ * Get filtered columns by type
+ */
+declare function getColumnsByType(columns: ColumnDefinition[], filter: 'numeric' | 'datetime' | 'string' | 'boolean' | 'all'): ColumnDefinition[];
+/**
+ * Calculate statistics for a numeric column
+ */
+declare function calculateColumnStats(data: DataRow[], columnIndex: number): {
+    min: number;
+    max: number;
+    sum: number;
+    count: number;
+    avg: number;
+};
+/**
+ * Get unique values for a column (for categorical data)
+ */
+declare function getUniqueValues(data: DataRow[], columnIndex: number): string[];
+/**
+ * Parse datetime value to timestamp
+ */
+declare function parseDateTime(value: unknown): number;
+/**
+ * Process data source into internal format for charts
+ */
+declare function processDataSource(source: StreamDataSource, xKey: string, yKey: string, zKey?: string): ProcessedDataSource;
+/**
+ * Merge deep objects (like lodash merge)
+ */
+declare function mergeDeep<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Generate unique ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Filter data by latest timestamp (frame-bound mode)
+ * Keeps only rows with the maximum timestamp value
+ */
+declare function filterByLatestTimestamp(data: unknown[][], timeIndex: number): unknown[][];
+/**
+ * Filter data by unique key (key-bound mode)
+ * Keeps only the latest row for each unique key value
+ */
+/**
+ * Filter data by unique key (key-bound mode)
+ * Keeps only the latest row for each unique key value
+ */
+declare function filterByKey(data: unknown[][], keyIndex: number | number[]): unknown[][];
+/**
+ * Apply temporal filtering based on configuration
+ */
+declare function applyTemporalFilter(data: unknown[][], columns: ColumnDefinition[], temporal: TemporalConfig): unknown[][];
+
+/**
+ * Core chart utilities and base functionality
+ */
+
+declare const AXIS_HEIGHT_WITH_TITLE = 70;
+declare const AXIS_HEIGHT_WITHOUT_TITLE = 40;
+declare const MAX_LEGEND_ITEMS = 30;
+/**
+ * Horizontal axis label transformation configuration
+ */
+declare const horizontalAxisLabelConfig: {
+    labelAutoHide: {
+        type: string;
+        keepHeader: boolean;
+        keepTail: boolean;
+    };
+    labelAutoRotate: boolean;
+    labelAutoEllipsis: {
+        type: string;
+        minLength: number;
+        maxLength: number;
+    };
+};
+/**
+ * Vertical axis label transformation configuration
+ */
+declare const verticalAxisLabelConfig: {
+    transform: {
+        margin: number[];
+        type: string;
+    }[];
+};
+/**
+ * Apply color encoding to a chart mark
+ */
+declare function applyColorEncoding(node: MarkNode, config: {
+    zIndex: number;
+    colors: ColorPalette;
+    domain?: string[];
+    activeIndex?: number;
+}): MarkNode;
+/**
+ * Apply legend configuration to a chart mark
+ */
+declare function applyLegend(node: MarkNode, enabled: boolean, onItemClick?: (index: number) => void, values?: string[], theme?: 'dark' | 'light'): MarkNode;
+/**
+ * Apply data label configuration to a chart mark
+ */
+declare function applyDataLabel(node: MarkNode, config: {
+    enabled: boolean;
+    yIndex: number;
+    unit?: {
+        position: 'left' | 'right';
+        value: string;
+    };
+    fractionDigits?: number;
+    showAll?: boolean;
+    textAlign?: 'start' | 'center' | 'end';
+    textBaseline?: 'top' | 'middle' | 'bottom' | 'alphabetic';
+}): MarkNode;
+/**
+ * Truncate label with ellipsis
+ */
+declare function truncateLabel(value: string, maxChar: number | null): string;
+/**
+ * Render chart with standard interactions
+ */
+declare function renderChart(chart: Chart, theme?: 'dark' | 'light'): Promise<void>;
+/**
+ * Configure tooltip for a chart mark
+ */
+declare function applyTooltip(node: MarkNode, enabled: boolean, config: {
+    xIndex: number;
+    yIndex: number;
+    zIndex?: number;
+    zValues?: string[];
+    colors: ColorPalette;
+    fractionDigits?: number;
+    yLabel?: string;
+}): MarkNode;
+/**
+ * Create default chart configuration based on data source
+ */
+declare function createDefaultConfig(source: ProcessedDataSource, chartType: string): Record<string, unknown>;
+/**
+ * Get theme colors for charts
+ */
+declare function getChartThemeColors(theme: 'dark' | 'light'): {
+    text: string;
+    textSecondary: string;
+    line: string;
+    gridline: string;
+    background: string;
+};
+/**
+ * Apply chart theme
+ */
+declare function applyChartTheme(chart: Chart, theme?: 'dark' | 'light'): void;
+
+/**
+ * Config Compilers — bridge between legacy chart configs and VistralSpec.
+ *
+ * These functions convert the existing high-level chart configuration
+ * objects (TimeSeriesConfig, BarColumnConfig) into the declarative
+ * VistralSpec grammar.
+ */
+
+/**
+ * Compile a `TimeSeriesConfig` into a `VistralSpec`.
+ *
+ * Mapping summary:
+ * - `chartType` -> mark type ('line' | 'area')
+ * - `xAxis` / `yAxis` / `color` -> encode channels
+ * - `lineStyle: 'curve'` -> style.shape: 'smooth', else 'line'
+ * - Always adds style.connect: true
+ * - `points: true` -> adds second point mark (tooltip: false)
+ * - `dataLabel: true` -> adds label; if showAll is false, selector: 'last'
+ * - area + color -> transforms: [{ type: 'stackY' }]
+ * - scales.x: time scale with optional mask from xFormat
+ * - scales.y: linear, nice, optional domain from yRange
+ * - temporal -> maps to TemporalSpec
+ * - streaming: { maxItems: config.maxItems ?? DEFAULT_MAX_ITEMS }
+ * - axes, legend, theme, animate configured per defaults
+ */
+declare function compileTimeSeriesConfig(config: TimeSeriesConfig, theme?: 'dark' | 'light'): VistralSpec;
+/**
+ * Compile a `BarColumnConfig` into a `VistralSpec`.
+ *
+ * Mapping summary:
+ * - mark type is always 'interval'
+ * - `chartType 'bar'` -> coordinate: { transforms: [{ type: 'transpose' }] }
+ * - `color` set -> transforms: stackY (if groupType==='stack') or dodgeX
+ * - `dataLabel: true` -> label with text: yAxis, overlapHide: true
+ * - scales: x with padding 0.5, y linear with nice
+ * - Same streaming/axes/legend/theme/animate defaults as time series
+ */
+declare function compileBarColumnConfig(config: BarColumnConfig, theme?: 'dark' | 'light'): VistralSpec;
+
+export { AXIS_HEIGHT_WITHOUT_TITLE, AXIS_HEIGHT_WITH_TITLE, AnnotationSpec, AxesSpec, BarColumnConfig, ChartConfig, ChartConfigBase, ChartHandle, ChartTheme, ColorPalette, ColumnDefinition, ColumnStatistics, ColumnType, CoordinateSpec, DEFAULT_MAX_ITEMS, DEFAULT_PALETTE, DataRow, DataTable, DataTableProps, EncodeFn, EncodeSpec, GeoChart, GeoChartConfig, GeoChartProps, InteractionSpec, LegendSpec, MAX_LEGEND_ITEMS, MarkSpec, OHLCConfig, ProcessedDataSource, ScaleSpec, SingleValueChart, SingleValueChartProps, SingleValueConfig, StreamChart, StreamChartProps, StreamDataSource, StreamingSpec, TableConfig, TemporalConfig, TemporalMode, TemporalSpec, ThemeName, TimeSeriesConfig, TooltipSpec, TransformSpec, VistralChart, VistralChartProps, VistralSpec, abbreviateNumber, allPalettes, applyChartTheme, applyColorEncoding, applyDataLabel, applyLegend, applyTemporalFilter, applyTooltip, calculateColumnStats, clamp, compileBarColumnConfig, compileTimeSeriesConfig, createDefaultConfig, darkTheme, debounce, StreamChart as default, filterByKey, filterByLatestTimestamp, findColumnIndex, findPaletteByLabel, findPaletteByValues, formatBytes, formatDuration, formatNumber, generateId, getChartThemeColors, getColumnsByType, getGeoChartDefaults, getPaletteKeyColor, getRowValue, getSeriesColors, getSingleValueDefaults, getTableDefaults, getTheme, getTimeMask, getUniqueValues, horizontalAxisLabelConfig, isBooleanColumn, isDateTimeColumn, isNumericColumn, isStringColumn, lightTheme, mergeDeep, multiColorPalettes, parseDateTime, processDataSource, renderChart, rowToArray, singleColorPalettes, truncateLabel, truncateWithEllipsis, useAutoConfig, useChart, useChartAnimation, useChartTheme, useDataSource, useDebouncedValue, useLastUpdated, usePrevious, useResizeObserver, useSparklineData, useStreamingData, verticalAxisLabelConfig };