import { JSX } from 'react';

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

/**
 * Converts a Recharts adapter config into MAIDR's root data structure.
 *
 * @param config - Recharts adapter configuration
 * @returns MaidrData ready to pass to the `<Maidr>` component
 */
export declare function convertRechartsToMaidr(config: RechartsAdapterConfig): MaidrData;

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

/**
 * Returns the CSS selector string for individual data point elements
 * of the given Recharts chart type.
 *
 * Returns `undefined` when `seriesIndex` is provided, because CSS alone
 * cannot reliably target a specific series in Recharts' SVG structure.
 * See the module-level documentation for details.
 *
 * @param chartType - The Recharts chart type
 * @param seriesIndex - When set, indicates a multi-series chart — returns undefined
 * @returns CSS selector string, or undefined for multi-series targeting
 */
export declare function getRechartsSelector(chartType: RechartsChartType, seriesIndex?: number): string | undefined;

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

/**
 * Configuration for histogram bin ranges.
 * Required when `chartType` is `'histogram'`.
 */
export declare interface HistogramBinConfig {
    /** Key in data objects for the lower bin edge. */
    xMinKey: string;
    /** Key in data objects for the upper bin edge. */
    xMaxKey: string;
    /** Key in data objects for the minimum count (typically 0). Defaults to 0. */
    yMinKey?: string;
    /** Key in data objects for the maximum count. Defaults to the yKey value. */
    yMaxKey?: string;
}

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

/**
 * Wrapper component that makes Recharts charts accessible via MAIDR.
 *
 * This component extracts data configuration from props, converts it to
 * MAIDR's data format, and renders the Recharts children inside a `<Maidr>`
 * component for audio sonification, text descriptions, braille output,
 * and keyboard navigation.
 */
export declare function MaidrRecharts({ id, title, subtitle, caption, data, chartType, xKey, yKeys, layers, xLabel, yLabel, orientation, fillKeys, binConfig, selectorOverride, children, }: MaidrRechartsProps): JSX.Element;

/**
 * Props for the MaidrRecharts wrapper component.
 */
export declare interface MaidrRechartsProps extends RechartsAdapterConfig {
    /** Recharts chart component(s) to make accessible. */
    children: React.ReactNode;
}

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

/**
 * Configuration for the Recharts-to-MAIDR adapter.
 *
 * Supports two configuration modes:
 * 1. **Simple mode** — Set `chartType` and `yKeys` for a single chart type
 *    with one or more data series.
 * 2. **Composed mode** — Set `layers` for mixed chart types (e.g., bar + line).
 *
 * @example Simple bar chart
 * ```typescript
 * const config: RechartsAdapterConfig = {
 *   id: 'sales-chart',
 *   title: 'Sales by Quarter',
 *   data: [{ quarter: 'Q1', revenue: 100 }, { quarter: 'Q2', revenue: 200 }],
 *   chartType: 'bar',
 *   xKey: 'quarter',
 *   yKeys: ['revenue'],
 *   xLabel: 'Quarter',
 *   yLabel: 'Revenue ($)',
 * };
 * ```
 *
 * @example Stacked bar chart
 * ```typescript
 * const config: RechartsAdapterConfig = {
 *   id: 'stacked-chart',
 *   title: 'Revenue by Product',
 *   data: [{ month: 'Jan', productA: 50, productB: 30 }],
 *   chartType: 'stacked_bar',
 *   xKey: 'month',
 *   yKeys: ['productA', 'productB'],
 *   fillKeys: ['Product A', 'Product B'],
 *   xLabel: 'Month',
 *   yLabel: 'Revenue',
 * };
 * ```
 *
 * @example Histogram
 * ```typescript
 * const config: RechartsAdapterConfig = {
 *   id: 'hist-chart',
 *   title: 'Score Distribution',
 *   data: [{ bin: '0-10', count: 5, xMin: 0, xMax: 10 }],
 *   chartType: 'histogram',
 *   xKey: 'bin',
 *   yKeys: ['count'],
 *   binConfig: { xMinKey: 'xMin', xMaxKey: 'xMax' },
 *   xLabel: 'Score',
 *   yLabel: 'Frequency',
 * };
 * ```
 *
 * @example Composed chart (bar + line)
 * ```typescript
 * const config: RechartsAdapterConfig = {
 *   id: 'mixed-chart',
 *   title: 'Revenue and Trend',
 *   data: [{ month: 'Jan', revenue: 100, trend: 95 }],
 *   xKey: 'month',
 *   layers: [
 *     { yKey: 'revenue', chartType: 'bar', name: 'Revenue' },
 *     { yKey: 'trend', chartType: 'line', name: 'Trend' },
 *   ],
 *   xLabel: 'Month',
 *   yLabel: 'Value',
 * };
 * ```
 */
export declare interface RechartsAdapterConfig {
    /** Unique identifier for the chart (used for DOM IDs). */
    id: string;
    /** Chart title displayed in text descriptions. */
    title?: string;
    /** Chart subtitle. */
    subtitle?: string;
    /** Chart caption. */
    caption?: string;
    /** Recharts data array. Each item is one data point with named fields. */
    data: Record<string, unknown>[];
    /**
     * Chart type for simple mode (single chart type with one or more series).
     * Mutually exclusive with `layers`.
     */
    chartType?: RechartsChartType;
    /** Key in data objects for x-axis values. */
    xKey: string;
    /**
     * Keys in data objects for y-axis values (simple mode).
     * Each key creates a separate data series.
     * Mutually exclusive with `layers`.
     */
    yKeys?: string[];
    /**
     * Layer configurations for composed charts (composed mode).
     * Each layer defines a chart type and data key.
     * Mutually exclusive with `chartType`/`yKeys`.
     */
    layers?: RechartsLayerConfig[];
    /** X-axis label. */
    xLabel?: string;
    /** Y-axis label. */
    yLabel?: string;
    /** Bar/box chart orientation. Defaults to vertical. */
    orientation?: Orientation;
    /**
     * Display names for each series in stacked/dodged/normalized bar charts.
     * Maps 1:1 with `yKeys` — the i-th fillKey names the i-th yKey.
     * When omitted, the yKey strings are used as fill labels.
     */
    fillKeys?: string[];
    /**
     * Histogram bin range configuration.
     * Required when `chartType` is `'histogram'`.
     */
    binConfig?: HistogramBinConfig;
    /**
     * Custom CSS selector override for SVG highlighting.
     *
     * By default the adapter generates selectors from Recharts' built-in
     * class names. For multi-series charts, CSS selectors cannot reliably
     * distinguish between series, so highlighting is disabled.
     *
     * To enable highlighting for multi-series charts, add a custom
     * `className` to each Recharts component and pass the selector here:
     *
     * @example
     * ```tsx
     * <Bar className="revenue-bar" dataKey="revenue" />
     * // then set selectorOverride: '.revenue-bar .recharts-bar-rectangle'
     * ```
     */
    selectorOverride?: string;
}

/**
 * Recharts chart types supported by the adapter.
 *
 * Mapping to MAIDR trace types:
 * - `'bar'` → `TraceType.BAR` — Simple bar chart
 * - `'stacked_bar'` → `TraceType.STACKED` — Stacked bar chart (Recharts `<Bar stackId="...">`)
 * - `'dodged_bar'` → `TraceType.DODGED` — Grouped/dodged bar chart (multiple `<Bar>` without stackId)
 * - `'normalized_bar'` → `TraceType.NORMALIZED` — Stacked normalized (100%) bar chart
 * - `'histogram'` → `TraceType.HISTOGRAM` — Histogram rendered as bar chart with bin ranges
 * - `'line'` → `TraceType.LINE` — Line chart
 * - `'scatter'` → `TraceType.SCATTER` — Scatter/point plot
 */
export declare type RechartsChartType = 'bar' | 'stacked_bar' | 'dodged_bar' | 'normalized_bar' | 'histogram' | 'line' | 'scatter';

/**
 * A single data series/layer configuration for composed charts.
 * Use this when a chart has multiple series of different types.
 */
export declare interface RechartsLayerConfig {
    /** Key in the data array for this series' y-values. */
    yKey: string;
    /** Chart type for this series. */
    chartType: RechartsChartType;
    /** Display name for this series (used in legends/descriptions). */
    name?: string;
}

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

/**
 * Converts Recharts configuration into MAIDR data format.
 *
 * The result is memoized: it only recomputes when individual config
 * fields change. You do **not** need to stabilize the config object
 * reference itself — the hook destructures it and tracks each field
 * independently. However, fields that are arrays or objects (`data`,
 * `yKeys`, `layers`, `fillKeys`, `binConfig`) are compared by
 * reference. Define them outside the component or wrap them in
 * `useMemo` to avoid unnecessary recomputation on every render.
 *
 * @param config - Recharts adapter configuration
 * @returns MaidrData ready to pass to `<Maidr data={...}>`
 */
export declare function useRechartsAdapter(config: RechartsAdapterConfig): MaidrData;

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