/**
 * Normalised report payload shared by every report and every export
 * format. Builders produce a ReportPayload; exporters (csv/xlsx/pdf)
 * consume it. Keeping one shape decouples report content from output
 * format — adding a new report doesn't require touching any exporter
 * and vice-versa.
 */

export interface ReportPayload {
  /** Display title (e.g. "Sales performance"). Used as the PDF cover
   *  title + xlsx workbook name + CSV filename root. */
  title: string;
  /** Period the report covers. Rendered on the PDF cover; baked into
   *  the CSV/xlsx filename. */
  range: { from: Date; to: Date };
  /** Optional one-line subtitle. */
  description?: string;
  /** Filename slug (kebab/snake). Used as the basis for the downloaded
   *  file's name; the format extension is appended by the exporter. */
  filenameSlug: string;
  /** Single-number KPI cards rendered at the top of every output. The
   *  CSV exporter emits these as the first section; xlsx puts them on
   *  a "Summary" sheet; PDF renders them as a banner. */
  kpis: ReportKpi[];
  /** Tabular sections. Each section becomes a CSV block (with a blank
   *  line between sections), an xlsx sheet, and a PDF table. */
  sections: ReportSection[];
}

export interface ReportKpi {
  label: string;
  value: string | number;
  /** Optional secondary line under the value (e.g. "based on 12 won deals"). */
  hint?: string;
}

export interface ReportSection {
  /** Human-readable section title. xlsx uses it as the sheet name
   *  (truncated to 31 chars per Excel's limit); CSV writes it as a
   *  comment row. */
  title: string;
  /** Ordered column definitions. The CSV header row + xlsx column
   *  headers + PDF table columns come from this. */
  columns: ReportColumn[];
  /** Row data. Each row is an object keyed by column.key. */
  rows: Array<Record<string, unknown>>;
}

export interface ReportColumn {
  /** Object key used to extract the cell value from a row. */
  key: string;
  /** Display header. */
  label: string;
  /** Optional formatter applied per cell at export time. Default is
   *  String(value). */
  format?: (value: unknown) => string;
  /** Alignment hint for xlsx + PDF (CSV ignores). */
  align?: 'left' | 'right' | 'center';
}

/** What a sender produces; what an exporter returns. */
export interface ExportResult {
  filename: string;
  /** MIME type appropriate to the format. */
  mimeType: string;
  /** Raw bytes (xlsx/pdf) or UTF-8 string (csv). The caller serialises
   *  to a download via createObjectURL / Blob. */
  body: Blob;
}
