"""
What a renderer is given.
"""

from dataclasses import dataclass

import numpy as np


@dataclass
class PlotContext:
    """
    Everything a renderer needs: the oriented data, the plan describing how to
    lay it out, and the presentation options.

    `data` is already materialized and, for two-dimensional plots, already
    transposed into (y, x) order, so renderers never reason about dimension
    order themselves.
    """
    varname: str
    data: np.ndarray
    plan: object
    label: str = ''
    units: str = None
    long_name: str = None
    colormap: str = 'jet'
    norm: object = None
    output_path: str = None
    show_topo: bool = True
    show_polar: bool = False
    show_3d: bool = False
    interactive: bool = True
    subtitle: str = ''
    globe: object = None      # GlobeOptions, when a 3D view may be drawn
    frames: np.ndarray = None  # every step of an animated dimension, that axis first
    frame_dim: str = None      # which dimension `frames` runs over
    frame_axis: object = None  # that dimension's Axis, so frames carry their value
    fps: int = 12              # frames per second of animated output
    composite: object = None   # an overlay.Composite, when several variables share the figure
    figsize: tuple = None      # --figsize, overriding each plot kind's own default
    dpi: int = None            # --dpi, for saved output only
    title_override: str = None  # --title, used verbatim
    interpolate: bool = True   # smooth the field between cell centres, or draw the cells
    overlay_style: str = 'blend'  # how --overlay layers share the figure
    overlay_scale: str = 'own'  # whether panels share one colour scale
    panel: object = None       # a panel grid, when one figure holds several plots

    @property
    def title(self):
        if self.title_override:
            return self.title_override
        base = self.long_name or self.varname
        return f"{base}{f' - {self.subtitle}' if self.subtitle else ''}"

    def titled(self, suffix):
        """
        The figure's title with a renderer's own words after it - "profile",
        "over time", "(soildepth vs lat)".

        A title the user asked for is used exactly as given. Someone who writes
        `--title "Fig. 3"` for a paper means "Fig. 3", not "Fig. 3 profile", and
        every renderer decorating the title in its own way is precisely why this
        has to be asked in one place.
        """
        if self.title_override:
            return self.title_override
        return f"{self.title} {suffix}" if suffix else self.title