panel-reactflow 0.3.0rc0__tar.gz → 0.3.0rc1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.3.0rc0
+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

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.0rc0 → panel_reactflow-0.3.0rc1}/docs/how-to/define-nodes-edges.md

@@ -2,9 +2,9 @@
 
 Every graph in Panel-ReactFlow is built from two lists: **nodes** and
 **edges**.  Nodes represent entities on the canvas; edges represent
-connections between them.  Both are plain Python dictionaries, so you can
-construct them from any data source — a database, a config file, or user
-input at runtime.
+connections between them.  Nodes can be plain dictionaries, `NodeSpec`
+objects, or `Node` instances, so you can choose between lightweight payloads
+and object-oriented node classes.
 
 This guide covers how to create nodes and edges, use the helper dataclasses,
 and update data after the graph is live.
@@ -104,6 +104,40 @@ nodes = [
 
 ---
 
+## Define nodes as classes
+
+Use `Node` when you want per-node Python state, event hooks, and optional
+custom view/editor methods.
+
+```python
+import panel as pn
+from panel_reactflow import Node, ReactFlow
+
+
+class JobNode(Node):
+    def __init__(self, **params):
+        super().__init__(type="job", data={"status": "idle"}, **params)
+
+    def __panel__(self):
+        return pn.pane.Markdown(f"**{self.label}**: {self.data.get('status')}")
+
+    def on_move(self, payload, flow):
+        print(f"{self.id} moved to {payload['position']}")
+
+
+nodes = [
+    JobNode(id="j1", label="Fetch", position={"x": 0, "y": 0}),
+    JobNode(id="j2", label="Process", position={"x": 260, "y": 60}),
+]
+
+flow = ReactFlow(nodes=nodes)
+```
+
+`Node` instances stay as Python objects in `flow.nodes`; they are serialized
+to dicts only when syncing to the frontend.
+
+---
+
 ## Define edges
 
 Edges link two nodes by their `id`.  Use the top-level `label` for the
@@ -128,6 +162,79 @@ edges = [
 
 ---
 
+## Define edges as classes
+
+Use `Edge` when you want object-oriented edge state and edge-specific hooks or
+editor logic.
+
+```python
+from panel_reactflow import Edge, ReactFlow
+
+
+class FlowEdge(Edge):
+    def __init__(self, **params):
+        super().__init__(type="flow", data={"weight": 1.0}, **params)
+
+    def on_data_change(self, payload, flow):
+        print(f"{self.id} updated:", payload["patch"])
+
+
+flow = ReactFlow(
+    nodes=[
+        {"id": "n1", "position": {"x": 0, "y": 0}, "data": {}},
+        {"id": "n2", "position": {"x": 260, "y": 60}, "data": {}},
+    ],
+    edges=[FlowEdge(id="e1", source="n1", target="n2")],
+)
+```
+
+`Edge` instances stay as Python objects in `flow.edges`; they are serialized
+to dicts only when syncing to the frontend.
+
+---
+
+## Data <-> parameter sync on `Node` and `Edge`
+
+For class-based nodes/edges, Panel-ReactFlow supports two-way synchronization
+between `data` and declared parameters.
+
+### Which parameters are included?
+
+Only subclass parameters with **explicit non-negative precedence**
+(`precedence >= 0`) are treated as data fields.
+
+```python
+import param
+from panel_reactflow import Node
+
+
+class TaskNode(Node):
+    status = param.Selector(default="idle", objects=["idle", "running", "done"], precedence=0)
+    retries = param.Integer(default=0, precedence=0)
+    _internal_state = param.String(default="x", precedence=-1)
+```
+
+In this example:
+
+- `status` and `retries` are included in `data`
+- `_internal_state` is not included
+
+### Sync behavior
+
+- **Parameter -> data**: updating `node.status` or `edge.weight` triggers an
+  automatic data patch to the graph and frontend.
+- **Data -> parameter**: incoming graph patches/sync updates write values back
+  onto matching parameters.
+- **Schema generation**: if no explicit type schema is provided, these
+  included parameters are used to generate a JSON schema for editors.
+
+### Editor implication
+
+If your editor widgets are bound with `from_param(...)`, you usually do not
+need manual `on_patch` watchers for those data parameters.
+
+---
+
 ## Use the NodeSpec / EdgeSpec helpers
 
 If you prefer a typed API, use the dataclass helpers.  They validate fields

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

@@ -23,10 +23,10 @@ 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_data_changed`  | `patch_node_data()` is called. | `node_id`, `patch` |
+| `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` |
-| `edge_data_changed`  | `patch_edge_data()` is called. | `edge_id`, `patch` |
+| `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)* |
 
@@ -57,6 +57,58 @@ pn.Column(log, flow).servable()
 
 ---
 
+## Handle events on `Node` classes
+
+If you define nodes as `Node` subclasses, you can implement hooks directly on
+the node instance:
+
+```python
+from panel_reactflow import Node, ReactFlow
+
+
+class TaskNode(Node):
+    def on_event(self, payload, flow):
+        print("any node event:", payload["type"])
+
+    def on_delete(self, payload, flow):
+        print("deleted:", self.id)
+
+
+flow = ReactFlow(nodes=[TaskNode(id="t1", position={"x": 0, "y": 0}, data={})])
+```
+
+Common hooks include `on_event` (wildcard), `on_add`, `on_move`, `on_click`,
+`on_data_change`, and `on_delete`.
+
+When a `Node` subclass parameter with `precedence >= 0` changes, it
+automatically patches node data and will trigger `on_data_change`.
+
+---
+
+## Handle events on `Edge` classes
+
+`Edge` subclasses can handle edge lifecycle and patch events directly:
+
+```python
+from panel_reactflow import Edge, ReactFlow
+
+
+class WeightedEdge(Edge):
+    def on_data_change(self, payload, flow):
+        print("edge patch:", payload["patch"])
+
+    def on_delete(self, payload, flow):
+        print("edge deleted:", self.id)
+```
+
+Common edge hooks include `on_event`, `on_add`, `on_data_change`,
+`on_selection_changed`, and `on_delete`.
+
+Likewise, changing an `Edge` subclass data parameter (`precedence >= 0`)
+triggers `on_data_change` through the same data patch pipeline.
+
+---
+
 ## Listen for all events
 
 Use the wildcard `"*"` to receive every event.  This is useful for

{panel_reactflow-0.3.0rc0 → panel_reactflow-0.3.0rc1}/docs/index.md

@@ -66,6 +66,10 @@ flow.servable()
 - [Style Nodes & Edges](how-to/style-nodes-edges.md)
 - [React to Events](how-to/react-to-events.md)
 
+## Examples
+
+- [Examples gallery](examples/index.md)
+
 ## Reference
 
 - [API reference](reference/panel_reactflow.md)

panel_reactflow-0.3.0rc1/examples/node_edge_instances.py

@@ -0,0 +1,138 @@
+"""Complex example using Node and Edge class instances.
+
+Demonstrates:
+- ``Node`` / ``Edge`` subclass instances in ``ReactFlow``
+- Per-instance ``__panel__`` node views
+- Per-instance custom editors via ``editor(...)``
+- Node/edge event hooks (``on_data_change``, ``on_selection_changed``)
+- Programmatic updates with ``patch_node_data`` / ``patch_edge_data``
+"""
+
+import random
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from panel_reactflow import Edge, Node, ReactFlow
+
+pn.extension()
+
+
+class PipelineNode(Node):
+    status = param.Selector(default="idle", objects=["idle", "running", "done", "failed"], precedence=0)
+    retries = param.Integer(default=0, bounds=(0, None), precedence=0)
+    owner = param.String(default="ops", precedence=0)
+    notes = param.String(default="", precedence=0)
+
+    def __init__(self, **params):
+        params.setdefault("type", "pipeline")
+        super().__init__(**params)
+        self._summary = pn.pane.Markdown(margin=(0, 0, 6, 0))
+        self._activity = pn.pane.Markdown("", styles={"font-size": "12px", "opacity": "0.8"})
+        self.param.watch(self._refresh_view, ["status", "owner", "retries", "label"])
+        self._refresh_view()
+
+    def _refresh_view(self, *_):
+        self._summary.object = (
+            f"**{self.label}**  \n"
+            f"Status: `{self.status}`  \n"
+            f"Owner: `{self.owner}`  \n"
+            f"Retries: `{self.retries}`"
+        )
+
+    def __panel__(self):
+        return pn.Column(self._summary, self._activity, margin=0, sizing_mode="stretch_width")
+
+    def editor(self, data, schema, *, id, type, on_patch):
+        status = pmui.Select.from_param(self.param.status, name="Status")
+        retries = pmui.IntInput.from_param(self.param.retries, name="Retries")
+        owner = pmui.TextInput.from_param(self.param.owner, name="Owner")
+        notes = pmui.TextAreaInput.from_param(self.param.notes, name="Notes", height=80)
+        return pn.Column(status, retries, owner, notes, sizing_mode="stretch_width")
+
+    def on_data_change(self, payload, flow):
+        if payload.get("node_id") == self.id:
+            self._activity.object = f"Last patch: `{payload.get('patch', {})}`"
+
+    def on_selection_changed(self, payload, flow):
+        selected = self.id in (payload.get("nodes") or [])
+        if selected:
+            self._activity.object = "Selected in canvas"
+
+
+class WeightedEdge(Edge):
+    weight = param.Number(default=0.5, bounds=(0, 1), precedence=0)
+    channel = param.Selector(default="main", objects=["main", "backup", "shadow"], precedence=0)
+    enabled = param.Boolean(default=True, precedence=0)
+
+    def __init__(self, **params):
+        params.setdefault("type", "weighted")
+        super().__init__(**params)
+
+    def editor(self, data, schema, *, id, type, on_patch):
+        weight = pmui.FloatSlider.from_param(self.param.weight, name="Weight", step=0.01)
+        channel = pmui.Select.from_param(self.param.channel, name="Channel")
+        enabled = pmui.Checkbox.from_param(self.param.enabled, name="Enabled")
+        return pn.Column(weight, channel, enabled, sizing_mode="stretch_width")
+
+
+nodes = [
+    PipelineNode(id="extract", label="Extract", position={"x": 0, "y": 40}),
+    PipelineNode(id="transform", label="Transform", position={"x": 300, "y": 160}, status="running", retries=1, owner="ml", notes="Batch window"),
+    PipelineNode(id="load", label="Load", position={"x": 600, "y": 40}, owner="platform"),
+]
+
+edges = [
+    WeightedEdge(id="e1", source="extract", target="transform", weight=0.72),
+    WeightedEdge(id="e2", source="transform", target="load", weight=0.63, channel="backup"),
+]
+
+event_log = pmui.TextAreaInput(name="Events", value="", disabled=True, height=180, sizing_mode="stretch_width")
+last_event = pn.pane.Markdown("**Last event:** _none_")
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    editor_mode="side",
+    sizing_mode="stretch_both",
+)
+
+def _log_event(payload):
+    event_type = payload.get("type", "unknown")
+    last_event.object = f"**Last event:** `{event_type}`"
+    snippet = str(payload)
+    event_log.value = f"{event_log.value}\n{event_type}: {snippet}"[-6000:]
+
+
+flow.on("*", _log_event)
+
+
+def _advance_nodes(_):
+    order = {"idle": "running", "running": "done", "done": "done", "failed": "idle"}
+    for node in nodes:
+        current = node.status
+        flow.patch_node_data(node.id, {"status": order.get(current, "idle")})
+
+
+def _randomize_weights(_):
+    for edge in edges:
+        flow.patch_edge_data(edge.id, {"weight": round(random.uniform(0.05, 0.95), 2)})
+
+
+advance_btn = pmui.Button(name="Advance pipeline")
+advance_btn.on_click(_advance_nodes)
+
+weights_btn = pmui.Button(name="Randomize edge weights")
+weights_btn.on_click(_randomize_weights)
+
+controls = pn.Row(advance_btn, weights_btn, sizing_mode="stretch_width")
+
+pn.Column(
+    pn.pane.Markdown("## Node/Edge Instance Workflow"),
+    controls,
+    last_event,
+    flow,
+    event_log,
+    sizing_mode="stretch_both",
+).servable()