panel-reactflow 0.5.0b1__tar.gz → 0.6.0b0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/PKG-INFO +12 -1
  2. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/README.md +8 -0
  3. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/define-editors.md +28 -3
  4. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/define-nodes-edges.md +46 -0
  5. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/react-to-events.md +80 -2
  6. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/validate-connections.md +1 -1
  7. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/quickstart.md +4 -1
  8. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/releases.md +54 -7
  9. panel_reactflow-0.6.0b0/examples/drop_from_menu.py +75 -0
  10. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/pixi.lock +5300 -5260
  11. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/pixi.toml +1 -0
  12. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/pyproject.toml +2 -0
  13. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/base.py +1199 -327
  14. panel_reactflow-0.6.0b0/src/panel_reactflow/dist/panel-reactflow.bundle.js +88 -0
  15. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/models/reactflow.jsx +763 -202
  16. panel_reactflow-0.6.0b0/src/panel_reactflow/schema.py +469 -0
  17. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/conftest.py +42 -1
  18. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/test_api.py +398 -25
  19. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/test_core.py +39 -10
  20. panel_reactflow-0.6.0b0/tests/test_schema.py +425 -0
  21. panel_reactflow-0.6.0b0/tests/test_structural_sync.py +395 -0
  22. panel_reactflow-0.6.0b0/tests/test_validation.py +500 -0
  23. panel_reactflow-0.6.0b0/tests/ui/test_frontend_robustness.py +409 -0
  24. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/ui/test_ui.py +814 -1
  25. panel_reactflow-0.5.0b1/src/panel_reactflow/dist/panel-reactflow.bundle.js +0 -88
  26. panel_reactflow-0.5.0b1/src/panel_reactflow/schema.py +0 -239
  27. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.copier-answers.yml +0 -0
  28. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.gitattributes +0 -0
  29. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.github/CODEOWNERS +0 -0
  30. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.github/dependabot.yml +0 -0
  31. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.github/workflows/build.yml +0 -0
  32. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.github/workflows/docs.yml +0 -0
  33. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.github/workflows/test.yml +0 -0
  34. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.gitignore +0 -0
  35. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.pre-commit-config.yaml +0 -0
  36. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/.prettierrc +0 -0
  37. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/LICENSE.txt +0 -0
  38. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/MANIFEST.in +0 -0
  39. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/logo.svg +0 -0
  40. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/declare-types.png +0 -0
  41. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/define-editors-edge.png +0 -0
  42. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/define-editors-node.png +0 -0
  43. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/define-nodes-edges.png +0 -0
  44. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/embed-views-in-nodes.png +0 -0
  45. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/advanced.png +0 -0
  46. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/custom_editor.png +0 -0
  47. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/edge_editors.png +0 -0
  48. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/node_edge_instances.png +0 -0
  49. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/schema_types.png +0 -0
  50. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/simple.png +0 -0
  51. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/threejs_viewer.png +0 -0
  52. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/examples/threejs_viewer_instances.png +0 -0
  53. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/quickstart.png +0 -0
  54. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/react-to-events.png +0 -0
  55. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/assets/screenshots/style-nodes-edges.png +0 -0
  56. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/advanced.md +0 -0
  57. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/custom-editor.md +0 -0
  58. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/edge-editors.md +0 -0
  59. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/index.md +0 -0
  60. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/node-edge-instances.md +0 -0
  61. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/schema-types.md +0 -0
  62. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/simple.md +0 -0
  63. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/threejs-viewer-instances.md +0 -0
  64. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/examples/threejs-viewer.md +0 -0
  65. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/context-menu.md +0 -0
  66. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/control-handle-connectivity.md +0 -0
  67. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/declare-types.md +0 -0
  68. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/embed-views-in-nodes.md +0 -0
  69. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/recover-from-errors.md +0 -0
  70. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/how-to/style-nodes-edges.md +0 -0
  71. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/index.md +0 -0
  72. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/docs/reference/panel_reactflow.md +0 -0
  73. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/advanced.py +0 -0
  74. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/connection_validation.py +0 -0
  75. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/context_menu.py +0 -0
  76. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/custom_editor.py +0 -0
  77. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/edge_editors.py +0 -0
  78. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/edge_types_comparison.py +0 -0
  79. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/node_edge_instances.py +0 -0
  80. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/port_value_inspection.py +0 -0
  81. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/schema_types.py +0 -0
  82. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/simple.py +0 -0
  83. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/smart_edges_example.py +0 -0
  84. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/threejs_viewer.py +0 -0
  85. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/examples/threejs_viewer_instances.py +0 -0
  86. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/hatch_build.py +0 -0
  87. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/__init__.py +0 -0
  88. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/__version.py +0 -0
  89. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/dist/css/reactflow.css +0 -0
  90. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/dist/icons/gear.svg +0 -0
  91. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/dist/panel-reactflow.bundle.css +0 -0
  92. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/src/panel_reactflow/py.typed +0 -0
  93. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/__init__.py +0 -0
  94. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/test_connectable_handles.py +0 -0
  95. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/test_connectable_integration.py +0 -0
  96. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/test_error_recovery.py +0 -0
  97. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/ui/__init__.py +0 -0
  98. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/ui/test_context_menu.py +0 -0
  99. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/ui/test_error_recovery.py +0 -0
  100. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/tests/ui/test_value_popup.py +0 -0
  101. {panel_reactflow-0.5.0b1 → panel_reactflow-0.6.0b0}/zensical.toml +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: panel-reactflow
3
- Version: 0.5.0b1
3
+ Version: 0.6.0b0
4
4
  Summary: A Panel wrapper for the Reactflow JS library.
5
5
  Project-URL: Homepage, https://github.com/panel-extensions/panel-reactflow
6
6
  Project-URL: Source, https://github.com/panel-extensions/panel-reactflow
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.13
22
22
  Classifier: Topic :: Scientific/Engineering
23
23
  Classifier: Topic :: Software Development :: Libraries
24
24
  Requires-Python: >=3.10
25
+ Requires-Dist: jsonschema
25
26
  Requires-Dist: packaging
26
27
  Requires-Dist: panel>=1.5.0
27
28
  Provides-Extra: dev
@@ -35,6 +36,8 @@ Requires-Dist: pytest-asyncio; extra == 'dev'
35
36
  Requires-Dist: pytest-rerunfailures; extra == 'dev'
36
37
  Requires-Dist: pytest-xdist; extra == 'dev'
37
38
  Requires-Dist: watchfiles; extra == 'dev'
39
+ Provides-Extra: material
40
+ Requires-Dist: panel-material-ui; extra == 'material'
38
41
  Provides-Extra: mypy
39
42
  Requires-Dist: mypy; extra == 'mypy'
40
43
  Requires-Dist: types-requests; extra == 'mypy'
@@ -73,6 +76,14 @@ Install it via `pip`:
73
76
  pip install panel-reactflow
74
77
  ```
75
78
 
79
+ The schema-driven editors use [panel-material-ui](https://github.com/panel-extensions/panel-material-ui)
80
+ widgets when it is installed and plain Panel widgets otherwise. Install it
81
+ with:
82
+
83
+ ```bash
84
+ pip install "panel-reactflow[material]"
85
+ ```
86
+
76
87
  ## Usage
77
88
 
78
89
  ```python
@@ -30,6 +30,14 @@ Install it via `pip`:
30
30
  pip install panel-reactflow
31
31
  ```
32
32
 
33
+ The schema-driven editors use [panel-material-ui](https://github.com/panel-extensions/panel-material-ui)
34
+ widgets when it is installed and plain Panel widgets otherwise. Install it
35
+ with:
36
+
37
+ ```bash
38
+ pip install "panel-reactflow[material]"
39
+ ```
40
+
33
41
  ## Usage
34
42
 
35
43
  ```python
@@ -10,9 +10,24 @@ can build a node editor, you already know how to build an edge editor.
10
10
 
11
11
  When a user selects a node (or an edge), Panel-ReactFlow looks up the
12
12
  matching editor, creates the view, and displays it in the configured panel.
13
- If no editor is registered for a type, the built-in `SchemaEditor` is
13
+ If no editor is registered for a node type, the built-in `SchemaEditor` is
14
14
  used: it auto-generates a form from the JSON Schema if one is present,
15
- or falls back to a raw JSON editor.
15
+ or falls back to a raw JSON editor. Edges only get the `SchemaEditor`
16
+ fallback when their type declares a schema, so selecting a plain edge does
17
+ not open an editor. Editors are hidden entirely while `editable=False`.
18
+
19
+ The form understands the schemas generated by `param` and `pydantic`:
20
+ `$ref` definitions, optional (nullable) fields, `Literal`/`const` and enum
21
+ choices, and `minimum`/`maximum` bounds, which produce sliders. A property
22
+ without a dedicated widget, such as a nested object, is shown as a literal
23
+ input rather than replacing the whole form. Dates are written back to the
24
+ node data as ISO 8601 strings.
25
+
26
+ When `panel-material-ui` is installed the form uses its widgets, but loading
27
+ it for the editor does not switch the global `pn.config.design` to
28
+ `MaterialDesign` the way importing `panel_material_ui` normally does. If the
29
+ rest of your app should use the Material design, import `panel_material_ui`
30
+ before building the first editor, or set `pn.config.design` explicitly.
16
31
 
17
32
  ![Screenshot: a node with schema-driven form editor open in the side panel](../assets/screenshots/define-editors-node.png)
18
33
 
@@ -102,7 +117,7 @@ Panel-ReactFlow ships two built-in editor classes:
102
117
 
103
118
  | Class | Behavior |
104
119
  |--------------------|----------|
105
- | `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.** |
120
+ | `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** (for edges, only when the edge type has a schema). |
106
121
  | `JsonEditor` | Always renders a raw JSON editor (powered by `panel.pane.JSON`). |
107
122
 
108
123
  ```python
@@ -163,6 +178,16 @@ flow = ReactFlow(
163
178
  Edge editors work identically. Register them via `edge_editors` (keyed by
164
179
  edge type) or `default_edge_editor` for a blanket default.
165
180
 
181
+ Unlike nodes, an edge without a registered editor and without a schema
182
+ has no editor: selecting it only updates `selection`. To give every edge
183
+ an editor, including a raw JSON fallback, set `default_edge_editor`:
184
+
185
+ ```python
186
+ from panel_reactflow import ReactFlow, SchemaEditor
187
+
188
+ flow = ReactFlow(nodes=nodes, edges=edges, default_edge_editor=SchemaEditor)
189
+ ```
190
+
166
191
  ![Screenshot: an edge editor open in the side panel](../assets/screenshots/define-editors-edge.png)
167
192
 
168
193
  ### Complete runnable example (edge editor screenshot)
@@ -183,6 +183,23 @@ edges = [
183
183
  ]
184
184
  ```
185
185
 
186
+ ### Self-loops
187
+
188
+ An edge whose `source` and `target` are the same node is drawn as a loop
189
+ that leaves the output handle, arcs around the node and re-enters at the input
190
+ handle, whatever its `type`. The label sits at the far point of the arc, and
191
+ several loops on one node are stacked so each stays visible.
192
+
193
+ ```python
194
+ edges = [
195
+ {"id": "lateral", "source": "n1", "target": "n1", "label": "lateral"},
196
+ ]
197
+ ```
198
+
199
+ Users can draw a self-loop by dragging from a node's output to its own input.
200
+ Enable the `cycles` policy in `connection_validation` to reject them; see
201
+ [Validate Connections](validate-connections.md).
202
+
186
203
  ---
187
204
 
188
205
  ## Define edges as classes
@@ -419,6 +436,14 @@ flow.remove_node("n3") # also removes connected edges
419
436
  flow.remove_edge("e1")
420
437
  ```
421
438
 
439
+ `add_node()` and `add_edge()` raise a `ValueError` for an id that is already
440
+ in use, an edge whose `source` or `target` is not a node of the graph, and data
441
+ that cannot be sent to the browser. Anything Bokeh can serialize is accepted,
442
+ including NumPy scalars and arrays and datetimes; arbitrary objects, sets and
443
+ dataclasses are not (a node's `view` is rendered separately and not checked).
444
+ The same checks apply to `patch_node_data()`, `patch_edge_data()` and the
445
+ `patch_*_props()` methods.
446
+
422
447
  `remove_node()` and `remove_edge()` also take several ids at once, either as
423
448
  separate arguments or as a single sequence. Pass them together rather than
424
449
  calling the methods in a loop: a batch assigns `nodes` and `edges` once, so the
@@ -441,3 +466,24 @@ with pn.io.hold():
441
466
  flow.nodes = new_nodes
442
467
  flow.edges = new_edges
443
468
  ```
469
+
470
+ ### Fit the graph into view
471
+
472
+ The canvas fits the view to the graph only when it first renders. After adding
473
+ nodes or loading a new graph, call `fit_view()` to pan and zoom so that the
474
+ graph fits again. The resulting viewport is synced back to `flow.viewport`.
475
+
476
+ ```python
477
+ flow.nodes = new_nodes
478
+ flow.edges = new_edges
479
+ flow.fit_view()
480
+
481
+ # Zoom to a subset of nodes with some padding and an animated transition
482
+ flow.fit_view("n1", "n2", padding=0.2, duration=500)
483
+ ```
484
+
485
+ A fit requested right after `nodes` changed waits until the browser has
486
+ rendered and measured the new nodes, so it fits the new graph rather than the
487
+ previous one, also inside `pn.io.hold()`. Calling `fit_view()` before the
488
+ component is displayed does nothing, since the first render fits the view
489
+ anyway.
@@ -22,7 +22,7 @@ the `ReactFlow` instance as a second argument. You can also listen for
22
22
  | `node_added` | A node is added to the graph. | `node` |
23
23
  | `node_deleted` | A node is removed. | `node_id` |
24
24
  | `node_moved` | A node is dragged to a new position. | `node_id`, `position` |
25
- | `node_clicked` | A node is clicked (single click). | `node_id` |
25
+ | `node_clicked` | A node is clicked (single click). See [below](#node-clicks). | `node_id`, `position` |
26
26
  | `node_context_menu` | A node is right-clicked. | `node_id`, `position` |
27
27
  | `node_data_changed` | Node data is patched (via API, editor patch, or parameter-driven sync). | `node_id`, `patch` |
28
28
  | `edge_added` | An edge is created (UI connect or API). | `edge` |
@@ -30,8 +30,16 @@ the `ReactFlow` instance as a second argument. You can also listen for
30
30
  | `edge_data_changed` | Edge data is patched (via API, editor patch, or parameter-driven sync). | `edge_id`, `patch` |
31
31
  | `selection_changed` | The active selection changes. | `nodes`, `edges` |
32
32
  | `sync` | A batch sync from the frontend. | *(varies)* |
33
+ | `drop` | Data of one of the `drop_types` is dropped onto the canvas. See [Handle drops](#handle-drops-onto-the-canvas). | `drop_type`, `data`, `position`, `target` |
33
34
  | `client_error` | The graph view hit a rendering error in the browser. See [Recover from Rendering Errors](recover-from-errors.md). | `source`, `message`, `stack`, `component_stack`, `attempt`, `mode` |
34
35
 
36
+ ### Node clicks
37
+
38
+ `node_clicked` fires on every single click, so a double click emits two
39
+ `node_clicked` events before the double-click handling runs. Clicks that end a
40
+ drag or pan, and clicks on a node's embedded view or editor, are not reported.
41
+ The event also fires when `editable=False`.
42
+
35
43
  ---
36
44
 
37
45
  ## Listen for a single event type
@@ -133,7 +141,8 @@ flow.on("*", on_any_event)
133
141
 
134
142
  `selection_changed` fires whenever the user clicks a node, an edge, or the
135
143
  canvas background. The payload includes lists of selected `nodes` and
136
- `edges` IDs.
144
+ `edges` IDs. Selection keeps working on a read-only canvas
145
+ (`editable=False`); set `selectable=False` to turn it off.
137
146
 
138
147
  ```python
139
148
  details = pn.pane.JSON({}, depth=2)
@@ -151,6 +160,68 @@ flow.on("selection_changed", on_selection)
151
160
 
152
161
  ---
153
162
 
163
+ ## Handle drops onto the canvas
164
+
165
+ Set `drop_types` to the MIME types the canvas accepts, and each drop of one
166
+ of them emits `drop`. Anything that sets data under that type when a drag
167
+ starts can be the source; a `panel_material_ui.MenuList` with
168
+ `draggable=True` sends `{"path": [...], "label": ...}` under its
169
+ `drag_type`. The payload's `position` is in flow coordinates, and `target`
170
+ names the node, and handle when there is one, under the pointer, so a
171
+ handler can add the dropped item there or wire it to the handle it landed
172
+ on. Drops are ignored while `editable` is False.
173
+
174
+ ```python
175
+ palette = pmui.MenuList(items=[{"label": "CSV file"}, {"label": "Database"}], draggable=True)
176
+ flow = ReactFlow(drop_types=[palette.drag_type])
177
+
178
+ def on_drop(payload, flow):
179
+ item = palette.items[payload["data"]["path"][0]]
180
+ node_id = f"node-{len(flow.nodes)}"
181
+ flow.add_node({"id": node_id, "label": item["label"], "position": payload["position"], "data": {}})
182
+ target = payload["target"]
183
+ if target and target["direction"] == "input":
184
+ flow.add_edge({"source": node_id, "target": target["node_id"], "targetHandle": target["handle_id"]})
185
+
186
+ flow.on("drop", on_drop)
187
+ ```
188
+
189
+ `examples/drop_from_menu.py` extends this with a grouped palette and places
190
+ a node dropped on an input handle beside the node it feeds.
191
+
192
+ To accept files dragged in from the operating system, add `"Files"` to `drop_types`. The payload's `data` is then a list with one `{"name", "type", "size", "content"}` entry per file. A file whose bytes are valid UTF-8 arrives with its text as a `str` `content`, whatever MIME type the operating system reports for it (Windows, for example, reports `.csv` files as `application/vnd.ms-excel`). Other files, such as images or Parquet, arrive with `bytes` content:
193
+
194
+ ```python
195
+ flow = ReactFlow(drop_types=["Files"])
196
+
197
+ def on_file_drop(payload, flow):
198
+ for file in payload["data"]:
199
+ if file["name"].endswith(".json"):
200
+ graph = json.loads(file["content"])
201
+ flow.param.update(nodes=graph["nodes"], edges=graph["edges"])
202
+
203
+ flow.on("drop", on_file_drop)
204
+ ```
205
+
206
+ For example, to load tables of either kind:
207
+
208
+ ```python
209
+ import io
210
+
211
+ import pandas as pd
212
+
213
+ def on_table_drop(payload, flow):
214
+ for file in payload["data"]:
215
+ if file["name"].endswith(".parquet"):
216
+ df = pd.read_parquet(io.BytesIO(file["content"]))
217
+ elif file["name"].endswith(".csv"):
218
+ df = pd.read_csv(io.StringIO(file["content"]))
219
+ ```
220
+
221
+ Files that exceed `max_drop_size` (10 MB in total by default) or cannot be read are not sent; they are listed in the payload's `rejected` entries with a `reason` instead.
222
+
223
+ ---
224
+
154
225
  ## Register multiple handlers
155
226
 
156
227
  You can register as many handlers as you like for the same event — they
@@ -168,6 +239,13 @@ flow.on("node_added", recalculate_layout)
168
239
 
169
240
  - Callbacks run on the server in the Panel event loop. Keep them fast;
170
241
  offload heavy work with `pn.state.execute()` or background threads.
242
+ - `ReactFlow` is not thread-safe. Change the graph (`add_node()`,
243
+ `patch_node_data()`, assigning `nodes`, ...) only from the session's own
244
+ callbacks, not from a background thread; hand results back with
245
+ `pn.state.execute(callback)` instead.
246
+ - An exception in a callback or `Node`/`Edge` hook is logged on the
247
+ `panel.reactflow` logger and the remaining callbacks still run. The graph
248
+ change that emitted the event has already been applied.
171
249
  - Use `"*"` during development for a quick audit trail, then switch to
172
250
  specific event names in production.
173
251
  - The `selection` parameter on `ReactFlow` also updates reactively. If
@@ -79,4 +79,4 @@ Register callbacks with `flow.add_connection_validator(callback)` and unregister
79
79
 
80
80
  When a user starts dragging from an output or input, Python checks every candidate handle on the opposite side. Validators run in registration order until one rejects a candidate. Browser policies and Python reasons are shown on handles while dragging; the browser prevents a rejected connection. Python results must arrive before the connection is dropped: pending requests and requests taking longer than three seconds block the connection. Exceptions also reject the candidate and are logged on the server. Keep validators fast.
81
81
 
82
- Validation is for interactive drags, not a constraint on `flow.edges` or `flow.add_edge()`. Python validators run at drag start, not when the edge is added. If the rule depends on graph state that may change during the drag, check it again in an `edge_added` handler before keeping or persisting the edge. The example above removes an edge if its application rule no longer holds.
82
+ Validation is for interactive connections, not a constraint on `flow.edges` or `flow.add_edge()`. Python validators run when a drag starts and once more for the final connection when the browser reports the new edge, since the graph may have changed during the drag. An edge rejected at that point is never added to `flow.edges`, no `edge_added` event fires, and the browser removes the edge it had already drawn. The same happens when `flow.add_edge()` raises for an edge from the browser, e.g. because an endpoint no longer exists or its data fails schema validation with `validate_on_add=True`. Browser policies set with `connection_validation` are only checked in the browser.
@@ -9,9 +9,12 @@ interactive graph that auto-generates editing forms from a JSON Schema.
9
9
  ## Install
10
10
 
11
11
  ```bash
12
- pip install panel-reactflow
12
+ pip install "panel-reactflow[material]"
13
13
  ```
14
14
 
15
+ The `material` extra installs `panel-material-ui`, whose widgets the
16
+ schema-driven editors use (plain Panel widgets otherwise).
17
+
15
18
  ## Minimal app
16
19
 
17
20
  !!! note "Required Extension"
@@ -1,9 +1,41 @@
1
1
  # Release Notes
2
2
 
3
+ ## Unreleased
4
+
5
+ ### Breaking changes
6
+
7
+ - `add_node()`, `add_nodes()`, `add_edge()` and `add_edges()` raise a `ValueError` for an id that is already in use, an edge whose `source` or `target` is missing or not a node of the graph, and data that cannot be sent to the browser (arbitrary objects, sets, dataclasses; NumPy values and datetimes are fine). Previously such nodes and edges were added and broke rendering or later lookups. The same data check applies to `patch_node_data()`, `patch_edge_data()` and `patch_*_props()`. Add nodes before the edges that connect them. Graphs passed to the constructor only log a warning for duplicate ids and dangling edges.
8
+ - Connection validators registered with `add_connection_validator()` run again on the final connection when the browser reports a new edge (`edge_added`), not only while dragging. A rejected edge is not added to `flow.edges`, no `edge_added` event fires, and the browser removes the edge it drew (`edge_rejected` message). The same happens when `add_edge()` raises for an edge from the browser. A browser edge whose id collides with an existing edge gets a fresh id instead.
9
+ - Exceptions raised by event callbacks registered with `flow.on()` and by `Node`/`Edge` hooks are logged on the `panel.reactflow` logger instead of propagating, and the remaining callbacks still run. Code that relied on a callback exception aborting `add_node()`, `remove_node()` and similar calls must check state explicitly.
10
+
11
+ ### Enhancements
12
+
13
+ - **Binary file drops**: binary files dropped onto the canvas, such as images or Parquet, now arrive with `bytes` content instead of being mangled by a text decode. Any file that decodes as UTF-8 still arrives as a `str`, whatever MIME type the operating system reports, so text handlers keep working ([#88](https://github.com/panel-extensions/panel-reactflow/pull/88)).
14
+ - **Drop size limit**: the new `max_drop_size` parameter (10 MB by default) caps the bytes sent for one drop so a large drop cannot exceed the websocket message limit and disconnect the session. Files over the limit or that cannot be read are listed in the drop event's `rejected` entries ([#88](https://github.com/panel-extensions/panel-reactflow/pull/88)).
15
+ - **Batch graph edits**: `add_nodes()` and `add_edges()` add many nodes or edges in a single update, validating all of them first, and emit one `node_added`/`edge_added` event per item ([#89](https://github.com/panel-extensions/panel-reactflow/pull/89)).
16
+ - **Faster structural updates**: adding, removing and assigning nodes and edges no longer re-renders every embedded view and editor, and node and edge editors are built only when shown (toolbar editors on first open, side panel and edge editors on selection) ([#89](https://github.com/panel-extensions/panel-reactflow/pull/89)).
17
+
18
+ ### Behavior changes
19
+
20
+ - Selection changes made in the browser no longer emit `node_props_changed`/`edge_props_changed` for `Node`/`Edge` instances (nor echo a `patch_*_props` message back to the browser); `selection_changed` and `on_selection_changed` still fire ([#89](https://github.com/panel-extensions/panel-reactflow/pull/89)).
21
+ - Cached editors are rebuilt when a node is replaced under the same id, its type changes or the type/editor configuration changes ([#89](https://github.com/panel-extensions/panel-reactflow/pull/89)).
22
+
23
+ ### Bug fixes
24
+
25
+ - **Schema editors**: forms are built for the schemas generated by `param` and `pydantic` (`$ref`, nullable `anyOf`, `const`, enums, `minimum`/`maximum`), a property without a dedicated widget is shown as a literal input instead of replacing the whole form, and nullable fields show and accept `None`. Building an editor no longer switches the global `pn.config.design` to `MaterialDesign`; import `panel_material_ui` first, or set `pn.config.design`, if your app relies on that. `jsonschema` is now a dependency, so node and edge data is always validated against its schema, and `panel-material-ui` is declared through the `material` extra ([#87](https://github.com/panel-extensions/panel-reactflow/pull/87)).
26
+
27
+ ## Version 0.5.1
28
+
29
+ A small enhancement release that lets the canvas accept files dragged in from the operating system.
30
+
31
+ ### Enhancements
32
+
33
+ - **Drop files onto the canvas**: add `"Files"` to `drop_types` to accept files dragged in from the operating system. The `drop` event's `data` lists each file's `name`, `type`, `size` and text `content`, so a handler can, for example, load a graph saved as JSON. See [React to Events](how-to/react-to-events.md#handle-drops-onto-the-canvas) ([#79](https://github.com/panel-extensions/panel-reactflow/pull/79)).
34
+
3
35
  ## Version 0.5.0
4
36
 
5
- This release adds port and edge value inspection and connection checks
6
- for interactive graph editing. `Node` and `Edge` properties now sync to
37
+ This release adds port and edge value inspection, connection checks
38
+ and canvas drops for interactive graph editing. `Node` and `Edge` properties now sync to
7
39
  the browser in place, batches of changes render as a single update, and
8
40
  an error boundary keeps a malformed graph from blanking the canvas.
9
41
 
@@ -26,7 +58,7 @@ an error boundary keeps a malformed graph from blanking the canvas.
26
58
  `examples/connection_validation.py`
27
59
  ([#75](https://github.com/panel-extensions/panel-reactflow/pull/75)).
28
60
 
29
- - **Error recovery** — the canvas is now wrapped in an error boundary,
61
+ - **Error recovery**: the canvas is now wrapped in an error boundary,
30
62
  controlled by the new `error_recovery` parameter (`"auto"` by default,
31
63
  or `"manual"` / `"off"`). In `"auto"` mode a React render error
32
64
  remounts the canvas, then remounts again in a view-only safe mode that
@@ -39,7 +71,7 @@ an error boundary keeps a malformed graph from blanking the canvas.
39
71
  to the server
40
72
  ([#70](https://github.com/panel-extensions/panel-reactflow/pull/70)).
41
73
 
42
- - **Base property sync** — the top-level React Flow fields on `Node` and
74
+ - **Base property sync**: the top-level React Flow fields on `Node` and
43
75
  `Edge` (`label`, `type`, `style`, `className`, `draggable`,
44
76
  `connectable`, `deletable`, ...) are now synced to the frontend, so
45
77
  assigning `node.label = "Start (running)"` patches the browser in place
@@ -55,7 +87,7 @@ an error boundary keeps a malformed graph from blanking the canvas.
55
87
 
56
88
  ### Enhancements
57
89
 
58
- - **Batch removal** — `remove_node()` and `remove_edge()` now accept
90
+ - **Batch removal**: `remove_node()` and `remove_edge()` now accept
59
91
  several ids, either as separate arguments
60
92
  (`flow.remove_node("n1", "n2")`) or as a sequence
61
93
  (`flow.remove_node(["n1", "n2"])`), and remove them in a single update.
@@ -63,9 +95,24 @@ an error boundary keeps a malformed graph from blanking the canvas.
63
95
  `pn.io.hold()` to render them at once
64
96
  ([#72](https://github.com/panel-extensions/panel-reactflow/pull/72)).
65
97
 
98
+ - **Drop data onto the canvas**: `drop_types` lists MIME types the canvas
99
+ accepts, and each drop of one of them emits a `drop` event with the
100
+ dropped data, its flow position, and the node or handle under the
101
+ pointer, so a handler can add and wire what was dropped. Draggable
102
+ `panel_material_ui.MenuList` items work as a source; see
103
+ [React to Events](how-to/react-to-events.md#handle-drops-onto-the-canvas)
104
+ ([#77](https://github.com/panel-extensions/panel-reactflow/pull/77)).
105
+
66
106
  ### Bug fixes
67
107
 
68
- - **Progressive re-render when deleting multiple elements** — deleting a
108
+ - **Nodes remounted when node types change**: any change to
109
+ `node_types` rebuilt the component for every node type, so React
110
+ remounted every node and detached its embedded view, which could leave
111
+ Bokeh plots blank. Each type's component is now reused until its own
112
+ spec or the popup settings change
113
+ ([#77](https://github.com/panel-extensions/panel-reactflow/pull/77)).
114
+
115
+ - **Progressive re-render when deleting multiple elements**: deleting a
69
116
  multi-node selection removed the nodes one at a time, syncing an
70
117
  intermediate graph to the browser per node so the nodes visibly
71
118
  disappeared one by one. Updates triggered by a frontend message are now
@@ -73,7 +120,7 @@ an error boundary keeps a malformed graph from blanking the canvas.
73
120
  `nodes` and `edges` once
74
121
  ([#72](https://github.com/panel-extensions/panel-reactflow/pull/72)).
75
122
 
76
- - **Serialization error when updating `node_types`** — assigning
123
+ - **Serialization error when updating `node_types`**: assigning
77
124
  `NodeType` or `EdgeType` descriptors with a `schema` class after
78
125
  construction synced them to the browser before they were converted to
79
126
  JSON descriptors, so the server failed with `can't serialize
@@ -0,0 +1,75 @@
1
+ """Drag items from a panel-material-ui MenuList onto the canvas to add nodes.
2
+
3
+ Dropping an item on empty canvas adds a node there; dropping it on a node's
4
+ input handle also connects the new node to that input.
5
+
6
+ Run from the repository root with:
7
+
8
+ PYTHONPATH=src pixi run panel serve examples/drop_from_menu.py --show
9
+ """
10
+
11
+ import panel as pn
12
+ import panel_material_ui as pmui
13
+
14
+ from panel_reactflow import NodeSpec, NodeType, ReactFlow
15
+
16
+ pn.extension()
17
+
18
+ PALETTE_ITEMS = [
19
+ {"label": "Sources", "draggable": False, "items": [
20
+ {"label": "CSV file", "icon": "description", "kind": "source"},
21
+ {"label": "Database", "icon": "storage", "kind": "source"},
22
+ ]},
23
+ {"label": "Transforms", "draggable": False, "items": [
24
+ {"label": "Filter", "icon": "filter_alt", "kind": "transform"},
25
+ ]},
26
+ ]
27
+
28
+
29
+ def lookup(items, path):
30
+ item = {"items": items}
31
+ for index in path:
32
+ item = item["items"][index]
33
+ return item
34
+
35
+
36
+ palette = pmui.MenuList(
37
+ items=PALETTE_ITEMS, draggable=True, expanded=[(0,), (1,)], width=220, label="Drag onto the canvas"
38
+ )
39
+
40
+ flow = ReactFlow(
41
+ nodes=[NodeSpec(id="sink", type="transform", label="Sink", position={"x": 400, "y": 150}).to_dict()],
42
+ node_types={
43
+ "source": NodeType(type="source", inputs=[], outputs=["out"]),
44
+ "transform": NodeType(type="transform", inputs=["in"], outputs=["out"]),
45
+ },
46
+ drop_types=[palette.drag_type],
47
+ # Keeps fitView from zooming in on the lone starting node, so nodes placed
48
+ # beside it stay on screen.
49
+ max_zoom=1,
50
+ sizing_mode="stretch_both",
51
+ min_height=500,
52
+ )
53
+
54
+
55
+ def on_drop(payload, flow):
56
+ item = lookup(palette.items, payload["data"]["path"])
57
+ node_id = f"{item['kind']}-{len(flow.nodes)}"
58
+ target = payload["target"]
59
+ wire = target is not None and target["direction"] == "input"
60
+ position = payload["position"]
61
+ if wire:
62
+ # Place the new node left of the input it feeds rather than on top of it.
63
+ target_node = next(n for n in flow.nodes if n["id"] == target["node_id"])
64
+ position = {"x": target_node["position"]["x"] - 320, "y": target_node["position"]["y"]}
65
+ flow.add_node(NodeSpec(id=node_id, type=item["kind"], label=item["label"], position=position).to_dict())
66
+ if wire:
67
+ flow.add_edge(
68
+ {"source": node_id, "sourceHandle": "out", "target": target["node_id"], "targetHandle": target["handle_id"]}
69
+ )
70
+
71
+
72
+ flow.on("drop", on_drop)
73
+
74
+ demo = pmui.Row(palette, flow, sizing_mode="stretch_both")
75
+ demo.servable()