@dataclass(slots=True)
class Deck:
    """A whole deck.

    Attributes:
        title: The deck title: the title of the page, and the text of the
            generated opening slide.
        date: The deck date, shown on the opening slide and in the chrome.
        theme: The name of the theme stylesheet to link.
        slides: The slides, in the order they are shown.
        units: The units the number highlighting recognises, in any order.
        extra_css: Extra stylesheets, linked after the theme.
        extra_js: Extra scripts, loaded after `mkdeck.js`.
        reveal: Options merged into `Reveal.initialize`.
        title_slide: Whether to generate the opening title slide from `title`
            and `date`. It is left out when the first slide is itself a title
            slide (`layout="title"`), which is then the opening slide.
    """

    title: str
    date: str | None = None
    theme: str = "minimal"
    slides: list[Slide] = field(default_factory=list)
    units: list[str] = field(default_factory=lambda: list(DEFAULT_UNITS))
    extra_css: list[str] = field(default_factory=list)
    extra_js: list[str] = field(default_factory=list)
    reveal: dict[str, Any] = field(default_factory=dict)
    title_slide: bool = True

    # build and serve import inside the method body on purpose: mkdeck.build and
    # mkdeck.server both import this module, so a module-scope import would be
    # circular,
    # and `import mkdeck` should not load the file watcher.

    def build(
        self,
        out: Path | str = "site",
        *,
        source: Path | str | None = None,
        single_file: bool = False,
    ) -> Path:
        """Write this deck to an output folder.

        Building again into the same folder brings it up to date: every file is
        copied afresh, and a file the previous build wrote that this one no
        longer needs is removed.

        Args:
            out: The output folder, or the HTML file when `single_file` is set
                and the path ends in `.html`.
            source: The folder the deck's assets live in; the current directory
                when omitted.
            single_file: True to inline every stylesheet and script.

        Returns:
            The path of the written HTML document.

        Raises:
            DeckError: If the deck or a slide breaks a rule of the model, the
                source folder does not exist, the output folder is the source
                folder or its `assets` folder, or a file the deck names is
                outside the source folder.
        """
        from mkdeck.build import build_deck

        return build_deck(self, out, source=source, single_file=single_file)

    def serve(
        self,
        *,
        source: Path | str | None = None,
        host: str = "127.0.0.1",
        port: int = 5020,
        open_browser: bool = False,
        reload: bool = True,
    ) -> None:
        """Serve this deck until interrupted.

        The deck is the one in hand: it is built again, unchanged, whenever a
        file under `source` changes. The Python code that made the slides is not
        run again.

        Args:
            source: The folder the deck's assets live in; the current directory
                when omitted. It is watched, and the page reloads when a file in
                it changes.
            host: The interface to bind.
            port: The port to bind.
            open_browser: True to open the deck in a browser once it is up.
            reload: True to watch `source` and push reloads.

        Raises:
            DeckError: If the deck cannot be rendered, the source folder does
                not exist, or the port is taken.
        """
        from mkdeck.build import build_deck
        from mkdeck.server import serve

        folder = Path(source) if source is not None else Path.cwd()

        def build(root: Path, live: bool) -> None:
            build_deck(self, root, source=folder, live_reload=live)

        serve(
            build,
            watch_paths=[folder],
            host=host,
            port=port,
            open_browser=open_browser,
            reload=reload,
        )

@dataclass(slots=True)
class Slide:
    """One slide of a deck.

    Attributes:
        id: A stable identifier, emitted as `data-id`, or `None`.
        layout: How the slide is laid out; `"auto"` picks from the content.
        title: The heading, drawn above the rest of the slide. A slide that
            holds nothing else is a title slide.
        sentence: The visible headline. Inline Markdown and `$...$` math are
            allowed, and so is an HTML element, which is kept as written.
        bullets: A compact list drawn under the sentence, with the same inline
            syntax.
        math: Display formulas, one per line, drawn above the sentence.
        embeds: The figures on the slide, at most `MAX_EMBEDS` of them. A slide
            takes figures or a table, not both.
        table: The table on the slide, or `None`.
        html: Raw HTML drawn with the rest of the slide. The escape hatch.
        notes: Speaker notes, shown in reveal's presenter view.
        date: On `layout="title"`, the date that restamps every later slide.
        classes: Extra CSS classes put on the `<section>`.
    """

    id: str | None = None
    layout: Layout = "auto"
    title: str | None = None
    sentence: str | None = None
    bullets: list[str] = field(default_factory=list)
    math: list[str] = field(default_factory=list)
    embeds: list[Embed] = field(default_factory=list)
    table: Table | None = None
    html: str | None = None
    notes: str | None = None
    date: str | None = None
    classes: list[str] = field(default_factory=list)

@dataclass(slots=True)
class Embed:
    """A figure on a slide: an iframe page, an image or an animation.

    Attributes:
        src: The page or image, relative to the deck source folder. An `http` or
            `https` URL is also accepted; an absolute path is not. A query or
            fragment, as in `plot.html?seed=2`, is kept in the document and left
            off the file name.
        label: The caption drawn above the frame, or `None` for no caption.
        kind: `"iframe"`, `"image"` or `"rollout"`, or `"auto"` to pick from the
            suffix of `src`.
    """

    src: str
    label: str | None = None
    kind: EmbedKind = "auto"

@dataclass(slots=True)
class Table:
    """A table on a slide.

    Attributes:
        columns: The header cells, at least one. Each is shown with `str()`.
        rows: The body rows; every row holds one cell per column, each shown
            with `str()`.
    """

    columns: list[str]
    rows: list[list[str]]

@dataclass(frozen=True, slots=True)
class DeckSource:
    """A deck loaded from disk, ready to build or serve.

    Attributes:
        deck: The parsed deck. The frontmatter and `deck.yml` are already merged
            into its fields, so the deck alone carries the settings.
        directory: The folder holding the Markdown and its assets.
        markdown: The Markdown file the deck came from.
    """

    deck: Deck
    directory: Path
    markdown: Path

    def build(
        self, out: Path | str = "site", *, single_file: bool = False
    ) -> Path:
        """Write the deck to an output folder, with the assets it names.

        Args:
            out: The output folder, or the HTML file when `single_file` is set
                and the path ends in `.html`.
            single_file: True to inline every stylesheet and script.

        Returns:
            The path of the written HTML document.

        Raises:
            DeckError: If a slide breaks a rule of the model, the output folder
                is the deck folder, or a file the deck names is outside the deck
                folder.
        """
        return self.deck.build(
            out, source=self.directory, single_file=single_file
        )

    def serve(
        self,
        *,
        host: str = "127.0.0.1",
        port: int = 5020,
        open_browser: bool = False,
        reload: bool = True,
    ) -> None:
        """Serve the deck until interrupted.

        Read it again whenever its folder changes. While it is served from
        this machine, the text of a slide can be edited on the page, and the
        edit is written into the Markdown file.

        The first build uses `deck` as it is, but every rebuild reads the
        Markdown and `deck.yml` from disk again, so a change made to `deck` in
        Python shows only until the first edit. To serve a deck that is changed
        in Python, serve that `Deck` with `Deck.serve` instead.

        The folder is watched apart from the ones `mkdeck build`, `check` and
        `export` write into by default (`site`, `report` and `deck.pdf`).

        Args:
            host: The interface to bind.
            port: The port to bind.
            open_browser: True to open the deck in a browser once it is up.
            reload: True to watch the folder and push reloads.

        Raises:
            DeckError: If the deck cannot be rendered or the port is taken.
        """
        from mkdeck.build import (
            build_deck,  # imported here, so that `import mkdeck` loads neither
        )
        from mkdeck.server import serve  # the renderer nor the file watcher

        pending: DeckSource | None = self

        def build(root: Path, live: bool) -> None:
            nonlocal pending
            current, pending = (
                pending or load_source(self.markdown),
                None,
            )  # the first build reuses the deck in hand
            build_deck(
                current.deck,
                root,
                source=current.directory,
                live_reload=live,
                editable=True,
            )

        serve(
            build,
            watch_paths=[self.directory],
            host=host,
            port=port,
            open_browser=open_browser,
            reload=reload,
            edit_file=self.markdown,
        )

class DeckError(Exception):
    """A deck could not be read, validated or rendered.

    The string form of the error is `<source>: <slide>: <message>`, with the
    parts that are known. Name the slide with `mkdeck.model.slide_name` so that
    every message names it the same way.

    Attributes:
        message: What went wrong and what the author should do about it.
        slide: The offending slide, already named, or `None` for a deck-level
            problem.
        source: The deck file or folder the problem came from, or `None`.
    """

    def __init__(
        self,
        message: str,
        *,
        slide: str | None = None,
        source: Path | str | None = None,
    ) -> None:
        """Create the error.

        Args:
            message: What went wrong and what the author should do about it.
                Write it as a complete sentence with its own subject, because it
                is also shown without the prefix, for example `"This slide has 3
                embeds, but a slide takes at most 2; move one onto a new
                slide."`.
            slide: The offending slide, named by `mkdeck.model.slide_name`.
            source: The deck file or folder the problem came from.
        """
        self.message = message
        self.slide = slide
        self.source = str(source) if source is not None else None
        prefix = ": ".join(part for part in (self.source, self.slide) if part)
        super().__init__(f"{prefix}: {message}" if prefix else message)

class DeckWarning(UserWarning):
    """A problem that leaves the deck usable.

    An embed that is not on disk is one such problem.
    """

@dataclass(frozen=True)
class Converted:
    """Where one conversion put its files.

    Attributes:
        rollout: The written ``.rollout``.
        meshes: The shared ``.meshes`` the rollout points at.
        shared: True when the mesh file was already there, written by an earlier
            run of the same model.
    """

    rollout: Path
    meshes: Path
    shared: bool

class NotBraxPage(DeckError):  # noqa: N818 - a case for the caller to choose on, not a failure name
    """The page is not a Brax playback page, which is not always a mistake.

    An assets folder normally mixes playback pages with plots, so a caller
    converting a batch may want to skip these and still fail on the rest.
    """