Skip to content

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

TypeScript

spec(Tooltip, HoverCard): rename pressTrigger to triggerBehavior ('adaptive' | 'hover' | 'toggle') (#9379)

Cindy Zhanga68e0e372f61
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.md
index 724ca80876..4909fc57cf 100644
--- a/docs/architecture/interaction-modality.md
+++ b/docs/architecture/interaction-modality.md
@@ -160,7 +160,7 @@ work.
whose accessible name already carries its text is not a separate
interaction, so a tap on that trigger performs the action and does not open
the tooltip; information that lives only in a hint is reachable on touch
- through `pressTrigger="toggle"` (`component:Tooltip` DEC-1).
+ through `triggerBehavior="toggle"` (`component:Tooltip` DEC-1).
- **INV5 — Existing state semantics win.** Disabled controls do not become
interactive because of modality. Read-only and busy controls preserve their
documented focus and activation behavior.
@@ -331,7 +331,7 @@ reachability, newer-intent precedence, and the evidence/scope guard were approve
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INV1, INV2 | Programmatic-focus cases after keyboard and pointer input in representative component tests | Programmatic focus invents a modality, or pointer history paints the keyboard indicator |
| INV3 | Direct-owner, wrapper-owner, replaceable-indicator, and nested-action cases, including a Token inside an Item and a control inside a card; evidence gap for the shared-module cases: the module does not exist yet | No indicator, two indicators, replacement content that can opt out, or a component that writes the focus-owner attribute or selector itself |
-| INV4 | Keyboard, mouse, touch, and pen browser paths where applicable; tap cases on an action trigger with a label tooltip and on a hint-only trigger with `pressTrigger="toggle"` | Hover-only behavior, sticky touch hover, unreachable action, a tap on an action trigger that opens its label tooltip, or hint-only information with no touch path |
+| INV4 | Keyboard, mouse, touch, and pen browser paths where applicable; tap cases on an action trigger with a label tooltip and on a hint-only trigger with `triggerBehavior="toggle"` | Hover-only behavior, sticky touch hover, unreachable action, a tap on an action trigger that opens its label tooltip, or hint-only information with no touch path |
| INV5 | Disabled, busy, and read-only DOM and activation assertions | Inactive control reacts, eligible control loses focus, or state changes with modality |
| INV6 | Public API review and representative source inspection | A component adds caller-controlled modality without a separate API decision |
| INV7 | Rendered-browser affected-state checks across geometry, clipping, scrolling, hit testing, built-in and custom-renderer paths | At an offered interaction point one modality loses every essential path, or evidence substitutes class equality for reachability/perceptibility |
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
index 397dd74b55..e6f4849ca1 100644
--- a/docs/specs/AST-082-native-first-surfaces/spec.md
+++ b/docs/specs/AST-082-native-first-surfaces/spec.md
@@ -85,7 +85,7 @@ depends only on runtimes it can maintain.
announcements). It is the same on every platform that offers the component.
- A platform honors a prop when the prop behaves the way core already defines
for that platform's input type. `tooltip` stays in the core: core defines
- what a tooltip does where there is no hover (Tooltip `pressTrigger`), and a
+ what a tooltip does where there is no hover (Tooltip `triggerBehavior`), and a
touch platform behaves that way.
- A prop leaves the core only when a platform that offers the component cannot
match core's defined behavior for its input type. Such a prop belongs to the
diff --git a/docs/specs/components/HoverCard/HoverCard.spec.md b/docs/specs/components/HoverCard/HoverCard.spec.md
index d09f181946..a078589db2 100644
--- a/docs/specs/components/HoverCard/HoverCard.spec.md
+++ b/docs/specs/components/HoverCard/HoverCard.spec.md
@@ -37,15 +37,15 @@ system_specs: [spec:AST-003, spec:AST-017]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `pressTrigger` (`none`), `touchTrigger` (`tap` deprecated by `component:Tooltip` DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. `useHoverCard` takes the same `pressTrigger` and `touchTrigger`. |
-| Behavior | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after `delay`, on focus, and on a qualifying tap, stays open while the pointer is on the trigger or card, and closes on leave, Escape, or a tap outside. With `label` it is a named dialog the trigger advertises; without, a group that describes the trigger. With `pressTrigger="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
-| End-user impact | Mouse, keyboard, and touch users can open the preview, move into it to use its actions, and dismiss it; screen-reader users hear it as a named popup dialog or as the trigger's description. With the toggle, a pinned card stays open while people read or use it, whatever the pointer does. |
-| Builder impact | A trigger whose information lives only in the card passes `pressTrigger="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement at the next minor. |
-| Compatibility/readiness | Additive `pressTrigger`, default `none`; `touchTrigger="tap"` deprecated and `touchTrigger` folded into `pressTrigger` at the next minor (`component:Tooltip` DEP-0016, CLN-0024). FR9, FR10, and AR3 are not yet built; eight further implementation gaps (see Current-state impact). |
-| Review checks | Reject an unnamed `dialog`, a card that cannot be hovered or dismissed (WCAG 1.4.13), Escape in the page that also closes a layer underneath, or `aria-expanded` set on a trigger whose role does not support it, a pinned card that closes on pointer leave, or a non-button toggle trigger without the development warning. |
-| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `triggerBehavior` (`adaptive`), `touchTrigger` (`tap` deprecated by `component:Tooltip` DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. `useHoverCard` takes the same `triggerBehavior` and `touchTrigger`. |
+| Behavior | A floating card of rich, possibly interactive content anchored to a trigger. It opens on hover after `delay`, on focus, and on a qualifying tap, stays open while the pointer is on the trigger or card, and closes on leave, Escape, or a tap outside. With `label` it is a named dialog the trigger advertises; without, a group that describes the trigger. With `triggerBehavior="hover"`, touch never opens it. With `triggerBehavior="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
+| End-user impact | Mouse, keyboard, and touch users can open the preview, move into it to use its actions, and dismiss it; screen-reader users hear it as a named popup dialog or as the trigger's description. With the toggle, a pinned card stays open while people read or use it, whatever the pointer does. |
+| Builder impact | A trigger whose information lives only in the card passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement at the next minor. |
+| Compatibility/readiness | Additive `triggerBehavior`, default `adaptive`, the released behavior; `touchTrigger="tap"` deprecated and `touchTrigger` removed at the next minor, `triggerBehavior="adaptive"` keeping its `auto` behavior and `triggerBehavior="hover"` its `none` behavior (`component:Tooltip` DEP-0016, CLN-0024). FR9, FR10, and AR3 are not yet built; eight further implementation gaps (see Current-state impact). |
+| Review checks | Reject an unnamed `dialog`, a card that cannot be hovered or dismissed (WCAG 1.4.13), Escape in the page that also closes a layer underneath, or `aria-expanded` set on a trigger whose role does not support it, a pinned card that closes on pointer leave, or a non-button toggle trigger without the development warning. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -58,28 +58,29 @@ Consumer usage lives in `HoverCard.doc.mjs`.
## Compatibility and migration
-- Released default preserved: the defaults stay `pressTrigger="none"` and
- `touchTrigger="auto"`. In patch releases `auto` keeps its released
- behavior: a tap opens the card unless the trigger itself performs an
+- Released default preserved: the default `triggerBehavior="adaptive"` is the
+ released behavior, and `touchTrigger` keeps its default `auto`. In patch
+ releases `adaptive` keeps that released behavior: a tap opens the card unless the trigger itself performs an
action. The one exception is a disabled control, which is not an action, so
its reason opens on a tap; that restoration ships on its own as a patch
`[fix]`. FR5's walk, under which a tap that already acts on a control around
the trigger does not open the card, needs app code where a hint-only
- trigger sits inside a control (it declares `pressTrigger="toggle"`), so it
+ trigger sits inside a control (it declares `triggerBehavior="toggle"`), so it
is a breaking change under `spec:AST-017` FR1 and DEC-17 and ships with
CLN-0024 in the next minor; no caller's behavior changes in a patch
-- Compatibility class: additive `pressTrigger`; `touchTrigger="tap"` is
+- Compatibility class: additive `triggerBehavior`; `touchTrigger="tap"` is
deprecated; FR5's walk is a breaking change for the next minor
(`component:Tooltip` CLN-0024); no DOM or styling change without
- `pressTrigger`
+ `triggerBehavior`; until CLN-0024, an explicit `touchTrigger` decides taps
+ under `triggerBehavior="adaptive"`, and `hover` and `toggle` ignore it
- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
state, and a controlled card reports close requests through
`onOpenChange(false)` without closing itself (FR7); under
- `pressTrigger="toggle"` a press on a controlled card reports the toggled
+ `triggerBehavior="toggle"` a press on a controlled card reports the toggled
value through `onOpenChange` and does not change the state itself (FR9)
- Migration decision: `component:Tooltip` DEP-0016, then CLN-0024 in the next
minor; both cover HoverCard's and `useHoverCard`'s `touchTrigger`, with the
- same codemods, and CLN-0024 brings FR5's walk to `auto`
+ same codemods, and CLN-0024 brings FR5's walk to `adaptive`
Consumer migration instructions belong in consumer docs and release notes.
@@ -90,9 +91,10 @@ Consumer migration instructions belong in consumer docs and release notes.
so a name or ID inside a clickable card opens its card on the tap that opens
the card behind it. The walk ships with `component:Tooltip` CLN-0024 (FR5,
DEC-1).
-- **Press-to-pin is not built.** `pressTrigger`, its toggle (FR9), and the
- trigger wiring and announcement (FR10) are specified and not implemented.
- `touchTrigger="tap"` is the shipped way to open on every tap.
+- **Toggle pinning is not built.** `triggerBehavior` and its three values, the
+ toggle (FR9), and the trigger wiring and announcement (FR10) are specified
+ and not implemented. `touchTrigger="tap"` is the shipped way to open on every
+ tap, and `touchTrigger="none"` the shipped way to open on no tap.
- **A held-closed card still opens on focus.** With `isOpen={false}`, the hover
path stays shut but focus on the trigger opens the card, so a caller cannot
hold it closed. Escape then only reports `onOpenChange(false)`, which the
@@ -148,28 +150,28 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ------- | --------------------- | --------------------------------------------------------------------------------------------- | -------------------------------- |
-| Popup role | named dialog, group | `label` makes the card a named `dialog`; without it the card is a `group`. | Every card. | group | `component:HoverCard` | Stable | Not applicable. |
-| Focus trigger | `auto`, `always`, `never` | Whether focus opens the card: on focusable triggers (FR4's gap), always, or never. | Every trigger. | `auto` | `component:HoverCard` | Stable | TypeScript rejects other values. |
-| Press trigger | `none`, `toggle` | Whether a click, tap, Enter, or Space on the trigger pins the card open: never, leaving taps to `touchTrigger`, or on every press (FR9). | Button triggers; a non-button trigger keeps tap-only opening (FR9). | `none` | `component:HoverCard` | Stable | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; never. Ignored under `pressTrigger="toggle"`. | Touch without hover. | `auto` | `component:HoverCard` | Stable; `tap` deprecated (`component:Tooltip` DEP-0016); folds into `pressTrigger` (CLN-0024) | TypeScript rejects other values. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------- | --------------------- | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| Popup role | named dialog, group | `label` makes the card a named `dialog`; without it the card is a `group`. | Every card. | group | `component:HoverCard` | Stable | Not applicable. |
+| Focus trigger | `auto`, `always`, `never` | Whether focus opens the card: on focusable triggers (FR4's gap), always, or never. | Every trigger. | `auto` | `component:HoverCard` | Stable | TypeScript rejects other values. |
+| Trigger behavior | `adaptive`, `hover`, `toggle` | How the trigger opens the card; under every value, hover on a fine pointer and focus preview it (FR4). Under `adaptive`, a tap opens it unless the tap already acts (FR5, DEC-1), and no press pins it; under `hover`, touch never opens it, and no press pins it; under `toggle`, a click, a completed tap, Enter, or Space pins it, and the same press on a pinned card closes it (FR9). | Every trigger; `toggle` pins only on a button trigger, and any other trigger keeps tap-only opening (FR9). | `adaptive` | `component:HoverCard` | Stable | TypeScript rejects other values. |
+| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it under `triggerBehavior="adaptive"`: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; never. Ignored under `triggerBehavior="hover"` and `"toggle"`. | Touch without hover. | `auto` | `component:HoverCard` | Stable; `tap` deprecated (`component:Tooltip` DEP-0016); removed at the next minor (CLN-0024) | TypeScript rejects other values. |
## 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` |
-| 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 |
+| 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 `triggerBehavior` when the finger lifts; a touch that becomes a scroll does not. Under `adaptive`, 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). Until `component:Tooltip` CLN-0024 removes `touchTrigger`, an explicit `touchTrigger` decides instead under `adaptive`: `tap` opens on every tap and `none` on no tap. Implementation gap: the walk ships with `component:Tooltip` CLN-0024 in the next minor; until then `adaptive`, like the shipped `touchTrigger="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 `hover`, no tap opens it. Under `toggle`, FR9 decides what a tap does. `hover` and `toggle` ignore `touchTrigger`. | 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 `triggerBehavior="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: every completed tap opens the card, and no press pins it. Implementation gap: not yet built (Current-state impact). | DEC-1; WCAG 1.4.13, 2.1.1 |
+| FR10 | While `triggerBehavior="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
@@ -204,7 +206,7 @@ Consumer migration instructions belong in consumer docs and release notes.
dismissible, and persistent per WCAG 1.4.13, except FR6's other-document gap,
FR7's held-closed Escape gap, and the pointer-only hold (Current-state
impact).
-- **AR3 — A pinned card is a toggletip.** Under `pressTrigger="toggle"` the
+- **AR3 — A pinned card is a toggletip.** Under `triggerBehavior="toggle"` the
trigger is a named button that reports `aria-expanded` and `aria-controls`
(FR10); keyboard and touch users pin and close the card without hover (FR9);
it is announced once when it pins (FR10); and it persists until Escape, a
@@ -251,15 +253,16 @@ 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; `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` |
+| 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` |
+| FR5, FR9 (`triggerBehavior`) | Evidence gap until built: a trigger-behavior suite in `HoverCard.test.tsx` | `adaptive` by default and explicitly, `hover`, and `toggle`, each with mouse hover, focus, and touch; `touchTrigger` beside each value | Under any value, a lost hover or focus preview; under `adaptive`, an info-only tap that leaves the card shut or a press that pins it; under `hover`, a tap that opens it or a press that pins it; under `toggle`, a click, tap, Enter, or Space that does not pin or close it as FR9 states; or a `touchTrigger` that changes `hover` or `toggle`, 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:
@@ -276,20 +279,22 @@ Read from source, with no focused test yet:
### DEC-1 — A press pins the card; a tap that already acts stays with its control
**Reference:** `component:HoverCard/DEC-1`
-**Decider:** `cixzhang`, `2026-10-31`
+**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01`
-A card keeps previewing on hover and focus, and `pressTrigger="toggle"` adds
+A card keeps previewing on hover and focus, and `triggerBehavior="toggle"` adds
one more open state of the same layer: a press pins it, so people on touch,
keyboard, or a screen reader can keep it open to read or use it. Components
-declare `pressTrigger="toggle"` where the card is the only home of their
-information, such as a timestamp's details. `touchTrigger="auto"`, the
-default until `touchTrigger` folds into `pressTrigger` at the next minor, is
-the fallback: under it, a tap that already acts does not open the card. The
+declare `triggerBehavior="toggle"` where the card is the only home of their
+information, such as a timestamp's details. `adaptive`, the default and the
+released behavior, previews on hover and focus and opens on a tap; `hover`
+previews on hover and focus only, so touch never opens the card; `toggle` adds
+the pin on every device. Under `adaptive`, a tap that already acts does not
+open the card. The
walk that decides it starts at the tapped element and the innermost control
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,
+`touchTrigger="tap"` and the removal of `touchTrigger` 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 over
diff --git a/docs/specs/components/InfoTip/InfoTip.spec.md b/docs/specs/components/InfoTip/InfoTip.spec.md
index 5e8419a05d..efcaff9c89 100644
--- a/docs/specs/components/InfoTip/InfoTip.spec.md
+++ b/docs/specs/components/InfoTip/InfoTip.spec.md
@@ -35,7 +35,7 @@ system_specs: [spec:AST-017, spec:AST-094]
| Area | Contract |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public contract | `InfoTip` from `@astryxdesign/core` with `content`, `label` (a localized "More information"), `size` (`sm`), a `ref` forwarded to the button, and BaseProps' `xstyle`, `className`, and `style`. The `@astryxdesign/lab` export is a deprecated re-export for one release. |
-| Behavior | A named info-icon button wrapped in `component:Tooltip` with `pressTrigger="toggle"`: hover and focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. |
+| Behavior | A named info-icon button wrapped in `component:Tooltip` with `triggerBehavior="toggle"`: hover and focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. |
| End-user impact | People on a mouse, touch, keyboard, or screen reader can open, keep open, and close the help behind an "i", and hear it once when it pins. |
| Builder impact | Use InfoTip for help next to a label, value, or metric instead of composing an icon inside Tooltip. Lab callers change the import. |
| Compatibility/readiness | New in Core; Core has no implementation yet (Current-state impact). The Lab component ships with Tooltip's `touchTrigger="tap"` and an English default name. |
@@ -56,7 +56,7 @@ Consumer usage lives in `InfoTip.doc.mjs`.
- Released default preserved: not yet released in Core; the Lab component's
props keep their meaning
- Compatibility class: additive Core export; the Lab component moves to Core
- with the same props and opens through `pressTrigger="toggle"` instead of
+ with the same props and opens through `triggerBehavior="toggle"` instead of
`touchTrigger="tap"`
- Controlled/uncontrolled behavior: uncontrolled only; open state is Tooltip's
- Migration decision: DEC-1; the `@astryxdesign/lab` `InfoTip` export stays one
@@ -87,7 +87,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- Info artwork resolution — owned by the icon registry
(`architecture:icon-resolution-and-component-slots`).
- Rich or interactive help — `component:HoverCard` with
- `pressTrigger="toggle"`.
+ `triggerBehavior="toggle"`.
## Public concepts
@@ -97,12 +97,12 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| FR1 | InfoTip renders one `<button type="button">` named by `label`, else the translated `@astryx.infoTip.label` ("More information"), containing the registry's `info` icon at `size`. Implementation gap: the Lab component's default name is an untranslated English literal (Current-state impact). | DEC-1; WCAG 2.2 SC 4.1.2; `architecture:icon-resolution-and-component-slots` |
-| FR2 | InfoTip wraps its button in `component:Tooltip` with `content` and `pressTrigger="toggle"`, and adds no layer, listener, timer, announcement, or dismissal rule of its own: previewing, pinning, closing, the trigger's `aria-expanded` and `aria-controls`, and the announcement are Tooltip's FR3–FR10. Implementation gap: the Lab component passes `touchTrigger="tap"` (Current-state impact). | DEC-1; `architecture:public-component-api` INV21 |
-| FR3 | The public props are `content` (required; short, noninteractive help), `label`, `size`, a `ref` forwarded to the button, and BaseProps' `xstyle`, `className`, and `style`; InfoTip takes no open-state, placement, or trigger props. | DEC-1 |
-| FR4 | The `@astryxdesign/lab` `InfoTip` export re-exports the Core component, marked deprecated with static metadata, for one release, and is then removed. | `spec:AST-017` FR29, FR29a |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| FR1 | InfoTip renders one `<button type="button">` named by `label`, else the translated `@astryx.infoTip.label` ("More information"), containing the registry's `info` icon at `size`. Implementation gap: the Lab component's default name is an untranslated English literal (Current-state impact). | DEC-1; WCAG 2.2 SC 4.1.2; `architecture:icon-resolution-and-component-slots` |
+| FR2 | InfoTip wraps its button in `component:Tooltip` with `content` and `triggerBehavior="toggle"`, and adds no layer, listener, timer, announcement, or dismissal rule of its own: previewing, pinning, closing, the trigger's `aria-expanded` and `aria-controls`, and the announcement are Tooltip's FR3–FR10. Implementation gap: the Lab component passes `touchTrigger="tap"` (Current-state impact). | DEC-1; `architecture:public-component-api` INV21 |
+| FR3 | The public props are `content` (required; short, noninteractive help), `label`, `size`, a `ref` forwarded to the button, and BaseProps' `xstyle`, `className`, and `style`; InfoTip takes no open-state, placement, or trigger props. | DEC-1 |
+| FR4 | The `@astryxdesign/lab` `InfoTip` export re-exports the Core component, marked deprecated with static metadata, for one release, and is then removed. | `spec:AST-017` FR29, FR29a |
### Allowed variation
@@ -174,7 +174,7 @@ Consumer migration instructions belong in consumer docs and release notes.
Help behind an "i" is the same job as a tooltip that pins on a press, so
InfoTip supplies only the named button, its icon, and its default, and is
-built entirely on `component:Tooltip` with `pressTrigger="toggle"`. A component
+built entirely on `component:Tooltip` with `triggerBehavior="toggle"`. A component
built entirely on another public API is one API with it
(`architecture:public-component-api` INV21, the reasoning `spec:AST-107` DEC-2
and DEC-3 apply to a component over a public factory), as `component:MoreMenu`
diff --git a/docs/specs/components/StatusDot/StatusDot.spec.md b/docs/specs/components/StatusDot/StatusDot.spec.md
index ad3e8bea50..5396f94278 100644
--- a/docs/specs/components/StatusDot/StatusDot.spec.md
+++ b/docs/specs/components/StatusDot/StatusDot.spec.md
@@ -35,15 +35,15 @@ system_specs: [spec:AST-009, spec:AST-094]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`. |
-| Behavior | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a standalone dot with a tooltip is a button named by `label` whose press pins the tooltip (`pressTrigger="toggle"`), so the tooltip is reachable by hover, touch, and keyboard; inside a button, link, menu item, or option, the dot stays an image and the host's accessible name carries the tooltip text (FR5). |
-| End-user impact | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. Inside a button, link, menu item, or option, sighted touch users lose the dot's visible tooltip text, and the host's accessible name carries the status for screen readers (FR5). |
-| Builder impact | StatusDot decides by placement. A standalone dot with a tooltip is a toggle button; inside a button, link, menu item, or option, the host carries the status in its accessible name, so a control never nests another control (FR5). A host named by `aria-label`, such as a Tab with `isLabelHidden`, takes no name from its content, so its caller includes the status in that label. |
-| Compatibility/readiness | No API or default change; a standalone dot with a tooltip becomes a button trigger with `pressTrigger="toggle"` no later than `component:Tooltip` FR5's walk ships, and a dot inside an interactive element hands its tooltip text to the host (FR5, not yet built). Three gaps are listed under Current-state impact. |
-| Review checks | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target. |
-| Governing rules | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1. |
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A fixed 8px status dot with a required theme-extensible `variant` and a required `label`, plus optional `isPulsing`, `tooltip`, and `icon`. |
+| Behavior | The dot is an image named by `label`; a renderable `icon` paints inside it in the variant's ink and is hidden from assistive technology; a standalone dot with a tooltip is a button named by `label` whose press pins the tooltip (`triggerBehavior="toggle"`), so the tooltip is reachable by hover, touch, and keyboard; inside a button, link, menu item, or option, the dot stays an image and the host's accessible name carries the tooltip text (FR5). |
+| End-user impact | Screen-reader users hear the status without hover; sighted users see a color signal, optionally pulsing and optionally carrying a non-color mark. Inside a button, link, menu item, or option, sighted touch users lose the dot's visible tooltip text, and the host's accessible name carries the status for screen readers (FR5). |
+| Builder impact | StatusDot decides by placement. A standalone dot with a tooltip is a toggle button; inside a button, link, menu item, or option, the host carries the status in its accessible name, so a control never nests another control (FR5). A host named by `aria-label`, such as a Tab with `isLabelHidden`, takes no name from its content, so its caller includes the status in that label. |
+| Compatibility/readiness | No API or default change; a standalone dot with a tooltip becomes a button trigger with `triggerBehavior="toggle"` no later than `component:Tooltip` FR5's walk ships, and a dot inside an interactive element hands its tooltip text to the host (FR5, not yet built). Three gaps are listed under Current-state impact. |
+| Review checks | Reject a dot without an accessible name, a dot without a tooltip that adds its own tab stop, an icon exposed to assistive technology, a pulse that ignores reduced motion, or a second target. |
+| Governing rules | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:theme-tokens/INV11`; WCAG 2.2 2.1.1. |
This table is a review projection; the body below is authoritative.
@@ -58,7 +58,7 @@ optional pulse, optional inner mark, and its accessible name.
- Released default preserved: `yes`
- Compatibility class: no public prop, default, or styling output change; with a
`tooltip`, a standalone dot becomes a button named by `label` inside Tooltip
- with `pressTrigger="toggle"`, adopted no later than `component:Tooltip`
+ with `triggerBehavior="toggle"`, adopted no later than `component:Tooltip`
FR5's walk ships with its CLN-0024, and a dot inside a button, link, menu item, or option
stays an image whose tooltip text joins the host's accessible name (FR5). The dot emits only the canonical `status-dot`
target; the `statusdot` alias is not emitted
@@ -79,8 +79,9 @@ Consumer migration instructions belong in consumer docs and release notes.
the tooltip text, where WCAG 2.2 2.1.1 expects functionality to be keyboard
operable. The accessible name still carries the status. Today a tap opens a
dot's tooltip, because the dot performs no action and Tooltip's default
- `auto` opens on such a tap, and a standalone dot does not yet take
- `pressTrigger="toggle"`, so its tooltip has no pin for touch or keyboard.
+ touch behavior (`touchTrigger="auto"`, which `triggerBehavior="adaptive"`
+ keeps) opens on such a tap, and a standalone dot does not yet take
+ `triggerBehavior="toggle"`, so its tooltip has no pin for touch or keyboard.
FR5 changes a dot inside a button, link, menu item, or option to an image
whose tooltip previews on hover only, so sighted touch users lose its visible
tooltip text there; the host's accessible name carries the status for screen
@@ -123,14 +124,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target. | Current source and tests |
-| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
-| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests. | Current source and tests |
-| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless. | Current source and tests |
-| FR5 | A non-empty `tooltip` renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and `pressTrigger="toggle"` and is the toggle's button trigger, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the toggle no later than `component:Tooltip` FR5's walk ships, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the toggle, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (`architecture:interaction-modality` INV4). A host named by `aria-label` takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests; `component:Tooltip` DEC-1 |
-| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
+| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target. | Current source and tests |
+| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
+| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests. | Current source and tests |
+| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless. | Current source and tests |
+| FR5 | A non-empty `tooltip` renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and `triggerBehavior="toggle"` and is the toggle's button trigger, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the toggle no later than `component:Tooltip` FR5's walk ships, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the toggle, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (`architecture:interaction-modality` INV4). A host named by `aria-label` takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests; `component:Tooltip` DEC-1 |
+| FR6 | `ref` reaches the dot. Supported DOM, ARIA, data, and event props reach the dot after its role and name; `xstyle`, `className`, and `style` merge in that order after component styles. | Current source and tests |
### Allowed variation
diff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.md
index 1fa0c493c4..cb705452a8 100644
--- a/docs/specs/components/Tooltip/Tooltip.spec.md
+++ b/docs/specs/components/Tooltip/Tooltip.spec.md
@@ -40,15 +40,15 @@ system_specs: [spec:AST-003, spec:AST-017]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `pressTrigger` (`none`), `touchTrigger` (`auto`; `tap` deprecated by DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. `useTooltip` takes the same `pressTrigger` and `touchTrigger`. |
-| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `pressTrigger="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
-| End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. With the toggle, people on touch, keyboard, or a screen reader can keep it open to read it, and hear it once when it pins. |
-| Builder impact | A trigger whose information lives only in the tooltip passes `pressTrigger="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement at the next minor. |
-| Compatibility/readiness | Additive `pressTrigger`, default `none`; `touchTrigger="tap"` deprecated (DEP-0016); `touchTrigger` folds into `pressTrigger` at the next minor (CLN-0024). FR9, FR10, and AR6 are not yet built; ten further implementation gaps (see Current-state impact). |
-| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a toggle without `aria-expanded`, or a non-button toggle trigger without the development warning. |
-| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `triggerBehavior` (`adaptive`), `touchTrigger` (`auto`; `tap` deprecated by DEP-0016), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. `useTooltip` takes the same `triggerBehavior` and `touchTrigger`. |
+| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `triggerBehavior="hover"`, no touch or pen tap opens it. With `triggerBehavior="toggle"`, hover and focus preview it, and a click, tap, Enter, or Space on a button trigger pins it open until Escape, a second press, a press outside, or focus leaving. |
+| End-user impact | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description. With the toggle, people on touch, keyboard, or a screen reader can keep it open to read it, and hear it once when it pins. |
+| Builder impact | A trigger whose information lives only in the tooltip passes `triggerBehavior="toggle"` and a button trigger (DEC-1). `touchTrigger="tap"` callers migrate by trigger kind: the deprecating release's codemod rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement at the next minor. |
+| Compatibility/readiness | Additive `triggerBehavior`, default `adaptive`, the released behavior; `touchTrigger="tap"` deprecated (DEP-0016); `touchTrigger` is removed at the next minor, `triggerBehavior="adaptive"` keeping its `auto` behavior and `triggerBehavior="hover"` its `none` behavior (CLN-0024). FR9, FR10, and AR6 are not yet built; ten further implementation gaps (see Current-state impact). |
+| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a toggle without `aria-expanded`, or a non-button toggle trigger without the development warning. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (deprecation); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -61,56 +61,58 @@ in `Tooltip.doc.mjs`.
## Compatibility and migration
-- Released default preserved: the defaults stay `pressTrigger="none"` and
- `touchTrigger="auto"`. In patch releases `auto` keeps its released
- behavior: a tap opens the tooltip unless the trigger itself performs an
+- Released default preserved: the default `triggerBehavior="adaptive"` is the
+ released behavior, and `touchTrigger` keeps its default `auto`. In patch
+ releases `adaptive` keeps that released behavior: a tap opens the tooltip unless the trigger itself performs an
action. The one exception is a disabled control, which is not an action, so
its reason opens on a tap; that restoration ships on its own as a patch
`[fix]`. FR5's walk, under which a tap that already acts on a control around
the trigger does not open the tooltip, needs app code where a hint-only
- trigger sits inside a control (it declares `pressTrigger="toggle"`), so it
+ trigger sits inside a control (it declares `triggerBehavior="toggle"`), so it
is a breaking change under `spec:AST-017` FR1 and DEC-17 and ships with
CLN-0024 in the next minor; no caller's behavior changes in a patch
-- Compatibility class: additive `pressTrigger`; `touchTrigger="tap"` is
+- Compatibility class: additive `triggerBehavior`; `touchTrigger="tap"` is
deprecated (DEP-0016); FR5's walk is a breaking change for the next minor
- (CLN-0024); DOM, styling, and targets remain unchanged without `pressTrigger`
+ (CLN-0024); DOM, styling, and targets remain unchanged without `triggerBehavior`;
+ until CLN-0024, an explicit `touchTrigger` decides taps under
+ `triggerBehavior="adaptive"`, and `hover` and `toggle` ignore it
- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
state, and a controlled tooltip reports close requests through
`onOpenChange(false)` without closing itself (FR7); under
- `pressTrigger="toggle"` a press on a controlled tooltip reports the toggled
+ `triggerBehavior="toggle"` a press on a controlled tooltip reports the toggled
value through `onOpenChange` and does not change the state itself (FR9)
- Migration decision: DEP-0016, then CLN-0024 in the next minor
### DEP-0016 — Deprecate `touchTrigger="tap"`
-| Field | Value |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id | `DEP-0016` |
-| cleanup | `CLN-0024` |
-| package | `@astryxdesign/core` |
-| surface | `touchTrigger="tap"` on `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard` |
-| old contract | Every completed tap opens the layer, even on a trigger that performs its own action; a mouse click, Enter, or Space does not keep it open |
-| replacement | `pressTrigger="toggle"`: a tap still opens the layer, and a click, Enter, or Space pins it too (FR9); a non-button trigger keeps tap-only opening (FR9) |
-| direct authority | `component:Tooltip` DEC-1 and `component:HoverCard` DEC-1. Owner: `cixzhang` |
-| warning | Static `@deprecated` metadata on the `tap` value; consumer docs and the release notes name `DEP-0016` and `pressTrigger="toggle"`. No runtime warning (`spec:AST-017` FR29, FR29a). When `touchTrigger` and `pressTrigger="toggle"` are both given, `pressTrigger` wins |
-| migration | Mechanical only where the result is observably the same: on a trigger that is statically a non-interactive element, such as an icon or a span, `pressTrigger="toggle"` replaces `touchTrigger="tap"`. That rewrite keeps every production behavior because FR9 keeps a non-button toggle trigger on tap-only opening, as `touchTrigger="tap"` does; in development such a trigger also gets FR9's warning, which points its caller to a button trigger. On a trigger whose tooltip repeats its own text, a button, a link, or an element the codemod cannot identify, the toggle changes what a click, Enter, or Space does (and on a button adds `aria-expanded`), so the caller migrates by hand; the deprecated `tap` keeps working until CLN-0024 |
-| codemod | An `astryx upgrade` codemod staged in `packages/cli/assets/codemods/transforms/next/`, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates `tap`: it rewrites static `touchTrigger="tap"` to `pressTrigger="toggle"` only where the trigger is statically a non-interactive icon or span, which FR9 keeps on tap-only opening, reports every other `touchTrigger="tap"` site (an own-text trigger, a button, a link, or an unknown element) with a manual-migration note and leaves it unchanged, removes static `touchTrigger="auto"`, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d) |
-| downstream | In the deprecating release, Core FieldLabel's info icon moves from `touchTrigger="tap"` to `component:InfoTip` with `pressTrigger="toggle"` (`component:FieldLabel` FR9), and Lab InfoTip and the CLI page templates migrate too, the templates to a button trigger with `pressTrigger="toggle"` so they carry no development warning (`spec:AST-017` FR29c); docs, stories, templates, and examples teach only `pressTrigger` |
-| transition | no prior transition |
-| state | `proposed` |
-| target plan | `CLN-0024` in the next minor release |
-
-### CLN-0024 — `touchTrigger` folds into `pressTrigger`
-
-| Field | Value |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id | `CLN-0024` |
-| lifecycle | `DEP-0016` |
-| delta | `touchTrigger` is removed from `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`. `pressTrigger` takes `auto`, `toggle`, and `none`, default `auto`: `auto` is the released `touchTrigger="auto"` (a tap opens the layer unless the trigger performs its own action, and no press pins it), `none` is the released `touchTrigger="none"` (no tap or press opens it), and `toggle` is unchanged. `auto` gains FR5's walk: a tap that already acts on a control around the trigger does not open the layer. A hint-only trigger inside a control migrates by declaring `pressTrigger="toggle"`, which no codemod can decide; Astryx's own info-only triggers (InfoTip, FieldLabel's info button, and a standalone StatusDot) declare it before this minor; a StatusDot inside a button, link, menu item, or option stays an image whose status the host's accessible name carries. One prop decides what a press does |
-| replacement | Each remaining `touchTrigger="tap"` site has a named replacement (`spec:AST-017` FR8): a button or link whose only job is its tooltip takes `pressTrigger="toggle"`, so its tooltip keeps a touch path; a button or link with its own action whose accessible name already carries the layer's text drops `tap` and takes `auto`, so a tap performs the action and opens no layer (`architecture:interaction-modality` INV4's case); any other button or link with its own action moves the layer's information to an adjacent info trigger that declares `pressTrigger="toggle"`, such as an InfoTip, or into its visible label, so that information keeps a touch path, and then drops `tap`; a trigger whose tooltip repeats its own text takes `pressTrigger="toggle"` (FR9's own-text exception); an unknown element is reported for a manual choice (`architecture:interaction-modality` INV4) |
-| codemod | The minor's `astryx upgrade` codemod, with tests and fixtures: `touchTrigger="none"` becomes `pressTrigger="none"`; `touchTrigger="auto"` and the released `pressTrigger="none"` are removed, since `auto` reproduces them; `pressTrigger="toggle"` is kept and any `touchTrigger` beside it removed; a remaining `touchTrigger="tap"` becomes `pressTrigger="toggle"` on an own-text trigger the codemod can identify; every button and link `tap` site is reported with the options in its note (`pressTrigger="toggle"` when the trigger's only job is its layer; remove `tap` for `auto` when the trigger's accessible name already carries the layer's text; otherwise move the information to an adjacent InfoTip or the visible label, then remove `tap`), since no static check tells them apart, and every other remaining `tap` site is reported; spreads and dynamic values are reported |
-| rollback | Restore `touchTrigger` and the two-value `pressTrigger` from the final-patch baseline |
-| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
+| Field | Value |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `DEP-0016` |
+| cleanup | `CLN-0024` |
+| package | `@astryxdesign/core` |
+| surface | `touchTrigger="tap"` on `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`; `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now |
+| old contract | Every completed tap opens the layer, even on a trigger that performs its own action; a mouse click, Enter, or Space does not keep it open |
+| replacement | `triggerBehavior="toggle"`: a tap still opens the layer, and a click, Enter, or Space pins it too (FR9); a non-button trigger keeps tap-only opening (FR9) |
+| direct authority | `component:Tooltip` DEC-1 and `component:HoverCard` DEC-1. Owner: `cixzhang` |
+| warning | Static `@deprecated` metadata on the `tap` value; consumer docs and the release notes name `DEP-0016` and `triggerBehavior="toggle"`. No runtime warning (`spec:AST-017` FR29, FR29a). When `touchTrigger` is given beside `triggerBehavior="hover"` or `"toggle"`, `triggerBehavior` wins |
+| migration | Mechanical only where the result is observably the same: on a trigger that is statically a non-interactive element, such as an icon or a span, `triggerBehavior="toggle"` replaces `touchTrigger="tap"`. That rewrite keeps every production behavior because FR9 keeps a non-button toggle trigger on tap-only opening, as `touchTrigger="tap"` does; in development such a trigger also gets FR9's warning, which points its caller to a button trigger. On a trigger whose tooltip repeats its own text, a button, a link, or an element the codemod cannot identify, the toggle changes what a click, Enter, or Space does (and on a button adds `aria-expanded`), so the caller migrates by hand; the deprecated `tap` keeps working until CLN-0024 |
+| codemod | An `astryx upgrade` codemod staged in `packages/cli/assets/codemods/transforms/next/`, with tests and fixtures, checked by the codemod verify workflow, and available in the release that deprecates `tap`: it rewrites static `touchTrigger="tap"` to `triggerBehavior="toggle"` only where the trigger is statically a non-interactive icon or span, which FR9 keeps on tap-only opening, reports every other `touchTrigger="tap"` site (an own-text trigger, a button, a link, or an unknown element) with a manual-migration note and leaves it unchanged, removes static `touchTrigger="auto"`, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d) |
+| downstream | In the deprecating release, Core FieldLabel's info icon moves from `touchTrigger="tap"` to `component:InfoTip` with `triggerBehavior="toggle"` (`component:FieldLabel` FR9), and Lab InfoTip and the CLI page templates migrate too, the templates to a button trigger with `triggerBehavior="toggle"` so they carry no development warning (`spec:AST-017` FR29c); docs, stories, templates, and examples teach only `triggerBehavior` |
+| transition | no prior transition |
+| state | `proposed` |
+| target plan | `CLN-0024` in the next minor release |
+
+### CLN-0024 — Remove `touchTrigger`
+
+| Field | Value |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id | `CLN-0024` |
+| lifecycle | `DEP-0016` |
+| delta | `touchTrigger` is removed from `Tooltip`, `HoverCard`, `useTooltip`, and `useHoverCard`; `touchTrigger` remains supported until the next minor; only `"tap"` is deprecated now (DEP-0016). `triggerBehavior` alone then decides what a tap does, with `adaptive`, `hover`, and `toggle`, default `adaptive`: `adaptive` keeps the released `touchTrigger="auto"` (a tap opens the layer unless the trigger performs its own action, and no press pins it), `hover` keeps the released `touchTrigger="none"` (no touch or pen tap opens the layer, and no press pins it), and `toggle` is unchanged and replaces `touchTrigger="tap"`. `adaptive` gains FR5's walk: a tap that already acts on a control around the trigger does not open the layer. A hint-only trigger inside a control migrates by declaring `triggerBehavior="toggle"`, which no codemod can decide; Astryx's own info-only triggers (InfoTip, FieldLabel's info button, and a standalone StatusDot) declare it before this minor; a StatusDot inside a button, link, menu item, or option stays an image whose status the host's accessible name carries. One prop decides what a press does |
+| replacement | `touchTrigger="none"` becomes `triggerBehavior="hover"`, under which no touch or pen tap opens the layer, and `touchTrigger="auto"` becomes the default `triggerBehavior="adaptive"`. Each remaining `touchTrigger="tap"` site has a named replacement (`spec:AST-017` FR8): a button or link whose only job is its tooltip takes `triggerBehavior="toggle"`, so its tooltip keeps a touch path; a button or link with its own action whose accessible name already carries the layer's text drops `tap` and keeps the default `adaptive`, so a tap performs the action and opens no layer (`architecture:interaction-modality` INV4's case); any other button or link with its own action moves the layer's information to an adjacent info trigger that declares `triggerBehavior="toggle"`, such as an InfoTip, or into its visible label, so that information keeps a touch path, and then drops `tap`; a trigger whose tooltip repeats its own text takes `triggerBehavior="toggle"` (FR9's own-text exception); an unknown element is reported for a manual choice (`architecture:interaction-modality` INV4) |
+| codemod | The minor's `astryx upgrade` codemod, with tests and fixtures: `touchTrigger="auto"` is removed, since the default `adaptive` reproduces it; `touchTrigger="none"` becomes `triggerBehavior="hover"`; an explicit `triggerBehavior="hover"` or `"toggle"` is kept and any `touchTrigger` beside it removed, and beside an explicit `triggerBehavior="adaptive"` the `touchTrigger` value maps as stated here and replaces it; a remaining `touchTrigger="tap"` becomes `triggerBehavior="toggle"` on an icon or span trigger and on an own-text trigger the codemod can identify; every button and link `tap` site is reported with the options in its note (`triggerBehavior="toggle"` when the trigger's only job is its layer; remove `tap` and keep the default `adaptive` when the trigger's accessible name already carries the layer's text; otherwise move the information to an adjacent InfoTip or the visible label, then remove `tap`), since no static check tells them apart, and every other remaining `tap` site is reported; spreads and dynamic values are reported |
+| rollback | Restore `touchTrigger` and the final-patch `triggerBehavior="adaptive"`, without FR5's walk, from the final-patch baseline |
+| state | `pending` — lands in a declared minor with its `[breaking]` Changeset |
Consumer migration instructions belong in consumer docs and release notes.
@@ -131,11 +133,12 @@ Consumer migration instructions belong in consumer docs and release notes.
`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. The walk ships with CLN-0024 (FR5, DEC-1).
-- **Press-to-pin is not built.** `pressTrigger`, its toggle (FR9), the trigger
- wiring and announcement (FR10), and a pinned tooltip's Escape priority
- (`spec:AST-003` FR4) are specified and not implemented, and the codemod
- DEP-0016 names does not exist yet. `touchTrigger="tap"` is the shipped way to
- open on every tap.
+- **Toggle pinning is not built.** `triggerBehavior` and its three values, the
+ toggle (FR9), the trigger wiring and announcement (FR10), and a pinned
+ tooltip's Escape priority (`spec:AST-003` FR4) are specified and not
+ implemented, and the codemod DEP-0016 names does not exist yet.
+ `touchTrigger="tap"` is the shipped way to open on every tap, and
+ `touchTrigger="none"` the shipped way to open on no tap.
- **The tooltip consumes Escape until AST-003 ships.** A visible, topmost
tooltip handles Escape, as `family:overlay-dismissal` records, so the layer
underneath it, such as a Dialog, stays open for that press. `spec:AST-003`
@@ -195,27 +198,27 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------- | ------------------- | ------------------------------------------------------------------------- | -------------------------------- |
-| Focus trigger | `auto`, `always`, `never` | Whether keyboard focus opens the tooltip: on focusable triggers (FR4's gap), always, or never. | Every trigger mode. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
-| Press trigger | `none`, `toggle` | Whether a click, tap, Enter, or Space on the trigger pins the tooltip open: never, leaving taps to `touchTrigger`, or on every press (FR9). | Button triggers; a non-button trigger keeps tap-only opening (FR9). | `none` | `component:Tooltip` | Stable | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; or never. Ignored under `pressTrigger="toggle"`. | Touch and pen without hover. | `auto` | `component:Tooltip` | Stable; `tap` deprecated (DEP-0016); folds into `pressTrigger` (CLN-0024) | TypeScript rejects other values. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------- | ------------------------------------------------------------------------- | -------------------------------- |
+| Focus trigger | `auto`, `always`, `never` | Whether keyboard focus opens the tooltip: on focusable triggers (FR4's gap), always, or never. | Every trigger mode. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Trigger behavior | `adaptive`, `hover`, `toggle` | How the trigger opens the tooltip; under every value, hover on a fine pointer and keyboard focus preview it (FR3, FR4). Under `adaptive`, a tap opens it unless the tap already acts (FR5, DEC-1), and no press pins it; under `hover`, no touch or pen tap opens it, and no press pins it; under `toggle`, a click, a completed tap, Enter, or Space pins it, and the same press on a pinned tooltip closes it (FR9). | Every trigger; `toggle` pins only on a button or own-text trigger, and any other trigger keeps tap-only opening (FR9). | `adaptive` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Touch trigger | `auto`, `tap`, `none` | Whether a tap opens it under `triggerBehavior="adaptive"`: unless the tap already acts, as the innermost control around the tapped element decides (DEC-1); always; or never. Ignored under `triggerBehavior="hover"` and `"toggle"`. | Touch and pen without hover. | `auto` | `component:Tooltip` | Stable; `tap` deprecated (DEP-0016); removed at the next minor (CLN-0024) | TypeScript rejects other values. |
## 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` |
-| 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) |
+| 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 and pen, a completed tap opens per `triggerBehavior` 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 `adaptive`, 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). Until CLN-0024 removes `touchTrigger`, an explicit `touchTrigger` decides instead under `adaptive`: `tap` opens on every tap and `none` on no tap. Implementation gap: the walk ships with CLN-0024 in the next minor; until then `adaptive`, like the shipped `touchTrigger="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 `hover`, no tap opens it. Under `toggle`, FR9 decides what a tap does. `hover` and `toggle` ignore `touchTrigger`. | 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 `triggerBehavior="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 `triggerBehavior="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: every completed tap opens the tooltip, 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 `triggerBehavior="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 `triggerBehavior="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
@@ -254,7 +257,7 @@ Consumer migration instructions belong in consumer docs and release notes.
held-closed Escape gap as the exceptions to Escape dismissal. Hiding when focus leaves, showing on hover,
and hiding on leave go beyond the required parts `spec:AST-020` FR15 adopts
and are this record's named exception, kept because they ship.
-- **AR6 — A pinned tooltip is a toggletip.** Under `pressTrigger="toggle"` the
+- **AR6 — A pinned tooltip is a toggletip.** Under `triggerBehavior="toggle"` the
trigger is a named button that reports `aria-expanded` and `aria-controls`
(FR10), apart from FR9's trigger whose tooltip repeats its own text; keyboard and touch users pin and close the tooltip without hover
(FR9); it is announced once when it pins (FR10); and it persists until
@@ -292,17 +295,18 @@ 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` 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` |
+| 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` |
+| FR5, FR9 (`triggerBehavior`) | Evidence gap until built: a trigger-behavior suite in `Tooltip.test.tsx` and `useTooltip.test.tsx`, and a real-touch and pen case in `TouchTrigger.a11y.chromium.spec.ts` | `adaptive` by default and explicitly, `hover`, and `toggle`, each with mouse hover, keyboard focus, touch, and pen; `touchTrigger` beside each value | Under any value, a lost hover or keyboard-focus preview; under `adaptive`, an info-only tap that leaves the tooltip shut or a press that pins it; under `hover`, a touch or pen tap that opens it or a press that pins it; under `toggle`, a click, tap, Enter, or Space that does not pin or close it as FR9 states; or a `touchTrigger` that changes `hover` or `toggle`, 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"`; `triggerBehavior` 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:
@@ -325,19 +329,21 @@ Read from source, with no focused test yet:
### DEC-1 — A press pins the layer; a tap that already acts stays with its control
**Reference:** `component:Tooltip/DEC-1`
-**Decider:** `cixzhang`, `2026-10-31`
+**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01`
-A tooltip keeps previewing on hover and focus, and `pressTrigger="toggle"`
+A tooltip keeps previewing on hover and focus, and `triggerBehavior="toggle"`
adds one more open state of the same layer: a press pins it, so people on
touch, keyboard, or a screen reader can keep it open long enough to read it. A
pinned tooltip is a toggletip, so its trigger is a button that reports
-`aria-expanded`. Components declare `pressTrigger="toggle"` where the tooltip
+`aria-expanded`. Components declare `triggerBehavior="toggle"` where the tooltip
is the only home of their information, such as an info icon, a status dot, or
a timestamp.
-`touchTrigger="auto"`, the default until `touchTrigger` folds into
-`pressTrigger` at the next minor (CLN-0024), is the fallback. Under it, a tap
-that already acts does not open the layer, so one tap does one thing: a
+`triggerBehavior` names how the layer answers each device. `adaptive`, the
+default and the released behavior, previews on hover and keyboard focus and
+opens on a tap; `hover` previews on hover and keyboard focus only, so no touch or
+pen tap opens the layer; `toggle` adds the pin on every device. Under
+`adaptive`, a tap that already acts does not open the layer, so one tap does one thing: a
truncated label inside a link follows the link, while a truncated label in
running text opens its tooltip. Whether a tap acts is decided by walking out
from the tapped element: the innermost control on that path decides, whether a
@@ -347,8 +353,9 @@ 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).
+`touchTrigger="tap"` is deprecated in favor of `triggerBehavior="toggle"`
+(DEP-0016). `touchTrigger` is removed at the next minor, and the walk ships
+with that removal (CLN-0024).
`component:HoverCard` DEC-1 applies the same rules, and `component:InfoTip` is
the info-icon preset over the toggle.
@@ -357,6 +364,8 @@ HoverCard's previews (`architecture:public-component-api` INV21).
Rejected: judging the trigger alone, which lets one tap do two things.
+Rejected: a `touchTrigger` beside `triggerBehavior`, which splits one question across two props.
+
## Open questions
None.