panel-reactflow 0.4.0b1__tar.gz → 0.5.0__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 (102) hide show
  1. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.github/workflows/build.yml +5 -5
  2. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.github/workflows/docs.yml +6 -6
  3. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.github/workflows/test.yml +13 -13
  4. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/PKG-INFO +30 -2
  5. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/README.md +28 -0
  6. panel_reactflow-0.5.0/docs/how-to/declare-types.md +446 -0
  7. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/define-nodes-edges.md +53 -11
  8. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/react-to-events.md +33 -0
  9. panel_reactflow-0.5.0/docs/how-to/recover-from-errors.md +121 -0
  10. panel_reactflow-0.5.0/docs/how-to/validate-connections.md +82 -0
  11. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/index.md +1 -0
  12. panel_reactflow-0.5.0/docs/releases.md +252 -0
  13. panel_reactflow-0.5.0/examples/connection_validation.py +89 -0
  14. panel_reactflow-0.5.0/examples/drop_from_menu.py +75 -0
  15. panel_reactflow-0.5.0/examples/port_value_inspection.py +123 -0
  16. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/pixi.lock +8186 -6602
  17. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/pixi.toml +2 -2
  18. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/base.py +871 -217
  19. panel_reactflow-0.5.0/src/panel_reactflow/dist/css/reactflow.css +273 -0
  20. panel_reactflow-0.5.0/src/panel_reactflow/dist/panel-reactflow.bundle.css +1 -0
  21. panel_reactflow-0.5.0/src/panel_reactflow/dist/panel-reactflow.bundle.js +88 -0
  22. panel_reactflow-0.5.0/src/panel_reactflow/models/reactflow.jsx +1720 -0
  23. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/test_api.py +810 -0
  24. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/test_core.py +36 -4
  25. panel_reactflow-0.5.0/tests/test_error_recovery.py +128 -0
  26. panel_reactflow-0.5.0/tests/ui/test_error_recovery.py +161 -0
  27. panel_reactflow-0.5.0/tests/ui/test_ui.py +1244 -0
  28. panel_reactflow-0.5.0/tests/ui/test_value_popup.py +239 -0
  29. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/zensical.toml +3 -1
  30. panel_reactflow-0.4.0b1/docs/how-to/declare-types.md +0 -239
  31. panel_reactflow-0.4.0b1/docs/releases.md +0 -98
  32. panel_reactflow-0.4.0b1/src/panel_reactflow/dist/css/reactflow.css +0 -90
  33. panel_reactflow-0.4.0b1/src/panel_reactflow/dist/panel-reactflow.bundle.css +0 -1
  34. panel_reactflow-0.4.0b1/src/panel_reactflow/dist/panel-reactflow.bundle.js +0 -88
  35. panel_reactflow-0.4.0b1/src/panel_reactflow/models/reactflow.jsx +0 -776
  36. panel_reactflow-0.4.0b1/tests/ui/test_ui.py +0 -598
  37. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.copier-answers.yml +0 -0
  38. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.gitattributes +0 -0
  39. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.github/CODEOWNERS +0 -0
  40. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.github/dependabot.yml +0 -0
  41. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.gitignore +0 -0
  42. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.pre-commit-config.yaml +0 -0
  43. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/.prettierrc +0 -0
  44. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/LICENSE.txt +0 -0
  45. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/MANIFEST.in +0 -0
  46. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/logo.svg +0 -0
  47. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/declare-types.png +0 -0
  48. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/define-editors-edge.png +0 -0
  49. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/define-editors-node.png +0 -0
  50. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/define-nodes-edges.png +0 -0
  51. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/embed-views-in-nodes.png +0 -0
  52. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/advanced.png +0 -0
  53. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/custom_editor.png +0 -0
  54. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/edge_editors.png +0 -0
  55. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/node_edge_instances.png +0 -0
  56. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/schema_types.png +0 -0
  57. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/simple.png +0 -0
  58. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/threejs_viewer.png +0 -0
  59. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/examples/threejs_viewer_instances.png +0 -0
  60. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/quickstart.png +0 -0
  61. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/react-to-events.png +0 -0
  62. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/assets/screenshots/style-nodes-edges.png +0 -0
  63. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/advanced.md +0 -0
  64. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/custom-editor.md +0 -0
  65. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/edge-editors.md +0 -0
  66. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/index.md +0 -0
  67. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/node-edge-instances.md +0 -0
  68. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/schema-types.md +0 -0
  69. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/simple.md +0 -0
  70. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/threejs-viewer-instances.md +0 -0
  71. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/examples/threejs-viewer.md +0 -0
  72. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/context-menu.md +0 -0
  73. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/control-handle-connectivity.md +0 -0
  74. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/define-editors.md +0 -0
  75. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/embed-views-in-nodes.md +0 -0
  76. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/how-to/style-nodes-edges.md +0 -0
  77. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/quickstart.md +0 -0
  78. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/docs/reference/panel_reactflow.md +0 -0
  79. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/advanced.py +0 -0
  80. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/context_menu.py +0 -0
  81. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/custom_editor.py +0 -0
  82. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/edge_editors.py +0 -0
  83. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/edge_types_comparison.py +0 -0
  84. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/node_edge_instances.py +0 -0
  85. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/schema_types.py +0 -0
  86. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/simple.py +0 -0
  87. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/smart_edges_example.py +0 -0
  88. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/threejs_viewer.py +0 -0
  89. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/examples/threejs_viewer_instances.py +0 -0
  90. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/hatch_build.py +0 -0
  91. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/pyproject.toml +0 -0
  92. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/__init__.py +0 -0
  93. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/__version.py +0 -0
  94. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/dist/icons/gear.svg +0 -0
  95. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/py.typed +0 -0
  96. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/src/panel_reactflow/schema.py +0 -0
  97. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/__init__.py +0 -0
  98. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/conftest.py +0 -0
  99. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/test_connectable_handles.py +0 -0
  100. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/test_connectable_integration.py +0 -0
  101. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/ui/__init__.py +0 -0
  102. {panel_reactflow-0.4.0b1 → panel_reactflow-0.5.0}/tests/ui/test_context_menu.py +0 -0
@@ -11,11 +11,11 @@ jobs:
11
11
  build:
12
12
  runs-on: ubuntu-latest
13
13
  steps:
14
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
14
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
15
15
  with:
16
16
  fetch-depth: 0
17
17
  - name: Set up pixi
18
- uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
18
+ uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
19
19
  with:
20
20
  environments: build
21
21
  - name: Build project
@@ -23,7 +23,7 @@ jobs:
23
23
  - name: Check package
24
24
  run: pixi run -e build check-wheel
25
25
  - name: Upload package
26
- uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
26
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
27
27
  with:
28
28
  name: artifact
29
29
  path: dist/*
@@ -37,9 +37,9 @@ jobs:
37
37
  id-token: write
38
38
  environment: pypi
39
39
  steps:
40
- - uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8.0.0
40
+ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
41
41
  with:
42
42
  name: artifact
43
43
  path: dist
44
44
  - name: Publish package on PyPi
45
- uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
45
+ uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
@@ -43,23 +43,23 @@ jobs:
43
43
  runs-on: ubuntu-latest
44
44
 
45
45
  steps:
46
- - uses: actions/checkout@v6
46
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
47
47
  with:
48
48
  fetch-depth: 0
49
49
  - name: Set up Pixi
50
- uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
50
+ uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
51
51
  with:
52
52
  environments: docs
53
53
  - name: Build documentation
54
54
  run: pixi run -e docs docs-build
55
- - uses: actions/upload-artifact@v7
55
+ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
56
56
  if: always()
57
57
  with:
58
58
  name: docs
59
59
  if-no-files-found: error
60
60
  path: builtdocs
61
61
  - name: Upload artifact
62
- uses: actions/upload-pages-artifact@v4
62
+ uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
63
63
  with:
64
64
  path: ./builtdocs
65
65
 
@@ -71,7 +71,7 @@ jobs:
71
71
  needs: build
72
72
  steps:
73
73
  - name: Deploy dev
74
- uses: peaceiris/actions-gh-pages@v4
74
+ uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
75
75
  # Dev site built on PRs
76
76
  if: |
77
77
  (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
@@ -88,4 +88,4 @@ jobs:
88
88
  ((github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'main') ||
89
89
  (github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc'))))
90
90
  id: deployment
91
- uses: actions/deploy-pages@v4
91
+ uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
@@ -20,10 +20,10 @@ jobs:
20
20
  code_change: ${{ steps.filter.outputs.code }}
21
21
  matrix: ${{ env.MATRIX }}
22
22
  steps:
23
- - uses: actions/checkout@v6
23
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
24
24
  if: github.event_name != 'pull_request'
25
25
  - name: Check for code changes
26
- uses: dorny/paths-filter@v3
26
+ uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
27
27
  id: filter
28
28
  with:
29
29
  filters: |
@@ -72,7 +72,7 @@ jobs:
72
72
  name: Pixi lock
73
73
  runs-on: ubuntu-latest
74
74
  steps:
75
- - uses: holoviz-dev/holoviz_tasks/pixi_lock@v0
75
+ - uses: holoviz-dev/holoviz_tasks/pixi-lock@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
76
76
  with:
77
77
  cache: ${{ github.event.inputs.cache == 'true' || github.event.inputs.cache == '' }}
78
78
 
@@ -80,15 +80,15 @@ jobs:
80
80
  needs: [setup, pixi_lock]
81
81
  runs-on: "ubuntu-latest"
82
82
  steps:
83
- - uses: actions/checkout@v6
83
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
84
84
  - name: Set up pixi
85
- uses: prefix-dev/setup-pixi@v0.9.4
86
- - uses: holoviz-dev/holoviz_tasks/pre-commit@v0
87
- - uses: pre-commit/action@v3.0.1
85
+ uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
86
+ - uses: holoviz-dev/holoviz_tasks/pre-commit@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
87
+ - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
88
88
  if: needs.setup.outputs.img_change == 'true'
89
89
  with:
90
90
  extra_args: -a --hook-stage manual oxipng || true --
91
- - uses: stefanzweifel/git-auto-commit-action@v7
91
+ - uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0
92
92
  if: needs.setup.outputs.img_change == 'true'
93
93
  with:
94
94
  commit_message: "Optimize PNG images (lossless)"
@@ -111,11 +111,11 @@ jobs:
111
111
  - windows-latest
112
112
  steps:
113
113
  - name: Checkout branch
114
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
114
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
115
115
  with:
116
116
  fetch-depth: 0
117
117
  - name: Set up pixi
118
- uses: prefix-dev/setup-pixi@a0af7a228712d6121d37aba47adf55c1332c9c2e # v0.9.4
118
+ uses: prefix-dev/setup-pixi@d3f436a425481402e6a95a1d1fc10331c708cd9e # v0.10.2
119
119
  with:
120
120
  environments: ${{ matrix.environment }}
121
121
  - name: Install repository
@@ -139,7 +139,7 @@ jobs:
139
139
  PANEL_LOG_LEVEL: info
140
140
  FAIL: "--screenshot only-on-failure --full-page-screenshot --output ui_screenshots --tracing retain-on-failure"
141
141
  steps:
142
- - uses: holoviz-dev/holoviz_tasks/pixi_install@v0
142
+ - uses: holoviz-dev/holoviz_tasks/pixi-install@8fb2d0a3e4c70e218d487e0eed3b9c2488997212 # v1.0.6
143
143
  with:
144
144
  environments: ${{ matrix.environment }}
145
145
  install: false
@@ -151,14 +151,14 @@ jobs:
151
151
  echo "[run]\nconcurrency = greenlet" > .uicoveragerc
152
152
  pixi run -e ${{ matrix.environment }} test-ui $COV --cov-config=.uicoveragerc $FAIL
153
153
  - name: Upload UI Screenshots
154
- uses: actions/upload-artifact@v7
154
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
155
155
  if: always()
156
156
  with:
157
157
  name: ui_screenshots_${{ runner.os }}
158
158
  path: ./ui_screenshots
159
159
  if-no-files-found: ignore
160
160
  - name: Upload coverage reports to Codecov
161
- uses: codecov/codecov-action@v5
161
+ uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
162
162
  with:
163
163
  token: ${{ secrets.CODECOV_TOKEN }}
164
164
  slug: panel-extensions/panel-splitjs
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: panel-reactflow
3
- Version: 0.4.0b1
3
+ Version: 0.5.0
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
@@ -114,6 +114,34 @@ flow
114
114
 
115
115
  For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`. `.on` callbacks receive the event payload as the first argument and can optionally accept the `ReactFlow` instance as a second argument.
116
116
 
117
+ ## Connection validation
118
+
119
+ Connection checks are opt-in. For frontend-only validation, set `connection_validation` with any of `direction`, `types`, `capacity`, `duplicates`, or `cycles` set to `True`. `types` compares declared handle types case-insensitively and permits unknown types; `capacity` uses `maxConnections` on input handle dictionaries, with no limit when omitted. Existing handle connectability flags still apply.
120
+
121
+ ```python
122
+ from panel_reactflow import NodeType, ReactFlow
123
+
124
+ flow = ReactFlow(
125
+ node_types={
126
+ "source": NodeType(type="source", outputs=[{"id": "value", "type": "str"}]),
127
+ "sink": NodeType(type="sink", inputs=[{"id": "value", "type": "str", "maxConnections": 1}]),
128
+ },
129
+ connection_validation={"direction": True, "types": True, "capacity": True, "cycles": True},
130
+ )
131
+ ```
132
+
133
+ For application rules, register a Python validator. On each drag start, ReactFlow requests results for every candidate port and shows the returned reasons while dragging. The callback receives an edge-shaped payload with `source`, `target`, `sourceHandle`, and `targetHandle`; return `None` to allow or a string to reject. Hooks and frontend checks can be used together. Validate again in your `edge_added` handler before accepting the connection, since the graph may have changed after drag start.
134
+
135
+ ```python
136
+ def validate_connection(edge, flow):
137
+ if edge["source"] == edge["target"]:
138
+ return "A node cannot connect to itself."
139
+
140
+ flow.add_connection_validator(validate_connection)
141
+ ```
142
+
143
+ Run the [connection validation demo](examples/connection_validation.py) with `PYTHONPATH=src pixi run panel serve examples/connection_validation.py --show` from the repository root.
144
+
117
145
  ## Development
118
146
 
119
147
  ```bash
@@ -71,6 +71,34 @@ flow
71
71
 
72
72
  For property schemas and richer editors, provide `node_types`/`edge_types` with `PropertySpec` and handle changes via `ReactFlow.on(...)`. `.on` callbacks receive the event payload as the first argument and can optionally accept the `ReactFlow` instance as a second argument.
73
73
 
74
+ ## Connection validation
75
+
76
+ Connection checks are opt-in. For frontend-only validation, set `connection_validation` with any of `direction`, `types`, `capacity`, `duplicates`, or `cycles` set to `True`. `types` compares declared handle types case-insensitively and permits unknown types; `capacity` uses `maxConnections` on input handle dictionaries, with no limit when omitted. Existing handle connectability flags still apply.
77
+
78
+ ```python
79
+ from panel_reactflow import NodeType, ReactFlow
80
+
81
+ flow = ReactFlow(
82
+ node_types={
83
+ "source": NodeType(type="source", outputs=[{"id": "value", "type": "str"}]),
84
+ "sink": NodeType(type="sink", inputs=[{"id": "value", "type": "str", "maxConnections": 1}]),
85
+ },
86
+ connection_validation={"direction": True, "types": True, "capacity": True, "cycles": True},
87
+ )
88
+ ```
89
+
90
+ For application rules, register a Python validator. On each drag start, ReactFlow requests results for every candidate port and shows the returned reasons while dragging. The callback receives an edge-shaped payload with `source`, `target`, `sourceHandle`, and `targetHandle`; return `None` to allow or a string to reject. Hooks and frontend checks can be used together. Validate again in your `edge_added` handler before accepting the connection, since the graph may have changed after drag start.
91
+
92
+ ```python
93
+ def validate_connection(edge, flow):
94
+ if edge["source"] == edge["target"]:
95
+ return "A node cannot connect to itself."
96
+
97
+ flow.add_connection_validator(validate_connection)
98
+ ```
99
+
100
+ Run the [connection validation demo](examples/connection_validation.py) with `PYTHONPATH=src pixi run panel serve examples/connection_validation.py --show` from the repository root.
101
+
74
102
  ## Development
75
103
 
76
104
  ```bash
@@ -0,0 +1,446 @@
1
+ # Declare Node & Edge Types
2
+
3
+ Node and edge types are lightweight descriptors that define **what data each
4
+ kind of node/edge carries**. A type can provide:
5
+
6
+ - a type name (`type`)
7
+ - a display label (`label`)
8
+ - node handles (`inputs` / `outputs`)
9
+ - handle connectivity controls (`input_connectable*` / `output_connectable*`)
10
+ - a schema for the `data` payload (`schema`)
11
+
12
+ Types are separate from editors. A type defines structure; an editor defines
13
+ the UI used to edit it.
14
+
15
+ ![Screenshot: multiple node types with different schemas](../assets/screenshots/declare-types.png)
16
+
17
+ ---
18
+
19
+ ## Complete runnable example
20
+
21
+ This script is a minimal, working example that produces the visualization
22
+ shown above.
23
+
24
+ ```python
25
+ import param
26
+ import panel as pn
27
+
28
+ from panel_reactflow import EdgeType, NodeType, ReactFlow
29
+
30
+ pn.extension("jsoneditor")
31
+
32
+
33
+ class Job(param.Parameterized):
34
+ status = param.Selector(objects=["idle", "running", "done"])
35
+ retries = param.Integer(default=0)
36
+
37
+
38
+ decision_schema = {
39
+ "type": "object",
40
+ "properties": {
41
+ "question": {"type": "string", "title": "Question"},
42
+ "outcome": {
43
+ "type": "string",
44
+ "enum": ["yes", "no", "maybe"],
45
+ "title": "Outcome",
46
+ },
47
+ },
48
+ }
49
+
50
+ node_types = {
51
+ "job": NodeType(type="job", label="Job", schema=Job, inputs=["in"], outputs=["out"]),
52
+ "decision": NodeType(
53
+ type="decision",
54
+ label="Decision",
55
+ schema=decision_schema,
56
+ inputs=["in"],
57
+ outputs=["yes", "no"],
58
+ ),
59
+ }
60
+
61
+ edge_types = {
62
+ "flow": EdgeType(
63
+ type="flow",
64
+ label="Flow",
65
+ schema={
66
+ "type": "object",
67
+ "properties": {"weight": {"type": "number", "title": "Weight"}},
68
+ },
69
+ ),
70
+ }
71
+
72
+ nodes = [
73
+ {
74
+ "id": "j1",
75
+ "type": "job",
76
+ "label": "Fetch Data",
77
+ "position": {"x": 0, "y": 0},
78
+ "data": {"status": "idle", "retries": 0},
79
+ },
80
+ {
81
+ "id": "d1",
82
+ "type": "decision",
83
+ "label": "Valid?",
84
+ "position": {"x": 300, "y": 250},
85
+ "data": {"question": "Is data valid?", "outcome": "yes"},
86
+ },
87
+ {
88
+ "id": "j2",
89
+ "type": "job",
90
+ "label": "Process",
91
+ "position": {"x": 600, "y": 400},
92
+ "data": {"status": "running", "retries": 1},
93
+ },
94
+ ]
95
+
96
+ edges = [
97
+ {"id": "e1", "source": "j1", "target": "d1", "type": "flow", "data": {"weight": 1.0}},
98
+ {"id": "e2", "source": "d1", "target": "j2", "type": "flow", "data": {"weight": 0.8}},
99
+ ]
100
+
101
+ TASK_NODE_CSS = """
102
+ .react-flow__node-job {
103
+ background-color: white;
104
+ border-radius: 8px;
105
+ border: 1.5px solid #7c3aed;
106
+ }
107
+
108
+ .react-flow__node-decision {
109
+ background-color: white;
110
+ border-radius: 8px;
111
+ border: 1.5px solid green;
112
+ }
113
+ """
114
+
115
+ flow = ReactFlow(
116
+ nodes=nodes,
117
+ edges=edges,
118
+ node_types=node_types,
119
+ edge_types=edge_types,
120
+ editor_mode="node",
121
+ sizing_mode="stretch_both",
122
+ stylesheets=[TASK_NODE_CSS]
123
+ )
124
+
125
+ pn.Column(flow, sizing_mode="stretch_both").servable()
126
+ ```
127
+
128
+ ## How this code maps to the visualization
129
+
130
+ - `node_types["job"]` and `node_types["decision"]` define the two node kinds you see.
131
+ - `inputs` and `outputs` define the left/right handles rendered on each node.
132
+ - `edge_types["flow"]` defines the edge payload schema used by both connections.
133
+ - `nodes` controls labels (`Fetch Data`, `Valid?`, `Process`) and positions.
134
+ - `editor_mode="side"` makes selection open the schema-driven editor in the right panel.
135
+
136
+ ---
137
+
138
+ ## Node type snippet
139
+
140
+ Use `NodeType` to define node handles and payload schema.
141
+
142
+ ```python
143
+ from panel_reactflow import NodeType
144
+
145
+ task_schema = {
146
+ "type": "object",
147
+ "properties": {
148
+ "status": {"type": "string", "enum": ["idle", "running", "done"]},
149
+ "priority": {"type": "integer"},
150
+ },
151
+ }
152
+
153
+ node_types = {
154
+ "task": NodeType(
155
+ type="task",
156
+ label="Task",
157
+ schema=task_schema,
158
+ inputs=["in"],
159
+ outputs=["out"],
160
+ ),
161
+ }
162
+ ```
163
+
164
+ ## Edge type snippet
165
+
166
+ Use `EdgeType` for edge payload schema and label.
167
+
168
+ ```python
169
+ from panel_reactflow import EdgeType
170
+
171
+ edge_types = {
172
+ "pipe": EdgeType(
173
+ type="pipe",
174
+ label="Pipe",
175
+ schema={
176
+ "type": "object",
177
+ "properties": {
178
+ "throughput": {"type": "number"},
179
+ "protocol": {"type": "string", "enum": ["tcp", "udp", "http"]},
180
+ },
181
+ },
182
+ ),
183
+ }
184
+ ```
185
+
186
+ ---
187
+
188
+ ## Schema sources
189
+
190
+ The `schema` field accepts multiple inputs and normalizes them to JSON Schema.
191
+
192
+ | Source | Example |
193
+ |--------|---------|
194
+ | **JSON Schema dict** | `{"type": "object", "properties": {...}}` |
195
+ | **Param class** | A `param.Parameterized` subclass |
196
+ | **Pydantic model** | A `pydantic.BaseModel` subclass |
197
+
198
+ ### Param class shorthand
199
+
200
+ ```python
201
+ import param
202
+ from panel_reactflow import NodeType
203
+
204
+ class Job(param.Parameterized):
205
+ status = param.Selector(objects=["idle", "running", "done"])
206
+ retries = param.Integer(default=0)
207
+
208
+ node_types = {"job": NodeType(type="job", label="Job", schema=Job)}
209
+ ```
210
+
211
+ ### Pydantic model shorthand
212
+
213
+ ```python
214
+ from pydantic import BaseModel
215
+ from panel_reactflow import NodeType
216
+
217
+ class Config(BaseModel):
218
+ host: str = "localhost"
219
+ port: int = 8080
220
+
221
+ node_types = {"config": NodeType(type="config", label="Config", schema=Config)}
222
+ ```
223
+
224
+ ---
225
+
226
+ ## Register on `ReactFlow`
227
+
228
+ Pass `node_types` and `edge_types` as dictionaries keyed by type name:
229
+
230
+ ```python
231
+ flow = ReactFlow(
232
+ nodes=nodes,
233
+ edges=edges,
234
+ node_types=node_types,
235
+ edge_types=edge_types,
236
+ )
237
+ ```
238
+
239
+ Types without a schema still work; they just do not get schema-driven
240
+ validation or auto-generated forms.
241
+
242
+ ---
243
+
244
+ ## Handle tooltips
245
+
246
+ By default, handles are plain connection points. You can add a tooltip (shown
247
+ on hover) by passing a dict with `"id"` and `"label"` and/or `"type"` instead
248
+ of a plain string:
249
+
250
+ ```python
251
+ from panel_reactflow import NodeType
252
+
253
+ node_types = {
254
+ "transform": NodeType(
255
+ type="transform",
256
+ label="Transform",
257
+ inputs=[{"id": "in", "label": "Data Input", "type": "DataFrame"}],
258
+ outputs=[
259
+ {"id": "success", "label": "Successful results", "type": "DataFrame"},
260
+ {"id": "error", "label": "Failed records", "type": "list"},
261
+ ],
262
+ ),
263
+ }
264
+ ```
265
+
266
+ The tooltip combines both when present (`"Data Input (DataFrame)"`), or falls
267
+ back to whichever one is given. Plain strings and dicts can be mixed freely in
268
+ the same list:
269
+
270
+ ```python
271
+ inputs=["simple_port", {"id": "documented_port", "label": "Hover to see this", "type": "int"}]
272
+ ```
273
+
274
+ ---
275
+
276
+ ## Show a port's current value on click
277
+
278
+ Clicking a handle emits a `"handle_clicked"` event with the node id, handle
279
+ id, direction (`"input"`/`"output"`) and a screen position. Clicking an edge
280
+ emits `"edge_clicked"` with the edge id and position. Use
281
+ `ReactFlow.show_popup(content, position)` in the handler to display whatever
282
+ you consider the "current value" for that port or connection:
283
+
284
+ ```python
285
+ def on_handle_clicked(payload, flow):
286
+ node_id, handle_id = payload["node_id"], payload["handle_id"]
287
+ value = live_values.get(node_id, {}).get(handle_id)
288
+ flow.show_popup(pn.pane.Markdown(f"**{handle_id}**: {value!r}"), payload["position"])
289
+
290
+ def on_edge_clicked(payload, flow):
291
+ source_id, source_port = edge_sources[payload["edge_id"]]
292
+ value = live_values.get(source_id, {}).get(source_port)
293
+ flow.show_popup(pn.pane.Markdown(f"**Value:** {value!r}"), payload["position"])
294
+
295
+ flow.on("handle_clicked", on_handle_clicked)
296
+ flow.on("edge_clicked", on_edge_clicked)
297
+ ```
298
+
299
+ For `popup_trigger="hover"`, register `handle_hovered` and `edge_hovered` to
300
+ show the popup and their corresponding `handle_unhovered` and `edge_unhovered`
301
+ events to call `flow.close_popup()`. Match the unhovered target against the
302
+ currently displayed one so a delayed leave event does not dismiss a newer
303
+ popup. See the runnable example below for both pairs of callbacks.
304
+
305
+ The default `popup_hover_delay` is 500 ms. After opening, an unhover event is
306
+ emitted when the pointer moves more than 10% of the shorter canvas dimension
307
+ from the anchor (at least 48 pixels) and is not over the popup. Click-opened
308
+ popups dismiss on outside click; either mode can dismiss programmatically via
309
+ `flow.close_popup()`. Use
310
+ `popup_trigger="none"` to disable the built-in inspection events.
311
+ `panel-reactflow` only provides the interaction events and overlay; looking up
312
+ "the current value" for a port is application-specific.
313
+
314
+ For a complete runnable graph with typed port hover tooltips and popups for
315
+ both handles and edges, run:
316
+
317
+ ```bash
318
+ panel serve examples/port_value_inspection.py --show
319
+ ```
320
+
321
+ ---
322
+
323
+ ## Control handle connectivity
324
+
325
+ By default, all handles (inputs and outputs) are fully connectable — users can
326
+ drag edges from or to any handle. Use the `*_connectable*` flags to restrict
327
+ which connections are allowed.
328
+
329
+ ### Common patterns
330
+
331
+ #### Data source (output only)
332
+
333
+ A node that produces data but cannot accept incoming connections to its output:
334
+
335
+ ```python
336
+ from panel_reactflow import NodeType
337
+
338
+ source_type = NodeType(
339
+ type="data_source",
340
+ label="Data Source",
341
+ outputs=["data"],
342
+ output_connectable_start=True, # Can drag FROM output
343
+ output_connectable_end=False, # Cannot drag TO output
344
+ )
345
+ ```
346
+
347
+ #### Data sink (input only)
348
+
349
+ A node that consumes data but cannot produce outgoing connections from its input:
350
+
351
+ ```python
352
+ sink_type = NodeType(
353
+ type="data_sink",
354
+ label="Data Sink",
355
+ inputs=["data"],
356
+ input_connectable_start=False, # Cannot drag FROM input
357
+ input_connectable_end=True, # Can drag TO input
358
+ )
359
+ ```
360
+
361
+ #### Monitor node
362
+
363
+ A node that accepts input but whose output is status-only (one direction):
364
+
365
+ ```python
366
+ monitor_type = NodeType(
367
+ type="monitor",
368
+ label="Monitor",
369
+ inputs=["in"],
370
+ outputs=["status"],
371
+ input_connectable_start=False, # Cannot start edges from input
372
+ output_connectable_end=False, # Cannot end edges at output
373
+ )
374
+ ```
375
+
376
+ ### All connectivity flags
377
+
378
+ | Flag | Default | Controls |
379
+ |------|---------|----------|
380
+ | `input_connectable` | `True` | Whether input handles are connectable at all |
381
+ | `input_connectable_start` | `True` | Whether edges can start from input handles |
382
+ | `input_connectable_end` | `True` | Whether edges can end at input handles |
383
+ | `output_connectable` | `True` | Whether output handles are connectable at all |
384
+ | `output_connectable_start` | `True` | Whether edges can start from output handles |
385
+ | `output_connectable_end` | `True` | Whether edges can end at output handles |
386
+
387
+ ### Complete example
388
+
389
+ ```python
390
+ import panel as pn
391
+ from panel_reactflow import NodeType, NodeSpec, EdgeSpec, ReactFlow
392
+
393
+ pn.extension("jsoneditor")
394
+
395
+ # Define node types with different connectivity patterns
396
+ node_types = {
397
+ "source": NodeType(
398
+ type="source",
399
+ label="Data Source",
400
+ outputs=["data"],
401
+ output_connectable_start=True,
402
+ output_connectable_end=False,
403
+ ),
404
+ "transform": NodeType(
405
+ type="transform",
406
+ label="Transform",
407
+ inputs=["in"],
408
+ outputs=["out"],
409
+ # All connectable flags default to True
410
+ ),
411
+ "sink": NodeType(
412
+ type="sink",
413
+ label="Data Sink",
414
+ inputs=["data"],
415
+ input_connectable_start=False,
416
+ input_connectable_end=True,
417
+ ),
418
+ }
419
+
420
+ # Create a data pipeline
421
+ flow = ReactFlow(
422
+ nodes=[
423
+ NodeSpec(id="src", type="source", position={"x": 0, "y": 100}, data={}).to_dict(),
424
+ NodeSpec(id="tx", type="transform", position={"x": 250, "y": 100}, data={}).to_dict(),
425
+ NodeSpec(id="snk", type="sink", position={"x": 500, "y": 100}, data={}).to_dict(),
426
+ ],
427
+ edges=[
428
+ EdgeSpec(id="e1", source="src", target="tx").to_dict(),
429
+ EdgeSpec(id="e2", source="tx", target="snk").to_dict(),
430
+ ],
431
+ node_types=node_types,
432
+ sizing_mode="stretch_both",
433
+ )
434
+
435
+ flow.servable()
436
+ ```
437
+
438
+ In this example:
439
+
440
+ - Users can drag from the **source** output to the **transform** input ✓
441
+ - Users cannot drag to the **source** output ✗
442
+ - Users can drag from the **transform** output to the **sink** input ✓
443
+ - Users cannot drag from the **sink** input ✗
444
+
445
+ The UI prevents invalid connections automatically — non-connectable handles
446
+ show different cursor behavior and won't accept drag operations.