Plugin docs (#8)

* Start working on plugin docs.

* Add plugin docs to menu/reference.

* Move app_template_demo.py -> demos/

* Add plugin demos.

* Make plugin demos available to use in code examples.

* Plugins documentation.

* Move plugins docs to Guide

* Add file extension section.

* Make boxy_counter a subclass of counter.

* Plugin doc improvements.

* Make plugin examples available as local variables to `exec()`

* Remove unnecessary IIFE.

* Plugin docs fixes.

* Docs fixes.

* Remove boxy plugins section.

Author: mariusnita

hyperdiv_docs/code_examples.py

@@ -1,6 +1,8 @@
 import re
 from textwrap import dedent as dedent_text
 import hyperdiv as hd
+from .demos.counter_plugin import counter, boxy_counter
+from .demos.leaflet_plugin import leaflet
 
 
 def parse_doc(doc):
@@ -63,7 +65,15 @@ def code_example(code, code_to_execute=None):
                         state.error = None
                 else:
                     try:
-                        exec(dedent_text(code_to_execute), globals(), globals())
+                        exec(
+                            dedent_text(code_to_execute),
+                            globals(),
+                            dict(
+                                counter=counter,
+                                boxy_counter=boxy_counter,
+                                leaflet=leaflet,
+                            ),
+                        )
                     except Exception as e:
                         state.error = str(e)
 

hyperdiv_docs/demos/__init__.py

@@ -0,0 +1 @@
+from .counter import counter, boxy_counter

hyperdiv_docs/app_template_demo.py renamed to hyperdiv_docs/demos/app_template_demo.py

@@ -0,0 +1,9 @@
+button {
+  padding: 0.5rem;
+  background-color: var(--sl-color-blue-100);
+  border: none;
+  border-radius: var(--sl-border-radius-large);
+  cursor: pointer;
+  font-size: 1rem;
+  width: fit-content;
+}

hyperdiv_docs/demos/counter_plugin/__init__.py

@@ -0,0 +1,31 @@
+window.hyperdiv.registerPlugin("counter", (ctx) => {
+  let count = 0;
+  const button = document.createElement("button");
+  button.innerText = "Increment";
+  const countDiv = document.createElement("div");
+
+  const updateCount = (newCount) => {
+    count = newCount;
+    countDiv.innerText = count;
+  };
+
+  // On click, increment the count and send the updated
+  // prop value to Python:
+  button.addEventListener("click", () => {
+    updateCount(count + 1);
+    ctx.updateProp("count", count);
+  });
+
+  // Handle incoming prop updates from Python. We ignore
+  // `propValue` because there is only one prop, "count".
+  ctx.onPropUpdate((propName, propValue) => {
+    updateCount(propValue);
+  });
+
+  // Add the dom elements to the shadow root.
+  ctx.domElement.appendChild(button);
+  ctx.domElement.appendChild(countDiv);
+
+  // Initialize the plugin with the initial count.
+  updateCount(ctx.initialProps.count);
+});

hyperdiv_docs/demos/counter_plugin/assets/counter.css

@@ -0,0 +1,14 @@
+import os
+import hyperdiv as hd
+
+
+class counter(hd.Plugin):
+    _name = "counter"
+    _assets_root = os.path.join(os.path.dirname(__file__), "assets")
+    _assets = ["*"]
+
+    count = hd.Prop(hd.Int, 0)
+
+
+class boxy_counter(counter, hd.Boxy):
+    _classes = ["box"]

hyperdiv_docs/demos/counter_plugin/assets/counter.js

@@ -0,0 +1 @@
+from .leaflet import leaflet

hyperdiv_docs/demos/counter_plugin/counter.py

@@ -0,0 +1,40 @@
+window.hyperdiv.registerPlugin("leaflet", ctx => {
+  const L = window.L;
+
+  const props = {...ctx.initialProps};
+
+  const mapContainer = document.createElement("div");
+  mapContainer.style.width = "100%";
+  mapContainer.style.height = "100%";
+  ctx.domElement.appendChild(mapContainer);
+
+  const map = L.map(mapContainer);
+  map.setView([props.lat, props.lng], props.zoom);
+
+  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
+    maxZoom: 19,
+    attribution:
+    '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
+  }).addTo(map);
+
+  map.on("zoomend", () => {
+    props.zoom = map.getZoom();
+    ctx.updateProp("zoom", props.zoom);
+  });
+
+  map.on("moveend", () => {
+    const center = map.getCenter();
+    props.lat = center.lat;
+    props.lng = center.lng;
+    ctx.updateProp("lat", props.lat);
+    ctx.updateProp("lng", props.lng);
+  });
+
+  ctx.onPropUpdate((propName, propValue) => {
+    props[propName] = propValue;
+    map.setView([props.lat, props.lng], props.zoom);
+  });
+  
+  const resizeObserver = new ResizeObserver(() => map.invalidateSize());
+  resizeObserver.observe(mapContainer);
+});

hyperdiv_docs/demos/leaflet_plugin/__init__.py

@@ -0,0 +1,18 @@
+import os
+import hyperdiv as hd
+
+
+class leaflet(hd.Plugin):
+    _assets_root = os.path.join(os.path.dirname(__file__), "assets")
+    _assets = [
+        "https://unpkg.com/leaflet@1.9.4/dist/leaflet.css",
+        "https://unpkg.com/leaflet@1.9.4/dist/leaflet.js",
+        "leaflet-plugin.js",
+    ]
+
+    zoom = hd.Prop(hd.Int, 13)
+    lat = hd.Prop(hd.Float, 51.505)
+    lng = hd.Prop(hd.Float, -0.09)
+
+    def __init__(self, height=20, **kwargs):
+        super().__init__(height=height, **kwargs)

hyperdiv_docs/demos/leaflet_plugin/assets/leaflet-plugin.js

@@ -2,7 +2,7 @@
 import hyperdiv as hd
 from .router import router
 from .menu import menu
-from .app_template_demo import main as demo_main
+from .demos.app_template_demo import main as demo_main
 
 
 def render_title(slot=None):

hyperdiv_docs/demos/leaflet_plugin/leaflet.py

@@ -16,6 +16,7 @@
 from .pages.guide.static_assets import static_assets
 from .pages.guide.deploying import deploying
 from .pages.guide.matplotlib_charts import matplotlib_charts
+from .pages.guide.plugins import plugins
 
 from .pages.reference.components import components
 from .pages.reference.env_variables import env_variables
@@ -44,6 +45,7 @@
         "Using The App Template": {"href": using_the_app_template.path},
         "Matplotlib Charts": {"href": matplotlib_charts.path},
         "Static Assets": {"href": static_assets.path},
+        "Building Custom Components": {"href": plugins.path},
         "Deploying Hyperdiv": {"href": deploying.path},
     },
     "Reference": {