config.py

"""Centralized configuration defaults for scenario controls."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Final


@dataclass(frozen=True)
class SliderDefaults:
    """Slider configuration along with a helper to clamp values."""

    minimum: float
    maximum: float
    value: float
    step: float

    def clamp(self, candidate: float) -> float:
        """Clamp ``candidate`` to this slider's min/max bounds."""
        return max(self.minimum, min(self.maximum, candidate))


SCENARIO_DEFAULTS: Final[dict[str, SliderDefaults]] = {
    "fire_count": SliderDefaults(minimum=1, maximum=40, value=20, step=1),
    "fire_intensity": SliderDefaults(minimum=0.2, maximum=0.9, value=0.6, step=0.05),
    "building_count": SliderDefaults(minimum=1, maximum=35, value=20, step=1),
    "max_units": SliderDefaults(minimum=1, maximum=20, value=10, step=1),
}


def range_text(key: str) -> str:
    """
    Return a human-readable ``min-max`` string for any configured scenario slider.
    Primarily used in docstrings / README notes to avoid diverging documentation.
    """
    defaults = SCENARIO_DEFAULTS[key]
    step_value = float(defaults.step)
    if step_value.is_integer():
        min_val = int(defaults.minimum)
        max_val = int(defaults.maximum)
    else:
        min_val = defaults.minimum
        max_val = defaults.maximum
    return f"{min_val}-{max_val}"