"""
states/State.py - Abstract base class for state machine
"""
from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, Optional, Dict

if TYPE_CHECKING:
    from Robot import Robot


class State(ABC):
    """Abstract base class for all robot states."""

    @abstractmethod
    def enter(self, robot: "Robot") -> None:
        """Called once when entering the state."""
        pass

    @abstractmethod
    def execute(self, robot: "Robot") -> Optional[str]:
        """
        Called every control loop tick.
        Returns Optional[str] containing the name of the next state if transitioning,
        or None to stay in the current state.
        """
        pass

    @abstractmethod
    def exit(self, robot: "Robot") -> None:
        """Called once when exiting the state."""
        pass


# Registry mapping state key names to state instances
STATE_REGISTRY: Dict[str, State] = {}