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/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

@@ -104,13 +104,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

src/idom/core/vdom.py

@@ -17,7 +17,8 @@
     EventHandlerMapping,
     EventHandlerType,
     ImportSourceDict,
-    VdomAttributesAndChildren,
+    Key,
+    VdomChild,
     VdomDict,
     VdomJson,
 )
@@ -129,43 +130,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,17 +184,6 @@ 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:
@@ -199,19 +193,8 @@ def make_vdom_constructor(
     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(*args, **kwargs)
         if not allow_children and "children" in model:
             raise TypeError(f"{tag!r} nodes cannot have children.")
         return model
@@ -232,35 +215,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():
@@ -339,3 +311,17 @@ def _is_single_child(value: Any) -> bool:
     class _EllipsisRepr:
         def __repr__(self) -> str:
             return "..."
+
+
+class _VdomDictConstructor(Protocol):
+    def __call__(
+        self,
+        tag: str,
+        /,
+        *children: VdomChild,
+        key: str | int | None = None,
+        event_handlers: EventHandlerMapping | None = None,
+        import_source: ImportSourceDict | None = None,
+        **attributes: Any,
+    ) -> VdomDict:
+        ...

src/idom/html.py

@@ -161,18 +161,15 @@
 from typing import Any, Mapping
 
 from .core.types import Key, VdomDict
-from .core.vdom import coalesce_attributes_and_children, make_vdom_constructor
+from .core.vdom import flatten_children, make_vdom_constructor
 
 
 def _(*children: Any, key: Key | None = None) -> VdomDict:
     """An HTML fragment - this element will not appear in the DOM"""
-    attributes, coalesced_children = coalesce_attributes_and_children(children)
-    if attributes:
-        raise TypeError("Fragments cannot have attributes")
     model: VdomDict = {"tagName": ""}
 
-    if coalesced_children:
-        model["children"] = coalesced_children
+    if children:
+        model["children"] = flatten_children(children)
 
     if key is not None:
         model["key"] = key
@@ -276,10 +273,7 @@ def _(*children: Any, key: Key | None = None) -> VdomDict:
 noscript = make_vdom_constructor("noscript")
 
 
-def script(
-    *attributes_and_children: Mapping[str, Any] | str,
-    key: str | int | None = None,
-) -> VdomDict:
+def script(*children: str, key: Key | None = None, **attributes: Any) -> VdomDict:
     """Create a new `<{script}> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script>`__ element.
 
     This behaves slightly differently than a normal script element in that it may be run
@@ -295,9 +289,8 @@ def script(
     """
     model: VdomDict = {"tagName": "script"}
 
-    attributes, children = coalesce_attributes_and_children(attributes_and_children)
-
     if children:
+        children = flatten_children(children)
         if len(children) > 1:
             raise ValueError("'script' nodes may have, at most, one child.")
         elif not isinstance(children[0], str):

src/idom/testing/common.py

@@ -154,7 +154,7 @@ class StaticEventHandler:
             def MyComponent():
                 state, set_state = idom.hooks.use_state(0)
                 handler = static_handler.use(lambda event: set_state(state + 1))
-                return idom.html.button({"onClick": handler}, "Click me!")
+                return idom.html.button("Click me!", on_click=handler)
 
             # gives the target ID for onClick where from the last render of MyComponent
             static_handlers.target
@@ -177,7 +177,7 @@ def Parent():
             def Child(key):
                 state, set_state = idom.hooks.use_state(0)
                 handler = static_handlers_by_key[key].use(lambda event: set_state(state + 1))
-                return idom.html.button({"onClick": handler}, "Click me!")
+                return idom.html.button("Click me!", on_click=handler)
 
             # grab the individual targets for each instance above
             first_target = static_handlers_by_key["first"].target

tests/test_client.py

@@ -22,7 +22,7 @@ async def test_automatic_reconnect(browser: Browser):
 
     @idom.component
     def OldComponent():
-        return idom.html.p({"id": "old-component"}, "old")
+        return idom.html.p("old", id="old-component")
 
     async with AsyncExitStack() as exit_stack:
         server = await exit_stack.enter_async_context(BackendFixture(port=port))
@@ -43,7 +43,7 @@ def OldComponent():
     @idom.component
     def NewComponent():
         state, set_state.current = idom.hooks.use_state(0)
-        return idom.html.p({"id": f"new-component-{state}"}, f"new-{state}")
+        return idom.html.p(f"new-{state}", id=f"new-component-{state}")
 
     async with AsyncExitStack() as exit_stack:
         server = await exit_stack.enter_async_context(BackendFixture(port=port))
@@ -111,13 +111,13 @@ async def test_slow_server_response_on_input_change(display: DisplayFixture):
 
     @idom.component
     def SomeComponent():
-        value, set_value = idom.hooks.use_state("")
+        _, set_value = idom.hooks.use_state("")
 
         async def handle_change(event):
             await asyncio.sleep(delay)
             set_value(event["target"]["value"])
 
-        return idom.html.input({"onChange": handle_change, "id": "test-input"})
+        return idom.html.input(on_change=handle_change, id="test-input")
 
     await display.show(SomeComponent)
 

tests/test_html.py

@@ -13,7 +13,7 @@ async def test_script_mount_unmount(display: DisplayFixture):
     def Root():
         is_mounted, toggle_is_mounted.current = use_toggle(True)
         return html.div(
-            html.div({"id": "mount-state", "data-value": False}),
+            html.div(id="mount-state", data_value=False),
             HasScript() if is_mounted else html.div(),
         )
 
@@ -53,8 +53,8 @@ async def test_script_re_run_on_content_change(display: DisplayFixture):
     def HasScript():
         count, incr_count.current = use_counter(1)
         return html.div(
-            html.div({"id": "mount-count", "data-value": 0}),
-            html.div({"id": "unmount-count", "data-value": 0}),
+            html.div(id="mount-count", data_value=0),
+            html.div(id="unmount-count", data_value=0),
             html.script(
                 f"""() => {{
                     const mountCountEl = document.getElementById("mount-count");
@@ -101,7 +101,7 @@ def HasScript():
             return html.div()
         else:
             return html.div(
-                html.div({"id": "run-count", "data-value": 0}),
+                html.div(id="run-count", data_value=0),
                 html.script(
                     {
                         "src": f"/_idom/modules/{file_name_template.format(src_id=src_id)}"
@@ -148,8 +148,3 @@ def test_simple_fragment():
         "key": "something",
         "children": [1, 2, 3],
     }
-
-
-def test_fragment_can_have_no_attributes():
-    with pytest.raises(TypeError, match="Fragments cannot have attributes"):
-        html._({"some-attribute": 1})

tests/test_widgets.py

@@ -24,7 +24,7 @@ def make_next_count_constructor(count):
 
         def constructor():
             count.current += 1
-            return idom.html.div({"id": f"hotswap-{count.current}"}, count.current)
+            return idom.html.div(count.current, id=f"hotswap-{count.current}")
 
         return constructor
 
@@ -35,7 +35,7 @@ def ButtonSwapsDivs():
         async def on_click(event):
             mount(make_next_count_constructor(count))
 
-        incr = idom.html.button({"onClick": on_click, "id": "incr-button"}, "incr")
+        incr = idom.html.button("incr", on_click=on_click, id="incr-button")
 
         mount, make_hostswap = idom.widgets.hotswap(update_on_change=True)
         mount(make_next_count_constructor(count))