add inital work for responding to events

print statements in examples are now displayed in the same view

Author: rmorshea

docs/app.py

@@ -4,7 +4,6 @@
 
 from sanic import Sanic, response
 
-from idom.config import IDOM_WED_MODULES_DIR
 from idom.server.sanic import PerClientStateServer
 from idom.widgets import multiview
 
@@ -42,8 +41,8 @@ def run():
 
 def make_app():
     app = Sanic(__name__)
+
     app.static("/docs", str(HERE / "build"))
-    app.static("/_modules", str(IDOM_WED_MODULES_DIR.current))
 
     @app.route("/")
     async def forward_to_index(request):

docs/examples.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from io import StringIO
 from pathlib import Path
 from traceback import format_exc
 from typing import Callable, Iterator
@@ -32,6 +33,7 @@ def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
         raise FileNotFoundError(str(file))
 
     captured_component_constructor = None
+    capture_print, ShowPrint = _printout_viewer()
 
     def capture_component(component_constructor):
         nonlocal captured_component_constructor
@@ -40,7 +42,7 @@ def capture_component(component_constructor):
     idom.run = capture_component
     try:
         code = compile(file.read_text(), str(file.absolute()), "exec")
-        exec(code, {})
+        exec(code, {"print": capture_print})
     except Exception:
         return _make_error_display()
     finally:
@@ -49,7 +51,12 @@ def capture_component(component_constructor):
     if captured_component_constructor is None:
         return _make_example_did_not_run(str(file))
     else:
-        return captured_component_constructor
+
+        @idom.component
+        def Wrapper():
+            return idom.html.div(captured_component_constructor(), ShowPrint())
+
+        return Wrapper
 
 
 def get_example_name_from_file(file: Path) -> str:
@@ -64,6 +71,37 @@ def get_js_example_file_by_name(name: str) -> Path:
     return EXAMPLES_DIR.joinpath(*name.split(".")).with_suffix(".js")
 
 
+def _printout_viewer():
+    print_callbacks: set[Callable[[str], None]] = set()
+
+    @idom.component
+    def ShowPrint():
+        buffer = idom.hooks.use_state(StringIO)[0]
+        update = _use_force_update()
+
+        @idom.hooks.use_effect
+        def add_buffer():
+            print_callbacks.add(buffer.write)
+            update()
+
+        value = buffer.getvalue()
+        return idom.html.pre({"class": "printout"}, value) if value else idom.html.div()
+
+    def capture_print(*args, **kwargs):
+        buffer = StringIO()
+        print(*args, file=buffer, **kwargs)
+        value = buffer.getvalue()
+        for cb in print_callbacks:
+            cb(value)
+
+    return capture_print, ShowPrint
+
+
+def _use_force_update():
+    toggle, set_toggle = idom.hooks.use_state(False)
+    return lambda: set_toggle(not toggle)
+
+
 def _make_example_did_not_run(example_name):
     @idom.component
     def ExampleDidNotRun():

docs/source/_examples/adding_interactivity/button_does_nothing.py

@@ -0,0 +1,9 @@
+from idom import component, html, run
+
+
+@component
+def Button():
+    return html.button("I don't do anything yet")
+
+
+run(Button)

docs/source/_examples/adding_interactivity/button_prints_event.py

@@ -0,0 +1,12 @@
+from idom import component, html, run
+
+
+@component
+def Button():
+    def handle_event(event):
+        print(event)
+
+    return html.button({"onClick": handle_event}, "Print event to terminal")
+
+
+run(Button)

docs/source/_static/css/interactive-widget.css

@@ -6,10 +6,17 @@
 }
 .widget-container {
   padding: 15px;
+  overflow: auto;
   background-color: var(--color-code-background);
   min-height: 75px;
 }
 
+.widget-container .printout {
+  margin-top: 20px;
+  border-top: solid 2px var(--color-foreground-border);
+  padding-top: 20px;
+}
+
 .widget-container > div {
   width: 100%;
 }

docs/source/_static/custom.js

@@ -1977,30 +1977,64 @@ function LazyPromise() {
   });
 }
 
-const LOC = window.location;
-const HTTP_PROTO = LOC.protocol;
-const WS_PROTO = HTTP_PROTO === "https:" ? "wss:" : "ws:";
-const IDOM_MODULES_PATH = "/_modules";
+function mountWithLayoutServer(
+  element,
+  serverInfo,
+  maxReconnectTimeout
+) {
+  const loadImportSource = (source, sourceType) =>
+    import(sourceType == "NAME" ? serverInfo.path.module(source) : source);
+
+  mountLayoutWithWebSocket(
+    element,
+    serverInfo.path.stream,
+    loadImportSource,
+    maxReconnectTimeout
+  );
+}
+
+function LayoutServerInfo({ host, port, path, query, secure }) {
+  const wsProtocol = "ws" + (secure ? "s" : "");
+  const httpProtocol = "http" + (secure ? "s" : "");
+
+  const uri = host + ":" + port;
+  const url = (uri + path).split("/").slice(0, -1).join("/");
+
+  const wsBaseUrl = wsProtocol + "://" + url;
+  const httpBaseUrl = httpProtocol + "://" + url;
+
+  this.path = {
+    stream: wsBaseUrl + "/stream" + "?" + query,
+    module: (source) => httpBaseUrl + `/modules/${source}`,
+  };
+}
 
 function mountWidgetExample(
   mountID,
   viewID,
   idomServerHost,
   useActivateButton
 ) {
-  const idomUrl  = "//" + (idomServerHost || LOC.host);
-  const httpIdomUrl = HTTP_PROTO + idomUrl ;
-  const wsIdomUrl = WS_PROTO + idomUrl ;
+  let idomHost, idomPort;
+  if (idomServerHost) {
+    [idomHost, idomPort] = idomServerHost.split(":", 2);
+  } else {
+    idomHost = window.location.hostname;
+    idomPort = window.location.port;
+  }
+
+  const serverInfo = new LayoutServerInfo({
+    host: idomHost,
+    port: idomPort,
+    path: "/_idom/",
+    query: `view_id=${viewID}`,
+    secure: window.location.protocol == "https",
+  });
 
   const mountEl = document.getElementById(mountID);
 
   if (!useActivateButton) {
-    mountLayoutWithWebSocket(
-      mountEl,
-      wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
-      (source, sourceType) =>
-        loadImportSource(httpIdomUrl, source, sourceType)
-    );
+    mountWithLayoutServer(mountEl, serverInfo);
     return;
   }
 
@@ -2013,12 +2047,7 @@ function mountWidgetExample(
       {
         mountEl.removeChild(enableWidgetButton);
         mountEl.setAttribute("class", "interactive widget-container");
-        mountLayoutWithWebSocket(
-          mountEl,
-          wsIdomUrl + `/_idom/stream?view_id=${viewID}`,
-          (source, sourceType) =>
-            loadImportSource(httpIdomUrl, source, sourceType)
-        );
+        mountWithLayoutServer(mountEl, serverInfo);
       }
     })
   );
@@ -2046,12 +2075,4 @@ function mountWidgetExample(
   mountEl.appendChild(enableWidgetButton);
 }
 
-function loadImportSource(baseUrl, source, sourceType) {
-  if (sourceType == "NAME") {
-    return import(baseUrl + IDOM_MODULES_PATH + "/" + source);
-  } else {
-    return import(source);
-  }
-}
-
 export { mountWidgetExample };

docs/source/adding-interactivity/index.rst

@@ -9,3 +9,110 @@ Adding Interactivity
     state-as-a-snapshot
     dangers-of-mutability
     batched-updates
+
+
+.. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
+    :color: info
+    :animate: fade-in
+    :open:
+
+    .. grid:: 2
+
+        .. grid-item-card:: :octicon:`bell` Responding to Events
+            :link: responding-to-events
+            :link-type: doc
+
+            ...
+
+        .. grid-item-card:: :octicon:`package-dependencies` Components With State
+            :link: components-with-state
+            :link-type: doc
+
+            ...
+
+        .. grid-item-card:: :octicon:`device-camera-video` State as a Snapshot
+            :link: state-as-a-snapshot
+            :link-type: doc
+
+            ...
+
+        .. grid-item-card:: :octicon:`issue-opened` Dangers of Mutability
+            :link: dangers-of-mutability
+            :link-type: doc
+
+            ...
+
+        .. grid-item-card:: :octicon:`versions` Batched Updates
+            :link: batched-updates
+            :link-type: doc
+
+            ...
+
+...
+
+
+Section 1: Responding to Events
+-------------------------------
+
+...
+
+.. card::
+    :link: responding-to-events
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    ...
+
+
+Section 2: Components with State
+--------------------------------
+
+.. card::
+    :link: components-with-state
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    ...
+
+
+Section 3: State as a Snapshot
+------------------------------
+
+.. card::
+    :link: state-as-a-snapshot
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    ...
+
+
+Section 4: Dangers of Mutability
+--------------------------------
+
+.. card::
+    :link: dangers-of-mutability
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    ...
+
+
+Section 3: Batched Updates
+--------------------------
+
+.. card::
+    :link: batched-updates
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    ...

docs/source/adding-interactivity/responding-to-events.rst

@@ -1,4 +1,29 @@
 Responding to Events
 ====================
 
-Under construction :)
+IDOM lets you add event handlers to your parts of the interface. This means that you can
+assign functions that are triggered when a particular user interaction occurs like
+clicking, hovering, of focusing on form inputs, and more.
+
+
+Adding Event Handlers
+---------------------
+
+To start out we'll just display a button that, for the moment, doesn't do anything:
+
+.. example:: adding_interactivity.button_does_nothing
+    :activate-result:
+
+To add an event handler to this button we'll do three things:
+
+1. Declare a function called ``handle_event(event)`` inside the body of our ``Button`` component
+2. Add logic to ``handle_event`` that will print the ``event`` it receives to the console.
+3. Add an ``"onClick": handle_event`` attribute to the ``<button>`` element.
+
+.. example:: adding_interactivity.button_prints_event
+    :activate-result:
+
+.. note::
+
+    Normally print statements will only be displayed in the terminal where you launched
+    the server.

docs/source/credits-and-licenses.rst

@@ -1,12 +1,12 @@
 Credits and Licenses
 ====================
 
-Much of this documentation was created with heavy influence from https://reactjs.org
-which uses the `Creative Commons Attribution 4.0 International
+Much of this documentation, including its layout and content, was created with heavy
+influence from https://reactjs.org which uses the `Creative Commons Attribution 4.0
+International
 <https://raw.githubusercontent.com/reactjs/reactjs.org/b2d5613b6ae20855ced7c83067b604034bebbb44/LICENSE-DOCS.md>`__
-license. While much of the content has been transformed in one way or another, we
-paraphrase or copy directly in places where React's behavior is mirroried by IDOM's.
-Additionally, the outline of the documentation closely mirror's React's documentation
+license. While many things have been transformed, we paraphrase and, in some places,
+copy language or examples where React's behavior is directly mirroried by IDOM's.
 
 
 Source Code License