component

@dataclass_transform(frozen_default=True)
class Component:
    """Base of every page component; subclass it, annotate the props, implement ``html``.

    A prop is a JSON scalar, a list or dict of them, a ``cg`` value, or another
    component; each is checked against its annotation when the component is
    built, and a path given for a file prop becomes that file scalar. A
    component given ``Missing`` for any prop is absent and renders as nothing,
    so ``cg.ui.Stat("Wind", session.weather.wind_speed_mps)`` simply leaves
    the page when no weather was recorded; a ``Missing`` item in a list prop
    is left out.

    ```python
    class Badge(cg.ui.Component):
        text: str

        def html(self, render: cg.ui.Render) -> str:
            return cg.ui.element("span", {"class": "badge"}, cg.ui.text(self.text))
    ```
    """

    _props: ClassVar[dict[str, object]] = {}

    def __init_subclass__(cls, **kwargs: object) -> None:
        """Freeze ``cls`` over its props and make its ``html`` render nothing when absent."""
        super().__init_subclass__(**kwargs)
        dataclass(frozen=True)(cls)
        cls._props = {
            name: hint
            for name, hint in get_type_hints(cls).items()
            if get_origin(hint) is not ClassVar
        }
        if "html" in cls.__dict__:
            cls.html = _nothing_when_absent(cls.__dict__["html"])

    def __post_init__(self) -> None:
        """Check every prop against its annotation, coercing where a scalar admits it.

        Raises:
            TypeError: If a prop does not fit its annotation; the message names the prop.
        """
        if not self.absent:
            for name, annotation in type(self)._props.items():
                checked = check_prop(
                    getattr(self, name), annotation, f"{type(self).__name__}.{name}"
                )
                object.__setattr__(self, name, checked)
        Build.attach(self)

    @property
    def absent(self) -> bool:
        """Whether any prop is ``Missing``, in which case the component renders as nothing."""
        return any(isinstance(getattr(self, name), _Missing) for name in type(self)._props)

    def html(self, render: Render) -> str:
        """This component as HTML, its files staged and its links resolved through ``render``.

        Raises:
            NotImplementedError: Always, on the base class.
        """
        raise NotImplementedError(f"{type(self).__name__} does not implement html()")