"""Central colour registry for ``_repr_html_`` methods.

This module defines the colour scheme for HTML representations of pitchspace types
(pitch, interval, pitch class, interval class) and scale degree types. Colours are
centralized here for consistency and future user customization.

Design Principles
-----------------
1. **Scale degrees** use semantically meaningful colours:

   - **Major** collection types (major, ionian): blue
   - **Minor** collection types (natural_minor, harmonic_minor, etc.): red
   - **Other** collection types (dorian, phrygian, etc.): dark grey
   - **Generic** scale degrees (GSD, GSDI — no collection type): light grey

2. **Pitch and interval types** use three colour families:

   - **Specific** (SPC, SP, SIC, SI): green family
   - **Enharmonic** (EPC, EP, EIC, EI): purple family
   - **Generic** (GPC, GP, GIC, GI): orange family

3. **Within each colour family**, shades distinguish:

   - Pitch class: dark + saturated
   - Pitch (with octave): dark + less saturated
   - Interval class: light + saturated
   - Interval (with octave): light + less saturated

4. **Blue and red are reserved** for scale degrees (major/minor).

Future Customization
--------------------
The dictionaries in this module are designed for future programmatic modification.
Users will be able to override colours at runtime by modifying the registry dicts.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from flexohr.harmony.harmony_enums import CollectionType


# ══════════════════════════════════════════════════════════════════════════════
#  Pitchspace Type Colours
# ══════════════════════════════════════════════════════════════════════════════

#: Colour registry for pitch and interval types.
#: Keys are type abbreviations; values are hex colour strings.
#: Designed for future user customization via direct dict modification.
PITCHSPACE_COLORS: dict[str, str] = {
    # Specific (Green family)
    "SPC": "#166534",  # dark, saturated
    "SP": "#3f6212",  # dark, less saturated
    "SIC": "#4ade80",  # light, saturated
    "SI": "#86efac",  # light, less saturated
    # Enharmonic (Purple family)
    "EPC": "#7c3aed",  # dark, saturated
    "EP": "#6d28d9",  # dark, less saturated
    "EIC": "#c4b5fd",  # light, saturated
    "EI": "#ddd6fe",  # light, less saturated
    # Generic (Orange family)
    "GPC": "#c2410c",  # dark, saturated
    "GP": "#9a3412",  # dark, less saturated
    "GIC": "#fdba74",  # light, saturated
    "GI": "#fed7aa",  # light, less saturated
}


# ══════════════════════════════════════════════════════════════════════════════
#  Scale Degree Colours
# ══════════════════════════════════════════════════════════════════════════════

#: Colour for generic scale degrees (GSD, GSDI) which have no collection type.
GENERIC_SCALE_DEGREE_COLOR: str = "#9ca3af"

#: Colour for minor-mode scale degrees (SD, SDI with minor collection types).
MINOR_SCALE_DEGREE_COLOR: str = "#dc2626"

#: Colour for major-mode scale degrees (SD, SDI with major collection types).
MAJOR_SCALE_DEGREE_COLOR: str = "#2563eb"

#: Default colour for other scale degrees (non-major/minor modes like dorian).
OTHER_SCALE_DEGREE_COLOR: str = "#4b5563"

#: Direct mapping from CollectionType values to scale degree colours.
#: This dict is the primary lookup for ``get_scale_degree_color()``.
#: Designed for future user customization: users can add entries for new
#: collection types or override existing ones.
COLLECTION_TYPE_COLORS: dict[str, str] = {
    # Major family
    "major": MAJOR_SCALE_DEGREE_COLOR,
    "ionian": MAJOR_SCALE_DEGREE_COLOR,
    "M": MAJOR_SCALE_DEGREE_COLOR,
    # Minor family
    "natural_minor": MINOR_SCALE_DEGREE_COLOR,
    "harmonic_minor": MINOR_SCALE_DEGREE_COLOR,
    "melodic_minor": MINOR_SCALE_DEGREE_COLOR,
    "aeolian": MINOR_SCALE_DEGREE_COLOR,
    "m": MINOR_SCALE_DEGREE_COLOR,
    "hm": MINOR_SCALE_DEGREE_COLOR,
    "mm": MINOR_SCALE_DEGREE_COLOR,
    "aeo": MINOR_SCALE_DEGREE_COLOR,
    # Other modes default to OTHER_SCALE_DEGREE_COLOR via fallback
}


def get_scale_degree_color(collection_type: CollectionType | None) -> str:
    """Return the appropriate colour for a scale degree.

    Parameters
    ----------
    collection_type
        The collection type of the scale degree, or ``None`` for generic
        scale degrees (GSD, GSDI).

    Returns
    -------
    str
        Hex colour string (e.g., ``"#2563eb"``).

    Examples
    --------
    >>> from flexohr.harmony.harmony_enums import CollectionType
    >>> get_scale_degree_color(CollectionType.major)
    '#2563eb'
    >>> get_scale_degree_color(CollectionType.natural_minor)
    '#dc2626'
    >>> get_scale_degree_color(CollectionType.dorian)
    '#4b5563'
    >>> get_scale_degree_color(None)
    '#9ca3af'
    """
    if collection_type is None:
        return GENERIC_SCALE_DEGREE_COLOR
    return COLLECTION_TYPE_COLORS.get(collection_type.value, OTHER_SCALE_DEGREE_COLOR)
