Merge pull request #139 from ahuang11/panel-holoviews-interaction

Create panel-holoviews-interactions resource

Author: MarcSkovMadsen

src/holoviz_mcp/config/resources/skills/panel-holoviews-interactions.md

@@ -0,0 +1,255 @@
+---
+name: panel-holoviews-interactions
+description: Best practices for using HoloViews/hvPlot with Panel, especially DynamicMap patterns for live-updating dashboards.
+metadata:
+  version: "1.0.0"
+  author: ahuang11
+  category: web-development
+  difficulty: intermediate
+---
+
+# Panel + HoloViews Interaction Patterns
+
+## Core Principle: Don't Replace DOM — Update In Place
+
+Panel re-renders the entire DOM subtree when a `@param.depends` method returns a new component. This causes flicker, resets scroll position, and destroys client-side state (zoom, selection, hover).
+
+### DON'T: Return new panes from `@param.depends`
+
+```python
+# BAD — creates new pane/layout objects every time data changes → DOM replacement, flicker
+@param.depends("data")
+def my_chart(self):
+    return pn.pane.HoloViews(self.data.hvplot.scatter(...))
+
+@param.depends("data")
+def my_table(self):
+    return pn.widgets.Tabulator(self.data)
+```
+
+### DO: Create panes once, pass reactive method references as content
+
+The preferred Panel pattern: create panes in `__init__`, pass `@param.depends` methods as content references. The pane calls the method reactively and updates its own content — no DOM replacement.
+
+```python
+def __init__(self, **params):
+    super().__init__(**params)
+    # Pane created ONCE; method reference passed as content
+    self._summary_pane = pn.pane.Markdown(self._summary_text)
+    self._chart_pane = pn.pane.HoloViews()
+
+@param.depends("data")
+def _summary_text(self):
+    self._summary_pane.object = f"**Rows**: {len(self.data)}"
+
+@param.depends("data", watch=True, on_init=True)
+def _update_chart(self):
+    self._chart_pane.object = self.data.hvplot.scatter(...)
+```
+
+### DO: Use `param.depends` when orchestrating multiple component updates from one event
+
+When a single data change needs to update many components at once (status HTML, chart trigger, table value, visibility flags), a single watcher is cleaner than having each component independently depend on the same param:
+
+```python
+def __init__(self, **params):
+    super().__init__(**params)
+    self._table = pn.widgets.Tabulator(pd.DataFrame(), ...)
+    self._status_html = pn.pane.HTML("", sizing_mode="stretch_width")
+
+@param.depends("data", watch=True)
+def _on_data_changed(self, *events):
+    self._status_html.object = self._render_status(self.data)
+    self._table.value = self._prepare_df(self.data)
+    self._chart_trigger += 1
+    self._chart_section.visible = not self.data.empty
+```
+
+**When to use which**:
+- `@param.depends("x")` (no watch) → return content, pass method ref to a pane. Preferred for simple 1-param → 1-pane reactivity.
+- `@param.depends("x", watch=True)` → update state parameters or trigger side effects.
+
+---
+
+## DynamicMap: Preserve Zoom/Pan Across Data Refreshes
+
+When you set `pane.object = new_plot`, Bokeh resets all axes ranges. Wrap the plot function in `hv.DynamicMap` so Bokeh updates data in the existing figure rather than replacing it.
+
+### DON'T: Replace chart object directly
+
+```python
+# BAD — zoom resets every refresh
+self._chart_pane.object = df.hvplot.scatter(...)
+```
+
+### DO: Use DynamicMap with a trigger parameter
+
+```python
+class Monitor(pn.viewable.Viewer):
+    _chart_trigger = param.Integer(default=0)
+
+    def __init__(self, **params):
+        super().__init__(**params)
+        dmap = hv.DynamicMap(pn.bind(self._render_scatter, self.param._chart_trigger))
+        self._chart_pane = pn.pane.HoloViews(dmap, sizing_mode="stretch_width")
+
+    def _render_scatter(self, trigger):
+        # Reads self.data directly; trigger is just a signal to re-invoke
+        df = self.data
+        if df is None or df.empty:
+            return hv.Scatter([], kdims=['x'], vdims=['y'])
+        return df.hvplot.scatter(x='x', y='y', ...)
+
+    def _on_data_changed(self, *events):
+        # Increment trigger → DynamicMap re-invokes → Bokeh patches in place
+        self._chart_trigger += 1
+```
+
+---
+
+## One Element Per DynamicMap
+
+Returning an `hv.Overlay` from a DynamicMap causes two problems:
+
+1. **Type mismatch errors** — if you sometimes return `hv.Scatter` and sometimes `hv.Overlay`, DynamicMap raises `AssertionError: DynamicMap must only contain one type of object`.
+2. **Lost hover tooltips** — when scatter + HLines are combined inside `hv.Overlay([...])`, the scatter's hover tool configuration doesn't propagate.
+
+### DON'T: Return mixed types or Overlays from a single DynamicMap
+
+```python
+# BAD — type mismatch when data is empty vs populated
+def render(trigger):
+    if no_data:
+        return hv.Text(0, 0, "empty")  # Text type
+    plot = df.hvplot.scatter(...)
+    return plot * hv.HLine(avg)  # Overlay type → AssertionError
+
+# BAD — hover tooltips lost
+def render(trigger):
+    scatter = df.hvplot.scatter(..., tools=['hover'])
+    return hv.Overlay([scatter, hv.HLine(avg)])  # hover doesn't propagate
+```
+
+### DO: Separate DynamicMap per element, combine with `*` at layout level
+
+```python
+def __init__(self, **params):
+    super().__init__(**params)
+    scatter_dmap = hv.DynamicMap(pn.bind(self._render_scatter, self.param._trigger))
+    avg_dmap = hv.DynamicMap(pn.bind(self._render_avg_line, self.param._trigger))
+    min_dmap = hv.DynamicMap(pn.bind(self._render_min_line, self.param._trigger))
+    max_dmap = hv.DynamicMap(pn.bind(self._render_max_line, self.param._trigger))
+    overlay = scatter_dmap * avg_dmap * min_dmap * max_dmap
+    self._chart_pane = pn.pane.HoloViews(overlay, sizing_mode="stretch_width")
+```
+
+Each callback returns exactly **one element type**, always:
+
+```python
+def _render_scatter(self, trigger):
+    completed = self._get_completed()
+    if completed.empty:
+        # Same type as the populated case — just no data
+        return hv.Scatter([], kdims=['START_TIME'], vdims=['RUNTIME_SECONDS']).opts(
+            bgcolor='#0d1015', height=180, responsive=True,
+        )
+    return completed.hvplot.scatter(x='START_TIME', y='RUNTIME_SECONDS', ...)
+
+def _render_avg_line(self, trigger):
+    avg = self._stats().get('avg_runtime', 0)
+    if avg > 0:
+        return hv.HLine(avg).opts(color='amber', line_dash='dashed', ...)
+    # Invisible but valid — same type always
+    return hv.HLine(0).opts(alpha=0)
+```
+
+Benefits:
+- Each DynamicMap always returns the same HoloViews element type (no `AssertionError`)
+- Scatter keeps its hover tools natively (tools are per-element, not per-overlay)
+- Each layer updates independently
+- Static layers (like a tile source) can be pulled out of DynamicMap entirely
+
+---
+
+## Client-Side Interactions with `jslink`
+
+For styling/visual controls that don't need Python computation, use `jslink` to wire Panel widgets directly to Bokeh properties. No server roundtrip, works in saved HTML files.
+
+### Simple property binding
+
+```python
+# Float slider → glyph fill alpha (also works for size, line_width, fill_color, etc.)
+widget = pn.widgets.FloatSlider(value=1, step=0.01)
+plot = hv.Points((x, y)).opts(size=10)
+widget.jslink(plot, value='glyph.fill_alpha')
+
+# Text input → plot title
+widget = pn.widgets.TextInput(value="Title")
+plot = hv.Curve((x, y)).opts(title="Title")
+widget.jslink(plot, value="plot.title.text")
+
+# Text input → axis label
+widget = pn.widgets.TextInput(value="X Label")
+plot = hv.Curve((x, y)).opts(xlabel="X Label")
+widget.jslink(plot, value="xaxis.axis_label")
+
+# RadioButtonGroup → title alignment
+widget = pn.widgets.RadioButtonGroup(options=["left", "center", "right"])
+widget.jslink(plot, value="plot.title.align")
+```
+
+### JavaScript code callbacks
+
+For transforms that need a bit of JS logic, use the `code` parameter:
+
+```python
+# Range slider → axis limits
+widget = pn.widgets.RangeSlider(start=0, end=10)
+plot = hv.Curve((x, y))
+widget.jslink(plot, code={'value': """
+    x_range.start = cb_obj.value[0];
+    x_range.end = cb_obj.value[1];
+"""})
+
+# Range slider → colorbar limits
+widget.jslink(plot, code={'value': """
+    color_mapper.low = cb_obj.value[0];
+    color_mapper.high = cb_obj.value[1];
+"""})
+
+# Float slider → modify data directly
+widget.jslink(plot, code={'value': """
+    var y = cds.data['y'];
+    for (var i = 0; i < y.length; i++) { y[i] = cb_obj.value; }
+    cds.change.emit();
+"""})
+
+# Select → colormap with extra args
+cmaps_colors = {name: hv.plotting.util.process_cmap(cmap, n) for ...}
+widget.jslink(plot, code={'value': "color_mapper.palette = cmap_dict[source.value];"}, 
+              args={"cmap_dict": cmaps_colors})
+```
+
+**Bokeh property targets available via jslink**:
+- `glyph.*` — fill_alpha, fill_color, size, line_width, line_color, etc.
+- `plot.title.*` — text, text_font_size, align
+- `xaxis.*` / `yaxis.*` — axis_label, etc.
+- `x_range.*` / `y_range.*` — start, end
+- `color_mapper.*` — low, high, palette
+- `cds.*` — column data source for direct data manipulation
+
+**When to use jslink vs DynamicMap**:
+- `jslink` — pure visual/styling changes, axis limits, color tweaks. No Python needed.
+- `DynamicMap` — data transformations, aggregations, anything that needs Python computation.
+
+---
+
+## Summary Checklist
+
+| Pattern | Do | Don't |
+|---|---|---|
+| Update UI | Pass `@param.depends` method ref to pane; or `pn.bind` for multi-component orchestration | Return new panes/layouts from `@param.depends` |
+| Preserve zoom | `hv.DynamicMap(pn.bind(fn, trigger))` | `pane.object = new_plot` |
+| Overlay composition | One DynamicMap per element, `*` at layout | `hv.Overlay([...])` inside callback |
+| Empty chart state | `hv.Scatter([], kdims=..., vdims=...)` | `hv.Overlay([])` or `hv.Text(...)` |
+| Side effects | `pn.bind(fn, obj.param.value)` | `@param.depends` with `watch=True` for UI |