/**
 * Canonical axis configuration. Every axis (x, y, z) must be specified as an
 * object of this shape. The `label` is optional and falls back to built-in
 * defaults ('X', 'Y', 'Level') when omitted.
 *
 * Grid navigation properties (`min`, `max`, `tickStep`) are currently consumed
 * by scatter-plot traces only; they are silently ignored by other trace types.
 *
 * Formatting configuration lives inline as `format` on each axis, allowing
 * different formatters per axis without a separate top-level block.
 *
 * @example
 * // Simple label
 * axes: { x: { label: "Date" }, y: { label: "Price" } }
 *
 * @example
 * // With grid navigation (scatter)
 * axes: {
 *   x: { label: "Sepal Length", min: 4.3, max: 7.9, tickStep: 0.7 },
 *   y: { label: "Sepal Width",  min: 2,   max: 4.4, tickStep: 0.5 }
 * }
 *
 * @example
 * // With formatting
 * axes: {
 *   x: { label: "Date" },
 *   y: { label: "Price", format: { type: "currency", decimals: 2 } }
 * }
 */
declare interface AxisConfig {
    /** Axis label displayed in text descriptions. Defaults applied when absent. */
    label?: string;
    /** Minimum value for grid navigation (scatter only). */
    min?: number;
    /** Maximum value for grid navigation (scatter only). */
    max?: number;
    /** Step size for grid navigation (scatter only). */
    tickStep?: number;
    /** Optional per-axis value formatting applied in text descriptions. */
    format?: AxisFormat;
}

/**
 * Configuration for formatting values on an axis.
 *
 * Two ways to specify formatting:
 * 1. `function` - Function body string (for custom logic)
 * 2. `type` - Format type specifier (for common patterns)
 *
 * @example
 * // Using function string
 * { "function": "return `$${Number(value).toFixed(2)}`" }
 *
 * @example
 * // Using type specifier
 * { "type": "currency", "decimals": 2 }
 */
declare interface AxisFormat {
    /**
     * Function body string for custom formatting.
     * The function receives `value` as parameter and must return a string.
     *
     * @example
     * // Currency formatting
     * { "function": "return `$${Number(value).toFixed(2)}`" }
     *
     * @example
     * // Date formatting
     * { "function": "return new Date(value).toLocaleDateString('en-US')" }
     */
    function?: string;
    /**
     * Format type specifier for common formatting patterns.
     * Use with `decimals`, `currency`, `locale`, `dateOptions` for customization.
     *
     * @example
     * { "type": "currency", "currency": "USD", "decimals": 2 }
     * { "type": "percent", "decimals": 1 }
     * { "type": "date", "dateOptions": { "month": "short", "day": "numeric" } }
     */
    type?: FormatType;
    /**
     * Number of decimal places for numeric formatters.
     * Used with: currency, percent, fixed, number, scientific
     * @default varies by type
     */
    decimals?: number;
    /**
     * ISO 4217 currency code for currency formatter.
     * @default 'USD'
     */
    currency?: string;
    /**
     * BCP 47 locale string for locale-aware formatters.
     * Used with: currency, number, date
     * @default 'en-US'
     */
    locale?: string;
    /**
     * Options for Intl.DateTimeFormat when using date type.
     *
     * @example
     * { "month": "short", "day": "numeric" } // "Jan 15"
     * { "year": "numeric", "month": "long" } // "January 2024"
     */
    dateOptions?: Intl.DateTimeFormatOptions;
}

/**
 * Data point for bar charts with x and y coordinates.
 */
declare interface BarPoint {
    x: string | number;
    y: number | string;
}

/**
 * Initialise MAIDR on an already-rendered Vega-Lite chart.
 *
 * Locates the `<svg>` inside the Vega view's container, converts the spec
 * to a {@link Maidr} schema, and mounts the accessible MAIDR UI on it.
 *
 * **The view must have completed its first render before this is called.**
 * `vegaEmbed(...)` resolves when the view is *constructed*, not when it has
 * rendered*, so callers using this entry point directly must
 * `await view.runAsync()` between embedding and binding:
 *
 * ```js
 * const result = await vegaEmbed('#vis', vlSpec, { renderer: 'svg' });
 * await result.view.runAsync(); // wait for the first paint
 * maidrVegaLite.bindVegaLite(result.view, vlSpec, { id: 'my-chart' });
 * ```
 *
 * For most use cases prefer {@link embed}, which performs both steps for you.
 *
 * @param view - The compiled Vega `View` returned by `vegaEmbed`.
 * @param spec - The original Vega-Lite specification.
 * @param options - Optional id / title overrides.
 */
export declare function bindVegaLite(view: VegaView, spec: VegaLiteSpec, options?: VegaLiteToMaidrOptions): void;

/**
 * Data point for boxplots containing quartiles, min/max, and outliers.
 */
declare interface BoxPoint {
    z: string;
    lowerOutliers: number[];
    min: number;
    q1: number;
    q2: number;
    q3: number;
    max: number;
    upperOutliers: number[];
    /** Mean value for violin plots when mean display is enabled. */
    mean?: number;
}

/**
 * DOM selectors for boxplot visual elements.
 */
declare interface BoxSelector {
    lowerOutliers: string[];
    min: string;
    iq: string;
    q2: string;
    max: string;
    upperOutliers: string[];
    /** CSS selector for mean marker element in violin plots. */
    mean?: string;
    /** Optional direct CSS selector for Q1 element (bypasses iq edge derivation). */
    q1?: string;
    /** Optional direct CSS selector for Q3 element (bypasses iq edge derivation). */
    q3?: string;
}

/**
 * Data point for candlestick charts with OHLC values, volume, and trend information.
 */
declare interface CandlestickPoint {
    value: string;
    open: number;
    high: number;
    low: number;
    close: number;
    /** Optional volume data. May be undefined when source (e.g., Google Charts) doesn't provide it. */
    volume?: number;
    trend: CandlestickTrend;
    volatility: number;
}

/**
 * DOM selectors for candlestick chart visual elements.
 */
declare interface CandlestickSelector {
    body: string | string[];
    wickHigh?: string | string[];
    wickLow?: string | string[];
    wick?: string | string[];
    open?: string | string[];
    close?: string | string[];
}

/**
 * Represents the trend direction for candlestick data points.
 * Used across the application for audio palette selection and data representation.
 */
declare type CandlestickTrend = 'Bull' | 'Bear' | 'Neutral';

/**
 * Render a Vega-Lite spec **and** mount MAIDR on it, in a single call.
 *
 * This wraps `vegaEmbed()` + {@link bindVegaLite} and handles the two things
 * that make the manual path error-prone:
 *
 * 1. Forces `renderer: "svg"`. MAIDR navigates the rendered DOM via CSS
 *    selectors that target SVG elements (`g.mark-rect path`, etc.) and
 *    cannot operate on a `<canvas>`-rendered chart. If the caller passes
 *    `embedOptions: { renderer: 'canvas' }` we log a warning and override.
 * 2. `await result.view.runAsync()` — waits for the first render frame to
 *    complete. `vegaEmbed(...)` resolves when the view is *constructed*,
 *    not when it has *painted*; binding before the first paint races the
 *    DOM and is the root cause of "No SVG found" errors on slow/aggregated
 *    specs (histograms, complex transforms).
 *
 * Requires the global `vegaEmbed` (from the `vega-embed` script) to be
 * loaded before this function is called.
 *
 * @param target - A CSS selector or HTMLElement that will host the chart.
 * @param spec - The Vega-Lite specification.
 * @param options - Optional MAIDR id / title and `vegaEmbed` options.
 * @returns A promise that resolves with the underlying Vega `View`.
 *
 * @example
 * ```js
 * maidrVegaLite.embed('#chart', spec, { id: 'tips-bar' });
 * ```
 */
export declare function embed(target: string | HTMLElement, spec: VegaLiteSpec, options?: VegaLiteEmbedOptions): Promise<VegaLiteEmbedResult>;

/**
 * Supported format type specifiers for JSON/HTML API.
 */
declare type FormatType = 'currency' | 'percent' | 'fixed' | 'number' | 'date' | 'scientific';

/**
 * Data structure for heatmap charts with x/y labels and 2D point values.
 */
declare interface HeatmapData {
    x: string[];
    y: string[];
    points: number[][];
}

/**
 * Data point for histograms extending bar points with bin ranges.
 */
declare interface HistogramPoint extends BarPoint {
    xMin: number;
    xMax: number;
    yMin: number;
    yMax: number;
}

/**
 * Data point for line charts with optional fill color for multi-series plots.
 */
declare interface LinePoint {
    x: number | string;
    y: number;
    z?: string;
}

/**
 * Root MAIDR data structure containing figure metadata and subplot grid.
 * This is the type for the `data` prop passed to the `<Maidr>` React component.
 *
 * @example
 * ```typescript
 * const data: Maidr = {
 *   id: 'my-chart',
 *   title: 'Sales by Quarter',
 *   subplots: [[{
 *     layers: [{
 *       id: '0',
 *       type: 'bar',
 *       axes: { x: 'Quarter', y: 'Revenue' },
 *       data: [{ x: 'Q1', y: 120 }, { x: 'Q2', y: 200 }],
 *     }],
 *   }]],
 * };
 * ```
 */
export declare interface MaidrData {
    /** Unique identifier for the chart. Used for DOM element IDs. */
    id: string;
    /** Chart title displayed in text descriptions. */
    title?: string;
    /** Chart subtitle. */
    subtitle?: string;
    /** Chart caption. */
    caption?: string;
    /**
     * 2D grid of subplots. Each row is an array of subplots.
     * For a single chart, use `[[{ layers: [...] }]]`.
     */
    subplots: MaidrSubplot[][];
}

/**
 * Layer/trace definition containing plot type, data, and rendering configuration.
 */
export declare interface MaidrLayer {
    id: string;
    type: TraceType;
    title?: string;
    selectors?: string | string[] | BoxSelector[] | CandlestickSelector;
    orientation?: Orientation;
    /**
     * Optional DOM mapping hints. When provided, individual traces can opt-in
     * to use these hints to map DOM elements to the internal row-major data grid
     * without changing default behavior when omitted.
     */
    domMapping?: {
        /**
         * Specify DOM flattening order for grid-like traces.
         * 'row' => row-major, 'column' => column-major.
         */
        order?: 'row' | 'column';
        /**
         * For segmented/dodged bars, control the per-column group/level iteration.
         * 'forward' => iterate groups top-to-bottom (as previously domOrder='forward').
         * 'reverse' => iterate bottom-to-top (default).
         */
        groupDirection?: 'forward' | 'reverse';
        /**
         * For boxplots, control the Q1/Q3 edge mapping for IQR box.
         * 'forward' => Q1=bottom, Q3=top (default for vertical)
         * 'reverse' => Q1=top, Q3=bottom (for Base R vertical boxplots)
         */
        iqrDirection?: 'forward' | 'reverse';
    };
    /**
     * Axis configuration. Every axis (x, y, z) is specified as an {@link AxisConfig}
     * object with an optional `label`, optional grid navigation properties
     * (`min`, `max`, `tickStep`), and optional per-axis `format`.
     *
     * @example
     * // Basic labels
     * axes: { x: { label: "Date" }, y: { label: "Price" } }
     *
     * @example
     * // With per-axis formatting
     * axes: {
     *   x: { label: "Date" },
     *   y: { label: "Price", format: { type: "currency", decimals: 2 } }
     * }
     *
     * @example
     * // With grid navigation (scatter)
     * axes: {
     *   x: { label: "Sepal Length", min: 4.3, max: 7.9, tickStep: 0.7 },
     *   y: { label: "Sepal Width",  min: 2,   max: 4.4, tickStep: 0.5 }
     * }
     */
    axes?: {
        x?: AxisConfig;
        y?: AxisConfig;
        z?: AxisConfig;
    };
    /**
     * Optional display configuration for violin plot layers (VIOLIN_KDE and VIOLIN_BOX).
     * Controls which summary statistics are shown in the violin box overlay.
     */
    violinOptions?: ViolinOptions;
    data: BarPoint[] | BoxPoint[] | CandlestickPoint[] | HeatmapData | HistogramPoint[] | LinePoint[][] | ScatterPoint[] | SegmentedPoint[][] | SmoothPoint[][] | ViolinKdePoint[][];
}

/**
 * Subplot data structure containing optional legend and trace layers.
 * A subplot groups one or more layers (traces) that share the same coordinate space.
 *
 * @example
 * ```typescript
 * const subplot: MaidrSubplot = {
 *   layers: [
 *     { id: '0', type: 'bar', axes: { x: 'X', y: 'Y' }, data: [...] },
 *     { id: '1', type: 'line', axes: { x: 'X', y: 'Y' }, data: [...] },
 *   ],
 * };
 * ```
 */
export declare interface MaidrSubplot {
    /** Legend labels for multi-series plots. */
    legend?: string[];
    /** CSS selector for the subplot container element. */
    selector?: string;
    /** Array of trace layers in this subplot. */
    layers: MaidrLayer[];
}

/**
 * Chart orientation for bar and box plots.
 */
export declare enum Orientation {
    VERTICAL = "vert",
    HORIZONTAL = "horz"
}

/**
 * Data point for scatter plots with x and y coordinates.
 */
declare interface ScatterPoint {
    x: number;
    y: number;
}

/**
 * Data point for segmented/grouped bar charts with fill color identifier.
 */
declare interface SegmentedPoint extends BarPoint {
    z: string;
}

/**
 * Toggle adapter-level diagnostic logging at runtime.
 *
 * Useful when debugging highlight or navigation alignment problems —
 * the adapter logs the converted MAIDR schema and any DOM re-ordering
 * it performs. Off by default.
 *
 * @example
 * ```js
 * maidrVegaLite.setDebug(true);
 * maidrVegaLite.embed('#chart', spec);
 * ```
 */
export declare function setDebug(enabled: boolean): void;

/**
 * Data point for smooth/regression plots with data and SVG coordinate pairs.
 */
declare interface SmoothPoint {
    x: number;
    y: number;
    svg_x: number;
    svg_y: number;
}

/**
 * Enumeration of supported plot trace types.
 * Use these values for the `type` field in {@link MaidrLayer}.
 *
 * @example
 * ```typescript
 * import { TraceType } from 'maidr/react';
 * const layer = { id: '0', type: TraceType.BAR, ... };
 * // Or use the string value directly:
 * const layer2 = { id: '0', type: 'bar', ... };
 * ```
 */
export declare enum TraceType {
    BAR = "bar",
    BOX = "box",
    CANDLESTICK = "candlestick",
    DODGED = "dodged_bar",
    HEATMAP = "heat",
    HISTOGRAM = "hist",
    LINE = "line",
    NORMALIZED = "stacked_normalized_bar",
    SCATTER = "point",
    SMOOTH = "smooth",
    STACKED = "stacked_bar",
    VIOLIN_BOX = "violin_box",
    VIOLIN_KDE = "violin_kde"
}

/**
 * Subset of a Vega-Lite channel definition fields read by the adapter.
 */
export declare interface VegaLiteChannelDef {
    field?: string;
    type?: string;
    aggregate?: string;
    title?: string;
    axis?: {
        title?: string;
    } | null;
    bin?: boolean | Record<string, unknown>;
    stack?: boolean | string | null;
}

/**
 * Options accepted by {@link embed}.
 */
export declare interface VegaLiteEmbedOptions extends VegaLiteToMaidrOptions {
    /**
     * Options forwarded to `vegaEmbed`. By default `actions: false` is set
     * but can be overridden here.
     */
    embedOptions?: Record<string, unknown>;
}

/**
 * Result of {@link embed} — gives callers access to the underlying Vega view.
 */
export declare interface VegaLiteEmbedResult {
    view: VegaView;
}

/**
 * The encoding channels that the adapter inspects when mapping a
 * Vega-Lite spec to a MAIDR trace.
 */
export declare interface VegaLiteEncoding {
    x?: VegaLiteChannelDef;
    y?: VegaLiteChannelDef;
    /**
     * Modern Vega-Lite dodge channel — when paired with a categorical
     * `field`, Vega-Lite places bars of each subcategory **side-by-side**
     * within the same x slot. The adapter inspects this to classify a
     * `bar` mark as DODGED rather than STACKED.
     */
    xOffset?: VegaLiteChannelDef;
    /** Vertical counterpart of `xOffset`. */
    yOffset?: VegaLiteChannelDef;
    color?: VegaLiteChannelDef;
    fill?: VegaLiteChannelDef;
    row?: VegaLiteChannelDef;
    column?: VegaLiteChannelDef;
}

/**
 * Minimal Vega-Lite top-level specification shape.
 *
 * Covers single-view, layered (`layer`), and composite (`hconcat` / `vconcat`
 * / `concat`) specs. Faceted (`facet`) and repeated (`repeat`) specs are
 * recognised but not yet supported by the adapter.
 */
export declare interface VegaLiteSpec {
    $schema?: string;
    title?: string | {
        text?: string;
        subtitle?: string;
    };
    description?: string;
    data?: unknown;
    mark?: string | {
        type: string;
    };
    encoding?: VegaLiteEncoding;
    layer?: VegaLiteSpec[];
    hconcat?: VegaLiteSpec[];
    vconcat?: VegaLiteSpec[];
    concat?: VegaLiteSpec[];
    facet?: unknown;
    spec?: VegaLiteSpec;
    repeat?: unknown;
}

/**
 * Convert a Vega-Lite spec (and optionally its compiled Vega view) into a
 * MAIDR-compatible schema.
 *
 * @param spec - The Vega-Lite specification object.
 * @param view - Optional compiled Vega view for runtime data extraction.
 * @param options - Optional id / title overrides.
 * @returns A complete {@link Maidr} schema ready for MAIDR consumption.
 */
export declare function vegaLiteToMaidr(spec: VegaLiteSpec, view?: VegaView, options?: VegaLiteToMaidrOptions): MaidrData;

/**
 * Options accepted by the {@link vegaLiteToMaidr} converter.
 */
export declare interface VegaLiteToMaidrOptions {
    /** Override the chart id (defaults to `"vl-chart"`). */
    id?: string;
    /** Override the chart title (extracted from the spec by default). */
    title?: string;
    /**
     * Override how MAIDR maps the rendered SVG of a segmented (stacked /
     * normalised / dodged) bar trace back onto the 2-D `data[seriesIndex][barIndex]`
     * grid. Supplied as a hint to {@link MaidrLayer.domMapping}.
     *
     * - `'series-major'` — DOM emits **all bars of one colour** before
     *   moving to the next colour. This is Vega-Lite's default for
     *   stacked / normalised bars.
     * - `'subject-major'` — DOM emits **all colours of one x-subject**
     *   before moving to the next subject. This is Vega-Lite's default
     *   for dodged bars.
     *
     * Leave undefined to use the type-based defaults
     * (stacked/normalised → series-major, dodged → subject-major).
     * Only set this if your Vega-Lite spec uses a non-default mark order
     * or transform that changes the DOM emission sequence.
     */
    domOrder?: 'series-major' | 'subject-major';
}

/**
 * Minimal type declarations for the Vega / Vega-Lite API surface used by
 * the MAIDR Vega-Lite adapter.
 *
 * Vega and Vega-Lite are **peer dependencies** of MAIDR. The adapter only
 * references their public API through these lightweight aliases so that the
 * MAIDR bundle does not ship the libraries.
 *
 * @see https://vega.github.io/vega-lite/
 */
/**
 * Minimal subset of a Vega `View` that the adapter needs at runtime.
 *
 * The compiled view exposes processed datasets (post-transform / aggregate)
 * via {@link VegaView.data}, which is the most accurate source for chart
 * data extraction.
 *
 * {@link VegaView.runAsync} is used by the adapter to wait for the first
 * render frame to complete, which guarantees the SVG element exists in the
 * container before MAIDR tries to mount on it.
 */
export declare interface VegaView {
    data: (name: string) => Record<string, unknown>[];
    container: () => HTMLElement | null;
    runAsync: () => Promise<VegaView>;
    /**
     * Look up a Vega scale by name (e.g. `'x'`, `'y'`, `'color'`).
     *
     * Returns `undefined` if the scale doesn't exist. The scale's
     * `domain()` provides the **rendered** domain in the order Vega uses
     * to lay out marks — used by the adapter to align data ordering with
     * the SVG DOM order so MAIDR's index-based highlighting matches the
     * visible chart.
     */
    scale: (name: string) => {
        domain: () => unknown[];
    } | undefined;
}

/**
 * Data point for violin KDE (kernel density estimation) curves.
 * Library-agnostic — no SVG coordinates embedded in data.
 * The density field falls back to width if absent.
 */
declare interface ViolinKdePoint {
    /** Categorical label for the violin (e.g., "setosa") */
    x: string | number;
    /** Position along the density axis */
    y: number;
    /** KDE density value at this point. Falls back to `width` if absent. */
    density?: number;
    /** Half-width of the violin at this Y level (used as density fallback) */
    width?: number;
    /** SVG viewport x-coordinate for highlight positioning (provided by backend) */
    svg_x?: number;
    /** SVG viewport y-coordinate for highlight positioning (provided by backend) */
    svg_y?: number;
}

/**
 * Configuration options for violin plot display.
 * Controls which summary statistics are shown in the violin box overlay.
 * Sent from the Python backend alongside violin_kde and violin_box layers.
 */
declare interface ViolinOptions {
    /** Show median line marker. Default: true */
    showMedian?: boolean;
    /** Show mean value marker. Default: false */
    showMean?: boolean;
    /** Show extrema (min/max) markers. Default: true */
    showExtrema?: boolean;
}

export { }