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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.3.1a0
+Version: 0.4.0
 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.0/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.0/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.0}/docs/how-to/declare-types.md

@@ -6,6 +6,7 @@ kind of node/edge carries**. A type can provide:
 - a type name (`type`)
 - a display label (`label`)
 - node handles (`inputs` / `outputs`)
+- handle connectivity controls (`input_connectable*` / `output_connectable*`)
 - a schema for the `data` payload (`schema`)
 
 Types are separate from editors. A type defines structure; an editor defines
@@ -237,3 +238,159 @@ flow = ReactFlow(
 
 Types without a schema still work; they just do not get schema-driven
 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:
+
+```python
+from panel_reactflow import NodeType
+
+node_types = {
+    "transform": NodeType(
+        type="transform",
+        label="Transform",
+        inputs=[{"id": "in", "label": "Data Input"}],
+        outputs=[
+            {"id": "success", "label": "Successful results"},
+            {"id": "error", "label": "Failed records"},
+        ],
+    ),
+}
+```
+
+Plain strings and dicts can be mixed freely in the same list:
+
+```python
+inputs=["simple_port", {"id": "documented_port", "label": "Hover to see this"}]
+```
+
+---
+
+## Control handle connectivity
+
+By default, all handles (inputs and outputs) are fully connectable — users can
+drag edges from or to any handle. Use the `*_connectable*` flags to restrict
+which connections are allowed.
+
+### Common patterns
+
+#### Data source (output only)
+
+A node that produces data but cannot accept incoming connections to its output:
+
+```python
+from panel_reactflow import NodeType
+
+source_type = NodeType(
+    type="data_source",
+    label="Data Source",
+    outputs=["data"],
+    output_connectable_start=True,   # Can drag FROM output
+    output_connectable_end=False,    # Cannot drag TO output
+)
+```
+
+#### Data sink (input only)
+
+A node that consumes data but cannot produce outgoing connections from its input:
+
+```python
+sink_type = NodeType(
+    type="data_sink",
+    label="Data Sink",
+    inputs=["data"],
+    input_connectable_start=False,   # Cannot drag FROM input
+    input_connectable_end=True,      # Can drag TO input
+)
+```
+
+#### Monitor node
+
+A node that accepts input but whose output is status-only (one direction):
+
+```python
+monitor_type = 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
+)
+```
+
+### All connectivity 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 |
+
+### Complete example
+
+```python
+import panel as pn
+from panel_reactflow import NodeType, NodeSpec, EdgeSpec, ReactFlow
+
+pn.extension("jsoneditor")
+
+# Define node types with different connectivity patterns
+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"],
+        # All connectable flags default to True
+    ),
+    "sink": NodeType(
+        type="sink",
+        label="Data Sink",
+        inputs=["data"],
+        input_connectable_start=False,
+        input_connectable_end=True,
+    ),
+}
+
+# Create a data pipeline
+flow = ReactFlow(
+    nodes=[
+        NodeSpec(id="src", type="source", position={"x": 0, "y": 100}, data={}).to_dict(),
+        NodeSpec(id="tx", type="transform", position={"x": 250, "y": 100}, data={}).to_dict(),
+        NodeSpec(id="snk", type="sink", position={"x": 500, "y": 100}, data={}).to_dict(),
+    ],
+    edges=[
+        EdgeSpec(id="e1", source="src", target="tx").to_dict(),
+        EdgeSpec(id="e2", source="tx", target="snk").to_dict(),
+    ],
+    node_types=node_types,
+    sizing_mode="stretch_both",
+)
+
+flow.servable()
+```
+
+In this example:
+
+- Users can drag from the **source** output to the **transform** input ✓
+- Users cannot drag to the **source** output ✗
+- Users can drag from the **transform** output to the **sink** input ✓
+- Users cannot drag from the **sink** input ✗
+
+The UI prevents invalid connections automatically — non-connectable handles
+show different cursor behavior and won't accept drag operations.

{panel_reactflow-0.3.1a0 → panel_reactflow-0.4.0}/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.0}/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.0}/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)