Skip to content

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

TypeScript

fix(Tooltip): a held-closed tooltip reports keyboard focus without opening (#10490)

Cindy Zhang48c480b60e1c
diff --git a/.changeset/tooltip-controlled-intent.md b/.changeset/tooltip-controlled-intent.md
new file mode 100644
index 0000000000..812ca5ca1f
--- /dev/null
+++ b/.changeset/tooltip-controlled-intent.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] A controlled `Tooltip` held closed (`isOpen={false}`) no longer opens on keyboard focus or a click into a text-field trigger. It reports that focus as `onOpenChange(true)` and shows nothing, so the caller decides, the same way Escape on a held-open tooltip reports `onOpenChange(false)` without hiding. Before, focus opened a held-closed tooltip anyway, and Escape could not close it. `useTooltip` reports the same focus through `onShow` under `isOpen={false}`.
+
+@cixzhang
diff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.md
index 321a2371aa..bacde9551c 100644
--- a/docs/specs/components/Tooltip/Tooltip.spec.md
+++ b/docs/specs/components/Tooltip/Tooltip.spec.md
@@ -48,7 +48,7 @@ system_specs: [spec:AST-003, spec:AST-017, spec:AST-086/FR12, spec:AST-086/FR14]
| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a tap that `touchTrigger` allows; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `touchTrigger="none"`, no touch or pen tap opens it. `useTooltip`'s `show()` pins it open until `hide()`, Escape, a press outside, or focus leaving, while hover and focus still preview an unpinned tooltip (FR9, FR12). `component:InfoTip`'s button pins and closes it on a click, tap, Enter, or Space. |
| End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. Under the default `touchTrigger="auto"`, a tap on a trigger that performs an action performs only that action. When a button pins it through `show()`, as `component:InfoTip`'s does, people on touch, keyboard, or a screen reader can keep help open to read it, and hear it once when it pins. |
| Builder impact | `touchTrigger` answers one question: is it safe to consume a tap to show this tooltip (DEC-1)? Keep the default `auto` on a trigger that performs an action, pass `tap` where a tap only reveals the tooltip, and pass `none` where a tap must never show it. Help behind an info icon uses `component:InfoTip`; an app's own toggle-style trigger is a button that calls `useTooltip`'s `show()` and `hide()` (DEC-1). The layer is always a scroll container (`overflow-y: auto`), so `position: sticky` and `scroll(nearest)` timelines inside its content resolve against the layer, not the page. |
-| Compatibility/readiness | `useTooltip` adds `show` and `hide` (FR12), an additive change. `touchTrigger` keeps its released values and its default `auto`, and pinning adds no public prop. Nine implementation gaps (see Current-state impact). |
+| Compatibility/readiness | `useTooltip` adds `show` and `hide` (FR12), an additive change. `touchTrigger` keeps its released values and its default `auto`, and pinning adds no public prop. Eight implementation gaps (see Current-state impact). |
| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a tap under `touchTrigger="auto"` that both performs the trigger's action and shows the tooltip, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a pinning trigger that is not a native button or lacks `aria-expanded`, or a toggle prop or option on Tooltip. |
| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (lifecycle); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
@@ -102,12 +102,6 @@ Consumer migration instructions belong in consumer docs and release notes.
inside an open Tooltip or HoverCard surface, as its documentation states;
Core's own containers rely on `architecture:layer-runtime` INV17 instead.
`CLN-0028` removes the registry and that answer.
-- **A held-closed tooltip still opens on focus.** With `isOpen={false}`, the
- hover path stays shut but any focus FR4 opens on, keyboard focus or a click
- into a text-field trigger, opens the tooltip and reports `onOpenChange(true)`, so a caller cannot hold it closed.
- Escape then only reports `onOpenChange(false)`, which the caller already
- holds, so the tooltip stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with
- a new `onOpenChange` (FR7).
- **Escape cannot close a tooltip in another document.** Tooltip listens for
Escape only in the page's document and its surface is a manual popover, so a
tooltip rendered into an iframe or a Picture-in-Picture window with no layer
@@ -179,7 +173,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR4 | Focus that a closing menu or other layer returns to its trigger after a pointer pick is pointer focus, so it opens no tooltip on that trigger (`architecture:interaction-modality` INV1). Focus that matches `:focus-visible` opens the tooltip per `focusTrigger`: keyboard focus, programmatic focus that follows keyboard input (AR4), pointer focus on a text-entry trigger, which browsers mark focus-visible, and programmatic focus on a text-entry trigger unless a finger or pen pressed that trigger and the last input was a pointer press, and on any other trigger unless the last input was a pointer (after keyboard input, as in AR4, or before any input). Implementation gap: script focus after a pointer press that focused nothing opens it, because the hook reads `:focus-visible` alone (Current-state impact). Focus a tap leaves behind, and other pointer focus, does not. Focus leaving the trigger schedules the hide as a pointer leave does. Under `focusTrigger="auto"`, focus opens the tooltip on any focusable trigger, judged when focus arrives. | Current source and tests |
| FR5 | On touch and pen, a completed tap opens the tooltip per `touchTrigger` when the finger lifts; a touch that becomes a scroll, or a press the browser does not count as a tap, does not open it. Under `auto`, a tap opens it unless the trigger itself performs an action; an `aria-disabled` control, or a label for a disabled control, is not an action, so a disabled control's reason opens on a tap, even inside a clickable row or card (DEC-1). Under `tap`, every tap opens it; under `none`, no tap does. A second tap on the trigger, a tap outside, or a scroll starting outside closes it. On a button that pins through `show()`, the button's click decides what a tap does (FR9). Whether `auto` also leaves the tooltip shut when the tap acts on a control around the trigger is open (OQ1). | Current source and tests |
| FR6 | Escape closes a visible tooltip; Escape during text composition is ignored. Escape routing follows `family:overlay-dismissal`: a visible topmost tooltip in the page handles that Escape, so a layer underneath stays open for that press. Implementation gap: a tooltip rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). `spec:AST-003` FR4, accepted and not yet implemented, makes an unpinned tooltip passive and gives a pinned one Escape first (Current-state impact). Outside a `show()` hold (FR12), pressing an uncontrolled tooltip's trigger closes it; a press that focuses a text-entry trigger reopens it through FR4. | WCAG 1.4.13; tests |
-| FR7 | `isOpen` forces the tooltip shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled tooltip answers Escape by calling `onOpenChange(false)` without hiding, and is not closed by pressing the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, any focus FR4 opens on, keyboard focus or a click into a text-field trigger, still opens the tooltip and reports `onOpenChange(true)`, and Escape then only reports `onOpenChange(false)`, so it stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with a new `onOpenChange` (Current-state impact). `isEnabled={false}` disables triggers and drops a pending open. A trigger whose caller removes it while disabling the tooltip closes its open, uncontrolled tooltip; when it attaches again enabled, the tooltip shows only for focus FR4 would open on. A trigger that detaches and attaches again while the tooltip stays enabled keeps the tooltip as it is. | Current source and tests |
+| FR7 | `isOpen` forces the tooltip shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled tooltip answers Escape by calling `onOpenChange(false)` without hiding, and is not closed by pressing the trigger. With `isOpen={false}`, focus FR4 opens on calls `onOpenChange(true)` and shows nothing. `isDefaultOpen` opens it on mount, still dismissible. `isEnabled={false}` disables triggers and drops a pending open. A trigger whose caller removes it while disabling the tooltip closes its open, uncontrolled tooltip; when it attaches again enabled, the tooltip shows only for focus FR4 would open on. A trigger that detaches and attaches again while the tooltip stays enabled keeps the tooltip as it is. | Current source and tests |
| FR8 | `onOpenChange` reports each show and hide. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |
| FR9 | A tooltip held open by `useTooltip`'s `show()` (FR12) is pinned. Tooltip has no toggle prop or option: a caller pins the tooltip by having its own native button call `show()` and `hide()`, as `component:InfoTip` does, so a click, a completed tap, Enter, or Space on that button pins the tooltip and the same press on a pinned tooltip closes it. Hover and keyboard focus still preview an unpinned tooltip per FR3 and FR4. A pinned tooltip stays open when the pointer leaves the trigger and the surface, and Tooltip's own press-to-close on the trigger leaves it open (FR6); Escape (FR6), `hide()`, such as the button's second press, a press outside the trigger and the surface, or focus moving outside them closes it. One internal owner per `useTooltip` call runs the `show()` hold and the touch trigger (FR5). | DEC-1; WCAG 1.4.13, 2.1.1 |
| FR10 | A button that pins the tooltip through `show()` and `hide()` carries, as its own attributes, FR2's `aria-describedby`, `aria-expanded` (`true` only while pinned), and `aria-controls` naming the surface while it shows (FR12); Tooltip writes no `aria-expanded` or `aria-controls` itself. When the tooltip pins, its text is announced once through a polite live region; a preview announces nothing beyond the description. | DEC-1; WAI-ARIA 1.2 `aria-expanded` |
@@ -197,8 +191,7 @@ Consumer migration instructions belong in consumer docs and release notes.
### Transformation and precedence order
-- **ORD1 — Open state.** `isOpen`, then the input triggers, apart from FR7's
- focus gap.
+- **ORD1 — Open state.** `isOpen`, then the input triggers.
### Performance and resources
@@ -210,8 +203,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **AR1 — Description.** The trigger's `aria-describedby` names the tooltip
(FR2), apart from FR2's changed-trigger gap.
- **AR2 — Content on hover or focus.** The tooltip is hoverable, dismissible,
- and persistent per WCAG 1.4.13 (FR3, FR6), except FR6's other-document gap and
- FR7's held-closed Escape gap.
+ and persistent per WCAG 1.4.13 (FR3, FR6), except FR6's other-document gap.
- **AR3 — Focus modality.** Only `:focus-visible` focus opens it (FR4).
- **AR4 — Focus return.** When closing a popover from the keyboard returns
focus to a trigger that carries a tooltip, the tooltip shows for that focus
@@ -219,8 +211,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **AR5 — Tooltip pattern.** The record adopts the APG tooltip pattern's parts:
`role="tooltip"`, the trigger's `aria-describedby`, showing on keyboard focus
and hiding when focus leaves, Escape dismissal, and showing on hover and
- hiding on leave (FR1–FR4, FR6), with FR6's other-document gap and FR7's
- held-closed Escape gap as the exceptions to Escape dismissal. Hiding when focus leaves, showing on hover,
+ hiding on leave (FR1–FR4, FR6), with FR6's other-document gap as the exception to Escape dismissal. Hiding when focus leaves, showing on hover,
and hiding on leave go beyond the required parts `spec:AST-020` FR15 adopts
and are this record's named exception, kept because they ship.
- **AR6 — A pinned tooltip is a toggletip.** When a button pins the tooltip
@@ -267,6 +258,7 @@ has no arrow element.
| FR1 scroll container | `TooltipTallContent.a11y.browser.spec.ts` sticky case | A tall tooltip whose content starts with a `position: sticky` child, scrolled inside | The sticky child scrolls away with the content, or pins to the page instead of the tooltip | — |
| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open; `auto` judged when focus arrives (roving member, `<summary>`, non-focusable wrapper) | Wrong open or close for an input fails. | `audit:Tooltip/behavior` |
| FR4, FR7 reattach | `useTooltip.test.tsx` detach-and-attach suite; `DropdownMenuTooltip.a11y.chromium.spec.ts` | A trigger that detaches while open; keyboard and pointer focus that arrive while detached; a data menu, a compound menu and a bottom sheet: a pointer pick, a keyboard pick, and Escape | A tooltip left open after its trigger detaches, a tooltip after a pointer pick, or none for returned keyboard focus, fails. | `audit:Tooltip/behavior` |
+| FR7 held closed | `Tooltip.test.tsx` controlled suite; `useTooltip.test.tsx` controlled suite | With `isOpen={false}`, keyboard focus; with `isOpen={true}`, Escape and a pointer leave | A held-closed tooltip that shows on focus, or reports focus other than one `onOpenChange(true)`, fails; Escape on a held-open tooltip that hides it, or a pointer leave that hides it, fails. | `audit:Tooltip/behavior` |
| AR1–AR4 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts`; `TooltipHoverBridge.a11y.chromium.spec.ts`; `TooltipFocusReturn.a11y.chromium.spec.ts` | Real-browser hover bridge and focus return | A tooltip that vanishes on the way to it or strands focus fails. | `audit:Tooltip/accessibility` |
| AR5 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts` | Wrapped, text, anchor, and hook triggers | A lost role, description, keyboard-focus show, or Escape dismissal fails; focus-leave hide, hover show, and leave hide run as advisory rows (Current-state impact). | `audit:Tooltip/accessibility` |
| FR5 | `Tooltip.test.tsx` touch suite; `TouchTrigger.a11y.chromium.spec.ts` finger and pen cases; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases | Tap open, scroll, second tap, tap outside; `touchTrigger` `auto`, `tap`, and `none`; an action trigger and a trigger that performs no action; a trigger in running text; a disabled control inside a clickable row | A tap that fails to open or close as stated, opens the tooltip on a trigger that performs an action under `auto` or on any tap under `none`, or leaves a disabled control's reason shut fails. | `audit:Tooltip/behavior` |
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index a4125c6926..68c4a63029 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -135,7 +135,8 @@ export const docs = {
{
name: 'isOpen',
type: 'boolean',
- description: 'Controlled open state for the tooltip.',
+ description:
+ 'Controlled open state for the tooltip. Held closed, focus that would open it calls onOpenChange(true) and shows nothing; held open, Escape calls onOpenChange(false) and it stays.',
},
],
},
diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsx
index bdae9653f3..6b61848fa5 100644
--- a/packages/core/src/Tooltip/Tooltip.test.tsx
+++ b/packages/core/src/Tooltip/Tooltip.test.tsx
@@ -353,6 +353,51 @@ describe('Tooltip', () => {
});
describe('controlled', () => {
+ /** Whether the tooltip's layer is open. */
+ const isShown = () =>
+ screen
+ .getByRole('tooltip', {hidden: true})
+ .closest<HTMLElement>('[popover]')
+ ?.matches(':popover-open') ?? false;
+
+ it('reports keyboard-focus intent once while held closed, and shows nothing', async () => {
+ const onOpenChange = vi.fn();
+ render(
+ <Tooltip
+ content="Held"
+ isOpen={false}
+ onOpenChange={onOpenChange}
+ delay={0}>
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ const realMatches = trigger.matches.bind(trigger);
+ vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
+ selector === ':focus-visible' ? true : realMatches(selector),
+ );
+ fireEvent.keyDown(document, {key: 'Tab'});
+ fireEvent.focusIn(trigger);
+ await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(true));
+ await new Promise(r => setTimeout(r, 20));
+ expect(onOpenChange).toHaveBeenCalledTimes(1);
+ expect(isShown()).toBe(false);
+ });
+
+ it('reports Escape as onOpenChange(false) while held open, and stays shown', async () => {
+ const onOpenChange = vi.fn();
+ render(
+ <Tooltip content="Held" isOpen onOpenChange={onOpenChange} delay={0}>
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+ await waitFor(() => expect(isShown()).toBe(true));
+ onOpenChange.mockClear();
+ fireEvent.keyDown(document, {key: 'Escape'});
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ expect(isShown()).toBe(true);
+ });
+
// Escape asks a controlled tooltip to close by calling this same handler,
// so a consumer who complies sees the request and then this echo. Pinning
// the echo here keeps the two straight.
diff --git a/packages/core/src/Tooltip/Tooltip.tsx b/packages/core/src/Tooltip/Tooltip.tsx
index 768c2f26e9..3b0dec680e 100644
--- a/packages/core/src/Tooltip/Tooltip.tsx
+++ b/packages/core/src/Tooltip/Tooltip.tsx
@@ -151,6 +151,10 @@ export interface TooltipProps {
* answers by calling `onOpenChange(false)` without hiding itself — closing is
* your update's decision, exactly as for a controlled Dialog. Ignore the call
* and the tip stays, and so does the press: nothing underneath dismisses.
+ *
+ * The same holds for focus held closed: focus that would open the tooltip
+ * calls `onOpenChange(true)` and shows nothing until your update sets
+ * `isOpen`.
*/
isOpen?: boolean;
diff --git a/packages/core/src/Tooltip/useTooltip.doc.mjs b/packages/core/src/Tooltip/useTooltip.doc.mjs
index 68d9e30af0..e24dcc24f8 100644
--- a/packages/core/src/Tooltip/useTooltip.doc.mjs
+++ b/packages/core/src/Tooltip/useTooltip.doc.mjs
@@ -58,7 +58,7 @@ export const docs = {
name: 'isOpen',
type: 'boolean',
description:
- 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+ 'Controlled open state. true force-shows; false force-hides, and focus that would show it calls onShow; undefined lets hover/focus manage visibility.',
},
{
name: 'isDefaultOpen',
@@ -69,7 +69,8 @@ export const docs = {
{
name: 'onShow',
type: '() => void',
- description: 'Callback fired when the tooltip becomes visible.',
+ description:
+ 'Callback fired when the tooltip becomes visible. Under isOpen={false}, it reports focus that would show the tooltip.',
},
{
name: 'onHide',
diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx
index cbf9c8e212..3a60bc3f6d 100644
--- a/packages/core/src/Tooltip/useTooltip.tsx
+++ b/packages/core/src/Tooltip/useTooltip.tsx
@@ -150,7 +150,8 @@ export interface TooltipOptions {
/**
* Controlled open state. When provided, overrides hover/focus triggers:
* - `true`: force-show the tooltip (hover/focus hide is suppressed)
- * - `false`: force-hide the tooltip
+ * - `false`: force-hide the tooltip. Focus that would show it calls
+ * `onShow` and shows nothing.
* - `undefined`: uncontrolled — hover/focus triggers manage visibility
*
* A controlled tooltip still takes Escape when it is the top-most layer, and
@@ -167,7 +168,8 @@ export interface TooltipOptions {
isDefaultOpen?: boolean;
/**
- * Callback fired when tooltip is shown.
+ * Callback fired when tooltip is shown. Under `isOpen={false}`, it reports
+ * focus that would show the tooltip.
* Wrap in useCallback for stable identity.
*/
onShow?: () => void;
@@ -573,6 +575,13 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
return;
}
clearTimeouts();
+ // Held closed, the focus reports through onShow and shows nothing. The
+ // caller decides.
+ const latest = latestRef.current;
+ if (latest.isOpen === false) {
+ latest.onShow?.();
+ return;
+ }
showLayer();
},
[