federate modules with mount function

Allows modules to define a mount function that can attach
components directly to a DOM element. This gives authors of
custom components a high degree of flexibility and alleviates
the problem have having conflicting React instances when
idom-client-react is installed independently.

For example, custom components with a mount function need
not be implemented in React.

Author: rmorshea

scripts/live_docs.py

@@ -28,7 +28,7 @@ def new_builder():
         [s.stop() for s in _running_idom_servers]
 
         # we need to set this before `docs.main` does
-        IDOM_CLIENT_IMPORT_SOURCE_URL.set(
+        IDOM_CLIENT_IMPORT_SOURCE_URL.current = (
             f"http://{example_server_host}{IDOM_CLIENT_IMPORT_SOURCE_URL.default}"
         )
 

src/idom/client/_private.py

@@ -2,7 +2,7 @@
 import re
 import shutil
 from pathlib import Path
-from typing import Dict, List, Tuple, cast
+from typing import Dict, Set, Tuple, cast
 
 from idom.config import IDOM_CLIENT_BUILD_DIR
 
@@ -75,12 +75,12 @@ def build_dependencies() -> Dict[str, str]:
 )
 
 
-def find_js_module_exports_in_source(content: str) -> List[str]:
-    names: List[str] = []
+def find_js_module_exports_in_source(content: str) -> Set[str]:
+    names: Set[str] = set()
     for match in _JS_MODULE_EXPORT_PATTERN.findall(content):
         for export in match.split(","):
             export_parts = export.split(" as ", 1)
-            names.append(export_parts[-1].strip())
-    names.extend(_JS_MODULE_EXPORT_FUNC_PATTERN.findall(content))
-    names.extend(_JS_MODULE_EXPORT_NAME_PATTERN.findall(content))
+            names.add(export_parts[-1].strip())
+    names.update(_JS_MODULE_EXPORT_FUNC_PATTERN.findall(content))
+    names.update(_JS_MODULE_EXPORT_NAME_PATTERN.findall(content))
     return names

src/idom/client/app/packages/idom-client-react/src/index.js

@@ -4,12 +4,17 @@ import htm from "htm";
 
 import serializeEvent from "./event-to-object";
 
-import { applyPatchInplace, getPathProperty, joinUrl } from "./utils";
+import { applyPatchInplace, joinUrl } from "./utils";
 
 const html = htm.bind(react.createElement);
 const LayoutConfigContext = react.createContext({});
 
-export function mountLayout(mountElement, saveUpdateHook, sendEvent, importSourceUrl) {
+export function mountLayout(
+  mountElement,
+  saveUpdateHook,
+  sendEvent,
+  importSourceUrl
+) {
   reactDOM.render(
     html`
       <${Layout}
@@ -53,24 +58,18 @@ function Element({ model }) {
 
 function ImportedElement({ model }) {
   const config = react.useContext(LayoutConfigContext);
-  const module = useLazyModule(model.importSource.source, config.importSourceUrl);
-  if (module) {
-    const cmpt = getPathProperty(module, model.tagName);
-    const children = elementChildren(model);
-    const attributes = elementAttributes(model, config.sendEvent);
-    return html`<${cmpt} ...${attributes}>${children}<//>`;
-  } else {
-    const fallback = model.importSource.fallback;
-    if (!fallback) {
-      return html`<div />`;
-    }
-    switch (typeof fallback) {
-      case "object":
-        return html`<${Element} model=${fallback} />`;
-      case "string":
-        return html`<div>${fallback}</div>`;
-    }
-  }
+  const mountPoint = react.useRef(null);
+
+  react.useEffect(() => {
+    const importSource = joinUrl(
+      config.importSourceUrl,
+      model.importSource.source
+    );
+    eval(`import("${importSource}")`).then((module) => {
+      mountImportSource(module, mountPoint.current, model, config);
+    });
+  });
+  return html`<div ref=${mountPoint} />`;
 }
 
 function StandardElement({ model }) {
@@ -91,7 +90,7 @@ function elementChildren(model) {
     return model.children.map((child) => {
       switch (typeof child) {
         case "object":
-          return html`<${Element} model=${child} />`;
+          return html`<${Element} key=${child.key} model=${child} />`;
         case "string":
           return child;
       }
@@ -138,13 +137,21 @@ function eventHandler(sendEvent, eventSpec) {
   };
 }
 
-function useLazyModule(source, sourceUrlBase = "") {
-  const [module, setModule] = react.useState(null);
-  if (!module) {
-    // use eval() to avoid weird build behavior by bundlers like Webpack
-    eval(`import("${joinUrl(sourceUrlBase, source)}")`).then(setModule);
-  }
-  return module;
+function mountImportSource(module, mountPoint, model, config) {
+  const mountFunction = model.importSource.hasMount
+    ? module.mount
+    : (element, component, props, children) =>
+        reactDOM.render(
+          react.createElement(component, props, ...children),
+          element
+        );
+
+  const component = module[model.tagName];
+  const children = elementChildren(model);
+  const attributes = elementAttributes(model, config.sendEvent);
+  const props = { key: model.key, ...attributes };
+
+  mountFunction(mountPoint, component, props, children);
 }
 
 function useInplaceJsonPatch(doc) {

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

@@ -19,17 +19,6 @@ export function applyPatchInplace(doc, path, patch) {
   }
 }
 
-export function getPathProperty(obj, prop) {
-  // properties may be dot seperated strings
-  const path = prop.split(".");
-  const firstProp = path.shift();
-  let value = obj[firstProp];
-  for (let i = 0; i < path.length; i++) {
-    value = value[path[i]];
-  }
-  return value;
-}
-
 export function joinUrl(base, tail) {
   return tail.startsWith("./")
     ? (base.endsWith("/") ? base.slice(0, -1) : base) + tail.slice(1)

src/idom/client/manage.py

@@ -28,7 +28,7 @@ def web_module_path(package_name: str, must_exist: bool = False) -> Path:
     return path
 
 
-def web_module_exports(package_name: str) -> List[str]:
+def web_module_exports(package_name: str) -> Set[str]:
     """Get a list of names this module exports"""
     web_module_path(package_name, must_exist=True)
     return _private.find_js_module_exports_in_source(

src/idom/client/module.py

@@ -6,9 +6,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple, Union, overload
+from typing import Any, Dict, List, Optional, Set, Tuple, Union, overload
 from urllib.parse import urlparse
 
+from idom.config import IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT
 from idom.core.vdom import ImportSourceDict, VdomDict, make_vdom_constructor
 
 from . import _private, manage
@@ -36,6 +37,8 @@ def install(
     packages: Union[str, List[str], Tuple[str]],
     ignore_installed: bool = False,
     fallback: Optional[str] = None,
+    # dynamically installed modules probably won't have a mount so we default to False
+    has_mount: bool = False,
 ) -> Union[Module, List[Module]]:
     return_one = False
     if isinstance(packages, str):
@@ -48,9 +51,11 @@ def install(
         manage.build(packages, clean_build=False)
 
     if return_one:
-        return Module(pkg_names[0], fallback=fallback)
+        return Module(pkg_names[0], fallback=fallback, has_mount=has_mount)
     else:
-        return [Module(pkg, fallback=fallback) for pkg in pkg_names]
+        return [
+            Module(pkg, fallback=fallback, has_mount=has_mount) for pkg in pkg_names
+        ]
 
 
 class Module:
@@ -67,6 +72,12 @@ class Module:
             built-in client will inject this module adjacent to other installed modules
             which means they can be imported via a relative path like
             ``./some-other-installed-module.js``.
+        fallack:
+            What to display while the modules is being loaded.
+        has_mount:
+            Whether the module exports a ``mount`` function that allows components to
+            be mounted directly to the DOM. Such a mount function enables greater
+            flexibility in how custom components can be implemented.
 
     Attributes:
         installed:
@@ -75,41 +86,52 @@ class Module:
             The URL this module will be imported from.
     """
 
-    __slots__ = "url", "fallback", "exports", "_export_names"
+    __slots__ = (
+        "url",
+        "fallback",
+        "exports",
+        "has_mount",
+        "check_exports",
+        "_export_names",
+    )
 
     def __init__(
         self,
         url_or_name: str,
         source_file: Optional[Union[str, Path]] = None,
         fallback: Optional[str] = None,
+        has_mount: bool = False,
         check_exports: bool = True,
     ) -> None:
         self.fallback = fallback
-        self._export_names: Optional[List[str]] = None
+        self.has_mount = has_mount
+        self.check_exports = check_exports
+
+        self.exports: Set[str] = set()
         if source_file is not None:
             self.url = (
                 manage.web_module_url(url_or_name)
                 if manage.web_module_exists(url_or_name)
                 else manage.add_web_module(url_or_name, source_file)
             )
             if check_exports:
-                self._export_names = manage.web_module_exports(url_or_name)
+                self.exports = manage.web_module_exports(url_or_name)
         elif _is_url(url_or_name):
             self.url = url_or_name
+            self.check_exports = False
         elif manage.web_module_exists(url_or_name):
             self.url = manage.web_module_url(url_or_name)
             if check_exports:
-                self._export_names = manage.web_module_exports(url_or_name)
+                self.exports = manage.web_module_exports(url_or_name)
         else:
             raise ValueError(f"{url_or_name!r} is not installed or is not a URL")
-        self.exports = {name: self.declare(name) for name in (self._export_names or [])}
 
     def declare(
         self,
         name: str,
         has_children: bool = True,
         fallback: Optional[str] = None,
-    ) -> "Import":
+    ) -> Import:
         """Return  an :class:`Import` for the given :class:`Module` and ``name``
 
         This roughly translates to the javascript statement
@@ -121,19 +143,20 @@ def declare(
         Where ``name`` is the given name, and ``module`` is the :attr:`Module.url` of
         this :class:`Module` instance.
         """
-        if (
-            self._export_names is not None
-            # if 'default' is exported there's not much we can infer
-            and "default" not in self._export_names
-        ):
-            if name not in self._export_names:
-                raise ValueError(
-                    f"{self} does not export {name!r}, available options are {self._export_names}"
-                )
-        return Import(self.url, name, has_children, fallback=fallback or self.fallback)
-
-    def __getattr__(self, name: str) -> "Import":
-        return self.exports.get(name) or self.declare(name)
+        if self.check_exports and name not in self.exports:
+            raise ValueError(
+                f"{self} does not export {name!r}, available options are {list(self.exports)}"
+            )
+        return Import(
+            self.url,
+            name,
+            has_children,
+            has_mount=self.has_mount,
+            fallback=fallback or self.fallback,
+        )
+
+    def __getattr__(self, name: str) -> Import:
+        return self.declare(name)
 
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.url})"
@@ -161,11 +184,19 @@ def __init__(
         module: str,
         name: str,
         has_children: bool = True,
+        has_mount: bool = False,
         fallback: Optional[str] = None,
     ) -> None:
+        if IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT.current and not has_mount:
+            raise RuntimeError(
+                f"{IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT} is set and {module} has no mount"
+            )
+
         self._name = name
         self._constructor = make_vdom_constructor(name, has_children)
-        self._import_source = ImportSourceDict(source=module, fallback=fallback)
+        self._import_source = ImportSourceDict(
+            source=module, fallback=fallback, hasMount=has_mount
+        )
 
     def __call__(
         self,

src/idom/config.py

@@ -66,6 +66,19 @@ def all_options() -> List[_option.Option[Any]]:
         ``ABSOLUTE_PATH/my-module.js``
 """
 
+IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT = _option.Option(
+    "IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT",
+    default=False,
+    validator=lambda x: bool(int(x)),
+)
+"""Control whether imported modules must have a mounting function.
+
+Client implementations that do not support dynamically installed modules can set this
+option to block the usages of components that are not mounted in isolation. More
+specifically, this requires the ``has_mount`` option of
+:class:`~idom.client.module.Module` must be set to ``True``.
+"""
+
 IDOM_FEATURE_INDEX_AS_DEFAULT_KEY = _option.Option(
     "IDOM_FEATURE_INDEX_AS_DEFAULT_KEY",
     default=False,

src/idom/core/vdom.py

@@ -58,6 +58,7 @@
                     "if": {"not": {"type": "null"}},
                     "then": {"$ref": "#/definitions/elementOrString"},
                 },
+                "hasMount": {"type": "boolean"},
             },
             "required": ["source"],
         },
@@ -83,6 +84,7 @@ def validate_vdom(value: Any) -> None:
 class ImportSourceDict(TypedDict):
     source: str
     fallback: Any
+    hasMount: bool  # noqa
 
 
 class _VdomDictOptional(TypedDict, total=False):

tests/test_cli.py

@@ -82,6 +82,7 @@ def test_show_options():
                 "True",
             ],
             ["IDOM_CLIENT_IMPORT_SOURCE_URL", "/client", "/client", "True"],
+            ["IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT", "False", "False", "True"],
             [
                 "IDOM_DEBUG_MODE",
                 IDOM_DEBUG_MODE.current,