Types

interface AnalyseResult<T extends ChartOptions = ChartOptions> {
  /** The input options with fit series, plot lines and descriptions added. */
  options: AnalysedOptions<T>;
  /** One entry per series that carried a `fit`. */
  fits: FitOutcome[];
}

interface ChartOptions {
  series?: FittableSeries[];
  xAxis?: unknown;
  accessibility?: Record<string, unknown>;
  [key: string]: unknown;
}

interface FitOutcome {
  /** Index of the source series in the input `series` array. */
  sourceIndex: number;
  sourceName: string;
  method: FitMethod;
  /** Empty when the fit failed. */
  facts: Fact[];
  /** Sentences, one per fact, at full verbosity. */
  sentences: string[];
  /** One paragraph suitable for `accessibility.description`. */
  description: string;
  /**
   * The raw `@statili/stats` result, including `predict`.
   *
   * Facts are deliberately JSON-serialisable so they can be handed to an AI
   * pipeline as ground truth, which rules out carrying a function. Anything
   * that needs to evaluate the model outside the observed domain —
   * extrapolation, a denser curve, a hover readout — reads it from here.
   *
   * Absent when the fit failed.
   */
  stats?: RegressionSuccess | SmoothSuccess;
  /** Present when the fit could not be computed. */
  error?: { message: string; helpText: string; errorType: string };
}

interface FittableSeries {
  name?: string;
  data?: unknown;
  fit?: SeriesFit;
  [key: string]: unknown;
}

interface SeriesFit {
  method: FitMethod;
  /** Decimal places for the fitted coefficients. @default 2 */
  precision?: number;
  /** Polynomial degree. `polynomial` only. @default 2 */
  order?: number;
  /**
   * Fraction of the sample in each local neighbourhood. `loess` only.
   * @default 0.25
   */
  bandwidth?: number;
  /** R² at or above which a fit is called "moderate". @default 0.3 */
  rSquaredThresholdWeak?: number;
  /** R² at or above which a fit is called "strong". @default 0.7 */
  rSquaredThresholdStrong?: number;
  /** Axis names used when facts are rendered into prose. */
  labels?: AxisLabels;
  /** Units appended to rendered quantities. */
  units?: AxisUnits;
  /**
   * Extend the fitted curve this many steps past the last observation.
   *
   * The step size comes from the average spacing of the observed X values.
   * Extrapolation is forward only, matching what charting users expect of a
   * trend line.
   *
   * @default 0
   */
  extrapolate?: number;
  /** Options merged into the generated fit series. */
  seriesOptions?: Record<string, unknown>;
  /** Draw a plot line at any `marker` annotation the facts carry. @default true */
  showMarkers?: boolean;
  /**
   * Draw the uncertainty band as an `arearange` series behind the fit.
   *
   * Requires Highcharts' `highcharts-more` module, which supplies `arearange` —
   * hence off by default rather
// …truncated

type AnalysedOptions<T extends ChartOptions> = T & {
  accessibility?: { description?: string } & Record<string, unknown>;
  xAxis?: unknown;
};

type FitMethod =
  | "linear"
  | "polynomial"
  | "power"
  | "exponential"
  | "logarithmic"
  /** A smoother, not a fitted model — no equation, and it cannot extrapolate. */
  | "loess";