An open source design system that's fully customizable and agent ready
TypeScript
fix(Tooltip, HoverCard): a press inside an open surface doesn't activate the card, row or field around it (#9252)
Cindy Zhang3d44c583a0ba
diff --git a/.changeset/tooltip-surface-press-stays.md b/.changeset/tooltip-surface-press-stays.mdnew file mode 100644index 0000000000..ff6740b93d--- /dev/null+++ b/.changeset/tooltip-surface-press-stays.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] A click inside an open Tooltip or HoverCard no longer activates the card, row or field around its trigger: a FileInput no longer opens its file picker, and a ClickableCard, SelectableCard, Token, or Item, TreeList or Table row no longer activates. Links and buttons inside a HoverCard keep working.++@cixzhangdiff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.mdindex 1bbb682859..1b116eed33 100644--- a/docs/specs/components/ClickableCard/ClickableCard.spec.md+++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md@@ -121,7 +121,7 @@ Consumer migration instructions belong in consumer docs and release notes.| ID | Invariant | Basis || --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- || FR1 | The root is Card's `div`. With `href`, a visually hidden native link holds the destination and `target`; otherwise a visually hidden `button type="button"` calls `onClick`. `label` names that control, and the hidden control is the card's tab stop. | Current source and tests |-| FR2 | A primary-button press on the card surface calls `onClick` once with the card as `currentTarget`, then performs an accepted navigation unless the callback cancels it. A middle press on the surface of a card given `href` opens an accepted destination in a new tab without calling `onClick`. A press inside a nested interactive descendant, or one that ends a text selection, does not activate the card. Activating the hidden button of an action card calls `onClick` once; activating the hidden link navigates without calling `onClick`. | Current source and tests; `architecture:public-component-api` INV7 |+| FR2 | A primary-button press on the card surface calls `onClick` once with the card as `currentTarget`, then performs an accepted navigation unless the callback cancels it. A middle press on the surface of a card given `href` opens an accepted destination in a new tab without calling `onClick`. A press inside a nested interactive descendant, inside an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or one that ends a text selection, does not activate the card. Activating the hidden button of an action card calls `onClick` once; activating the hidden link navigates without calling `onClick`. | Current source and tests; `architecture:public-component-api` INV7 || FR3 | Plain, new-tab, modified, middle-click, and surface-delegated navigation use the shared destination decision; a blocked destination does not navigate. | `family:navigation-destinations` FR1, FR3–FR5 || FR4 | `isDisabled` keeps the hidden control focusable with `aria-disabled="true"`; Enter, Space, and clicks on it do nothing. A disabled link keeps its link role and name but has no `href` or `target`. The control stays focusable and announced (`spec:AST-085` FR1, FR2, FR5); the card's own click and mouseup handling and the caller's `onMouseUp` are removed, other caller event props still reach the root, and the surface shows no hover or pressed paint (`spec:AST-085` FR6), and renders at half opacity. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `clickable-card` target reflects no disabled state (Current-state impact). | Current source and tests || FR5 | While enabled, the root paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses, and a bordered card's border responds to hover. Keyboard focus on the hidden control shows the shared focus outline on the root. | Current source, stories, and `architecture:interaction-modality` |diff --git a/docs/specs/components/HoverCard/HoverCard.spec.md b/docs/specs/components/HoverCard/HoverCard.spec.mdindex 1360e3fa4d..d09f181946 100644--- a/docs/specs/components/HoverCard/HoverCard.spec.md+++ b/docs/specs/components/HoverCard/HoverCard.spec.md@@ -157,18 +157,19 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-| FR1 | The open card is one surface carrying only the `hover-card` target, padded on every logical edge, with `content` inside and the theme's body font. `xstyle`, `className`, and `style` apply to the card. | Current source and tests |-| 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 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 |-| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the card open, and the same press on a pinned card closes it. Hover and focus still preview it per FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned card stays open when the pointer leaves the trigger and the card, and a press on its own content keeps it pinned; Escape (FR6), a second press on the trigger, a press outside the trigger and the card, or focus moving outside them closes it. In a controlled card a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the card as `touchTrigger="tap"` does, and no press pins it. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |-| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the card while it shows, with or without `label`, each replacing the trigger's own value while wired and restored on cleanup; FR3's popup role and description are kept. When the card pins, a polite live region announces it once: its `label` when it has one, else its text. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |+| ID | Invariant | Basis |+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |+| FR1 | The open card is one surface carrying only the `hover-card` target, padded on every logical edge, with `content` inside and the theme's body font. `xstyle`, `className`, and `style` apply to the card. | Current source and tests |+| 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 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 |+| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the card open, and the same press on a pinned card closes it. Hover and focus still preview it per FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned card stays open when the pointer leaves the trigger and the card, and a press on its own content keeps it pinned; Escape (FR6), a second press on the trigger, a press outside the trigger and the card, or focus moving outside them closes it. In a controlled card a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the card as `touchTrigger="tap"` does, and no press pins it. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |+| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the card while it shows, with or without `label`, each replacing the trigger's own value while wired and restored on cleanup; FR3's popup role and description are kept. When the card pins, a polite live region announces it once: its `label` when it has one, else its text. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |+| FR11 | A press inside an open HoverCard surface acts only within that surface: it never activates the trigger, a clickable container around it, or the control a label names. Interactive content inside the card (a link, a button) keeps its own activation. The press still reaches page-level listeners, so a menu or Typeahead inside the surface keeps working. | `component:HoverCard` FR9 (a pinning press stops at its trigger); `component:Tooltip` FR11 |### Allowed variation@@ -257,6 +258,7 @@ Consumer migration instructions belong in consumer docs and release notes.| 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` |+| FR11 | `HoverCard.test.tsx` surface-press suite | A card inside a clickable container and inside a `<label>`; a button inside the card | A click on card content that runs the container's click handler or activates a labelled control, or a card button that stops working, fails. | — || 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:diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.mdindex a68b9f06a9..1a106b899a 100644--- a/docs/specs/components/SelectableCard/SelectableCard.spec.md+++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md@@ -112,7 +112,7 @@ Consumer migration instructions belong in consumer docs and release notes.| ID | Invariant | Basis || --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ || FR1 | SelectableCard renders `component:Card` with the given `variant`, `elevation`, `padding`, and sizing. The root also carries the `selectable-card` target reflecting `variant` and `selected`, and the first child is a visually hidden native `input type="checkbox"` named by `label` with `checked` equal to `isSelected`. | Current source and tests |-| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle. A caller `onMouseUp` runs after the card's own handling. | Current source and tests |+| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content, an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle. A caller `onMouseUp` runs after the card's own handling. | Current source and tests || FR3 | Selection adds a 2px inset ring through Card's ring variable, so layout does not move, and composes with any elevation shadow. `default`, `transparent`, and `muted` ring in `--color-accent`; each palette variant rings in its `--color-border-<name>`; a theme-added variant rings in `--selectable-card-ring-color`. Selection also colors the border in the ring color where Card draws one, which is only the `default` variant. | Current source and tests || FR4 | While enabled, the surface paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses. Keyboard focus on the hidden checkbox shows one indicator on the card root (`architecture:interaction-modality` INV3). Implementation gap: the root outlines while any descendant has `:focus-visible`, so focusing a nested control draws both the card outline and the control's own (Current-state impact). | Current source and tests || FR5 | `isDisabled` dims the card to half opacity, removes the card's own click and mouseup handling and the caller's `onClick` and `onMouseUp` (other caller event props still reach the root) and the hover and pressed overlays (`spec:AST-085` FR6), and keeps the checkbox focusable with `aria-disabled="true"`; no click, Space, or Enter calls `onChange`. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `selectable-card` target reflects `variant` and `selected` but not the disabled state (Current-state impact). | Current source and tests |diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.mdindex 8a3bc535b7..a7a7c57ca2 100644--- a/docs/specs/components/Token/Token.spec.md+++ b/docs/specs/components/Token/Token.spec.md@@ -119,18 +119,18 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap. | Current source and tests |-| FR2 | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly. | Current source and tests |-| FR3 | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact). | Current source and tests |-| FR4 | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`. With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation. | Current source and tests |-| FR5 | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). A disabled token with `href` and no `onClick` or trigger context renders a focusable link with `aria-disabled="true"` and no `href`, and every structure reflects the disabled state on the `token` target. | Current source and tests |-| FR6 | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it. | Current source and tests |-| FR7 | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment. | Current source and tests |-| FR8 | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it. | Current source and tests |-| FR9 | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither. | Current source |-| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root, except that in the clickable structure `aria-labelledby` and `aria-describedby` reach the inner button, the element that owns the token's action (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |+| ID | Invariant | Basis |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | Content renders in logical inline order: Icon, Label, End content, Remove button. The root is inline-flex with `--spacing-1` gaps, inline padding `--spacing-2`, `--radius-inner` corners, `--text-supporting-size` type at `--font-weight-medium`, and a minimum block size of `--size-element-sm`, `-md`, or `-lg` minus 8px for `sm`, `md`, and `lg`. That size grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap. | Current source and tests |+| FR2 | With no `href`, `onClick`, or enclosing trigger context, the token is a static `span` holding its content directly. | Current source and tests |+| FR3 | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact). | Current source and tests |+| FR4 | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`, except a click inside an open Tooltip or HoverCard surface (`component:Tooltip` FR11). With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation. | Current source and tests |+| FR5 | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). A disabled token with `href` and no `onClick` or trigger context renders a focusable link with `aria-disabled="true"` and no `href`, and every structure reflects the disabled state on the `token` target. | Current source and tests |+| FR6 | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it. | Current source and tests |+| FR7 | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment. | Current source and tests |+| FR8 | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it. | Current source and tests |+| FR9 | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither. | Current source |+| FR10 | `ref` reaches the root element of every structure. Supported DOM, ARIA, data, and event props reach the root, except that in the clickable structure `aria-labelledby` and `aria-describedby` reach the inner button, the element that owns the token's action (`architecture:public-component-api` INV5); `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |### Allowed variationdiff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.mdindex 4250811dd0..1fa0c493c4 100644--- a/docs/specs/components/Tooltip/Tooltip.spec.md+++ b/docs/specs/components/Tooltip/Tooltip.spec.md@@ -203,18 +203,19 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-| FR1 | The rendered tooltip contains one owned surface, `role="tooltip"`, carrying the `tooltip` target, at most 300 px wide, with the supplied `content` inside; content has no separate target and there is no arrow. | Current source, docs, and tests |-| 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 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 |-| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the tooltip open, and the same press on a pinned tooltip closes it. Hover and keyboard focus still preview it per FR3 and FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned tooltip stays open when the pointer leaves the trigger and the surface; Escape (FR6), a second press, a press outside the trigger and the surface, or focus moving outside them closes it. In a controlled tooltip a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the tooltip as `touchTrigger="tap"` does, and no press pins it. A trigger whose tooltip repeats its own visible text, such as a truncated Text that is its own tab stop, may take `pressTrigger="toggle"` without being a button: a press pins it as on a button trigger, and it gets no development warning, no `aria-expanded` or `aria-controls`, and no announcement, since its text is already its content. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |-| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the surface while it shows, each replacing the trigger's own value while wired and restored on cleanup; FR2's `aria-describedby` is kept. When the tooltip pins, its text is announced once through a polite live region; a preview announces nothing beyond the description. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |+| ID | Invariant | Basis |+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |+| FR1 | The rendered tooltip contains one owned surface, `role="tooltip"`, carrying the `tooltip` target, at most 300 px wide, with the supplied `content` inside; content has no separate target and there is no arrow. | Current source, docs, and tests |+| 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 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 |+| FR9 | With `pressTrigger="toggle"` and a trigger whose role is `button` (a `<button>` or `role="button"`), a click, a completed tap, Enter, or Space on the trigger pins the tooltip open, and the same press on a pinned tooltip closes it. Hover and keyboard focus still preview it per FR3 and FR4; on touch no preview opens and a tap pins it, while a touch that becomes a scroll pins nothing. A pinned tooltip stays open when the pointer leaves the trigger and the surface; Escape (FR6), a second press, a press outside the trigger and the surface, or focus moving outside them closes it. In a controlled tooltip a press reports the toggled value through `onOpenChange` and does not change the state itself (FR7). A press that pins or closes the layer stops at its trigger: it does not reach a clickable row, card, or container around it, or the control a label names. A trigger whose role is not `button` gets a development warning and keeps tap-only opening: a tap opens the tooltip as `touchTrigger="tap"` does, and no press pins it. A trigger whose tooltip repeats its own visible text, such as a truncated Text that is its own tab stop, may take `pressTrigger="toggle"` without being a button: a press pins it as on a button trigger, and it gets no development warning, no `aria-expanded` or `aria-controls`, and no announcement, since its text is already its content. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |+| FR10 | While `pressTrigger="toggle"` wires a button trigger, the trigger carries `aria-expanded`, `true` only while pinned, and `aria-controls` naming the surface while it shows, each replacing the trigger's own value while wired and restored on cleanup; FR2's `aria-describedby` is kept. When the tooltip pins, its text is announced once through a polite live region; a preview announces nothing beyond the description. Implementation gap: not yet built (Current-state impact). | DEC-1; WAI-ARIA 1.2 `aria-expanded` |+| FR11 | A press inside an open Tooltip surface acts only within that surface: it never activates the trigger, a clickable container around it, or the control a label names. A tooltip that renders inside a FileInput dropzone, a ClickableCard, an Item row, or a `<label>` keeps a click on its text from opening the file picker, activating the container, or toggling or focusing the labelled control. The press still reaches page-level listeners, so a menu or Typeahead inside the surface keeps working. | `component:Tooltip` FR9 (a pinning press stops at its trigger); `component:Tooltip` DEC-1 (one tap does one thing) |### Allowed variation@@ -299,6 +300,7 @@ has no arrow element.| 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` |+| FR11 | `Tooltip.test.tsx` surface-press suite; `FileInputTooltipPress.a11y.chromium.spec.ts` | A tooltip inside a clickable container and inside a `<label>`; FileInput compact and dropzone status tooltips, with a click on the empty dropzone as the positive control | A click on tooltip text that runs the container's click handler, checks or focuses a labelled control, or opens the file picker fails. | — || 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` |diff --git a/docs/specs/components/TreeList/TreeList.spec.md b/docs/specs/components/TreeList/TreeList.spec.mdindex f817e70f61..c4489ea458 100644--- a/docs/specs/components/TreeList/TreeList.spec.md+++ b/docs/specs/components/TreeList/TreeList.spec.md@@ -110,7 +110,7 @@ Supporting one does not justify omitting another from the durable contract.| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content. | Current source and target docs | Current reachability gap; no new target is accepted || FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged || FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision. | Owner decision and the caller-owned per-row interaction boundary | Settled intent |-| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and a disabled Item does nothing. | Owner decision; `family:navigation-destinations` | Settled intent; implementation may be staged |+| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and a disabled Item does nothing. A press inside an open Tooltip or HoverCard surface performs no row action (`component:Tooltip` FR11). | Owner decision; `family:navigation-destinations` | Settled intent; implementation may be staged || FR8 | Expanding or collapsing an Item with children MUST play its group's own motion: under a coarse primary pointer its rows slide out from under the parent as one block, clipped to the group's box, and back on collapse, a collapsing group's rows leaving the accessibility tree as the slide starts, while the Chevron turns, by transform only (`spec:AST-094` FR4–FR5); under a fine pointer the group appears and leaves at once. With an `animatedLayout` handle, the group and the rows after it follow `spec:AST-105`'s shared motion under every pointer (FR4, FR5); without one, the group's own slide stays touch-only and the rows after the group take their places at once (`spec:AST-105` FR2). | UIKit outline list (`UICollectionView`), iOS 26.2; `spec:AST-105` FR2 | Proposed; awaiting an engineering owner's approval || FR9 | `TreeList` MUST accept `animatedLayout?: AnimatedLayout`. With a handle, expanding and collapsing a row report the row's size change through it, so the content after the row glides inside the handle's container, and the shown rows and the row's Chevron move on the same motion (`spec:AST-105` FR1–FR4; `spec:AST-108` FR4a). Without one, expanding and collapsing follow FR8. The prop MUST NOT change tree semantics or keyboard behavior. | `spec:AST-105` FR1, FR2; `spec:AST-108` FR4a | Current behavior |diff --git a/packages/core/src/FileInput/FileInput.test.tsx b/packages/core/src/FileInput/FileInput.test.tsxindex 01b14410f5..b65ce607e7 100644--- a/packages/core/src/FileInput/FileInput.test.tsx+++ b/packages/core/src/FileInput/FileInput.test.tsx@@ -17,6 +17,7 @@ import {createEvent,waitFor,act,+ within,} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {FileInput} from './FileInput';@@ -1631,3 +1632,33 @@ describe('FileInput statusVariant forwarding', () => {},);});++// component:Tooltip FR11: the status tooltip renders inside the clickable+// surface, so a click on its text must stay in the tooltip.+describe('FileInput status tooltip press', () => {+ it.each(['input', 'dropzone'] as const)(+ 'a click on the tooltip text does not open the picker in %s mode',+ mode => {+ render(+ <FileInput+ label="Upload"+ mode={mode}+ value={null}+ onChange={() => {}}+ status={{type: 'error', message: 'File must be under 10MB'}}+ statusVariant="tooltip"+ />,+ );+ const openPicker = vi.spyOn(fileInputEl(), 'click');+ fireEvent.click(+ within(screen.getByRole('tooltip', h)).getByText(+ 'File must be under 10MB',+ ),+ );+ expect(openPicker).not.toHaveBeenCalled();+ // Positive control: a click on the surface itself still opens it.+ fireEvent.click(screen.getByRole('button', {name: 'Upload'}));+ expect(openPicker).toHaveBeenCalledTimes(1);+ },+ );+});diff --git a/packages/core/src/FileInput/__tests__/FileInputTooltipPress.a11y.chromium.spec.ts b/packages/core/src/FileInput/__tests__/FileInputTooltipPress.a11y.chromium.spec.tsnew file mode 100644index 0000000000..c6455b7f15--- /dev/null+++ b/packages/core/src/FileInput/__tests__/FileInputTooltipPress.a11y.chromium.spec.ts@@ -0,0 +1,79 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y scope ^(packages/core/src/FileInput/|packages/core/src/Tooltip/|apps/storybook/stories/FileInput)++/**+ * @file FileInputTooltipPress.a11y.chromium.spec.ts+ * @input The `Core/FileInput` AuditMatrix story in a built Storybook, in+ * Chromium: the compact and dropzone fields with a tooltip status.+ * @output Real-browser proof of component:Tooltip FR11 in FileInput: a click on+ * the open status tooltip's text never raises the file chooser, while a+ * click on the empty dropzone still does.+ * @position Runs in pr-a11y when FileInput, Tooltip or this spec changes.+ */++import {expect, test, type Page} from '@playwright/test';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const STORY = 'core-fileinput--audit-matrix';+const MESSAGE = 'File must be under 10MB';++let storybook: StaticServer;++test.beforeAll(async () => {+ storybook = await serveStorybook(DEFAULT_STORYBOOK_DIR);+});++test.afterAll(async () => {+ await storybook?.close();+});++async function openStory(page: Page): Promise<void> {+ await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);+ await page.locator('[data-audit-case="dropzone-empty"]').waitFor();+}++/** Resolves true when a file chooser opens within `timeout` ms. */+async function chooserWithin(page: Page, timeout: number): Promise<boolean> {+ return page+ .waitForEvent('filechooser', {timeout})+ .then(() => true)+ .catch(() => false);+}++test('a click on the empty dropzone raises the file chooser', async ({+ page,+}) => {+ await openStory(page);+ const chooser = chooserWithin(page, 3000);+ await page+ .locator('[data-audit-case="dropzone-empty"] .astryx-file-input')+ .click();+ expect(await chooser).toBe(true);+});++for (const id of ['input-error-tooltip', 'dropzone-error-tooltip']) {+ test(`a click on the open status tooltip's text raises no chooser (${id})`, async ({+ page,+ }) => {+ await openStory(page);+ const field = page.locator(`[data-audit-case="${id}"]`);+ // Keyboard focus opens the status tooltip: Tab from the trigger lands on+ // the status button (the FileInput audit's focus order).+ await field.locator('button[type="button"][aria-label]').first().focus();+ await page.keyboard.press('Tab');+ await expect(+ field.getByRole('button', {name: 'Error details'}),+ ).toBeFocused();+ const tooltip = page+ .locator('[role="tooltip"]:popover-open')+ .filter({hasText: MESSAGE});+ await expect(tooltip).toBeVisible();+ const chooser = chooserWithin(page, 1000);+ await tooltip.getByText(MESSAGE).click();+ expect(await chooser).toBe(false);+ });+}diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsxindex 124768daec..745d10fbfb 100644--- a/packages/core/src/HoverCard/HoverCard.test.tsx+++ b/packages/core/src/HoverCard/HoverCard.test.tsx@@ -30,6 +30,7 @@ import {renderToString} from 'react-dom/server';import {hydrateRoot} from 'react-dom/client';import {StrictMode} from 'react';import {Button} from '../Button/Button';+import {ClickableCard} from '../ClickableCard/ClickableCard';import {Theme, defineTheme} from '../theme';import {HoverCard} from './HoverCard';import {useHoverCard} from './useHoverCard';@@ -1337,3 +1338,98 @@ describe('HoverCard theme target names', () => {});});});++// FR11: a press inside an open card acts only within the card.+describe('HoverCard surface press', () => {+ it('keeps a click on card content from activating a clickable card', () => {+ const onCardClick = vi.fn();+ const onCardButton = vi.fn();+ render(+ <ClickableCard label="Card" onClick={onCardClick}>+ <span>Card body</span>+ <HoverCard+ isOpen+ content={+ <span>+ Hover content{' '}+ <button type="button" onClick={onCardButton}>+ Card action+ </button>+ </span>+ }>+ <button type="button">Trigger</button>+ </HoverCard>+ </ClickableCard>,+ );+ fireEvent.click(screen.getByText(/Hover content/));+ fireEvent.click(+ screen.getByRole('button', {name: 'Card action', hidden: true}),+ );+ expect(onCardClick).not.toHaveBeenCalled();+ // The hover card's own button keeps its activation.+ expect(onCardButton).toHaveBeenCalledTimes(1);+ // Positive control: a click on the card's own content still activates it.+ fireEvent.click(screen.getByText('Card body'));+ expect(onCardClick).toHaveBeenCalledTimes(1);+ });++ it("keeps a click on a padded card's own edge from activating a clickable card", () => {+ const onCardClick = vi.fn();+ render(+ <ClickableCard label="Card" onClick={onCardClick}>+ <HoverCard+ isOpen+ style={{padding: 24}}+ content={<span>Hover content</span>}>+ <button type="button">Trigger</button>+ </HoverCard>+ </ClickableCard>,+ );+ // The padding belongs to the layer root around the content.+ const root = screen.getByText('Hover content').closest('[popover]')!;+ fireEvent.click(root);+ expect(onCardClick).not.toHaveBeenCalled();+ });++ it('keeps a middle-button press on card content from opening a card link', () => {+ const open = vi.spyOn(window, 'open').mockReturnValue(null);+ render(+ <ClickableCard label="Card" href="https://example.com/">+ <HoverCard isOpen content={<span>Hover content</span>}>+ <button type="button">Trigger</button>+ </HoverCard>+ </ClickableCard>,+ );+ fireEvent.mouseUp(screen.getByText('Hover content'), {button: 1});+ expect(open).not.toHaveBeenCalled();+ open.mockRestore();+ });++ it('still lets document listeners see a click inside the card', () => {+ const onDocumentClick = vi.fn();+ document.addEventListener('click', onDocumentClick);+ render(+ <HoverCard isOpen content={<span>Hover content</span>}>+ <button type="button">Trigger</button>+ </HoverCard>,+ );+ fireEvent.click(screen.getByText('Hover content'));+ document.removeEventListener('click', onDocumentClick);+ expect(onDocumentClick).toHaveBeenCalledTimes(1);+ });++ it('keeps a click on card text inside a label from toggling its control', () => {+ render(+ <label>+ <input type="checkbox" /> Accept{' '}+ <HoverCard isOpen content={<span>Card content</span>}>+ <button type="button">Info</button>+ </HoverCard>+ </label>,+ );+ // The card mounts outside the label (a label cannot contain it), so a+ // click on its text is not label activation.+ fireEvent.click(screen.getByText('Card content'));+ expect(screen.getByRole('checkbox')).not.toBeChecked();+ });+});diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsxindex 9c28c3dcc0..6a04f201fe 100644--- a/packages/core/src/HoverCard/useHoverCard.tsx+++ b/packages/core/src/HoverCard/useHoverCard.tsx@@ -31,6 +31,7 @@ import {type LayerTouchTrigger,} from '../Layer/useTouchTrigger';import {layerAnimations} from '../Layer/layerAnimations.stylex';+import {registerLayerSurface} from '../Layer/layerSurfacePress';import {useLayerDismissal} from '../Layer/useLayerDismissal';import {colorVars,@@ -273,6 +274,7 @@ function isFocusable(element: HTMLElement): boolean {* {hoverCard.renderHoverCard(<ProfileCard user={user} />)}* ```*/+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {const {placement = 'above',@@ -666,6 +668,11 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {return renderLayer(<div+ // FR11: a press inside the card acts only within the card. A+ // registered surface counts as something else in the shared+ // interactive-ancestor walk, so a clickable container around the+ // trigger leaves it alone; document listeners still see it.+ ref={registerLayerSurface}{...stylex.props(styles.content)}onMouseEnter={() => {// Touch synthesizes these over the card too; letting a tap insidediff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsxindex 316a0397a6..ab3621245e 100644--- a/packages/core/src/Item/Item.tsx+++ b/packages/core/src/Item/Item.tsx@@ -48,6 +48,7 @@ import {typeScaleVars,} from '../theme/tokens.stylex';import type {BaseProps} from '../BaseProps';+import {isLayerSurface} from '../Layer/layerSurfacePress';import {isRenderable} from '../utils/isRenderable';import {mergeProps} from '../utils/mergeProps';import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';@@ -56,7 +57,10 @@ import {ItemMarkerColumnsContext} from './ItemMarkerColumnsContext';import {useMergedRefs} from '../hooks/useMergedRefs';import {computeTargetAndRel} from '../Link/computeTargetAndRel';import {useLinkComponent} from '../Link/useLinkComponent';-import {useClickableContainer} from '../hooks/useClickableContainer';+import {+ innermostInteractive,+ useClickableContainer,+} from '../hooks/useClickableContainer';import {useDevWarning} from '../hooks/useDevWarning';import {themeProps} from '../utils/themeProps';import {focusOutlineProps} from '../utils/focusOutline.stylex';@@ -764,7 +768,12 @@ export function Item({return;}const target = e.target as HTMLElement;- if (target.closest('button, a, input, select, textarea')) {+ if (+ target.closest('button, a, input, select, textarea') ||+ // A press inside an open Tooltip or HoverCard belongs to it+ // (component:Tooltip FR11, component:HoverCard FR11).+ innermostInteractive(target, e.currentTarget, isLayerSurface) != null+ ) {return;}onClick?.(e);diff --git a/packages/core/src/Layer/layerSurfacePress.ts b/packages/core/src/Layer/layerSurfacePress.tsnew file mode 100644index 0000000000..758835090f--- /dev/null+++ b/packages/core/src/Layer/layerSurfacePress.ts@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file layerSurfacePress.ts+ * @input The content element of an open Tooltip or HoverCard surface.+ * @output A registry of those elements, so the shared "does this press belong+ * to something else" walk (hasInteractiveAncestor) treats a press inside one+ * as not the container's.+ * @position component:Tooltip FR11 and component:HoverCard FR11. The surfaces+ * register their content element; every clickable container that asks+ * hasInteractiveAncestor (useClickableContainer, TreeListItem, Table row+ * plugins), or walks with isLayerSurface (Item, Token), leaves the press+ * alone. The event+ * keeps propagating, so document and window listeners still see it. Not+ * exported from the package.+ */++const surfaces = new WeakSet<Element>();++/**+ * Ref callback for a layer surface's content element. The layer root around+ * it is registered too: a caller's `style`, `xstyle` or `className` (padding,+ * for instance) lands there, so a press on that edge is still the surface's.+ */+export function registerLayerSurface(element: Element | null): void {+ if (element == null) {+ return;+ }+ surfaces.add(element);+ const root = element.parentElement;+ if (root?.hasAttribute('popover')) {+ surfaces.add(root);+ }+}++/** Whether this element is a registered layer surface. */+export function isLayerSurface(element: Element): boolean {+ return surfaces.has(element);+}diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsxindex 98036ce398..c8dfab44d0 100644--- a/packages/core/src/Token/Token.tsx+++ b/packages/core/src/Token/Token.tsx@@ -38,7 +38,9 @@ import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';import {focusOutlineProps} from '../utils/focusOutline.stylex';import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';+import {innermostInteractive} from '../hooks/useClickableContainer';import {usePressFeedback} from '../hooks/usePressFeedback';+import {isLayerSurface} from '../Layer/layerSurfacePress';import {useTranslator} from '../i18n';import type {TokenColorMap} from './index';import {disabledInteractionProps} from '../utils/disabledInteraction';@@ -489,7 +491,12 @@ export function Token({if (effectiveOnClick != null) {const handleContainerClick = (e: React.MouseEvent) => {const target = e.target as HTMLElement;- if (target.closest('button, a')) {+ if (+ target.closest('button, a') ||+ // A press inside an open Tooltip or HoverCard belongs to it+ // (component:Tooltip FR11, component:HoverCard FR11).+ innermostInteractive(target, e.currentTarget, isLayerSurface) != null+ ) {return;}effectiveOnClick(e);diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsxindex 5eaac92360..b5e3e3cb11 100644--- a/packages/core/src/Tooltip/Tooltip.test.tsx+++ b/packages/core/src/Tooltip/Tooltip.test.tsx@@ -27,6 +27,9 @@ import {} from '@testing-library/react';import {useRef} from 'react';import {Tooltip} from './Tooltip';+import {ClickableCard} from '../ClickableCard/ClickableCard';+import {Item} from '../Item/Item';+import {Token} from '../Token/Token';import {useTooltip} from './useTooltip';import {__resetInteractionModalityForTest} from '../utils/interactionModality';@@ -817,3 +820,108 @@ describe('Tooltip sibling mode (anchorRef)', () => {expect(anchor.getAttribute('aria-describedby')).toBe(null);});});++// FR11: a press inside an open tooltip acts only within the tooltip.+describe('Tooltip surface press', () => {+ it('keeps a click on the tooltip text from activating a clickable card', () => {+ const onCardClick = vi.fn();+ render(+ <ClickableCard label="Card" onClick={onCardClick}>+ <span>Card body</span>+ <Tooltip content="Tooltip text" isOpen>+ <button type="button">Trigger</button>+ </Tooltip>+ </ClickableCard>,+ );+ fireEvent.click(screen.getByText('Tooltip text'));+ expect(onCardClick).not.toHaveBeenCalled();+ // Positive control: a click on the card's own content still activates it.+ fireEvent.click(screen.getByText('Card body'));+ expect(onCardClick).toHaveBeenCalledTimes(1);+ });++ it('keeps a click on the tooltip text from running an Item row', () => {+ const onRowClick = vi.fn();+ render(+ <Item+ label="Row"+ onClick={onRowClick}+ endContent={+ <Tooltip content="Tooltip text" isOpen>+ <span tabIndex={0}>Info</span>+ </Tooltip>+ }+ />,+ );+ fireEvent.click(screen.getByText('Tooltip text'));+ expect(onRowClick).not.toHaveBeenCalled();+ fireEvent.click(screen.getByText('Row'));+ expect(onRowClick).toHaveBeenCalledTimes(1);+ });++ it('keeps a click on the tooltip text from running a Token', () => {+ const onTokenClick = vi.fn();+ render(+ <Token+ label="Tag"+ onClick={onTokenClick}+ endContent={+ <Tooltip content="Tooltip text" isOpen>+ <span tabIndex={0}>Info</span>+ </Tooltip>+ }+ />,+ );+ fireEvent.click(screen.getByText('Tooltip text'));+ expect(onTokenClick).not.toHaveBeenCalled();+ fireEvent.click(screen.getByText('Tag'));+ expect(onTokenClick).toHaveBeenCalledTimes(1);+ });++ it('keeps a middle-button press on the tooltip text from opening a card link', () => {+ const open = vi.spyOn(window, 'open').mockReturnValue(null);+ render(+ <ClickableCard label="Card" href="https://example.com/">+ <Tooltip content="Tooltip text" isOpen>+ <button type="button">Trigger</button>+ </Tooltip>+ </ClickableCard>,+ );+ fireEvent.mouseUp(screen.getByText('Tooltip text'), {button: 1});+ expect(open).not.toHaveBeenCalled();+ open.mockRestore();+ });++ it('still lets document listeners see a click on the tooltip text', () => {+ // A Typeahead or menu inside a layer closes and opens from document+ // listeners, so the press must keep propagating.+ const onDocumentClick = vi.fn();+ document.addEventListener('click', onDocumentClick);+ render(+ <Tooltip content="Tooltip text" isOpen>+ <button type="button">Trigger</button>+ </Tooltip>,+ );+ fireEvent.click(screen.getByText('Tooltip text'));+ document.removeEventListener('click', onDocumentClick);+ expect(onDocumentClick).toHaveBeenCalledTimes(1);+ });++ it('keeps a click on the tooltip text inside a label from toggling its control', () => {+ render(+ <label>+ <input type="checkbox" /> Accept{' '}+ <Tooltip content="Why we ask" isOpen>+ <button type="button">Info</button>+ </Tooltip>+ </label>,+ );+ // The surface mounts outside the label (a label cannot contain it), so+ // a click on its text is not label activation.+ fireEvent.click(screen.getByText('Why we ask'));+ expect(screen.getByRole('checkbox')).not.toBeChecked();+ // Positive control: a click on the label's own text still toggles it.+ fireEvent.click(screen.getByText('Accept'));+ expect(screen.getByRole('checkbox')).toBeChecked();+ });+});diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsxindex 56b7e74b62..9c272eade4 100644--- a/packages/core/src/Tooltip/useTooltip.tsx+++ b/packages/core/src/Tooltip/useTooltip.tsx@@ -31,6 +31,7 @@ import {type LayerTouchTrigger,} from '../Layer/useTouchTrigger';import {layerAnimations} from '../Layer/layerAnimations.stylex';+import {registerLayerSurface} from '../Layer/layerSurfacePress';import {useLayerDismissal} from '../Layer/useLayerDismissal';import {themeProps} from '../utils/themeProps';import {@@ -264,6 +265,7 @@ function isFocusable(element: HTMLElement): boolean {* {tooltip.renderTooltip('Helpful tooltip text')}* ```*/+export function useTooltip(options: TooltipOptions = {}): TooltipReturn {const {placement = 'above',@@ -636,7 +638,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {};return renderLayer(- <div {...stylex.props(styles.content)}>{children}</div>,+ // FR11: React bubbles a press on the surface to the trigger's+ // ancestors, portaled or not. A registered surface counts as+ // something else in the shared interactive-ancestor walk, so a+ // clickable container around the trigger leaves the press alone while+ // document listeners still see it.+ <div ref={registerLayerSurface} {...stylex.props(styles.content)}>+ {children}+ </div>,renderProps,);},diff --git a/packages/core/src/hooks/useClickableContainer.ts b/packages/core/src/hooks/useClickableContainer.tsindex 43b070f45f..a6781ce57f 100644--- a/packages/core/src/hooks/useClickableContainer.ts+++ b/packages/core/src/hooks/useClickableContainer.ts@@ -22,6 +22,7 @@*/import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';+import {isLayerSurface} from '../Layer/layerSurfacePress';import {isSafeUrl} from '../utils/safeUrl';/**@@ -108,9 +109,18 @@ export function innermostInteractive(* instance, has no ref to hand the hook but needs the identical rule. Sharing* the walk keeps one definition of "this click belongs to something else"* instead of a short hand-rolled selector list per caller.+ *+ * A press inside an open Tooltip or HoverCard surface also answers true: it+ * belongs to that surface, not the container around its trigger.*/export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {- return innermostInteractive(el, rootEl) != null;+ return innermostInteractive(el, rootEl, belongsToSomethingElse) != null;+}++// A press inside an open Tooltip or HoverCard surface belongs to that surface+// (component:Tooltip FR11, component:HoverCard FR11).+function belongsToSomethingElse(element: Element): boolean {+ return matchesInteractiveSelectors(element) || isLayerSurface(element);}/**