update changelog for 0.32.0 release

Author: rmorshea

docs/source/architectural-patterns.rst

@@ -173,7 +173,7 @@ Communication Scheme
 --------------------
 
 To communicate between its back-end Python server and Javascript client, IDOM uses
-something called a Virtual Document Object Model (:ref:`VDOM <VDOM Mimetype>`) to
+something called a Virtual Document Object Model (:ref:`VDOM`) to
 construct a representation of the view. The VDOM is constructed on the Python side by
 components. Then, as it evolves, IDOM's layout computes VDOM-diffs and wires them to its
 Javascript client where it is ultimately displayed:

docs/source/changelog.rst

@@ -1,6 +1,43 @@
 Changelog
 =========
 
+
+0.32.0
+------
+
+In addition to a variety of bug fixes and other minor improvements, there's a breaking
+change to the custom component interface - instead of exporting multiple functions that
+render custom components, we simply expect a single ``bind()`` function.
+binding function then must return an object with a ``render()`` and ``unmount()``
+function. This change was made in order to better support the rendering of child models.
+See :ref:`Custom JavaScript Components` for details on the new interface.
+
+**Closed Issues**
+
+- Docs broken on Firefox - :issue:`469`
+- URL resolution for web modules does not consider urls starting with / - :issue:`460`
+- Query params in package name for module_from_template not stripped - :issue:`455`
+- Make docs section margins larger - :issue:`450`
+- Search broken in docs - :issue:`443`
+- Move src/idom/client out of Python package - :issue:`429`
+- Use composition instead of classes with Layout and LifeCycleHook  - :issue:`412`
+- Remove Python language extension - :issue:`282`
+- Add keys to models so React doesn't complain of child arrays requiring them -
+  :issue:`255`
+- Fix binder link in docs - :issue:`231`
+
+**Pull Requests**
+
+- Update issue form - :pull:`471`
+- improve heading legibility - :pull:`470`
+- fix search in docs by upgrading sphinx - :pull:`462`
+- rework custom component interface with bind() func - :pull:`458`
+- parse package as url path in module_from_template - :pull:`456`
+- add file extensions to import - :pull:`439`
+- fix key warnings - :pull:`438`
+- fix #429 - move client JS to top of src/ dir - :pull:`430`
+
+
 0.31.0
 ------
 

docs/source/core-abstractions.rst

@@ -12,7 +12,7 @@ the adage "the best code is no code at all," we make the related claim that "the
 way to manage state is to have no state at all."
 
 With IDOM the core of your application will be built on the back of basic functions and
-coroutines that return :ref:`VDOM <VDOM Mimetype>` models and which do so without state
+coroutines that return :ref:`VDOM` models and which do so without state
 and without `side effects`_. We call these kinds of model rendering functions
 :ref:`Pure Components`. For example, one might want a function which
 accepted a list of strings and turned it into a series of paragraph elements:
@@ -54,7 +54,7 @@ whose body contains a hook usage. We'll demonstrate that with a simple
 Component Layout
 ----------------
 
-Displaying components requires you to turn them into :ref:`VDOM <VDOM Mimetype>`. This
+Displaying components requires you to turn them into :ref:`VDOM`. This
 transformation, known as "rendering a component", is done by a
 :class:`~idom.core.proto.LayoutType`. Layouts are responsible for rendering components
 and scheduling their re-renders when they change. IDOM's concrete

docs/source/faq.rst

@@ -36,7 +36,7 @@ work, even those that don't rely on React.
 How does IDOM communicate with the client?
 ------------------------------------------
 
-IDOM sends diffs of a Virtual Document Object Model (:ref:`VDOM <VDOM Mimetype>`) to the
+IDOM sends diffs of a Virtual Document Object Model (:ref:`VDOM`) to the
 client. For more details, see the description in
 `this article <https://ryanmorshead.com/articles/2021/idom-react-but-its-python/article/#virtual-document-object-model>`__.
 

docs/source/handling-events.rst

@@ -3,7 +3,7 @@ Handling Events
 
 When :ref:`Getting Started`, we saw how IDOM makes it possible to write server-side code
 that defines basic views and can react to client-side events. The simplest way to listen
-and respond to events is by assigning a callable object to a :ref:`VDOM <VDOM Mimetype>`
+and respond to events is by assigning a callable object to a :ref:`VDOM`
 an attribute where event signals are sent. This is relatively similar to
 `handling events in React`_:
 

docs/source/javascript-components.rst

@@ -72,7 +72,7 @@ adheres to the following interface:
     }
 
     type bind = (node: HTMLElement, context: LayoutContext) => ({
-        render(component: any, props: Object, children: Array<any>): void;
+        render(component: any, props: Object, childModels: Array<any>): void;
         unmount(): void;
     });
 
@@ -88,7 +88,10 @@ adheres to the following interface:
     - ``props`` is an object containing attributes and callbacks for the given
       ``component``.
 
-    - ``children`` is an array of unrendered VDOM elements.
+    - ``childModels`` is an array of unrendered VDOM elements. Passing them in this raw
+      form allows for other frameworks besides react to render them as needed. If you
+      are using react, you can just use the ``idom-client-react`` library to process
+      them. See :ref:`Distributing Javascript via PyPI` for an example usage.
 
 The interface returned by ``bind()`` can be thought of as being similar to that of
 React.
@@ -215,12 +218,26 @@ To start, let's take a look at the file structure we'll be building:
 
     import * as React from "react";
     import * as ReactDOM from "react-dom";
+    import { LayoutConfigContext, elementChildren } from "idom-client-react";
+
+    export function bind(node, config) {
+        return {
+            render: (component, props, childModels) =>
+            ReactDOM.render(createElement(config, component, props, childModels), node),
+            unmount: () => ReactDOM.unmountComponentAtNode(node),
+        };
+    }
 
-    // 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;
+    function createElement(config, component, props, childModels) {
+        // Render child models with idom-client-react
+        return React.createElement(
+            LayoutConfigContext.Provider,
+            { value: config },
+            React.createElement(
+            component, props, ...elementChildren(children)
+            )
+        )
+    }
 
     // exports for your components
     export YourFirstComponent(props) {...};
@@ -248,6 +265,7 @@ Your ``package.json`` should include the following:
       "dependencies": {
         "react": "^17.0.1",
         "react-dom": "^17.0.1",
+        "idom-client-react": "^0.8.5",
         ...
       },
       ...

docs/source/specifications.rst

@@ -2,17 +2,16 @@ Specifications
 ==============
 
 Describes various data structures and protocols used to define and communicate virtual
-document object models (:ref:`VDOM <VDOM Mimetype>`). The definitions to below follow in
-the footsteps of
+document object models (:ref:`VDOM`). The definitions below follow in the footsteps of
 `a specification <https://github.com/nteract/vdom/blob/master/docs/mimetype-spec.md>`_
 created by `Nteract <https://nteract.io>`_ and which was built into
 `JupyterLab <https://jupyterlab.readthedocs.io/en/stable/>`_. While IDOM's specification
 for VDOM is fairly well established, it should not be relied until it's been fully
 adopted by the aforementioned organizations.
 
 
-VDOM Mimetype
--------------
+VDOM
+----
 
 A set of definitions that explain how IDOM creates a virtual representation of
 the document object model. We'll begin by looking at a bit of HTML that we'll convert
@@ -149,7 +148,10 @@ type name. The various properties for the ``onChange`` handler are:
   `here <https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation>`__.
 
 
-To clearly describe the VDOM schema we've created a `JSON Schema <https://json-schema.org/>`_:
+VDOM JSON Schema
+................
+
+To clearly describe the VDOM spec we've created a `JSON Schema <https://json-schema.org/>`_:
 
 .. literalinclude:: ./vdom-json-schema.json
    :language: json

src/idom/core/vdom.py

@@ -88,7 +88,7 @@
         },
     },
 }
-"""JSON Schema describing serialized VDOM - see :ref:`VDOM Mimetype` for more info"""
+"""JSON Schema describing serialized VDOM - see :ref:`VDOM` for more info"""
 
 
 # we can't add a docstring to this because Sphinx doesn't know how to find its source
@@ -283,7 +283,7 @@ class _VdomDictRequired(TypedDict, total=True):
 
 
 class VdomDict(_VdomDictRequired, _VdomDictOptional):
-    """A VDOM dictionary - see :ref:`VDOM Mimetype` for more info"""
+    """A :ref:`VDOM` dictionary"""
 
 
 class ImportSourceDict(TypedDict):
@@ -306,10 +306,7 @@ class _RequiredVdomJson(TypedDict, total=True):
 
 
 class VdomJson(_RequiredVdomJson, _OptionalVdomJson):
-    """A JSON serializable form of :class:`VdomDict` compliant with :data:`VDOM_JSON_SCHEMA`
-
-    For more information on this form see :ref:`VDOM Mimetype`.
-    """
+    """A JSON serializable form of :class:`VdomDict` matching the :data:`VDOM_JSON_SCHEMA`"""
 
 
 class _JsonEventTarget(TypedDict):