"""Ergonomic slider-mode declaration for :class:`mixlar.plugin.MixlarPlugin`.

A plugin slider mode normally means overriding ``get_slider_mode`` to return a
``(mode_id, display_name)`` tuple and, optionally, ``get_slider_color`` to
return a fixed color per fader — two small methods that are almost always
just returning class-level constants (see ``get_slider_mode``/
``get_slider_color`` in ``PC Software/Plugin Examples/HttpTrigger/HttpTrigger.py``).
:class:`SliderMode` lets you declare those as plain class attributes instead::

    from mixlar import MixlarPlugin
    from mixlar.sliders import SliderMode

    class MyPlugin(SliderMode, MixlarPlugin):
        plugin_id = "my_plugin"
        slider_mode_id = "my_plugin_slider"
        slider_mode_name = "My Plugin"
        slider_color = "#0a84ff"

        def handle_slider_value(self, idx, value, pct):
            ...  # required — the mixin only covers the two getters

No decorator needed; every field is optional except ``handle_slider_value``,
which you must still override (it has real side effects, so there is nothing
sensible to auto-generate).
"""
from __future__ import annotations

from typing import Optional, Tuple


class SliderMode:
    """Mixin: derive ``get_slider_mode``/``get_slider_color`` from class attrs.

    Mix in ahead of :class:`mixlar.plugin.MixlarPlugin` so this class's methods
    take priority in the MRO::

        class MyPlugin(SliderMode, MixlarPlugin): ...

    Set ``slider_mode_id`` to opt a plugin into a slider mode at all — leaving
    it blank (the default) makes :meth:`get_slider_mode` return ``None``,
    matching the base class's "no slider mode" behaviour.
    """

    #: Unique mode id shown in the slider-mode picker's ``QComboBox`` data role.
    slider_mode_id: str = ""
    #: Human-readable label shown in the slider-mode picker.
    slider_mode_name: str = "Unnamed Mode"
    #: Optional hex color (e.g. ``"#ff4d14"``) applied to every fader in this
    #: mode. ``None``/unset falls back to the app's default fader color.
    slider_color: Optional[str] = None

    def get_slider_mode(self) -> Optional[Tuple[str, str]]:
        if not self.slider_mode_id:
            return None
        return (self.slider_mode_id, self.slider_mode_name)

    def get_slider_color(self, idx) -> Optional[str]:
        return self.slider_color

    def handle_slider_value(self, idx: int, value: int, pct: float) -> None:
        """Handle slider movement (0-100 value, 0.0-1.0 pct). Override this."""


__all__ = ["SliderMode"]
