"""
Styling utilities for matplotlib plots.

Provides functions for consistent styling across all plotting modules,
including dark mode support for presentations and dark-themed environments.
"""


def apply_dark_style(ax, color="white"):
    """
    Apply dark-background-friendly styling to axes.

    Sets all text elements (labels, ticks, spines) to the specified color,
    making plots readable on dark backgrounds.

    Parameters
    ----------
    ax : matplotlib.axes.Axes
        The axes to style.
    color : str, optional
        Color for text and lines. Default is "white".

    Returns
    -------
    matplotlib.axes.Axes
        The styled axes (same object, returned for chaining).
    """
    # Axis labels
    ax.xaxis.label.set_color(color)
    ax.yaxis.label.set_color(color)

    # Tick labels
    ax.tick_params(colors=color, which="both")

    # Spines (the box around the plot)
    for spine in ax.spines.values():
        spine.set_edgecolor(color)

    # Title if present
    ax.title.set_color(color)

    return ax


def apply_dark_style_colorbar(cbar, color="white"):
    """
    Apply dark-background-friendly styling to a colorbar.

    Parameters
    ----------
    cbar : matplotlib.colorbar.Colorbar
        The colorbar to style.
    color : str, optional
        Color for text and lines. Default is "white".

    Returns
    -------
    matplotlib.colorbar.Colorbar
        The styled colorbar (same object, returned for chaining).
    """
    cbar.ax.yaxis.label.set_color(color)
    cbar.ax.tick_params(colors=color)
    cbar.outline.set_edgecolor(color)

    return cbar
