import type { WidgetSeries } from '../types'

/**
 * Series metadata rendered as a coloured avatar at the start of a row.
 *
 * Type alias of the cross-widget {@link WidgetSeries} shape so the same
 * `{ name, color? }` object can drive Formula avatars, Spread avatars,
 * Category legends, and echart-widget legends with no per-widget shape
 * gymnastics. Kept as a named export for backwards compatibility.
 */
export type FormulaSeries = WidgetSeries

export type DeltaSeverity = 'positive' | 'negative' | 'neutral'

/** Comparative delta rendered as a coloured chip on the right of a row. */
export interface FormulaDelta {
  /** Numeric magnitude. Default formatting renders as a percent (e.g. `-12,3 %`). */
  value: number
  /** Pre-formatted label override (skips the default percent formatter). */
  label?: string
  /**
   * Visual treatment override. When omitted it's derived from `value`'s sign:
   * `>0 → 'positive'`, `<0 → 'negative'`, `=0 → 'neutral'`.
   */
  severity?: DeltaSeverity
}

/** A single KPI value rendered by the Formula widget. */
export interface FormulaDataItem {
  value: number
  prefix?: string
  suffix?: string
  /** Override the value's text colour (e.g. `'success.main'`). */
  color?: string
  /** Optional series indicator — coloured avatar with first letter of `name`. */
  series?: FormulaSeries
  /** Optional caption rendered below the value. */
  note?: string
  /** Optional comparative delta chip rendered to the right of the row. */
  delta?: FormulaDelta
}

/**
 * Formula widget data — an array of KPI items rendered top-to-bottom. A common
 * "single big number" widget is just `[{ value: 123 }]`. Multi-series usage
 * sets `series`, `note`, and/or `delta` per item.
 */
export type FormulaWidgetData = readonly FormulaDataItem[]