Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Tooltip): keep the tooltip open when the pointer crosses onto it in one step (#7802)

Cindy Zhang7fbacfb4b0ef
diff --git a/.changeset/tooltip-hover-bridge-one-step.md b/.changeset/tooltip-hover-bridge-one-step.md
new file mode 100644
index 0000000000..6c6c1ab24d
--- /dev/null
+++ b/.changeset/tooltip-hover-bridge-one-step.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Tooltip: moving the pointer straight from the trigger onto the tooltip in one step no longer hides it, so it stays open while hovered (WCAG 1.4.13).
+
+@cixzhang
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8e95ca2f1..f920367af9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1383,6 +1383,17 @@ jobs:
--project chromium \
--output menu-header-footer-output
+ # A pointer that crosses from a Tooltip's trigger onto the tooltip in one
+ # step must not lose it (WCAG 1.4.13 hoverable). The defect is in the
+ # order the engine dispatches mouseout and mouseleave on that step, which
+ # only a real engine produces.
+ - name: Run Tooltip hover bridge contract
+ run: |
+ pnpm exec playwright test \
+ packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts \
+ --project chromium \
+ --output tooltip-hover-bridge-output
+
# A Token's remove target is enlarged past its 16px X, and only a real
# engine hit-tests it: a press on the end of the value beside the X must
# run the token's own action, and a press just outside the X must remove.
diff --git a/packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts b/packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..8c2b7723cb
--- /dev/null
+++ b/packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts
@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TooltipHoverBridge.a11y.chromium.spec.ts
+ * @input The `Core/Tooltip` Default story in a built Storybook and real mouse
+ * input.
+ * @output Real-engine proof that a pointer moving from the trigger onto the
+ * tooltip in one step keeps the tooltip open (WCAG 2.2 1.4.13 Content on
+ * Hover or Focus, hoverable), and that leaving the tooltip still hides it.
+ * @position Run with `pnpm test:a11y-contract`. The defect lives in the order
+ * the engine dispatches mouseout and mouseleave on one pointer step, which
+ * only a real engine produces.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+const STORY = 'core-tooltip--default';
+
+async function openTooltip(page: Page) {
+ await page.setViewportSize({width: 900, height: 600});
+ await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+ await holdMotionStill(page);
+ const trigger = page.getByRole('button', {name: 'Hover me'});
+ await trigger.hover();
+ const tooltip = page.getByRole('tooltip');
+ await expect(tooltip).toBeVisible();
+ const t = await trigger.boundingBox();
+ const s = await tooltip.boundingBox();
+ if (t == null || s == null) {
+ throw new Error('the trigger or the tooltip has no layout box');
+ }
+ return {tooltip, s};
+}
+
+test('a one-step move from the trigger onto the tooltip keeps it open', async ({
+ page,
+}) => {
+ const {tooltip, s} = await openTooltip(page);
+
+ // One mousemove event straight onto the tooltip, as a quick hand makes.
+ await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+ // Well past the 100ms hover bridge.
+ await page.waitForTimeout(400);
+
+ await expect(tooltip).toBeVisible();
+});
+
+test('leaving the tooltip for the page still hides it', async ({page}) => {
+ const {tooltip, s} = await openTooltip(page);
+
+ await page.mouse.move(s.x + s.width / 2, s.y + s.height / 2);
+ await page.waitForTimeout(200);
+ await page.mouse.move(5, 5);
+
+ await expect(tooltip).toBeHidden();
+});
diff --git a/packages/core/src/Tooltip/useTooltip.test.tsx b/packages/core/src/Tooltip/useTooltip.test.tsx
index 70f79a93ad..292f64424d 100644
--- a/packages/core/src/Tooltip/useTooltip.test.tsx
+++ b/packages/core/src/Tooltip/useTooltip.test.tsx
@@ -214,6 +214,29 @@ describe('useTooltip — hide delay', () => {
expect(onHide).toHaveBeenCalledTimes(1);
});
+ it('stays open when the pointer crosses onto the tooltip in one step', () => {
+ const onHide = vi.fn();
+ showTooltip(onHide);
+ const surface = tooltipElement();
+
+ // A one-step crossing dispatches in browser order: the trigger's mouseout
+ // (React derives the surface's onMouseEnter from it), then the trigger's
+ // native mouseleave, both pointing at the surface. fireEvent.mouseLeave
+ // would add a mouseout after the leave, so the leave is dispatched raw.
+ fireEvent.mouseOut(trigger(), {relatedTarget: surface});
+ act(() => {
+ trigger().dispatchEvent(
+ new MouseEvent('mouseleave', {relatedTarget: surface}),
+ );
+ });
+ tick(500);
+ expect(onHide).not.toHaveBeenCalled();
+
+ fireEvent.mouseOut(surface, {relatedTarget: document.body});
+ tick(100);
+ expect(onHide).toHaveBeenCalledTimes(1);
+ });
+
it('uses an explicit hideDelay instead of the hover bridge', () => {
const onHide = vi.fn();
showTooltip(onHide, {hideDelay: 500});
diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx
index 508a25899f..c99b7015e1 100644
--- a/packages/core/src/Tooltip/useTooltip.tsx
+++ b/packages/core/src/Tooltip/useTooltip.tsx
@@ -397,15 +397,28 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
scheduleShow();
}, [isTouchPointerRef, scheduleShow]);
- const handleMouseLeave = useCallback(() => {
- // 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.
- if (isTouchPointerRef.current) {
- return;
- }
- scheduleHide();
- }, [isTouchPointerRef, scheduleHide]);
+ const handleMouseLeave = useCallback(
+ (event: Event) => {
+ // 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.
+ if (isTouchPointerRef.current) {
+ return;
+ }
+ // Leaving straight onto the tooltip: the surface's onMouseEnter already
+ // ran, because React dispatches it from the mouseout that precedes this
+ // mouseleave, so a hide scheduled now would never be cancelled. The
+ // surface's own mouse leave schedules the hide instead.
+ const next = (event as MouseEvent).relatedTarget as Node | null;
+ const surface =
+ next == null ? null : next.ownerDocument?.getElementById(layerId);
+ if (surface != null && surface.contains(next)) {
+ return;
+ }
+ scheduleHide();
+ },
+ [isTouchPointerRef, layerId, scheduleHide],
+ );
const handleFocusIn = useCallback(
(e: Event) => {