"""System color-scheme (light / dark mode) tracking.

The platform screen host publishes the operating system's current
appearance here (Android: ``Configuration.uiMode``; iOS:
``UITraitCollection.userInterfaceStyle``), and components read it back
through [`use_color_scheme`][pythonnative.use_color_scheme] or
[`use_theme`][pythonnative.use_theme], both of which re-render when
the scheme changes.

Apps can also *override* the scheme (e.g. an in-app appearance
setting) with [`set_color_scheme`][pythonnative.appearance.set_color_scheme];
the override wins over the system value until cleared with ``None``.

Example:
    >>> from pythonnative import appearance
    >>> appearance.get_color_scheme()
    'light'
    >>> appearance.set_color_scheme("dark")   # app-level override
    >>> appearance.get_color_scheme()
    'dark'
    >>> appearance.set_color_scheme(None)     # follow the system again
"""

from __future__ import annotations

import threading
from typing import Callable, List, Literal, Optional

ColorScheme = Literal["light", "dark"]
"""The two supported appearance values."""

_system_scheme: str = "light"
_override_scheme: Optional[str] = None

_subscribers: List[Callable[[], None]] = []
_subscribers_lock = threading.Lock()


def _notify_subscribers() -> None:
    """Invoke every registered subscriber, swallowing exceptions."""
    with _subscribers_lock:
        callbacks = list(_subscribers)
    for cb in callbacks:
        try:
            cb()
        except Exception:
            pass


def subscribe(callback: Callable[[], None]) -> Callable[[], None]:
    """Register ``callback`` to fire whenever the effective scheme changes.

    Returns an unsubscribe function. Threadsafe.
    """
    with _subscribers_lock:
        _subscribers.append(callback)

    def _unsub() -> None:
        with _subscribers_lock:
            try:
                _subscribers.remove(callback)
            except ValueError:
                pass

    return _unsub


def _coerce(scheme: object) -> Optional[str]:
    if scheme in ("light", "dark"):
        return str(scheme)
    return None


def set_system_color_scheme(scheme: str) -> None:
    """Publish the operating system's current scheme.

    Called by the platform screen host on create/resume and whenever
    the system reports an appearance change. Invalid values are
    ignored. Subscribers are only notified when the *effective* scheme
    (after any app override) actually changes.
    """
    global _system_scheme
    coerced = _coerce(scheme)
    if coerced is None or coerced == _system_scheme:
        return
    effective_before = get_color_scheme()
    _system_scheme = coerced
    if get_color_scheme() != effective_before:
        _notify_subscribers()


def set_color_scheme(scheme: Optional[str]) -> None:
    """Set (or clear) the app-level scheme override.

    Args:
        scheme: ``"light"`` or ``"dark"`` to force that appearance
            regardless of the system setting, or ``None`` to follow
            the system again.
    """
    global _override_scheme
    coerced = _coerce(scheme) if scheme is not None else None
    if scheme is not None and coerced is None:
        return
    effective_before = get_color_scheme()
    _override_scheme = coerced
    if get_color_scheme() != effective_before:
        _notify_subscribers()


def get_color_scheme() -> str:
    """Return the effective scheme: the app override if set, else the system value."""
    return _override_scheme if _override_scheme is not None else _system_scheme


def get_system_color_scheme() -> str:
    """Return the system-reported scheme, ignoring any app override."""
    return _system_scheme


def reset_color_scheme() -> None:
    """Reset to system ``"light"`` with no override. Intended for tests."""
    global _system_scheme, _override_scheme
    _system_scheme = "light"
    _override_scheme = None