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..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();
@@ -567,6 +633,75 @@ 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('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 a454ff142bb58..79c419fac74a5 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';
@@ -344,6 +345,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
disabledRendersRef.current += 1;
}
+ // 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
+ // keyboard-focus dismissal does not swallow the next hover.
+ const isPointerOverRef = useRef(false);
+
// Clear all timeouts
const clearTimeouts = useCallback(() => {
if (showTimeoutRef.current) {
@@ -537,11 +546,19 @@ 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) {
+ 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.
@@ -558,6 +575,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
if (surface != null && surface.contains(next)) {
return;
}
+ isPointerOverRef.current = false;
scheduleHide();
},
[isTouchPointerRef, layerId, scheduleHide],
@@ -625,6 +643,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
if (!focusGate.focusOut(e, focusTrigger)) {
return;
}
+ // Focus left the trigger. The next hover can show the tooltip again.
+ dismissedByEscapeRef.current = false;
scheduleHide();
},
[focusGate, focusTrigger, scheduleHide],
@@ -737,7 +757,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;
@@ -746,6 +768,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();
}
@@ -960,6 +984,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
}
},
onDismiss: () => {
+ dismissedByEscapeRef.current = isPointerOverRef.current;
clearTimeouts();
clearTapOpen();
dropHold();
@@ -971,6 +996,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: 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.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(
(
@@ -989,8 +1040,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(
@@ -1011,8 +1062,8 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
placement,
alignment,
popoverXstyle,
- cancelHide,
- scheduleHide,
+ handleSurfaceMouseEnter,
+ handleSurfaceMouseLeave,
contentRefs,
],
);