import math
import textwrap
from collections.abc import Iterable
from operator import attrgetter
from typing import TYPE_CHECKING, Literal, Optional, Union

from attrs import evolve

from cyclopts.utils import frozen

if TYPE_CHECKING:
    from rich.box import Box
    from rich.console import Console, ConsoleOptions, RenderableType
    from rich.padding import PaddingDimensions
    from rich.panel import Panel
    from rich.style import StyleType
    from rich.table import Table

    from cyclopts.help import HelpEntry
    from cyclopts.help.protocols import Renderer


class NameRenderer:
    """Renderer for parameter/command names with optional text wrapping.

    Parameters
    ----------
    max_width : int | None
        Maximum width for wrapping. If None, no wrapping is applied.
    """

    def __init__(self, max_width: int | None = None):
        """Initialize the renderer with formatting options.

        Parameters
        ----------
        max_width : int | None
            Maximum width for wrapping. If None, no wrapping is applied.
        """
        self.max_width = max_width

    def __call__(self, entry: "HelpEntry") -> "RenderableType":
        """Render the names column with optional text wrapping.

        Parameters
        ----------
        entry : HelpEntry
            The table entry to render.

        Returns
        -------
        ~rich.console.RenderableType
            Combined names and shorts, optionally wrapped.
            Order: positive_names, positive_shorts, negative_names, negative_shorts
        """
        text = " ".join(entry.all_options)

        if self.max_width is None:
            return text

        wrapped = textwrap.wrap(
            text,
            self.max_width,
            subsequent_indent="  ",
            break_on_hyphens=False,
            tabsize=4,
        )

        return "\n".join(wrapped)


class CommandNameRenderer:
    """Renderer for command names with aliases in parentheses.

    Displays commands in argparse-style format: ``primary (alias1, alias2)``.

    Parameters
    ----------
    max_width : int | None
        Maximum width for wrapping. If None, no wrapping is applied.
    """

    def __init__(self, max_width: int | None = None):
        """Initialize the renderer with formatting options.

        Parameters
        ----------
        max_width : int | None
            Maximum width for wrapping. If None, no wrapping is applied.
        """
        self.max_width = max_width

    def __call__(self, entry: "HelpEntry") -> "RenderableType":
        """Render command name with aliases in parentheses.

        Parameters
        ----------
        entry : HelpEntry
            The table entry to render.

        Returns
        -------
        ~rich.console.RenderableType
            Primary command name with aliases in parentheses.
        """
        primary = entry.all_options[0] if entry.all_options else ""
        aliases = list(entry.all_options[1:])

        if aliases:
            text = f"{primary} ({', '.join(aliases)})"
        else:
            text = primary

        if self.max_width is None:
            return text

        wrapped = textwrap.wrap(
            text,
            self.max_width,
            subsequent_indent="  ",
            break_on_hyphens=False,
            tabsize=4,
        )

        return "\n".join(wrapped)


class DescriptionRenderer:
    """Renderer for descriptions with configurable metadata formatting.

    Parameters
    ----------
    newline_metadata : bool
        If True, display metadata (choices, env vars, defaults) on separate lines.
        If False (default), display metadata inline with the description.
    """

    def __init__(self, newline_metadata: bool = False):
        """Initialize the renderer with formatting options.

        Parameters
        ----------
        newline_metadata : bool
            If True, display metadata on separate lines instead of inline.
        """
        self.newline_metadata = newline_metadata

    def __call__(self, entry: "HelpEntry") -> "RenderableType":
        """Render parameter description with metadata annotations.

        Enriches the base description with choices, environment variables,
        default values, and required status.

        Parameters
        ----------
        entry : HelpEntry
            The table entry to render.

        Returns
        -------
        ~rich.console.RenderableType
            Description with appended metadata.
        """
        from rich.text import Text

        from cyclopts.help.inline_text import InlineText

        description = entry.description
        if description is None:
            description = InlineText(Text())
        elif not isinstance(description, InlineText):
            # Convert to InlineText if it isn't already
            if hasattr(entry.description, "__rich_console__"):
                # It's already a Rich renderable, wrap it
                description = InlineText(description)
            else:
                # Convert to Text first, then wrap in InlineText
                from rich.text import Text

                description = InlineText(Text(str(description)))

        # Collect metadata items
        metadata_items = []

        if entry.choices:
            choices_str = ", ".join(entry.choices)
            metadata_items.append(Text(rf"[choices: {choices_str}]", "dim"))

        if entry.env_var:
            env_vars_str = ", ".join(entry.env_var)
            metadata_items.append(Text(rf"[env var: {env_vars_str}]", "dim"))

        if entry.default is not None:
            metadata_items.append(Text(rf"[default: {entry.default}]", "dim"))

        if entry.required:
            metadata_items.append(Text(r"[required]", "dim red"))

        # Apply metadata based on formatting mode
        if self.newline_metadata and metadata_items:
            # Add metadata on separate lines with indentation
            from rich.console import Group as RichGroup
            from rich.text import Text

            # Create a list of renderables to group
            renderables = []

            # Add the original description first
            if description.primary_renderable:
                renderables.append(description.primary_renderable)

            # Add each metadata item without indentation
            for item in metadata_items:
                renderables.append(item)

            # Return a Rich Group that stacks these vertically
            return RichGroup(*renderables) if renderables else Text()
        else:
            # Original inline behavior
            for item in metadata_items:
                description.append(item)

            return description


class AsteriskRenderer:
    """Renderer for required parameter asterisk indicator.

    A simple renderer that displays an asterisk (*) for required parameters.
    """

    def __call__(self, entry: "HelpEntry") -> "RenderableType":
        """Render an asterisk for required parameters.

        Parameters
        ----------
        entry : HelpEntry
            The table entry to render.

        Returns
        -------
        ~rich.console.RenderableType
            An asterisk if the entry is required, empty string otherwise.
        """
        return "*" if entry.required else ""


@frozen
class ColumnSpec:
    """Specification for a single column in a help table.

    Used by :class:`~cyclopts.help.formatters.default.DefaultFormatter` to define
    how individual columns are rendered in help tables. Each column can have its
    own renderer, styling, and layout properties.

    See Also
    --------
    ~cyclopts.help.formatters.default.DefaultFormatter : The formatter that uses these specs.
    ~cyclopts.help.specs.TableSpec : Specification for the entire table.
    ~cyclopts.help.specs.PanelSpec : Specification for the outer panel.
    """

    renderer: Union[str, "Renderer"]
    """Specifies how to extract and render cell content from a :class:`~cyclopts.help.HelpEntry`.

    Can be either:

    - A string: The attribute name to retrieve from :class:`~cyclopts.help.HelpEntry` (e.g., 'names',
      'description', 'required', 'type'). The string is displayed as-is.
    - A callable: A function matching the :class:`~cyclopts.help.protocols.Renderer` protocol.
      The function receives a :class:`~cyclopts.help.HelpEntry` and should return a
      :class:`~rich.console.RenderableType` (str, :class:`~rich.text.Text`, or other Rich renderable).

    Examples::

        # String renderer - get attribute directly
        ColumnSpec(renderer="description")

        # Callable renderer - custom formatting
        def format_names(entry: HelpEntry) -> str:
            return ", ".join(entry.names) if entry.names else ""
        ColumnSpec(renderer=format_names)
    """

    header: str = ""
    """Column header text displayed at the top of the column.

    Example::

        header="Options" renders:
        ┌─────────┬─────────────┐
        │ Options │ Description │
        ├─────────┼─────────────┤
        │ --help  │ Show help   │
        └─────────┴─────────────┘
    """

    footer: str = ""
    """Column footer text displayed at the bottom of the column.

    Example::

        footer="Required" renders:
        ┌──────────┬────────────┐
        │ --help   │ Show help  │
        ├──────────┼────────────┤
        │ Required │            │
        └──────────┴────────────┘
    """

    header_style: Optional["StyleType"] = None
    """Style applied to the column header text.

    Corresponds to the ``header_style`` parameter of :meth:`rich.table.Table.add_column`.
    """

    footer_style: Optional["StyleType"] = None
    """Style applied to the column footer text.

    Corresponds to the ``footer_style`` parameter of :meth:`rich.table.Table.add_column`.
    """

    style: Optional["StyleType"] = None
    """Default style applied to all cells in this column.

    Corresponds to the ``style`` parameter of :meth:`rich.table.Table.add_column`.
    """

    justify: Literal["default", "left", "center", "right", "full"] = "left"
    """Text justification within the column.

    Corresponds to the ``justify`` parameter of :meth:`rich.table.Table.add_column`.
    """

    vertical: Literal["top", "middle", "bottom"] = "top"
    """Vertical alignment of text within cells.

    Corresponds to the ``vertical`` parameter of :meth:`rich.table.Table.add_column`.
    """

    overflow: Literal["fold", "crop", "ellipsis", "ignore"] = "ellipsis"
    """How to handle text that exceeds column width.

    Corresponds to the ``overflow`` parameter of :meth:`rich.table.Table.add_column`.
    """

    width: int | None = None
    """Fixed width for the column in characters.

    Corresponds to the ``width`` parameter of :meth:`rich.table.Table.add_column`.
    """

    min_width: int | None = None
    """Minimum width for the column in characters.

    Corresponds to the ``min_width`` parameter of :meth:`rich.table.Table.add_column`.
    """

    max_width: int | None = None
    """Maximum width for the column in characters.

    Corresponds to the ``max_width`` parameter of :meth:`rich.table.Table.add_column`.
    """

    ratio: int | None = None
    """Relative width ratio compared to other columns.

    Corresponds to the ``ratio`` parameter of :meth:`rich.table.Table.add_column`.
    """

    no_wrap: bool = False
    """Prevent text wrapping in the column.

    Corresponds to the ``no_wrap`` parameter of :meth:`rich.table.Table.add_column`.
    """

    highlight: bool | None = None
    """Enable automatic highlighting of text in the column.

    Corresponds to the ``highlight`` parameter of :meth:`rich.table.Table.add_column`.
    """

    def _render_cell(self, entry: "HelpEntry") -> "RenderableType":
        """Render the cell content based on the renderer type.

        If renderer is a string, retrieves that attribute from the entry.
        If renderer is callable, calls it with the entry.
        """
        if isinstance(self.renderer, str):
            value = attrgetter(self.renderer)(entry)
        elif callable(self.renderer):
            value = self.renderer(entry)
        else:
            value = None
        return "" if value is None else value

    def copy(self, **kwargs):
        return evolve(self, **kwargs)


# For Parameters:
AsteriskColumn = ColumnSpec(
    renderer=AsteriskRenderer(),
    header="",
    justify="left",
    width=1,
    style="red bold",
)

NameColumn = ColumnSpec(
    renderer=NameRenderer(),
    header="Option",
    justify="left",
    style="cyan",
)

DescriptionColumn = ColumnSpec(renderer=DescriptionRenderer(), header="Description", justify="left", overflow="fold")


def get_default_command_columns(
    console: "Console", options: "ConsoleOptions", entries: list["HelpEntry"]
) -> tuple[ColumnSpec, ...]:
    """Get default column specifications for command display.

    Parameters
    ----------
    console : ~rich.console.Console
        Rich console for width calculations.
    options : ~rich.console.ConsoleOptions
        Console rendering options.
    entries : list[HelpEntry]
        Command entries to display.

    Returns
    -------
    tuple[ColumnSpec, ...]
        Column specifications for command table.
    """
    max_width = math.ceil(console.width * 0.35)
    command_column = ColumnSpec(
        renderer=CommandNameRenderer(max_width=max_width),
        header="Command",
        justify="left",
        style="cyan",
        max_width=max_width,
    )

    return (
        command_column,
        DescriptionColumn,
    )


def get_default_parameter_columns(
    console: "Console", options: "ConsoleOptions", entries: list["HelpEntry"]
) -> tuple[ColumnSpec, ...]:
    """Get default column specifications for parameter display.

    Parameters
    ----------
    console : ~rich.console.Console
        Rich console for width calculations.
    options : ~rich.console.ConsoleOptions
        Console rendering options.
    entries : list[HelpEntry]
        Parameter entries to display.

    Returns
    -------
    tuple[ColumnSpec, ...]
        Column specifications for parameter table.
    """
    max_width = math.ceil(console.width * 0.35)
    name_column = ColumnSpec(
        renderer=NameRenderer(max_width=max_width),
        header="Option",
        justify="left",
        style="cyan",
        max_width=max_width,
    )

    if any(x.required for x in entries):
        return (
            AsteriskColumn,
            name_column,
            DescriptionColumn,
        )
    else:
        return (
            name_column,
            DescriptionColumn,
        )


@frozen
class TableSpec:
    """Specification for table layout and styling.

    Used by :class:`~cyclopts.help.formatters.default.DefaultFormatter` to control
    the appearance of tables that display commands and parameters. This spec defines
    table-wide properties like borders, headers, and padding.

    See Also
    --------
    ~cyclopts.help.formatters.default.DefaultFormatter : The formatter that uses these specs.
    ~cyclopts.help.specs.ColumnSpec : Specification for individual columns.
    ~cyclopts.help.specs.PanelSpec : Specification for the outer panel.
    """

    # Intrinsic table styling/config
    title: str | None = None
    """Title text displayed above the table.

    Corresponds to the ``title`` parameter of :class:`~rich.table.Table`.
    """

    caption: str | None = None
    """Caption text displayed below the table.

    Corresponds to the ``caption`` parameter of :class:`~rich.table.Table`.
    """

    style: Optional["StyleType"] = None
    """Default style applied to the entire table.

    Corresponds to the ``style`` parameter of :class:`~rich.table.Table`.
    """

    border_style: Optional["StyleType"] = None
    """Style applied to table borders.

    Corresponds to the ``border_style`` parameter of :class:`~rich.table.Table`.
    """

    header_style: Optional["StyleType"] = None
    """Default style for all table headers (can be overridden per column).

    Corresponds to the ``header_style`` parameter of :class:`~rich.table.Table`.
    """

    footer_style: Optional["StyleType"] = None
    """Default style for all table footers (can be overridden per column).

    Corresponds to the ``footer_style`` parameter of :class:`~rich.table.Table`.
    """

    box: Optional["Box"] = None
    """Box drawing style for the table borders.

    Corresponds to the ``box`` parameter of :class:`~rich.table.Table`. See :mod:`rich.box` for available styles.
    """

    show_header: bool = False
    """Whether to display column headers.

    Corresponds to the ``show_header`` parameter of :class:`~rich.table.Table`.
    """

    show_footer: bool = False
    """Whether to display column footers.

    Corresponds to the ``show_footer`` parameter of :class:`~rich.table.Table`.
    """

    show_lines: bool = False
    """Whether to show horizontal lines between rows.

    Corresponds to the ``show_lines`` parameter of :class:`~rich.table.Table`.
    """

    show_edge: bool = True
    """Whether to draw a box around the outside of the table.

    Corresponds to the ``show_edge`` parameter of :class:`~rich.table.Table`.
    """

    expand: bool = False
    """Whether the table should expand to fill available width.

    Corresponds to the ``expand`` parameter of :class:`~rich.table.Table`.
    """

    pad_edge: bool = False
    """Whether to add padding to the table edges.

    Corresponds to the ``pad_edge`` parameter of :class:`~rich.table.Table`.
    """

    padding: "PaddingDimensions" = (0, 2, 0, 0)
    """Padding around cell content (top, right, bottom, left).

    Corresponds to the ``padding`` parameter of :class:`~rich.table.Table`.
    """

    collapse_padding: bool = False
    """Whether to collapse padding when adjacent cells are empty.

    Corresponds to the ``collapse_padding`` parameter of :class:`~rich.table.Table`.
    """

    width: int | None = None
    """Fixed width for the table in characters.

    Corresponds to the ``width`` parameter of :class:`~rich.table.Table`.
    """

    min_width: int | None = None
    """Minimum width for the table in characters.

    Corresponds to the ``min_width`` parameter of :class:`~rich.table.Table`.
    """

    safe_box: bool | None = None
    """Whether to use ASCII-safe box characters for compatibility.

    Corresponds to the ``safe_box`` parameter of :class:`~rich.table.Table`.
    """

    def build(
        self,
        columns: tuple[ColumnSpec, ...],
        entries: Iterable["HelpEntry"],
        **overrides,
    ) -> "Table":
        """Construct and populate a rich.Table.

        Parameters
        ----------
        columns : tuple[ColumnSpec, ...]
            Column specifications defining the table structure.
        entries : Iterable[HelpEntry]
            Table entries to populate the table with.
        **overrides
            Per-render overrides for table settings.

        Returns
        -------
        Table
            A populated Rich Table.
        """
        # If show_header is True but all columns have empty headers, don't show the header
        # This prevents an empty line from appearing at the top of the table
        show_header = self.show_header
        if show_header and all(not col.header for col in columns):
            show_header = False

        opts = {
            "title": self.title,
            "caption": self.caption,
            "style": self.style,
            "border_style": self.border_style,
            "header_style": self.header_style,
            "footer_style": self.footer_style,
            "box": self.box,
            "show_header": show_header,
            "show_footer": self.show_footer,
            "show_lines": self.show_lines,
            "show_edge": self.show_edge,
            "expand": self.expand,
            "pad_edge": self.pad_edge,
            "padding": self.padding,
            "collapse_padding": self.collapse_padding,
            "width": self.width,
            "min_width": self.min_width,
            "safe_box": self.safe_box,
        }
        opts.update(overrides)

        from rich.table import Table

        table = Table(**opts)

        # Add columns
        for column in columns:
            col_opts = {
                "header": column.header,
                "footer": column.footer,
                "header_style": column.header_style,
                "footer_style": column.footer_style,
                "style": column.style,
                "justify": column.justify,
                "vertical": column.vertical,
                "overflow": column.overflow,
                "width": column.width,
                "min_width": column.min_width,
                "max_width": column.max_width,
                "ratio": column.ratio,
                "no_wrap": column.no_wrap,
            }
            if column.highlight is not None:
                col_opts["highlight"] = column.highlight
            table.add_column(**col_opts)

        # Add entries
        for e in entries:
            cells = [col._render_cell(e) for col in columns]
            table.add_row(*cells)

        return table

    def copy(self, **kwargs):
        return evolve(self, **kwargs)


@frozen
class PanelSpec:
    """Specification for panel (outer box) styling.

    Used by :class:`~cyclopts.help.formatters.default.DefaultFormatter` to control
    the appearance of the outer panel that wraps help sections. This spec defines
    the panel's border, title, subtitle, and overall styling.

    See Also
    --------
    ~cyclopts.help.formatters.default.DefaultFormatter : The formatter that uses these specs.
    ~cyclopts.help.specs.TableSpec : Specification for the inner table.
    ~cyclopts.help.specs.ColumnSpec : Specification for individual columns.
    """

    # Content-independent panel chrome
    title: Optional["RenderableType"] = None
    """Title text displayed at the top of the panel.

    Corresponds to the ``title`` parameter of :class:`~rich.panel.Panel`.
    """

    subtitle: Optional["RenderableType"] = None
    """Subtitle text displayed at the bottom of the panel.

    Corresponds to the ``subtitle`` parameter of :class:`~rich.panel.Panel`.
    """

    title_align: Literal["left", "center", "right"] = "left"
    """Alignment of the title text within the panel.

    Corresponds to the ``title_align`` parameter of :class:`~rich.panel.Panel`.
    """

    subtitle_align: Literal["left", "center", "right"] = "center"
    """Alignment of the subtitle text within the panel.

    Corresponds to the ``subtitle_align`` parameter of :class:`~rich.panel.Panel`.
    """

    style: Optional["StyleType"] = "none"
    """Style applied to the panel background.

    Corresponds to the ``style`` parameter of :class:`~rich.panel.Panel`.
    """

    border_style: Optional["StyleType"] = "none"
    """Style applied to the panel border.

    Corresponds to the ``border_style`` parameter of :class:`~rich.panel.Panel`.
    """

    box: Optional["Box"] = None  # Will use ROUNDED as default when building
    """Box drawing style for the panel border.

    Corresponds to the ``box`` parameter of :class:`~rich.panel.Panel`. See :mod:`rich.box` for available styles.
    Defaults to ``rich.box.ROUNDED``.
    """

    padding: "PaddingDimensions" = (0, 1)
    """Padding inside the panel (top/bottom, left/right) or (top, right, bottom, left).

    Corresponds to the ``padding`` parameter of :class:`~rich.panel.Panel`.
    """

    expand: bool = True
    """Whether the panel should expand to fill available width.

    Corresponds to the ``expand`` parameter of :class:`~rich.panel.Panel`.
    """

    width: int | None = None
    """Fixed width for the panel in characters.

    Corresponds to the ``width`` parameter of :class:`~rich.panel.Panel`.
    """

    height: int | None = None
    """Fixed height for the panel in lines.

    Corresponds to the ``height`` parameter of :class:`~rich.panel.Panel`.
    """

    safe_box: bool | None = None
    """Whether to use ASCII-safe box characters for compatibility.

    Corresponds to the ``safe_box`` parameter of :class:`~rich.panel.Panel`.
    """

    highlight: bool = False
    """Enable automatic highlighting of panel contents.

    Corresponds to the ``highlight`` parameter of :class:`~rich.panel.Panel`.
    """

    def build(self, renderable: "RenderableType", **overrides) -> "Panel":
        """Create a Panel around `renderable`. Use kwargs to override spec per render."""
        # Import box here for lazy loading
        box = self.box
        if box is None:
            from rich.box import ROUNDED

            box = ROUNDED

        opts = {
            "title_align": self.title_align,
            "subtitle_align": self.subtitle_align,
            "style": self.style,
            "border_style": self.border_style,
            "box": box,
            "padding": self.padding,
            "expand": self.expand,
            "width": self.width,
            "height": self.height,
            "safe_box": self.safe_box,
            "highlight": self.highlight,
        }
        if self.title is not None:
            opts["title"] = self.title
        if self.subtitle is not None:
            opts["subtitle"] = self.subtitle

        opts.update(overrides)

        from rich.panel import Panel

        return Panel(renderable, **opts)

    def copy(self, **kwargs):
        return evolve(self, **kwargs)