mirror react/reactDOM render funcs

Author: rmorshea

docs/source/examples/super_simple_chart.js

@@ -1,18 +1,12 @@
-import {
-  h,
-  Component,
-  render as preactRender,
-} from "https://unpkg.com/preact?module";
+import { h, Component, render } from "https://unpkg.com/preact?module";
 import htm from "https://unpkg.com/htm?module";
 
 const html = htm.bind(h);
 
-export function render(element, component, props) {
-  preactRender(html`<${component} ...${props} />`, element);
-}
+export { h as createElement, render as renderElement };
 
-export function unmount(element) {
-  preactRender(null, element);
+export function unmountElement(container) {
+  preactRender(null, container);
 }
 
 export function SuperSimpleChart(props) {

docs/source/faq.rst

@@ -48,22 +48,16 @@ Yes, but with some restrictions:
 
 1. The Javascript in question must be distributed as an ECMAScript Module
    (`ESM <https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/>`__)
-2. The module must export the following functions:
-
-   - ``render(element: HTMLElement, component: any, props: Object) => void``
-   - ``unmount(element: HTMLElement) => void``
-
-
+2. The module must export the :ref:`required interface <Custom Javascript Components>`.
 
 These restrictions apply because the Javascript from the CDN must be able to run
-natively in the browser, the module must be able to run in isolation from the main
-application, and the server must tell the client to use the exported ``mount()``
-function.
+natively in the browser and the module must be able to run in isolation from the main
+application.
 
 
 What props can I pass to Javascript components?
 -----------------------------------------------
 
 You can only pass JSON serializable props to components implemented in Javascript. It is
-possible to implement a :ref:`Custom Javascript Component <Custom Javascript Components>`
+possible to create a :ref:`Custom Javascript Component <Custom Javascript Components>`
 which undestands how to deserialise JSON data into native Javascript objects though.

docs/source/javascript-components.rst

@@ -30,28 +30,62 @@ Custom Javascript Components
 For projects that will be shared with others we recommend bundling your Javascript with
 `rollup <https://rollupjs.org/guide/en/>`__ or `webpack <https://webpack.js.org/>`__
 into a
-`web module <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`__
-using IDOM's
+`web module <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`__.
+IDOM also provides a
 `template repository <https://github.com/idom-team/idom-react-component-cookiecutter>`__
-as a blueprint to build a React component. Once you've done this, you can distribute
-bundled javascript in your Python package and integrate it into IDOM by defining
-:class:`~idom.client.module.Module` objects that load them from source:
+that can be used as a blueprint to build a library of React components.
+
+The core benefit of loading Javascript in this way is that users of your code won't need
+to have NPM_ installed. Rather, they can use ``pip`` to install your Python package
+without any other build steps because the bundled Javascript you distributed with it
+will be symlinked into the IDOM client at runtime.
+
+To work as intended, the Javascript bundle must export the following named functions:
+
+.. code-block:: typescript
+
+    type createElement = (component: any, props: Object) => any;
+    type renderElement = (element: any, container: HTMLElement) => void;
+    type unmountElement = (element: HTMLElement) => void;
+
+These functions can be thought of as being analogous to those from React.
+
+- ``createElement`` ➜ |react.createElement|_
+- ``renderElement`` ➜ |reactDOM.render|_
+- ``unmountElement`` ➜ |reactDOM.unmountComponentAtNode|_
+
+.. |react.createElement| replace:: ``react.createElement``
+.. _react.createElement: https://reactjs.org/docs/react-api.html#createelement
+
+.. |reactDOM.render| replace:: ``reactDOM.render``
+.. _reactDOM.render: https://reactjs.org/docs/react-dom.html#render
+
+.. |reactDOM.unmountComponentAtNode| replace:: ``reactDOM.unmountComponentAtNode``
+.. _reactDOM.unmountComponentAtNode: https://reactjs.org/docs/react-api.html#createelement
+
+And will be called in the following manner:
+
+.. code-block::
+
+    // on every render
+    renderElement(createElement(type, props), container);
+    // on unmount
+    unmountElement(container);
+
+Once you've done this, you can distribute the bundled javascript in your Python package
+and integrate it into IDOM by defining :class:`~idom.client.module.Module` objects that
+load them from source:
 
 .. code-block::
 
     import idom
     my_js_package = idom.Module("my-js-package", source_file="/path/to/my/bundle.js")
 
-The core benefit of loading Javascript in this way is that users of your code won't need
-NPM_. Rather, they can use ``pip`` to install your Python package without any other build
-steps because the bundled Javascript you distributed with it will be symlinked into the
-IDOM client at runtime.
-
-With that said, if you just want to see how this all works it might be easiest to hook
-in simple a hand-crafted Javascript component. In the example to follow we'll create a
-very basic SVG line chart. The catch though is that we are limited to using Javascript
-that can run directly in the browser. This means we can't use fancy syntax like
-`JSX <https://reactjs.org/docs/introducing-jsx.html>`__ and instead will use
+The simplest way to try this out yourself though, is to hook in simple a hand-crafted
+Javascript module that has the requisite interface. In the example to follow we'll
+create a very basic SVG line chart. The catch though is that we are limited to using
+Javascript that can run directly in the browser. This means we can't use fancy syntax
+like `JSX <https://reactjs.org/docs/introducing-jsx.html>`__ and instead will use
 `htm <https://github.com/developit/htm>`__ to simulate JSX in plain Javascript.
 
 .. example:: super_simple_chart

setup.py

@@ -136,7 +136,7 @@ def run(self):
                 for args in (f"{npm} install", f"{npm} run build"):
                     args_list = args.split()
                     log.info(f"> {list2cmdline(args_list)}")
-                    subprocess.run(args_list, cwd=js_dir)
+                    subprocess.run(args_list, cwd=js_dir, check=True)
             except Exception:
                 log.error("Failed to install Javascript")
                 log.error(traceback.format_exc())

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

@@ -64,19 +64,23 @@ function ImportedElement({ model }) {
 
   // this effect must run every time in case the model has changed
   react.useEffect(() => {
-    importSource.then(({ render }) => {
-      render(
-        mountPoint.current,
-        model.tagName,
-        elementAttributes(model, config.sendEvent),
-        model.children,
-        config
+    importSource.then(({ createElement, renderElement }) => {
+      renderElement(
+        createElement(
+          model.tagName,
+          elementAttributes(model, config.sendEvent),
+          model.children
+        ),
+        mountPoint.current
       );
     });
   });
 
   react.useEffect(
-    () => () => importSource.then(({ unmount }) => unmount()),
+    () => () =>
+      importSource.then(({ unmountElement }) =>
+        unmountElement(mountPoint.current)
+      ),
     []
   );
 
@@ -149,28 +153,26 @@ function loadFromImportSource(config, importSource) {
     .loadImportSource(importSource.source, importSource.sourceType)
     .then((module) => {
       if (
-        typeof module.render == "function" &&
-        typeof module.unmount == "function"
+        typeof module.createElement == "function" &&
+        typeof module.renderElement == "function" &&
+        typeof module.unmountElement == "function"
       ) {
         return {
-          render: (element, type, props, children, config) => {
-            module.render(element, module[type], props, children, config);
-          },
-          unmount: module.unmount,
+          createElement: (type, props) =>
+            module.createElement(module[type], props),
+          renderElement: module.renderElement,
+          unmountElement: module.unmountElement,
         };
       } else {
         return {
-          render: (element, type, props, children) => {
-            reactDOM.render(
-              react.createElement(
-                module[type],
-                props,
-                ...elementChildren(children)
-              ),
-              element
-            );
-          },
-          unmount: reactDOM.unmountComponentAtNode,
+          createElement: (type, props, children) =>
+            react.createElement(
+              module[type],
+              props,
+              ...elementChildren(children)
+            ),
+          renderElement: reactDOM.render,
+          unmountElement: reactDOM.unmountComponentAtNode,
         };
       }
     });

tests/test_client/js/set-flag-when-unmount-is-called.js

@@ -1,18 +1,22 @@
-export function render(element, component, props) {
-  if (element.firstChild) {
-    element.removeChild(element.firstChild);
+export function createElement(component, props) {
+  return component(props);
+}
+
+export function renderElement(element, container) {
+  if (container.firstChild) {
+    container.removeChild(container.firstChild);
   }
-  element.appendChild(component(props));
+  container.appendChild(element);
 }
 
-export function unmount(element) {
+export function unmountElement(container) {
   // We add an element to the document.body to indicate that this function was called.
   // Thus allowing Selenium to see communicate to server-side code that this effect
   // did indeed occur.
   const unmountFlag = document.createElement("h1");
   unmountFlag.setAttribute("id", "unmount-flag");
   document.body.appendChild(unmountFlag);
-  element.innerHTML = "";
+  container.innerHTML = "";
 }
 
 export function SomeComponent(props) {