render

class Render:
    """One page's render context, handed to every component's ``html``.

    ``at`` is the position of the value the page is the page of; every link is
    relative to it, one ``../`` up for the ``~/`` segment the server mounts the
    page under, then the on-disk path from ``at`` to the linked position.
    """

    def __init__(self, page: DirScalar, at: object | None) -> None:
        """A render into ``page`` for the page of ``at`` (``None`` for a page of nothing)."""
        self._page = page
        self.at = position(at) if at is not None else None
        self._staged: dict[Path, str] = {}
        self._libraries: set[str] = set()
        self._emitted: set[str] = set()
        self._counters: dict[str, int] = {}

    def stage(self, file: str | os.PathLike[str]) -> str:
        """Copy ``file`` (or a directory) under ``files/`` and return its relative href.

        Files are numbered in the order they are first staged; the same source
        staged twice is copied once.

        ```python
        assert render.stage(session.photo) == "files/0.jpeg"
        ```
        """
        source = Path(os.path.abspath(file))
        href = self._staged.get(source)
        if href is None:
            suffix = source.suffix if source.is_file() else ""
            href = f"{FILES_DIR}/{len(self._staged)}{suffix}"
            self._page.stage(source, href)
            self._staged[source] = href
        return href

    def href(self, value: object) -> str | None:
        """The relative link to ``value``'s page, or ``None`` when it or this page has no position.

        ```python
        assert render.href(sibling) == "../../0006380070917400/"
        ```
        """
        base = position(value)
        return None if base is None else self._link(base)

    def entry_href(self, container: Map | Array, key: object) -> str | None:
        """The relative link to the page of ``container``'s entry at ``key``, or ``None``.

        ``key`` is a ``Map`` key or an ``Array`` index; the entry need not exist.

        ```python
        assert render.entry_href(journal.sessions, noon) == "../sessions/0006380070917400/"
        ```

        Raises:
            TypeError: If ``container`` is an ``Array`` and ``key`` is not an ``int``.
        """
        base = position(container)
        if base is None:
            return None
        if isinstance(container, Array):
            if not isinstance(key, int):
                raise TypeError(
                    f"{type(container).__name__} entries are indexed by int, got {key!r}"
                )
            name = index_name(key)
        else:
            key_type = container._key
            if key_type is None:
                return None
            name = key_type.key_encode(key)
        return self._link(base / name)

    def _link(self, base: Path) -> str | None:
        if self.at is None:
            return None
        parts = base.relative_to(self.at, walk_up=True).parts
        return "../" + "".join(f"{part}/" for part in parts)

    def lib(self, name: str) -> str:
        """The relative href of the shipped library file ``name`` (``"leaflet/leaflet.css"``).

        The whole library folder is copied under ``lib/`` the first time one of
        its files is asked for.

        ```python
        assert render.lib("vega/vega.min.js") == "lib/vega/vega.min.js"
        ```

        Raises:
            FileNotFoundError: If no such library ships with the package.
        """
        library = name.partition("/")[0]
        if library not in self._libraries:
            copy_library(library, Path(self._page, LIB_DIR, library))
            self._libraries.add(library)
        return f"{LIB_DIR}/{name}"

    def once(self, key: str, html: str) -> str:
        """``html`` the first time ``key`` is seen in this render, ``""`` after.

        ```python
        render.once("leaflet", element("script", {"src": render.lib("leaflet/leaflet.js")}))
        ```
        """
        if key in self._emitted:
            return ""
        self._emitted.add(key)
        return html

    def identifier(self, prefix: str) -> str:
        """A fresh element id ``cg-<prefix>-<n>``, unique within this render."""
        count = self._counters.get(prefix, 0) + 1
        self._counters[prefix] = count
        return f"cg-{prefix}-{count}"