An open source design system that's fully customizable and agent ready
TypeScript
fix(Tooltip, HoverCard): a disabled control's reason opens on a tap (#8207)
Christopher Chedeau97b3711d6826
diff --git a/.changeset/hover-layers-disabled-reason-tap.md b/.changeset/hover-layers-disabled-reason-tap.mdnew file mode 100644index 0000000000..f1ad87acf8--- /dev/null+++ b/.changeset/hover-layers-disabled-reason-tap.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Tooltip and HoverCard: a tap on a disabled `Button`, `IconButton` or `ToggleButton`, or a disabled menu item, now opens the tooltip that explains why it is disabled, and nothing activates. Before, with `touchTrigger="auto"` (the default), the tap counted as the control's own action, so on a touch screen the disabled reason could not be reached (`spec:AST-085` FR5, `architecture:interaction-modality` INV4). An `aria-disabled` control now performs no action, and a tap on a label for a disabled control opens its reason too. A tap on a disabled control inside another acting trigger, such as an option row or a link-role card, now opens that trigger's tooltip or hover card. Taps on enabled controls, `touchTrigger="tap"` and `"none"`, and mouse hover are unchanged.++@vjeuxdiff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 610ef70a21..8240f0faff 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -104,7 +104,7 @@ export const docs = {name: 'touchTrigger',type: "'auto' | 'tap' | 'none'",description:- 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens. none never opens on touch. A tap-opened card is dismissed by a tap outside it.',+ 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens. none never opens on touch. A tap-opened card is dismissed by a tap outside it.',default: "'auto'",},{@@ -289,7 +289,7 @@ export const docsZh = {name: 'touchTrigger',type: "'auto' | 'tap' | 'none'",description:- '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有。tap:始终轻点打开。none:触摸永不打开。轻点打开的卡片可通过点击卡片外部关闭。',+ '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有;设置了 aria-disabled 的控件不执行操作,因此轻点它会显示其原因。tap:始终轻点打开。none:触摸永不打开。轻点打开的卡片可通过点击卡片外部关闭。',default: "'auto'",},{@@ -439,7 +439,7 @@ export const docsDense = {hideDelay: 'Hide delay in ms.',focusTrigger: 'Controls when focus events trigger hover card.',touchTrigger:- 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',+ 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',isEnabled: 'Enable/disable hover + focus triggers.',label:'Accessible name for the popup. With label: named role="dialog"; without: role="group".',diff --git a/packages/core/src/HoverCard/HoverCard.spec.md b/packages/core/src/HoverCard/HoverCard.spec.mdindex f170195ab0..1360e3fa4d 100644--- a/packages/core/src/HoverCard/HoverCard.spec.md+++ b/packages/core/src/HoverCard/HoverCard.spec.md@@ -14,6 +14,8 @@ verified_by:[packages/core/src/HoverCard/HoverCard.test.tsx,packages/core/src/Layer/layerDismissalFamilies.test.tsx,+ packages/core/src/Layer/useTouchTrigger.test.ts,+ packages/core/src/Layer/touchTriggerTargets.test.tsx,apps/storybook/stories/HoverCard.stories.tsx,scripts/check-knowledge.mjs,]@@ -161,7 +163,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element inside an inline-safe wrapper. | Current source and tests || FR3 | With `label`, the card is `role="dialog"` named by `label`; the trigger gets `aria-haspopup="dialog"` and, only when its role supports it, `aria-expanded`, each replacing the trigger's own value while the card is wired, plus `aria-controls` naming the card while open, merged with the trigger's own; the trigger's own values return on cleanup. Without `label`, the card is `role="group"` and the trigger's `aria-describedby` gains the card's id. | Current source and tests || FR4 | On a hover-capable pointer, entering the trigger opens the card after `delay` ms; leaving the trigger or the card closes it after `hideDelay` ms, and moving between them keeps it open. Any focus on the trigger, keyboard, pointer, or programmatic, opens it per `focusTrigger`, except the focus a tap leaves behind, the refocus after an Escape dismiss (FR6), and the refocus after a controlled close (FR7). Implementation gap: under `auto` the tab order is read only when the trigger's listeners attach, on mount and on a re-render that re-attaches them, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | WCAG 1.4.13; tests |-| FR5 | On touch, a completed tap opens it per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. Under `auto`, a tap that already acts leaves it shut, decided as `component:Tooltip` DEC-1 decides it: the innermost control from the tapped element outward, the trigger included, decides, and a disabled or `aria-disabled` control is not an action (DEC-1). Implementation gap: the walk ships with `component:Tooltip` CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A tap on the card's own content keeps it open; a second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | Current source and tests |+| FR5 | On touch, a completed tap opens it per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. Under `auto`, a tap that already acts leaves it shut, decided as `component:Tooltip` DEC-1 decides it: the innermost control from the tapped element outward, the trigger included, decides, and an `aria-disabled` control, or a label for a disabled control, is not an action (DEC-1). Implementation gap: the walk ships with `component:Tooltip` CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A tap on the card's own content keeps it open; a second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | Current source and tests || FR6 | Escape closes a visible card through the shared dismissal stack when it is the topmost layer in the page, so a layer underneath stays open. Implementation gap: a card 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). When focus was inside the card, it returns to the trigger, and that refocus does not reopen the card. | WCAG 1.4.13; tests || FR7 | `isOpen` forces the card shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled card answers Escape by calling `onOpenChange(false)` without hiding, and setting `isOpen={false}` while focus is inside the card returns focus to the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, focus on the trigger still opens the card, and Escape then only reports `onOpenChange(false)` (Current-state impact). `isEnabled={false}` disables the triggers. `onOpenChange` reports each show and hide. | Current source and tests || FR8 | Content renders only while open; server markup and the first client render match, including a default-open card. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger. | Current source and tests |@@ -248,14 +250,14 @@ Consumer migration instructions belong in consumer docs and release notes.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |-| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails. | `audit:HoverCard/anatomy` |-| FR3, AR1 | `HoverCard.test.tsx` role and trigger-attribute tests | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |-| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests; tap-destination cases an evidence gap until built | Hover, focus, tap, Escape from trigger and content; a trigger inside a link or a clickable card; a disabled control inside a clickable row | A card that cannot be reached or dismissed, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |-| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open | Wrong state reporting fails. | `audit:HoverCard/behavior` |-| FR9, FR10, AR3 | Evidence gap until built: a press-toggle suite in `HoverCard.test.tsx` and a controlled pinned case in `layerDismissalFamilies.test.tsx` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave and presses on the card keep the pin; labelled and unlabelled; non-button trigger; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:HoverCard/behavior` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | `audit:HoverCard/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails. | `audit:HoverCard/anatomy` |+| FR3, AR1 | `HoverCard.test.tsx` role and trigger-attribute tests | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |+| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases; tap-destination cases an evidence gap until built | Hover, focus, tap, Escape from trigger and content; a trigger inside a link or a clickable card; a disabled control inside a clickable row | A card that cannot be reached or dismissed, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |+| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open | Wrong state reporting fails. | `audit:HoverCard/behavior` |+| FR9, FR10, AR3 | Evidence gap until built: a press-toggle suite in `HoverCard.test.tsx` and a controlled pinned case in `layerDismissalFamilies.test.tsx` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave and presses on the card keep the pin; labelled and unlabelled; non-button trigger; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:HoverCard/behavior` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | `audit:HoverCard/theming` |Read from source, with no focused test yet:@@ -282,11 +284,11 @@ information, such as a timestamp's details. `touchTrigger="auto"`, thedefault until `touchTrigger` folds into `pressTrigger` at the next minor, isthe fallback: under it, a tap that already acts does not open the card. Thewalk that decides it starts at the tapped element and the innermost control-decides; a disabled or `aria-disabled` control is not an action; and an-element that acts only through a role-less `onClick` is a caller fix, as-`component:Tooltip` DEC-1 states. The deprecation of `touchTrigger="tap"` and-the fold are `component:Tooltip` DEP-0016 and CLN-0024, which apply here-unchanged.+decides; an `aria-disabled` control, or a label for a disabled control, is not+an action; and an element that acts only through a role-less `onClick` is a+caller fix, as `component:Tooltip` DEC-1 states. The deprecation of+`touchTrigger="tap"` and the fold are `component:Tooltip` DEP-0016 and CLN-0024,+which apply here unchanged.Rejected: judging the trigger alone, which lets one tap open a name's card overthe card the same tap opened.diff --git a/packages/core/src/HoverCard/useHoverCard.doc.mjs b/packages/core/src/HoverCard/useHoverCard.doc.mjsindex 4c6c8ee456..0623a46cff 100644--- a/packages/core/src/HoverCard/useHoverCard.doc.mjs+++ b/packages/core/src/HoverCard/useHoverCard.doc.mjs@@ -12,7 +12,7 @@ export const docs = {{name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},{name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},{name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},- {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens; none never opens on touch.', default: "'auto'"},+ {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch.', default: "'auto'"},{name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},{name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},{name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},diff --git a/packages/core/src/Layer/touchTriggerTargets.test.tsx b/packages/core/src/Layer/touchTriggerTargets.test.tsxnew file mode 100644index 0000000000..2aa2ffe7ce--- /dev/null+++ b/packages/core/src/Layer/touchTriggerTargets.test.tsx@@ -0,0 +1,592 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file touchTriggerTargets.test.tsx+ * @input Uses every Core component that shows a disabled reason in a tooltip+ * (Button, IconButton and ToggleButton through `tooltip`; the form+ * controls through `disabledMessage`), DropdownMenuItem, ClickableCard and+ * Tooltip, under a finger's tap in jsdom+ * @output Proof that under touchTrigger="auto" a tap on a disabled control+ * opens its disabled-reason tooltip and nothing activates, also inside a+ * clickable row or card, while a tap on an enabled control is left to the+ * trigger as before+ * @position Unit tests beside useTouchTrigger; the rule's own rows are in+ * useTouchTrigger.test.ts+ */++import type {MouseEvent, ReactElement} from 'react';+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import {Button} from '../Button/Button';+import {IconButton} from '../IconButton/IconButton';+import {ToggleButton} from '../ToggleButton/ToggleButton';+import {CheckboxInput} from '../CheckboxInput/CheckboxInput';+import {CheckboxList} from '../CheckboxList/CheckboxList';+import {CheckboxListItem} from '../CheckboxList/CheckboxListItem';+import {DateInput} from '../DateInput/DateInput';+import {DateRangeInput} from '../DateRangeInput/DateRangeInput';+import {DateTimeInput} from '../DateTimeInput/DateTimeInput';+import {FileInput} from '../FileInput/FileInput';+import {MultiSelector} from '../MultiSelector/MultiSelector';+import {NumberInput} from '../NumberInput/NumberInput';+import {PowerSearch} from '../PowerSearch/PowerSearch';+import type {PowerSearchConfig} from '../PowerSearch/types';+import {RadioList} from '../RadioList/RadioList';+import {RadioListItem} from '../RadioList/RadioListItem';+import {SegmentedControl} from '../SegmentedControl/SegmentedControl';+import {SegmentedControlItem} from '../SegmentedControl/SegmentedControlItem';+import {Selector} from '../Selector/Selector';+import {Slider} from '../Slider/Slider';+import {Switch} from '../Switch/Switch';+import {TextArea} from '../TextArea/TextArea';+import {TextInput} from '../TextInput/TextInput';+import {TimeInput} from '../TimeInput/TimeInput';+import {Tokenizer} from '../Tokenizer/Tokenizer';+import {Typeahead} from '../Typeahead/Typeahead';+import type {SearchSource, SearchableItem} from '../Typeahead/types';+import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';+import {ClickableCard} from '../ClickableCard/ClickableCard';+import {Overlay} from '../Overlay/Overlay';+import {HoverCard} from '../HoverCard/HoverCard';+import {Tooltip} from '../Tooltip/Tooltip';+import {__resetInteractionModalityForTest} from '../utils/interactionModality';++const originalShowPopover = HTMLElement.prototype.showPopover;+const originalHidePopover = HTMLElement.prototype.hidePopover;+const originalMatches = HTMLElement.prototype.matches;++beforeEach(() => {+ __resetInteractionModalityForTest();+ // jsdom has no Popover API: keep the open state where the test reads it.+ HTMLElement.prototype.showPopover = function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ };+ HTMLElement.prototype.hidePopover = function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ };+ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ (HTMLElement.prototype as any).matches = function (+ this: HTMLElement,+ selector: string,+ ): boolean {+ return selector === ':popover-open'+ ? this.hasAttribute('popover-open')+ : originalMatches.call(this, selector);+ };+});++afterEach(() => {+ HTMLElement.prototype.showPopover = originalShowPopover;+ HTMLElement.prototype.hidePopover = originalHidePopover;+ HTMLElement.prototype.matches = originalMatches;+});++/** A finger's tap on `element`, in the order a browser dispatches it. */+function tap(element: HTMLElement) {+ fireEvent.pointerEnter(element, {pointerType: 'touch'});+ fireEvent.pointerDown(element, {pointerType: 'touch'});+ fireEvent.pointerUp(element, {pointerType: 'touch'});+ fireEvent.mouseEnter(element);+ fireEvent.click(element);+}++/** The tooltip holding `text`. */+function layerOf(text: string): HTMLElement | null {+ return (+ screen+ .queryByText(text, {exact: false})+ ?.closest<HTMLElement>('[popover]') ?? null+ );+}++/** Whether the tooltip holding `text` is open. */+function isOpen(text: string): boolean {+ return layerOf(text)?.hasAttribute('popover-open') === true;+}++/**+ * The control a disabled reason describes: the element whose+ * `aria-describedby` names the reason's tooltip, which is what a finger taps.+ */+function controlDescribedBy(reason: string): HTMLElement {+ const layer = layerOf(reason);+ const id = layer?.id;+ if (id == null || id === '') {+ throw new Error(`no tooltip with an id holds "${reason}"`);+ }+ const control = Array.from(+ document.querySelectorAll<HTMLElement>('[aria-describedby]'),+ ).find(element =>+ (element.getAttribute('aria-describedby') ?? '').split(/\s+/).includes(id),+ );+ if (control == null) {+ throw new Error(`nothing is described by the tooltip holding "${reason}"`);+ }+ return control;+}++const fruits: SearchableItem[] = [+ {id: '1', label: 'Apple'},+ {id: '2', label: 'Banana'},+];+const fruitSource: SearchSource = {+ search: (query: string) =>+ fruits.filter(f => f.label.toLowerCase().includes(query.toLowerCase())),+ bootstrap: () => fruits,+};+const searchConfig: PowerSearchConfig = {+ name: 'Issues',+ fields: [+ {+ key: 'title',+ label: 'Title',+ defaultOperator: 'contains',+ operators: [+ {key: 'contains', label: 'contains', value: {type: 'string'}},+ ],+ },+ ],+};++type DisabledReasonCase = {+ name: string;+ reason: string;+ /** Renders the component disabled with `reason`; `act` is its action. */+ renderDisabled: (reason: string, act: () => void) => ReactElement;+};++const DISABLED_REASON_CASES: DisabledReasonCase[] = [+ // A disabled Link is not listed: it takes no pointer events+ // (component:Link FR5), so a tap never reaches it.+ {+ name: 'Button',+ reason: 'You need the Editor role to publish',+ renderDisabled: (reason, act) => (+ <Button label="Publish" isDisabled tooltip={reason} onClick={act} />+ ),+ },+ {+ name: 'IconButton',+ reason: 'Only the owner can delete this file',+ renderDisabled: (reason, act) => (+ <IconButton+ label="Delete"+ icon="info"+ isDisabled+ tooltip={reason}+ onClick={act}+ />+ ),+ },+ {+ name: 'ToggleButton',+ reason: 'Formatting is off in plain-text mode',+ renderDisabled: (reason, act) => (+ <ToggleButton+ label="Bold"+ isDisabled+ tooltip={reason}+ onPressedChange={act}+ />+ ),+ },+ {+ name: 'CheckboxInput',+ reason: 'Terms are managed by your administrator',+ renderDisabled: (reason, act) => (+ <CheckboxInput+ label="Accept terms"+ value={false}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'CheckboxList',+ reason: 'Notifications are managed by your administrator',+ renderDisabled: (reason, act) => (+ <CheckboxList+ label="Notifications"+ value={['email']}+ onChange={act}+ isDisabled+ disabledMessage={reason}>+ <CheckboxListItem label="Email" value="email" />+ <CheckboxListItem label="SMS" value="sms" />+ </CheckboxList>+ ),+ },+ {+ name: 'DateInput',+ reason: 'Scheduling is locked',+ renderDisabled: (reason, act) => (+ <DateInput+ label="Date"+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'DateRangeInput',+ reason: 'The reporting period is fixed',+ renderDisabled: (reason, act) => (+ <DateRangeInput+ label="Range"+ value={null}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'DateTimeInput',+ reason: 'The launch time is locked',+ renderDisabled: (reason, act) => (+ <DateTimeInput+ label="When"+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'FileInput',+ reason: 'You need the Editor role to upload',+ renderDisabled: (reason, act) => (+ <FileInput+ label="Resume"+ value={null}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'MultiSelector',+ reason: 'Select a table first',+ renderDisabled: (reason, act) => (+ <MultiSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange']}+ value={[]}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'NumberInput',+ reason: 'Quantity is fixed by the contract',+ renderDisabled: (reason, act) => (+ <NumberInput+ label="Quantity"+ value={42}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'PowerSearch',+ reason: 'You need edit access to search',+ renderDisabled: (reason, act) => (+ <PowerSearch+ config={searchConfig}+ filters={[]}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'RadioList',+ reason: 'Upgrade your account to change plans',+ renderDisabled: (reason, act) => (+ <RadioList+ label="Plan"+ value="free"+ onChange={act}+ isDisabled+ disabledMessage={reason}>+ <RadioListItem label="Free" value="free" />+ <RadioListItem label="Pro" value="pro" />+ </RadioList>+ ),+ },+ {+ name: 'SegmentedControl',+ reason: 'Choose a project to switch views',+ renderDisabled: (reason, act) => (+ <SegmentedControl+ value="grid"+ onChange={act}+ label="View mode"+ isDisabled+ disabledMessage={reason}>+ <SegmentedControlItem value="grid" label="Grid" />+ <SegmentedControlItem value="list" label="List" />+ </SegmentedControl>+ ),+ },+ {+ name: 'Selector',+ reason: 'Ask an admin to change the fruit',+ renderDisabled: (reason, act) => (+ <Selector+ label="Fruit"+ options={['Apple', 'Banana', 'Cherry']}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'Slider',+ reason: 'Volume is locked while sharing your screen',+ renderDisabled: (reason, act) => (+ <Slider+ label="Volume"+ value={50}+ onChange={act}+ valueDisplay="none"+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'Switch',+ reason: 'Notifications are turned off for your organization',+ renderDisabled: (reason, act) => (+ <Switch+ label="Notifications"+ value={false}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'TextArea',+ reason: 'Notes are locked while the review is open',+ renderDisabled: (reason, act) => (+ <TextArea+ label="Notes"+ value="hello"+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'TextInput',+ reason: 'You need the Editor role to change this',+ renderDisabled: (reason, act) => (+ <TextInput+ label="Owner"+ value="alice"+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'TimeInput',+ reason: 'Time edits are locked',+ renderDisabled: (reason, act) => (+ <TimeInput+ label="Start time"+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'Tokenizer',+ reason: 'Tags are locked while syncing',+ renderDisabled: (reason, act) => (+ <Tokenizer+ label="Tags"+ searchSource={fruitSource}+ value={[]}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+ {+ name: 'Typeahead',+ reason: 'You need the Editor role to assign',+ renderDisabled: (reason, act) => (+ <Typeahead+ label="Assignee"+ searchSource={fruitSource}+ value={null}+ onChange={act}+ isDisabled+ disabledMessage={reason}+ />+ ),+ },+];++describe('a tap on a disabled control opens its disabled-reason tooltip, and nothing activates', () => {+ it.each(DISABLED_REASON_CASES)('$name', async ({reason, renderDisabled}) => {+ const act = vi.fn();+ render(renderDisabled(reason, act));+ const control = controlDescribedBy(reason);++ tap(control);++ await waitFor(() => {+ expect(isOpen(reason)).toBe(true);+ });+ expect(act).not.toHaveBeenCalled();+ expect(control).not.toHaveAttribute('aria-expanded', 'true');+ });++ it('a disabled menu item, through a caller tooltip (menu items have no reason prop)', async () => {+ const onClick = vi.fn();+ render(+ <ul role="menu">+ <Tooltip content="Ask an admin to delete projects">+ <DropdownMenuItem+ label="Delete project"+ isDisabled+ onClick={onClick}+ />+ </Tooltip>+ </ul>,+ );++ tap(+ screen+ .getByText('Delete project')+ .closest('[role="menuitem"]') as HTMLElement,+ );++ await waitFor(() => {+ expect(isOpen('Ask an admin to delete projects')).toBe(true);+ });+ expect(onClick).not.toHaveBeenCalled();+ });+});++describe('a disabled field inside a clickable card or row', () => {+ it("opens the field's reason on a tap, and neither the field nor the row activates", async () => {+ const onRowClick = vi.fn();+ const onChange = vi.fn();+ render(+ <ClickableCard label="Billing contact" onClick={onRowClick}>+ <TextInput+ label="Email"+ value="[email protected]"+ onChange={onChange}+ isDisabled+ disabledMessage="Only an owner can change the billing contact"+ />+ </ClickableCard>,+ );+ const field = screen.getByRole('textbox', {name: /Email/});++ tap(field);++ await waitFor(() => {+ expect(isOpen('Only an owner can change the billing contact')).toBe(true);+ });+ expect(onRowClick).not.toHaveBeenCalled();+ expect(onChange).not.toHaveBeenCalled();+ expect(field).toHaveValue('[email protected]');+ });+});++describe('a tap on an enabled control is left to the trigger, as before', () => {+ it('a tap inside a default Overlay within a link leaves the link’s tooltip shut, as before, and the link runs', async () => {+ const follow = vi.fn((event: MouseEvent) => event.preventDefault());+ render(+ <Tooltip content="Open the full report">+ <a href="/report" onClick={follow}>+ <Overlay content={<span>Caption</span>}>+ <span>Q3 report</span>+ </Overlay>+ </a>+ </Tooltip>,+ );+ tap(screen.getByText('Q3 report'));+ expect(follow).toHaveBeenCalledTimes(1);+ await new Promise(resolve => setTimeout(resolve, 50));+ expect(isOpen('Open the full report')).toBe(false);+ });++ it('a truncated label inside a link still opens its tooltip, and the link still runs', async () => {+ const follow = vi.fn((event: MouseEvent) => event.preventDefault());+ render(+ <a href="/doc" onClick={follow}>+ <Tooltip content="A very long document title">+ <span>A very long document…</span>+ </Tooltip>+ </a>,+ );+ tap(screen.getByText('A very long document…'));+ await waitFor(() => {+ expect(isOpen('A very long document title')).toBe(true);+ });+ expect(follow).toHaveBeenCalledTimes(1);+ });+});++describe('HoverCard: a disabled control performs no action', () => {+ it('a tap on an aria-disabled trigger opens its hover card, and nothing activates', async () => {+ const onOpenChange = vi.fn();+ const publish = vi.fn();+ render(+ <HoverCard+ content={<span>Publishing needs an editor</span>}+ onOpenChange={onOpenChange}+ delay={0}>+ <button type="button" aria-disabled="true" onClick={publish}>+ Publish+ </button>+ </HoverCard>,+ );+ tap(screen.getByRole('button', {name: 'Publish'}));+ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });+ });++ it('a tap on a disabled checkbox inside an option-row trigger opens the row’s hover card', async () => {+ const onOpenChange = vi.fn();+ render(+ <HoverCard+ content={<span>Archived projects cannot be selected</span>}+ onOpenChange={onOpenChange}+ delay={0}>+ <div role="option" aria-selected={false} tabIndex={0}>+ <input type="checkbox" aria-disabled="true" aria-label="Apollo" />+ Apollo+ </div>+ </HoverCard>,+ );+ tap(screen.getByRole('checkbox', {name: 'Apollo'}));+ await waitFor(() => {+ expect(onOpenChange).toHaveBeenCalledWith(true);+ });+ });+});diff --git a/packages/core/src/Layer/useTouchTrigger.test.ts b/packages/core/src/Layer/useTouchTrigger.test.tsindex 930714463e..092a046945 100644--- a/packages/core/src/Layer/useTouchTrigger.test.ts+++ b/packages/core/src/Layer/useTouchTrigger.test.ts@@ -2,9 +2,11 @@/*** @file useTouchTrigger.test.ts- * @input Uses vitest, Testing Library, isActionTrigger, useTapStop- * @output Unit tests for the action-trigger rule behind touchTrigger="auto"- * and for the tap stop a reveal-only trigger uses+ * @input Uses vitest, Testing Library, isActionTrigger,+ * tapLandsOnDisabledControl, useTapStop+ * @output Unit tests for the action rules behind touchTrigger="auto" (the+ * trigger's own action, and a tap that lands in a disabled control) and for+ * the tap stop a reveal-only trigger uses* @position Testing; validates useTouchTrigger.ts implementation** SYNC: When useTouchTrigger.ts changes, update tests to match new behavior@@ -17,7 +19,11 @@import {createElement} from 'react';import {fireEvent, render, screen} from '@testing-library/react';import {describe, it, expect} from 'vitest';-import {isActionTrigger, useTapStop} from './useTouchTrigger';+import {+ isActionTrigger,+ tapLandsOnDisabledControl,+ useTapStop,+} from './useTouchTrigger';function element(html: string): HTMLElement {const host = document.createElement('div');@@ -110,3 +116,85 @@ describe('useTapStop', () => {expect(fireEvent.click(trigger)).toBe(true);});});++describe('isActionTrigger: a disabled control', () => {+ it.each([+ ['<button type="button" aria-disabled="true">Publish</button>'],+ ['<button type="button" disabled>Publish</button>'],+ ['<a href="/archive" aria-disabled="true">Archive</a>'],+ ['<div role="menuitem" aria-disabled="true">Delete</div>'],+ ['<input type="checkbox" role="switch" aria-disabled="true" />'],+ ])('is no action: %s', html => {+ const host = document.createElement('div');+ host.innerHTML = html;+ expect(isActionTrigger(host.firstElementChild as HTMLElement)).toBe(false);+ });++ it('makes the label around it no action', () => {+ const host = document.createElement('div');+ host.innerHTML =+ '<label><input type="checkbox" aria-disabled="true" /> Notify</label>';+ document.body.append(host);+ expect(isActionTrigger(host.querySelector('label') as HTMLElement)).toBe(+ false,+ );+ host.remove();+ });+});++/** The element a tap lands on: the one marked `data-tapped`, else the trigger. */+function tappedIn(html: string): HTMLElement {+ const host = document.createElement('div');+ host.innerHTML = html;+ return (host.querySelector('[data-tapped]') ??+ host.querySelector('[data-trigger]')) as HTMLElement;+}++describe('tapLandsOnDisabledControl', () => {+ it.each([+ // The disabled control itself, or the icon or label inside it.+ ['<button type="button" aria-disabled="true" data-tapped>Publish</button>'],+ ['<button type="button" disabled data-tapped>Publish</button>'],+ [+ '<button type="button" aria-disabled="true"><svg data-tapped></svg></button>',+ ],+ [+ '<div role="menuitem" aria-disabled="true"><span data-tapped>Delete</span></div>',+ ],+ // A disabled field inside a clickable card: the field is innermost.+ [+ '<div data-pressable-container="true"><span><input aria-disabled="true" data-tapped /></span></div>',+ ],+ // A label for a disabled control.+ [+ '<label><input type="checkbox" aria-disabled="true" /><span data-tapped>Notify</span></label>',+ ],+ // A clickable container that is itself aria-disabled.+ [+ '<div data-pressable-container="true" aria-disabled="true"><span data-tapped>Owner</span></div>',+ ],+ ])('takes the tap itself: %s', html => {+ expect(tapLandsOnDisabledControl(tappedIn(html))).toBe(true);+ });++ it.each([+ // An enabled control, also around the tapped text: left to the trigger.+ ['<a href="/doc"><span data-tapped>A very long title</span></a>'],+ ['<button type="button"><span data-tapped>Label</span></button>'],+ ['<label><input type="checkbox" /><span data-tapped>Notify</span></label>'],+ ['<div data-pressable-container="true"><span data-tapped>ID</span></div>'],+ // An enabled control inside a disabled container is innermost.+ [+ '<div data-pressable-container="true" aria-disabled="true"><a href="/doc" data-tapped>Doc</a></div>',+ ],+ // A clickable container that only takes no click (a default Overlay's+ // mark) is no disabled control.+ [+ '<div data-pressable-container="true"><span data-tapped>Caption</span></div>',+ ],+ // No control at all.+ ['<p>Read the <span data-tapped>WCAG</span> notes.</p>'],+ ])('leaves the tap to the trigger: %s', html => {+ expect(tapLandsOnDisabledControl(tappedIn(html))).toBe(false);+ });+});diff --git a/packages/core/src/Layer/useTouchTrigger.ts b/packages/core/src/Layer/useTouchTrigger.tsindex cf71b22ca7..9939eeec30 100644--- a/packages/core/src/Layer/useTouchTrigger.ts+++ b/packages/core/src/Layer/useTouchTrigger.ts@@ -6,11 +6,13 @@* @file useTouchTrigger.ts* @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks* @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,- * TOUCH_POINTER_TYPES and useTapStop (internal: not re-exported from index)+ * tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:+ * not re-exported from index)* @position Layer hook; shared touch behavior for useTooltip and useHoverCard** SYNC: When modified, update:* - /packages/core/src/Layer/index.ts+ * - /packages/core/src/hooks/useClickableContainer.ts (innermostInteractive)** Hover is the one trigger a touch screen cannot express. A tap synthesizes* `mouseenter`, so an untreated hover layer either opens on every tap and@@ -24,7 +26,10 @@* action — an info icon, an abbreviation, a truncated label — has nothing to* lose, so the tap opens the layer and the next tap outside dismisses it. That* is `auto`; `tap` and `none` state the choice outright, which is what an- * icon-button whose only job is to reveal the layer needs.+ * icon-button whose only job is to reveal the layer needs. An `aria-disabled`+ * control performs no action: a tap that lands in one, or on a label for a+ * disabled control, opens the layer, so its reason has a touch path. (A+ * natively `disabled` control receives no click at all.)** A touch decides nothing until it is a tap. A finger landing on the trigger* may be starting a scroll, a pinch or a long press, and only the browser@@ -47,6 +52,11 @@ import {type RefObject,} from 'react';import {currentGesture} from './gestureCounter';+import {+ innermostInteractive,+ matchesInteractiveSelectors,+} from '../hooks/useClickableContainer';+import {isDisabledControl} from '../utils/pressDisabled';import {useInteractionModalityTrackingFor} from '../utils/interactionModality';/**@@ -128,15 +138,25 @@ const ACTION_ROLES = new Set([* with no role) gets both: the layer opens and the handler runs.*/export function isActionTrigger(element: HTMLElement): boolean {+ // A disabled control performs no action: its tap is free to open the layer+ // that explains why it is disabled.+ if (isDisabledControl(element)) {+ return false;+ }const role = element.getAttribute('role');if (role != null && role !== '') {return ACTION_ROLES.has(role);}switch (element.tagName) {+ case 'LABEL': {+ // A label acts by operating its control, so a label for a disabled one+ // performs none.+ const control = (element as HTMLLabelElement).control;+ return control == null || !isDisabledControl(control);+ }case 'BUTTON':case 'INPUT':- case 'LABEL':case 'SELECT':case 'SUMMARY':case 'TEXTAREA':@@ -149,6 +169,41 @@ export function isActionTrigger(element: HTMLElement): boolean {}}+/**+ * Whether this element takes a tap itself, as a disabled control does: an+ * `aria-disabled` (or `:disabled`) control, or a label for one.+ */+function isDisabledTarget(element: Element): boolean {+ if (isDisabledControl(element)) {+ return true;+ }+ if (element.tagName === 'LABEL') {+ const control = (element as HTMLLabelElement).control;+ return control != null && isDisabledControl(control);+ }+ return false;+}++/**+ * Whether a tap landed in a disabled control: walking out from the tapped+ * element on the clickable containers' own walk (`innermostInteractive`),+ * with labels counted, the innermost interactive element is an+ * `aria-disabled` control or a label for a disabled control. That element+ * takes the tap: the layer opens with its reason, and nothing activates.+ * Every other tap is left to the trigger (`isActionTrigger`).+ */+export function tapLandsOnDisabledControl(tapped: Element): boolean {+ const innermost = innermostInteractive(+ tapped,+ null,+ element =>+ matchesInteractiveSelectors(element) ||+ element.tagName === 'LABEL' ||+ isDisabledControl(element),+ );+ return innermost != null && isDisabledTarget(innermost);+}+/*** Whether typing into this element edits it. Reads the attribute as well as* the property: jsdom does not implement `isContentEditable`, and an editor@@ -350,14 +405,19 @@ export function useTouchTrigger(// What a tap on the trigger does. It runs from the tap's `click`, after the// render that armed it, so it reads the latest props through this ref.- const answerTapRef = useRef<() => void>(() => {});- answerTapRef.current = () => {+ const answerTapRef = useRef<(tapEvent: Event) => void>(() => {});+ answerTapRef.current = (tapEvent: Event) => {const trigger = triggerRef.current;+ // A tap that landed in a disabled control is that control's: its reason+ // opens. Every other tap is the trigger's to decide.+ const tapped = tapEvent.target instanceof Element ? tapEvent.target : null;const mode =touchTrigger === 'auto'- ? trigger != null && isActionTrigger(trigger)- ? 'none'- : 'tap'+ ? tapped != null && tapLandsOnDisabledControl(tapped)+ ? 'tap'+ : trigger != null && isActionTrigger(trigger)+ ? 'none'+ : 'tap': touchTrigger;if (mode === 'none' || !isEnabled) {@@ -409,10 +469,10 @@ export function useTouchTrigger(forgetPendingTapRef.current = null;}};- const handleTap = () => {+ const handleTap = (tapEvent: Event) => {forget();if (currentGesture() === gesture) {- answerTapRef.current();+ answerTapRef.current(tapEvent);}};trigger.addEventListener('click', handleTap);diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjsindex ad121e6a3c..0045533756 100644--- a/packages/core/src/Tooltip/Tooltip.doc.mjs+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs@@ -84,7 +84,7 @@ export const docs = {name: 'touchTrigger',type: "'auto' | 'tap' | 'none'",description:- 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',+ 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',default: "'auto'",},{@@ -197,7 +197,7 @@ export const docsZh = {name: 'touchTrigger',type: "'auto' | 'tap' | 'none'",description:- '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有。tap:始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none:触摸永不打开。',+ '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有;设置了 aria-disabled 的控件不执行操作,因此轻点它会显示其原因。tap:始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none:触摸永不打开。',default: "'auto'",},{@@ -274,7 +274,7 @@ export const docsDense = {delay: 'Show delay in ms.',hideDelay: 'Hide delay in ms.',focusTrigger: 'Controls when focus events trigger tooltip.',- touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens (info icon rendered as a button); none = never on touch.',+ touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (info icon rendered as a button); none = never on touch.',isEnabled: 'Enables/disables tooltip triggers.',onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',hasHoverIndication: 'Dashed underline on trigger element.',diff --git a/packages/core/src/Tooltip/Tooltip.spec.md b/packages/core/src/Tooltip/Tooltip.spec.mdindex fb7062d07a..4250811dd0 100644--- a/packages/core/src/Tooltip/Tooltip.spec.md+++ b/packages/core/src/Tooltip/Tooltip.spec.md@@ -15,6 +15,7 @@ verified_by:packages/core/src/Tooltip/Tooltip.test.tsx,packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts,packages/core/src/Tooltip/useTooltip.test.tsx,+ packages/core/src/Layer/touchTriggerTargets.test.tsx,packages/core/src/Tooltip/__tests__/Tooltip.a11y.test.tsx,packages/core/src/Tooltip/__tests__/Tooltip.a11y.chromium.spec.ts,packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts,@@ -129,8 +130,7 @@ Consumer migration instructions belong in consumer docs and release notes.- **A tap inside a control still opens the tooltip.** The shipped`touchTrigger="auto"` asks only whether the trigger itself performs an action,so a truncated label inside a link opens its tooltip on the tap that follows- the link, and a disabled control's reason opens on no tap. The walk ships- with CLN-0024 and the disabled-control restoration as a patch (FR5, DEC-1).+ the link. The walk ships with CLN-0024 (FR5, DEC-1).- **Press-to-pin is not built.** `pressTrigger`, its toggle (FR9), the triggerwiring and announcement (FR10), and a pinned tooltip's Escape priority(`spec:AST-003` FR4) are specified and not implemented, and the codemod@@ -209,7 +209,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element; `anchorRef` attaches to that element. The trigger's `aria-describedby` gains the tooltip id, merged with and later restored to any existing value. Implementation gap: the wiring runs only when the trigger's listeners attach, so a trigger element replaced after mount, or a trigger whose own `aria-describedby` changes, loses it until a re-render re-attaches them (Current-state impact). | Current source and tests || FR3 | On a hover-capable pointer, entering the trigger opens after `delay` ms; leaving closes after `hideDelay` ms. With `hideDelay` 0 a short bridge lets the pointer move onto the surface without closing it, and the surface stays open while hovered. | WCAG 1.4.13; tests || FR4 | 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. Implementation gap: `auto` recognizes only an explicit non-negative `tabindex`, HTML links, buttons, form fields, and editable elements, so a `<summary>` or an SVG link never opens on keyboard focus; and it reads the tab order only when it attaches the trigger's listeners, on mount and again when `focusTrigger`, `isEnabled`, `isOpen`, `delay`, `hideDelay`, or `onOpenChange` changes, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | Current source and tests |-| FR5 | On touch, a completed tap opens 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 that already acts leaves it shut: walking out from the tapped element, the trigger included, the innermost button, link, label, form control, option, menu item, or row or card made clickable with `useClickableContainer` decides, and a disabled or `aria-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). Implementation gap: the walk ships with CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | Current source and tests |+| FR5 | On touch, a completed tap opens 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 that already acts leaves it shut: walking out from the tapped element, the trigger included, the innermost button, link, label, form control, option, menu item, or row or card made clickable with `useClickableContainer` decides, and 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). Implementation gap: the walk ships with CLN-0024 in the next minor; until then `auto` asks only whether the trigger itself performs an action, apart from a disabled control (Compatibility and migration). A second tap on the trigger, a tap outside, or a scroll starting outside closes it. Under `pressTrigger="toggle"`, FR9 decides what a tap does and `touchTrigger` is ignored. | 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 `pressTrigger="toggle"`, 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. | 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 |@@ -291,16 +291,16 @@ has no arrow element.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |-| FR1 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |-| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open | Wrong open or close for an input 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`; `useTouchTrigger.test.ts`, with tap-destination cases an evidence gap until built | Tap open, scroll, second tap, tap outside; a trigger inside a link, a clickable row, or a clickable card; 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 tap that already acts, or leaves a disabled control's reason shut fails. | `audit:Tooltip/behavior` |-| FR9, FR10, AR6 | Evidence gap until built: a press-toggle suite in `Tooltip.test.tsx` and `useTooltip.test.tsx`, and a real-touch and keyboard case in `TouchTrigger.a11y.chromium.spec.ts` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave keeps the pin; controlled; non-button trigger; a truncated Text trigger whose tooltip repeats its text; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, an own-text trigger that warns, gets `aria-expanded`, or is announced, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:Tooltip/behavior` |-| DEP-0016, CLN-0024 | Evidence gap until built: the codemod's tests and fixtures beside its transform, and the codemod verify workflow | `touchTrigger="tap"` on an icon and a span, and on an own-text trigger, an info-only button, a button with its own action, a link, and an unknown element, under each codemod; `"auto"` and `"none"`; `pressTrigger` beside `touchTrigger`; spreads and dynamic values | A rewrite that changes behavior; under DEP-0016's codemod, a rewritten own-text, button, link, or unknown-element site; under CLN-0024's codemod, a rewritten button, link, or unknown-element site, or an identifiable own-text site left unrewritten; a reported site without its manual-migration note (all three options for a button or link); a missed static use; or a silently skipped dynamic one fails. | `audit:Tooltip/api` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Tooltip/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |+| FR1 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |+| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open | Wrong open or close for an input 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`; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases, with tap-destination cases an evidence gap until built | Tap open, scroll, second tap, tap outside; a trigger inside a link, a clickable row, or a clickable card; 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 tap that already acts, or leaves a disabled control's reason shut fails. | `audit:Tooltip/behavior` |+| FR9, FR10, AR6 | Evidence gap until built: a press-toggle suite in `Tooltip.test.tsx` and `useTooltip.test.tsx`, and a real-touch and keyboard case in `TouchTrigger.a11y.chromium.spec.ts` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave keeps the pin; controlled; non-button trigger; a truncated Text trigger whose tooltip repeats its text; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, an own-text trigger that warns, gets `aria-expanded`, or is announced, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:Tooltip/behavior` |+| DEP-0016, CLN-0024 | Evidence gap until built: the codemod's tests and fixtures beside its transform, and the codemod verify workflow | `touchTrigger="tap"` on an icon and a span, and on an own-text trigger, an info-only button, a button with its own action, a link, and an unknown element, under each codemod; `"auto"` and `"none"`; `pressTrigger` beside `touchTrigger`; spreads and dynamic values | A rewrite that changes behavior; under DEP-0016's codemod, a rewritten own-text, button, link, or unknown-element site; under CLN-0024's codemod, a rewritten button, link, or unknown-element site, or an identifiable own-text site left unrewritten; a reported site without its manual-migration note (all three options for a button or link); a missed static use; or a silently skipped dynamic one fails. | `audit:Tooltip/api` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Tooltip/theming` |Read from source, with no focused test yet:@@ -340,10 +340,10 @@ truncated label inside a link follows the link, while a truncated label inrunning text opens its tooltip. Whether a tap acts is decided by walking outfrom the tapped element: the innermost control on that path decides, whether abutton, link, label, form control, option, menu item, or row or card made-clickable with `useClickableContainer`, the trigger included. A disabled or-`aria-disabled` control is not an action, so its reason opens on a tap, even-inside a clickable row or card. An element that acts only through a role-less-`onClick` is a caller fix: it needs a role.+clickable with `useClickableContainer`, the trigger included. An `aria-disabled`+control, or a label for a disabled control, is not an action, so its reason+opens on a tap, even inside a clickable row or card. An element that acts only+through a role-less `onClick` is a caller fix: it needs a role.The walk ships with the fold at the next minor (CLN-0024).`touchTrigger="tap"` is deprecated in favor of the toggle (DEP-0016).diff --git a/packages/core/src/Tooltip/useTooltip.doc.mjs b/packages/core/src/Tooltip/useTooltip.doc.mjsindex 13e360b6f4..355149437a 100644--- a/packages/core/src/Tooltip/useTooltip.doc.mjs+++ b/packages/core/src/Tooltip/useTooltip.doc.mjs@@ -12,7 +12,7 @@ export const docs = {{name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},{name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},{name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},- {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},+ {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},{name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},{name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},{name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},diff --git a/packages/core/src/gestures/haptics.ts b/packages/core/src/gestures/haptics.tsindex 416129dd7d..da9e4e2109 100644--- a/packages/core/src/gestures/haptics.ts+++ b/packages/core/src/gestures/haptics.ts@@ -38,6 +38,7 @@ import {HAPTIC_VIBRATION_PATTERNS,type HapticFeedbackKind,} from '../motion/uikit/gestures';+import {isDisabledControl} from '../utils/pressDisabled';/** Marks the hidden switch, so click handlers can recognize and ignore it. */export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';@@ -79,14 +80,6 @@ const VISUALLY_HIDDEN =let nextLabelId = 0;-/** A native disabled control, or one marked `aria-disabled`. */-function isDisabledControl(control: HTMLElement): boolean {- return (- control.matches(':disabled') ||- control.getAttribute('aria-disabled') === 'true'- );-}-/** Whether `input` is a switch checkbox, which plays the tap haptic itself. */function isSwitch(input: HTMLInputElement): boolean {return input.type === 'checkbox' && input.hasAttribute('switch');diff --git a/packages/core/src/hooks/useClickableContainer.ts b/packages/core/src/hooks/useClickableContainer.tsindex 35985f1c7a..43b070f45f 100644--- a/packages/core/src/hooks/useClickableContainer.ts+++ b/packages/core/src/hooks/useClickableContainer.ts@@ -5,7 +5,8 @@/*** @file useClickableContainer.ts* @input Container ref, interactive element ref, click/href handlers- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;+ * hasInteractiveAncestor and the shared innermostInteractive walk* @position Core hook for clickable containers that safely handle nested interactive elements** Solves the "nested interactive elements" problem: when a card is clickable@@ -23,6 +24,13 @@import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';import {isSafeUrl} from '../utils/safeUrl';+/**+ * The attribute this hook sets on the container it makes clickable. A click+ * inside a nested marked container belongs to that container (see+ * INTERACTIVE_SELECTORS).+ */+export const PRESSABLE_CONTAINER_ATTRIBUTE = 'data-pressable-container';+/*** Canonical list of interactive element selectors — native controls plus* role-based interactive elements. Clicks on these (or their descendants)@@ -52,15 +60,48 @@ export const INTERACTIVE_SELECTORS = ['[role="listbox"]','[role="slider"]','[role="spinbutton"]',- '[data-pressable-container]',+ `[${PRESSABLE_CONTAINER_ATTRIBUTE}]`,].join(',');const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';/**- * Check whether an element has an interactive ancestor between it and the root.- * If the click target is inside a nested button/link/etc., we should NOT- * handle it at the container level.+ * Whether this element is interactive by INTERACTIVE_SELECTORS: a control,+ * link, editor, or nested clickable container, and not marked read-only.+ */+export function matchesInteractiveSelectors(element: Element): boolean {+ return (+ element.matches(INTERACTIVE_SELECTORS) &&+ !element.matches(NON_INTERACTIVE_SELECTORS)+ );+}++/**+ * The innermost element, from `el` up to (not including) `rootEl` or the+ * document body, that `isInteractive` accepts: by default the+ * INTERACTIVE_SELECTORS match. The one walk every "does this event belong+ * to a control" check shares; a hover layer's tap passes its own test+ * (useTouchTrigger's `tapLandsOnDisabledControl`).+ */+export function innermostInteractive(+ el: Element,+ rootEl: Element | null,+ isInteractive: (element: Element) => boolean = matchesInteractiveSelectors,+): Element | null {+ let current: Element | null = el;+ while (current != null && current !== rootEl && current !== document.body) {+ if (isInteractive(current)) {+ return current;+ }+ current = current.parentElement;+ }+ return null;+}++/**+ * Check whether an element has an interactive ancestor between it and the+ * root (the element itself included). If the click target is inside a nested+ * button/link/etc., we should NOT handle it at the container level.** Exported for containers that cannot use the hook itself — a `<tr>` whose* props are assembled inside a Table plugin's `transformBodyRow`, for@@ -69,17 +110,7 @@ const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';* instead of a short hand-rolled selector list per caller.*/export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {- let current: Element | null = el;- while (current != null && current !== rootEl && current !== document.body) {- if (- current.matches(INTERACTIVE_SELECTORS) &&- !current.matches(NON_INTERACTIVE_SELECTORS)- ) {- return true;- }- current = current.parentElement;- }- return false;+ return innermostInteractive(el, rootEl) != null;}/**@@ -164,7 +195,7 @@ export function useClickableContainer({useEffect(() => {const el = containerRef.current;if (el) {- el.setAttribute('data-pressable-container', 'true');+ el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');}}, [containerRef]);diff --git a/packages/core/src/utils/pressDisabled.test.ts b/packages/core/src/utils/pressDisabled.test.tsnew file mode 100644index 0000000000..ba435b61f2--- /dev/null+++ b/packages/core/src/utils/pressDisabled.test.ts@@ -0,0 +1,37 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {isDisabledControl} from './pressDisabled';++function element(html: string): Element {+ const host = document.createElement('div');+ host.innerHTML = html;+ const found = host.querySelector('[data-subject]');+ if (found == null) {+ throw new Error('no [data-subject] element');+ }+ return found;+}++describe('isDisabledControl', () => {+ it.each([+ ['<button data-subject aria-disabled="true">Publish</button>'],+ ['<button data-subject disabled>Publish</button>'],+ ['<input data-subject disabled />'],+ ['<div data-subject role="menuitem" aria-disabled="true">Delete</div>'],+ // A disabled fieldset disables the controls inside it.+ ['<fieldset disabled><input data-subject /></fieldset>'],+ ])('is true for %s', html => {+ expect(isDisabledControl(element(html))).toBe(true);+ });++ it.each([+ ['<button data-subject>Publish</button>'],+ ['<button data-subject aria-disabled="false">Publish</button>'],+ // `disabled` means nothing on an element that is not a form control.+ ['<div data-subject disabled>Owner</div>'],+ ['<span data-subject>Owner</span>'],+ ])('is false for %s', html => {+ expect(isDisabledControl(element(html))).toBe(false);+ });+});diff --git a/packages/core/src/utils/pressDisabled.ts b/packages/core/src/utils/pressDisabled.tsnew file mode 100644index 0000000000..c37378f85d--- /dev/null+++ b/packages/core/src/utils/pressDisabled.ts@@ -0,0 +1,32 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file pressDisabled.ts+ * @input An element+ * @output `isDisabledControl`: whether an element is a disabled control, so a+ * press on it performs no action+ * @position The one disabled-control check that press feedback+ * (../gestures/haptics) and the hover layers' touch trigger+ * (../Layer/useTouchTrigger) share, so the two never disagree about a+ * control. It lives outside the gesture code, which a public import that+ * uses no gesture never carries (architecture:react-component-runtime+ * INV13).+ */++/**+ * Whether `element` is a disabled control: `aria-disabled="true"`, or a form+ * control the browser counts as `:disabled` (a disabled fieldset's controls+ * included). A disabled control performs no action, so it gives no press+ * feedback (spec:AST-094 FR23), and a tap on it opens its reason instead+ * (component:Tooltip FR5).+ */+export function isDisabledControl(element: Element): boolean {+ if (element.getAttribute('aria-disabled') === 'true') {+ return true;+ }+ try {+ return element.matches(':disabled');+ } catch {+ return false;+ }+}