"""Tipos para resultado granular de cada reporte.

Cada reporte devuelve un ``ReportBundle`` con:
- HTML completo (compatibilidad con flujo viejo).
- Lista de figuras (PNG + SVG en disco) con nombres canónicos.
- Lista de tablas (CSV en disco) con nombres canónicos.
- Warnings y meta para mostrar al usuario.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path
from typing import Any


@dataclass(frozen=True)
class FigureArtifact:
    name: str
    title: str
    section: str
    png_path: Path
    svg_path: Path | None = None
    html_path: Path | None = None  # versión interactiva (Plotly, autocontenida)
    caption: str = ""


@dataclass(frozen=True)
class TableArtifact:
    name: str
    title: str
    section: str
    csv_path: Path
    preview_html: str = ""


@dataclass(frozen=True)
class ReportBundle:
    report_type: str
    html_path: Path
    figures: list[FigureArtifact] = field(default_factory=list)
    tables: list[TableArtifact] = field(default_factory=list)
    warnings: list[str] = field(default_factory=list)
    meta: dict[str, Any] = field(default_factory=dict)