docs/features/vl-disk-interactions.md

Voltage-level disk interactions (NAD)

The voltage-level (VL) disks drawn by pypowsybl on the Network Area Diagram are directly interactive on every NAD tab — Network (N), Contingency and Remedial Action. Three gestures are wired onto each disk:

Gesture	Effect
Hover	Shows the VL name in a small floating tooltip — but only while the on-diagram VL labels are hidden (the 🏷 VL toggle). When the labels are visible the name is already drawn, so the tooltip stays out of the way.
Single-click (disk)	Selects the VL: fills the bottom-left Inspect field with the VL id, auto-zooms / highlights it, and surfaces the 📄 SLD shortcut — exactly as typing the name into the Inspect box would.
Single-click (name box)	Opens the VL's Single Line Diagram overlay directly — the name label next to the disk is a second, larger click target for the SLD.
Double-click (disk or name box)	Opens the VL's Single Line Diagram overlay (the same entry point as the 📄 SLD button / onVlOpen).

This is the disk-driven complement to the Inspect search field: the field finds an asset by name; the disk finds it by pointing at it.

The whole disk is a target, even under a branch

A branch is often drawn ON TOP of a VL disk, which would otherwise steal the pointer hit-test from the disk beneath it. The handlers resolve this: when the direct hit-test lands on something that is not a VL (an occluding edge, or empty space), they fall back to document.elementsFromPoint and take the first VL disk / name box in the paint stack under the cursor. So the disk is interactive across its whole area regardless of what is painted over it. The fallback only runs on discrete pointer events (mousedown / hover-while-labels-hidden), never per frame, so the performance contract below is unchanged.

The name box is resolved through the metadata

pypowsybl renders each VL name as a <div class="nad-label-box" id="…"> inside a root-level <foreignObject class="nad-text-nodes">. The box id is the NAD metadata text-node svgId, which the metadata index (metaIndex.textNodesBySvgId, built from metadata.textNodes via each entry's vlNode link / equipmentId) maps to the same VL NodeMeta the disk resolves to. A delegated handler climbs from the click target to the first ancestor whose id is a known disk or text-node svgId.

Where it lives

• frontend/src/utils/svg/vlInteractions.ts — attachVlInteractions(container, metaIndex, handlers). The whole behaviour is one function returning a teardown.
• frontend/src/App.tsx — a single effect binds the three NAD containers, mapping each gesture to the existing handlers:
  • onSelect(vlId) → handleInspectQueryChangeFor(tab, vlId) (drives the per-tab Inspect query + auto-zoom in useDiagrams). Fired by a single-click on the disk.
  • onOpenSld(vlId) → handleVlOpen(vlId) → useSldOverlay.handleVlDoubleClick. Fired by a double-click on the disk / name box and by a single-click on the name box. The callbacks are held in refs (vlSelectRef / vlOpenSldRef / vlDisplayNameRef) so the listeners re-bind only when a diagram or its metadata index changes — never on an unrelated render, which would needlessly tear down the listeners and cancel an in-flight single-click timer.
• frontend/src/App.css — .svg-container .nad-vl-nodes, .svg-container .nad-label-box { cursor: pointer } is the (static) pointer-cursor affordance on both the disk and the name box.

onSelect / onOpenSld reuse pre-existing interaction events (inspect_query_changed, sld_overlay_opened), so the replay log stays complete with no new event types.

How a disk is resolved

pypowsybl renders each VL under <g class="nad-vl-nodes"> as a group <g id="{svgId}"><circle r="27.5"/>…</g>. The diagram metadata index (metaIndex.nodesBySvgId) maps that svgId to the VL's equipmentId (the VL id used everywhere else — voltageLevels, the SLD endpoints, the zoom-to-element lookup). A delegated handler climbs from the event target up to the first ancestor whose id is a known node svgId, yielding the VL.

Performance contract (do not regress)

Pan/zoom fluidity is the hard constraint — the NAD can carry ~5 000 VLs / ~100 k DOM nodes. The design is built around touching nothing per frame:

• Event delegation. A fixed handful of listeners on the container (mouseover, mouseout, mousedown, click, dblclick), never one per node. A 5 000-VL grid costs the same to wire as a 5-VL one.
• No mousemove / no per-frame work. The tooltip is positioned once on mouseover; the cursor is a static CSS rule.
• Idle during gestures. usePanZoom adds .svg-interacting during a pan/zoom, which sets pointer-events: none on every SVG child (App.css), so none of the disk handlers fire mid-gesture. Pan/zoom is a direct viewBox rewrite (no React re-render per frame), and this layer adds nothing to it.

The click-vs-pan subtlety (regression-tested)

Because .svg-interacting flips pointer-events: none on SVG children the instant a press starts, by the time mouseup fires the disk is transparent and the browser retargets the resulting click / dblclick to the container (the common ancestor of the disk-mousedown and the container-mouseup). Resolving the VL from click.target would therefore always miss — this is exactly the bug where hover worked but clicks did nothing.

The fix: capture the VL on mousedown, whose hit-test still lands on the live disk (the cull class is only set by that handler, after the target is already fixed), and use the captured node in the click / double-click handlers. A press is told apart from a pan by pointer travel (DRAG_THRESHOLD_PX), and the single-click action is deferred VL_SINGLE_CLICK_DELAY_MS (250 ms) so a double-click pre-empts it.

Tests

• frontend/src/utils/svg/vlInteractions.test.ts — unit coverage for the module: single-click → onSelect, double-click → onOpenSld (and single-click suppression), the container-retargeted click / dbl-click (the real-world pointer-events cull), the drag guard, hover-tooltip gating on nad-hide-vl-labels, displayName fallback, same-group mouseout, single-tooltip reuse, nested-child resolution, multi-VL disambiguation, teardown (listeners + tooltip + pending timer), and the no-op guards.
• frontend/src/App.stateManagement.test.tsx (Voltage-level disk interaction wiring) — captures the handlers App passes to attachVlInteractions and invokes them, asserting onSelect flows into the shared Inspect query and onOpenSld opens the SLD overlay for the VL.

History

Supersedes the former native <title> tooltip injector (utils/svg/vlTitles.ts, applyVlTitles, removed): the native title only delivered hover-name; the unified layer delivers hover + click + double- click with an immediate, theme-aware tooltip and no double tooltip.