refactor: implement safe triangle pattern for submenu navigation

[DiegoCardoso]

Summary

Fixes #9904

Introduces a SafeTriangleController that prevents premature submenu closing when the user moves the mouse diagonally from a parent menu item toward the open submenu. Integrated into both vaadin-context-menu (items mixin) and vaadin-menu-bar (menu bar mixin).

Uses atan2 angle comparison (inspired by React Aria's approach) to detect whether the cursor is aimed at the submenu, with a 15° angular tolerance and a 2-strike threshold before allowing submenu switches.

How it works

When a submenu is open, a pointermove listener on document tracks cursor movement (throttled via event.timeStamp comparison). For each movement, it computes angles from the cursor to the near-edge corners of the submenu overlay. If the cursor's movement vector falls within that angular cone (plus tolerance), the submenu stays open. Only after 2 consecutive "miss" movements does the controller allow the switch.

Key design decisions

• Lazy activation — listener only attached while a submenu is open, zero overhead otherwise
• Touch-safe — skipped entirely for pointerType === 'touch' or 'pen'
• Direction-agnostic — detects submenu direction from actual overlay position at runtime (handles both LTR/RTL and viewport-edge flipping)
• Accessible — the 2-strike threshold accommodates motor impairments and hand tremors
• JS private class members — controller internals use #private fields for encapsulation
• safe-triangle-active attribute — reflected on the menu overlay container while the controller is active, enabling CSS-based hover highlight suppression
• Hover highlight suppression — pointer-events: none on list-box items while safe-triangle navigation is active, preventing distracting hover flicker
• Fallback timeout — 1-second safety net that deactivates the controller if no pointer movement is detected, preventing stuck states
• Pending switch scheduling — when the controller blocks a submenu switch, the switch is queued and executed once the controller deactivates
• Escape key deactivation — pressing Escape deactivates the controller and cleans up state
• Stale container cleanup — the controller detects and handles cases where the submenu container is removed from the DOM while active

Architecture

• SafeTriangleController in packages/context-menu/src/vaadin-safe-triangle-controller.js (224 lines)
• Shared pointerMove test helper in packages/context-menu/test/helpers.js for simulating diagonal mouse movements across both test suites
• Uses event.timeStamp for throttle timing instead of performance.now() for consistency with the event stream
• Aura and Lumo theme CSS additions for [safe-triangle-active] styling on overlay list-boxes

Performance analysis

Chrome DevTools performance traces were captured before (commit b0d3dd98c8) and after (commit 76db29d76b) the change, using the same dev/menu-bar.html page and identical interaction sequences (open Share submenu → hover nested "On social media" → hover sibling "Get link" → repeat).

Page load (control — controller inactive)

Metric	Before	After	Delta
LCP	745 ms	740 ms	-5 ms (noise)
CLS	0.00	0.00	0

Interaction (hot path — controller active during submenu hover)

Metric	Before	After	Delta
INP	40 ms	46 ms	+6 ms (noise)
Long tasks (>50ms)	0	0	0

Both INP values are well within the "Good" threshold (< 200ms). The +6ms delta is evenly distributed across all INP phases (input delay, processing, presentation), consistent with measurement noise rather than a systematic regression. No long tasks were introduced in either run.

Conclusion: The SafeTriangleController introduces no measurable performance overhead.

Changes

15 files changed, 764 insertions, 19 deletions (12 commits)

Test plan

• yarn test --group context-menu — 213 passed, 0 failed
• yarn test --group menu-bar — 193 passed, 0 failed
• yarn test:snapshots --group context-menu — updated
• yarn test:snapshots --group menu-bar — updated
• Manual testing at /dev/menu-bar.html and /dev/context-menu.html with diagonal mouse movements
• Verify keyboard navigation is unaffected
• Verify touch behavior is unaffected

🤖 Generated with Claude Code

[jouni]

The only thing that bothers me with this implementation (a little, not likely to be a blocker), is that the other items under the mouse cursor still apply the hover styles when passing over them towards the sub-menu.

[DiegoCardoso]

The only thing that bothers me with this implementation (a little, not likely to be a blocker), is that the other items under the mouse cursor still apply the hover styles when passing over them towards the sub-menu.

Added some implementation to cover this. It adds an attribute to the host element and targets in CSS the not expanded items to have a transparent background.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud