panel-reactflow 0.4.1__tar.gz → 0.5.0b0__tar.gz

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/.github/workflows/build.yml

@@ -11,11 +11,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
+        uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
         with:
           environments: build
       - name: Build project
@@ -23,7 +23,7 @@ jobs:
       - name: Check package
         run: pixi run -e build check-wheel
       - name: Upload package
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: artifact
           path: dist/*
@@ -37,9 +37,9 @@ jobs:
       id-token: write
     environment: pypi
     steps:
-      - uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: artifact
           path: dist
       - name: Publish package on PyPi
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/.github/workflows/docs.yml

@@ -43,23 +43,23 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up Pixi
-        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
+        uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
         with:
           environments: docs
       - name: Build documentation
         run: pixi run -e docs docs-build
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()
         with:
           name: docs
           if-no-files-found: error
           path: builtdocs
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: ./builtdocs
 
@@ -71,7 +71,7 @@ jobs:
     needs: build
     steps:
       - name: Deploy dev
-        uses: peaceiris/actions-gh-pages@v4
+        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
         # Dev site built on PRs
         if: |
           (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
@@ -88,4 +88,4 @@ jobs:
           ((github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'main') ||
           (github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc'))))
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/.github/workflows/test.yml

@@ -20,10 +20,10 @@ jobs:
       code_change: ${{ steps.filter.outputs.code }}
       matrix: ${{ env.MATRIX }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         if: github.event_name != 'pull_request'
       - name: Check for code changes
-        uses: dorny/paths-filter@v3
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         id: filter
         with:
           filters: |
@@ -72,7 +72,7 @@ jobs:
     name: Pixi lock
     runs-on: ubuntu-latest
     steps:
-      - uses: holoviz-dev/holoviz_tasks/pixi_lock@v0
+      - uses: holoviz-dev/holoviz_tasks/pixi-lock@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
         with:
           cache: ${{ github.event.inputs.cache == 'true' || github.event.inputs.cache == '' }}
 
@@ -80,15 +80,15 @@ jobs:
     needs: [setup, pixi_lock]
     runs-on: "ubuntu-latest"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@v0.9.4
-      - uses: holoviz-dev/holoviz_tasks/pre-commit@v0
-      - uses: pre-commit/action@v3.0.1
+        uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
+      - uses: holoviz-dev/holoviz_tasks/pre-commit@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
         if: needs.setup.outputs.img_change == 'true'
         with:
           extra_args: -a --hook-stage manual oxipng || true --
-      - uses: stefanzweifel/git-auto-commit-action@v7
+      - uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0
         if: needs.setup.outputs.img_change == 'true'
         with:
           commit_message: "Optimize PNG images (lossless)"
@@ -111,11 +111,11 @@ jobs:
           - windows-latest
     steps:
       - name: Checkout branch
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
+        uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
         with:
           environments: ${{ matrix.environment }}
       - name: Install repository
@@ -139,7 +139,7 @@ jobs:
       PANEL_LOG_LEVEL: info
       FAIL: "--screenshot only-on-failure --full-page-screenshot --output ui_screenshots --tracing retain-on-failure"
     steps:
-      - uses: holoviz-dev/holoviz_tasks/pixi_install@v0
+      - uses: holoviz-dev/holoviz_tasks/pixi-install@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
         with:
           environments: ${{ matrix.environment }}
           install: false
@@ -151,14 +151,14 @@ jobs:
           echo "[run]\nconcurrency = greenlet" > .uicoveragerc
           pixi run -e ${{ matrix.environment }} test-ui $COV --cov-config=.uicoveragerc $FAIL
       - name: Upload UI Screenshots
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()
         with:
           name: ui_screenshots_${{ runner.os }}
           path: ./ui_screenshots
           if-no-files-found: ignore
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: panel-extensions/panel-splitjs

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: panel-reactflow
-Version: 0.4.1
+Version: 0.5.0b0
 Summary: A Panel wrapper for the Reactflow JS library.
 Project-URL: Homepage, https://github.com/panel-extensions/panel-reactflow
 Project-URL: Source, https://github.com/panel-extensions/panel-reactflow
@@ -114,6 +114,34 @@ flow
 
 For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`. `.on` callbacks receive the event payload as the first argument and can optionally accept the `ReactFlow` instance as a second argument.
 
+## Connection validation
+
+Connection checks are opt-in. For frontend-only validation, set `connection_validation` with any of `direction`, `types`, `capacity`, `duplicates`, or `cycles` set to `True`. `types` compares declared handle types case-insensitively and permits unknown types; `capacity` uses `maxConnections` on input handle dictionaries, with no limit when omitted. Existing handle connectability flags still apply.
+
+```python
+from panel_reactflow import NodeType, ReactFlow
+
+flow = ReactFlow(
+    node_types={
+        "source": NodeType(type="source", outputs=[{"id": "value", "type": "str"}]),
+        "sink": NodeType(type="sink", inputs=[{"id": "value", "type": "str", "maxConnections": 1}]),
+    },
+    connection_validation={"direction": True, "types": True, "capacity": True, "cycles": True},
+)
+```
+
+For application rules, register a Python validator. On each drag start, ReactFlow requests results for every candidate port and shows the returned reasons while dragging. The callback receives an edge-shaped payload with `source`, `target`, `sourceHandle`, and `targetHandle`; return `None` to allow or a string to reject. Hooks and frontend checks can be used together. Validate again in your `edge_added` handler before accepting the connection, since the graph may have changed after drag start.
+
+```python
+def validate_connection(edge, flow):
+    if edge["source"] == edge["target"]:
+        return "A node cannot connect to itself."
+
+flow.add_connection_validator(validate_connection)
+```
+
+Run the [connection validation demo](examples/connection_validation.py) with `PYTHONPATH=src pixi run panel serve examples/connection_validation.py --show` from the repository root.
+
 ## Development
 
 ```bash

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/README.md

@@ -71,6 +71,34 @@ flow
 
 For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`. `.on` callbacks receive the event payload as the first argument and can optionally accept the `ReactFlow` instance as a second argument.
 
+## Connection validation
+
+Connection checks are opt-in. For frontend-only validation, set `connection_validation` with any of `direction`, `types`, `capacity`, `duplicates`, or `cycles` set to `True`. `types` compares declared handle types case-insensitively and permits unknown types; `capacity` uses `maxConnections` on input handle dictionaries, with no limit when omitted. Existing handle connectability flags still apply.
+
+```python
+from panel_reactflow import NodeType, ReactFlow
+
+flow = ReactFlow(
+    node_types={
+        "source": NodeType(type="source", outputs=[{"id": "value", "type": "str"}]),
+        "sink": NodeType(type="sink", inputs=[{"id": "value", "type": "str", "maxConnections": 1}]),
+    },
+    connection_validation={"direction": True, "types": True, "capacity": True, "cycles": True},
+)
+```
+
+For application rules, register a Python validator. On each drag start, ReactFlow requests results for every candidate port and shows the returned reasons while dragging. The callback receives an edge-shaped payload with `source`, `target`, `sourceHandle`, and `targetHandle`; return `None` to allow or a string to reject. Hooks and frontend checks can be used together. Validate again in your `edge_added` handler before accepting the connection, since the graph may have changed after drag start.
+
+```python
+def validate_connection(edge, flow):
+    if edge["source"] == edge["target"]:
+        return "A node cannot connect to itself."
+
+flow.add_connection_validator(validate_connection)
+```
+
+Run the [connection validation demo](examples/connection_validation.py) with `PYTHONPATH=src pixi run panel serve examples/connection_validation.py --show` from the repository root.
+
 ## Development
 
 ```bash

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/docs/how-to/declare-types.md

@@ -244,7 +244,8 @@ validation or auto-generated forms.
 ## Handle tooltips
 
 By default, handles are plain connection points. You can add a tooltip (shown
-on hover) by passing a dict with `"id"` and `"label"` instead of a plain string:
+on hover) by passing a dict with `"id"` and `"label"` and/or `"type"` instead
+of a plain string:
 
 ```python
 from panel_reactflow import NodeType
@@ -253,19 +254,68 @@ node_types = {
     "transform": NodeType(
         type="transform",
         label="Transform",
-        inputs=[{"id": "in", "label": "Data Input"}],
+        inputs=[{"id": "in", "label": "Data Input", "type": "DataFrame"}],
         outputs=[
-            {"id": "success", "label": "Successful results"},
-            {"id": "error", "label": "Failed records"},
+            {"id": "success", "label": "Successful results", "type": "DataFrame"},
+            {"id": "error", "label": "Failed records", "type": "list"},
         ],
     ),
 }
 ```
 
-Plain strings and dicts can be mixed freely in the same list:
+The tooltip combines both when present (`"Data Input (DataFrame)"`), or falls
+back to whichever one is given. Plain strings and dicts can be mixed freely in
+the same list:
 
 ```python
-inputs=["simple_port", {"id": "documented_port", "label": "Hover to see this"}]
+inputs=["simple_port", {"id": "documented_port", "label": "Hover to see this", "type": "int"}]
+```
+
+---
+
+## Show a port's current value on click
+
+Clicking a handle emits a `"handle_clicked"` event with the node id, handle
+id, direction (`"input"`/`"output"`) and a screen position. Clicking an edge
+emits `"edge_clicked"` with the edge id and position. Use
+`ReactFlow.show_popup(content, position)` in the handler to display whatever
+you consider the "current value" for that port or connection:
+
+```python
+def on_handle_clicked(payload, flow):
+    node_id, handle_id = payload["node_id"], payload["handle_id"]
+    value = live_values.get(node_id, {}).get(handle_id)
+    flow.show_popup(pn.pane.Markdown(f"**{handle_id}**: {value!r}"), payload["position"])
+
+def on_edge_clicked(payload, flow):
+    source_id, source_port = edge_sources[payload["edge_id"]]
+    value = live_values.get(source_id, {}).get(source_port)
+    flow.show_popup(pn.pane.Markdown(f"**Value:** {value!r}"), payload["position"])
+
+flow.on("handle_clicked", on_handle_clicked)
+flow.on("edge_clicked", on_edge_clicked)
+```
+
+For `popup_trigger="hover"`, register `handle_hovered` and `edge_hovered` to
+show the popup and their corresponding `handle_unhovered` and `edge_unhovered`
+events to call `flow.close_popup()`. Match the unhovered target against the
+currently displayed one so a delayed leave event does not dismiss a newer
+popup. See the runnable example below for both pairs of callbacks.
+
+The default `popup_hover_delay` is 500 ms. After opening, an unhover event is
+emitted when the pointer moves more than 10% of the shorter canvas dimension
+from the anchor (at least 48 pixels) and is not over the popup. Click-opened
+popups dismiss on outside click; either mode can dismiss programmatically via
+`flow.close_popup()`. Use
+`popup_trigger="none"` to disable the built-in inspection events.
+`panel-reactflow` only provides the interaction events and overlay; looking up
+"the current value" for a port is application-specific.
+
+For a complete runnable graph with typed port hover tooltips and popups for
+both handles and edges, run:
+
+```bash
+panel serve examples/port_value_inspection.py --show
 ```
 
 ---

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/docs/how-to/define-nodes-edges.md

@@ -358,26 +358,45 @@ Without `sourceHandle` and `targetHandle`, edges connect to the default (first)
 
 ---
 
-## Update data vs. label
+## Update data vs. presentation
 
-`data` and `label` live in different places and are updated differently:
-
-- **Data** — use `patch_node_data()` or `patch_edge_data()`.  This sends
-  an incremental patch to the frontend without replacing the full list.
-- **Label** — replace the node/edge in `flow.nodes` or `flow.edges`.
+A node or edge has an arbitrary `data` dictionary plus a set of top-level React
+Flow fields (`label`, `style`, `type`, `className`, `position`, ...).  Each has
+its own patch method, and both send an incremental update to the frontend
+instead of replacing the full list:
 
 ```python
 # Patch a data field
 flow.patch_node_data("n1", {"status": "running"})
 flow.patch_edge_data("e1", {"weight": 0.75})
 
-# Update a label
-flow.nodes = [
-    {**node, "label": "Start (running)"} if node["id"] == "n1" else node
-    for node in flow.nodes
-]
+# Patch a top-level field
+flow.patch_node_props("n1", {"label": "Start (running)", "className": "busy"})
+flow.patch_edge_props("e1", {"style": {"stroke": "#ef4444", "strokeWidth": 4}, "type": "step"})
+```
+
+Passing `None` to `patch_node_props()`/`patch_edge_props()` clears the field so
+the element falls back to the CSS/theme default:
+
+```python
+flow.patch_edge_props("e1", {"style": None})
 ```
 
+If you use `Node`/`Edge` subclasses, you rarely need either method: assigning to
+a parameter patches the browser in place.  Parameters you declare on the
+subclass are synced into `data`, the presentational base parameters are synced
+as top-level fields.
+
+```python
+node.label = "Start (running)"                  # top-level label
+edge.style = {"stroke": "#ef4444"}              # top-level style
+edge.weight = 0.75                              # subclass param, goes into data
+```
+
+`position` and `selected` are the exception: the browser owns them while the
+user drags or selects, so assignment does not push them.  Use
+`patch_node_props()` to move or select a node from Python.
+
 ---
 
 ## Add and remove at runtime
@@ -399,3 +418,26 @@ flow.add_edge(EdgeSpec(id="e2", source="n3", target="n4"))
 flow.remove_node("n3")   # also removes connected edges
 flow.remove_edge("e1")
 ```
+
+`remove_node()` and `remove_edge()` also take several ids at once, either as
+separate arguments or as a single sequence. Pass them together rather than
+calling the methods in a loop: a batch assigns `nodes` and `edges` once, so the
+browser renders a single update instead of one per element.
+
+```python
+flow.remove_node("n1", "n2", "n3")   # also removes connected edges
+flow.remove_edge(["e1", "e2"])
+```
+
+More generally, every parameter assignment is synced to the browser on its own
+and the canvas re-renders per sync, so a sequence of updates renders each
+intermediate graph. Wrap any batch of changes in `pn.io.hold()` to combine them
+into a single render:
+
+```python
+import panel as pn
+
+with pn.io.hold():
+    flow.nodes = new_nodes
+    flow.edges = new_edges
+```

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/docs/how-to/react-to-events.md

@@ -30,6 +30,7 @@ the `ReactFlow` instance as a second argument.  You can also listen for
 | `edge_data_changed`  | Edge data is patched (via API, editor patch, or parameter-driven sync). | `edge_id`, `patch` |
 | `selection_changed`  | The active selection changes. | `nodes`, `edges` |
 | `sync`               | A batch sync from the frontend. | *(varies)* |
+| `client_error`       | The graph view hit a rendering error in the browser. See [Recover from Rendering Errors](recover-from-errors.md). | `source`, `message`, `stack`, `component_stack`, `attempt`, `mode` |
 
 ---
 

panel_reactflow-0.5.0b0/docs/how-to/recover-from-errors.md

@@ -0,0 +1,121 @@
+# Recover from Rendering Errors
+
+A React rendering error is unforgiving: when a component throws during
+render, React unmounts the whole subtree.  In a graph editor that means a
+single malformed node can blank the canvas, and because the exception dies
+in the browser console the server never learns about it.  The user is left
+staring at an empty viewport with no way back other than reloading the page,
+even though their graph is still safely held in Python.
+
+Panel-ReactFlow wraps the canvas in an error boundary that catches those
+errors, tries to bring the view back, and reports what happened to the
+server.  This is on by default, controlled by the `error_recovery`
+parameter.
+
+```python
+from panel_reactflow import ReactFlow
+
+flow = ReactFlow(nodes=nodes, edges=edges, error_recovery="auto")
+```
+
+---
+
+## Recovery modes
+
+| Mode       | Behavior |
+|------------|----------|
+| `"auto"`   | *(default)* Remount the canvas once, then remount again in safe mode.  If it still fails, show the recovery panel. |
+| `"manual"` | Report the error and show the recovery panel immediately, without retrying. |
+| `"off"`    | Disable the error boundary entirely so exceptions propagate to the browser.  Useful when debugging a custom node component. |
+
+Each retry budget refills once a remounted canvas has survived for five
+seconds, so a graph that breaks again much later still gets a fresh set of
+attempts rather than going straight to the failure panel.
+
+---
+
+## What safe mode does
+
+On the second attempt the frontend validates the graph before handing it to
+React Flow and either repairs or hides anything it cannot render:
+
+| Issue | Action |
+|-------|--------|
+| `invalid_position` | Position is missing or not finite, so the node is placed at the origin. |
+| `unknown_node_type` | Node type is not registered, so the node falls back to the default renderer. |
+| `unknown_edge_type` | Edge type is not registered, so the type is stripped. |
+| `dangling_edge` | Edge references a node that does not exist, so it is hidden. |
+| `duplicate_node_id` / `duplicate_edge_id` | Later duplicates are hidden. |
+| `missing_node_id` / `missing_edge_id` / `invalid_node` / `invalid_edge` | The element is hidden. |
+
+Safe mode is **view-only**.  It filters what the browser renders and never
+sends a graph mutation back to Python, so `flow.nodes` and `flow.edges` keep
+every element they had before the error.  Once the underlying state is
+repaired on the server, the affected elements reappear.
+
+A banner tells the user what was changed and offers a details list of the
+individual issues:
+
+```text
+Safe mode: repaired 1 element and hid 1 element that could not be rendered.
+Nothing was deleted on the server.
+```
+
+---
+
+## The recovery panel
+
+When retries are exhausted, or in `"manual"` mode, the canvas is replaced by
+a panel that names the error and offers three actions: *Try again*, which
+remounts the canvas, *Reload page*, which rebuilds the session from the
+server-side state, and *Copy details*, which puts a JSON diagnostic blob on
+the clipboard for a bug report.
+
+Because Python holds the canonical graph, reloading is genuinely safe: no
+work is lost.  The panel says so explicitly, which matters when the
+alternative is a user assuming their graph is gone.
+
+---
+
+## Log and handle errors in Python
+
+Every error the frontend catches is reported to the server, logged to the
+`panel.reactflow` logger, and emitted as a `client_error` event.
+
+```python
+import logging
+
+logging.getLogger("panel.reactflow").setLevel(logging.INFO)
+
+def on_client_error(payload, flow):
+    if payload["source"] == "safe_mode":
+        print("hidden or repaired:", payload["issues"])
+    else:
+        print(f"render error on attempt {payload['attempt']}: {payload['message']}")
+
+flow.on("client_error", on_client_error)
+```
+
+Render errors carry `name`, `message`, `stack`, `component_stack`, `attempt`,
+`mode` and `auto_retry`.  Errors raised inside interaction handlers are
+reported with `source="handler"` and the `handler` name, which catches the
+case where a drag or connect silently fails and leaves the canvas showing a
+change that never reached Python.  Safe mode reports arrive with
+`source="safe_mode"` and the list of `issues`.
+
+Use this hook to forward errors to your own telemetry, to snapshot the graph
+for later inspection, or to attempt a server-side repair before the user
+clicks *Try again*.
+
+---
+
+## Tips
+
+- Keep `error_recovery="auto"` in production; switch to `"off"` while
+  developing a custom node component so you see the real stack trace.
+- A `client_error` with `source="safe_mode"` is a strong signal that
+  something upstream produced invalid state.  Treat it as a bug report
+  rather than a warning to be ignored.
+- The error boundary only covers the graph canvas.  Content you pass to
+  `top_panel`, `bottom_panel`, `left_panel` and `right_panel` stays mounted
+  when the canvas fails, so side panels remain usable during recovery.

panel_reactflow-0.5.0b0/docs/how-to/validate-connections.md

@@ -0,0 +1,82 @@
+# Validate Connections
+
+Use `connection_validation` to reject invalid connections as users drag between handles. The policies run in the browser; a Python validator can add application-specific rules. Both are opt-in and can be used together.
+
+## Configure browser policies
+
+Set only the checks your graph needs:
+
+| Policy | Rejects |
+|--------|---------|
+| `direction` | Connections that do not run from a declared output to a declared input. Users can still start a drag at either end. |
+| `types` | Connections between handles with different declared `type` values (case-insensitive). If either type is missing, the connection is allowed. |
+| `capacity` | Connections to an input handle that has reached its positive integer `maxConnections` limit. Inputs without a limit are unrestricted. |
+| `duplicates` | A second edge with the same source, target, source handle, and target handle. Different handle pairs can still connect the same nodes. |
+| `cycles` | Connections that would create a cycle, including a self-connection. |
+
+Policies default to off. Existing `NodeType` connectable flags still control whether a handle can start or receive a drag; see [Control Handle Connectivity](control-handle-connectivity.md).
+
+The following app uses handle types and capacity limits alongside a Python rule. Save it as `validation_app.py` and run `panel serve validation_app.py --show`:
+
+```python
+import panel as pn
+
+from panel_reactflow import NodeSpec, NodeType, ReactFlow
+
+pn.extension("jsoneditor")
+
+flow = ReactFlow(
+    nodes=[
+        NodeSpec(id="source", type="source", label="Source", position={"x": 0, "y": 0}),
+        NodeSpec(id="transform", type="transform", label="Transform", position={"x": 260, "y": 0}),
+        NodeSpec(id="publish", type="publish", label="Publish", position={"x": 520, "y": 0}),
+    ],
+    node_types={
+        "source": NodeType(type="source", outputs=[{"id": "text", "type": "Text"}]),
+        "transform": NodeType(
+            type="transform",
+            inputs=[{"id": "text", "type": "text", "maxConnections": 1}],
+            outputs=[{"id": "cleaned", "type": "Text"}],
+        ),
+        "publish": NodeType(type="publish", inputs=[{"id": "text", "type": "Text", "maxConnections": 1}]),
+    },
+    connection_validation={
+        "direction": True,
+        "types": True,
+        "capacity": True,
+        "duplicates": True,
+        "cycles": True,
+    },
+    height=350,
+    width=800,
+)
+
+
+def validate_connection(edge, flow):
+    if edge["source"] == "source" and edge["target"] == "publish":
+        return "Publish requires the Transform output."
+    return None
+
+
+flow.add_connection_validator(validate_connection)
+
+
+def on_edge_added(event, flow):
+    edge = event["edge"]
+    if validate_connection(edge, flow):
+        flow.remove_edge(edge["id"])
+
+
+flow.on("edge_added", on_edge_added)
+flow.servable()
+```
+
+Drag from **Source.text** to **Transform.text**, then from **Transform.cleaned** to **Publish.text**. A direct connection from Source to Publish is rejected by Python. Try connecting Source.text to Transform.cleaned (two outputs) to see the direction check, or connect an output to an already occupied input to see the capacity check.
+
+## Add application rules
+
+Register callbacks with `flow.add_connection_validator(callback)` and unregister them with `flow.remove_connection_validator(callback)`. Each callback accepts either `edge` or `(edge, flow)` and returns `None` to allow the connection or a reason string to reject it. The payload has `source`, `target`, `sourceHandle`, and `targetHandle` keys; handles without an explicit ID use `None`.
+
+When a user starts dragging from an output or input, Python checks every candidate handle on the opposite side. Validators run in registration order until one rejects a candidate. Browser policies and Python reasons are shown on handles while dragging; the browser prevents a rejected connection. Python results must arrive before the connection is dropped: pending requests and requests taking longer than three seconds block the connection. Exceptions also reject the candidate and are logged on the server. Keep validators fast.
+
+Validation is for interactive drags, not a constraint on `flow.edges` or `flow.add_edge()`. Python validators run at drag start, not when the edge is added. If the rule depends on graph state that may change during the drag, check it again in an `edge_added` handler before keeping or persisting the edge. The example above removes an edge if its application rule no longer holds.

{panel_reactflow-0.4.1 → panel_reactflow-0.5.0b0}/docs/index.md

@@ -62,6 +62,7 @@ flow.servable()
 - [Define Nodes & Edges](how-to/define-nodes-edges.md)
 - [Declare Node & Edge Types](how-to/declare-types.md)
 - [Control Handle Connectivity](how-to/control-handle-connectivity.md) — restrict connections
+- [Validate Connections](how-to/validate-connections.md) — check types, capacity, cycles, and application rules
 - [Define Editors](how-to/define-editors.md) — node *and* edge editors
 - [Embed Views in Nodes](how-to/embed-views-in-nodes.md)
 - [Style Nodes & Edges](how-to/style-nodes-edges.md)