/**
 * 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;
}

/**
 * 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';

/**
 * Creates a MAIDR data object from a rendered Google Charts chart.
 *
 * Call this **after** the chart has finished rendering (inside the
 * `google.visualization.events.addListener(chart, 'ready', …)` callback)
 * so that the container DOM already contains the SVG elements.
 *
 * @param chart     - The Google Charts chart instance. Used to access
 *                    `getChartLayoutInterface()` for locating SVG elements.
 * @param dataTable - The `google.visualization.DataTable` (or DataView) used
 *                    to draw the chart.
 * @param container - The DOM element the chart was drawn into.
 * @param options   - Adapter options (chart type is required).
 * @returns A {@link Maidr} object ready to be passed to `<Maidr data={…}>` or
 *          set as the `maidr` / `maidr-data` attribute.
 *
 * @example
 * ```js
 * google.charts.load('current', { packages: ['corechart'] });
 * google.charts.setOnLoadCallback(() => {
 *   const data = google.visualization.arrayToDataTable([
 *     ['City', 'Population'],
 *     ['New York', 8336817],
 *     ['Los Angeles', 3979576],
 *   ]);
 *   const container = document.getElementById('chart');
 *   const chart = new google.visualization.ColumnChart(container);
 *
 *   google.visualization.events.addListener(chart, 'ready', () => {
 *     const maidr = createMaidrFromGoogleChart(chart, data, container, {
 *       chartType: 'ColumnChart',
 *     });
 *     container.setAttribute('maidr', JSON.stringify(maidr));
 *   });
 *
 *   chart.draw(data);
 * });
 * ```
 */
export declare function createMaidrFromGoogleChart(chart: GoogleChart, dataTable: GoogleDataTable, container: HTMLElement, options: GoogleChartAdapterOptions): MaidrData;

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

/**
 * Bounding box returned by `getChartLayoutInterface().getBoundingBox()`.
 */
declare interface GoogleBoundingBox {
    left: number;
    top: number;
    width: number;
    height: number;
}

/**
 * Common interface shared by all Google visualization chart types.
 */
export declare interface GoogleChart {
    getSelection: () => GoogleSelectionItem[];
    setSelection: (selection: GoogleSelectionItem[]) => void;
    /**
     * Returns the chart layout interface for accessing element positions.
     *
     * @see https://developers.google.com/chart/interactive/docs/gallery/columnchart#methods
     */
    getChartLayoutInterface: () => GoogleChartLayoutInterface;
}

/**
 * Options accepted by {@link createMaidrFromGoogleChart}.
 */
export declare interface GoogleChartAdapterOptions {
    /** Unique ID for the MAIDR instance. Defaults to the container element's `id`. */
    id?: string;
    /** Chart title. Extracted from chart options when omitted. */
    title?: string;
    /**
     * The Google Charts chart type string (e.g. `'BarChart'`, `'LineChart'`).
     * Must be provided because the chart instance does not expose its own type.
     *
     * For stacked, normalized, or grouped (dodged) variants of bar / column
     * charts, use the explicit adapter type strings such as
     * `'StackedColumnChart'`, `'NormalizedBarChart'`, or `'DodgedColumnChart'`.
     */
    chartType: GoogleChartType;
}

/**
 * Chart layout interface for accessing element positions.
 *
 * @see https://developers.google.com/chart/interactive/docs/gallery/columnchart#methods
 */
declare interface GoogleChartLayoutInterface {
    /**
     * Returns the bounding box of a chart element.
     *
     * For bar/column charts, use IDs like:
     *   - `'bar#seriesIndex#dataIndex'` — e.g., `'bar#0#2'` for series 0, bar 2
     *   - `'chartarea'` — the entire chart area
     *   - `'hAxis'`, `'vAxis'` — axis elements
     *
     * @param id - The element ID string
     * @returns Bounding box with left, top, width, height, or null if not found
     */
    getBoundingBox: (id: string) => GoogleBoundingBox | null;
    /**
     * Returns the pixel x-coordinate of a data value relative to the chart container's left edge.
     *
     * @param dataValue - The data value on the horizontal axis
     * @param axisIndex - Optional axis index for charts with multiple axes (default: 0)
     * @returns The pixel x-coordinate
     */
    getXLocation: (dataValue: number, axisIndex?: number) => number;
    /**
     * Returns the pixel y-coordinate of a data value relative to the chart container's top edge.
     *
     * @param dataValue - The data value on the vertical axis
     * @param axisIndex - Optional axis index for charts with multiple axes (default: 0)
     * @returns The pixel y-coordinate
     */
    getYLocation: (dataValue: number, axisIndex?: number) => number;
}

/**
 * Supported Google Charts chart type strings that the adapter can convert.
 */
export declare type GoogleChartType = 'BarChart' | 'CandlestickChart' | 'ColumnChart' | 'DodgedBarChart' | 'DodgedColumnChart' | 'LineChart' | 'ScatterChart' | 'StackedBarChart' | 'StackedColumnChart';

/**
 * Minimal type declarations for Google Charts API.
 *
 * These cover only the subset required by the MAIDR Google Charts adapter.
 * Google Charts is loaded via a CDN script tag and exposes its API on the
 * `google.visualization` namespace at runtime.
 *
 * @see https://developers.google.com/chart
 */
/**
 * Google Charts DataTable — the tabular data model backing every chart.
 */
export declare interface GoogleDataTable {
    getNumberOfRows: () => number;
    getNumberOfColumns: () => number;
    getValue: (rowIndex: number, columnIndex: number) => unknown;
    getFormattedValue: (rowIndex: number, columnIndex: number) => string;
    getColumnLabel: (columnIndex: number) => string;
    getColumnType: (columnIndex: number) => 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'timeofday';
    getColumnRole?: (columnIndex: number) => string;
}

/**
 * Google Charts event helper namespace.
 */
export declare interface GoogleEvents {
    addListener: (chart: GoogleChart, eventName: string, handler: (...args: unknown[]) => void) => {
        remove: () => void;
    };
    removeAllListeners: (chart: GoogleChart) => void;
}

/**
 * Google Charts selection item returned by `chart.getSelection()`.
 */
export declare interface GoogleSelectionItem {
    row: number | null;
    column: number | null;
}

/**
 * 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;
}

/**
 * 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"
}

/**
 * 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 { }