allow jupyter widgets to be used in reactpy components

Author: rmorshea

Diff for: notebooks/introduction.ipynb

@@ -4,13 +4,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# What is ReactPy?\n",
+    "<img src=\"https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-landscape.svg\" alt=\"ReactPy Logo\" style=\"min-width: 300px; width: 35%\" />\n",
     "\n",
-    "ReactPy connects your Python web framework of choice to a ReactJS frontend, allowing you to create **interactive websites without needing JavaScript!**\n",
+    "---\n",
     "\n",
-    "Following ReactJS styling, web elements are combined into [reusable \"components\"](https://reactpy.dev/docs/guides/creating-interfaces/your-first-components/index.html#parametrizing-components). These components can utilize [hooks](https://reactpy.dev/docs/reference/hooks-api.html) and [events](https://reactpy.dev/docs/guides/adding-interactivity/responding-to-events/index.html#async-event-handlers) to create infinitely complex web pages.\n",
+    "[ReactPy](https://reactpy.dev/) is a library for building user interfaces in Python without Javascript. ReactPy interfaces are made from components which look and behave similarly to those found in [ReactJS](https://reactjs.org/). Designed with simplicity in mind, ReactPy can be used by those without web development experience while also being powerful enough to grow with your ambitions.\n",
     "\n",
-    "When needed, ReactPy can [use components directly from NPM](https://reactpy.dev/docs/guides/escape-hatches/javascript-components.html#dynamically-loaded-components). For additional flexibility, components can also be [fully developed in JavaScript](https://reactpy.dev/docs/guides/escape-hatches/javascript-components.html#custom-javascript-components).\n",
     "\n",
     "\n",
     "# Getting Started\n",
@@ -60,7 +59,7 @@
    },
    "outputs": [],
    "source": [
-    "from reactpy import component, html, run\n",
+    "from reactpy import component, html\n",
     "\n",
     "\n",
     "@component\n",
@@ -186,7 +185,29 @@
    "source": [
     "# Using ReactPy With Jupyter Widgets\n",
     "\n",
-    "While you can use ReactPy components independently, it may also be useful to integrate them with the rest of the Jupyter Widget ecosystem. Let's consider a ReactPy component that responds to and displays changes from an `ipywidgets.IntSlider`. The ReactPy component will need to accept an `IntSlider` instance as one of its arguments, declare state that will track the slider's value, and register a lister that will update that state via the slider's `IntSlider.observe()` method using an [\"effect\"](https://reactpy.dev/docs/reference/hooks-api.html#use-effect):"
+    "It's possible to use Jupyter Widgets in ReactPy components if you convert them first using `reactpy_jupyter.from_widget`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from reactpy_jupyter import from_widget\n",
+    "from ipywidgets import IntSlider\n",
+    "\n",
+    "slider_widget = IntSlider()\n",
+    "slider_component = from_widget(slider_widget)\n",
+    "\n",
+    "slider_component"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's consider a ReactPy component that responds to and displays changes from an `ipywidgets.IntSlider`. The ReactPy component will need to accept an `IntSlider` instance as one of its arguments, convert it to a component with `from_widget`, declare state that will track the slider's value, and register a lister that will update that state via the slider's `IntSlider.observe()` method using an [\"effect\"](https://reactpy.dev/docs/reference/hooks-api.html#use-effect):"
    ]
   },
   {
@@ -198,10 +219,12 @@
    "outputs": [],
    "source": [
     "from reactpy import use_effect\n",
+    "from reactpy_jupyter import from_widget\n",
     "\n",
     "\n",
     "@component\n",
     "def SliderObserver(slider):\n",
+    "    slider_component = from_widget(slider)\n",
     "    value, set_value = use_state(0)\n",
     "\n",
     "    @use_effect\n",
@@ -214,14 +237,14 @@
     "        # unobserve the slider's value if this component is no longer displayed\n",
     "        return lambda: slider.unobserve(handle_change, \"value\")\n",
     "\n",
-    "    return html.p(f\"ReactPy observes the value to be: \", value)"
+    "    return html.div(slider_component, html.p(f\"ReactPy observes the value to be: \", value))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now you'll need to display the `SliderObserver` component as well as an `IntSlider` widget. To do this, you'll want wrap the component in a `reactpy_jupyter.LayoutWidget` instance before using it alongside other Jupyter Widgets. Specifically, you'll be displaying the `SliderObserver` and `IntSlider` in a `Box`:\n"
+    "Now you need to pass the `SliderObserver` component an `IntSlider` widget and display it.\n"
    ]
   },
   {
@@ -232,20 +255,16 @@
    },
    "outputs": [],
    "source": [
-    "from ipywidgets import Box, IntSlider\n",
-    "from reactpy_jupyter import LayoutWidget\n",
-    "\n",
-    "slider = IntSlider(readout=False)\n",
-    "slider_observer = LayoutWidget(SliderObserver(slider))\n",
+    "from ipywidgets import IntSlider\n",
     "\n",
-    "Box([slider, slider_observer])"
+    "SliderObserver(IntSlider(readout=False))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If it becomes painful to wrap every ReactPy component in a `LayoutWidget` you can create an alternate `LayoutWidget` constructor using `reactpy_jupyter.widgetize`:"
+    "You can also include ReactPy components within Jupyter Widgets using `reactpy_jupyter.to_widget`"
    ]
   },
   {
@@ -256,21 +275,34 @@
    },
    "outputs": [],
    "source": [
-    "from reactpy_jupyter import widgetize\n",
-    "\n",
-    "SliderObserverWidget = widgetize(SliderObserver)\n",
+    "from ipywidgets import Box\n",
+    "from reactpy_jupyter import to_widget\n",
     "\n",
     "slider = IntSlider(readout=False)\n",
-    "slider_observer = SliderObserverWidget(slider)\n",
+    "slider_observer_widget = to_widget(SliderObserver(slider))\n",
     "\n",
-    "Box([slider, slider_observer])"
+    "Box([slider, slider_observer_widget])"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "It's worth noting that, while ReactPy can be used with Jupyter Widgets, the reverse is not true. That is, **you cannot use a Jupyter Widget inside a ReactPy component**. If this is a capability you would find useful, please [start a discussion](https://github.com/reactive-python/reactpy/discussions). The ReactPy team would be very interested to hear how allowing Jupyter Widgets to be used with ReactPy could facilitate your work."
+    "If it becomes painful to convert every ReactPy component to a jupyter widget you can create an alternate widget constructor:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "slider = IntSlider(readout=False)\n",
+    "slider_observer_constructor = to_widget(SliderObserver)\n",
+    "observer_1 = slider_observer_constructor(slider)\n",
+    "observer_2 = slider_observer_constructor(slider)\n",
+    "\n",
+    "Box([observer_1, observer_2])"
    ]
   },
   {