import type { ApexOptions } from 'apexcharts';
/** A single chart series (one bar/line group). */
export interface ChartSeries {
    readonly name: string;
    readonly data: number[];
}
/** Chart-ready model derived from the grid's range / group / pivot aggregates. */
export interface ChartModel {
    readonly categories: string[];
    readonly series: ChartSeries[];
}
/** How the rows within one category are collapsed into a single series value. */
export type ChartAggregation = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median';
/**
 * How a category/measure chart is mapped out of a labeled grid, shared by the range and view-bound
 * model builders. Every field is optional: an empty definition reproduces the automatic default
 * (first non-numeric column = category, every numeric column = a series, summed per category), so a
 * mapping UI can seed itself from the default and only override what the user changes.
 */
export interface ChartDefinition {
    /** Column key for the category (X) axis. Defaults to the first non-numeric column. */
    readonly category?: string;
    /** Column keys to plot as series (Y). Defaults to every numeric column except the category. */
    readonly measures?: readonly string[];
    /**
     * Aggregation applied to the rows in each category. One function for all series, or a per-measure
     * map keyed by column key (unlisted measures fall back to `sum`). Defaults to `sum`.
     */
    readonly aggregation?: ChartAggregation | Readonly<Record<string, ChartAggregation>>;
    /**
     * Measure keys (a subset of {@link measures}) to plot against a **secondary** value axis (drawn on
     * the opposite side). Use when measures live on different scales, e.g. revenue vs. headcount.
     * Empty/unset keeps every series on one axis.
     */
    readonly secondaryMeasures?: readonly string[];
    /**
     * Extra series computed from a formula over the other fields (see {@link CalculatedField}), e.g.
     * a "Bonus %" of `bonus / salary * 100`. Evaluated per category over the **aggregated** values
     * (ratio of totals), appended after the measure series.
     */
    readonly calculatedFields?: readonly CalculatedField[];
}
/**
 * A chart series computed from a formula rather than a column. The formula uses **A1** references
 * where the letters map to the numeric columns in display order (`A1` = first numeric column, `B1` =
 * second, …; row is always 1 — one aggregated value per column per category). Evaluated once per
 * category over the aggregated values. See {@link ChartDefinition.calculatedFields}.
 */
export interface CalculatedField {
    /** Series name (shown in the legend). */
    readonly name: string;
    /** Formula, e.g. `bonus / salary * 100` written as `B1 / A1 * 100`. A leading `=` is optional. */
    readonly formula: string;
}
/** A chartable grid column, surfaced by `getChartFields()` to drive a mapping UI. */
export interface ChartField {
    /** Column key (matches {@link ChartDefinition} category/measures). */
    readonly key: string;
    /** Human label (the column header), also the series name for a measure. */
    readonly label: string;
    /** Whether the column holds numeric data (a candidate measure). */
    readonly numeric: boolean;
}
/** The handful of chart-formatting options users change most often (see {@link formatToApexOptions}). */
export interface ChartFormat {
    /** Series colors, in series order. */
    readonly colors?: readonly string[];
    /** Show the legend. */
    readonly legend?: boolean;
    /** Show value labels on points/bars. */
    readonly dataLabels?: boolean;
    /** Show the background gridlines. */
    readonly gridlines?: boolean;
    /** Number format applied to value labels + tooltips. `'none'` (default) leaves ApexCharts' own. */
    readonly numberFormat?: 'none' | 'currency' | 'percent' | 'thousands';
    /** Draw a dashed target/threshold line at this value on the measure axis. */
    readonly referenceLine?: number;
    /** Shade a target/tolerance region between two values on the measure axis. */
    readonly referenceBand?: {
        readonly from: number;
        readonly to: number;
    };
    /** Overlay a linear (least-squares) trend line for the first series. */
    readonly trendline?: boolean;
    /** Project this many future periods for the first series, drawn as a forecast continuation. */
    readonly forecast?: number;
    /** With a forecast, also draw upper/lower prediction bounds (see {@link linearForecastBand}). */
    readonly forecastBand?: boolean;
    /** Axis titles. Only the sides you set are drawn (cartesian charts only). */
    readonly axisTitles?: {
        readonly x?: string;
        readonly y?: string;
    };
}
/**
 * Least-squares linear fit of `values` against their index (0, 1, 2, …), returned as the predicted
 * y for each index — i.e. the straight trend line through the series. A flat line (mean) when the
 * x-variance is zero; empty in, empty out.
 */
export declare function linearTrend(values: readonly number[]): number[];
/**
 * Project `periods` future values by extending the least-squares fit of `values` past its end
 * (indices n, n+1, …). Empty when `periods <= 0` or there is nothing to fit. Pairs with
 * {@link linearTrend} to draw a forecast continuation.
 */
export declare function linearForecast(values: readonly number[], periods: number): number[];
/**
 * Prediction band around {@link linearForecast}: `{ upper, lower }`, one entry per future period.
 * The half-width is a ~95% prediction interval derived from the fit's residual standard error,
 * widening the further out the period is. Collapses to the point forecast (zero width) when there
 * are too few points to estimate spread. Empty in, empty out.
 */
export declare function linearForecastBand(values: readonly number[], periods: number): {
    upper: number[];
    lower: number[];
};
/**
 * Translate a {@link ChartFormat} into a partial {@link ApexOptions} overlay. Only the fields the
 * caller actually set are emitted, so an empty format is a no-op and merging it never clobbers the
 * author's own options. Number formatting is applied to **data labels and tooltips** (not axes), so
 * it can't collide with a caller's multi-axis `yaxis` array. Circular charts (pie/donut) keep their
 * percentage labels. `type` decides only the circular-vs-cartesian branch.
 */
export declare function formatToApexOptions(format: ChartFormat, type?: ChartType | 'auto'): Partial<ApexOptions>;
/**
 * Build a **dual value-axis** `yaxis` config: series named in `secondaryNames` bind to a second axis
 * drawn on the opposite side, the rest share the primary axis. Both axes carry the number formatter
 * (so labels match) and their optional titles. Returns `[]` when nothing is on the secondary axis —
 * the caller then keeps its single-axis path. ApexCharts binds a whole group of series to one axis
 * via an array `seriesName`, so primary series share one scale and secondary series share another
 * (rather than each auto-scaling on its own axis).
 */
export declare function buildValueAxes(seriesNames: readonly string[], secondaryNames: readonly string[], opts?: {
    numberFormat?: ChartFormat['numberFormat'];
    primaryTitle?: string;
    secondaryTitle?: string;
}): Record<string, unknown>[];
/**
 * Friendly chart types. Mapped to ApexCharts shapes internally (see
 * {@link chartModelToApexOptions}); `'column'`/`'bar'` distinguish vertical vs horizontal,
 * `'combo'` mixes per-series types.
 */
export type ChartType = 'column' | 'bar' | 'line' | 'area' | 'pie' | 'donut' | 'scatter' | 'radar' | 'combo';
/** Options for {@link renderApexChart} / {@link chartModelToApexOptions}. */
export interface RenderChartOptions {
    /** Friendly chart type, or `'auto'` for the recommended-type heuristic. Defaults to `'column'`. */
    readonly type?: ChartType | 'auto';
    readonly title?: string;
    /** Pixel height, or a CSS length like `'100%'` to fill the container. */
    readonly height?: number | string;
    /**
     * Per-series type overrides for `type: 'combo'`, aligned by series index. Defaults to series 0 =
     * column, the rest = line.
     */
    readonly comboTypes?: ChartType[];
    /** Extra ApexCharts options, deep-merged last (escape hatch). */
    readonly apexOptions?: Partial<ApexOptions>;
}
/**
 * Excel-style "Recommended Charts" lite: pick a sensible default type from the model shape.
 * One series over a handful of categories reads best as a pie; a long category axis as a line;
 * otherwise a column chart.
 */
export declare function recommendChartType(model: ChartModel): ChartType;
/**
 * Pure transform: a {@link ChartModel} + options into an ApexCharts options object. No ApexCharts
 * import, so it is unit-tested directly. Handles the cartesian vs circular (pie/donut) data shapes
 * and combo per-series types, resolves `type: 'auto'`, and deep-merges `apexOptions` last so the
 * caller can override anything.
 */
export declare function chartModelToApexOptions(model: ChartModel, options?: RenderChartOptions): ApexOptions;
/**
 * Render a {@link ChartModel} into `container` using ApexCharts and return the instance (so the
 * caller can `updateOptions`/`destroy`).
 *
 * ApexCharts is **dynamically imported** so it only loads when a chart is actually drawn (the base
 * enterprise bundle stays lean). Render into a light-DOM container (not the grid's shadow root):
 * ApexCharts injects global styles and measures layout, which is unreliable inside shadow DOM.
 */
export declare function renderApexChart(container: HTMLElement, model: ChartModel, options?: RenderChartOptions): Promise<import("apexcharts")>;