panel-reactflow 0.0.1a1__tar.gz → 0.1.0__tar.gz

{panel_reactflow-0.0.1a1 → panel_reactflow-0.1.0}/.github/workflows/docs.yml

@@ -2,8 +2,25 @@ name: Build documentation
 
 on:
   push:
-    branches:
-      - main
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+a[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+b[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Site to build and deploy"
+        type: choice
+        options:
+          - dev
+          - main
+          - dryrun
+        required: true
+        default: dryrun
+  schedule:
+    - cron: "0 17 * * SUN"
+
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:

{panel_reactflow-0.0.1a1 → panel_reactflow-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panel-reactflow
-Version: 0.0.1a1
+Version: 0.1.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
@@ -51,6 +51,8 @@ Description-Content-Type: text/markdown
 
 A Panel wrapper for the React Flow JS library.
 
+![panel-reactflow demo](https://assets.holoviz.org/panel-reactflow/videos/reactflow_demo.gif)
+
 ## Features
 
 - Python-first, JSON-serializable graph state
@@ -85,14 +87,16 @@ nodes = [
         "id": "n1",
         "position": {"x": 0, "y": 0},
         "type": "panel",
-        "data": {"label": "Start"},
+        "label": "Start",
+        "data": {},
         "view": pn.pane.Markdown("Node 1 content"),
     },
     {
         "id": "n2",
         "position": {"x": 260, "y": 60},
         "type": "panel",
-        "data": {"label": "End"},
+        "label": "End",
+        "data": {},
         "view": pn.pane.Markdown("Node 2 content"),
     },
 ]

{panel_reactflow-0.0.1a1 → panel_reactflow-0.1.0}/README.md

@@ -8,6 +8,8 @@
 
 A Panel wrapper for the React Flow JS library.
 
+![panel-reactflow demo](https://assets.holoviz.org/panel-reactflow/videos/reactflow_demo.gif)
+
 ## Features
 
 - Python-first, JSON-serializable graph state
@@ -42,14 +44,16 @@ nodes = [
         "id": "n1",
         "position": {"x": 0, "y": 0},
         "type": "panel",
-        "data": {"label": "Start"},
+        "label": "Start",
+        "data": {},
         "view": pn.pane.Markdown("Node 1 content"),
     },
     {
         "id": "n2",
         "position": {"x": 260, "y": 60},
         "type": "panel",
-        "data": {"label": "End"},
+        "label": "End",
+        "data": {},
         "view": pn.pane.Markdown("Node 2 content"),
     },
 ]

panel_reactflow-0.1.0/docs/how-to/declare-types.md

@@ -0,0 +1,125 @@
+# Declare Node & Edge Types
+
+Node and edge types are lightweight descriptors that tell Panel-ReactFlow
+**what kind of data a node or edge carries**.  A type defines a name, an
+optional display label, optional input/output ports (for nodes), and an
+optional JSON Schema for its `data` payload.
+
+Types are separate from editors.  A type says "a *task* node has a
+*status* string and a *priority* integer"; an editor says "render a
+dropdown and a number input for those fields."  This separation lets you
+reuse the same type with different editors, or rely on the auto-generated
+form.
+
+![Screenshot: multiple node types with different schemas](../assets/screenshots/declare-types.png)
+
+---
+
+## Node types
+
+Use `NodeType` to describe a node type.  Provide `inputs` and `outputs` to
+control the handles (ports) shown on each side of the node.
+
+```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 types
+
+Use `EdgeType` to describe an edge type.  Edges with a schema get the same
+auto-generated editor support as nodes.
+
+```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 formats.  All are normalized to
+JSON Schema before being sent to the frontend or used by editors.
+
+| 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 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 — the node or edge simply has no
+schema-driven validation or auto-generated form.

panel_reactflow-0.1.0/docs/how-to/define-editors.md

@@ -0,0 +1,239 @@
+# Define Editors
+
+Editors give users a way to view and modify the `data` payload of a node or
+edge at runtime.  Panel-ReactFlow **decouples editors from types**: you
+register editors separately, so you can swap editing UI without touching
+your type definitions.
+
+Both node editors and edge editors share the exact same interface.  If you
+can build a node editor, you already know how to build an edge editor.
+
+When a user selects a node (or an edge), Panel-ReactFlow looks up the
+matching editor, creates the view, and displays it in the configured panel.
+If no editor is registered for a type, the built-in `SchemaEditor` is
+used: it auto-generates a form from the JSON Schema if one is present,
+or falls back to a raw JSON editor.
+
+![Screenshot: a node with schema-driven form editor open in the side panel](../assets/screenshots/define-editors-node.png)
+
+---
+
+## Editor signature
+
+Every editor — whether a simple function, a lambda, or a class — receives
+the same arguments:
+
+```
+editor(data, schema, *, id, type, on_patch) -> Viewable
+```
+
+| Argument   | Description |
+|------------|-------------|
+| `data`     | The current `data` dict of the node or edge. |
+| `schema`   | The normalized JSON Schema (or `None`). |
+| `id`       | The node or edge ID. |
+| `type`     | The node or edge type name. |
+| `on_patch` | Callback: call `on_patch({"key": value})` to push a partial update. |
+
+---
+
+## Built-in editors
+
+Panel-ReactFlow ships two built-in editor classes:
+
+| Class              | Behavior |
+|--------------------|----------|
+| `SchemaEditor` | Renders a form generated from the JSON Schema. Falls back to a raw JSON editor when no schema is available. **This is the default.** |
+| `JsonEditor`   | Always renders a raw JSON editor (powered by `panel.pane.JSON`). |
+
+```python
+from panel_reactflow import JsonEditor, ReactFlow, SchemaEditor
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    default_node_editor=SchemaEditor,   # already the default
+    default_edge_editor=JsonEditor,      # override for edges
+)
+```
+
+---
+
+## Node editors
+
+### Register a callable editor for a node type
+
+The simplest way to provide a custom node editor is a plain function that
+returns a Panel viewable.
+
+```python
+import panel_material_ui as pmui
+from panel_reactflow import ReactFlow
+
+def metric_editor(data, schema, *, id, type, on_patch):
+    value = pmui.FloatSlider(value=data.get("value", 0), start=0, end=100)
+    unit = pmui.Select(value=data.get("unit", "ms"), options=["ms", "s", "%"])
+    value.param.watch(lambda e: on_patch({"value": e.new}), "value")
+    unit.param.watch(lambda e: on_patch({"unit": e.new}), "value")
+    return pmui.Column(value, unit)
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    node_editors={"metric": metric_editor},
+)
+```
+
+### Set a default node editor
+
+If you want *all* node types to use the same custom editor, set
+`default_node_editor` instead of mapping each type individually.
+
+```python
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    default_node_editor=metric_editor,
+)
+```
+
+---
+
+## Edge editors
+
+Edge editors work identically.  Register them via `edge_editors` (keyed by
+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)
+
+### Schema-driven edge editor
+
+If you declare an `EdgeType` with a schema and do not provide an explicit
+editor, the default `SchemaEditor` auto-generates a form — the same
+as for nodes.
+
+```python
+from panel_reactflow import EdgeType, ReactFlow
+
+edge_types = {
+    "pipe": EdgeType(
+        type="pipe",
+        label="Pipe",
+        schema={
+            "type": "object",
+            "properties": {
+                "throughput": {"type": "number", "title": "Throughput"},
+                "protocol": {
+                    "type": "string",
+                    "enum": ["tcp", "udp", "http"],
+                    "title": "Protocol",
+                },
+            },
+        },
+    ),
+}
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    edge_types=edge_types,
+    # No edge_editors needed — SchemaEditor handles "pipe" automatically.
+)
+```
+
+### Custom callable edge editor
+
+```python
+import panel_material_ui as pmui
+from panel_reactflow import EdgeType, ReactFlow
+
+def signal_editor(data, schema, *, id, type, on_patch):
+    freq = pmui.FloatSlider(
+        value=data.get("frequency", 1.0), start=0.1, end=100, step=0.1,
+        label="Frequency (Hz)",
+    )
+    active = pmui.Checkbox(value=data.get("active", True), label="Active")
+    freq.param.watch(lambda e: on_patch({"frequency": e.new}), "value")
+    active.param.watch(lambda e: on_patch({"active": e.new}), "value")
+    return pmui.Paper(pmui.Column(freq, active, margin=5), margin=0)
+
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    edge_types={"signal": EdgeType(type="signal", label="Signal")},
+    edge_editors={"signal": signal_editor},
+)
+```
+
+---
+
+## Class-based editors
+
+For editors with complex state or lifecycle needs, subclass `Editor`.
+The base class stores `data`, `schema`, `id`, `type`, and `on_patch` for
+you.  Implement `__panel__()` to return the view.
+
+Class-based editors work for both nodes and edges.
+
+```python
+import panel as pn
+from panel_reactflow import Editor
+
+class TitleEditor(Editor):
+    def __init__(self, data, schema, **kwargs):
+        super().__init__(data, schema, **kwargs)
+        self._input = pn.widgets.TextInput(value=data.get("title", ""))
+        self._input.param.watch(self._on_title_change, "value")
+
+    def _on_title_change(self, event):
+        if self._on_patch is not None:
+            self._on_patch({"title": event.new})
+
+    def __panel__(self):
+        return self._input
+```
+
+Register it like any callable:
+
+```python
+flow = ReactFlow(
+    nodes=nodes, edges=edges,
+    node_editors={"article": TitleEditor},
+    edge_editors={"comment": TitleEditor},  # reuse the same class
+)
+```
+
+---
+
+## Editor display modes
+
+Control where node editors appear with `editor_mode`:
+
+| Mode      | Description |
+|-----------|-------------|
+| `"side"`  | Side panel to the right of the canvas. |
+| `"node"`  | Inline, directly inside the selected node. |
+| `"toolbar"` | In the top toolbar area. |
+
+Edge editors always appear in the **side panel** (right side of the
+canvas).
+
+```python
+flow = ReactFlow(
+    nodes=nodes,
+    edges=edges,
+    editor_mode="side",
+)
+```
+
+---
+
+## Tips
+
+- Call `on_patch({"key": value})` for data changes.  Labels are top-level
+  and should be updated by replacing the node/edge in `flow.nodes` or
+  `flow.edges`.
+- You can mix strategies: use schema-driven editors for most types and
+  custom editors only where you need full control.
+- The same editor class or function can be registered for both node and
+  edge types.

panel_reactflow-0.1.0/docs/how-to/define-nodes-edges.md

@@ -0,0 +1,133 @@
+# Define Nodes & Edges
+
+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.
+
+This guide covers how to create nodes and edges, use the helper dataclasses,
+and update data after the graph is live.
+
+![Screenshot: a simple two-node graph with one edge](../assets/screenshots/define-nodes-edges.png)
+
+---
+
+## Define nodes
+
+A node dict requires `id`, `position`, and `data`.  The display label is a
+**top-level** field — keep it out of `data` so the frontend can render it
+without parsing the payload.
+
+```python
+import panel as pn
+
+nodes = [
+    {
+        "id": "n1",
+        "type": "panel",
+        "label": "Start",
+        "position": {"x": 0, "y": 0},
+        "data": {"status": "idle"},
+    },
+    {
+        "id": "n2",
+        "type": "panel",
+        "label": "End",
+        "position": {"x": 260, "y": 60},
+        "data": {"status": "done"},
+        "view": pn.pane.Markdown("Optional node body"),
+    },
+]
+```
+
+| Key        | Required | Description |
+|------------|----------|-------------|
+| `id`       | yes      | Unique string identifier. |
+| `position` | yes      | `{"x": float, "y": float}` canvas coordinates. |
+| `data`     | yes      | Arbitrary dict of payload data. |
+| `label`    | no       | Display text shown in the node header. |
+| `type`     | no       | Node type name (default `"panel"`). |
+| `view`     | no       | A Panel viewable rendered inside the node. |
+
+---
+
+## Define edges
+
+Edges link two nodes by their `id`.  Use the top-level `label` for the
+text shown on the edge.
+
+```python
+edges = [
+    {"id": "e1", "source": "n1", "target": "n2", "label": "next"},
+]
+```
+
+| Key      | Required | Description |
+|----------|----------|-------------|
+| `id`     | yes      | Unique string identifier. |
+| `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). |
+| `data`   | no       | Arbitrary dict of payload data. |
+
+---
+
+## Use the NodeSpec / EdgeSpec helpers
+
+If you prefer a typed API, use the dataclass helpers.  They validate fields
+at construction time and convert to plain dicts via `.to_dict()`.
+
+```python
+from panel_reactflow import NodeSpec, EdgeSpec
+
+n1 = NodeSpec(
+    id="n1",
+    type="panel",
+    label="Start",
+    position={"x": 0, "y": 0},
+    data={"status": "idle"},
+).to_dict()
+
+e1 = EdgeSpec(
+    id="e1",
+    source="n1",
+    target="n2",
+    label="next",
+).to_dict()
+```
+
+---
+
+## Update data vs. label
+
+`data` and `label` live in different places and are updated differently:
+
+- **Data** — use `patch_node_data()` or `patch_edge_data()`.  This sends
+  an incremental patch to the frontend without replacing the full list.
+- **Label** — replace the node/edge in `flow.nodes` or `flow.edges`.
+
+```python
+# Patch a data field
+flow.patch_node_data("n1", {"status": "running"})
+flow.patch_edge_data("e1", {"weight": 0.75})
+
+# Update a label
+flow.nodes = [
+    {**node, "label": "Start (running)"} if node["id"] == "n1" else node
+    for node in flow.nodes
+]
+```
+
+---
+
+## Add and remove at runtime
+
+```python
+flow.add_node({"id": "n3", "position": {"x": 520, "y": 0}, "label": "New", "data": {}})
+flow.add_edge({"source": "n2", "target": "n3", "data": {}})
+
+flow.remove_node("n3")   # also removes connected edges
+flow.remove_edge("e1")
+```