rework custom component interface with bind() func

docs/source/_static/custom.js

@@ -1600,91 +1600,85 @@ function Layout({ saveUpdateHook, sendEvent, loadImportSource }) {
   }
 }
 
-function Element({ model, key }) {
+function Element({ model }) {
   if (model.importSource) {
     return html`<${ImportedElement} model=${model} />`;
   } else {
     return html`<${StandardElement} model=${model} />`;
   }
 }
 
-function elementChildren(modelChildren) {
-  if (!modelChildren) {
-    return [];
-  } else {
-    return modelChildren.map((child) => {
-      switch (typeof child) {
-        case "object":
-          return html`<${Element} key=${child.key} model=${child} />`;
-        case "string":
-          return child;
-      }
-    });
-  }
-}
-
 function StandardElement({ model }) {
   const config = react.useContext(LayoutConfigContext);
   const children = elementChildren(model.children);
   const attributes = elementAttributes(model, config.sendEvent);
-  if (model.children && model.children.length) {
-    return html`<${model.tagName} ...${attributes}>${children}<//>`;
-  } else {
-    return html`<${model.tagName} ...${attributes} />`;
-  }
+  // Use createElement here to avoid warning about variable numbers of children not
+  // having keys. Warning about this must now be the responsibility of the server
+  // providing the models instead of the client rendering them.
+  return react.createElement(model.tagName, attributes, ...children);
 }
 
 function ImportedElement({ model }) {
   const config = react.useContext(LayoutConfigContext);
-  config.sendEvent;
+
+  const importSourceFallback = model.importSource.fallback;
+  const [importSource, setImportSource] = react.useState(null);
+
+  if (!importSource) {
+    // load the import source in the background
+    loadImportSource$1(config, model.importSource).then(setImportSource);
+
+    // display a fallback if one was given
+    if (!importSourceFallback) {
+      return html`<div />`;
+    } else if (typeof importSourceFallback == "string") {
+      return html`<div>${importSourceFallback}</div>`;
+    } else {
+      return html`<${StandardElement} model=${importSourceFallback} />`;
+    }
+  } else {
+    return html`<${RenderImportedElement}
+      model=${model}
+      importSource=${importSource}
+    />`;
+  }
+}
+
+function RenderImportedElement({ model, importSource }) {
+  react.useContext(LayoutConfigContext);
   const mountPoint = react.useRef(null);
-  const fallback = model.importSource.fallback;
-  const importSource = useConst(() =>
-    loadFromImportSource(config, model.importSource)
-  );
+  const sourceBinding = react.useRef(null);
 
   react.useEffect(() => {
-    if (fallback) {
-      importSource.then(() => {
-        reactDom.unmountComponentAtNode(mountPoint.current);
-        if (mountPoint.current.children) {
-          mountPoint.current.removeChild(mountPoint.current.children[0]);
-        }
-      });
+    sourceBinding.current = importSource.bind(mountPoint.current);
+    if (!importSource.data.unmountBeforeUpdate) {
+      return sourceBinding.current.unmount;
     }
   }, []);
 
   // this effect must run every time in case the model has changed
   react.useEffect(() => {
-    importSource.then(({ createElement, renderElement }) => {
-      renderElement(
-        createElement(
-          model.tagName,
-          elementAttributes(model, config.sendEvent),
-          model.children
-        ),
-        mountPoint.current
-      );
-    });
+    sourceBinding.current.render(model);
+    if (importSource.data.unmountBeforeUpdate) {
+      return sourceBinding.current.unmount;
+    }
   });
 
-  react.useEffect(
-    () => () =>
-      importSource.then(({ unmountElement }) =>
-        unmountElement(mountPoint.current)
-      ),
-    []
-  );
+  return html`<div ref=${mountPoint} />`;
+}
 
-  if (!fallback) {
-    return html`<div ref=${mountPoint} />`;
-  } else if (typeof fallback == "string") {
-    // need the second div there so we can removeChild above
-    return html`<div ref=${mountPoint}><div>${fallback}</div></div>`;
+function elementChildren(modelChildren) {
+  if (!modelChildren) {
+    return [];
   } else {
-    return html`<div ref=${mountPoint}>
-      <${StandardElement} model=${fallback} />
-    </div>`;
+    return modelChildren.map((child) => {
+      switch (typeof child) {
+        case "object":
+          return html`<${Element} key=${child.key} model=${child} />`;
+        case "string":
+          return child;
+      }
+    });
   }
 }
 
@@ -1715,34 +1709,47 @@ function eventHandler(sendEvent, eventSpec) {
         return value;
       }
     });
-    new Promise((resolve, reject) => {
-      const msg = {
-        data: data,
-        target: eventSpec["target"],
-      };
-      sendEvent(msg);
-      resolve(msg);
+    sendEvent({
+      data: data,
+      target: eventSpec["target"],
     });
   };
 }
 
-function loadFromImportSource(config, importSource) {
+function loadImportSource$1(config, importSource) {
   return config
     .loadImportSource(importSource.source, importSource.sourceType)
     .then((module) => {
-      if (
-        typeof module.createElement == "function" &&
-        typeof module.renderElement == "function" &&
-        typeof module.unmountElement == "function"
-      ) {
+      if (typeof module.bind == "function") {
         return {
-          createElement: (type, props, children) =>
-            module.createElement(module[type], props, children, config),
-          renderElement: module.renderElement,
-          unmountElement: module.unmountElement,
+          data: importSource,
+          bind: (node) => {
+            const binding = module.bind(node, config);
+            if (
+              typeof binding.render == "function" &&
+              typeof binding.unmount == "function"
+            ) {
+              return {
+                render: (model) => {
+                  binding.render(
+                    module[model.tagName],
+                    elementAttributes(model, config.sendEvent),
+                    model.children
+                  );
+                },
+                unmount: binding.unmount,
+              };
+            } else {
+              console.error(
+                `${importSource.source} returned an impropper binding`
+              );
+            }
+          },
         };
       } else {
-        console.error(`${module} does not expose the required interfaces`);
+        console.error(
+          `${importSource.source} did not export a function 'bind'`
+        );
       }
     });
 }
@@ -1767,16 +1774,6 @@ function useForceUpdate() {
   return react.useCallback(() => updateState({}), []);
 }
 
-function useConst(func) {
-  const ref = react.useRef();
-
-  if (!ref.current) {
-    ref.current = func();
-  }
-
-  return ref.current;
-}
-
 function mountLayout(mountElement, layoutProps) {
   reactDom.render(react.createElement(Layout, layoutProps), mountElement);
 }

docs/source/examples.rst

@@ -50,25 +50,18 @@ Try interacting with the sliders 📈
 .. example:: simple_dashboard
 
 
-Install Javascript Modules
---------------------------
+Dynamically Loaded React Components
+-----------------------------------
 
-Simply install your javascript library of choice using the ``idom`` CLI:
-
-.. code-block:: bash
-
-    idom install victory
-
-Then import the module with :mod:`~idom.web.module`:
+This method is not recommended for use in production applications, but it's great while
+you're experimenting:
 
 .. example:: victory_chart
 
 
 Define Javascript Modules
 -------------------------
 
-Assuming you already installed ``victory`` as in the :ref:`Install Javascript Modules` section:
-
 Click the bars to trigger an event 👇
 
 .. example:: super_simple_chart
@@ -77,8 +70,6 @@ Click the bars to trigger an event 👇
 Material UI Slider
 ------------------
 
-Assuming you already installed ``@material-ui/core`` as in the :ref:`Install Javascript Modules` section:
-
 Move the slider and see the event information update 👇
 
 .. example:: material_ui_slider

docs/source/examples/material_ui_button_no_action.py

@@ -1,7 +1,7 @@
 import idom
 
 
-mui = idom.web.module_from_template("react", "@material-ui/core", fallback="⌛")
+mui = idom.web.module_from_template("react", "@material-ui/core@^5.0", fallback="⌛")
 Button = idom.web.export(mui, "Button")
 
 idom.run(

docs/source/examples/material_ui_button_on_click.py

@@ -3,7 +3,7 @@
 import idom
 
 
-mui = idom.web.module_from_template("react", "@material-ui/core", fallback="⌛")
+mui = idom.web.module_from_template("react", "@material-ui/core@^5.0", fallback="⌛")
 Button = idom.web.export(mui, "Button")
 
 

docs/source/examples/material_ui_slider.py

@@ -3,7 +3,7 @@
 import idom
 
 
-mui = idom.web.module_from_template("react", "@material-ui/core", fallback="⌛")
+mui = idom.web.module_from_template("react", "@material-ui/core@^5.0", fallback="⌛")
 Slider = idom.web.export(mui, "Slider")
 
 

docs/source/examples/simple_dashboard.py

@@ -6,7 +6,13 @@
 from idom.widgets import Input
 
 
-victory = idom.web.module_from_template("react", "victory", fallback="loading...")
+victory = idom.web.module_from_template(
+    "react",
+    "victory-line",
+    fallback="⌛",
+    # not usually required (see issue #461 for more info)
+    unmount_before_update=True,
+)
 VictoryLine = idom.web.export(victory, "VictoryLine")
 
 

docs/source/examples/super_simple_chart.js

@@ -3,10 +3,16 @@ import htm from "https://unpkg.com/htm?module";
 
 const html = htm.bind(h);
 
-export { h as createElement, render as renderElement };
-
-export function unmountElement(container) {
-  render(null, container);
+export function bind(node, config) {
+  return {
+    render: (component, props, children) => {
+      if (children) {
+        console.error("Children not supported");
+      }
+      render(h(component, props), node);
+    },
+    unmount: () => render(null, node),
+  }
 }
 
 export function SuperSimpleChart(props) {

docs/source/examples/victory_chart.py

@@ -1,7 +1,7 @@
 import idom
 
 
-victory = idom.web.module_from_template("react", "victory", fallback="⌛")
+victory = idom.web.module_from_template("react", "victory-line", fallback="⌛")
 VictoryBar = idom.web.export(victory, "VictoryBar")
 
 bar_style = {"parent": {"width": "500px"}, "data": {"fill": "royalblue"}}