from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from rich.console import Console, ConsoleOptions, RenderableType

    from .help import HelpEntry, HelpPanel
    from .specs import ColumnSpec


@runtime_checkable
class Renderer(Protocol):
    """Protocol for column renderers that transform HelpEntry to display content."""

    def __call__(self, entry: "HelpEntry") -> "RenderableType": ...


@runtime_checkable
class ColumnSpecBuilder(Protocol):
    """Protocol for ColumnSpecBuilders."""

    def __call__(
        self, console: "Console", options: "ConsoleOptions", entries: list["HelpEntry"]
    ) -> tuple["ColumnSpec", ...]:
        """Build column specifications based on console settings and entries.

        Parameters
        ----------
        console : ~rich.console.Console
            The Rich console instance.
        options : ~rich.console.ConsoleOptions
            Console rendering options.
        entries : list[HelpEntry]
            List of help entries to be displayed.

        Returns
        -------
        tuple[ColumnSpec, ...]
            Tuple of column specifications for table rendering.
        """
        ...


@runtime_checkable
class HelpFormatter(Protocol):
    """Protocol for help **formatter** functions.

    It's the Formatter's job to transform a :class:`.HelpPanel` into rendered text on the display.

    Implementations may optionally provide the following methods for custom rendering of "usage" and "description". If these methods are not provided, default rendering will be used.

    .. code-block:: python

        def render_usage(self, console: Console, options: ConsoleOptions, usage: Any) -> None:
            \"\"\"Render the usage line.\"\"\"
            ...

        def render_description(self, console: Console, options: ConsoleOptions, description: Any) -> None:
            \"\"\"Render the description.\"\"\"
            ...
    """

    def __call__(
        self,
        console: "Console",
        options: "ConsoleOptions",
        panel: "HelpPanel",
    ) -> None:
        """Format and render a single help panel.

        Parameters
        ----------
        console : ~rich.console.Console
            Console to render to.
        options : ~rich.console.ConsoleOptions
            Console rendering options.
        panel : HelpPanel
            Help panel to render (commands, parameters, etc).
        """
        ...