Allow building ESM based components

.gitignore

@@ -161,3 +161,5 @@ app_streamlit.py
 pixi.lock
 panel/_version.py
 .uicoveragerc
+mario_button.*
+counter_button.*

doc/conf.py

@@ -117,12 +117,14 @@
  'galleries': {
  'reference': {
  'title': 'Component Gallery',
+ 'extensions': ['*.ipynb', '*.py', '*.md'],
  'sections': [
  'panes',
  'widgets',
  'layouts',
  # 3 most important by expected usage. Rest alphabetically
  'chat',
+ 'custom_components',
  'global',
  'indicators',
  'templates',

doc/how_to/custom_components/esm/callbacks.md

@@ -0,0 +1,72 @@
+# ESM component with callback
+
+In this guide we will show you how to add callbacks to your ESM components.
+
+## Slideshow with Python callback
+
+This example shows you how to create a `SlideShow` component that uses a Python *callback* function to update the `Slideshow` image when its clicked:
+
+```{pyodide}
+import param
+import panel as pn
+
+from panel.custom import JSComponent
+
+pn.extension()
+
+class Slideshow(JSComponent):
+
+ index = param.Integer(default=0)
+
+ _esm = """
+ export function render({ model }) {
+ const img = document.createElement('img')
+ img.src = `https://picsum.photos/800/300?image=${model.index}`
+ img.addEventListener('click', (event) => model.send_event('click', event))
+ model.on('index', () => {
+ img.src = `https://picsum.photos/800/300?image=${model.index}`
+ })
+ return img
+ }
+ """
+
+ def _handle_click(self, event):
+ self.index += 1
+
+Slideshow(width=500, height=200).servable()
+```
+
+This approach lets you quickly build custom components with complex interactivity. However if you do not need any complex computations in Python you can also construct a pure JS equivalent:
+
+## Slideshow with Javascript Callback
+
+This example shows you how to create a `Slideshow` component that uses a Javascript *callback* function to update the `Slideshow` image when its clicked:
+
+```{pyodide}
+import param
+import panel as pn
+
+from panel.custom import JSComponent
+
+pn.extension()
+
+class JSSlideshow(JSComponent):
+
+ index = param.Integer(default=0)
+
+ _esm = """
+ export function render({ model }) {
+ const img = document.createElement('img')
+ img.src = `https://picsum.photos/800/300?image=${model.index}`
+ img.addEventListener('click', (event) => { model.index += 1 })
+ model.on('index', () => {
+ img.src = `https://picsum.photos/800/300?image=${model.index}`
+ })
+ return img
+ }
+ """
+
+JSSlideshow(width=800, height=300).servable()
+```
+
+By using Javascript callbacks instead of Python callbacks you can achieve higher performance, components that can be *js linked* and components that will also work when your app is saved to static html.