From 857cccabb679949f119f75104170d2ec5e21a2b2 Mon Sep 17 00:00:00 2001 From: Ravindra Singh Shah Date: Thu, 19 Nov 2026 14:55:59 -0600 Subject: [PATCH 1/5] fix(Tooltip): keep Escape-dismissed tooltip closed while pointer rests on trigger (#11895) --- .../tooltip-escape-dismissal-stays-closed.md | 6 +++ packages/core/src/Tooltip/useTooltip.test.tsx | 46 +++++++++++++++++++ packages/core/src/Tooltip/useTooltip.tsx | 15 ++++++ 3 files changed, 67 insertions(+) create mode 100644 .changeset/tooltip-escape-dismissal-stays-closed.md diff --git a/.changeset/tooltip-escape-dismissal-stays-closed.md b/.changeset/tooltip-escape-dismissal-stays-closed.md new file mode 100644 index 0000000000000..87a4b48e0e82b --- /dev/null +++ b/.changeset/tooltip-escape-dismissal-stays-closed.md @@ -0,0 +1,6 @@ +--- +'@astryxdesign/core': patch +--- + +[fix] Tooltip stays dismissed with Escape while the pointer rests on its trigger (#11895) +@ravindrasinghshah diff --git a/packages/core/src/Tooltip/useTooltip.test.tsx b/packages/core/src/Tooltip/useTooltip.test.tsx index 31c5a50159428..e8ac3b7503601 100644 --- a/packages/core/src/Tooltip/useTooltip.test.tsx +++ b/packages/core/src/Tooltip/useTooltip.test.tsx @@ -567,6 +567,52 @@ describe('useTooltip — Escape dismissal', () => { expect(tooltipElement().matches(':popover-open')).toBe(false); }); + it('stays closed on a fresh mouseenter while the pointer never left after Escape', () => { + const onShow = vi.fn(); + render(); + fireEvent.mouseEnter(trigger()); + tick(0); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + fireEvent.keyDown(document, {key: 'Escape'}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // The pointer never moved: the surface closing hands the trigger a fresh + // mouseenter, and that enter must not reopen the tooltip. + fireEvent.mouseEnter(trigger()); + tick(1000); + expect(onShow).toHaveBeenCalledTimes(1); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // Leaving and entering again is a genuine re-entry: it shows. + fireEvent.mouseLeave(trigger()); + fireEvent.mouseEnter(trigger()); + tick(0); + expect(onShow).toHaveBeenCalledTimes(2); + expect(tooltipElement().matches(':popover-open')).toBe(true); + }); + + it('shows again after focus leaves and returns following an Escape dismissal', () => { + const onShow = vi.fn(); + render(); + const matches = trigger().matches.bind(trigger()); + vi.spyOn(trigger(), 'matches').mockImplementation( + selector => selector === ':focus-visible' || matches(selector), + ); + act(() => trigger().focus()); + expect(onShow).toHaveBeenCalledTimes(1); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + fireEvent.keyDown(document, {key: 'Escape'}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // Focus leaves and comes back: a new entry, so the tooltip shows. + act(() => trigger().blur()); + act(() => trigger().focus()); + expect(onShow).toHaveBeenCalledTimes(2); + expect(tooltipElement().matches(':popover-open')).toBe(true); + }); + it('ignores an Escape that carries the IME keyCode 229', () => { const onHide = vi.fn(); render(); diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx index a454ff142bb58..6aad25e918ba3 100644 --- a/packages/core/src/Tooltip/useTooltip.tsx +++ b/packages/core/src/Tooltip/useTooltip.tsx @@ -344,6 +344,11 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { disabledRendersRef.current += 1; } + // Set by an Escape dismissal. While set, a mouseenter does not schedule a + // show: the pointer never left the trigger, so the enter is the surface + // closing, not a new hover. Pointer leave or focus leave clears it. + const dismissedByEscapeRef = useRef(false); + // Clear all timeouts const clearTimeouts = useCallback(() => { if (showTimeoutRef.current) { @@ -537,11 +542,18 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { if (isTouchPointerRef.current) { return; } + // A tooltip dismissed with Escape stays closed while the pointer rests + // on its trigger. + if (dismissedByEscapeRef.current) { + return; + } scheduleShow(); }, [isTouchPointerRef, scheduleShow]); const handleMouseLeave = useCallback( (event: Event) => { + // The pointer left the trigger, so a later enter is a new hover. + dismissedByEscapeRef.current = false; // On touch the synthesized mouseleave arrives with the next tap elsewhere, // which the outside-tap dismissal already handles — and handling it here // too would close the tooltip behind the tap-open bookkeeping's back. @@ -625,6 +637,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { if (!focusGate.focusOut(e, focusTrigger)) { return; } + // Focus left the trigger, so a later focus is a new entry. + dismissedByEscapeRef.current = false; scheduleHide(); }, [focusGate, focusTrigger, scheduleHide], @@ -960,6 +974,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { } }, onDismiss: () => { + dismissedByEscapeRef.current = true; clearTimeouts(); clearTapOpen(); dropHold(); From c74ef52386a97a6e1b861fd6387378217ce2941a Mon Sep 17 00:00:00 2001 From: Ravindra Singh Shah Date: Thu, 19 Nov 2026 18:23:39 -0600 Subject: [PATCH 2/5] fix(Tooltip): arm Escape-dismissal guard only while pointer is over trigger (#11895) --- packages/core/src/Tooltip/useTooltip.test.tsx | 23 +++++++++ packages/core/src/Tooltip/useTooltip.tsx | 50 +++++++++++++++---- 2 files changed, 64 insertions(+), 9 deletions(-) diff --git a/packages/core/src/Tooltip/useTooltip.test.tsx b/packages/core/src/Tooltip/useTooltip.test.tsx index e8ac3b7503601..a17e5bfb2caf7 100644 --- a/packages/core/src/Tooltip/useTooltip.test.tsx +++ b/packages/core/src/Tooltip/useTooltip.test.tsx @@ -613,6 +613,29 @@ describe('useTooltip — Escape dismissal', () => { expect(tooltipElement().matches(':popover-open')).toBe(true); }); + it('shows on hover after a keyboard-focus Escape', () => { + const onShow = vi.fn(); + render(); + const matches = trigger().matches.bind(trigger()); + vi.spyOn(trigger(), 'matches').mockImplementation( + selector => selector === ':focus-visible' || matches(selector), + ); + // Keyboard focus opens the tooltip with the pointer nowhere near it. + act(() => trigger().focus()); + expect(onShow).toHaveBeenCalledTimes(1); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + fireEvent.keyDown(document, {key: 'Escape'}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // The pointer was never over the trigger, so this is a first real hover: + // it shows, unlike the no-move mouseenter after a hover dismissal. + fireEvent.mouseEnter(trigger()); + tick(1000); + expect(onShow).toHaveBeenCalledTimes(2); + expect(tooltipElement().matches(':popover-open')).toBe(true); + }); + it('ignores an Escape that carries the IME keyCode 229', () => { const onHide = vi.fn(); render(); diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx index 6aad25e918ba3..e30a0ee2cfe93 100644 --- a/packages/core/src/Tooltip/useTooltip.tsx +++ b/packages/core/src/Tooltip/useTooltip.tsx @@ -344,10 +344,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { disabledRendersRef.current += 1; } - // Set by an Escape dismissal. While set, a mouseenter does not schedule a - // show: the pointer never left the trigger, so the enter is the surface - // closing, not a new hover. Pointer leave or focus leave clears it. + // An Escape dismissal sets this flag. Closing the surface can give the + // trigger a mouseenter with no pointer movement. While the flag is set, that + // enter shows nothing. A pointer leave or a focus leave clears the flag. const dismissedByEscapeRef = useRef(false); + // Whether the pointer is over the trigger or the tooltip surface. An + // Escape dismissal arms the flag above only while this is set, so a + // keyboard-focus dismissal does not swallow the next hover. + const isPointerOverRef = useRef(false); // Clear all timeouts const clearTimeouts = useCallback(() => { @@ -542,6 +546,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { if (isTouchPointerRef.current) { return; } + isPointerOverRef.current = true; // A tooltip dismissed with Escape stays closed while the pointer rests // on its trigger. if (dismissedByEscapeRef.current) { @@ -570,6 +575,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { if (surface != null && surface.contains(next)) { return; } + isPointerOverRef.current = false; scheduleHide(); }, [isTouchPointerRef, layerId, scheduleHide], @@ -637,7 +643,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { if (!focusGate.focusOut(e, focusTrigger)) { return; } - // Focus left the trigger, so a later focus is a new entry. + // Focus left the trigger. The next hover can show the tooltip again. dismissedByEscapeRef.current = false; scheduleHide(); }, @@ -974,7 +980,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { } }, onDismiss: () => { - dismissedByEscapeRef.current = true; + dismissedByEscapeRef.current = isPointerOverRef.current; clearTimeouts(); clearTapOpen(); dropHold(); @@ -986,6 +992,32 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { }, }); + // The surface is part of the trigger's hover zone: while the pointer is + // over it, an Escape dismissal still counts as a dismissal under the + // pointer. Leaving the surface for anywhere but the trigger leaves the + // zone, so a later hover is a new entry. + const handleSurfaceMouseEnter = useCallback(() => { + isPointerOverRef.current = true; + cancelHide(); + }, [cancelHide]); + + const handleSurfaceMouseLeave = useCallback( + (event: Event) => { + // React's simulated mouseleave can carry a non-Node relatedTarget + // (the window), so only a Node inside the trigger counts as moving + // back onto it. + const next = (event as MouseEvent).relatedTarget as Node | null; + const trigger = triggerRef.current; + if (next instanceof Node && trigger != null && trigger.contains(next)) { + return; + } + isPointerOverRef.current = false; + dismissedByEscapeRef.current = false; + scheduleHide(); + }, + [scheduleHide, triggerRef], + ); + // Render function that wraps layer.render with tooltip styling const renderTooltip = useCallback( ( @@ -1004,8 +1036,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { // (WCAG 1.4.13 hoverable). These sit on the layer container — the // element the user actually hovers — not the inner content div, since // mouseenter/leave do not bubble. - onMouseEnter: cancelHide, - onMouseLeave: scheduleHide, + onMouseEnter: handleSurfaceMouseEnter, + onMouseLeave: handleSurfaceMouseLeave, }; return renderLayer( @@ -1026,8 +1058,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { placement, alignment, popoverXstyle, - cancelHide, - scheduleHide, + handleSurfaceMouseEnter, + handleSurfaceMouseLeave, contentRefs, ], ); From 2df73300e15ad65dde1ef9e064f9b4fa9cd407a9 Mon Sep 17 00:00:00 2001 From: Ravindra Singh Shah Date: Thu, 19 Nov 2026 18:39:35 -0600 Subject: [PATCH 3/5] fix(Tooltip): type surface mouseleave handler as React MouseEvent (#11895) --- packages/core/src/Tooltip/useTooltip.tsx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx index e30a0ee2cfe93..17461cfb3828e 100644 --- a/packages/core/src/Tooltip/useTooltip.tsx +++ b/packages/core/src/Tooltip/useTooltip.tsx @@ -19,6 +19,7 @@ import { useEffect, useRef, useState, + type MouseEvent as ReactMouseEvent, type ReactNode, type RefCallback, } from 'react'; @@ -1002,11 +1003,11 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { }, [cancelHide]); const handleSurfaceMouseLeave = useCallback( - (event: Event) => { + (event: ReactMouseEvent) => { // React's simulated mouseleave can carry a non-Node relatedTarget // (the window), so only a Node inside the trigger counts as moving // back onto it. - const next = (event as MouseEvent).relatedTarget as Node | null; + const next = event.relatedTarget as Node | null; const trigger = triggerRef.current; if (next instanceof Node && trigger != null && trigger.contains(next)) { return; From df1703b7c93632624701bdc884cd248651060084 Mon Sep 17 00:00:00 2001 From: Ravindra Singh Shah Date: Thu, 19 Nov 2026 19:29:10 -0600 Subject: [PATCH 4/5] fix(Tooltip): reset pointer state when a disabled trigger detaches (#11895) --- packages/core/src/Tooltip/useTooltip.test.tsx | 66 +++++++++++++++++++ packages/core/src/Tooltip/useTooltip.tsx | 6 +- 2 files changed, 71 insertions(+), 1 deletion(-) diff --git a/packages/core/src/Tooltip/useTooltip.test.tsx b/packages/core/src/Tooltip/useTooltip.test.tsx index a17e5bfb2caf7..c287c85ff2136 100644 --- a/packages/core/src/Tooltip/useTooltip.test.tsx +++ b/packages/core/src/Tooltip/useTooltip.test.tsx @@ -203,6 +203,72 @@ describe('useTooltip — a trigger that detaches and attaches again', () => { expect(onHide).toHaveBeenCalledTimes(1); }); + it('shows on hover after an Escape that follows a detached-while-hovered reattach', async () => { + const onShow = vi.fn(); + const {rerender} = render(); + fireEvent.mouseEnter(trigger()); + tick(200); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + // The menu opens: the caller removes the wiring and disables the tooltip. + rerender(); + await act(async () => {}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // The pointer leaves while detached: no mouseleave reaches the hook. + fireEvent.mouseLeave(trigger()); + + // The menu closes on Escape and focus returns to the trigger, so the + // tooltip shows again on reattach. + const matches = trigger().matches.bind(trigger()); + vi.spyOn(trigger(), 'matches').mockImplementation( + selector => selector === ':focus-visible' || matches(selector), + ); + act(() => trigger().focus()); + rerender(); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + // Escape dismisses it with the pointer nowhere near the trigger now. + fireEvent.keyDown(document, {key: 'Escape'}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // This is a first real hover: it shows. + fireEvent.mouseEnter(trigger()); + tick(1000); + expect(onShow).toHaveBeenCalledTimes(3); + expect(tooltipElement().matches(':popover-open')).toBe(true); + }); + + it('shows on hover after an Escape and a detached-while-hovered menu pick', async () => { + const onShow = vi.fn(); + const {rerender} = render(); + fireEvent.mouseEnter(trigger()); + tick(200); + expect(tooltipElement().matches(':popover-open')).toBe(true); + + // Escape dismisses it while the pointer is still over the trigger. + fireEvent.keyDown(document, {key: 'Escape'}); + expect(tooltipElement().matches(':popover-open')).toBe(false); + + // The menu opens: the caller removes the wiring and disables the tooltip. + rerender(); + await act(async () => {}); + + // The pointer leaves while detached, and the menu item is picked with + // the mouse: neither leave is seen by the hook. + fireEvent.mouseLeave(trigger()); + + // The menu closes and the wiring comes back. + rerender(); + await act(async () => {}); + + // This is a first real hover: it shows. + fireEvent.mouseEnter(trigger()); + tick(1000); + expect(onShow).toHaveBeenCalledTimes(2); + expect(tooltipElement().matches(':popover-open')).toBe(true); + }); + it('shows on attach for keyboard focus that arrived while detached', async () => { const {rerender} = render(); rerender(); diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx index 17461cfb3828e..53b7cb3b4580c 100644 --- a/packages/core/src/Tooltip/useTooltip.tsx +++ b/packages/core/src/Tooltip/useTooltip.tsx @@ -758,7 +758,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { // A caller removes the wiring as it disables the tooltip. Close an // uncontrolled tooltip then, or the next attach shows a stale tooltip. A // detach while enabled, such as a merged ref that changes identity on a - // re-render, keeps a hovered or held tooltip open. + // re-render, keeps a hovered or held tooltip open. The pointer may have + // left while detached, and the mouseleave listener is gone, so the pointer + // state resets too. const settleDetach = useCallback(() => { if (!isDetachPendingRef.current) { return; @@ -767,6 +769,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { const latest = handlersRef.current; if (!latest.isEnabled && latest.isOpen === undefined) { wasSuppressedRef.current = true; + isPointerOverRef.current = false; + dismissedByEscapeRef.current = false; latest.dropHold(); latest.hideNow(); } From 58c247689a823a92d717b3905b33fd3a89f80f7f Mon Sep 17 00:00:00 2001 From: Ravindra Singh Shah Date: Thu, 19 Nov 2026 20:44:09 -0600 Subject: [PATCH 5/5] chore(Tooltip): tighten Escape-dismissal comment wording (#11895) --- packages/core/src/Tooltip/useTooltip.tsx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx index 53b7cb3b4580c..79c419fac74a5 100644 --- a/packages/core/src/Tooltip/useTooltip.tsx +++ b/packages/core/src/Tooltip/useTooltip.tsx @@ -345,9 +345,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn { disabledRendersRef.current += 1; } - // An Escape dismissal sets this flag. Closing the surface can give the - // trigger a mouseenter with no pointer movement. While the flag is set, that - // enter shows nothing. A pointer leave or a focus leave clears the flag. + // Closing the surface can give the trigger a mouseenter with no pointer + // movement. While this is set, that enter shows nothing. const dismissedByEscapeRef = useRef(false); // Whether the pointer is over the trigger or the tooltip surface. An // Escape dismissal arms the flag above only while this is set, so a