gallery

class Gallery(Component):
    """``images`` in a grid; a keyed collection captions each picture with its key.

    Built with ``of``, each picture links to its entry's page; given plainly,
    the pictures link nowhere. An entry with no picture is left out.

    ```python
    cg.ui.Gallery(target.sessions.photo)  # captioned by capture time
    cg.ui.Gallery(target.sessions.values()[-1].images)
    cg.ui.Gallery([target.reference, target.sessions.values()[-1].photo])
    cg.ui.Gallery.of(target.sessions, lambda s: thumbnail(s.photo))
    ```
    """

    images: list[StillImageFile] | Map | Array
    entries: Entries | None = None

    @classmethod
    def of[K, E](
        cls,
        container: Map[K, E] | Array[E],
        image: Callable[[E], StillImageFile | None],
    ) -> Self:
        """A gallery of ``image`` over ``container``'s elements, each linked to its entry's page.

        Args:
            container: A ``Map`` or ``Array``, such as ``target.sessions``.
            image: The picture for one element — any still image, such as a
                thumbnail; ``None`` (or ``Missing``) leaves that entry out.

        ```python
        cg.ui.Gallery.of(target.sessions, lambda s: thumbnail(s.photo))
        ```
        """
        images, entries = entries_of(container, image, cls.__name__)
        return cls(images, entries=entries)

    def html(self, render: Render) -> str:
        """A grid of figures, one per image."""
        items = items_of(self.images)
        hrefs = item_hrefs(render, self.entries, len(items))
        return element(
            "div",
            {"class": "cg-gallery"},
            *(
                picture(render.stage(image), None if key is None else caption(key), href)
                for (_, key, image), href in zip(items, hrefs, strict=True)
            ),
        )