initial work to unify vdom constructor interface

Author: rmorshea

.github/workflows/test.yml

@@ -23,7 +23,7 @@ jobs:
       session-name: test_python_suite
       session-arguments: --maxfail=3 --no-cov
       runs-on-array: '["ubuntu-latest", "macos-latest", "windows-latest"]'
-      python-version-array: '["3.7", "3.8", "3.9", "3.10"]'
+      python-version-array: '["3.8", "3.9", "3.10", "3.11"]'
   docs:
     uses: ./.github/workflows/.nox-session.yml
     with:

src/client/packages/idom-client-react/src/element-utils.js

@@ -22,18 +22,16 @@ export function createElementAttributes(model, sendEvent) {
 
   if (model.eventHandlers) {
     for (const [eventName, eventSpec] of Object.entries(model.eventHandlers)) {
-      attributes[eventName] = createEventHandler(
-        eventName,
-        sendEvent,
-        eventSpec
-      );
+      attributes[eventName] = createEventHandler(sendEvent, eventSpec);
     }
   }
 
-  return attributes;
+  return Object.fromEntries(
+    Object.entries(attributes).map(([key, value]) => [snakeToCamel(key), value])
+  );
 }
 
-function createEventHandler(eventName, sendEvent, eventSpec) {
+function createEventHandler(sendEvent, eventSpec) {
   return function () {
     const data = Array.from(arguments).map((value) => {
       if (typeof value === "object" && value.nativeEvent) {
@@ -54,3 +52,9 @@ function createEventHandler(eventName, sendEvent, eventSpec) {
     });
   };
 }
+
+function snakeToCamel(str) {
+  return str
+    .toLowerCase()
+    .replace(/([-_][a-z])/g, (group) => group.toUpperCase().replace("_", ""));
+}

src/idom/core/component.py

@@ -1,65 +1,84 @@
 from __future__ import annotations
 
 import inspect
+from collections.abc import Sequence
 from functools import wraps
-from typing import Any, Callable, Dict, Optional, Tuple
+from typing import Any, Callable
 
-from .types import ComponentType, VdomDict
+from .types import Key, RenderResult
+from .vdom import flatten_children
 
 
-def component(
-    function: Callable[..., ComponentType | VdomDict | str | None]
-) -> Callable[..., Component]:
+def component(function: Callable[..., RenderResult]) -> Callable[..., Component]:
     """A decorator for defining a new component.
 
     Parameters:
         function: The component's :meth:`idom.core.proto.ComponentType.render` function.
     """
     sig = inspect.signature(function)
 
-    if "key" in sig.parameters and sig.parameters["key"].kind in (
-        inspect.Parameter.KEYWORD_ONLY,
-        inspect.Parameter.POSITIONAL_OR_KEYWORD,
-    ):
+    if [
+        param.name
+        for param in sig.parameters.values()
+        if param.kind is inspect.Parameter.POSITIONAL_OR_KEYWORD
+        or param.kind is inspect.Parameter.POSITIONAL_ONLY
+    ]:
+        raise TypeError(
+            "Position-only and positional-or-keyword parameters are disallowed - "
+            "use variable positional arguments to define whether this component has "
+            "children and keyword-only to define its attributes."
+        )
+
+    if "key" in sig.parameters:
         raise TypeError(
             f"Component render function {function} uses reserved parameter 'key'"
         )
 
     @wraps(function)
-    def constructor(*args: Any, key: Optional[Any] = None, **kwargs: Any) -> Component:
-        return Component(function, key, args, kwargs, sig)
+    def constructor(
+        *children: Any, key: Key | None = None, **attributes: Any
+    ) -> Component:
+        return Component(function, key, flatten_children(children), attributes, sig)
 
     return constructor
 
 
 class Component:
     """An object for rending component models."""
 
-    __slots__ = "__weakref__", "_func", "_args", "_kwargs", "_sig", "key", "type"
+    __slots__ = (
+        "__weakref__",
+        "_func",
+        "_children",
+        "_attributes",
+        "_sig",
+        "key",
+        "type",
+    )
 
     def __init__(
         self,
-        function: Callable[..., ComponentType | VdomDict | str | None],
-        key: Optional[Any],
-        args: Tuple[Any, ...],
-        kwargs: Dict[str, Any],
+        function: Callable[..., RenderResult],
+        key: Key | None,
+        children: Sequence[Any],
+        attributes: dict[str, Any],
         sig: inspect.Signature,
     ) -> None:
         self.key = key
         self.type = function
-        self._args = args
-        self._kwargs = kwargs
+        self._children = children
+        self._attributes = attributes
         self._sig = sig
 
-    def render(self) -> ComponentType | VdomDict | str | None:
-        return self.type(*self._args, **self._kwargs)
+    def render(self) -> RenderResult:
+        return self.type(*self._children, **self._attributes)
 
     def should_render(self, new: Component) -> bool:
         return True
 
     def __repr__(self) -> str:
         try:
-            args = self._sig.bind(*self._args, **self._kwargs).arguments
+            args = self._sig.bind(*self._children, **self._attributes).arguments
         except TypeError:
             return f"{self.type.__name__}(...)"
         else:

src/idom/core/events.py

@@ -41,7 +41,7 @@ def event(
 
     .. code-block:: python
 
-        element = idom.html.button({"onClick": my_callback})
+        element = idom.html.button(on_click=my_callback)
 
     You may want the ability to prevent the default action associated with the event
     from taking place, or stoping the event from propagating up the DOM. This decorator
@@ -53,7 +53,7 @@ def event(
         def my_callback(*data):
             ...
 
-        element = idom.html.button({"onClick": my_callback})
+        element = idom.html.button(on_click=my_callback)
 
     Parameters:
         function:

src/idom/core/types.py

@@ -62,13 +62,16 @@ class ComponentType(Protocol):
     This is used to see if two component instances share the same definition.
     """
 
-    def render(self) -> VdomDict | ComponentType | str | None:
+    def render(self) -> RenderResult:
         """Render the component's view model."""
 
     def should_render(self: _OwnType, new: _OwnType) -> bool:
         """Whether the new component instance should be rendered."""
 
 
+RenderResult = Union["VdomDict", ComponentType, str, None]
+
+
 _Render = TypeVar("_Render", covariant=True)
 _Event = TypeVar("_Event", contravariant=True)
 
@@ -104,13 +107,6 @@ async def __aexit__(
 VdomChildren = Sequence[VdomChild]
 """Describes a series of :class:`VdomChild` elements"""
 
-VdomAttributesAndChildren = Union[
-    Mapping[str, Any],  # this describes both VdomDict and VdomAttributes
-    Iterable[VdomChild],
-    VdomChild,
-]
-"""Useful for the ``*attributes_and_children`` parameter in :func:`idom.core.vdom.vdom`"""
-
 
 class _VdomDictOptional(TypedDict, total=False):
     key: Key | None
@@ -207,12 +203,12 @@ class EventHandlerType(Protocol):
 
 
 class VdomDictConstructor(Protocol):
-    """Standard function for constructing a :class:`VdomDict`"""
-
     def __call__(
         self,
-        *attributes_and_children: VdomAttributesAndChildren,
-        key: str = ...,
-        event_handlers: Optional[EventHandlerMapping] = ...,
+        *children: VdomChild,
+        key: str | int | None = None,
+        event_handlers: EventHandlerMapping | None = None,
+        import_source: ImportSourceDict | None = None,
+        **attributes: Any,
     ) -> VdomDict:
         ...

src/idom/core/vdom.py

@@ -17,8 +17,10 @@
     EventHandlerMapping,
     EventHandlerType,
     ImportSourceDict,
-    VdomAttributesAndChildren,
+    Key,
+    VdomChild,
     VdomDict,
+    VdomDictConstructor,
     VdomJson,
 )
 
@@ -129,43 +131,47 @@ def is_vdom(value: Any) -> bool:
 
 def vdom(
     tag: str,
-    *attributes_and_children: VdomAttributesAndChildren,
-    key: str | int | None = None,
-    event_handlers: Optional[EventHandlerMapping] = None,
-    import_source: Optional[ImportSourceDict] = None,
+    /,
+    *children: VdomChild,
+    key: Key | None = None,
+    event_handlers: EventHandlerMapping | None = None,
+    import_source: ImportSourceDict | None = None,
+    **attributes: Any,
 ) -> VdomDict:
     """A helper function for creating VDOM dictionaries.
 
     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.
+        children:
+            String, compoennts, or other VDOM elements that are this element's children.
         key:
-            A string idicating 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.
+            A string or integer idicating 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.
+            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.
+        attributes:
+            Remaining attributes of this element.
     """
     model: VdomDict = {"tagName": tag}
 
-    attributes, children = coalesce_attributes_and_children(attributes_and_children)
     attributes, event_handlers = separate_attributes_and_event_handlers(
-        attributes, event_handlers or {}
+        attributes, event_handlers
     )
 
     if attributes:
+        if "cls" in attributes:
+            attributes["class"] = attributes.pop("cls")
         model["attributes"] = attributes
 
     if children:
-        model["children"] = children
+        model["children"] = flatten_children(children)
 
     if event_handlers:
         model["eventHandlers"] = event_handlers
@@ -179,39 +185,15 @@ def vdom(
     return model
 
 
-class _VdomDictConstructor(Protocol):
-    def __call__(
-        self,
-        *attributes_and_children: VdomAttributesAndChildren,
-        key: str | int | None = ...,
-        event_handlers: Optional[EventHandlerMapping] = ...,
-        import_source: Optional[ImportSourceDict] = ...,
-    ) -> VdomDict:
-        ...
-
-
-def make_vdom_constructor(
-    tag: str, allow_children: bool = True
-) -> _VdomDictConstructor:
+def make_vdom_constructor(tag: str, allow_children: bool = True) -> 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: VdomAttributesAndChildren,
-        key: str | int | None = None,
-        event_handlers: Optional[EventHandlerMapping] = None,
-        import_source: Optional[ImportSourceDict] = None,
-    ) -> VdomDict:
-        model = vdom(
-            tag,
-            *attributes_and_children,
-            key=key,
-            event_handlers=event_handlers,
-            import_source=import_source,
-        )
+    def constructor(*args: Any, **kwargs: Any) -> VdomDict:
+        model = vdom(tag, *args, **kwargs)
         if not allow_children and "children" in model:
             raise TypeError(f"{tag!r} nodes cannot have children.")
         return model
@@ -232,35 +214,24 @@ def constructor(
     return constructor
 
 
-def coalesce_attributes_and_children(
-    values: Sequence[Any],
-) -> Tuple[Mapping[str, Any], List[Any]]:
-    if not values:
-        return {}, []
-
-    children_or_iterables: Sequence[Any]
-    attributes, *children_or_iterables = values
-    if not _is_attributes(attributes):
-        attributes = {}
-        children_or_iterables = values
-
-    children: List[Any] = []
-    for child in children_or_iterables:
+def flatten_children(children: Sequence[VdomChild]) -> Sequence[VdomChild]:
+    child_list: list[VdomChild] = []
+    for child in children:
         if _is_single_child(child):
-            children.append(child)
+            child_list.append(child)
         else:
-            children.extend(child)
-
-    return attributes, children
+            child_list.extend(child)
+    return child_list
 
 
 def separate_attributes_and_event_handlers(
-    attributes: Mapping[str, Any], event_handlers: EventHandlerMapping
+    attributes: Mapping[str, Any],
+    event_handlers: EventHandlerMapping | None = None,
 ) -> Tuple[Dict[str, Any], EventHandlerDict]:
     separated_attributes = {}
     separated_event_handlers: Dict[str, List[EventHandlerType]] = {}
 
-    for k, v in event_handlers.items():
+    for k, v in (event_handlers or {}).items():
         separated_event_handlers[k] = [v]
 
     for k, v in attributes.items():