"""Base page class — a thin, extensible wrapper around discord.Embed."""

from __future__ import annotations

from typing import Any

from discord import Colour, Embed


class Page(Embed):
    """A single page in a paginated embed sequence.

    Subclass this to create custom page types.  It exposes the full
    ``discord.Embed`` API (``add_field``, ``set_image``, etc.) so you
    can build arbitrarily complex pages.

    Parameters
    ----------
    title : str | None
        The embed title.
    description : str | None
        The embed description / body text.
    colour : Colour | int | None
        Sidebar colour.  Accepts a ``discord.Colour`` or a raw int.
    url : str | None
        URL that the title links to.
    **kwargs
        Forwarded to ``discord.Embed.__init__``.

    Examples
    --------
    Simple page::

        page = Page(title="Hello", description="World", colour=0x00FF00)

    Custom subclass::

        class StatsPage(Page):
            def __init__(self, user_name: str, score: int):
                super().__init__(title=f"Stats for {user_name}", colour=0x3498DB)
                self.add_field(name="Score", value=str(score), inline=False)
    """

    def __init__(
        self,
        *,
        title: str | None = None,
        description: str | None = None,
        colour: Colour | int | None = None,
        url: str | None = None,
        **kwargs: Any,
    ) -> None:
        super().__init__(
            title=title,
            description=description,
            colour=colour,
            url=url,
            **kwargs,
        )
