"""Shared utility functions for SolarWine."""

from __future__ import annotations

from typing import Optional


def cwsi_from_delta_t(
    leaf_temp_c: Optional[float] = None,
    air_temp_c: Optional[float] = None,
    *,
    delta_t: Optional[float] = None,
) -> float:
    """Compute CWSI proxy from leaf–air temperature differential.

    Scale: 0°C delta → CWSI=0, 10°C delta → CWSI=1.
    Clamped to [0.0, 1.0].

    Can be called with (leaf_temp_c, air_temp_c) or with delta_t= directly.
    """
    if delta_t is None:
        if leaf_temp_c is None or air_temp_c is None:
            raise ValueError("Provide (leaf_temp_c, air_temp_c) or delta_t=")
        delta_t = leaf_temp_c - air_temp_c
    return max(0.0, min(1.0, delta_t / 10.0))