"""Base class for dashboard widgets.

A widget is a self-contained piece of the personalized dashboard that:
- decides whether it renders for a given user (`is_enabled`)
- fetches its own context (`get_context`)
- renders into a fixed page zone (kpi / actions / primary / side / footer)
"""
from __future__ import annotations

from typing import ClassVar


ZONE_KPI = "kpi"
ZONE_KPI_SCHOLARSHIP = "kpi_scholarship"
ZONE_KPI_FELLOWSHIP = "kpi_fellowship"
ZONE_ACTIONS = "actions"
ZONE_PRIMARY = "primary"
ZONE_SIDE = "side"
ZONE_FOOTER = "footer"

ZONE_ORDER: tuple[str, ...] = (
    ZONE_KPI,
    ZONE_KPI_SCHOLARSHIP,
    ZONE_KPI_FELLOWSHIP,
    ZONE_ACTIONS,
    ZONE_PRIMARY,
    ZONE_SIDE,
    ZONE_FOOTER,
)


class DashboardWidget:
    key: ClassVar[str] = ""
    zone: ClassVar[str] = ZONE_PRIMARY
    priority: ClassVar[int] = 100
    template: ClassVar[str] = ""

    # Optional: a KPI-zone widget may declare the heading (and a "view all"
    # action) for the KPI band it populates. The dashboard view picks the
    # heading from the first KPI widget that declares one; when none do, the
    # template falls back to its default heading. This lets each module label
    # its own KPI row instead of sharing one hardcoded heading.
    zone_heading: ClassVar[str] = ""
    zone_heading_url_name: ClassVar[str] = ""
    zone_heading_action_label: ClassVar[str] = "View all"

    @classmethod
    def is_enabled(cls, user) -> bool:
        return False

    def get_context(self, user) -> dict:
        return {}