Skip to main content

leptos_node_graph/
editor.rs

1use std::collections::HashMap;
2use std::marker::PhantomData;
3
4use leptos::prelude::*;
5use leptos_use::{UseElementSizeReturn, use_debounce_fn, use_element_size, use_event_listener};
6
7use crate::connection::ConnectionRenderer;
8use crate::group::GroupBoxOverlay;
9use crate::interaction;
10use crate::menu::{DraftContext, NodeMenu, NodeMenuEvent, NodeMenuItem};
11use crate::registry::{ConnectionEntry, EditorRegistry};
12use crate::selection::SelectionBox;
13use crate::types::*;
14
15/// A consumer-side handle to a [`NodeEditor`] instance.
16///
17/// The editor provides its registry via context, which flows DOWN — so a handler
18/// mounted on an ancestor of the editor (an HTML5 drop target wrapping the graph,
19/// a toolbar, a sibling pane) has no way to reach the live pan/zoom transform.
20/// Construct a handle, pass it to [`NodeEditor`], and it works from anywhere:
21///
22/// ```ignore
23/// let handle = EditorHandle::new();
24/// view! {
25///     <div
26///         on:dragover=|ev: web_sys::DragEvent| ev.prevent_default()
27///         on:drop=move |ev: web_sys::DragEvent| {
28///             ev.prevent_default();
29///             if let Some(pos) = handle.client_to_canvas(ev.client_x() as f64, ev.client_y() as f64) {
30///                 // `pos` is in canvas space, correct under any pan/zoom.
31///             }
32///         }
33///     >
34///         <NodeEditor handle=handle ...>...</NodeEditor>
35///     </div>
36/// }
37/// ```
38///
39/// Prefer this over reading the canvas element's CSS transform: the class names
40/// and the transform's representation are internal and may change, whereas this
41/// is the supported surface.
42#[derive(Clone, Copy, Debug)]
43pub struct EditorHandle {
44    viewport: RwSignal<ViewportTransform>,
45    container: NodeRef<leptos::html::Div>,
46}
47
48impl Default for EditorHandle {
49    fn default() -> Self {
50        Self::new()
51    }
52}
53
54impl EditorHandle {
55    pub fn new() -> Self {
56        Self {
57            viewport: RwSignal::new(ViewportTransform::default()),
58            container: NodeRef::new(),
59        }
60    }
61
62    /// The editor's live pan/zoom transform. Reading this in a reactive context
63    /// subscribes to it, so it also drives consumer-side minimaps, zoom readouts
64    /// and "frame the graph" controls.
65    ///
66    /// When this handle is passed to a [`NodeEditor`], the editor uses THIS
67    /// signal as its own — writing to it pans/zooms the graph.
68    pub fn viewport(&self) -> RwSignal<ViewportTransform> {
69        self.viewport
70    }
71
72    /// The editor's container element, once mounted.
73    pub fn container(&self) -> NodeRef<leptos::html::Div> {
74        self.container
75    }
76
77    /// Convert viewport client coordinates — `MouseEvent`/`DragEvent` `client_x`
78    /// and `client_y` — into canvas coordinates.
79    ///
80    /// This subtracts the container's own offset before applying the transform,
81    /// which is the step that's easy to miss: any padding, border or chrome
82    /// between the event's target and the editor's container shifts the result,
83    /// and the error only shows up once the layout gains that spacing.
84    ///
85    /// `None` before the editor has mounted. Reads are untracked, so this is safe
86    /// to call from event handlers without creating a subscription.
87    pub fn client_to_canvas(&self, client_x: f64, client_y: f64) -> Option<Position> {
88        let el = self.container.get_untracked()?;
89        let rect = el.get_bounding_client_rect();
90        Some(
91            self.viewport
92                .get_untracked()
93                .screen_to_canvas(Position::new(client_x - rect.left(), client_y - rect.top())),
94        )
95    }
96
97    /// Inverse of [`Self::client_to_canvas`]: canvas coordinates to viewport
98    /// client coordinates, for placing consumer-owned DOM over a graph position.
99    pub fn canvas_to_client(&self, canvas: Position) -> Option<Position> {
100        let el = self.container.get_untracked()?;
101        let rect = el.get_bounding_client_rect();
102        let s = self.viewport.get_untracked().canvas_to_screen(canvas);
103        Some(Position::new(s.x + rect.left(), s.y + rect.top()))
104    }
105}
106
107#[component]
108pub fn NodeEditor<N, P, C, T>(
109    #[prop(into)] config: EditorConfig,
110    #[prop(into)] connections: Signal<HashMap<C, ConnectionEntry<P, C>>>,
111    on_event: Callback<GraphEvent<N, P, C>>,
112    #[prop(optional)] _marker: PhantomData<T>,
113    /// Optional node catalog for the creation menu.
114    /// If provided, Tab/double-click opens a searchable menu.
115    /// Consumer filters this list reactively based on `menu_search`.
116    #[prop(optional, into)]
117    menu_items: Option<Signal<Vec<NodeMenuItem>>>,
118    /// Two-way search text for the menu. Consumer reads this to filter menu_items.
119    #[prop(optional)]
120    menu_search: Option<RwSignal<String>>,
121    /// Optional groups to render as visual overlays behind nodes.
122    #[prop(optional, into)]
123    groups: Option<Signal<Vec<crate::group::GroupBox<N>>>>,
124    /// Callback for group events (rename, add/remove node).
125    #[prop(optional, into)]
126    on_group_event: Option<Callback<crate::group::GroupEvent<N>>>,
127    /// Optional callback for the group header's ungroup action.
128    #[prop(optional, into)]
129    on_ungroup: Option<Callback<String>>,
130    /// Optional callback for the group header's select-all action.
131    #[prop(optional, into)]
132    on_select_all: Option<Callback<Vec<N>>>,
133    /// Optional consumer-owned handle. Gives code OUTSIDE the editor — a wrapping
134    /// drop target, a toolbar, a minimap — access to the live viewport and to
135    /// client/canvas coordinate conversion. See [`EditorHandle`].
136    #[prop(optional)]
137    handle: Option<EditorHandle>,
138    children: Children,
139) -> impl IntoView
140where
141    N: NodeId,
142    P: PortId,
143    C: ConnectionId,
144    T: PortType,
145{
146    // A handle owns the viewport signal and the container ref outright, rather
147    // than being kept in sync with internal copies — two-way mirroring of a
148    // signal that both sides write is a feedback loop waiting to happen.
149    let mut registry = EditorRegistry::<N, P, C, T>::new(config, on_event);
150    if let Some(h) = handle {
151        registry.viewport = h.viewport;
152    }
153    provide_context(registry.clone());
154
155    let container_ref = handle.map(|h| h.container).unwrap_or_default();
156
157    // Measure the container so each node can compute whether it's within the
158    // visible viewport (used to cull the expensive live content of off-screen
159    // nodes while keeping them mounted — their ports stay registered so wires
160    // are unaffected).
161    // Measured from the DOM on mount, with the observer driving later changes.
162    // The observer's first callback only arrives a frame after mount (and not at
163    // all while the tab is hidden and the browser throttles it), which would
164    // otherwise leave framing (`F`) and viewport culling working off a 0x0
165    // container until the first resize.
166    let UseElementSizeReturn {
167        width: cont_w,
168        height: cont_h,
169    } = use_element_size(container_ref);
170    let reg_cs = registry.clone();
171    Effect::new(move || {
172        let (obs_w, obs_h) = (cont_w.get(), cont_h.get());
173        if let Some(el) = container_ref.get() {
174            let (w, h) = (el.offset_width() as f64, el.offset_height() as f64);
175            if w > 0.0 || h > 0.0 {
176                reg_cs.container_size.set(Size::new(w, h));
177                return;
178            }
179        }
180        reg_cs.container_size.set(Size::new(obs_w, obs_h));
181    });
182
183    // Debounce viewport → visibility_viewport so node visibility (and thus the
184    // create/dispose of off-screen node content + its server queries) settles only
185    // AFTER a pan/zoom ends. The live `viewport` still drives the CSS transform
186    // every frame, so panning stays smooth; subscriptions never churn mid-pan.
187    let reg_settle = registry.clone();
188    let settle = use_debounce_fn(
189        move || {
190            let vp = reg_settle.viewport.get_untracked();
191            reg_settle.visibility_viewport.set(vp);
192        },
193        140.0,
194    );
195    let reg_track = registry.clone();
196    Effect::new(move || {
197        let _ = reg_track.viewport.get(); // track pan/zoom
198        settle();
199    });
200
201    // Menu state — owned by the editor
202    let menu_open_at: RwSignal<Option<Position>> = RwSignal::new(None);
203    let menu_screen_pos: RwSignal<Option<Position>> = RwSignal::new(None);
204    // Track last mouse position for Tab-to-open
205    let last_mouse: RwSignal<Position> = RwSignal::new(Position::new(400.0, 300.0));
206    let menu_search_signal = menu_search.unwrap_or_else(|| RwSignal::new(String::new()));
207    let has_menu = menu_items.is_some();
208
209    // Auto-focus the editor container on mount
210    Effect::new(move || {
211        if let Some(el) = container_ref.get() {
212            let _ = el.focus();
213        }
214    });
215
216    // Sync external connections into registry
217    let reg = registry.clone();
218    Effect::new(move || {
219        let conns = connections.get();
220        reg.set_connections(conns);
221    });
222
223    // Event handlers
224    let reg_md = registry.clone();
225    let ref_md = container_ref;
226    let on_mousedown = move |ev: web_sys::MouseEvent| {
227        interaction::handle_canvas_mousedown(&reg_md, ev, &ref_md);
228    };
229
230    let reg_mm = registry.clone();
231    let ref_mm = container_ref;
232    let _mousemove_cleanup = use_event_listener(
233        leptos::prelude::document(),
234        leptos::ev::mousemove,
235        move |ev: web_sys::MouseEvent| {
236            last_mouse.set(Position::new(ev.client_x() as f64, ev.client_y() as f64));
237            interaction::handle_canvas_mousemove(&reg_mm, ev, &ref_mm);
238        },
239    );
240
241    let reg_mu = registry.clone();
242    let ref_mu = container_ref;
243    let _mouseup_cleanup = use_event_listener(
244        leptos::prelude::document(),
245        leptos::ev::mouseup,
246        move |ev: web_sys::MouseEvent| {
247            interaction::handle_canvas_mouseup(&reg_mu, ev, &ref_mu);
248        },
249    );
250
251    let reg_wh = registry.clone();
252    let ref_wh = container_ref;
253    let on_wheel = move |ev: web_sys::WheelEvent| {
254        interaction::handle_wheel(&reg_wh, ev, &ref_wh);
255    };
256
257    let reg_kd = registry.clone();
258    let ref_kd = container_ref;
259    let on_keydown = move |ev: web_sys::KeyboardEvent| {
260        // Tab opens the menu
261        if ev.key() == "Tab" && has_menu {
262            ev.prevent_default();
263            let mouse = last_mouse.get_untracked();
264            let (ox, oy) = ref_kd.with_untracked(|el| {
265                el.as_ref()
266                    .map(|e| {
267                        let r = e.get_bounding_client_rect();
268                        (r.left(), r.top())
269                    })
270                    .unwrap_or((0.0, 0.0))
271            });
272            let vp = reg_kd.viewport.get_untracked();
273            let canvas_pos = vp.screen_to_canvas(Position::new(mouse.x - ox, mouse.y - oy));
274            menu_open_at.set(Some(canvas_pos));
275            menu_screen_pos.set(Some(mouse));
276            return;
277        }
278        interaction::handle_keydown(&reg_kd, ev, &ref_kd);
279    };
280
281    // Double-click opens the menu
282    let reg_dbl = registry.clone();
283    let on_dblclick = move |ev: web_sys::MouseEvent| {
284        if !has_menu {
285            return;
286        }
287        // Not while a draft connection is in flight — completing/cancelling a
288        // connection can land a fast click pair on the canvas, and the draft menu
289        // is reached with Tab, not by clicking. Don't pop it from a connection
290        // gesture.
291        if reg_dbl.draft_connection.with_untracked(Option::is_some) {
292            return;
293        }
294        // Only on empty canvas
295        if let Some(target) = ev.target() {
296            use leptos::wasm_bindgen::JsCast;
297            if let Some(el) = target.dyn_ref::<web_sys::Element>() {
298                if el.closest("[data-node]").ok().flatten().is_some() {
299                    return;
300                }
301                if el.closest("[data-anchor]").ok().flatten().is_some() {
302                    return;
303                }
304            }
305        }
306        let vp = reg_dbl.viewport.get_untracked();
307        let container_rect =
308            container_ref.with_untracked(|el| el.as_ref().map(|e| e.get_bounding_client_rect()));
309        let (ox, oy) = container_rect
310            .as_ref()
311            .map(|r| (r.left(), r.top()))
312            .unwrap_or((0.0, 0.0));
313        let canvas_pos = vp.screen_to_canvas(Position::new(
314            ev.client_x() as f64 - ox,
315            ev.client_y() as f64 - oy,
316        ));
317        menu_open_at.set(Some(canvas_pos));
318        menu_screen_pos.set(Some(Position::new(
319            ev.client_x() as f64,
320            ev.client_y() as f64,
321        )));
322    };
323
324    // Menu event handler — emits GraphEvent::CreateNode and clears draft
325    let reg_menu = registry.clone();
326    let on_event_menu = on_event;
327    let on_menu_event = Callback::new(move |event: NodeMenuEvent| {
328        match event {
329            NodeMenuEvent::CreateNode {
330                item_id,
331                position,
332                connect_to_port,
333            } => {
334                // Capture draft info before clearing
335                let (connect_from, connect_dir) =
336                    reg_menu.draft_connection.with_untracked(|d| match d {
337                        Some(d) => (Some(d.source_port.clone()), Some(d.origin_direction)),
338                        None => (None, None),
339                    });
340
341                // Clear the draft
342                reg_menu.draft_connection.set(None);
343
344                // Emit to consumer
345                on_event_menu.run(GraphEvent::CreateNode {
346                    item_id,
347                    position,
348                    connect_from,
349                    connect_to: connect_to_port,
350                    connect_direction: connect_dir,
351                });
352            }
353            NodeMenuEvent::Cancelled => {
354                reg_menu.draft_connection.set(None);
355            }
356        }
357        // The menu stole keyboard focus to its search input; once it closes, focus
358        // lands on <body> and the editor's key handlers (Tab to reopen, delete, …)
359        // go dead until the user clicks the canvas. Return focus to the editor on
360        // the next frame (after the menu element is gone).
361        let refocus = container_ref;
362        request_animation_frame(move || {
363            if let Some(el) = refocus.get_untracked() {
364                let _ = el.focus();
365            }
366        });
367    });
368
369    // Mirror the menu's open state onto the registry so the interaction handlers
370    // can see it. `menu_open_at` stays the single source of truth; this is the
371    // read path for code that only has the registry (see `menu_open`).
372    let reg_menu_open = registry.clone();
373    Effect::new(move || {
374        reg_menu_open.menu_open.set(menu_open_at.get().is_some());
375    });
376
377    // Draft context for the menu (drives port sub-item visibility + type filtering)
378    let reg_draft = registry.clone();
379    let compat_cb = Callback::new(|(src, tgt): (String, String)| T::compatible_by_id(&src, &tgt));
380    let draft_context = Signal::derive(move || {
381        reg_draft.draft_connection.with(|d| {
382            d.as_ref().map(|d| {
383                let source_type_id = reg_draft.ports.with_untracked(|ports| {
384                    ports
385                        .get(&d.source_port)
386                        .map(|p| p.port_type.type_id())
387                        .unwrap_or_default()
388                });
389
390                DraftContext {
391                    origin_direction: d.origin_direction,
392                    source_type_id,
393                    is_compatible: compat_cb,
394                }
395            })
396        })
397    });
398
399    let reg_vp = registry.clone();
400    let canvas_transform = move || {
401        let vp = reg_vp.viewport.get();
402        format!(
403            "position: relative; transform: translate({}px, {}px) scale({}); transform-origin: 0 0;",
404            vp.pan_x, vp.pan_y, vp.zoom
405        )
406    };
407
408    // Mount point for node-anchored overlays (see overlay.rs).
409    let overlay_ref = NodeRef::<leptos::html::Div>::new();
410    provide_context(crate::overlay::NodeOverlayLayer {
411        mount: overlay_ref,
412        viewport: registry.viewport.into(),
413    });
414
415    // A fast drag or resize can outrun the node and leave the pointer over empty
416    // canvas — hold the gesture's cursor for its whole duration.
417    let reg_cursor = registry.clone();
418    let node_style_ctx = use_context::<crate::theme::NodeStyle>().unwrap_or_default();
419    let (cursor_dragging, cursor_resize) =
420        (node_style_ctx.cursor_dragging, node_style_ctx.cursor_resize);
421    let container_style = move || {
422        let base =
423            "position: relative; width: 100%; height: 100%; overflow: hidden; outline: none;";
424        if reg_cursor.resize_state.with(|rs| rs.is_some()) {
425            format!("{base} cursor: {cursor_resize};")
426        } else if reg_cursor.drag_state.with(|ds| ds.is_some()) {
427            format!("{base} cursor: {cursor_dragging};")
428        } else {
429            base.to_string()
430        }
431    };
432
433    // Menu items (use empty vec if not provided)
434    let menu_items_signal = menu_items.unwrap_or_else(|| Signal::derive(std::vec::Vec::new));
435
436    // Groups overlay
437    let groups_signal = groups.unwrap_or_else(|| Signal::derive(std::vec::Vec::new));
438    let groups_view = if let Some(cb) = on_group_event {
439        view! {
440            <GroupBoxOverlay<N, P, C, T>
441                groups=groups_signal
442                on_event=cb
443                on_ungroup=on_ungroup.unwrap_or_else(|| Callback::new(|_| {}))
444                on_select_all=on_select_all.unwrap_or_else(|| Callback::new(|_| {}))
445            />
446        }
447        .into_any()
448    } else {
449        view! {
450            <GroupBoxOverlay<N, P, C, T>
451                groups=groups_signal
452                on_ungroup=on_ungroup.unwrap_or_else(|| Callback::new(|_| {}))
453                on_select_all=on_select_all.unwrap_or_else(|| Callback::new(|_| {}))
454            />
455        }
456        .into_any()
457    };
458
459    let menu_screen_pos_signal = Signal::derive(move || menu_screen_pos.get());
460
461    view! {
462        <div
463            class="node-editor"
464            tabindex="0"
465            node_ref=container_ref
466            style=container_style
467            on:mousedown=on_mousedown
468            on:wheel=on_wheel
469            on:keydown=on_keydown
470            on:dblclick=on_dblclick
471        >
472            <div class="node-editor__canvas" style=canvas_transform>
473                <ConnectionRenderer<N, P, C, T> />
474                {groups_view}
475                {children()}
476            </div>
477            <SelectionBox<N, P, C, T> />
478            // Overlay layer: inside the pane but OUTSIDE the canvas transform,
479            // so node-anchored panels are unscaled and positioned in pane space,
480            // and are clipped by the graph rather than escaping to the document.
481            <div
482                class="node-editor__overlays"
483                node_ref=overlay_ref
484                style="position: absolute; inset: 0; overflow: hidden; \
485                       pointer-events: none; isolation: isolate;"
486            />
487        </div>
488        <NodeMenu
489            items=menu_items_signal
490            search_text=menu_search_signal
491            on_event=on_menu_event
492            open_at=menu_open_at
493            screen_pos=menu_screen_pos_signal
494            draft_context=draft_context
495        />
496    }
497}