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.mdnew file mode 100644index 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}`.++@cixzhangdiff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.mdindex 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 forEscape only in the page's document and its surface is a manual popover, so atooltip 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 returnsfocus 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 focusand 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 adoptsand 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.mjsindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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();},[