improve docs + simplify multiview

Author: rmorshea

src/idom/_option.py

@@ -1,3 +1,8 @@
+"""
+Config Option
+=============
+"""
+
 from __future__ import annotations
 
 import os

src/idom/core/vdom.py

@@ -114,14 +114,15 @@ def vdom(
     import_source: _ImportSourceArg = None,
 ) -> VdomDict:
     """A helper function for creating VDOM dictionaries.
+
     Parameters:
         tag:
             The type of element (e.g. 'div', 'h1', 'img')
         attributes_and_children:
-            Attribute mappings followed by iterables of children for the element.
-            The attributes **must** precede the children, though you may pass multiple
-            sets of attributes, or children which will be merged into their respective
-            parts of the model.
+            Attribute mappings followed by iterables of children for the element. The
+            attributes **must** precede the children, though you may pass multiple sets
+            of attributes, or children which will be merged into their respective parts
+            of the model.
         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
@@ -167,6 +168,7 @@ def __call__(
 
 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.
     """

src/idom/widgets/utils.py

@@ -2,8 +2,9 @@
 Widget Tools
 ============
 """
+from __future__ import annotations
 
-from typing import Any, Callable, Dict, Set, Tuple, TypeVar
+from typing import Any, Callable, Dict, Optional, Set, Tuple, TypeVar
 
 from idom.core import hooks
 from idom.core.component import ComponentConstructor, component
@@ -97,30 +98,36 @@ def _use_callable(initial_func: _FuncVar) -> Tuple[_FuncVar, Callable[[_Func], N
     return state[0], lambda new: state[1](lambda old: new)
 
 
-def multiview() -> Tuple["MultiViewMount", ComponentConstructor]:
+def multiview() -> Tuple[MultiViewMount, ComponentConstructor]:
     """Dynamically add components to a layout on the fly
 
     Since you can't change the component functions used to create a layout
     in an imperative manner, you can use ``multiview`` to do this so
     long as you set things up ahead of time.
 
-    Returns:
-        A function for adding views and the root of the dynamic view
-
     Examples:
 
         .. code-block::
 
             import idom
 
-            define, root = idom.widgets.multiview()
+            mount, multiview = idom.widgets.multiview()
+
+            @idom.component
+            def Hello():
+                return idom.html.h1(["hello"])
 
-            @component
-            def Hello(self, phrase):
-                return idom.html.h1(["hello " + phrase])
+            # auto static view ID
+            mount.add("hello", Hello)
+            # use the view ID to create the associate component instance
+            hello_component_instance = multiview("hello")
 
-            add_hello = define(Hello)
-            hello_world_view_id = add_hello("world")
+            @idom.component
+            def World():
+                return idom.html.h1(["world"])
+
+            generated_view_id = mount.add(None, World)
+            world_component_instance = multiview(generated_view_id)
 
         Displaying ``root`` with the parameter ``view_id=hello_world_view_id`` will show
         the message 'hello world'. Usually though this is achieved by connecting to the
@@ -141,28 +148,37 @@ def MultiView(view_id: str) -> Any:
 
 
 class MultiViewMount:
+    """Mount point for :func:`multiview`"""
 
     __slots__ = "_next_auto_id", "_views"
 
     def __init__(self, views: Dict[str, ComponentConstructor]):
         self._next_auto_id = 0
         self._views = views
 
-    def remove(self, view_id: str) -> None:
-        del self._views[view_id]
-
-    def __getitem__(self, view_id: str) -> Callable[[ComponentConstructor], str]:
-        def mount(constructor: ComponentConstructor) -> str:
-            self._views[view_id] = constructor
-            return view_id
-
-        return mount
-
-    def __call__(self, constructor: ComponentConstructor) -> str:
-        self._next_auto_id += 1
-        view_id = str(self._next_auto_id)
+    def add(self, view_id: Optional[str], constructor: ComponentConstructor) -> str:
+        """Add a component constructor
+
+        Parameters:
+            view_id:
+                The view ID the constructor will be associated with. If ``None`` then
+                a view ID will be automatically generated.
+            constructor:
+                The component constructor to be mounted. It must accept no arguments.
+
+        Returns:
+            The view ID that was assocaited with the component - most useful for
+            auto-generated view IDs
+        """
+        if view_id is None:
+            self._next_auto_id += 1
+            view_id = str(self._next_auto_id)
         self._views[view_id] = constructor
         return view_id
 
+    def remove(self, view_id: str) -> None:
+        """Remove a mounted component constructor given its view ID"""
+        del self._views[view_id]
+
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self._views})"

tests/test_server/test_common/test_multiview.py

@@ -30,10 +30,14 @@ def server_mount_point(request):
 
 
 def test_multiview_server(driver_get, driver, server_mount_point):
-    manual_id = server_mount_point.mount["manually_set_id"](
-        lambda: idom.html.h1({"id": "e1"}, ["e1"])
+    manual_id = server_mount_point.mount.add(
+        "manually_set_id",
+        lambda: idom.html.h1({"id": "e1"}, ["e1"]),
+    )
+    auto_view_id = server_mount_point.mount.add(
+        None,
+        lambda: idom.html.h1({"id": "e2"}, ["e2"]),
     )
-    auto_view_id = server_mount_point.mount(lambda: idom.html.h1({"id": "e2"}, ["e2"]))
 
     driver_get({"view_id": manual_id})
     driver.find_element_by_id("e1")