panel-reactflow 0.3.1a0__tar.gz → 0.4.0b1__tar.gz

{panel_reactflow-0.3.1a0 → panel_reactflow-0.4.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.3.1a0
+Version: 0.4.0b1
 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

panel_reactflow-0.4.0b1/docs/how-to/context-menu.md

@@ -0,0 +1,105 @@
+# Node Context Menus
+
+Panel-ReactFlow supports per-node context menus that appear on right-click.
+Define the menu content by overriding the `context_menu()` method on a `Node`
+subclass. The method returns any Panel component, which is rendered as a
+floating overlay at the click position.
+
+---
+
+## Define a context menu
+
+Override `context_menu()` on your `Node` subclass to return a Panel component.
+The menu is dismissed automatically when the user clicks elsewhere on the
+canvas.
+
+```python
+import panel as pn
+import panel_material_ui as pmui
+from panel_reactflow import Node, ReactFlow
+
+
+class TaskNode(Node):
+    def context_menu(self):
+        return pn.Column(
+            pmui.Button(name="Run", variant="text", size="small"),
+            pmui.Button(name="Delete", variant="text", color="error", size="small"),
+        )
+
+
+flow = ReactFlow(nodes=[
+    TaskNode(id="t1", position={"x": 0, "y": 0}, label="My Task", data={}),
+])
+```
+
+---
+
+## Access node state in the menu
+
+The `context_menu()` method runs on the node instance, so you have access to
+all its parameters and the parent flow via `self.flow`.
+
+```python
+class PipelineNode(Node):
+    status = param.Selector(
+        default="idle", objects=["idle", "running", "done"], precedence=0
+    )
+
+    def context_menu(self):
+        def set_status(status):
+            self.flow.patch_node_data(self.id, {"status": status})
+            # Close the menu after action
+            self.flow._handle_msg({"type": "close_context_menu"})
+
+        return pn.Column(
+            pn.pane.Markdown(f"**{self.label}** ({self.status})"),
+            pmui.Button(
+                name="Start", variant="text", size="small",
+                on_click=lambda e: set_status("running"),
+            ),
+            pmui.Button(
+                name="Delete", variant="text", color="error", size="small",
+                on_click=lambda e: self.flow.remove_node(self.id),
+            ),
+        )
+```
+
+---
+
+## Close the menu programmatically
+
+The context menu closes when the user clicks anywhere on the canvas pane.
+To close it from a button callback (e.g. after performing an action), send
+the close message:
+
+```python
+self.flow._handle_msg({"type": "close_context_menu"})
+```
+
+---
+
+## Listen for context menu events
+
+You can also react to the right-click event without rendering a menu by
+subscribing to the `"node_context_menu"` event:
+
+```python
+def on_context(payload, flow):
+    print(f"Right-clicked node {payload['node_id']} at {payload['position']}")
+
+flow.on("node_context_menu", on_context)
+```
+
+The payload includes `node_id` and `position` (with `x` and `y` screen
+coordinates).
+
+---
+
+## Tips
+
+- Return `None` from `context_menu()` to disable the menu for specific nodes
+  (this is the default behavior).
+- Only `Node` subclass instances support context menus. Dict-based nodes do
+  not trigger a context menu on right-click.
+- The menu overlay uses the `.rf-context-menu` CSS class for styling. Override
+  it in a custom stylesheet to change appearance.

panel_reactflow-0.4.0b1/docs/how-to/control-handle-connectivity.md

@@ -0,0 +1,336 @@
+# Control Handle Connectivity
+
+Restrict which connections users can create by configuring the connectable
+flags on `NodeType`. This lets you enforce directional flow (sources, sinks,
+transforms) and prevent invalid edges at the UI level.
+
+![Screenshot: connectable handles demo](../assets/screenshots/connectable-handles.png)
+
+---
+
+## Problem
+
+By default, all handles are fully connectable — users can drag edges from or
+to any handle on any node. But many graph types have directional semantics:
+
+- **Data sources** should only output data, never accept input
+- **Data sinks** should only accept input, never produce output
+- **Monitor nodes** might accept input but only emit status (one direction)
+- **Read-only nodes** might display data without allowing any new connections
+
+Without restrictions, users can create semantically invalid edges that break
+your application's logic.
+
+---
+
+## Solution
+
+Use the six `*_connectable*` flags on `NodeType` to control which drag
+operations are allowed for input and output handles.
+
+### Available flags
+
+| Flag | Default | Controls |
+|------|---------|----------|
+| `input_connectable` | `True` | Whether input handles are connectable at all |
+| `input_connectable_start` | `True` | Whether edges can **start from** input handles |
+| `input_connectable_end` | `True` | Whether edges can **end at** input handles |
+| `output_connectable` | `True` | Whether output handles are connectable at all |
+| `output_connectable_start` | `True` | Whether edges can **start from** output handles |
+| `output_connectable_end` | `True` | Whether edges can **end at** output handles |
+
+---
+
+## Common patterns
+
+### Data source (output only)
+
+Produces data but cannot accept incoming connections:
+
+```python
+from panel_reactflow import NodeType
+
+source = NodeType(
+    type="source",
+    label="Data Source",
+    outputs=["data"],
+    output_connectable_start=True,   # Can drag FROM output
+    output_connectable_end=False,    # Cannot drag TO output
+)
+```
+
+**Valid**: Drag from source output → another node's input ✓
+**Invalid**: Drag from another node → source output ✗
+
+### Data sink (input only)
+
+Consumes data but cannot produce outgoing connections:
+
+```python
+sink = NodeType(
+    type="sink",
+    label="Data Sink",
+    inputs=["data"],
+    input_connectable_start=False,   # Cannot drag FROM input
+    input_connectable_end=True,      # Can drag TO input
+)
+```
+
+**Valid**: Drag from another node's output → sink input ✓
+**Invalid**: Drag from sink input → another node ✗
+
+### Transform (bidirectional)
+
+Full connectivity in both directions (default):
+
+```python
+transform = NodeType(
+    type="transform",
+    label="Transform",
+    inputs=["in"],
+    outputs=["out"],
+    # All flags default to True — no need to specify
+)
+```
+
+**Valid**: Any drag operation ✓
+
+### Monitor node
+
+Accepts input and emits status, but status cannot receive incoming edges:
+
+```python
+monitor = NodeType(
+    type="monitor",
+    label="Monitor",
+    inputs=["in"],
+    outputs=["status"],
+    input_connectable_start=False,   # Cannot start edges from input
+    output_connectable_end=False,    # Cannot end edges at output
+)
+```
+
+**Valid**: Drag from another node → monitor input ✓
+**Valid**: Drag from monitor output → another node ✓
+**Invalid**: Drag from monitor input → another node ✗
+**Invalid**: Drag from another node → monitor output ✗
+
+### Read-only node
+
+Displays data but allows no new connections:
+
+```python
+readonly = NodeType(
+    type="readonly",
+    label="Read Only",
+    inputs=["in"],
+    outputs=["out"],
+    input_connectable=False,
+    output_connectable=False,
+)
+```
+
+**Invalid**: Any drag operation ✗
+
+---
+
+## Complete working example
+
+This example builds a data pipeline with sources, transforms, and sinks:
+
+```python
+import panel as pn
+from panel_reactflow import NodeType, NodeSpec, EdgeSpec, ReactFlow
+
+pn.extension("jsoneditor")
+
+# Define node types
+node_types = {
+    "source": NodeType(
+        type="source",
+        label="Data Source",
+        outputs=["data"],
+        output_connectable_start=True,
+        output_connectable_end=False,
+    ),
+    "transform": NodeType(
+        type="transform",
+        label="Transform",
+        inputs=["in"],
+        outputs=["out"],
+    ),
+    "monitor": NodeType(
+        type="monitor",
+        label="Monitor",
+        inputs=["in"],
+        outputs=["status"],
+        input_connectable_start=False,
+        output_connectable_end=False,
+    ),
+    "sink": NodeType(
+        type="sink",
+        label="Data Sink",
+        inputs=["data"],
+        input_connectable_start=False,
+        input_connectable_end=True,
+    ),
+}
+
+# Build pipeline
+flow = ReactFlow(
+    nodes=[
+        NodeSpec(id="source1", type="source", position={"x": 100, "y": 150}, data={}).to_dict(),
+        NodeSpec(id="transform1", type="transform", position={"x": 350, "y": 150}, data={}).to_dict(),
+        NodeSpec(id="monitor1", type="monitor", position={"x": 600, "y": 150}, data={}).to_dict(),
+        NodeSpec(id="sink1", type="sink", position={"x": 850, "y": 150}, data={}).to_dict(),
+    ],
+    edges=[
+        EdgeSpec(id="e1", source="source1", target="transform1", sourceHandle="data", targetHandle="in").to_dict(),
+        EdgeSpec(id="e2", source="transform1", target="monitor1", sourceHandle="out", targetHandle="in").to_dict(),
+        EdgeSpec(id="e3", source="monitor1", target="sink1", sourceHandle="status", targetHandle="data").to_dict(),
+    ],
+    node_types=node_types,
+    width=1200,
+    height=400,
+)
+
+flow.servable()
+```
+
+### Try these interactions
+
+1. **Valid**: Drag from source output → transform input ✓
+2. **Valid**: Drag from transform output → monitor input ✓
+3. **Valid**: Drag from monitor output → sink input ✓
+4. **Invalid**: Try to drag TO source output ✗ (blocked)
+5. **Invalid**: Try to drag FROM sink input ✗ (blocked)
+6. **Invalid**: Try to drag TO monitor output ✗ (blocked)
+
+The UI automatically prevents invalid connections — handles show different
+cursor behavior and won't accept or initiate drag operations when restricted.
+
+---
+
+## Multiple handles per side
+
+Connectable flags apply to **all handles on a given side** (input or output).
+If a node has multiple input handles, `input_connectable_start=False` affects
+all of them:
+
+```python
+multi_input = NodeType(
+    type="multi",
+    label="Multi-Input",
+    inputs=["in1", "in2", "in3"],  # Three input handles
+    outputs=["out"],
+    input_connectable_start=False,  # Applies to all input handles
+)
+```
+
+All three input handles will respect the same connectivity rules.
+
+---
+
+## Programmatic edges vs UI restrictions
+
+Connectable flags only affect **user drag interactions** in the UI. You can
+still create edges programmatically regardless of the flags:
+
+```python
+# This edge will be created even if handles are non-connectable
+flow.add_edge(EdgeSpec(id="e1", source="source1", target="sink1"))
+```
+
+Or by passing edges directly to `ReactFlow`:
+
+```python
+edges = [
+    EdgeSpec(id="e1", source="source1", target="sink1").to_dict()
+]
+flow = ReactFlow(nodes=nodes, edges=edges, node_types=node_types)
+```
+
+The flags control what users can do via drag-and-drop, not what your code
+can create.
+
+---
+
+## Flag independence
+
+Each flag is independent. Setting one doesn't affect others:
+
+```python
+# Only restrict starting edges from inputs
+node = NodeType(
+    type="restricted",
+    inputs=["in"],
+    outputs=["out"],
+    input_connectable_start=False,  # Only this flag changes
+    # input_connectable=True (default)
+    # input_connectable_end=True (default)
+    # All output_* flags also default to True
+)
+```
+
+---
+
+## Backwards compatibility
+
+Existing code without connectable flags continues to work — all flags default
+to `True`:
+
+```python
+# Old-style node type definition
+legacy = NodeType(
+    type="task",
+    label="Task",
+    inputs=["in"],
+    outputs=["out"],
+)
+# Behaves exactly as before — all handles fully connectable
+```
+
+---
+
+## Use cases
+
+### ETL pipelines
+
+```python
+extract = NodeType(type="extract", outputs=["data"], output_connectable_end=False)
+transform = NodeType(type="transform", inputs=["in"], outputs=["out"])
+load = NodeType(type="load", inputs=["data"], input_connectable_start=False)
+```
+
+### State machines
+
+```python
+start = NodeType(type="start", outputs=["next"], output_connectable_end=False)
+state = NodeType(type="state", inputs=["in"], outputs=["out"])
+end = NodeType(type="end", inputs=["in"], input_connectable_start=False)
+```
+
+### DAG workflows
+
+```python
+trigger = NodeType(type="trigger", outputs=["event"], output_connectable_end=False)
+task = NodeType(type="task", inputs=["trigger"], outputs=["result"])
+logger = NodeType(type="logger", inputs=["log"], input_connectable_start=False)
+```
+
+---
+
+## Tips
+
+- **Start with defaults**: Don't add restrictions until you need them.
+- **Test in UI**: Try dragging to confirm the restrictions work as expected.
+- **Use patterns**: The source/sink/transform/monitor patterns cover most use cases.
+- **Document intent**: Add comments explaining why specific flags are set.
+
+---
+
+## Related
+
+- [Declare Node & Edge Types](declare-types.md) — full type declaration guide
+- [Define Nodes & Edges](define-nodes-edges.md) — node and edge structure
+- [API Reference](../reference/panel_reactflow.md) — complete API documentation

{panel_reactflow-0.3.1a0 → panel_reactflow-0.4.0b1}/docs/how-to/define-nodes-edges.md

@@ -155,11 +155,34 @@ edges = [
 | `source`       | yes      | ID of the source node. |
 | `target`       | yes      | ID of the target node. |
 | `label`        | no       | Text rendered on the edge. |
-| `type`         | no       | Edge type name (for styling / editors). |
+| `type`         | no       | Edge type (see built-in types below, or a custom type name). |
 | `data`         | no       | Arbitrary dict of payload data. |
 | `sourceHandle` | no       | Specific output handle on the source node. |
 | `targetHandle` | no       | Specific input handle on the target node. |
 
+### Built-in edge types
+
+| Type             | Description |
+|------------------|-------------|
+| `"bezier"`       | Smooth bezier curve (default). |
+| `"straight"`     | Straight line between nodes. |
+| `"step"`         | Orthogonal path with right angles. |
+| `"smoothstep"`   | Step path with rounded corners. |
+| `"smart_bezier"` | Bezier curve that automatically routes around nodes. |
+| `"smart_straight"`| Straight segments that automatically route around nodes. |
+| `"smart_step"`   | Step path that automatically routes around nodes. |
+
+Smart edge types use pathfinding to avoid overlapping with other nodes in
+the graph. They are useful when edges would otherwise pass through
+intermediate nodes.
+
+```python
+edges = [
+    {"id": "e1", "source": "n1", "target": "n2", "type": "smoothstep"},
+    {"id": "e2", "source": "n1", "target": "n3", "type": "smart_bezier"},
+]
+```
+
 ---
 
 ## Define edges as classes

{panel_reactflow-0.3.1a0 → panel_reactflow-0.4.0b1}/docs/how-to/react-to-events.md

@@ -23,6 +23,7 @@ the `ReactFlow` instance as a second argument.  You can also listen for
 | `node_deleted`       | A node is removed. | `node_id` |
 | `node_moved`         | A node is dragged to a new position. | `node_id`, `position` |
 | `node_clicked`       | A node is clicked (single click). | `node_id` |
+| `node_context_menu`  | A node is right-clicked. | `node_id`, `position` |
 | `node_data_changed`  | Node data is patched (via API, editor patch, or parameter-driven sync). | `node_id`, `patch` |
 | `edge_added`         | An edge is created (UI connect or API). | `edge` |
 | `edge_deleted`       | An edge is removed. | `edge_id` |

{panel_reactflow-0.3.1a0 → panel_reactflow-0.4.0b1}/docs/index.md

@@ -61,6 +61,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
 - [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)

panel_reactflow-0.4.0b1/examples/context_menu.py

@@ -0,0 +1,82 @@
+"""Context menu example using Node subclasses.
+
+Demonstrates:
+- Per-node context menus via ``Node.context_menu()``
+- Dynamic menu content based on node state
+- Closing the menu on action (via ``flow.patch_node_data``)
+"""
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from panel_reactflow import Node, ReactFlow
+
+pn.extension()
+
+
+class TaskNode(Node):
+    status = param.Selector(
+        default="idle", objects=["idle", "running", "done", "failed"], precedence=0
+    )
+
+    def __init__(self, **params):
+        params.setdefault("type", "panel")
+        super().__init__(**params)
+
+    def __panel__(self):
+        return pn.pane.Markdown(
+            f"**{self.label}**\n\nStatus: `{self.status}`",
+            sizing_mode="stretch_width",
+        )
+
+    def context_menu(self):
+        def set_status(status):
+            self.flow.patch_node_data(self.id, {"status": status})
+            self.flow._handle_msg({"type": "close_context_menu"})
+
+        run_btn = pmui.Button(
+            name="Run", variant="text", size="small",
+            on_click=lambda e: set_status("running"),
+        )
+        done_btn = pmui.Button(
+            name="Mark Done", variant="text", size="small",
+            on_click=lambda e: set_status("done"),
+        )
+        reset_btn = pmui.Button(
+            name="Reset", variant="text", size="small",
+            on_click=lambda e: set_status("idle"),
+        )
+        delete_btn = pmui.Button(
+            name="Delete", variant="text", color="error", size="small",
+            on_click=lambda e: self.flow.remove_node(self.id),
+        )
+
+        return pn.Column(
+            pn.pane.Markdown(f"**{self.label}**", margin=(4, 8)),
+            run_btn, done_btn, reset_btn, delete_btn,
+            sizing_mode="stretch_width",
+            margin=0,
+        )
+
+
+nodes = [
+    TaskNode(id="extract", label="Extract", position={"x": 0, "y": 0}),
+    TaskNode(id="transform", label="Transform", position={"x": 300, "y": 80}),
+    TaskNode(id="load", label="Load", position={"x": 600, "y": 0}, status="done"),
+]
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=[
+        {"id": "e1", "source": "extract", "target": "transform"},
+        {"id": "e2", "source": "transform", "target": "load"},
+    ],
+    sizing_mode="stretch_both",
+)
+
+pn.Column(
+    pn.pane.Markdown("## Context Menu Demo\nRight-click any node to see its context menu."),
+    flow,
+    sizing_mode="stretch_both",
+).servable()

panel_reactflow-0.4.0b1/examples/edge_types_comparison.py

@@ -0,0 +1,102 @@
+"""
+Comparison of standard edges vs smart edges.
+
+This example demonstrates the difference between standard React Flow edges
+and smart edges that automatically route around obstacles.
+"""
+
+import panel as pn
+from panel_reactflow import EdgeSpec, NodeSpec, ReactFlow
+
+pn.extension()
+
+# Create nodes arranged to show edge routing
+nodes = [
+    # Left column - sources
+    NodeSpec(id="s1", position={"x": 0, "y": 0}, label="Source 1").to_dict(),
+    NodeSpec(id="s2", position={"x": 0, "y": 100}, label="Source 2").to_dict(),
+    NodeSpec(id="s3", position={"x": 0, "y": 200}, label="Source 3").to_dict(),
+    NodeSpec(id="s4", position={"x": 0, "y": 300}, label="Source 4").to_dict(),
+    # Middle obstacles
+    NodeSpec(id="obs1", position={"x": 150, "y": 50}, label="Obstacle 1").to_dict(),
+    NodeSpec(id="obs2", position={"x": 150, "y": 150}, label="Obstacle 2").to_dict(),
+    NodeSpec(id="obs3", position={"x": 150, "y": 250}, label="Obstacle 3").to_dict(),
+    # Right column - targets
+    NodeSpec(id="t1", position={"x": 300, "y": 0}, label="Target 1").to_dict(),
+    NodeSpec(id="t2", position={"x": 300, "y": 100}, label="Target 2").to_dict(),
+    NodeSpec(id="t3", position={"x": 300, "y": 200}, label="Target 3").to_dict(),
+    NodeSpec(id="t4", position={"x": 300, "y": 300}, label="Target 4").to_dict(),
+]
+
+# Create edges with different types
+edges = [
+    # Default edge (goes through obstacle)
+    EdgeSpec(
+        id="e1",
+        source="s1",
+        target="t2",
+        label="default",
+        type=None,
+        style={"stroke": "#999"},
+    ).to_dict(),
+    # Smart bezier (routes around obstacle)
+    EdgeSpec(
+        id="e2",
+        source="s2",
+        target="t3",
+        label="smart_bezier",
+        type="smart_bezier",
+        style={"stroke": "#3b82f6"},
+    ).to_dict(),
+    # Smart straight (routes around obstacle)
+    EdgeSpec(
+        id="e3",
+        source="s3",
+        target="t1",
+        label="smart_straight",
+        type="smart_straight",
+        style={"stroke": "#10b981"},
+    ).to_dict(),
+    # Smart step (routes around obstacle)
+    EdgeSpec(
+        id="e4",
+        source="s4",
+        target="t4",
+        label="smart_step",
+        type="smart_step",
+        style={"stroke": "#f59e0b"},
+    ).to_dict(),
+]
+
+# Create the flow
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    height=600,
+    width="100%",
+)
+
+# Layout
+pn.template.FastListTemplate(
+    title="Edge Types Comparison",
+    sidebar=[
+        pn.pane.Markdown(
+            """
+            ## Edge Types
+
+            This example compares different edge types:
+
+            - **Gray (default)**: Standard edge that goes straight through obstacles
+            - **Blue (smart_bezier)**: Curved edge that routes around obstacles
+            - **Green (smart_straight)**: Straight segments that avoid obstacles
+            - **Orange (smart_step)**: Step-style edge that avoids obstacles
+
+            ### Try it:
+            - Drag the obstacle nodes around
+            - Watch how smart edges automatically reroute
+            - Notice the default edge doesn't avoid obstacles
+            """,
+        ),
+    ],
+    main=[flow],
+).servable()