Skip to content

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

TypeScript

fix(tooltip): satisfy WCAG 1.4.13 — Escape dismiss + hoverable surface (#3363)

Cindy Zhangbc2f7c920eca
diff --git a/.changeset/tooltip-wcag-1413.md b/.changeset/tooltip-wcag-1413.md
new file mode 100644
index 0000000000..9694e891d8
--- /dev/null
+++ b/.changeset/tooltip-wcag-1413.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Tooltip: satisfy WCAG 1.4.13 (Content on Hover or Focus). Tooltips can now be dismissed with `Escape` while visible, and stay open when the pointer moves from the trigger onto the tooltip surface (a short hover bridge). `useLayer` context render props gain `onMouseEnter`/`onMouseLeave` on the layer container to support hoverable overlays.
+@cixzhang
diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx
index f08e7b0bfb..57c07867d6 100644
--- a/packages/core/src/Layer/useLayer.tsx
+++ b/packages/core/src/Layer/useLayer.tsx
@@ -99,6 +99,16 @@ export interface ContextRenderProps {
* @default 'div'
*/
as?: 'div' | 'span';
+ /**
+ * Pointer-enter handler attached to the popover container itself. Lets a
+ * consumer keep a hover-driven layer open while the pointer is over the
+ * surface (e.g. Tooltip/HoverCard "hoverable" behavior — WCAG 1.4.13).
+ */
+ onMouseEnter?: React.MouseEventHandler<HTMLElement>;
+ /**
+ * Pointer-leave handler attached to the popover container itself.
+ */
+ onMouseLeave?: React.MouseEventHandler<HTMLElement>;
}
/**
@@ -389,6 +399,8 @@ export function useLayer(
className: extraClassName,
style: extraStyle,
as: Container = 'div',
+ onMouseEnter,
+ onMouseLeave,
} = props || {};
// CSS anchor positioning (dynamic, not in StyleX)
@@ -413,7 +425,9 @@ export function useLayer(
role={role}
popover={lightDismiss ? 'auto' : 'manual'}
className={combinedClassName}
- style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
+ style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}
+ onMouseEnter={onMouseEnter}
+ onMouseLeave={onMouseLeave}>
{children}
</Container>
);
diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsx
index bd3067016f..7ce9f79713 100644
--- a/packages/core/src/Tooltip/Tooltip.test.tsx
+++ b/packages/core/src/Tooltip/Tooltip.test.tsx
@@ -153,4 +153,72 @@ describe('Tooltip', () => {
});
});
});
+
+ describe('WCAG 1.4.13 — content on hover or focus', () => {
+ it('dismisses on Escape while visible (dismissible)', async () => {
+ const onOpenChange = vi.fn();
+ render(
+ <Tooltip content="Dismiss me" onOpenChange={onOpenChange} delay={0}>
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ fireEvent.mouseEnter(trigger);
+ await waitFor(() => {
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+
+ fireEvent.keyDown(document, {key: 'Escape'});
+ await waitFor(() => {
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+ });
+
+ it('ignores Escape during IME composition', async () => {
+ const onOpenChange = vi.fn();
+ render(
+ <Tooltip content="Stay" onOpenChange={onOpenChange} delay={0}>
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ fireEvent.mouseEnter(trigger);
+ await waitFor(() => {
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+ onOpenChange.mockClear();
+
+ fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
+ // Give any (incorrect) async hide a chance to run.
+ await new Promise(r => setTimeout(r, 20));
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ });
+
+ it('stays open when the pointer moves onto the tooltip surface (hoverable)', async () => {
+ const onOpenChange = vi.fn();
+ render(
+ <Tooltip content="Hover me" onOpenChange={onOpenChange} delay={0}>
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ fireEvent.mouseEnter(trigger);
+ await waitFor(() => {
+ expect(onOpenChange).toHaveBeenCalledWith(true);
+ });
+ onOpenChange.mockClear();
+
+ // Pointer leaves the trigger but enters the tooltip surface before the
+ // hover-bridge grace period elapses — the tooltip must not hide.
+ fireEvent.mouseLeave(trigger);
+ const layer = screen.getByRole('tooltip', {hidden: true});
+ fireEvent.mouseEnter(layer);
+
+ await new Promise(r => setTimeout(r, 150));
+ expect(onOpenChange).not.toHaveBeenCalledWith(false);
+ });
+ });
});
diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx
index e66a30c9d6..bd74d332e8 100644
--- a/packages/core/src/Tooltip/useTooltip.tsx
+++ b/packages/core/src/Tooltip/useTooltip.tsx
@@ -37,6 +37,13 @@ import {
typeScaleVars,
} from '../theme/tokens.stylex';
+/**
+ * Grace period (ms) before hiding on pointer-leave when no explicit `hideDelay`
+ * is set, so the pointer can travel across the small gap from the trigger onto
+ * the tooltip surface without the tooltip disappearing (WCAG 1.4.13 hoverable).
+ */
+const HOVER_BRIDGE_DELAY = 100;
+
const styles = stylex.create({
// Base container styles - inverted colors for high contrast
container: {
@@ -291,21 +298,29 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
}, delay);
}, [isEnabled, isOpen, clearTimeouts, layer, delay]);
- // Schedule hide with delay (suppressed when isOpen is true)
+ // Schedule hide with delay (suppressed when isOpen is true).
+ // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
+ // trigger onto the tooltip surface without the tooltip vanishing — required
+ // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
const scheduleHide = useCallback(() => {
if (isOpen === true) {
return;
}
clearTimeouts();
- if (hideDelay > 0) {
- hideTimeoutRef.current = setTimeout(() => {
- layer.hide();
- }, hideDelay);
- } else {
+ const effectiveHideDelay = hideDelay > 0 ? hideDelay : HOVER_BRIDGE_DELAY;
+ hideTimeoutRef.current = setTimeout(() => {
layer.hide();
- }
+ }, effectiveHideDelay);
}, [isOpen, clearTimeouts, layer, hideDelay]);
+ // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
+ const cancelHide = useCallback(() => {
+ if (hideTimeoutRef.current) {
+ clearTimeout(hideTimeoutRef.current);
+ hideTimeoutRef.current = null;
+ }
+ }, []);
+
// Event handlers
const handleMouseEnter = useCallback(() => {
// Suppress tooltips on touch devices — hover is simulated and eats a tap
@@ -420,6 +435,32 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
}
}, [isOpen, clearTimeouts, layer]);
+ // Dismiss on Escape (WCAG 1.4.13 — dismissible). Uncontrolled tooltips only;
+ // a controlled tooltip's visibility is owned by the consumer. The listener is
+ // mounted for the lifetime of an uncontrolled tooltip rather than gated on
+ // `layer.isOpen` (React state, which can lag a frame behind the DOM) —
+ // `layer.hide()` self-guards and no-ops when the layer is already closed.
+ // Guarded against IME composition-cancel.
+ useEffect(() => {
+ if (isOpen !== undefined) {
+ return;
+ }
+ const handleKeyDown = (e: KeyboardEvent) => {
+ if (e.key !== 'Escape') {
+ return;
+ }
+ if (e.isComposing || e.keyCode === 229) {
+ return;
+ }
+ clearTimeouts();
+ layer.hide();
+ };
+ document.addEventListener('keydown', handleKeyDown);
+ return () => {
+ document.removeEventListener('keydown', handleKeyDown);
+ };
+ }, [isOpen, layer, clearTimeouts]);
+
// Render function that wraps layer.render with tooltip styling
const renderTooltip = useCallback(
(children: ReactNode, props?: ContextRenderProps): ReactNode => {
@@ -430,6 +471,12 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
role: 'tooltip',
xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
className: themeProps('tooltip').className,
+ // Keep the tooltip open while the pointer is over the surface itself
+ // (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,
};
return layer.render(
@@ -437,7 +484,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
renderProps,
);
},
- [layer, placement, alignment, popoverXstyle],
+ [layer, placement, alignment, popoverXstyle, cancelHide, scheduleHide],
);
return {