/**
 * aeriz — focused, fast canvas charts.
 *
 * 21 chart types, single rendering core, zero dependencies.
 *
 * @packageDocumentation
 */

// ──────────────────────────────────────────────────────────────────
// Common types
// ──────────────────────────────────────────────────────────────────

/** A CSS selector or a DOM element to mount the chart into. */
export type ChartContainer = string | HTMLElement;

/** Color value — anything CSS accepts. */
export type Color = string;

/** Tick formatter used on numeric axes. Receives the raw tick value. */
export type TickFormatter = (value: number) => string;

/** Categorical tick formatter — receives the raw category label. */
export type CategoryTickFormatter = (label: string, index: number) => string;

/** Axis scale type. `time` interprets numeric values as ms since epoch. */
export type ScaleType = 'linear' | 'log' | 'time';

/** Click handler signature shared by all chart types. */
export type ClickHandler<H = unknown> = (
  hit: H | null,
  point: { x: number; y: number },
  chart: Chart<any>,
) => void;

/** A single named series of numeric values, used by category-axis charts. */
export interface Series {
  name: string;
  values: number[];
  color?: Color;
  hidden?: boolean;
}

/** A single radar-axis series — same shape as a regular Series. */
export type RadarSeries = Series;

// ──────────────────────────────────────────────────────────────────
// Per-chart datum shapes
// ──────────────────────────────────────────────────────────────────

export interface BarDatum {
  label: string;
  value: number;
  color?: Color;
}

export interface ScatterDatum {
  x: number;
  y: number;
  group?: number | string;
  color?: Color;
}

export interface BubbleDatum extends ScatterDatum {
  z: number;
}

export interface PieDatum {
  label: string;
  value: number;
  color?: Color;
}

export interface PolarDatum {
  label: string;
  value: number;
  color?: Color;
}

export interface HeatmapDatum {
  x: number;
  y: number;
  value: number;
}

export interface BoxplotDatum {
  label: string;
  min: number;
  q1: number;
  median: number;
  q3: number;
  max: number;
  outliers?: number[];
}

export interface FunnelDatum {
  label: string;
  value: number;
  color?: Color;
}

export interface TreemapDatum {
  label: string;
  value: number;
  color?: Color;
}

export interface WaterfallDatum {
  label: string;
  value: number;
  /** Anchor bar — drawn at absolute height instead of as a delta. */
  isTotal?: boolean;
  color?: Color;
}

/** A layer in a `CompositeChart`. */
export type CompositeLayer =
  | {
      type: 'bar' | 'line' | 'area';
      name: string;
      values: number[];
      color?: Color;
      /** Which y-axis the layer maps to. Default `'left'`. */
      axis?: 'left' | 'right';
    }
  | {
      type: 'scatter';
      name: string;
      values: Array<{ x: number; y: number }>;
      color?: Color;
      axis?: 'left' | 'right';
    };

// ──────────────────────────────────────────────────────────────────
// Per-chart option types
// ──────────────────────────────────────────────────────────────────

/** Options shared by every chart. */
export interface BaseChartOptions {
  /** Override the auto-resolved palette. */
  palette?: Color[];
  /** Show value labels on data points / bars (chart-dependent). */
  dataLabels?: boolean;
  /** Click handler — `hit` is the chart-specific datum or `null`. */
  onClick?: ClickHandler<any>;
}

export interface BarChartOptions extends BaseChartOptions {
  data: BarDatum[];
  yTickFormat?: TickFormatter;
  xTickFormat?: CategoryTickFormatter;
}

export interface HBarChartOptions extends BaseChartOptions {
  data: BarDatum[];
  xTickFormat?: TickFormatter;
  yTickFormat?: CategoryTickFormatter;
}

export interface LineChartOptions extends BaseChartOptions {
  data: BarDatum[];
  /** Path interpolation. Default `'smooth'`. */
  interpolation?: 'smooth' | 'linear' | 'step';
  /** Render the area under the line. */
  fill?: boolean;
  /** Highlight the last data point with a dot. */
  lastDot?: boolean;
  xScale?: ScaleType;
  yScale?: ScaleType;
  yTickFormat?: TickFormatter;
  xTickFormat?: CategoryTickFormatter;
}

export interface AreaChartOptions extends BaseChartOptions {
  categories: string[];
  series: Series[];
  /** Stack all series. Default `false`. */
  stacked?: boolean;
  yTickFormat?: TickFormatter;
  xTickFormat?: CategoryTickFormatter;
}

export interface StackedBarChartOptions extends BaseChartOptions {
  categories: string[];
  series: Series[];
  yTickFormat?: TickFormatter;
}

export interface GroupedBarChartOptions extends BaseChartOptions {
  categories: string[];
  series: Series[];
  yTickFormat?: TickFormatter;
}

export interface MultiLineChartOptions extends BaseChartOptions {
  categories: string[];
  series: Series[];
  interpolation?: 'smooth' | 'linear' | 'step';
  yTickFormat?: TickFormatter;
}

export interface ScatterChartOptions extends BaseChartOptions {
  data: ScatterDatum[];
  xScale?: ScaleType;
  yScale?: ScaleType;
  xTickFormat?: TickFormatter;
  yTickFormat?: TickFormatter;
}

export interface BubbleChartOptions extends BaseChartOptions {
  data: BubbleDatum[];
  xScale?: ScaleType;
  yScale?: ScaleType;
  xTickFormat?: TickFormatter;
  yTickFormat?: TickFormatter;
}

export interface PieChartOptions extends BaseChartOptions {
  data: PieDatum[];
  /**
   * Donut hole. Use a number (px) for fixed size, `'auto'` for proportional,
   * or omit for a solid pie.
   */
  innerRadius?: number | 'auto';
  /** Label drawn in the center of a donut. */
  totalLabel?: string;
  centerLabel?: string;
}

export interface RadarChartOptions extends BaseChartOptions {
  axes: string[];
  series: RadarSeries[];
}

export interface PolarChartOptions extends BaseChartOptions {
  data: PolarDatum[];
}

export interface GaugeChartOptions extends BaseChartOptions {
  value: number;
  /** Maximum scale value. Default `100`. */
  max?: number;
  /** Label drawn under the gauge. */
  label?: string;
  /** Suffix appended to the displayed value, e.g. `'%'`. */
  unit?: string;
}

export interface HeatmapChartOptions extends BaseChartOptions {
  xLabels: string[];
  yLabels: string[];
  data: HeatmapDatum[];
  /** Color of the lowest cell value. */
  colorLow?: Color;
  /** Color of the highest cell value. */
  colorHigh?: Color;
}

export interface BoxplotChartOptions extends BaseChartOptions {
  data: BoxplotDatum[];
  yTickFormat?: TickFormatter;
}

export interface FunnelChartOptions extends BaseChartOptions {
  data: FunnelDatum[];
}

export interface TreemapChartOptions extends BaseChartOptions {
  data: TreemapDatum[];
}

export interface SparklineOptions extends BaseChartOptions {
  /** Plain numeric series — sparklines have no axes. */
  data: number[];
  color?: Color;
  fill?: boolean;
  lastDot?: boolean;
}

export interface RealtimeChartOptions extends BaseChartOptions {
  /** Series definitions; values are pushed in over time via `push()`. */
  series: Array<{ name: string; color?: Color }>;
  /** Number of samples to keep on screen. Default `200`. */
  windowSize?: number;
  yTickFormat?: TickFormatter;
}

export interface WaterfallChartOptions extends BaseChartOptions {
  data: WaterfallDatum[];
  yTickFormat?: TickFormatter;
  /** Color for positive deltas. */
  colorUp?: Color;
  /** Color for negative deltas. */
  colorDown?: Color;
  /** Color for total / anchor bars. */
  colorTotal?: Color;
}

export interface CompositeChartOptions extends BaseChartOptions {
  categories: string[];
  layers: CompositeLayer[];
  xScale?: ScaleType;
  yLeftTickFormat?: TickFormatter;
  yRightTickFormat?: TickFormatter;
}

// ──────────────────────────────────────────────────────────────────
// Base Chart class
// ──────────────────────────────────────────────────────────────────

/**
 * Common base class for every chart.
 *
 * `O` is the concrete options shape for the subclass. Most users will
 * interact only through the typed subclasses (e.g. `BarChart`); this base
 * is exposed for advanced extension scenarios.
 */
export class Chart<O extends BaseChartOptions = BaseChartOptions> {
  constructor(container: ChartContainer, options: O);

  readonly container: HTMLElement;
  options: O;

  /** Re-resolve theme + palette from CSS variables and redraw. */
  invalidate(): void;

  /** Replace `options.data` and animate to the new state. Returns `this`. */
  setData(data: O extends { data: infer D } ? D : unknown): this;

  /** Show a loading overlay. Returns `this`. */
  setLoading(message?: string): this;
  /** Show an empty-state overlay. Returns `this`. */
  setEmpty(message?: string): this;
  /** Show an error overlay. Returns `this`. */
  setError(message?: string): this;
  /** Clear any active overlay state and resume rendering. Returns `this`. */
  clearState(): this;

  /** Tear down listeners, observers, and remove the canvas. */
  destroy(): void;
}

// ──────────────────────────────────────────────────────────────────
// Concrete chart classes
// ──────────────────────────────────────────────────────────────────

export class BarChart extends Chart<BarChartOptions> {
  constructor(container: ChartContainer, options: BarChartOptions);
}
export class HBarChart extends Chart<HBarChartOptions> {
  constructor(container: ChartContainer, options: HBarChartOptions);
}
export class LineChart extends Chart<LineChartOptions> {
  constructor(container: ChartContainer, options: LineChartOptions);
}
export class AreaChart extends Chart<AreaChartOptions> {
  constructor(container: ChartContainer, options: AreaChartOptions);
}
export class StackedBarChart extends Chart<StackedBarChartOptions> {
  constructor(container: ChartContainer, options: StackedBarChartOptions);
}
export class GroupedBarChart extends Chart<GroupedBarChartOptions> {
  constructor(container: ChartContainer, options: GroupedBarChartOptions);
}
export class MultiLineChart extends Chart<MultiLineChartOptions> {
  constructor(container: ChartContainer, options: MultiLineChartOptions);
}
export class ScatterChart extends Chart<ScatterChartOptions> {
  constructor(container: ChartContainer, options: ScatterChartOptions);
}
export class BubbleChart extends Chart<BubbleChartOptions> {
  constructor(container: ChartContainer, options: BubbleChartOptions);
}
export class PieChart extends Chart<PieChartOptions> {
  constructor(container: ChartContainer, options: PieChartOptions);
}
export class RadarChart extends Chart<RadarChartOptions> {
  constructor(container: ChartContainer, options: RadarChartOptions);
}
export class PolarChart extends Chart<PolarChartOptions> {
  constructor(container: ChartContainer, options: PolarChartOptions);
}

export class GaugeChart extends Chart<GaugeChartOptions> {
  constructor(container: ChartContainer, options: GaugeChartOptions);
  /** Animate the needle to a new value. */
  setValue(value: number): this;
}

export class HeatmapChart extends Chart<HeatmapChartOptions> {
  constructor(container: ChartContainer, options: HeatmapChartOptions);
}
export class BoxplotChart extends Chart<BoxplotChartOptions> {
  constructor(container: ChartContainer, options: BoxplotChartOptions);
}
export class FunnelChart extends Chart<FunnelChartOptions> {
  constructor(container: ChartContainer, options: FunnelChartOptions);
}
export class TreemapChart extends Chart<TreemapChartOptions> {
  constructor(container: ChartContainer, options: TreemapChartOptions);
}
export class Sparkline extends Chart<SparklineOptions> {
  constructor(container: ChartContainer, options: SparklineOptions);
}

export class RealtimeChart extends Chart<RealtimeChartOptions> {
  constructor(container: ChartContainer, options: RealtimeChartOptions);
  /**
   * Append one sample. Pass a single number for one-series charts, or an
   * array aligned with `options.series` for multi-series charts.
   */
  push(values: number | number[]): void;
  /** Drop all buffered samples. */
  clear(): void;
}

export class WaterfallChart extends Chart<WaterfallChartOptions> {
  constructor(container: ChartContainer, options: WaterfallChartOptions);
}

export class CompositeChart extends Chart<CompositeChartOptions> {
  constructor(container: ChartContainer, options: CompositeChartOptions);
}

// ──────────────────────────────────────────────────────────────────
// Engine + scheduler (advanced / extension API)
// ──────────────────────────────────────────────────────────────────

/**
 * Low-level canvas drawing primitives shared by every chart. Most users
 * will not touch this directly — extend `Chart` and use `this.engine`.
 */
export class Engine {
  constructor(canvas: HTMLCanvasElement);
  readonly canvas: HTMLCanvasElement;
  readonly ctx: CanvasRenderingContext2D;
  /** Logical width in CSS pixels (set by `resize()`). */
  readonly w: number;
  /** Logical height in CSS pixels (set by `resize()`). */
  readonly h: number;
  /** Device pixel ratio used for the backing buffer. */
  readonly dpr: number;
  resize(w: number, h: number, dpr?: number): void;
  clear(): void;
}

/**
 * Global render scheduler. Charts register themselves and are ticked on
 * `requestAnimationFrame` only when dirty.
 */
export const scheduler: {
  schedule(chart: Chart<any>): void;
  fps(): number;
  count(): number;
};

/** Current render frame rate, averaged over the last ~500 ms. */
export function getFPS(): number;

/** Number of charts currently mounted. */
export function getActiveCount(): number;

// ──────────────────────────────────────────────────────────────────
// Math helpers
// ──────────────────────────────────────────────────────────────────

/**
 * Default qualitative palette — 8 colors, brand accent first.
 *
 * Re-exported at the top level because every chart accepts a `palette`
 * option and most users only ever need this one math symbol directly.
 */
export const PALETTE: Color[];

/**
 * Pure helpers (scales, ticks, smoothing, color ops). Use as
 * `import { math } from 'aeriz'` and then `math.clamp(...)` etc.
 */
export const math: {
  readonly TAU: number;
  clamp(v: number, lo: number, hi: number): number;
  lerp(a: number, b: number, t: number): number;
  extent<T>(arr: T[], fn?: (x: T, i: number) => number): [number, number];
  niceTicks(min: number, max: number, count?: number): number[];
  niceDomain(min: number, max: number, count?: number): [number, number];
  timeNiceTicks(minMs: number, maxMs: number, count?: number): number[];
  timeFormat(stepMs: number): (timestampMs: number) => string;
  minMaxDecimate<T>(
    data: T[],
    targetCount: number,
    fn?: (d: T, i: number) => number,
  ): T[];
  shouldDecimate(n: number, pxWidth: number): boolean;
  bezierControlPoints(
    pts: Array<{ x: number; y: number }>,
    tension?: number,
  ): Array<{ c1x: number; c1y: number; c2x: number; c2y: number }>;
  springStep(
    v: number,
    target: number,
    velocity: number,
    cfg?: { stiffness?: number; damping?: number },
  ): { value: number; velocity: number; done: boolean };
  colorParse(c: Color): [number, number, number, number];
  colorAlpha(c: Color, a: number): string;
  colorMix(a: Color, b: Color, t: number): string;
  readonly PALETTE: Color[];
};

// ──────────────────────────────────────────────────────────────────
// Browser global (for the IIFE / CDN bundle)
// ──────────────────────────────────────────────────────────────────

declare global {
  interface Window {
    Aeriz?: typeof import('./index.js');
  }
}