Vdom constructor as a class-based interface

Author: Archmonger

pyproject.toml

@@ -107,6 +107,8 @@ filterwarnings = """
   ignore::DeprecationWarning:uvicorn.*
   ignore::DeprecationWarning:websockets.*
   ignore::UserWarning:tests.test_core.test_vdom
+  ignore::UserWarning:tests.test_pyscript.test_components
+  ignore::UserWarning:tests.test_utils
 """
 testpaths = "tests"
 xfail_strict = true

src/reactpy/__init__.py

@@ -19,7 +19,7 @@
     use_state,
 )
 from reactpy.core.layout import Layout
-from reactpy.core.vdom import vdom
+from reactpy.core.vdom import Vdom
 from reactpy.pyscript.components import pyscript_component
 from reactpy.utils import Ref, reactpy_to_string, string_to_reactpy
 
@@ -29,6 +29,7 @@
 __all__ = [
     "Layout",
     "Ref",
+    "Vdom",
     "component",
     "config",
     "create_context",
@@ -52,7 +53,6 @@
     "use_ref",
     "use_scope",
     "use_state",
-    "vdom",
     "web",
     "widgets",
 ]

src/reactpy/_html.py

@@ -3,7 +3,7 @@
 from collections.abc import Sequence
 from typing import TYPE_CHECKING, ClassVar, overload
 
-from reactpy.core.vdom import custom_vdom_constructor, make_vdom_constructor
+from reactpy.core.vdom import Vdom
 
 if TYPE_CHECKING:
     from reactpy.types import (
@@ -195,8 +195,8 @@ def __getattr__(self, value: str) -> VdomDictConstructor:
         if value in self.__cache__:
             return self.__cache__[value]
 
-        self.__cache__[value] = make_vdom_constructor(
-            value, allow_children=value not in NO_CHILDREN_ALLOWED_SVG
+        self.__cache__[value] = Vdom(
+            tagName=value, allow_children=value not in NO_CHILDREN_ALLOWED_SVG
         )
 
         return self.__cache__[value]
@@ -284,8 +284,8 @@ class HtmlConstructor:
 
     # ruff: noqa: N815
     __cache__: ClassVar[dict[str, VdomDictConstructor]] = {
-        "script": custom_vdom_constructor(_script),
-        "fragment": custom_vdom_constructor(_fragment),
+        "script": Vdom(tagName="script", custom_constructor=_script),
+        "fragment": Vdom(tagName="", custom_constructor=_fragment),
         "svg": SvgConstructor(),
     }
 
@@ -295,8 +295,8 @@ def __getattr__(self, value: str) -> VdomDictConstructor:
         if value in self.__cache__:
             return self.__cache__[value]
 
-        self.__cache__[value] = make_vdom_constructor(
-            value, allow_children=value not in NO_CHILDREN_ALLOWED_HTML_BODY
+        self.__cache__[value] = Vdom(
+            tagName=value, allow_children=value not in NO_CHILDREN_ALLOWED_HTML_BODY
         )
 
         return self.__cache__[value]

src/reactpy/core/vdom.py

@@ -1,9 +1,15 @@
+# pyright: reportIncompatibleMethodOverride=false
 from __future__ import annotations
 
 import json
-from collections.abc import Mapping, Sequence
-from functools import wraps
-from typing import Any, Callable, Protocol, cast
+from collections.abc import Iterable, Mapping, Sequence
+from typing import (
+    Any,
+    Callable,
+    Unpack,
+    cast,
+    overload,
+)
 
 from fastjsonschema import compile as compile_json_schema
 
@@ -12,17 +18,16 @@
 from reactpy.core._f_back import f_module_name
 from reactpy.core.events import EventHandler, to_event_handler_function
 from reactpy.types import (
+    ALLOWED_VDOM_KEYS,
     ComponentType,
+    CustomVdomConstructor,
+    EllipsisRepr,
     EventHandlerDict,
     EventHandlerType,
-    ImportSourceDict,
-    Key,
     VdomAttributes,
-    VdomChild,
     VdomChildren,
-    VdomDict,
-    VdomDictConstructor,
     VdomJson,
+    _VdomDict,
 )
 
 VDOM_JSON_SCHEMA = {
@@ -124,98 +129,83 @@ def is_vdom(value: Any) -> bool:
     )
 
 
-def vdom(tag: str, *attributes_and_children: VdomAttributes | VdomChildren) -> VdomDict:
-    """A helper function for creating VDOM elements.
-
-    Parameters:
-        tag:
-            The type of element (e.g. 'div', 'h1', 'img')
-        attributes_and_children:
-            An optional attribute mapping followed by any number of children or
-            iterables of children. The attribute mapping **must** precede the children,
-            or children which will be merged into their respective parts of the model.
-        key:
-            A string indicating the identity of a particular element. This is significant
-            to preserve event handlers across updates - without a key, a re-render would
-            cause these handlers to be deleted, but with a key, they would be redirected
-            to any newly defined handlers.
-        event_handlers:
-            Maps event types to coroutines that are responsible for handling those events.
-        import_source:
-            (subject to change) specifies javascript that, when evaluated returns a
-            React component.
-    """
-    model: VdomDict = {"tagName": tag}
+class Vdom:
+    """Class that follows VDOM spec, and exposes the user API that can create VDOM elements."""
 
-    if not attributes_and_children:
-        return model
+    def __init__(
+        self,
+        /,
+        allow_children: bool = True,
+        custom_constructor: CustomVdomConstructor | None = None,
+        **kwargs: Unpack[_VdomDict],
+    ) -> None:
+        """This init method is used to declare the VDOM dictionary default values, as well as configurable properties
+        related to the construction of VDOM dictionaries."""
+        if "tagName" not in kwargs:
+            msg = "You must specify a 'tagName' for a VDOM element."
+            raise ValueError(msg)
+        self._validate_keys(kwargs.keys())
+        self.allow_children = allow_children
+        self.custom_constructor = custom_constructor
+        self.default_values = kwargs
+
+        # Configure Python debugger attributes
+        self.__name__ = kwargs["tagName"]
+        module_name = f_module_name(1)
+        if module_name:
+            self.__module__ = module_name
+            self.__qualname__ = f"{module_name}.{kwargs['tagName']}"
+
+    @overload
+    def __call__(
+        self, attributes: VdomAttributes, /, *children: VdomChildren
+    ) -> _VdomDict: ...
 
-    attributes, children = separate_attributes_and_children(attributes_and_children)
-    key = attributes.pop("key", None)
-    attributes, event_handlers = separate_attributes_and_event_handlers(attributes)
+    @overload
+    def __call__(self, *children: VdomChildren) -> _VdomDict: ...
 
-    if attributes:
+    def __call__(
+        self, *attributes_and_children: VdomAttributes | VdomChildren
+    ) -> _VdomDict:
+        """The entry point for the VDOM API, for example reactpy.html(<WE_ARE_HERE>)."""
+        attributes, children = separate_attributes_and_children(attributes_and_children)
+        key = attributes.pop("key", None)
+        attributes, event_handlers = separate_attributes_and_event_handlers(attributes)
         if REACTPY_CHECK_JSON_ATTRS.current:
             json.dumps(attributes)
-        model["attributes"] = attributes
-
-    if children:
-        model["children"] = children
-
-    if key is not None:
-        model["key"] = key
 
-    if event_handlers:
-        model["eventHandlers"] = event_handlers
-
-    return model
-
-
-def make_vdom_constructor(
-    tag: str, allow_children: bool = True, import_source: ImportSourceDict | None = None
-) -> VdomDictConstructor:
-    """Return a constructor for VDOM dictionaries with the given tag name.
-
-    The resulting callable will have the same interface as :func:`vdom` but without its
-    first ``tag`` argument.
-    """
-
-    def constructor(*attributes_and_children: Any, **kwargs: Any) -> VdomDict:
-        model = vdom(tag, *attributes_and_children, **kwargs)
-        if not allow_children and "children" in model:
-            msg = f"{tag!r} nodes cannot have children."
+        # Run custom constructor, if defined
+        if self.custom_constructor:
+            result = self.custom_constructor(
+                key=key,
+                children=children,
+                attributes=attributes,
+                event_handlers=event_handlers,
+            )
+        # Otherwise, use the default constructor
+        else:
+            result = {
+                **({"key": key} if key is not None else {}),
+                **({"children": children} if children else {}),
+                **({"attributes": attributes} if attributes else {}),
+                **({"eventHandlers": event_handlers} if event_handlers else {}),
+            }
+
+        # Validate the result
+        if children and not self.allow_children:
+            msg = f"{self.default_values.get('tagName')!r} nodes cannot have children."
             raise TypeError(msg)
-        if import_source:
-            model["importSource"] = import_source
-        return model
-
-    # replicate common function attributes
-    constructor.__name__ = tag
-    constructor.__doc__ = (
-        "Return a new "
-        f"`<{tag}> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{tag}>`__ "
-        "element represented by a :class:`VdomDict`."
-    )
-
-    module_name = f_module_name(1)
-    if module_name:
-        constructor.__module__ = module_name
-        constructor.__qualname__ = f"{module_name}.{tag}"
+        if REACTPY_DEBUG.current:
+            self._validate_keys(result.keys())
 
-    return cast(VdomDictConstructor, constructor)
+        return cast(_VdomDict, self.default_values | result)
 
-
-def custom_vdom_constructor(func: _CustomVdomDictConstructor) -> VdomDictConstructor:
-    """Cast function to VdomDictConstructor"""
-
-    @wraps(func)
-    def wrapper(*attributes_and_children: Any) -> VdomDict:
-        attributes, children = separate_attributes_and_children(attributes_and_children)
-        key = attributes.pop("key", None)
-        attributes, event_handlers = separate_attributes_and_event_handlers(attributes)
-        return func(attributes, children, key, event_handlers)
-
-    return cast(VdomDictConstructor, wrapper)
+    @staticmethod
+    def _validate_keys(keys: Sequence[str] | Iterable[str]) -> None:
+        invalid_keys = set(keys) - ALLOWED_VDOM_KEYS
+        if invalid_keys:
+            msg = f"Invalid keys {invalid_keys} provided."
+            raise ValueError(msg)
 
 
 def separate_attributes_and_children(
@@ -224,48 +214,53 @@ def separate_attributes_and_children(
     if not values:
         return {}, []
 
-    attributes: VdomAttributes
+    _attributes: VdomAttributes
     children_or_iterables: Sequence[Any]
     if _is_attributes(values[0]):
-        attributes, *children_or_iterables = values
+        _attributes, *children_or_iterables = values
     else:
-        attributes = {}
+        _attributes = {}
         children_or_iterables = values
 
-    children: list[Any] = []
-    for child in children_or_iterables:
-        if _is_single_child(child):
-            children.append(child)
-        else:
-            children.extend(child)
+    _children: list[Any] = _flatten_children(children_or_iterables)
 
-    return attributes, children
+    return _attributes, _children
 
 
 def separate_attributes_and_event_handlers(
     attributes: Mapping[str, Any],
 ) -> tuple[VdomAttributes, EventHandlerDict]:
-    separated_attributes: VdomAttributes = {}
-    separated_event_handlers: dict[str, EventHandlerType] = {}
+    _attributes: VdomAttributes = {}
+    _event_handlers: dict[str, EventHandlerType] = {}
 
     for k, v in attributes.items():
         handler: EventHandlerType
 
         if callable(v):
             handler = EventHandler(to_event_handler_function(v))
         elif (
-            # isinstance check on protocols is slow - use function attr pre-check as a
-            # quick filter before actually performing slow EventHandlerType type check
+            # `isinstance` check on `Protocol` types is slow. We use pre-checks as an optimization
+            # before actually performing slow EventHandlerType type check
             hasattr(v, "function") and isinstance(v, EventHandlerType)
         ):
             handler = v
         else:
-            separated_attributes[k] = v
+            _attributes[k] = v
             continue
 
-        separated_event_handlers[k] = handler
+        _event_handlers[k] = handler
+
+    return _attributes, _event_handlers
 
-    return separated_attributes, separated_event_handlers
+
+def _flatten_children(children: Sequence[Any]) -> list[Any]:
+    _children: list[VdomChildren] = []
+    for child in children:
+        if _is_single_child(child):
+            _children.append(child)
+        else:
+            _children.extend(_flatten_children(child))
+    return _children
 
 
 def _is_attributes(value: Any) -> bool:
@@ -292,20 +287,5 @@ def _validate_child_key_integrity(value: Any) -> None:
                 warn(f"Key not specified for child in list {child}", UserWarning)
             elif isinstance(child, Mapping) and "key" not in child:
                 # remove 'children' to reduce log spam
-                child_copy = {**child, "children": _EllipsisRepr()}
+                child_copy = {**child, "children": EllipsisRepr()}
                 warn(f"Key not specified for child in list {child_copy}", UserWarning)
-
-
-class _CustomVdomDictConstructor(Protocol):
-    def __call__(
-        self,
-        attributes: VdomAttributes,
-        children: Sequence[VdomChild],
-        key: Key | None,
-        event_handlers: EventHandlerDict,
-    ) -> VdomDict: ...
-
-
-class _EllipsisRepr:
-    def __repr__(self) -> str:
-        return "..."

src/reactpy/transforms.py

@@ -20,7 +20,7 @@ def __init__(self, vdom: VdomDict, intercept_links: bool = True) -> None:
             if not name.startswith("_"):
                 getattr(self, name)(vdom)
 
-    def normalize_style_attributes(self, vdom: VdomDict) -> None:
+    def normalize_style_attributes(self, vdom: dict[str, Any]) -> None:
         """Convert style attribute from str -> dict with camelCase keys"""
         if (
             "attributes" in vdom