jellyflow_runtime/runtime/xyflow/callbacks/
traits.rs

1use super::types::{
2    ConnectionChange, DeleteChange, EdgeConnection, NodeDragEnd, NodeDragStart, NodeDragUpdate,
3    NodeResizeEnd, NodeResizeStart, NodeResizeUpdate, SelectionChange, ViewportMove,
4    ViewportMoveEnd, ViewportMoveStart,
5};
6use crate::runtime::commit::NodeGraphPatch;
7use crate::runtime::xyflow::changes::{EdgeChange, NodeChange, NodeGraphChanges};
8use jellyflow_core::core::{CanvasPoint, EdgeId, GroupId, NodeId, StickyNoteId};
9use jellyflow_core::ops::EdgeEndpoints;
10
11/// Headless/store commit callbacks for B-layer consumers.
12///
13/// Use this layer for controlled graph synchronization, analytics, and transaction-driven
14/// integrations. `NodeGraphPatch` is the full-fidelity primary payload; node/edge changes are a
15/// lossy XyFlow-style projection.
16///
17/// Ordering guarantees (per `GraphCommitted` store event):
18///
19/// 1) `on_graph_commit`
20/// 2) `on_node_edge_changes`
21/// 3) `on_nodes_change` (if non-empty)
22/// 4) `on_edges_change` (if non-empty)
23/// 5) `on_connection_change` for each derived `ConnectionChange`
24/// 6) `on_connect`/`on_disconnect`/`on_reconnect` for each derived `ConnectionChange`
25/// 7) `on_nodes_delete` / `on_edges_delete` / `on_delete` for derived removals
26pub trait NodeGraphCommitCallbacks: 'static {
27    fn on_graph_commit(&mut self, _patch: &NodeGraphPatch) {}
28
29    fn on_node_edge_changes(&mut self, _changes: &NodeGraphChanges) {}
30
31    fn on_nodes_change(&mut self, _changes: &[NodeChange]) {}
32    fn on_edges_change(&mut self, _changes: &[EdgeChange]) {}
33
34    fn on_connection_change(&mut self, _change: ConnectionChange) {}
35
36    fn on_connect(&mut self, _conn: EdgeConnection) {}
37    fn on_disconnect(&mut self, _conn: EdgeConnection) {}
38    fn on_reconnect(&mut self, _edge: EdgeId, _from: EdgeEndpoints, _to: EdgeEndpoints) {}
39
40    /// ReactFlow-style delete hook (`onNodesDelete`).
41    fn on_nodes_delete(&mut self, _nodes: &[NodeId]) {}
42    /// ReactFlow-style delete hook (`onEdgesDelete`).
43    fn on_edges_delete(&mut self, _edges: &[EdgeId]) {}
44    /// Delete hook for group containers.
45    fn on_groups_delete(&mut self, _groups: &[GroupId]) {}
46    /// Delete hook for sticky notes.
47    fn on_sticky_notes_delete(&mut self, _notes: &[StickyNoteId]) {}
48    /// Combined delete hook (ReactFlow `onDelete`-like).
49    fn on_delete(&mut self, _change: DeleteChange) {}
50}
51
52/// Headless/store view callbacks for B-layer consumers.
53///
54/// Use this layer for app-owned viewport/selection synchronization. These hooks are derived from
55/// `ViewChange` and remain headless-safe.
56///
57/// Ordering guarantees (per `ViewChanged` store event):
58///
59/// 1) `on_view_change`
60/// 2) `on_viewport_change` / `on_selection_change` for each derived `ViewChange`
61pub trait NodeGraphViewCallbacks: 'static {
62    fn on_view_change(&mut self, _changes: &[crate::runtime::events::ViewChange]) {}
63
64    fn on_viewport_change(&mut self, _pan: CanvasPoint, _zoom: f32) {}
65    fn on_selection_change(&mut self, _sel: SelectionChange) {}
66}
67
68/// UI gesture lifecycle callbacks for retained/editor shells.
69///
70/// Use this layer for canvas-owned transient gesture observation. App-facing controlled
71/// integrations usually only need commit/view callbacks unless they intentionally react to
72/// pointer-driven lifecycle events.
73pub trait NodeGraphGestureCallbacks: 'static {
74    /// UI-driven hook: viewport pan/zoom gesture start (ReactFlow `onMoveStart`).
75    fn on_move_start(&mut self, _ev: ViewportMoveStart) {}
76    /// UI-driven hook: viewport pan/zoom gesture update (ReactFlow `onMove`).
77    fn on_move(&mut self, _ev: ViewportMove) {}
78    /// UI-driven hook: viewport pan/zoom gesture end (ReactFlow `onMoveEnd`).
79    fn on_move_end(&mut self, _ev: ViewportMoveEnd) {}
80
81    /// UI-driven hook: node drag gesture start (ReactFlow `onNodeDragStart`).
82    fn on_node_drag_start(&mut self, _ev: NodeDragStart) {}
83    /// UI-driven hook: node drag gesture end (ReactFlow `onNodeDragStop`).
84    fn on_node_drag_end(&mut self, _ev: NodeDragEnd) {}
85    /// UI-driven hook: node drag gesture move (ReactFlow `onNodeDrag`).
86    fn on_node_drag(&mut self, _ev: NodeDragUpdate) {}
87
88    /// UI-driven hook: node resize gesture start (XyFlow `onResizeStart`).
89    fn on_node_resize_start(&mut self, _ev: NodeResizeStart) {}
90    /// UI-driven hook: node resize gesture update (XyFlow `onResize`).
91    fn on_node_resize(&mut self, _ev: NodeResizeUpdate) {}
92    /// UI-driven hook: node resize gesture end (XyFlow `onResizeEnd`).
93    fn on_node_resize_end(&mut self, _ev: NodeResizeEnd) {}
94
95    /// UI-driven hook: called when a connection gesture starts (after drag threshold / click-to-connect).
96    fn on_connect_start(&mut self, _ev: crate::runtime::events::ConnectStart) {}
97    /// UI-driven hook: called when a connection gesture ends (commit/reject/cancel/picker).
98    fn on_connect_end(&mut self, _ev: crate::runtime::events::ConnectEnd) {}
99}
100
101/// Composite callback surface consumed by store/canvas adapters.
102///
103/// Prefer implementing the smallest concern traits:
104///
105/// - `NodeGraphCommitCallbacks` for committed graph patches,
106/// - `NodeGraphViewCallbacks` for viewport/selection synchronization,
107/// - `NodeGraphGestureCallbacks` for transient UI gesture lifecycle.
108///
109/// `NodeGraphCallbacks` itself is only the composition boundary used by `install_callbacks` and
110/// retained canvas wiring.
111pub trait NodeGraphCallbacks:
112    NodeGraphCommitCallbacks + NodeGraphViewCallbacks + NodeGraphGestureCallbacks
113{
114}
115
116impl<T> NodeGraphCallbacks for T where
117    T: NodeGraphCommitCallbacks + NodeGraphViewCallbacks + NodeGraphGestureCallbacks
118{
119}
jellyflow_runtime/runtime/xyflow/callbacks/traits.rs

jellyflow_runtime/runtime/xyflow/callbacks/
traits.rs
