examples/full_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d8ec9a76-0819-463d-8955-55789ee36400",
   "metadata": {},
   "source": [
    "# Ipyreact walkthrough"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "083f2dc7-c0ec-482f-a720-aa2896ad193e",
   "metadata": {
    "tags": []
   },
   "source": [
    "Welcome to this ipyreact walkthrough!   \n",
    "The tutorial will be based on a very simple react button to show all the ipyreact features.  \n",
    "\n",
    "**Content** \n",
    "* use the %react cell magic\n",
    "* write a widget\n",
    "* style this with CSS\n",
    "* add parameters to your widgets (traitlets)\n",
    "* interact with these parameters\n",
    "* simple traitlet oberservation using `change`\n",
    "* observe a traitlet and call python function\n",
    "* observe a traitlet and call JavaScript function\n",
    "* call python functions from JavaScript\n",
    "* loading components from external files\n",
    "* enable hot reloading  \n",
    "* enable autocompletion in IDEs\n",
    "* print a message at class initialization"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06cb067d-0aea-4851-827d-d07f22466693",
   "metadata": {},
   "source": [
    "First, we will use the **`%react` magic**  from ipyreact.  \n",
    "The following line registers the cellmagic:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de17b188",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%pip install -q ipyreact\n",
    "# This line is for JupyterLite (if this takes more than 10 seconds, something probably hung, restart the kernel and run this cell again)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d85f911",
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext ipyreact"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c70f7253-98d5-4131-bf6b-1ac3433e2985",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%react\n",
    "\n",
    "import * as React from \"react\";\n",
    "\n",
    "export default function MyButton() {\n",
    "    return ( < button > X < /button>);\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b51d34f-8abc-4b7b-936e-6d582a1b64fe",
   "metadata": {},
   "source": [
    "Great, here we can see react code rendering in the jupyter notebook!  \n",
    "Next, we **convert this into a widget.**  \n",
    "For that, we need the code in a `_esm` string inside a class that inherits from `ipyreact.Widget`.  \n",
    "`esm` is short for for EcmaScript module, and thats standard for structuring JavaScript code in reusable components."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7c70385c-638e-482b-80e1-6f27614da867",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton() {\n",
    "        return <button class=\"mybutton\"> X < /button> \n",
    "    };\n",
    "    \"\"\"\n",
    "\n",
    "MyExampleWidget()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3edaca1d",
   "metadata": {},
   "source": [
    "## HTML elements, children and props\n",
    "For simple built-in HTML elements that the browser supports, such as button, we can also use the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "46d2c198",
   "metadata": {},
   "outputs": [],
   "source": [
    "ipyreact.Widget(_type=\"button\", children=[\"X\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3652d77",
   "metadata": {},
   "source": [
    "In this case, ipyreact simply wraps [React's createElement](https://react.dev/reference/react/createElement) where children can be text, or an ipywidget. If the widget is a ipyreact widget, the react render tree will continue uninterrupted.\n",
    "\n",
    "The props are passed to the createElement function, and for builtin elements can be common attributes such as `style`, `class` and `title`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9bd41896",
   "metadata": {},
   "outputs": [],
   "source": [
    "ipyreact.Widget(_type=\"button\", children=[\"X\"], props={\n",
    "    \"title\": \"Behaves like a tooltip\",\n",
    "    \"style\": {\"border\": \"5px solid orange\"},\n",
    "    \"class\": \"mybutton\"\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35f22aef-50c2-4772-b9fa-44f5fb486ee6",
   "metadata": {},
   "source": [
    "## Styling\n",
    "\n",
    "Let's style this with CSS"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38e8afeb-274c-4c62-99a7-6200fc9c179d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from IPython.display import HTML\n",
    "css_rules = \"\"\"\n",
    ".mybutton {\n",
    "    background-color: yellow;\n",
    "    border-radius: 10px;\n",
    "}\n",
    "\"\"\"\n",
    "HTML(\"<style>\" + css_rules + \"</style>\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb19480f-b3c6-44be-968c-06edf944d42f",
   "metadata": {},
   "source": [
    "Note: Loading CSS styles is global and will include every cell of the notebook.   \n",
    "Also the widgets at the bottom of the notebook will be affected.  \n",
    "\n",
    "You can also load CSS from a file.  \n",
    "And you can add extra CSS without overwriting the previous CSS import."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4a644e0-1dbe-4f50-9bb5-5a54f1fedbaf",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from IPython.display import HTML\n",
    "from pathlib import Path\n",
    "css_rules = Path(\"styles_orange.css\").read_text()\n",
    "HTML(\"<style>\" + css_rules + \"</style>\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f571eadd-1a94-4ffe-af43-1c5ef1ec2498",
   "metadata": {
    "tags": []
   },
   "source": [
    "Note: When you clear the output of the previous cell, this CSS style will be removed from the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "148b8562",
   "metadata": {},
   "source": [
    "## Parametizing\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b50fbd27-5679-48ea-b2cc-ff9c5c79f826",
   "metadata": {
    "tags": []
   },
   "source": [
    "Next, we want to **add parameters to the widget.**  \n",
    "First naive approach: Using f-strings.\n",
    "That works, but is bad for two reasons:  \n",
    "1. curly brackets from f-strings will collide with the curly brackets from JavaScript/TypeScript. \n",
    "Using curly brackets in an f-string as a normal character can be done by doubling them like this : `{`to `{{`.  \n",
    "2. The f-string is only interpreted when the class is interpreted. That means it's won't be possible to change the value of `my_message` when interacting with the widget.\n",
    "   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6fdda6ec-d6df-42bb-964c-66b686596ff2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "\n",
    "# ❌❌❌  WARNING: THIS CODEBLOCK IS NOT GOOD PRACTICE ❌❌❌ \n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    message = \"Hello World\"\n",
    "    _esm = f\"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton() {{\n",
    "        return <button> {message} </button> \n",
    "    }};\"\"\"\n",
    "MyExampleWidget()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12d2a8a2",
   "metadata": {},
   "source": [
    "## Parametrizing using props\n",
    "\n",
    "If you only want to set a value from the Python side, you can use the props to pass data to the component in the frontend.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2af801c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Unicode\n",
    "\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ message }) {\n",
    "        return <button> {message} </button>;\n",
    "    };\"\"\"\n",
    "MyExampleWidget(props={\"message\": \"hi\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67118dd2",
   "metadata": {},
   "source": [
    "### Forwarding unused props and children\n",
    "However, with this, we lose the ability to set all the other props like in the example above. We can use the following pattern using [object destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#object_destructuring) by passing all unused props (called `rest` in this example) to the button element. Also, do not forget to pass the children!."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a26f1e3d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Unicode\n",
    "\n",
    "# ⭐⭐⭐  This is good practice again ⭐⭐⭐\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ message, children, ...rest }) {\n",
    "        return <button {...rest}> {[message, ...children]} </button>;\n",
    "    };\"\"\"\n",
    "MyExampleWidget(props={\"message\": \"hi\", \"title\": \"Behaves like a tooltip\"}, children=[' extra', ' children'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "944363e3-92b1-4ee6-8e16-1a2f6879fefb",
   "metadata": {},
   "source": [
    "## Adding state\n",
    "\n",
    "Props cannot be changed by the component, they are considered pure input.\n",
    "\n",
    "When you need the component to control state, you can add a trait ([see traitlets](https://traitlets.readthedocs.io/en/stable/using_traitlets.html)) to your widget class will (with `.tag(sync=True)` to make it sync to the frontend). For every trait added, you will receive a value and a setter to our props in the frontend.\n",
    "\n",
    "For instance, if you add a trait called `message`, you will have a `message` and `setMessage` in your props."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e27dc18-82f2-4598-9117-9e0cfec49f99",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Unicode\n",
    "\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    message = Unicode(\"Click me\").tag(sync=True)\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ message, setMessage }) {\n",
    "        return <button onClick={() => setMessage('Clicked ⭐')}> {message} </button>;\n",
    "    };\"\"\"\n",
    "w = MyExampleWidget()\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5dad7f59",
   "metadata": {},
   "source": [
    "Every time the component calls `setMessage` the component will rerender itself with the new value for `message`, but will also synchronize the value to the Python side. \n",
    "\n",
    "If we change the value from the Python side, the value gets send to the frontend, and the component will render with the new `message` value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5bc13be9",
   "metadata": {},
   "outputs": [],
   "source": [
    "w.message = \"Set from Python 🐍\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e2fb6dcb-4477-4ff5-a7d0-5e0f209d83cf",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# we can use this traitlets also as parameters\n",
    "MyExampleWidget(message=\"Different initial value\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a4436e2",
   "metadata": {},
   "source": [
    "It's great that python will throw an error when the wrong type is given!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4dba603f-8052-4d8d-845d-d28029e17c35",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Note that traits can be type checked, this will result in an error because message is not a string (it is an int)\n",
    "# w.message = 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30979edc",
   "metadata": {},
   "source": [
    "### ValueWidget\n",
    "\n",
    "Since it is very common that a component controls a single value (e.g. any input component, such as text input, a slider etc) we made a special subclass of `ipyreact.Widget` called `ipyreact.ValueWidget` that already contains a `value` trait.\n",
    "\n",
    "In many cases you do not even need to create a subclass, but can directly use the class to create an instance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2fbfdcf2",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Unicode\n",
    "\n",
    "\n",
    "# Although we can subclass, we don't need to in this case\n",
    "# class MyExampleValueWidget(ipyreact.ValueWidget):\n",
    "#     # we get a value trait for free\n",
    "#     _esm = \"\"\"\n",
    "#     import * as React from \"react\";\n",
    "\n",
    "#     export default function MyButton({ value, setValue }) {\n",
    "#         return <button onClick={() => setValue('Clicked ⭐')}> {value} </button>;\n",
    "#     };\"\"\"\n",
    "# MyExampleValueWidget(value=\"Similar, but using the value/ValueWidget\")\n",
    "\n",
    "\n",
    "# We can simply create an instance of ValueWidget\n",
    "\n",
    "ipyreact.ValueWidget(value=\"Similar, but using the value/ValueWidget\",\n",
    "    _esm=\"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ value, setValue }) {\n",
    "        return <button onClick={() => setValue('Clicked ⭐')}> {value} </button>;\n",
    "    };\"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "adb7a394",
   "metadata": {},
   "source": [
    "The upside of using the `ValueWidget` is that it is a subclass of `ipywidgets.ValueWidget` and therefore can be used in [interact](https://ipywidgets.readthedocs.io/en/latest/examples/Using%20Interact.html).\n",
    "\n",
    "Having a standard name (`value`) for the trait can be useful, but might loss semantics in your specific case.\n",
    "\n",
    "Note that you may be tempted to add in many traits, since it makes it easier to modify the state of the component. But be aware that for ever trait added, your props get both a `foo` and `setFoo`. Make sure you do not accidently pass the `setFoo` to your child elements, as they might not support it (e.g. button has no setFoo attribute).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cee4af9a",
   "metadata": {},
   "source": [
    "## Adding events\n",
    "\n",
    "Apart from the traits, the props trait, and the children, we also support events.\n",
    "\n",
    "The events dict is a mapping from event name to an event handler. Event names can be native browser events, such as onClick on native elements (e.g. button), but they can also be custom events.\n",
    "\n",
    "### Native events\n",
    "\n",
    "Native browser events are always of the form `on<Name>`, for instance, the [click](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) event will map to the `onClick` event name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "269558f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "def on_click(event_data):\n",
    "    w.children = [\"Clicked ⭐\"]\n",
    "    \n",
    "w = ipyreact.Widget(_type=\"button\",\n",
    "                    children=[\"Click me\"],\n",
    "                    props={\n",
    "                        \"title\": \"Behaves like a tooltip\",\n",
    "                        \"style\": {\"border\": \"5px solid orange\"},\n",
    "                        \"class\": \"mybutton\"\n",
    "                    },\n",
    "                    events={\"onClick\": on_click})\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "232e5e9c",
   "metadata": {},
   "source": [
    "### Custom events\n",
    "\n",
    "If you are creating your own component, you are free to name events anything you'd like. Note that event handlers can optionally take arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43016676",
   "metadata": {},
   "outputs": [],
   "source": [
    "def on_my_click(new_label):\n",
    "    w.children = [new_label]\n",
    "    \n",
    "    \n",
    "w = ipyreact.Widget(children=[\"Click me\"],\n",
    "    events={\"onMyClick\": on_my_click},\n",
    "    _esm=\"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ onMyClick, children }) {\n",
    "        return <button onClick={() => onMyClick('Clicked ⭐')}> {...children} </button>;\n",
    "    };\n",
    "    \"\"\"\n",
    ")\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2736a01",
   "metadata": {},
   "source": [
    "It is also possible to add methods with a subclass, prefixed with `event_` that will automatically be available in the props as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ae44863a",
   "metadata": {},
   "outputs": [],
   "source": [
    "class MyButton(ipyreact.Widget):\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ onMyClick, children }) {\n",
    "        return <button onClick={() => onMyClick('Clicked ⭐')}> {...children} </button>;\n",
    "    };\n",
    "    \"\"\"\n",
    "\n",
    "    # the method name should match the name in the props\n",
    "    def event_onMyClick(self, new_label):\n",
    "        w.children = [new_label]\n",
    "\n",
    "w = MyButton(children=[\"Click me\"])\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6b30c43",
   "metadata": {},
   "source": [
    "## Traitlet events / observe\n",
    "\n",
    "Since traits can be [observed for changes](https://traitlets.readthedocs.io/en/stable/using_traitlets.html#observe) we can also add an event handler to state changes (instead of the event handler solution is the previous example).\n",
    "\n",
    "Both solutions can be valid. Sometimes events go together with a state change, and observing a state change then makes sense. In cases where a pure event is emitted, that does not directly lead to a state change, this solution might not be the right one.\n",
    "\n",
    "The example below does combine an event with a state change, and we therefore use the `@observe` decorator to handle further state changes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24f42e00",
   "metadata": {},
   "outputs": [],
   "source": [
    "from traitlets import  Any, observe\n",
    "from traitlets import Int, Any\n",
    "import ipyreact\n",
    "\n",
    "def is_prime_number(n):\n",
    "    for i in range(2, n):\n",
    "        if n % i == 0:\n",
    "            return False\n",
    "    return True\n",
    "\n",
    "\n",
    "class PrimePythonWidget(ipyreact.Widget):\n",
    "    message = Any(\"Click to test the next number\").tag(sync=True)\n",
    "    number = Int(0).tag(sync=True)\n",
    "\n",
    "    @observe(\"number\")\n",
    "    def _observe_count(self, change):\n",
    "        if is_prime_number(self.number):\n",
    "            self.message = \"Yes ✅ it is a prime number\"\n",
    "        else:\n",
    "            self.message = \"No ❌, not a primer number\"\n",
    "        # alternatively: \n",
    "        # self.props = {**self.props, message: ....}\n",
    "\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    // NOTE: we add setMessage, even though we do not use it, to avoid forwarding\n",
    "    // it to button\n",
    "    export default function({setNumber, number, message, setMessage, ...rest}) {\n",
    "        return <div>\n",
    "            <button onClick={() => setNumber(number + 1)} {...rest}>\n",
    "                Testing {number} for prime\n",
    "            </button>\n",
    "            <br/>\n",
    "            <span>{message}</span>\n",
    "        </div>\n",
    "    };\"\"\"\n",
    "\n",
    "\n",
    "primepy = PrimePythonWidget(props={\"class\": \"mybutton\"})\n",
    "primepy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "448a0e28",
   "metadata": {},
   "source": [
    "Note that in this case, we have chosen to add `message` as a trait, instead of sending the `message` via the `props` trait. Since we also combine this with forwarding the rest of the props to the button, we *have* to take out the `setMessage` callback. If we do not, React will complain that the button element does not support the `setMessage` attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7476173b",
   "metadata": {},
   "source": [
    "## Components in files\n",
    "Having the JavaScript components in python string variables is good for the beginning.  \n",
    "That way the project is compact and there is no need of file switching.  \n",
    "\n",
    "As examples are getting longer, the JavaScript components can be written in separate files.  \n",
    "That way, you will also get JavaScript syntax hilighting.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2e1ce310",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "import pathlib\n",
    "\n",
    "class WidgetFromFile(ipyreact.Widget):\n",
    "    _esm = pathlib.Path(\"my_component.tsx\").read_text()\n",
    "\n",
    "WidgetFromFile()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23f1401c",
   "metadata": {},
   "source": [
    "If you don't want to re-run the python code after making changes to the file that contains the component, you can see changes happening immediately thanks to **hot-reloading**.\n",
    "This requires `pip install watchdog`.  \n",
    "Next, you replace the line  \n",
    "`_esm = pathlib.Path(\"my_component.tsx\").read_text()`  \n",
    "with   \n",
    "`_esm = pathlib.Path(\"my_component.tsx\")`  \n",
    "\n",
    "Now open `my_component.tsx`, change \"Hello World\" to \"Hi there\", and you will see that the changes are reflected immediately."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d7bd0c3c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "import pathlib\n",
    "\n",
    "class WidgetFromFile(ipyreact.Widget):\n",
    "    _esm = pathlib.Path(\"my_component.tsx\") # <- this will not work in JupyterLite\n",
    "\n",
    "WidgetFromFile()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b34a44f8",
   "metadata": {},
   "source": [
    "### Importing external modules\n",
    "\n",
    "Writing JSX code without having to compile/bundle is great, but so is using external libraries.\n",
    "\n",
    "Ipyreact uses ES modules, which allows native importing of external libraries when written as an ES module.\n",
    "In the example below, we use https://esm.sh/ which exposes many JS libraries as ES modules that\n",
    "we can directly import."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "381b5a21",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "\n",
    "ipyreact.ValueWidget(\n",
    "    _esm=\"\"\"\n",
    "    import confetti from \"https://esm.sh/canvas-confetti@1.6.0\";\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function({value, setValue}) {\n",
    "        return <button onClick={() => confetti() && setValue(value + 1)}>\n",
    "            {value || 0} times confetti\n",
    "        </button>\n",
    "    };\n",
    "    \"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "366d143d",
   "metadata": {},
   "source": [
    "However, the above code now has a direct link to \"https://esm.sh/canvas-confetti@1.6.0\" which makes the code very specific to esm.sh.\n",
    "\n",
    "To address this, we also support [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to \n",
    "write code more independant of where the modules come from.\n",
    "You can provide an import map using `ipyreact.define_import_map`, which takes a dictionary of module names to urls or other modules. By default we support `react` and `react-dom` which is prebundled.\n",
    "\n",
    "Apart from `react`, the default we provide is:\n",
    "\n",
    "```python\n",
    "define_import_map({\n",
    "    \"@mui/material\": \"https://esm.sh/@mui/material@5.11.10?external=react,react-dom\",\n",
    "    \"@mui/material/\": \"https://esm.sh/@mui/material@5.11.10&external=react,react-dom/\",\n",
    "    \"@mui/icons-material/\": \"https://esm.sh/@mui/icons-material/?external=react,react-dom\",\n",
    "    \"canvas-confetti\": \"https://esm.sh/canvas-confetti@1.6.0\",\n",
    "})\n",
    "\n",
    "```\n",
    "\n",
    "_Note that it is important to add `external=react,react-dom` for ReactJS based libraries, otherwise [esm.sh](https://esm.sh/#using-import-maps) would import ReactJS again_.\n",
    "\n",
    "Which means we can now write our ConfettiButton as:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9081c0cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "\n",
    "# note that this import_map is already part of the default\n",
    "ipyreact.define_import_map({\n",
    "    \"canvas-confetti\": \"https://esm.sh/canvas-confetti@1.6.0\",\n",
    "})\n",
    "\n",
    "\n",
    "ipyreact.ValueWidget(\n",
    "    _esm=\"\"\"\n",
    "    import confetti from \"canvas-confetti\";\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function({value, setValue}) {\n",
    "        return <button onClick={() => confetti() && setValue(value + 1)}>\n",
    "            {value || 0} times confetti\n",
    "        </button>\n",
    "    };\n",
    "    \"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24138653",
   "metadata": {},
   "source": [
    "## Advanced\n",
    "\n",
    " * [Bundled ES modules (ant design example)](./antd/antd.ipynb)\n",
    " * [Bundled ES modules for threejs (3D WebGL threejs-fiber example)](./threejs-fiber/threejs-fiber.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82c9fbe3-6112-4dae-b817-e1a12343b407",
   "metadata": {},
   "source": [
    "## Optional\n",
    "### Autocomplete\n",
    "\n",
    "one more thing:  \n",
    "Having **autocompletion in IDEs** is awesome!  \n",
    "traitlets don't have that by default, but adding a `signature_has_traits` decorator will do the job!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89793f7c-1398-4f11-ab75-b73ffacd9b43",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Any, Unicode, Int, observe, signature_has_traits\n",
    "\n",
    "@signature_has_traits\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    my_width = Int(23).tag(sync=True)\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ my_width }) {\n",
    "      return (\n",
    "        <button\n",
    "          style={{\n",
    "            position: \"relative\",\n",
    "            width: my_width,\n",
    "            height: 30,\n",
    "          }}\n",
    "        >\n",
    "          {\" \"}\n",
    "          Width of {my_width} px{\" \"}\n",
    "        </button>\n",
    "      );\n",
    "    }\"\"\"\n",
    "MyExampleWidget(my_width=300)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38cfce36",
   "metadata": {},
   "source": [
    "And this screenshots shows that autocompletion works now:  \n",
    "<img src=\"autocomplete_screenshot.png\" width=\"400\">"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bae77944-e0dd-49c4-bd27-b401d7bbef1b",
   "metadata": {},
   "source": [
    "Now we want to **print a message at class initialization** that says \"Button was initialized with width 300px!\"  \n",
    "That is possible with the following code pattern using calling the `super` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "124771ca-8271-4b5e-9f5d-ee792442665b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import ipyreact\n",
    "from traitlets import Int, signature_has_traits\n",
    "\n",
    "# 🪄🪄🪄 this is an advanced example, feel free to skip 🪄🪄🪄\n",
    "\n",
    "@signature_has_traits\n",
    "class MyExampleWidget(ipyreact.Widget):\n",
    "    def __init__(self, **kwargs):\n",
    "        super().__init__(**kwargs)\n",
    "        self.print_welcome_message()\n",
    "\n",
    "    def print_welcome_message(self):\n",
    "        print(f\"Button was initilized with width of {self.my_width}px \")\n",
    "\n",
    "    my_width = Int(23).tag(sync=True)\n",
    "\n",
    "    _esm = \"\"\"\n",
    "    import * as React from \"react\";\n",
    "\n",
    "    export default function MyButton({ my_width }) {\n",
    "    return (\n",
    "        <button\n",
    "        style={{\n",
    "            position: \"relative\",\n",
    "            width: my_width,\n",
    "            height: 30,\n",
    "        }}\n",
    "        >\n",
    "        {\" \"}\n",
    "        Width of {my_width} px{\" \"}\n",
    "        </button>\n",
    "    );\n",
    "    }\"\"\"\n",
    "\n",
    "MyExampleWidget(my_width=200)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}