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

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc1}/.github/workflows/docs.yml

@@ -70,6 +70,22 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     steps:
-      - name: Deploy to GitHub Pages
+      - name: Deploy dev
+        uses: peaceiris/actions-gh-pages@v4
+        # Dev site built on PRs
+        if: |
+          (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
+          (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'dev') ||
+          (github.event_name == 'push' && (contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
+        with:
+          personal_token: ${{ secrets.HOLOVIZ_ACCESS_TOKEN }}
+          external_repository: holoviz-dev/panel-reactflow
+          publish_dir: ./builtdocs
+          force_orphan: true
+      - name: Deploy main
+        if: |
+          (github.event_name != 'pull_request') &&
+          ((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

{panel_reactflow-0.2.1 → panel_reactflow-0.3.0rc1}/.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.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.2.1
+Version: 0.3.0rc1
 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.0rc1}/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.0rc1/docs/examples/advanced.md

@@ -0,0 +1,12 @@
+# Advanced
+
+Schema-driven editor workflow with a custom node type, type stylesheets,
+and top-panel event feedback.
+
+![Screenshot: advanced example](../assets/screenshots/examples/advanced.png)
+
+## Source
+
+```python
+--8<-- "examples/advanced.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/custom-editor.md

@@ -0,0 +1,12 @@
+# Custom Editor
+
+Registers a callable editor for `metric` nodes and pushes incremental updates
+using `on_patch`.
+
+![Screenshot: custom editor example](../assets/screenshots/examples/custom_editor.png)
+
+## Source
+
+```python
+--8<-- "examples/custom_editor.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/edge-editors.md

@@ -0,0 +1,12 @@
+# Edge Editors
+
+Shows schema-backed edge editing plus a custom callable edge editor for
+specialized edge types.
+
+![Screenshot: edge editors example](../assets/screenshots/examples/edge_editors.png)
+
+## Source
+
+```python
+--8<-- "examples/edge_editors.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/index.md

@@ -0,0 +1,64 @@
+# Examples Gallery
+
+Browse runnable examples from `examples/`. Each card links to a dedicated page
+with a screenshot and full source code.
+
+<div class="grid cards" markdown>
+
+- ![Advanced example](../assets/screenshots/examples/advanced.png)
+
+    ---
+
+    **[Advanced](advanced.md)**
+    Schema-driven task nodes with event tracking.
+
+- ![Custom editor example](../assets/screenshots/examples/custom_editor.png)
+
+    ---
+
+    **[Custom Editor](custom-editor.md)**
+    Callable node editor with custom widgets.
+
+- ![Edge editors example](../assets/screenshots/examples/edge_editors.png)
+
+    ---
+
+    **[Edge Editors](edge-editors.md)**
+    Schema-backed and callable edge editors.
+
+- ![Node/edge instances example](../assets/screenshots/examples/node_edge_instances.png)
+
+    ---
+
+    **[Node/Edge Instances](node-edge-instances.md)**
+    Class-based nodes and edges with hooks.
+
+- ![Schema types example](../assets/screenshots/examples/schema_types.png)
+
+    ---
+
+    **[Schema Types](schema-types.md)**
+    Multiple node types, each with its own schema.
+
+- ![Simple example](../assets/screenshots/examples/simple.png)
+
+    ---
+
+    **[Simple](simple.md)**
+    Minimal graph setup with top panel.
+
+- ![ThreeJS viewer example](../assets/screenshots/examples/threejs_viewer.png)
+
+    ---
+
+    **[ThreeJS Viewer](threejs-viewer.md)**
+    Graph-driven 3D cube viewer controls.
+
+- ![ThreeJS viewer instances example](../assets/screenshots/examples/threejs_viewer_instances.png)
+
+    ---
+
+    **[ThreeJS Viewer (Instances)](threejs-viewer-instances.md)**
+    ThreeJS viewer with Node and Edge instances.
+
+</div>

panel_reactflow-0.3.0rc1/docs/examples/node-edge-instances.md

@@ -0,0 +1,12 @@
+# Node/Edge Instances
+
+Uses `Node` and `Edge` subclasses for rich behavior, custom editors, and event
+hooks while still rendering in a standard ReactFlow canvas.
+
+![Screenshot: node and edge instances example](../assets/screenshots/examples/node_edge_instances.png)
+
+## Source
+
+```python
+--8<-- "examples/node_edge_instances.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/schema-types.md

@@ -0,0 +1,12 @@
+# Schema Types
+
+Demonstrates multiple node types where each type contributes its own schema,
+including both Param-derived and raw JSON Schema definitions.
+
+![Screenshot: schema types example](../assets/screenshots/examples/schema_types.png)
+
+## Source
+
+```python
+--8<-- "examples/schema_types.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/simple.md

@@ -0,0 +1,11 @@
+# Simple
+
+A minimal two-node graph setup with an edge and an optional top panel.
+
+![Screenshot: simple example](../assets/screenshots/examples/simple.png)
+
+## Source
+
+```python
+--8<-- "examples/simple.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/threejs-viewer-instances.md

@@ -0,0 +1,12 @@
+# ThreeJS Viewer (Instances)
+
+The ThreeJS viewer example implemented with `Node` and `Edge` subclass
+instances for object-oriented graph behavior.
+
+![Screenshot: threejs viewer instances example](../assets/screenshots/examples/threejs_viewer_instances.png)
+
+## Source
+
+```python
+--8<-- "examples/threejs_viewer_instances.py"
+```

panel_reactflow-0.3.0rc1/docs/examples/threejs-viewer.md

@@ -0,0 +1,12 @@
+# ThreeJS Viewer
+
+Interactive 3D cube rendering controlled through graph-connected parameter
+nodes.
+
+![Screenshot: threejs viewer example](../assets/screenshots/examples/threejs_viewer.png)
+
+## Source
+
+```python
+--8<-- "examples/threejs_viewer.py"
+```

panel_reactflow-0.3.0rc1/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.0rc1}/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