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

{panel_reactflow-0.3.0rc0 → panel_reactflow-0.3.1}/.github/workflows/build.yml

@@ -11,11 +11,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@ba3bb36eb2066252b2363392b7739741bb777659 # v0.8.1
+        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
         with:
           environments: build
       - name: Build project
@@ -23,7 +23,7 @@ jobs:
       - name: Check package
         run: pixi run -e build check-wheel
       - name: Upload package
-        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: artifact
           path: dist/*
@@ -37,7 +37,7 @@ jobs:
       id-token: write
     environment: pypi
     steps:
-      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+      - uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
         with:
           name: artifact
           path: dist

{panel_reactflow-0.3.0rc0 → panel_reactflow-0.3.1}/.github/workflows/docs.yml

@@ -43,23 +43,23 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Set up Pixi
-        uses: prefix-dev/setup-pixi@ba3bb36eb2066252b2363392b7739741bb777659 # v0.8.1
+        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
         with:
           environments: docs
       - name: Build documentation
         run: pixi run -e docs docs-build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: docs
           if-no-files-found: error
           path: builtdocs
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: ./builtdocs
 
@@ -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.1}/.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
       code_change: ${{ steps.filter.outputs.code }}
       matrix: ${{ env.MATRIX }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         if: github.event_name != 'pull_request'
       - name: Check for code changes
         uses: dorny/paths-filter@v3
@@ -80,9 +80,9 @@ jobs:
     needs: [setup, pixi_lock]
     runs-on: "ubuntu-latest"
     steps:
-      - uses: actions/checkout@v5.0.0
+      - uses: actions/checkout@v6
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@v0.9.2
+        uses: prefix-dev/setup-pixi@v0.9.4
       - uses: holoviz-dev/holoviz_tasks/pre-commit@v0
       - uses: pre-commit/action@v3.0.1
         if: needs.setup.outputs.img_change == 'true'
@@ -111,11 +111,11 @@ jobs:
           - windows-latest
     steps:
       - name: Checkout branch
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
       - name: Set up pixi
-        uses: prefix-dev/setup-pixi@ba3bb36eb2066252b2363392b7739741bb777659 # v0.8.1
+        uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
         with:
           environments: ${{ matrix.environment }}
       - name: Install repository
@@ -151,7 +151,7 @@ jobs:
           echo "[run]\nconcurrency = greenlet" > .uicoveragerc
           pixi run -e ${{ matrix.environment }} test-ui $COV --cov-config=.uicoveragerc $FAIL
       - name: Upload UI Screenshots
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: ui_screenshots_${{ runner.os }}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.3.0rc0
+Version: 0.3.1
 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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1}/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.1}/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.1}/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.0rc0 → panel_reactflow-0.3.1}/docs/releases.md

@@ -1,5 +1,34 @@
 # Release Notes
 
+## Version 0.3.0
+
+This release focuses on core graph-model capabilities, callback ergonomics,
+rendering/styling improvements, and major documentation expansion.
+
+### Highlights
+
+- **Parameterized `Node`/`Edge` instances as first-class graph elements** —
+  `ReactFlow` now supports instance-based graph authoring with richer Python
+  object workflows, including improved serialization/sync behavior and expanded
+  API/core test coverage.
+- **Event callback improvements** — `.on(...)` callbacks can now accept the
+  `ReactFlow` instance as a second argument and support async callbacks, making
+  app-level event handling significantly more flexible.
+- **Rendering fixes for embedded views** — improved scaling and interaction
+  behavior when rendering figures inside nodes, including better handling of
+  drag/pan/scroll conflicts within embedded content.
+- **Editor rendering robustness** — fixed node and edge editor rendering paths
+  so editors can render reliably even when no node `view` is defined.
+- **Color mode and default node styling support** — added color-mode-aware
+  styling capabilities and refined baseline node CSS for better defaults out of
+  the box.
+- **Expanded how-to documentation** — substantial updates to guides for
+  declaring types, defining nodes/edges, editors, embedding views, reacting to
+  events, and styling, with refreshed screenshots across the docs.
+- **Examples overhaul in docs** — added an examples gallery with grid cards and
+  dedicated pages/screenshots for each example app, plus docs navigation
+  updates for easier discovery.
+
 ## Version 0.2.0
 
 This release focuses on stronger typed graph specs, better node-view handling,