panel-reactflow 0.2.1__tar.gz → 0.3.0rc0__tar.gz

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/.github/workflows/test.yml

@@ -135,7 +135,7 @@ jobs:
         environment: ["test-ui"]
     timeout-minutes: 60
     env:
-      PYTHONIOENCODING: utf8
+      PYTHONUTF8: 1
       PANEL_LOG_LEVEL: info
       FAIL: "--screenshot only-on-failure --full-page-screenshot --output ui_screenshots --tracing retain-on-failure"
     steps:

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.2.1
+Version: 0.3.0rc0
 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
@@ -59,7 +59,7 @@ A Panel wrapper for the React Flow JS library.
 - Panel viewables inside nodes via node ``view`` entries
 - Interactive editing (drag/select/connect/delete) with sync back to Python
 - Optional schema definitions for node/edge properties
-- Event callbacks via `ReactFlow.on(...)` for app-level handling
+- Event callbacks via `ReactFlow.on(...)` for app-level handling (callback signature: `callback(payload, flow)`)
 
 ## Pin your version!
 
@@ -112,7 +112,7 @@ flow = ReactFlow(
 flow
 ```
 
-For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`.
+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.
 
 ## Development
 

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/README.md

@@ -16,7 +16,7 @@ A Panel wrapper for the React Flow JS library.
 - Panel viewables inside nodes via node ``view`` entries
 - Interactive editing (drag/select/connect/delete) with sync back to Python
 - Optional schema definitions for node/edge properties
-- Event callbacks via `ReactFlow.on(...)` for app-level handling
+- Event callbacks via `ReactFlow.on(...)` for app-level handling (callback signature: `callback(payload, flow)`)
 
 ## Pin your version!
 
@@ -69,7 +69,7 @@ flow = ReactFlow(
 flow
 ```
 
-For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`.
+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.
 
 ## Development
 

panel_reactflow-0.3.0rc0/docs/how-to/declare-types.md

@@ -0,0 +1,239 @@
+# Declare Node & Edge Types
+
+Node and edge types are lightweight descriptors that define **what data each
+kind of node/edge carries**. A type can provide:
+
+- a type name (`type`)
+- a display label (`label`)
+- node handles (`inputs` / `outputs`)
+- a schema for the `data` payload (`schema`)
+
+Types are separate from editors. A type defines structure; an editor defines
+the UI used to edit it.
+
+![Screenshot: multiple node types with different schemas](../assets/screenshots/declare-types.png)
+
+---
+
+## Complete runnable example
+
+This script is a minimal, working example that produces the visualization
+shown above.
+
+```python
+import param
+import panel as pn
+
+from panel_reactflow import EdgeType, NodeType, ReactFlow
+
+pn.extension("jsoneditor")
+
+
+class Job(param.Parameterized):
+    status = param.Selector(objects=["idle", "running", "done"])
+    retries = param.Integer(default=0)
+
+
+decision_schema = {
+    "type": "object",
+    "properties": {
+        "question": {"type": "string", "title": "Question"},
+        "outcome": {
+            "type": "string",
+            "enum": ["yes", "no", "maybe"],
+            "title": "Outcome",
+        },
+    },
+}
+
+node_types = {
+    "job": NodeType(type="job", label="Job", schema=Job, inputs=["in"], outputs=["out"]),
+    "decision": NodeType(
+        type="decision",
+        label="Decision",
+        schema=decision_schema,
+        inputs=["in"],
+        outputs=["yes", "no"],
+    ),
+}
+
+edge_types = {
+    "flow": EdgeType(
+        type="flow",
+        label="Flow",
+        schema={
+            "type": "object",
+            "properties": {"weight": {"type": "number", "title": "Weight"}},
+        },
+    ),
+}
+
+nodes = [
+    {
+        "id": "j1",
+        "type": "job",
+        "label": "Fetch Data",
+        "position": {"x": 0, "y": 0},
+        "data": {"status": "idle", "retries": 0},
+    },
+    {
+        "id": "d1",
+        "type": "decision",
+        "label": "Valid?",
+        "position": {"x": 300, "y": 250},
+        "data": {"question": "Is data valid?", "outcome": "yes"},
+    },
+    {
+        "id": "j2",
+        "type": "job",
+        "label": "Process",
+        "position": {"x": 600, "y": 400},
+        "data": {"status": "running", "retries": 1},
+    },
+]
+
+edges = [
+    {"id": "e1", "source": "j1", "target": "d1", "type": "flow", "data": {"weight": 1.0}},
+    {"id": "e2", "source": "d1", "target": "j2", "type": "flow", "data": {"weight": 0.8}},
+]
+
+TASK_NODE_CSS = """
+.react-flow__node-job {
+    background-color: white;
+    border-radius: 8px;
+    border: 1.5px solid #7c3aed;
+}
+
+.react-flow__node-decision {
+    background-color: white;
+    border-radius: 8px;
+    border: 1.5px solid green;
+}
+"""
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    node_types=node_types,
+    edge_types=edge_types,
+    editor_mode="node",
+    sizing_mode="stretch_both",
+    stylesheets=[TASK_NODE_CSS]
+)
+
+pn.Column(flow, sizing_mode="stretch_both").servable()
+```
+
+## How this code maps to the visualization
+
+- `node_types["job"]` and `node_types["decision"]` define the two node kinds you see.
+- `inputs` and `outputs` define the left/right handles rendered on each node.
+- `edge_types["flow"]` defines the edge payload schema used by both connections.
+- `nodes` controls labels (`Fetch Data`, `Valid?`, `Process`) and positions.
+- `editor_mode="side"` makes selection open the schema-driven editor in the right panel.
+
+---
+
+## Node type snippet
+
+Use `NodeType` to define node handles and payload schema.
+
+```python
+from panel_reactflow import NodeType
+
+task_schema = {
+    "type": "object",
+    "properties": {
+        "status": {"type": "string", "enum": ["idle", "running", "done"]},
+        "priority": {"type": "integer"},
+    },
+}
+
+node_types = {
+    "task": NodeType(
+        type="task",
+        label="Task",
+        schema=task_schema,
+        inputs=["in"],
+        outputs=["out"],
+    ),
+}
+```
+
+## Edge type snippet
+
+Use `EdgeType` for edge payload schema and label.
+
+```python
+from panel_reactflow import EdgeType
+
+edge_types = {
+    "pipe": EdgeType(
+        type="pipe",
+        label="Pipe",
+        schema={
+            "type": "object",
+            "properties": {
+                "throughput": {"type": "number"},
+                "protocol": {"type": "string", "enum": ["tcp", "udp", "http"]},
+            },
+        },
+    ),
+}
+```
+
+---
+
+## Schema sources
+
+The `schema` field accepts multiple inputs and normalizes them to JSON Schema.
+
+| Source | Example |
+|--------|---------|
+| **JSON Schema dict** | `{"type": "object", "properties": {...}}` |
+| **Param class** | A `param.Parameterized` subclass |
+| **Pydantic model** | A `pydantic.BaseModel` subclass |
+
+### Param class shorthand
+
+```python
+import param
+from panel_reactflow import NodeType
+
+class Job(param.Parameterized):
+    status = param.Selector(objects=["idle", "running", "done"])
+    retries = param.Integer(default=0)
+
+node_types = {"job": NodeType(type="job", label="Job", schema=Job)}
+```
+
+### Pydantic model shorthand
+
+```python
+from pydantic import BaseModel
+from panel_reactflow import NodeType
+
+class Config(BaseModel):
+    host: str = "localhost"
+    port: int = 8080
+
+node_types = {"config": NodeType(type="config", label="Config", schema=Config)}
+```
+
+---
+
+## Register on `ReactFlow`
+
+Pass `node_types` and `edge_types` as dictionaries keyed by type name:
+
+```python
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    node_types=node_types,
+    edge_types=edge_types,
+)
+```
+
+Types without a schema still work; they just do not get schema-driven
+validation or auto-generated forms.

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/docs/how-to/define-editors.md

@@ -18,6 +18,65 @@ or falls back to a raw JSON editor.
 
 ---
 
+## Complete runnable example (node editor screenshot)
+
+This script is a minimal, working example for the screenshot above. Run it,
+then click the `Start` node to open the schema-driven editor in the side panel.
+
+```python
+import panel as pn
+
+from panel_reactflow import NodeType, ReactFlow
+
+pn.extension("jsoneditor")
+
+task_schema = {
+    "type": "object",
+    "properties": {
+        "status": {"type": "string", "enum": ["idle", "running", "done"], "title": "Status"},
+        "priority": {"type": "integer", "title": "Priority"},
+        "notes": {"type": "string", "title": "Notes"},
+    },
+}
+
+nodes = [
+    {
+        "id": "start",
+        "type": "task",
+        "label": "Start",
+        "position": {"x": 0, "y": 0},
+        "data": {"status": "idle", "priority": 1, "notes": ""},
+    },
+    {
+        "id": "finish",
+        "type": "task",
+        "label": "Finish",
+        "position": {"x": 300, "y": 80},
+        "data": {"status": "done", "priority": 2, "notes": "All clear"},
+    },
+]
+
+edges = [{"id": "e1", "source": "start", "target": "finish"}]
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    node_types={"task": NodeType(type="task", label="Task", schema=task_schema)},
+    editor_mode="side",
+    sizing_mode="stretch_both",
+)
+
+pn.Column(flow, sizing_mode="stretch_both").servable()
+```
+
+## How this code maps to the node-editor screenshot
+
+- `task_schema` defines fields rendered in the side-panel form.
+- `node_types={"task": ...}` binds that schema to both `task` nodes.
+- Clicking a node selects it and opens its editor because `editor_mode="side"`.
+
+---
+
 ## Editor signature
 
 Every editor — whether a simple function, a lambda, or a class — receives
@@ -106,6 +165,57 @@ edge type) or `default_edge_editor` for a blanket default.
 
 ![Screenshot: an edge editor open in the side panel](../assets/screenshots/define-editors-edge.png)
 
+### Complete runnable example (edge editor screenshot)
+
+This script reproduces the edge-editor screenshot. Run it, then click the
+`pipe` edge to open its schema-driven editor.
+
+```python
+import panel as pn
+
+from panel_reactflow import EdgeType, NodeType, ReactFlow
+
+pn.extension("jsoneditor")
+
+pipe_schema = {
+    "type": "object",
+    "properties": {
+        "throughput": {"type": "number", "title": "Throughput"},
+        "protocol": {
+            "type": "string",
+            "enum": ["tcp", "udp", "http"],
+            "title": "Protocol",
+        },
+    },
+}
+
+nodes = [
+    {"id": "src", "type": "device", "label": "Source", "position": {"x": 0, "y": 0}, "data": {}},
+    {"id": "sink", "type": "device", "label": "Sink", "position": {"x": 400, "y": 0}, "data": {}},
+]
+
+edges = [
+    {
+        "id": "e1",
+        "source": "src",
+        "target": "sink",
+        "type": "pipe",
+        "label": "pipe",
+        "data": {"throughput": 100.0, "protocol": "tcp"},
+    },
+]
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    node_types={"device": NodeType(type="device", label="Device")},
+    edge_types={"pipe": EdgeType(type="pipe", label="Pipe", schema=pipe_schema)},
+    sizing_mode="stretch_both",
+)
+
+pn.Column(flow, sizing_mode="stretch_both").servable()
+```
+
 ### Schema-driven edge editor
 
 If you declare an `EdgeType` with a schema and do not provide an explicit

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/docs/how-to/define-nodes-edges.md

@@ -13,6 +13,58 @@ and update data after the graph is live.
 
 ---
 
+## Complete runnable example
+
+This script is a minimal, working example that produces the visualization
+shown above.
+
+```python
+import panel as pn
+
+from panel_reactflow import ReactFlow
+
+pn.extension("jsoneditor")
+
+nodes = [
+    {
+        "id": "n1",
+        "type": "panel",
+        "label": "Start",
+        "position": {"x": 0, "y": 0},
+        "data": {"status": "idle"},
+        "view": pn.pane.Markdown("Optional node body"),
+    },
+    {
+        "id": "n2",
+        "type": "panel",
+        "label": "End",
+        "position": {"x": 300, "y": 80},
+        "data": {"status": "done"},
+    },
+]
+
+edges = [
+    {"id": "e1", "source": "n1", "target": "n2", "label": "next"},
+]
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    sizing_mode="stretch_both",
+)
+
+pn.Column(flow, sizing_mode="stretch_both").servable()
+```
+
+## How this code maps to the visualization
+
+- `nodes` defines the two boxes (`Start`, `End`) and where they appear.
+- `edges` defines the single connection labeled `next`.
+- `view` on `n1` adds inline content inside that node.
+- `ReactFlow(nodes=..., edges=...)` renders the graph from those lists.
+
+---
+
 ## Define nodes
 
 A node dict requires `id`, `position`, and `data`.  The display label is a

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/docs/how-to/embed-views-in-nodes.md

@@ -15,6 +15,74 @@ thumbnail on an image-processing node.
 
 ---
 
+## Complete runnable example
+
+This script is a minimal, working example that produces the visualization
+shown above.
+
+```python
+import panel as pn
+
+from panel_reactflow import ReactFlow
+
+pn.extension("jsoneditor")
+
+nodes = [
+    {
+        "id": "source",
+        "type": "panel",
+        "label": "Data Source",
+        "position": {"x": 0, "y": 0},
+        "data": {},
+        "view": pn.pane.Markdown("**Status:** connected\n\nRows: 1,204 • Updated 3s ago"),
+    },
+    {
+        "id": "metric",
+        "type": "panel",
+        "label": "KPI",
+        "position": {"x": 320, "y": 0},
+        "data": {},
+        "view": pn.indicators.Number(
+            value=87.3,
+            name="Accuracy",
+            format="{value}%",
+            colors=[(90, "orange"), (100, "green")],
+        ),
+    },
+    {
+        "id": "output",
+        "type": "panel",
+        "label": "Output",
+        "position": {"x": 160, "y": 180},
+        "data": {},
+        "view": pn.pane.HTML(
+            "<div style='padding:6px;font-size:12px;color:#475569;'>✅ Pipeline healthy</div>"
+        ),
+    },
+]
+
+edges = [
+    {"id": "e1", "source": "source", "target": "metric"},
+    {"id": "e2", "source": "metric", "target": "output"},
+]
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    sizing_mode="stretch_both",
+)
+
+pn.Column(flow, sizing_mode="stretch_both").servable()
+```
+
+## How this code maps to the visualization
+
+- Each node has a different `view` (`Markdown`, `Number`, `HTML`).
+- Those views are rendered inline inside the three visible nodes.
+- `edges` creates the two visible connections between those nodes.
+
+---
+
 ## Add a view to a node
 
 Set the `view` key when defining a node.  The value can be any Panel

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc0}/docs/how-to/react-to-events.md

@@ -7,8 +7,9 @@ arbitrary logic in response: update a status bar, log changes, sync to an
 external database, or trigger downstream computations.
 
 Events are registered with `flow.on(event_type, callback)`.  The callback
-receives a single dict containing the event payload.  You can also listen
-for **all** events at once by subscribing to `"*"`.
+receives the event payload as its first argument and may optionally accept
+the `ReactFlow` instance as a second argument.  You can also listen for
+**all** events at once by subscribing to `"*"`.
 
 ![Screenshot: a status bar updating in response to graph events](../assets/screenshots/react-to-events.png)
 
@@ -41,10 +42,13 @@ flow = ReactFlow(nodes=nodes, edges=edges, sizing_mode="stretch_both")
 
 log = pn.pane.Markdown("Waiting for events…")
 
-def on_node_moved(payload):
+def on_node_moved(payload, flow):
     node_id = payload["node_id"]
     pos = payload["position"]
-    log.object = f"**Moved** `{node_id}` → ({pos['x']:.0f}, {pos['y']:.0f})"
+    log.object = (
+        f"**Moved** `{node_id}` → ({pos['x']:.0f}, {pos['y']:.0f}) "
+        f"(nodes: {len(flow.nodes)})"
+    )
 
 flow.on("node_moved", on_node_moved)
 
@@ -62,9 +66,9 @@ debugging or building a generic activity log.
 history = []
 status = pn.pane.Markdown("")
 
-def on_any_event(payload):
+def on_any_event(payload, flow):
     history.append(payload.get("type", "unknown"))
-    status.object = f"**Events so far:** {len(history)}"
+    status.object = f"**Events so far:** {len(history)} (edges: {len(flow.edges)})"
 
 flow.on("*", on_any_event)
 ```
@@ -80,10 +84,12 @@ canvas background.  The payload includes lists of selected `nodes` and
 ```python
 details = pn.pane.JSON({}, depth=2)
 
-def on_selection(payload):
+def on_selection(payload, flow):
     details.object = {
         "selected_nodes": payload.get("nodes", []),
         "selected_edges": payload.get("edges", []),
+        "total_nodes": len(flow.nodes),
+        "total_edges": len(flow.edges),
     }
 
 flow.on("selection_changed", on_selection)