complete minimum doc update

Author: rmorshea

docs/source/core-concepts.rst

@@ -26,14 +26,32 @@ accepted a list of strings and turned it into a series of paragraph elements:
 
 .. code-block::
 
-    def Paragraphs(list_of_text):
+    def paragraphs(list_of_text):
         return idom.html.div([idom.html.p(text) for text in list_of_text])
 
 
 Stateful Elements
 -----------------
 
-...
+A Stateful Element is one which uses a :ref:`Life Cycle Hook`. These lifecycle hooks
+allow you to add state to otherwise stateless functions. To create a stateful element
+you'll need to apply the :func:`~idom.core.element.element` decorator to a coroutine_
+whose body contains a hook usage. We'll demonstrate that with a simple
+:ref:`click counter`:
+
+.. testcode::
+
+    import idom
+
+
+    @idom.element
+    async def ClickCount():
+        count, set_count = idom.hooks.use_state(0)
+
+        return idom.html.button(
+            {"onClick": lambda event: set_count(count + 1)},
+            [f"Click count: {count}"],
+        )
 
 
 Element Layout
@@ -45,22 +63,54 @@ elements (turning them into VDOM) and scheduling their re-renders when they
 :meth:`~idom.core.layout.Layout.update`. To create a layout, you'll need an
 :class:`~idom.core.element.Element` instance, which will become its root, and won't
 ever be removed from the model. Then you'll just need to call and await a
-:meth:`~idom.core.layout.Layout.render` which will return a bundle containing VDOM:
+:meth:`~idom.core.layout.Layout.render` which will return a :ref:`JSON Patch`:
 
 .. testcode::
 
-    ...
+    async with idom.Layout(ClickCount()) as layout:
+        patch = await layout.render()
 
 The layout also handles the triggering event handlers. Normally this is done
-automatically by a :ref:`Renderer <Layout Renderer>`, but for now we'll do this
-manually by digging into the :class:`~idom.core.layout.LayoutUpdate` object to find
-the ID of ``click_count``'s event handler so we can execute it. Once we have the ID, we
-can pass it, and a fake event, to the layout's :meth:`~idom.core.layout.Layout.trigger`
-method. Then we just have to re-render the layout and see what changed:
+automatically by a :ref:`Renderer <Layout Renderer>`, but for now we'll to it manually.
+To do use we can use a trick to hard-code the ``event_handler_id`` so we can pass it,
+and a fake event, to the layout's :meth:`~idom.core.layout.Layout.trigger` method. Then
+we just have to re-render the layout and see what changed:
 
 .. testcode::
 
-    ...
+    from idom.core.layout import LayoutEvent
+
+
+    event_handler_id = "on-click"
+
+
+    @idom.element
+    async def ClickCount():
+        count, set_count = idom.hooks.use_state(0)
+
+        @idom.event(target_id=event_handler_id)  # <-- trick to hard code event handler ID
+        def on_click(event):
+            set_count(count + 1)
+
+        return idom.html.button(
+            {"onClick": on_click},
+            [f"Click count: {count}"],
+        )
+
+
+    async with idom.Layout(ClickCount()) as layout:
+        patch_1 = await layout.render()
+
+        fake_event = LayoutEvent(event_handler_id, [{}])
+        await layout.trigger(fake_event)
+        patch_2 = await layout.render()
+
+        for change in patch_2.changes:
+            if change["path"] == "/children/0":
+                count_did_increment = change["value"] == "Click count: 1"
+
+        assert count_did_increment
+
 
 Layout Renderer
 ---------------
@@ -80,19 +130,19 @@ callback that's called by the renderer to events it should execute.
     from idom.core import SingleStateRenderer, EventHandler
     from idom.core.layout import LayoutEvent
 
-    sent_updates = []
+
+    sent_patches = []
 
 
-    async def send(update):
-        sent_updates.append(update)
-        if len(sent_updates) == 5:
+    async def send(patch):
+        sent_patches.append(patch)
+        if len(sent_patches) == 5:
             # if we didn't cancel the renderer would continue forever
             raise asyncio.CancelledError()
 
 
     async def recv():
-        fake_event_data = [{}]
-        event = LayoutEvent(event_handler_id, fake_event_data)
+        event = LayoutEvent(event_handler_id, [{}])
 
         # We need this so we don't flood the render loop with events.
         # In practice this is never an issue since events won't arrive
@@ -102,11 +152,11 @@ callback that's called by the renderer to events it should execute.
         return event
 
 
-    async with SingleStateRenderer(idom.Layout(ClickCount(0))) as renderer:
+    async with SingleStateRenderer(idom.Layout(ClickCount())) as renderer:
         context = None  # see note below
         await renderer.run(send, recv, context)
 
-    assert len(sent_updates) == 5
+    assert len(sent_patches) == 5
 
 
 .. note::
@@ -140,9 +190,9 @@ starting to add support for asyncio like
 In the case of our :class:`~idom.server.sanic.SanicRenderServer` types we have one
 implementation per builtin :ref:`Renderer <Layout Renderer>`:
 
-- :class:`idom.server.sanic.PerClientState`
+- :class:`idom.server.sanic.PerClientStateServer`
 
-- :class:`idom.server.sanic.SharedClientState`
+- :class:`idom.server.sanic.SharedClientStateServer`
 
 The main thing to understand about server implementations is that they can function in
 two ways - as a standalone application or as an extension to an existing application.
@@ -157,13 +207,13 @@ the model:
 .. code-block:: python
 
     import idom
-    from idom.server.sanic import PerClientState
+    from idom.server.sanic import PerClientStateServer
 
     @idom.element
     def View(self):
         return idom.html.h1(["Hello World"])
 
-    app = PerClientState(View)
+    app = PerClientStateServer(View)
     app.run("localhost", 5000)
 
 
@@ -184,11 +234,12 @@ The implementation registers hooks into the application to server the model once
     def View(self):
         return idom.html.h1(["Hello World"])
 
-    per_client_state = PerClientState(View)
+    per_client_state = PerClientStateServer(View)
     per_client_state.register(app)
 
     app.run("localhost", 5000)
 
 
 .. _pure functions: https://en.wikipedia.org/wiki/Pure_function
 .. _side effects: https://en.wikipedia.org/wiki/Side_effect_(computer_science)
+.. _coroutine: https://docs.python.org/3/glossary.html#term-coroutine

docs/source/examples.rst

@@ -76,6 +76,14 @@ Try clicking the image 🖱️
 .. interactive-widget:: slideshow
 
 
+Click Counter
+-------------
+
+.. literalinclude:: examples/click_count.py
+
+.. interactive-widget:: click_count
+
+
 To Do List
 ----------
 

docs/source/examples/click_count.py

@@ -2,13 +2,13 @@
 
 
 @idom.element
-async def ClickCount(self):
-    count, set_count = idom.hook.use_state(0)
+async def ClickCount():
+    count, set_count = idom.hooks.use_state(0)
 
-    async def increment(event):
-        set_count(count + 1)
-
-    return idom.html.button({"onClick": increment}, [f"Click count: {count}"])
+    return idom.html.button(
+        {"onClick": lambda event: set_count(count + 1)},
+        [f"Click count: {count}"],
+    )
 
 
 display(ClickCount)

docs/source/index.rst

@@ -12,9 +12,9 @@ Libraries for defining and controlling interactive webpages with Python
 
     installation
     getting-started
+    core-concepts
     life-cycle-hooks
     javascript-modules
-    core-concepts
     how-it-works
     specifications
     extra-features

docs/source/known-issues.rst

@@ -4,3 +4,4 @@ Known Issues
 .. [GH166] https://github.com/rmorshea/idom/issues/166
 .. [GH195] https://github.com/rmorshea/idom/issues/195
 .. [GH202] https://github.com/idom-team/idom/issues/202
+.. [GH203] https://github.com/idom-team/idom/issues/203

docs/source/life-cycle-hooks.rst

@@ -8,8 +8,8 @@ cases the :ref:`**Basic Hooks**` should be enough, however the remaining
 
 .. note::
 
-    At the moment not all of React's built-in hooks have been implemented. In the
-    future they will be added as the need arises.
+    Not all of React's built-in hooks have been implemented. In the future they will be
+    added, but if you have a particular need for a missing hook post an issue [GH203]_.
 
 .. contents::
   :local:
@@ -290,3 +290,4 @@ Under construction...
 .. _side effects: https://en.wikipedia.org/wiki/Side_effect_(computer_science)
 .. _memoization: https://en.wikipedia.org/wiki/Memoization
 .. _premature optimization: https://en.wikiquote.org/wiki/Donald_Knuth#Computer_Programming_as_an_Art_(1974)
+.. _gh issues: https://github.com/idom-team/idom/issues

docs/source/specifications.rst

@@ -162,4 +162,9 @@ To clearly describe the VDOM schema we've created a `JSON Schema <https://json-s
 JSON Patch
 ----------
 
-Under construction...
+Updates to VDOM modules are sent using the `JSON Patch`_ specification.
+
+... this section is still under construction :)
+
+
+.. _JSON Patch:: http://jsonpatch.com/

idom/core/layout.py

@@ -147,7 +147,7 @@ async def _create_layout_update(self, element: AbstractElement) -> LayoutUpdate:
         old_model = element_state.model.copy()  # we copy because it will be mutated
         new_model = await self._render_element(element_state)
         changes = make_patch(old_model, new_model).patch
-        return element_state.path, changes
+        return LayoutUpdate(path=element_state.path, changes=changes)
 
     async def _render_element(self, element_state: ElementState) -> Dict[str, Any]:
         try: