"""Plot a 2D KDE density overlay on a matplotlib Axes using seaborn."""

from __future__ import annotations


def plot_kde_2d(
    ax: "Axes",
    xs: "list[float] | np.ndarray",
    ys: "list[float] | np.ndarray",
    cmap: str = "magma",
    alpha: float = 0.35,
    thresh: float = 0.02,
    levels: int = 30,
    bw_adjust: float = 0.6,
) -> None:
    """Plot a 2D kernel density estimate as a filled contour overlay.

    Uses seaborn.kdeplot to render a smooth density surface over the given
    scatter of (x, y) points. If either array is empty the function returns
    immediately without painting anything.

    Args:
        ax: matplotlib Axes to draw on.
        xs: X coordinates (longitude or projected x).
        ys: Y coordinates (latitude or projected y).
        cmap: Matplotlib colormap name for the density fill. Default "magma".
        alpha: Opacity of the density overlay (0–1). Default 0.35.
        thresh: Density threshold below which contours are not drawn (0–1).
            Default 0.02 removes very sparse outlier contours.
        levels: Number of contour levels. Default 30.
        bw_adjust: Bandwidth adjustment factor for the kernel. Values < 1
            produce tighter, more detailed estimates. Default 0.6.
    """
    import numpy as np  # type: ignore
    import seaborn as sns  # type: ignore

    xs_arr = np.asarray(xs)
    ys_arr = np.asarray(ys)

    if xs_arr.size == 0 or ys_arr.size == 0:
        return

    sns.kdeplot(
        x=xs_arr,
        y=ys_arr,
        ax=ax,
        cmap=cmap,
        fill=True,
        alpha=alpha,
        thresh=thresh,
        levels=levels,
        bw_adjust=bw_adjust,
    )