fix #164 add basic docs for ES modules

Author: rmorshea

docs/source/index.rst

@@ -19,6 +19,7 @@ Libraries for defining and controlling interactive webpages with Python
     extra-features
     examples
     glossary
+    known-issues
     api
 
 

docs/source/javascript-modules.rst

@@ -12,10 +12,15 @@ pure Python, there are other projects which already allow you to do this inside
 or in
 `webpages <https://blog.jupyter.org/and-voil%C3%A0-f6a2c08a4a93?gi=54b835a2fcce>`__.
 The real power of IDOM comes from its ability to seemlessly leverage the existing
-ecosystem of `React components <https://reactjs.org/docs/components-and-props.html>`__.
-So long as you can install a React library using `Snowpack <https://www.snowpack.dev/>`__
-you can use it in your IDOM layout. You can even define your own Javascript modules
-which use these third party Javascript packages.
+ecosystem of
+`React components <https://reactjs.org/docs/components-and-props.html>`__.
+So long as your library of interest is an
+`ES Module <https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/>`__
+you could install using
+`Snowpack <https://www.snowpack.dev/>`__
+you can use it with IDOM (we're working to support non-standard packages too) [GH-166]_.
+You can even define your own Javascript modules which use these third party Javascript
+packages.
 
 
 Installing React Components
@@ -29,7 +34,8 @@ Installing React Components
 
 Once you've done this you can get started right away. In this example we'll be using a
 charting library for React called `Victory <https://formidable.com/open-source/victory/>`__.
-Installing it in IDOM is quite simple:
+Installing it in IDOM is quite simple. Just create a :class:`~idom.widgets.utils.Module`,
+tell it what to install and specify ``install=True`` (we're working on a CLI for this) [GH-167]_:
 
 .. code-block::
 
@@ -54,12 +60,132 @@ Using the ``VictoryBar`` chart component is as simple as displaying it:
 
     display(VictoryBar)
 
+The output should look something like this:
+
+.. image:: ./static/victory_bar_default_chart.png
+
 
 Passing Props To Components
 ---------------------------
 
-Under construction...
+So now that we can install and display a dependency we probably want to pass data or
+callbacks to it. This can be done in just the same way as you learned to do when
+:ref:`getting started`. In the following example we'll be using a
+`Button <https://react.semantic-ui.com/elements/button/>`__
+component from the
+`Semantic UI <https://react.semantic-ui.com/>`__
+framework. We'll register callbacks and pass props to the ``<Button/>`` just as you
+would for any other element in IDOM:
+
+.. code-block::
+
+    import idom
+
+    semantic_ui = idom.Module("semantic-ui-react", install=True)
+    Button = semantic_ui.Import("Button")
+
+    semantic_ui_style = idom.html.link(
+        {
+            "rel": "stylesheet",
+            "href": "//cdn.jsdelivr.net/npm/[email protected]/dist/semantic.min.css",
+        }
+    )
+
+    @idom.element
+    async def PrimarySecondaryButtons(self):
+
+        async def on_click_primary(event, info):
+            print("Primary Clicked:")
+            print(event)
+            print(info)
+
+        async def on_click_secondary(event, info):
+            print("Secondary Clicked:")
+            print(event)
+            print(info)
+
+        return idom.html.div(
+            [
+                semantic_ui_style,
+                Button({"primary": True, "onClick": on_click_primary}, ["Primary"]),
+                Button({"secondary": True, "onClick": on_click_secondary}, ["Secondary"]),
+            ]
+        )
+
+    display(PrimarySecondaryButtons)
+
+Which should produce the following output when interacted with:
+
+.. image:: ./static/primary_secondary_buttons.png
 
 
 Defining Your Own Modules
 -------------------------
+
+While it's probably best to create
+`a real package <https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry>`__
+for your Javascript, if you're just experimenting it might be easiest to just quickly
+hook in a module of your own making on the fly. As before, we'll be using a
+:class:`~idom.widgets.utils.Module`, however this time we'll pass it a ``source``
+parameter which is a file-like object. In this example we'll use Victory again, but
+this time we'll add a callback to it. Unfortunately we can't just pass it in
+:ref:`like we did before <Passing Props To Components>` because Victory's event API
+is a bit more complex so we've implemented a quick wrapper for it in a file ``chart.js``.
+
+.. code-block:: javascript
+
+    import React from "./react.js";
+    import { VictoryBar, VictoryChart, VictoryTheme, Bar } from "./victory.js";
+    import htm from "./htm.js";
+
+    const html = htm.bind(React.createElement);
+
+    export default {
+      ClickableChart: function ClickableChart(props) {
+        return html`
+          <${VictoryChart}
+            theme=${VictoryTheme.material}
+            style=${{"style": {"parent": {"width": "500px"}}}}
+            domainPadding=${20}
+          >
+            <${VictoryBar}
+              data=${props.data}
+              dataComponent=${html`
+                <${Bar}
+                  events=${{
+                    onClick: props.onClick,
+                  }}
+                />
+              `}
+            />
+          <//>
+        `;
+      },
+    };
+
+Which we can read in as a ``source`` to :class:`~idom.widgets.utils.Module`:
+
+.. code-block::
+
+    with open("chart.js") as f:
+        ClickableChart = idom.Module("chart", source=f).Import("ClickableChart")
+
+    async def handle_event(event):
+        print(event)
+
+    data = [
+        {"x": 1, "y": 2},
+        {"x": 2, "y": 4},
+        {"x": 3, "y": 7},
+        {"x": 4, "y": 3},
+        {"x": 5, "y": 5},
+    ]
+
+    display(
+        ClickableChart,
+        {"data": data, "onClick": handle_event}
+    )
+
+The above usag should then produce the following output when you click the bars in the chart:
+
+.. image:: ./static/custom_victory_chart.png

docs/source/known-issues.rst

@@ -0,0 +1,5 @@
+Known Issues
+============
+
+.. [GH-166] https://github.com/rmorshea/idom/issues/166
+.. [GH-167] https://github.com/rmorshea/idom/issues/167