rework custom component interface with bind() func

also...

- updated the react module template to render children
- removed preact module template until things are more stable
  (it was not being tested).

Author: rmorshea

Diff for: docs/source/_static/custom.js

@@ -1600,91 +1600,80 @@ 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() {
+  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);
+    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
-      );
-    });
-  });
+  react.useEffect(() => sourceBinding.current.render(model));
 
-  react.useEffect(
-    () => () =>
-      importSource.then(({ unmountElement }) =>
-        unmountElement(mountPoint.current)
-      ),
-    []
-  );
 
-  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 +1704,46 @@ 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,
+          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 +1768,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);
 }

Diff for: docs/source/custom_js/package-lock.json

@@ -6,7 +6,7 @@
 from idom.widgets import Input
 
 
-victory = idom.web.module_from_template("react", "victory", fallback="loading...")
+victory = idom.web.module_from_template("react", "victory", fallback="⌛")
 VictoryLine = idom.web.export(victory, "VictoryLine")
 
 
@@ -77,8 +77,8 @@ def update_value(value):
         set_value_callback(value)
 
     return idom.html.fieldset(
-        {"class": "number-input-container"},
-        [idom.html.legend({"style": {"font-size": "medium"}}, label)],
+        {"className": "number-input-container"},
+        [idom.html.legend({"style": {"fontSize": "medium"}}, label)],
         Input(update_value, "number", value, attributes=attrs, cast=float),
         Input(update_value, "range", value, attributes=attrs, cast=float),
     )

Diff for: docs/source/examples/simple_dashboard.py

@@ -56,44 +56,67 @@ For projects that will be shared with others, we recommend bundling your Javascr
 Rollup_ or Webpack_ into a `web module`_. IDOM also provides a `template repository`_
 that can be used as a blueprint to build a library of React components.
 
-To work as intended, the Javascript bundle must provide named exports for the following
-functions as well as any components that will be rendered.
+To work as intended, the Javascript bundle must export a function ``bind()`` that
+adheres to the following interface:
+
+.. code-block:: typescript
+
+    type EventData = {
+        target: string;
+        data: Array<any>;
+    }
+
+    type LayoutContext = {
+        sendEvent(data: EventData) => void;
+        loadImportSource(source: string, sourceType: "NAME" | "URL") => Module;
+    }
+
+    type bind = (node: HTMLElement, context: LayoutContext) => ({
+        render(component: any, props: Object, children: Array<any>): void;
+        unmount(): void;
+    });
 
 .. note::
 
-    The exported components do not have to be React-based since you'll have full control
-    over the rendering mechanism.
+    - ``node`` is the ``HTMLElement`` that ``render()`` should mount to.
 
-.. code-block:: typescript
+    - ``context`` can send events back to the server and load "import sources"
+      (like a custom component module).
 
-    type createElement = (component: any, props: Object) => any;
-    type renderElement = (element: any, container: HTMLElement) => void;
-    type unmountElement = (element: HTMLElement) => void;
+    - ``component`` is a named export of the current module.
 
-These functions can be thought of as being analogous to those from React.
+    - ``props`` is an object containing attributes and callbacks for the given
+      ``component``.
 
-- ``createElement`` ➜ |react.createElement|_
-- ``renderElement`` ➜ |reactDOM.render|_
-- ``unmountElement`` ➜ |reactDOM.unmountComponentAtNode|_
+    - ``children`` is an array of unrendered VDOM elements.
 
-.. |react.createElement| replace:: ``react.createElement``
-.. _react.createElement: https://reactjs.org/docs/react-api.html#createelement
+The interface returned by ``bind()`` can be thought of as being similar to that of
+React.
 
-.. |reactDOM.render| replace:: ``reactDOM.render``
-.. _reactDOM.render: https://reactjs.org/docs/react-dom.html#render
+- ``render`` ➜ |React.createElement|_ and |ReactDOM.render|_
+- ``unmount`` ➜ |ReactDOM.unmountComponentAtNode|_
 
-.. |reactDOM.unmountComponentAtNode| replace:: ``reactDOM.unmountComponentAtNode``
-.. _reactDOM.unmountComponentAtNode: https://reactjs.org/docs/react-api.html#createelement
+.. |React.createElement| replace:: ``React.createElement``
+.. _React.createElement: https://reactjs.org/docs/react-api.html#createelement
 
-And will be called in the following manner, where ``component`` is a named export of
-your module:
+.. |ReactDOM.render| replace:: ``ReactDOM.render``
+.. _ReactDOM.render: https://reactjs.org/docs/react-dom.html#render
 
-.. code-block::
+.. |ReactDOM.unmountComponentAtNode| replace:: ``ReactDOM.unmountComponentAtNode``
+.. _ReactDOM.unmountComponentAtNode: https://reactjs.org/docs/react-api.html#createelement
+
+It will be used in the following manner:
+
+.. code-block:: javascript
+
+    // once on mount
+    const binding = bind(node, context);
 
     // on every render
-    renderElement(createElement(component, props), container);
-    // on unmount
-    unmountElement(container);
+    binding.render(component, props, children);
+
+    // once on unmount
+    binding.unmount();
 
 The simplest way to try this out yourself though, is to hook in a simple hand-crafted
 Javascript module that has the requisite interface. In the example to follow we'll
@@ -190,14 +213,14 @@ To start, let's take a look at the file structure we'll be building:
 
 .. code-block:: javascript
 
-    import * as react from "react";
-    import * as reactDOM from "react-dom";
+    import * as React from "react";
+    import * as ReactDOM from "react-dom";
 
     // exports required to interface with IDOM
     export const createElement = (component, props) =>
-      react.createElement(component, props);
-    export const renderElement = reactDOM.render;
-    export const unmountElement = reactDOM.unmountComponentAtNode;
+      React.createElement(component, props);
+    export const renderElement = ReactDOM.render;
+    export const unmountElement = ReactDOM.unmountComponentAtNode;
 
     // exports for your components
     export YourFirstComponent(props) {...};