Skip to content

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

TypeScript

fix(Tooltip): remove the unreleased triggerBehavior prop before 0.7.7 (#9711)

Cindy Zhang1821fb3faead
diff --git a/.changeset/promote-infotip-to-core.md b/.changeset/promote-infotip-to-core.md
index 528e7685bf..99ed440601 100644
--- a/.changeset/promote-infotip-to-core.md
+++ b/.changeset/promote-infotip-to-core.md
@@ -2,6 +2,6 @@
'@astryxdesign/core': patch
---
-[component] Promote `InfoTip` from Lab to Core, imported from `@astryxdesign/core/InfoTip` or the package root: an info-icon button whose press pins its help. Hover and keyboard 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, through Tooltip's `triggerBehavior="toggle"`. Its default name is the translated "More information", and under a coarse pointer it takes taps out toward 44 px without taking a neighbour's. The `@astryxdesign/lab` `InfoTip` export is now a deprecated re-export of the Core component and is removed in the next release: import it from `@astryxdesign/core` instead.
+[component] Promote `InfoTip` from Lab to Core, imported from `@astryxdesign/core/InfoTip` or the package root: an info-icon button whose press pins its help. Hover and keyboard 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. Its default name is the translated "More information", and under a coarse pointer it takes taps out toward 44 px without taking a neighbour's. The `@astryxdesign/lab` `InfoTip` export is now a deprecated re-export of the Core component and is removed in the next release: import it from `@astryxdesign/core` instead.
@vjeux
diff --git a/.changeset/trigger-behavior-toggle.md b/.changeset/trigger-behavior-toggle.md
deleted file mode 100644
index 6eef27cfbf..0000000000
--- a/.changeset/trigger-behavior-toggle.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-'@astryxdesign/core': patch
----
-
-[feat] Tooltip and `useTooltip` take `triggerBehavior` (type `TooltipTriggerBehavior`). `adaptive`, the default, keeps the released behavior. `hover` previews the tooltip on hover and focus, and no touch or pen tap opens it. `toggle` pins the tooltip on a click, tap, Enter, or Space on a button trigger, and the same press closes it. Escape, a press outside, or focus leaving also closes it. The press stops at the trigger: its default action is prevented, the trigger's own handlers still run, and a clickable row, card, or label around it does nothing. With `anchorRef` or a caller's own trigger, a plain `onClick` element around the trigger still receives the press, and so does an Item row when that trigger is not a native button. The trigger reports `aria-expanded` and `aria-controls`, and the tooltip's text is announced once when it pins. A trigger that is not a button gets a development warning. `touchTrigger` now decides taps only under `adaptive`.
-
-@vjeux
diff --git a/apps/storybook/stories/InfoTip.stories.tsx b/apps/storybook/stories/InfoTip.stories.tsx
index a3c72853b3..18fe06b97a 100644
--- a/apps/storybook/stories/InfoTip.stories.tsx
+++ b/apps/storybook/stories/InfoTip.stories.tsx
@@ -42,10 +42,9 @@ export const NextToALabel: Story = {
};
/**
- * Revealing the help is the button's only purpose, so `InfoTip` sets
- * `triggerBehavior="toggle"`: tap the icon on a phone (or with touch emulation
- * on), click it, or press Enter or Space and the help pins open; tap outside
- * and it dismisses.
+ * Revealing the help is the button's only purpose, so `InfoTip` pins it on a
+ * press: tap the icon on a phone (or with touch emulation on), click it, or
+ * press Enter or Space and the help pins open; tap outside and it dismisses.
*/
export const Touch: Story = {
render: () => (
diff --git a/apps/storybook/stories/TooltipToggleBehaviorA11y.stories.tsx b/apps/storybook/stories/TooltipToggleBehaviorA11y.stories.tsx
index aec56cd094..0d6331e354 100644
--- a/apps/storybook/stories/TooltipToggleBehaviorA11y.stories.tsx
+++ b/apps/storybook/stories/TooltipToggleBehaviorA11y.stories.tsx
@@ -2,39 +2,38 @@
/**
* @file TooltipToggleBehaviorA11y.stories.tsx
- * @input Uses Tooltip, Button, ClickableCard and Layout from core
- * @output Fixtures for the toggle-behavior browser tests. One is a button
- * whose only job is its tooltip, alone and inside a clickable card. One is
- * an anchored trigger with its own click handler, inside a clickable card.
- * One is a trigger whose tooltip opens on no focus. One story has a trigger
- * per `triggerBehavior` value.
- * @position The reproduction path for the `triggerBehavior="toggle"` cases in
+ * @input Uses InfoTip, Tooltip, ClickableCard and Layout from core
+ * @output Fixtures for the press-to-pin browser tests: an InfoTip alone and
+ * inside a clickable card, and one story with a plain Tooltip term beside
+ * an InfoTip.
+ * @position The reproduction path for the press-to-pin cases in
* `packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts`
- * (`component:Tooltip` FR9, FR10). Per `docs/specs/AST-009/spec.md` FR30, a
- * browser claim is checked against a checked-in story.
+ * (`component:Tooltip` FR9, FR10; InfoTip is Tooltip's press-to-pin
+ * trigger). Per `docs/specs/AST-009/spec.md` FR30, a browser claim is
+ * checked against a checked-in story.
*
* SYNC: The spec navigates to these story ids by name. Nothing at compile
* time catches a renamed export — the Chromium spec does, when it finds no
* story.
*/
-import {useRef, useState} from 'react';
+import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
-import {Button} from '@astryxdesign/core/Button';
import {ClickableCard} from '@astryxdesign/core/ClickableCard';
+import {InfoTip} from '@astryxdesign/core/InfoTip';
import {VStack} from '@astryxdesign/core/Layout';
import {Tooltip} from '@astryxdesign/core/Tooltip';
const meta: Meta = {
title: 'a11y/Tooltip toggle behavior',
- // Driven by the toggle-behavior spec, not photographed: the states under test
+ // Driven by the press-to-pin spec, not photographed: the states under test
// are pins and closes across presses, which no single frame shows.
tags: ['no-visual'],
parameters: {
docs: {
description: {
component:
- 'A button whose only job is its tooltip takes `triggerBehavior="toggle"`: a click, a tap, Enter, or Space pins the tooltip, and the same press closes it. Inside a clickable card, the press stops at the trigger.',
+ 'InfoTip pins its help on a press: a click, a tap, Enter, or Space pins it, and the same press closes it. Inside a clickable card, the press stops at the InfoTip.',
},
},
},
@@ -44,18 +43,13 @@ export default meta;
type Story = StoryObj;
-/** A press pins the tooltip open; the same press, Escape, or a press outside closes it. */
+const HELP = 'Rows are ranked by how many places import the icon';
+
+/** A press pins the help open; the same press, Escape, or a press outside closes it. */
export const ButtonToggle: Story = {
render: () => (
<div style={{padding: 100}}>
- <Tooltip
- content="Rows are ranked by how many places import the icon"
- placement="above"
- triggerBehavior="toggle">
- <Button label="What is this?" variant="secondary">
- ?
- </Button>
- </Tooltip>
+ <InfoTip content={HELP} label="What is this?" />
</div>
),
};
@@ -68,14 +62,7 @@ function InAClickableCardRender() {
<ClickableCard label="Icon usage" onClick={() => setOpened(n => n + 1)}>
<VStack gap={2}>
Icon usage
- <Tooltip
- content="Rows are ranked by how many places import the icon"
- placement="above"
- triggerBehavior="toggle">
- <Button label="What is this?" variant="secondary">
- ?
- </Button>
- </Tooltip>
+ <InfoTip content={HELP} label="What is this?" />
</VStack>
</ClickableCard>
<span>Card opened {opened} times</span>
@@ -84,98 +71,20 @@ function InAClickableCardRender() {
);
}
-/** A press on the trigger pins its tooltip and stops there: the card does not open. */
+/** A press on the InfoTip pins its help and stops there: the card does not open. */
export const InAClickableCard: Story = {
render: () => <InAClickableCardRender />,
};
-function AnchoredActionInACardRender() {
- const [opened, setOpened] = useState(0);
- const [pressed, setPressed] = useState(0);
- const anchorRef = useRef<HTMLButtonElement>(null);
- return (
- <div style={{padding: 100, maxWidth: 360}}>
- <VStack gap={2}>
- <ClickableCard label="Icon usage" onClick={() => setOpened(n => n + 1)}>
- <VStack gap={2}>
- Icon usage
- <Button
- ref={anchorRef}
- label="What is this?"
- variant="secondary"
- onClick={() => setPressed(n => n + 1)}>
- ?
- </Button>
- <Tooltip
- anchorRef={anchorRef}
- content="Rows are ranked by how many places import the icon"
- placement="above"
- triggerBehavior="toggle"
- />
- </VStack>
- </ClickableCard>
- <span>Card opened {opened} times</span>
- <span>Button pressed {pressed} times</span>
- </VStack>
- </div>
- );
-}
-
-/**
- * An anchored trigger with its own click handler, in a clickable card: the
- * pinning press runs the trigger's own handler, and the card ignores it.
- */
-export const AnchoredActionInACard: Story = {
- render: () => <AnchoredActionInACardRender />,
-};
-
-/** A tooltip that opens on no focus: focus moving to another control still closes a pin. */
-export const FocusTriggerNever: Story = {
- render: () => (
- <div style={{padding: 100}}>
- <VStack gap={2}>
- <Tooltip
- content="Rows are ranked by how many places import the icon"
- placement="above"
- triggerBehavior="toggle"
- focusTrigger="never">
- <Button label="What is this?" variant="secondary">
- ?
- </Button>
- </Tooltip>
- <Button label="Next" variant="secondary">
- Next
- </Button>
- </VStack>
- </div>
- ),
-};
-
-/** One info-only trigger per `triggerBehavior` value: a tap opens, never opens, or pins. */
+/** A plain Tooltip term, which a tap opens, beside an InfoTip, which a press pins. */
export const TriggerBehaviors: Story = {
render: () => (
<div style={{padding: 100}}>
<VStack gap={4}>
- <Tooltip
- content="Adaptive: a tap opens it"
- triggerBehavior="adaptive"
- delay={0}>
+ <Tooltip content="Adaptive: a tap opens it" delay={0}>
<span tabIndex={0}>Adaptive term</span>
</Tooltip>
- <Tooltip
- content="Hover: touch never opens it"
- triggerBehavior="hover"
- delay={0}>
- <span tabIndex={0}>Hover term</span>
- </Tooltip>
- <Tooltip
- content="Toggle: a press pins it"
- triggerBehavior="toggle"
- delay={0}>
- <Button label="Toggle term" variant="secondary">
- ?
- </Button>
- </Tooltip>
+ <InfoTip content="Toggle: a press pins it" label="Toggle term" />
</VStack>
</div>
),
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.md
index 4909fc57cf..7126c82066 100644
--- a/docs/architecture/interaction-modality.md
+++ b/docs/architecture/interaction-modality.md
@@ -159,8 +159,9 @@ work.
belongs in a HoverCard or Popover. A tooltip that labels an action trigger
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 `triggerBehavior="toggle"` (`component:Tooltip` DEC-1).
+ the tooltip; a hint-only trigger that performs no action opens its tooltip
+ on a tap under the default `touchTrigger="auto"`, and help behind an info
+ icon pins through `component:InfoTip` (`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 +332,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 `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 |
+| 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 under `touchTrigger="auto"` | 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/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index e74867486a..9f3991a42f 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -118,9 +118,7 @@ guidance owns the process used to propose and test APIs.
`component:DropdownMenuSubMenu`); a new behavior prop defaults to the shipped
behavior, which is the adaptive value when the shipped behavior already
differs by device, and an existing prop's default moves only under INV16 and
- INV9.
- Tooltip and HoverCard `triggerBehavior` (`'adaptive'`, `'hover'`, `'toggle'`)
- follow this. An `is…` or `has…` boolean names only a true on/off that has no
+ INV9. An `is…` or `has…` boolean names only a true on/off that has no
third state, and `presentation` names which surface appears and, under INV16,
the input mode of an open surface.
- **INV4 — New props express caller-owned intent.** New public props follow
diff --git a/docs/families/overlay-dismissal.md b/docs/families/overlay-dismissal.md
index 65addd6bb0..e801060562 100644
--- a/docs/families/overlay-dismissal.md
+++ b/docs/families/overlay-dismissal.md
@@ -205,7 +205,7 @@ this record's current membership snapshot must be updated with it.
and FR3 apply within that document, so a host and the members nested in it
keep one order wherever they render. A member of another document is never a
candidate. An unpinned Tooltip never wins or blocks an Escape press against
- another member, and a Tooltip or HoverCard pinned open by a press takes Escape
+ another member, and a Tooltip pinned open by a press takes Escape
first (`spec:AST-003` FR4, DEC-6): Escape closes an unpinned Tooltip only when
it is the only present member in its document. The stack listens once in each document that holds a
member and stops when its last member leaves.
@@ -241,35 +241,35 @@ this record's current membership snapshot must be updated with it.
## Representative matrix
-| Member and state | Shared invariant | Deliberate variation |
-| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Dialog inside Dialog | Inner dialog handles the first request | Dialog supplies native modality and focus behavior |
-| Popover inside Dialog | Popover handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
-| Registered descendant inside CommandPalette | Descendant handles the first Escape | CommandPalette inherits Dialog's shared stack participation |
-| Tooltip or HoverCard inside Dialog, in page | An open HoverCard handles the first Escape; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | Hover families decide when they are present and how controlled state responds |
-| Lightbox or MobileNav above a required Dialog | Top member handles the request | Required Dialog uses `block` only when it is topmost |
-| Required Dialog alone | Request is consumed without closing | Dialog purpose selects `block` behavior |
-| Self-owned input popup | Popup participates while present | Input owns selection, focus, open state, positioning, and outside dismissal |
-| Two unrelated registered surfaces | Later active-cycle registration is topmost | Neither surface is treated as nested |
-| Platform close request sent to a lower Dialog | Lower Dialog stays open | The platform targets a host; the shared check decides whether it may close |
-| Popover in an iframe, Dialog in the page | Request goes to its own document's top member | The app renders into the second document through a portal |
-| Popover inside Dialog in an iframe | Popover handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
-| Tooltip or HoverCard inside Dialog, in iframe | An open HoverCard handles the first Escape there; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | An unpinned Tooltip never wins or blocks Escape against another member; a pinned Tooltip or HoverCard takes it first (`spec:AST-003` FR4, DEC-6) |
-| ContextMenu in a Picture-in-Picture window | Escape closes it; focus returns to its opener there | The menu opens where the person pressed (FR8, FR9) |
-| BottomSheet or Lightbox in a Picture-in-Picture window | Escape closes it; focus returns to its return target there | The surface covers that window (FR8, FR9) |
-| BottomSheet or Lightbox in an embedded iframe | Not supported | A surface that covers its window works only where the window is the app (FR8) |
-| Drawer or MobileNav | Page only | Page-level surfaces stay in the page's document (FR8) |
+| Member and state | Shared invariant | Deliberate variation |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Dialog inside Dialog | Inner dialog handles the first request | Dialog supplies native modality and focus behavior |
+| Popover inside Dialog | Popover handles the first Escape | Popover supplies anchoring, portal placement, and focus policy |
+| Registered descendant inside CommandPalette | Descendant handles the first Escape | CommandPalette inherits Dialog's shared stack participation |
+| Tooltip or HoverCard inside Dialog, in page | An open HoverCard handles the first Escape; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | Hover families decide when they are present and how controlled state responds |
+| Lightbox or MobileNav above a required Dialog | Top member handles the request | Required Dialog uses `block` only when it is topmost |
+| Required Dialog alone | Request is consumed without closing | Dialog purpose selects `block` behavior |
+| Self-owned input popup | Popup participates while present | Input owns selection, focus, open state, positioning, and outside dismissal |
+| Two unrelated registered surfaces | Later active-cycle registration is topmost | Neither surface is treated as nested |
+| Platform close request sent to a lower Dialog | Lower Dialog stays open | The platform targets a host; the shared check decides whether it may close |
+| Popover in an iframe, Dialog in the page | Request goes to its own document's top member | The app renders into the second document through a portal |
+| Popover inside Dialog in an iframe | Popover handles the iframe's first request | Both register their own elements, so they rank in the iframe's order |
+| Tooltip or HoverCard inside Dialog, in iframe | An open HoverCard handles the first Escape there; over an unpinned Tooltip, the Dialog takes it; a pinned Tooltip takes it first | An unpinned Tooltip never wins or blocks Escape against another member; a pinned Tooltip takes it first (`spec:AST-003` FR4, DEC-6) |
+| ContextMenu in a Picture-in-Picture window | Escape closes it; focus returns to its opener there | The menu opens where the person pressed (FR8, FR9) |
+| BottomSheet or Lightbox in a Picture-in-Picture window | Escape closes it; focus returns to its return target there | The surface covers that window (FR8, FR9) |
+| BottomSheet or Lightbox in an embedded iframe | Not supported | A surface that covers its window works only where the window is the app (FR8) |
+| Drawer or MobileNav | Page only | Page-level surfaces stay in the page's document (FR8) |
## Adoption and exceptions
-| Components or surface | Adoption | Current deviation or limitation |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Dialog, AlertDialog, Popover, MobileNav, Drawer, CommandPalette | shared owner; CommandPalette composes Dialog | none |
-| Tooltip, HoverCard | shared owner with DOM presence reporting | Neither provides nesting depth to descendant layers. Implementation gap: a Tooltip consumes Escape when it is the topmost layer, so the layer beneath it stays open for that press, and a Tooltip in another document is never closed by Escape (`component:Tooltip` FR6); FR8 gives that press to the layer beneath and closes a lone Tooltip in its own document. A Tooltip or HoverCard pinned open by a press takes Escape first (`spec:AST-003` FR4, DEC-6); implementation gap: the pin is not built (`component:Tooltip` FR9, `component:HoverCard` FR9). HoverCard reads its presence from the page's document, so in another document it takes no request (FR8) and returns no focus there (FR9) |
-| Focus traps with `onEscape` | shared owner through `useFocusTrap` | They provide DOM containment, not descendant depth |
-| BreadcrumbItem, ChatComposerInput, ComplexSelector, DateInput, DateRangeInput, DateTimeInput, Selector, MultiSelector, PowerSearch, BaseTypeahead, Typeahead, Tokenizer, SideNavHeading, SideNavItem, TabMenu, TopNavHeading, TopNavMenu, TopNavMegaMenu, Table, Lab TourStep, Lab ChatEmojiPicker | shared owner through `usePopover` or a composed Popover owner | Table filtering owns controlled Popover state and discards its draft on close; TourStep routes Popover close to the Tour; ChatEmojiPicker owns controlled Popover state |
-| DropdownMenu root, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, BottomSheet, BottomSheetSwitcher, Lightbox | shared owner | Implementation gap: in another document (for BottomSheet, BottomSheetSwitcher and Lightbox, a Picture-in-Picture window), each decides focus return from the page's document and last input, so focus returns to the frame element or the page, or without the ring the last input in its document calls for (FR9) |
-| DropdownMenuSubMenu, PowerSearchEditPopover | local only | Must migrate from component-specific listeners or registries to the shared owner |
+| Components or surface | Adoption | Current deviation or limitation |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dialog, AlertDialog, Popover, MobileNav, Drawer, CommandPalette | shared owner; CommandPalette composes Dialog | none |
+| Tooltip, HoverCard | shared owner with DOM presence reporting | Neither provides nesting depth to descendant layers. Implementation gap: a Tooltip consumes Escape when it is the topmost layer, so the layer beneath it stays open for that press, and a Tooltip in another document is never closed by Escape (`component:Tooltip` FR6); FR8 gives that press to the layer beneath and closes a lone Tooltip in its own document. A Tooltip pinned open by a press takes Escape first (`spec:AST-003` FR4, DEC-6; `component:Tooltip` FR9); a HoverCard has no press pin. HoverCard reads its presence from the page's document, so in another document it takes no request (FR8) and returns no focus there (FR9) |
+| Focus traps with `onEscape` | shared owner through `useFocusTrap` | They provide DOM containment, not descendant depth |
+| BreadcrumbItem, ChatComposerInput, ComplexSelector, DateInput, DateRangeInput, DateTimeInput, Selector, MultiSelector, PowerSearch, BaseTypeahead, Typeahead, Tokenizer, SideNavHeading, SideNavItem, TabMenu, TopNavHeading, TopNavMenu, TopNavMegaMenu, Table, Lab TourStep, Lab ChatEmojiPicker | shared owner through `usePopover` or a composed Popover owner | Table filtering owns controlled Popover state and discards its draft on close; TourStep routes Popover close to the Tour; ChatEmojiPicker owns controlled Popover state |
+| DropdownMenu root, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, BottomSheet, BottomSheetSwitcher, Lightbox | shared owner | Implementation gap: in another document (for BottomSheet, BottomSheetSwitcher and Lightbox, a Picture-in-Picture window), each decides focus return from the page's document and last input, so focus returns to the frame element or the page, or without the ring the last input in its document calls for (FR9) |
+| DropdownMenuSubMenu, PowerSearchEditPopover | local only | Must migrate from component-specific listeners or registries to the shared owner |
The rows marked partial or local are current adoption gaps against FR1, and the
rows naming an implementation gap are gaps against FR8 or FR9. They are not
@@ -280,19 +280,19 @@ modality, positioning, outside-dismissal, and open-state contracts.
## Verification map
-| Contract | Verification | Representative members and states | Mutation or failure expectation |
-| ------------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR2, FR4, FR5 | `useLayerDismissal.test.tsx`; `BottomSheetSwitcher.test.tsx`; `ContextMenu.test.tsx`; `CommandPalette.test.tsx` | synthetic provider depth, same-DOM containment, non-modal switcher nesting, ContextMenu nested layers, CommandPalette descendant nesting, unrelated, blocking, content-handled, present/absent | Removing depth, presence filtering, or event deferral sends Escape to the wrong surface |
-| FR2, FR3, FR4, FR6 | `layerDismissalInvariants.test.tsx` | nested same-DOM Dialogs, Lightbox over Dialog, Dialog in BottomSheet, platform cancel, IME | One request closes two surfaces, closes a host before its child, or dismisses during composition |
-| FR1, FR2, FR3, FR7 | `layerDismissalFamilies.test.tsx` | Dialog, Lightbox, MobileNav, BottomSheet, Tooltip, HoverCard; controlled and blocking states | A family bypasses the stack, a lower member handles a request, or controlled ownership is ignored |
-| FR1 | `useFocusTrap.test.tsx` | active, nested, and deactivated traps with `onEscape` | A dismissible trap stays off the shared stack or nested traps respond together |
-| FR8 | `useLayerDismissal.test.tsx`; `Popover.test.tsx` | members in the page and a same-origin iframe; a Popover alone and inside a Dialog, in an iframe | A press in one document dismisses a member of another, or a host closes over its nested layer |
-| FR8 | `PopoverSecondDocument.a11y.chromium.spec.ts` | a Popover in an iframe and in a Picture-in-Picture window, alone and with one open in the page | A press in the second document misses its own layer or dismisses the page's |
-| FR9 | `DialogSecondDocument.a11y.browser.spec.ts` | a Dialog in an iframe and in a Picture-in-Picture window, closed by Escape or a control inside it, and a Dialog in an iframe opened from the page | Focus lands outside the opener's document, or its ring does not follow the closing input |
-| FR8, FR9 | Real-browser second-document checks; implementation gap: only Dialog and Popover have them | Dialog, Popover, DropdownMenu, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, Tooltip and HoverCard, each in a same-origin iframe and in a Picture-in-Picture window: opens and takes Escape in the document it renders in (an unpinned Tooltip only when no other member is present; a pinned Tooltip or HoverCard before the member beneath it), and returns focus in the opener's document | The member opens or ranks in another document, a pinned Tooltip lets Escape reach the member beneath it, or focus lands on the frame element, the page, or the body |
-| FR8, FR9 | Real-browser second-document checks; implementation gap: none has them | BottomSheet, BottomSheetSwitcher, and Lightbox in a Picture-in-Picture window: opens, takes Escape, and returns focus to its return target there | The surface ranks in the page, or focus lands on the page or the body |
-| FR8 | Source check over Drawer and MobileNav | Drawer and MobileNav rendered from a control in a second document | A page-level surface moves into the second document |
-| FR10 | `useBackdropPress.test.tsx`; `BackdropPress.a11y.chromium.spec.ts` | Dialog (`purpose="info"`), Drawer scrim, and CommandPalette, with a mouse and a finger: a press that starts and ends on the backdrop, one that starts inside and ends on it, one that starts on it and ends inside, a cancelled pointer, and a backdrop start followed by a press inside | A press that crosses the edge either way dismisses, a cancelled or earlier press carries over, or a press on the backdrop alone does not dismiss |
+| Contract | Verification | Representative members and states | Mutation or failure expectation |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR2, FR4, FR5 | `useLayerDismissal.test.tsx`; `BottomSheetSwitcher.test.tsx`; `ContextMenu.test.tsx`; `CommandPalette.test.tsx` | synthetic provider depth, same-DOM containment, non-modal switcher nesting, ContextMenu nested layers, CommandPalette descendant nesting, unrelated, blocking, content-handled, present/absent | Removing depth, presence filtering, or event deferral sends Escape to the wrong surface |
+| FR2, FR3, FR4, FR6 | `layerDismissalInvariants.test.tsx` | nested same-DOM Dialogs, Lightbox over Dialog, Dialog in BottomSheet, platform cancel, IME | One request closes two surfaces, closes a host before its child, or dismisses during composition |
+| FR1, FR2, FR3, FR7 | `layerDismissalFamilies.test.tsx` | Dialog, Lightbox, MobileNav, BottomSheet, Tooltip, HoverCard; controlled and blocking states | A family bypasses the stack, a lower member handles a request, or controlled ownership is ignored |
+| FR1 | `useFocusTrap.test.tsx` | active, nested, and deactivated traps with `onEscape` | A dismissible trap stays off the shared stack or nested traps respond together |
+| FR8 | `useLayerDismissal.test.tsx`; `Popover.test.tsx` | members in the page and a same-origin iframe; a Popover alone and inside a Dialog, in an iframe | A press in one document dismisses a member of another, or a host closes over its nested layer |
+| FR8 | `PopoverSecondDocument.a11y.chromium.spec.ts` | a Popover in an iframe and in a Picture-in-Picture window, alone and with one open in the page | A press in the second document misses its own layer or dismisses the page's |
+| FR9 | `DialogSecondDocument.a11y.browser.spec.ts` | a Dialog in an iframe and in a Picture-in-Picture window, closed by Escape or a control inside it, and a Dialog in an iframe opened from the page | Focus lands outside the opener's document, or its ring does not follow the closing input |
+| FR8, FR9 | Real-browser second-document checks; implementation gap: only Dialog and Popover have them | Dialog, Popover, DropdownMenu, MoreMenu, ContextMenu, Selector, MultiSelector, TopNavHeading, TopNavMenu, TopNavMegaMenu, SideNavHeading, SideNavItem, Tooltip and HoverCard, each in a same-origin iframe and in a Picture-in-Picture window: opens and takes Escape in the document it renders in (an unpinned Tooltip only when no other member is present; a pinned Tooltip before the member beneath it), and returns focus in the opener's document | The member opens or ranks in another document, a pinned Tooltip lets Escape reach the member beneath it, or focus lands on the frame element, the page, or the body |
+| FR8, FR9 | Real-browser second-document checks; implementation gap: none has them | BottomSheet, BottomSheetSwitcher, and Lightbox in a Picture-in-Picture window: opens, takes Escape, and returns focus to its return target there | The surface ranks in the page, or focus lands on the page or the body |
+| FR8 | Source check over Drawer and MobileNav | Drawer and MobileNav rendered from a control in a second document | A page-level surface moves into the second document |
+| FR10 | `useBackdropPress.test.tsx`; `BackdropPress.a11y.chromium.spec.ts` | Dialog (`purpose="info"`), Drawer scrim, and CommandPalette, with a mouse and a finger: a press that starts and ends on the backdrop, one that starts inside and ends on it, one that starts on it and ends inside, a cancelled pointer, and a backdrop start followed by a press inside | A press that crosses the edge either way dismisses, a cancelled or earlier press carries over, or a press on the backdrop alone does not dismiss |
## Decision links
diff --git a/docs/specs/AST-003/spec.md b/docs/specs/AST-003/spec.md
index 982b01e6ae..53b9ef8074 100644
--- a/docs/specs/AST-003/spec.md
+++ b/docs/specs/AST-003/spec.md
@@ -71,10 +71,10 @@ browsers receive a usable reduced fallback, not equivalent behavior.
Escape/platform case.
- **FR4 — Passive dependents never shield owners.** An unpinned Tooltip is
passive. It does not win or block dismissal and disappears as a consequence
- when its associated owner or trigger interaction closes. A Tooltip or
- HoverCard that a press pinned open (`component:Tooltip` FR9,
- `component:HoverCard` FR9) is an active owner: it takes Escape first and
- closes, and the owner beneath it stays open for that press (DEC-6).
+ when its associated owner or trigger interaction closes. A Tooltip that a
+ press pinned open (`component:Tooltip` FR9) is an active owner: it takes
+ Escape first and closes, and the owner beneath it stays open for that press
+ (DEC-6).
- **FR5 — Associations are explicit.** Every active or blocking owner records an
optional parent owner and an interaction-branch root. A passive dependent
records its associated owner or trigger without creating an owner node or
@@ -190,8 +190,6 @@ Current `main` does not satisfy this spec completely:
- the stack has `close` and `block` but no passive role; Tooltip currently
consumes Escape ahead of associated owners;
-- no Tooltip or HoverCard pins open on a press yet (`component:Tooltip` FR9,
- `component:HoverCard` FR9);
- no shared owner/branch association graph or outside-branch resolver exists;
- DropdownMenuSubMenu has a local parent-close chain, but outside channels do not
consume shared branch identity;
@@ -238,22 +236,22 @@ Interaction modality continues to follow `architecture:interaction-modality`.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| FR1–FR6 | Pure registry/resolver tests plus family interaction tests | active, blocking, passive Tooltip, pinned Tooltip and HoverCard over a Dialog, visual-only, controlled owner | Passive surface wins, a pinned surface lets Escape reach the owner beneath, blocker leaks, or wrong owner closes |
-| FR7–FR10 | Branch resolver tests and real-browser outside interaction | root menu with two submenu levels; parent + child Popover; associated trigger | Outside root leaves submenu open, or child-only outside closes parent |
-| FR11–FR14 | Gesture-counter and browser event-order tests | native light dismiss before/after click; menu button; hover-open; touch; backdrop; swipe | Same gesture reopens any associated trigger or exposed hover reopens panel |
-| FR15–FR20 | Chromium/WebKit native host tests | Toast at root; Toast through one/two modals; CommandPalette above modal; ordinary local Popover | Global surface is behind/inert, loses state, or ordinary overlay becomes global |
-| FR21–FR23 | Supported/unsupported browser matrix and public-doc checks | anchor/fixed/custom; auto/manual; explicit controls; absent feature APIs | Docs promise equivalence or reduced fallback is unusable |
-| IR1–IR3 | API/type tests and mutation tests for resolvers/claims | one-at-a-time channel versus branch channel | One topmost query is reused for outside branches or timestamps replace identity |
-| IR4, IR5 | Public-surface snapshot and atomic change review | local Popover, global Toast, global CommandPalette | Generic global prop appears or unrelated behaviors are coupled in one change |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| --------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| FR1–FR6 | Pure registry/resolver tests plus family interaction tests | active, blocking, passive Tooltip, pinned Tooltip over a Dialog, visual-only, controlled owner | Passive surface wins, a pinned surface lets Escape reach the owner beneath, blocker leaks, or wrong owner closes |
+| FR7–FR10 | Branch resolver tests and real-browser outside interaction | root menu with two submenu levels; parent + child Popover; associated trigger | Outside root leaves submenu open, or child-only outside closes parent |
+| FR11–FR14 | Gesture-counter and browser event-order tests | native light dismiss before/after click; menu button; hover-open; touch; backdrop; swipe | Same gesture reopens any associated trigger or exposed hover reopens panel |
+| FR15–FR20 | Chromium/WebKit native host tests | Toast at root; Toast through one/two modals; CommandPalette above modal; ordinary local Popover | Global surface is behind/inert, loses state, or ordinary overlay becomes global |
+| FR21–FR23 | Supported/unsupported browser matrix and public-doc checks | anchor/fixed/custom; auto/manual; explicit controls; absent feature APIs | Docs promise equivalence or reduced fallback is unusable |
+| IR1–IR3 | API/type tests and mutation tests for resolvers/claims | one-at-a-time channel versus branch channel | One topmost query is reused for outside branches or timestamps replace identity |
+| IR4, IR5 | Public-surface snapshot and atomic change review | local Popover, global Toast, global CommandPalette | Generic global prop appears or unrelated behaviors are coupled in one change |
### Completion criteria
This spec is complete only when:
- an unpinned Tooltip is passive in Escape/platform and outside-branch
- coordination, and a pinned Tooltip or HoverCard takes Escape first;
+ coordination, and a pinned Tooltip takes Escape first;
- eligible-owner and associated-branch operations are shared and adopted by all
members named by `family:overlay-dismissal` for their relevant channels;
- outside a dropdown/menu root closes its entire open submenu cascade, while
@@ -341,7 +339,7 @@ implement the missing browser systems.
**Reference:** `spec:AST-003/DEC-6`
**Decider:** `cixzhang`, `2026-10-31`
-A Tooltip or HoverCard that a press pinned open is something the person asked
+A Tooltip that a press pinned open is something the person asked
to keep, so it is an active owner and Escape closes it before the owner beneath
it. A Tooltip that only previews on hover or focus stays passive.
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
index e6f4849ca1..101e30a87b 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 `triggerBehavior`), and a
+ what a tooltip does where there is no hover (Tooltip `touchTrigger`), 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/AST-090-exit-motion/spec.md b/docs/specs/AST-090-exit-motion/spec.md
index 613aa362ba..9524f83894 100644
--- a/docs/specs/AST-090-exit-motion/spec.md
+++ b/docs/specs/AST-090-exit-motion/spec.md
@@ -126,14 +126,14 @@ governs them in a touch presentation.
Toasts that a leaving dialog hosts are not its content (FR13).
- **FR5 — A leaving surface keeps its dismissal role, apart from a closing
pinned layer.** Until it is hidden, a leaving surface keeps the dismissal role
- it had while open (`spec:AST-003` FR1), except a closing pinned `Tooltip` or
- `HoverCard`, below. A leaving active or blocking owner stays present on the shared
+ it had while open (`spec:AST-003` FR1), except a closing pinned `Tooltip`,
+ below. A leaving active or blocking owner stays present on the shared
dismissal stack (`family:overlay-dismissal` FR2), so an Escape press or
platform close request during its exit does not reach an owner beneath it,
- except a closing pinned `Tooltip` or `HoverCard`, which leaves the stack when
- its exit starts. A
+ except a closing pinned `Tooltip`, which leaves the stack when its exit
+ starts. A
leaving passive dependent, such as an unpinned `Tooltip`, stays passive and
- shields nothing (`spec:AST-003` FR4). A pinned `Tooltip` or `HoverCard` that
+ shields nothing (`spec:AST-003` FR4). A pinned `Tooltip` that
is closing plays its exit and stops taking Escape once the exit starts: it is
no longer the stack's owner, so the member beneath it takes the next Escape
(`spec:AST-003` FR4, DEC-6).
@@ -206,7 +206,7 @@ governs them in a touch presentation.
shared exit copy (INV14), drawn in the top layer where the layer was. Native
close reconciliation stays single-fired (INV6). A leaving active or blocking
owner keeps its place on the dismissal stack until its exit ends, except a
- closing pinned Tooltip or HoverCard, which leaves it when its exit starts
+ closing pinned Tooltip, which leaves it when its exit starts
(FR5). A
leaving Dialog keeps supplying its modal outlet until it is hidden (FR13);
BottomSheet's outlet behavior does not change.
@@ -214,12 +214,12 @@ governs them in a touch presentation.
is the one transient exit copy INV7 allows, made by the shared mechanism and
removed when the exit ends (FR9).
- `family:overlay-dismissal`: no claim changes. A leaving member stays present
- for FR2 until it is hidden, except a closing pinned Tooltip or HoverCard,
+ for FR2 until it is hidden, except a closing pinned Tooltip,
which leaves the stack when its exit starts (FR5), and animation stays
member-owned (AV6).
- `spec:AST-003`: no claim changes. A leaving surface keeps its interaction role
(FR1), a leaving passive dependent such as an unpinned `Tooltip` still never
- shields an owner (FR4, DEC-1), and a closing pinned `Tooltip` or `HoverCard`
+ shields an owner (FR4, DEC-1), and a closing pinned `Tooltip`
gives up Escape when its exit starts (FR4, DEC-6). A leaving dialog is still the current native modal, so
it keeps its outlet and toasts stay operable above it (FR16, FR18).
- `spec:AST-094`: no claim changes. A touch presentation keeps the exit FR7 and
@@ -253,23 +253,23 @@ governs them in a touch presentation.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |
-| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |
-| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |
-| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |
-| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving unpinned Tooltip over a Dialog; Escape during the exit of a pinned Tooltip or HoverCard over a Dialog | The owner beneath a leaving owner closes, a leaving unpinned Tooltip absorbs the press, or a closing pinned Tooltip or HoverCard takes an Escape after its exit starts |
-| FR6 | Unit and real-browser focus and accessibility-tree tests | Dialog and layer closes, by keyboard and by pointer; the accessibility tree during a layer exit | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for the exit; a leaving layer's exit is in the accessibility tree |
-| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |
-| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |
-| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |
-| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |
-| FR11 | Real-browser frame sampling during an exit | A hover card, a menu with an open sub-menu, a selector with a search query | The leaving surface shows other content, or none, before it is hidden |
-| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |
-| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |
-| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |
-| Platform | Real-browser tests in Chromium and WebKit | A dialog exit and a layer exit with each kind on; a layer close where the Popover API is missing | A layer exit paints outside the top layer or does not play, or a close without the Popover API is delayed |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Component unit suites run unchanged with default tokens | Every dialog and layer member in a pointer presentation, opened and closed | A surface stays rendered after its close with default tokens |
+| FR2 | Real-browser test under a theme that sets one kind, fine primary pointer | Dialogs on with layers off; layers on with dialogs off; a nested `Theme` | The unset kind animates, or the set kind closes at once |
+| FR3 | Real-browser frame sampling during an exit | A dialog with and without an opener, a fullscreen dialog, a layer in each placement, right-to-left | The surface leaves its entrance path, or keeps the entrance curve |
+| FR4 | Real-browser test | A press and an Enter key on a control inside a leaving surface | The control activates |
+| FR5 | Dismissal invariant tests | Escape during a leaving Dialog or Popover with an owner beneath; Escape during a leaving unpinned Tooltip over a Dialog; Escape during the exit of a pinned Tooltip over a Dialog | The owner beneath a leaving owner closes, a leaving unpinned Tooltip absorbs the press, or a closing pinned Tooltip takes an Escape after its exit starts |
+| FR6 | Unit and real-browser focus and accessibility-tree tests | Dialog and layer closes, by keyboard and by pointer; the accessibility tree during a layer exit | Dialog focus returns before the dialog is hidden or lands on the body; layer focus waits for the exit; a leaving layer's exit is in the accessibility tree |
+| FR7 | Unit tests | Controlled and uncontrolled closes | A callback or `isOpen` waits for the exit |
+| FR8 | Unit and real-browser tests | Reopen during an exit, unmount during an exit, `Activity` hidden during an exit | The surface disappears and reappears, or stays after unmount |
+| FR9 | Unit test with a suppressed end event; real-browser test with animations and transitions disabled page-wide | Open and close in one update; page-wide `transition: none`; no end event | The surface is present more than 100ms after its exit duration |
+| FR10 | Real-browser test with reduced motion emulated, fine primary pointer | Each kind turned on | An exit plays |
+| FR11 | Real-browser frame sampling during an exit | A hover card, a menu with an open sub-menu, a selector with a search query | The leaving surface shows other content, or none, before it is hidden |
+| FR12 | Token default tests, theme template inventory test, token documentation check | Defaults; the `BottomSheet` closing curve | A default drifts, or `BottomSheet` restates the curve |
+| FR13 | Real-browser test | A toast action pressed, and a toast dismissed, during a dialog exit; the same toast after the dialog is hidden | The toast ignores input or fades with the dialog during the exit, or loses its entries or timers when the dialog is hidden |
+| FR14 | Real-browser test with a coarse primary pointer, after hydration | A Dialog, a Popover, and a menu opened and closed by a finger, with each kind switched off and on; the same surfaces under reduced motion | A switch changes the touch exit, or the surface closes without the exit `spec:AST-094` FR7 and FR8 give it |
+| Platform | Real-browser tests in Chromium and WebKit | A dialog exit and a layer exit with each kind on; a layer close where the Popover API is missing | A layer exit paints outside the top layer or does not play, or a close without the Popover API is delayed |
## Decision log
diff --git a/docs/specs/components/HoverCard/HoverCard.spec.md b/docs/specs/components/HoverCard/HoverCard.spec.md
index 0a1a183479..91f115cf5a 100644
--- a/docs/specs/components/HoverCard/HoverCard.spec.md
+++ b/docs/specs/components/HoverCard/HoverCard.spec.md
@@ -39,15 +39,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`, `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, an opt-in early migration when run explicitly, rewrites icon and span triggers and reports the rest (`component:Tooltip` DEP-0016), and `component:Tooltip` CLN-0024 names each remaining kind's replacement in 0.8.0, whose upgrade runs the codemod again. |
-| 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`. |
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `HoverCard` with `children` (trigger), `content`, `label`, `placement` (`above`), `alignment` (`center`), `delay` (300), `hideDelay` (200), `focusTrigger`, `touchTrigger` (`auto`), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `hover-card`. `useHoverCard` takes the same `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 tap that `touchTrigger` allows, 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 `touchTrigger="none"`, touch never opens it. |
+| 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. Under the default `touchTrigger="auto"`, a tap on a trigger that performs an action performs only that action. |
+| Builder impact | `touchTrigger` answers whether it is safe to consume a tap to show the card (DEC-1): keep the default `auto` on a trigger that performs an action, pass `tap` where a tap only reveals the card, and pass `none` where a tap must never show it. |
+| Compatibility/readiness | No public API change: `touchTrigger` keeps its released values and its default `auto`. Seven 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, `aria-expanded` set on a trigger whose role does not support it, or a tap under `touchTrigger="auto"` that both performs the trigger's action and shows the card. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (lifecycle); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -60,45 +60,19 @@ Consumer usage lives in `HoverCard.doc.mjs`.
## Compatibility and migration
-- 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 `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 `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
- `triggerBehavior`; until CLN-0024, an explicit `touchTrigger` decides taps
- under `triggerBehavior="adaptive"`, and `hover` and `toggle` ignore it
+- Released default preserved: yes. `touchTrigger` keeps its released values
+ and its default `auto`. A disabled control is not an action, so its reason
+ opens on a tap (FR5); that restoration ships on its own as a patch `[fix]`
+- Compatibility class: no public prop, default, DOM, or styling change
- 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
- `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, whose `touchTrigger` to
- `triggerBehavior` codemod is an opt-in early migration from the deprecating release, then CLN-0024 in
- 0.8.0, whose upgrade runs that codemod again with the removal; both cover
- HoverCard's and `useHoverCard`'s `touchTrigger`, and CLN-0024 brings FR5's
- walk to `adaptive`
+ `onOpenChange(false)` without closing itself (FR7)
+- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
-- **A tap inside a control still opens the card.** The shipped
- `touchTrigger="auto"` asks only whether the trigger itself performs an action,
- 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).
-- **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
@@ -129,7 +103,6 @@ Consumer migration instructions belong in consumer docs and release notes.
focus, and a hover-opened card the user has tabbed into closes when the
pointer leaves the trigger, dropping focus to the page. WCAG 1.4.13 requires
content shown on focus to persist until focus moves or the user dismisses it.
- A card pinned by a press (FR9) is held whatever the pointer does.
- **Mixed text children get no trigger.** Text children that reach React as
several strings, such as `Edited {when}`, have no element to attach to: no
focusable span or popup attributes are added, and hover and focus never open
@@ -140,8 +113,7 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
- Trigger wiring, open and close behavior per input, card semantics, and the
- `hover-card` surface (FR1–FR8), including the press toggle and the trigger
- state it sets (FR9, FR10).
+ `hover-card` surface (FR1–FR8).
**Does not own / non-goals**
@@ -154,28 +126,25 @@ 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. |
-| 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. |
+| 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. |
+| Touch trigger | `auto`, `tap`, `none` | Whether it is safe to consume a tap to show the card (DEC-1): `auto` shows it on a tap unless the trigger itself performs an action, a disabled control excepted (FR5); `tap` shows it on every tap; `none` on no tap. | Touch without hover. | `auto` | `component:HoverCard` | Stable | 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 `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. `architecture:layer-runtime` INV17 states this stop for every layer root. | `component:HoverCard` FR9 (a pinning press stops at its trigger); `component:Tooltip` FR11; `architecture:layer-runtime` INV17 |
+| 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 the card per `touchTrigger` when the finger lifts; a touch that becomes a scroll does not. Under `auto`, a tap opens it unless the trigger itself performs an action; an `aria-disabled` control, or a label for a disabled control, is not an action, so a disabled control's reason opens on a tap (DEC-1). Under `tap`, every tap opens it; under `none`, no tap does. 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. Whether `auto` also leaves the card shut when the tap acts on a control around the trigger is open (`component:Tooltip` OQ1). | 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 |
+| 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. `architecture:layer-runtime` INV17 states this stop for every layer root. | `component:Tooltip` FR11; `architecture:layer-runtime` INV17 |
### Allowed variation
@@ -210,12 +179,6 @@ 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 `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
- second press, a press outside, or focus leaving (FR9, WCAG 1.4.13).
- Implementation gap: not yet built.
## Design relationships
@@ -257,16 +220,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, SSR, and card `xstyle`/`className`/`style` tests; `HoverCardAudit` Chromium frames of `HoverCard / Open States` for the single target, equal padding on every logical edge, and the text trigger's dashed hover cue | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails, and so do card `xstyle`, `className`, or `style` that do not reach the card, missing or unequal card padding, or a lost dashed cue on a text trigger. | `audit:HoverCard/anatomy` |
-| FR3, AR1 | `HoverCard.test.tsx` role, trigger-attribute, and attribute-restore tests; `HoverCardAudit` frames and the audit axe pass on `HoverCard / Open States` | Labelled and unlabelled; supported and unsupported roles | Wrong role, trigger attributes that are not replaced and restored as stated, or a new axe violation on an open card, fail. | `audit:HoverCard/accessibility` |
-| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, delay and hide-delay timing, trigger-to-card hold, Escape, refocus, and touch tests; `HoverCardAudit` hover-and-keyboard pass in Chromium; `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, that opens before `delay` or closes before `hideDelay`, that closes while the pointer moves from the trigger into it, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |
-| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, onOpenChange, `isOpen` forcing, and controlled-close focus-return tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open, held open, held closed, closed by the caller with focus inside | Wrong state reporting, a hover that hides a card held open or opens one held closed, or focus left inside a card the caller closes, 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` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, SSR, and card `xstyle`/`className`/`style` tests; `HoverCardAudit` Chromium frames of `HoverCard / Open States` for the single target, equal padding on every logical edge, and the text trigger's dashed hover cue | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails, and so do card `xstyle`, `className`, or `style` that do not reach the card, missing or unequal card padding, or a lost dashed cue on a text trigger. | `audit:HoverCard/anatomy` |
+| FR3, AR1 | `HoverCard.test.tsx` role, trigger-attribute, and attribute-restore tests; `HoverCardAudit` frames and the audit axe pass on `HoverCard / Open States` | Labelled and unlabelled; supported and unsupported roles | Wrong role, trigger attributes that are not replaced and restored as stated, or a new axe violation on an open card, fail. | `audit:HoverCard/accessibility` |
+| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, delay and hide-delay timing, trigger-to-card hold, Escape, refocus, and touch tests; `HoverCardAudit` hover-and-keyboard pass in Chromium; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases | Hover, focus, tap, Escape from trigger and content; `touchTrigger` `auto`, `tap`, and `none`; an action trigger; a disabled control inside a clickable row | A card that cannot be reached or dismissed, that opens before `delay` or closes before `hideDelay`, that closes while the pointer moves from the trigger into it, or that opens on a tap on a trigger that performs an action under `auto` or on any tap under `none`, fails. | `audit:HoverCard/behavior` |
+| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, onOpenChange, `isOpen` forcing, and controlled-close focus-return tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open, held open, held closed, closed by the caller with focus inside | Wrong state reporting, a hover that hides a card held open or opens one held closed, or focus left inside a card the caller closes, 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:
@@ -281,29 +242,19 @@ Checked only in a browser, with no unit test:
## Decision log
-### DEC-1 — A press pins the card; a tap that already acts stays with its control
+### DEC-1 — `touchTrigger` decides whether a tap may show the card
**Reference:** `component:HoverCard/DEC-1`
-**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01`
-
-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 `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 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
-the card the same tap opened.
+**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01` and `2026-11-02`
+
+`touchTrigger` answers whether it is safe to consume a tap to show the card,
+as `component:Tooltip` DEC-1 states: `auto`, the default, shows the card on a
+tap only when the trigger performs no action of its own, so one tap does one
+thing; `tap` declares that every tap may show it; `none` declares that no tap
+may. 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. HoverCard has no public toggle prop; toggle-style triggers follow
+`component:Tooltip` DEC-1.
## Open questions
diff --git a/docs/specs/components/InfoTip/InfoTip.spec.md b/docs/specs/components/InfoTip/InfoTip.spec.md
index 581e08b62c..723a388294 100644
--- a/docs/specs/components/InfoTip/InfoTip.spec.md
+++ b/docs/specs/components/InfoTip/InfoTip.spec.md
@@ -42,21 +42,21 @@ system_specs: [spec:AST-017, spec:AST-094]
## Contract at a glance
-| 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 `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; the `@astryxdesign/lab` export is a deprecated re-export of it for one release (FR4). |
-| Review checks | Reject a layer, listener, timer, or dismissal rule of InfoTip's own, a trigger that is not a named button, an untranslated default name, or a prop beyond those FR3 lists. |
-| Governing rules | `component:Tooltip` FR9, FR10, AR6; `architecture:public-component-api` INV21; `spec:AST-094` FR42; `spec:AST-017` (lifecycle). |
+| 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`, which pins the help through its internal press-to-pin path (not a public prop): 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; the `@astryxdesign/lab` export is a deprecated re-export of it for one release (FR4). |
+| Review checks | Reject a layer, listener, timer, or dismissal rule of InfoTip's own, a trigger that is not a named button, an untranslated default name, or a prop beyond those FR3 lists. |
+| Governing rules | `component:Tooltip` FR9, FR10, AR6; `architecture:public-component-api` INV21; `spec:AST-094` FR42; `spec:AST-017` (lifecycle). |
This table is a review projection; the body below is authoritative.
## Intent
-InfoTip is the info-icon preset over Tooltip's press toggle. It owns the
+InfoTip is the info-icon preset over Tooltip's internal press-to-pin path. It owns the
trigger button, its icon, its name, and its default, so every "i" in a product
reads and behaves the same; Tooltip owns when the help opens and closes.
Consumer usage lives in `InfoTip.doc.mjs`.
@@ -66,8 +66,8 @@ 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 `triggerBehavior="toggle"` instead of
- `touchTrigger="tap"`
+ with the same props and pins through Tooltip's internal press-to-pin path
+ instead of opening through `touchTrigger="tap"`
- Controlled/uncontrolled behavior: uncontrolled only; open state is Tooltip's
- Migration decision: DEC-1; the `@astryxdesign/lab` `InfoTip` export stays one
release as a deprecated re-export of the Core component, then is removed
@@ -93,8 +93,7 @@ None.
`family:overlay-dismissal`.
- Info artwork resolution — owned by the icon registry
(`architecture:icon-resolution-and-component-slots`).
-- Rich or interactive help — `component:HoverCard` with
- `triggerBehavior="toggle"`.
+- Rich or interactive help — `component:HoverCard`.
## Public concepts
@@ -104,12 +103,12 @@ None.
## 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`. | 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. | 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`. | 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 pins its help on a press through Tooltip's internal press-to-pin path (not a public prop). It 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. Whether InfoTip moves onto `useTooltip`'s `show()` and `hide()` (`component:Tooltip` DEC-1) is OQ1. | 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
@@ -155,12 +154,12 @@ None.
## Family and system relationships
-- `component:Tooltip` owns the press toggle, preview, announcement, and
+- `component:Tooltip` owns the press-to-pin path, preview, announcement, and
surface; InfoTip is built entirely on it (DEC-1).
- `family:overlay-dismissal` owns Escape order through Tooltip.
- `architecture:icon-resolution-and-component-slots` owns the `info` artwork.
- InfoTip and Tooltip are one API, for the reason DEC-1 gives: InfoTip is built
- entirely on Tooltip's toggle and adds no layer, listener, or dismissal rule of
+ entirely on Tooltip's press-to-pin path and adds no layer, listener, or dismissal rule of
its own, as `component:MoreMenu` is built on DropdownMenu.
## Verification map
@@ -168,20 +167,21 @@ None.
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| FR1, AR1 | `InfoTip.test.tsx` button, name, catalog-default and hit-area cases; `InfoTipTouch.a11y.chromium.spec.ts` coarse-pointer reach, neighbour and fine-pointer cases | Default and custom name; each size | A trigger that is not a named button, an untranslated default, or a coarse-pointer hit area that stays under 44 px where its neighbors leave room or reaches a neighbor's target fails. | `audit:InfoTip/accessibility` |
-| FR2, AR2 | `InfoTip.test.tsx` press cases over `component:Tooltip`'s press-toggle suite | Hover and focus preview; click, tap, Enter, Space pin; Escape | A press that does not pin, or a listener or layer InfoTip owns, fails. | `audit:InfoTip/behavior` |
+| FR2, AR2 | `InfoTip.test.tsx` press cases over `component:Tooltip`'s press-to-pin suite | Hover and focus preview; click, tap, Enter, Space pin; Escape | A press that does not pin, or a listener or layer InfoTip owns, fails. | `audit:InfoTip/behavior` |
| FR3 | `InfoTip.test.tsx` props cases: the type checker rejects other props, and `ref`, `xstyle`, `className`, and `style` reach the button | `content`, `label`, `size`, `ref`, `xstyle`, `className`, `style` | A prop beyond those, or a `ref` that does not reach the button, fails. | `audit:InfoTip/api` |
| FR4 | Lab `InfoTip.test.tsx` identity and deprecation cases | Lab import | A Lab export that is not the Core component, or lacks the deprecation metadata, fails. | `audit:InfoTip/api` |
## Decision log
-### DEC-1 — InfoTip is a preset over Tooltip's toggle
+### DEC-1 — InfoTip is a preset over Tooltip's press-to-pin path
**Reference:** `component:InfoTip/DEC-1`
**Decider:** `cixzhang`, `2026-10-31`
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 `triggerBehavior="toggle"`. A component
+built entirely on `component:Tooltip` and its internal press-to-pin path,
+which has no public prop. 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`
@@ -192,7 +192,9 @@ HoverCard's previews.
## Open questions
-None.
+- **OQ1 — Does InfoTip move onto `useTooltip`'s `show()` and `hide()`?**
+ (`human-api`) Until then it pins through Tooltip's internal press-to-pin
+ path (FR2).
## Content boundary
diff --git a/docs/specs/components/StatusDot/StatusDot.spec.md b/docs/specs/components/StatusDot/StatusDot.spec.md
index 5396f94278..14cb4f8278 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 (`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. |
+| 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 (`component:Tooltip` DEC-1), 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 whose press pins the tooltip once `useTooltip`'s `show()` and `hide()` (`component:Tooltip` DEC-1) ship, 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,8 +58,8 @@ 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 `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
+ whose press pins the tooltip, adopted once `useTooltip`'s `show()` and
+ `hide()` (`component:Tooltip` DEC-1) ship, 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
- Controlled/uncontrolled behavior: not applicable; StatusDot holds no state
@@ -79,9 +79,8 @@ 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
- 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.
+ touch behavior (`touchTrigger="auto"`) opens on such a tap, and a standalone dot does not yet pin its
+ tooltip on a press, 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
@@ -124,14 +123,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 `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 |
+| 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 is a button trigger whose press pins it, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` DEC-1), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the pin once `useTooltip`'s `show()` and `hide()` (`component:Tooltip` DEC-1) ship, 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 pin, 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
@@ -233,7 +232,7 @@ Consumer migration instructions belong in consumer docs and release notes.
## Decision log
-None recorded. The tooltip's toggle follows `component:Tooltip` DEC-1.
+None recorded. The tooltip's pin follows `component:Tooltip` DEC-1.
## Open questions
diff --git a/docs/specs/components/Tooltip/Tooltip.spec.md b/docs/specs/components/Tooltip/Tooltip.spec.md
index fd6dabe1d6..ea62e3c489 100644
--- a/docs/specs/components/Tooltip/Tooltip.spec.md
+++ b/docs/specs/components/Tooltip/Tooltip.spec.md
@@ -50,15 +50,15 @@ system_specs: [spec:AST-003, spec:AST-017, spec:AST-086/FR12, spec:AST-086/FR14]
## Contract at a glance
-| 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, an opt-in early migration when run explicitly, rewrites icon and span triggers and reports the rest (DEP-0016), and CLN-0024 names each remaining kind's replacement in 0.8.0, whose upgrade runs the codemod again. |
-| 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). DEP-0016's deprecation metadata and codemod are not yet built; twelve 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`), `touchTrigger` (`auto`), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. `useTooltip` takes the same `touchTrigger`. The press-to-pin path (FR9, FR10) is internal to Core and has no public prop; `component:InfoTip` is its only caller. |
+| Behavior | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a tap that `touchTrigger` allows; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it). With `touchTrigger="none"`, no touch or pen tap opens it. On the internal press-to-pin path, 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. Under the default `touchTrigger="auto"`, a tap on a trigger that performs an action performs only that action. On the press-to-pin path, people on touch, keyboard, or a screen reader can keep help open to read it, and hear it once when it pins. |
+| Builder impact | `touchTrigger` answers one question: is it safe to consume a tap to show this tooltip (DEC-1)? Keep the default `auto` on a trigger that performs an action, pass `tap` where a tap only reveals the tooltip, and pass `none` where a tap must never show it. Help behind an info icon uses `component:InfoTip`; an app's own toggle-style trigger is a button that calls `useTooltip`'s `show()` and `hide()` (DEC-1). |
+| Compatibility/readiness | No public API change: `touchTrigger` keeps its released values and its default `auto`, and the press-to-pin path adds no public prop. Ten implementation gaps (see Current-state impact). |
+| Review checks | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, a lost `aria-describedby` link, a tap under `touchTrigger="auto"` that both performs the trigger's action and shows the tooltip, a pinned tooltip that closes on pointer leave or lets Escape pass to the layer beneath, a pinning trigger without `aria-expanded`, or a non-button pinning trigger without the development warning. |
+| Governing rules | WCAG 1.4.13, 2.1.1; `family:overlay-dismissal`; `spec:AST-003` FR4; `spec:AST-017` (lifecycle); `architecture:public-component-api` INV9, INV21; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`. |
This table is a review projection; the body below is authoritative.
@@ -71,60 +71,17 @@ in `Tooltip.doc.mjs`.
## Compatibility and migration
-- 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 `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 `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 `triggerBehavior`;
- until CLN-0024, an explicit `touchTrigger` decides taps under
- `triggerBehavior="adaptive"`, and `hover` and `toggle` ignore it
+- Released default preserved: yes. `touchTrigger` keeps its released values
+ and its default `auto`. A disabled control is not an action, so its reason
+ opens on a tap (FR5); that restoration ships on its own as a patch `[fix]`
+- Compatibility class: no public prop, default, DOM, styling, or target change;
+ the press-to-pin path (FR9, FR10) is internal and adds no public surface
- 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
- `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, whose `touchTrigger` to `triggerBehavior`
- codemod is an opt-in early migration from the deprecating release, then CLN-0024 in 0.8.0, whose
- upgrade runs that codemod again with the removal
-
-### 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`; `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"`, since the default `adaptive` reproduces it, rewrites static `touchTrigger="none"` to `triggerBehavior="hover"`, which keeps its behavior, and reports spreads and dynamic values it cannot prove (`spec:AST-017` FR29c, FR29d). It is usable from that release as an opt-in early migration: a caller who runs `astryx upgrade` explicitly moves every `touchTrigger` site to `triggerBehavior` before the removal, each rewrite keeping that release's behavior, and a caller who does not keeps `touchTrigger` working until 0.8.0. 0.8.0's upgrade runs the same codemod again with CLN-0024's removal, there applying CLN-0024's recorded kinds |
-| 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 0.8.0, 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 | DEP-0016's codemod, which callers could already run early, run again by 0.8.0's `astryx upgrade`, 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 0.8.0, a declared minor, with its `[breaking]` Changeset |
+ `onOpenChange(false)` without closing itself (FR7); on the press-to-pin path
+ a press on a controlled tooltip reports the toggled value through
+ `onOpenChange` and does not change the state itself (FR9)
+- Migration decision: none
### CLN-0028 — Remove the surface registry behind `hasInteractiveAncestor`
@@ -140,6 +97,9 @@ Consumer migration instructions belong in consumer docs and release notes.
## Current-state impact
+- **`useTooltip` has no `show()` or `hide()` yet.** An app cannot yet build
+ its own toggle-style trigger as DEC-1 describes; `component:InfoTip` pins
+ through the internal press-to-pin path (FR9, FR10).
- **`hasInteractiveAncestor` still asks the surface registry.** Until the
next minor, the public `hasInteractiveAncestor` answers true for a press
inside an open Tooltip or HoverCard surface, as its documentation states;
@@ -156,19 +116,6 @@ Consumer migration instructions belong in consumer docs and release notes.
tooltip rendered into an iframe or a Picture-in-Picture window with no layer
beneath it is never closed by Escape. WCAG 1.4.13 requires such content to
be dismissible (FR6).
-- **A tap inside a control still opens the tooltip.** The shipped
- `touchTrigger="auto"` asks only whether the trigger itself performs an action,
- so a truncated label inside a link opens its tooltip on the tap that follows
- the link. The walk ships with CLN-0024 (FR5, DEC-1).
-- **DEP-0016 is not built.** `touchTrigger="tap"` carries no `@deprecated`
- metadata yet, and the `astryx upgrade` codemod DEP-0016 names does not exist
- yet; `triggerBehavior` is built (FR9, FR10, and FR5's rules for its values).
-- **FR9's own-text pin is not built.** A trigger whose tooltip repeats its own
- visible text, such as a truncated Text, gets FR9's development warning under
- `triggerBehavior="toggle"` and keeps tap-only opening.
-- **An Item row runs on a press of an anchored button-role trigger.** Item's
- row click skips only native controls. So an anchored or caller's trigger that
- is not a native button pins the tooltip and also runs the row (FR9).
- **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`
@@ -204,8 +151,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- The rendered tooltip surface and content inside that surface (FR1).
- Trigger wiring and when the tooltip opens and closes for each input
- (FR2–FR8), including the press toggle and the trigger state it sets (FR9,
- FR10).
+ (FR2–FR8), including the internal press-to-pin path and the trigger state it sets
+ (FR9, FR10).
**Does not own / non-goals**
@@ -219,27 +166,26 @@ 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, judged when focus arrives (FR4), 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. |
+| 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, judged when focus arrives (FR4), always, or never. | Every trigger mode. | `auto` | `component:Tooltip` | Stable | TypeScript rejects other values. |
+| Touch trigger | `auto`, `tap`, `none` | Whether it is safe to consume a tap to show the tooltip (DEC-1): `auto` shows it on a tap unless the trigger itself performs an action, a disabled control excepted (FR5); `tap` shows it on every tap; `none` on no tap. | Touch and pen without hover; the press-to-pin path decides taps itself (FR9). | `auto` | `component:Tooltip` | Stable | 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, judged when focus arrives. | 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. With `anchorRef`, or `useTooltip` with a caller's trigger, the caller's own handlers still receive the press: the anchor's `onClick` runs, and a plain `onClick` element around the anchor receives it unless the anchor's `onClick` stops it; Astryx clickable rows, cards, and containers ignore it. 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 gaps (Current-state impact): the own-text clause is not built in Core yet. An Item row still runs on a press of an anchored or caller's trigger that is not a native button. | 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. | 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. `architecture:layer-runtime` INV17 states this stop for every layer root. | `component:Tooltip` FR9 (a pinning press stops at its trigger); `component:Tooltip` DEC-1 (one tap does one thing); `architecture:layer-runtime` INV17 |
+| 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, judged when focus arrives. | Current source and tests |
+| FR5 | On touch and pen, a completed tap opens the tooltip per `touchTrigger` when the finger lifts; a touch that becomes a scroll, or a press the browser does not count as a tap, does not open it. Under `auto`, a tap opens it unless the trigger itself performs an action; an `aria-disabled` control, or a label for a disabled control, is not an action, so a disabled control's reason opens on a tap, even inside a clickable row or card (DEC-1). Under `tap`, every tap opens it; under `none`, no tap does. A second tap on the trigger, a tap outside, or a scroll starting outside closes it. On the press-to-pin path, FR9 decides what a tap does. Whether `auto` also leaves the tooltip shut when the tap acts on a control around the trigger is open (OQ1). | Current source and tests |
+| FR6 | Escape closes a visible tooltip; Escape during text composition is ignored. Escape routing follows `family:overlay-dismissal`: a visible topmost tooltip in the page handles that Escape, so a layer underneath stays open for that press. Implementation gap: a tooltip rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). `spec:AST-003` FR4, accepted and not yet implemented, makes an unpinned tooltip passive and gives a pinned one Escape first (Current-state impact). Outside the press-to-pin path, 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 | On the press-to-pin path, an internal Tooltip option with no public prop that `component:InfoTip` uses, a click, a completed tap, Enter, or Space on a trigger whose role is `button` (a `<button>` or `role="button"`) 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. | DEC-1; WCAG 1.4.13, 2.1.1 |
+| FR10 | While the press-to-pin path 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. | 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. `architecture:layer-runtime` INV17 states this stop for every layer root. | `component:Tooltip` FR9 (a pinning press stops at its trigger); `component:Tooltip` DEC-1 (one tap does one thing); `architecture:layer-runtime` INV17 |
### Allowed variation
@@ -278,9 +224,9 @@ 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 `triggerBehavior="toggle"` the
+- **AR6 — A pinned tooltip is a toggletip.** On the press-to-pin path 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
+ (FR10); keyboard and touch users pin and close the tooltip without hover
(FR9); it is announced once when it pins (FR10); and it persists until
Escape, a second press, a press outside, or focus leaving (FR9, WCAG 1.4.13).
@@ -315,19 +261,16 @@ has no arrow element.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |
-| FR2–FR8 | `Tooltip.test.tsx`; `useTooltip.test.tsx` | Hover, focus, tap, Escape, controlled, default open; `auto` judged when focus arrives (roving member, `<summary>`, non-focusable wrapper) | 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 | `usePressPin.test.tsx` Tooltip suites; `TouchTrigger.a11y.chromium.spec.ts` toggle-behavior and mouse cases; `layerDismissalFamilies.test.tsx` pinned Tooltip over a Dialog; own text: evidence gap until built | 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 a child trigger, fails. | `audit:Tooltip/behavior` |
-| FR9 (`anchorRef`) | `usePressPin.test.tsx` `anchorRef` suite; `TouchTrigger.a11y.chromium.spec.ts` anchored case | An anchor with its own `onClick`, inside a ClickableCard, an Item row, a Table row that expands on click, and a plain `onClick` row | An anchor's own `onClick` that does not run, or an Astryx card, row, or Table row around the anchor that activates, fails. | `audit:Tooltip/behavior` |
-| FR5, FR9 (`triggerBehavior`) | `Tooltip.test.tsx` trigger-behavior suite; `TouchTrigger.a11y.chromium.spec.ts` finger and pen cases; `useTooltip.test.tsx` caller-trigger cases; `usePressPin.test.tsx` keyboard and close cases | `adaptive` by default and explicitly, `hover`, and `toggle`, each with mouse hover, keyboard focus, touch, and pen; `touchTrigger` beside each value; a `useTooltip` trigger inside an Astryx clickable card and inside a plain `onClick` element | 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` |
+| 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; `auto` judged when focus arrives (roving member, `<summary>`, non-focusable wrapper) | 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` finger and pen cases; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases | Tap open, scroll, second tap, tap outside; `touchTrigger` `auto`, `tap`, and `none`; an action trigger and a trigger that performs no action; a trigger in running text; a disabled control inside a clickable row | A tap that fails to open or close as stated, opens the tooltip on a trigger that performs an action under `auto` or on any tap under `none`, or leaves a disabled control's reason shut fails. | `audit:Tooltip/behavior` |
+| FR9, FR10, AR6 | `usePressPin.test.tsx` Tooltip suites; `TouchTrigger.a11y.chromium.spec.ts` press-to-pin and mouse cases; `layerDismissalFamilies.test.tsx` pinned Tooltip over a Dialog | 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 pinning 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 a child 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. | — |
+| 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:
@@ -347,49 +290,38 @@ Read from source, with no focused test yet:
## Decision log
-### DEC-1 — A press pins the layer; a tap that already acts stays with its control
+### DEC-1 — `touchTrigger` decides whether a tap may show the tooltip
**Reference:** `component:Tooltip/DEC-1`
-**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01`
-
-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 `triggerBehavior="toggle"` where the tooltip
-is the only home of their information, such as an info icon, a status dot, or
-a timestamp.
-
-`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
-button, link, label, form control, option, menu item, or row or card made
-clickable with `useClickableContainer`, the trigger included. An `aria-disabled`
-control, or a label for a disabled control, is not an action, so its reason
-opens on a tap, even inside a clickable row or card. An element that acts only
-through a role-less `onClick` is a caller fix: it needs a role.
-
-`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.
+**Decider:** `cixzhang`, `2026-10-31`; amended `2026-11-01` and `2026-11-02`
+
+`touchTrigger` answers one question: is it safe to consume a tap to show this
+content? A tap that shows a tooltip must not come before the tap that performs
+the control's action, so one tap does one thing. `auto`, the default, shows
+the tooltip on a tap only when the trigger performs no action of its own;
+`tap` declares that every tap may show it; `none` declares that no tap may. An
+`aria-disabled` control, or a label for a disabled control, is not an action,
+so its reason opens on a tap. An element that acts only through a role-less
+`onClick` is a caller fix: it needs a role.
+
+A press-to-pin toggle answers a different question, so it does not replace
+`touchTrigger`. A toggle needs a button under the trigger that the caller did
+not add, it adds interactions that are not clearly connected to the trigger,
+and it does not solve the touch case. Tooltip has no public toggle prop. An
+app builds a toggle-style trigger by having its own button call `useTooltip`'s
+imperative `show()` and `hide()`, which are not built yet (Current-state
+impact). `component:InfoTip` keeps its current behavior for now: it pins
+through Tooltip's internal press-to-pin path (FR9, FR10).
+`component:HoverCard` DEC-1 applies the same rules.
Rejected: a separate toggletip component, which would repeat Tooltip's and
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.
+- **OQ1 — Does `touchTrigger="auto"` also leave the tooltip shut when a tap
+ acts on a control around the trigger, such as a truncated label inside a
+ link?** (`human-api`) Today `auto` judges the trigger alone.
## Content boundary
diff --git a/packages/core/api-report.md b/packages/core/api-report.md
index 1c69f1db57..53f6c3d530 100644
--- a/packages/core/api-report.md
+++ b/packages/core/api-report.md
@@ -2681,7 +2681,6 @@ component Tooltip(props: TooltipProps)
prop onOpenChange?: (isOpen: boolean) => void
prop placement?: LayerPlacement = 'above'
prop touchTrigger?: TooltipTouchTrigger = 'auto'
- prop triggerBehavior?: TooltipTriggerBehavior = 'adaptive'
component TopNav(props: TopNavProps)
prop centerContent?: ReactNode
prop children?: ReactNode
@@ -5664,7 +5663,6 @@ interface TooltipOptions
onShow?: () => void
placement?: LayerPlacement = 'above'
touchTrigger?: TooltipTouchTrigger = 'auto'
- triggerBehavior?: TooltipTriggerBehavior = 'adaptive'
interface TooltipProps (props of Tooltip)
interface TooltipReturn
anchorId: string
@@ -5674,7 +5672,6 @@ interface TooltipReturn
ref: RefCallback<HTMLElement>
renderTooltip: (children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode
type TooltipTouchTrigger = LayerTouchTrigger
-type TooltipTriggerBehavior = 'adaptive' | 'hover' | 'toggle'
interface TopNavHeadingProps extends BaseProps<HTMLElement> (props of TopNavHeading)
interface TopNavItemProps extends BaseProps<HTMLAnchorElement> (props of TopNavItem)
interface TopNavMegaMenuFeaturedCardProps extends BaseProps<HTMLDivElement> (props of TopNavMegaMenuFeaturedCard)
@@ -8924,7 +8921,6 @@ TooltipOptions (.)
TooltipProps (.)
TooltipReturn (.)
TooltipTouchTrigger (.)
-TooltipTriggerBehavior (.)
useTooltip (.)
```
diff --git a/packages/core/src/InfoTip/InfoTip.doc.mjs b/packages/core/src/InfoTip/InfoTip.doc.mjs
index ec5db4ed35..be2dd58c24 100644
--- a/packages/core/src/InfoTip/InfoTip.doc.mjs
+++ b/packages/core/src/InfoTip/InfoTip.doc.mjs
@@ -66,7 +66,7 @@ export const docs = {
{
guidance: true,
description:
- 'Rely on InfoTip rather than a hand-rolled info button on touch: it sets Tooltip triggerBehavior to toggle, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+ 'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
},
{
guidance: false,
@@ -131,7 +131,7 @@ export const docsZh = {
{
guidance: true,
description:
- 'Rely on InfoTip rather than a hand-rolled info button on touch: it sets Tooltip triggerBehavior to toggle, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+ 'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
},
{
guidance: false,
@@ -168,7 +168,7 @@ export const docsDense = {
{
guidance: true,
description:
- 'Rely on InfoTip rather than a hand-rolled info button on touch: it sets Tooltip triggerBehavior to toggle, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+ 'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
},
{
guidance: false,
diff --git a/packages/core/src/InfoTip/InfoTip.test.tsx b/packages/core/src/InfoTip/InfoTip.test.tsx
index 62681c7191..708b057e40 100644
--- a/packages/core/src/InfoTip/InfoTip.test.tsx
+++ b/packages/core/src/InfoTip/InfoTip.test.tsx
@@ -331,7 +331,7 @@ describe('InfoTip', () => {
const layer = screen.getByRole('tooltip', {hidden: true});
// Revealing the help is the button's whole purpose, so a tap pins it
- // (`triggerBehavior="toggle"`). Without that its content is unreachable on
+ // (Tooltip's press-to-pin path). Without that its content is unreachable on
// a phone.
tap(trigger);
diff --git a/packages/core/src/InfoTip/InfoTip.tsx b/packages/core/src/InfoTip/InfoTip.tsx
index fed5e1e56d..8b7343da11 100644
--- a/packages/core/src/InfoTip/InfoTip.tsx
+++ b/packages/core/src/InfoTip/InfoTip.tsx
@@ -23,7 +23,7 @@ import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {Icon, type IconSize} from '../Icon/Icon';
-import {Tooltip} from '../Tooltip/Tooltip';
+import {TooltipWithTriggerBehavior} from '../Tooltip/Tooltip';
import {
registerEnglishFallback,
useComponentTranslator,
@@ -122,8 +122,8 @@ const styles = stylex.create({
* labels, values, and metrics for permission notes, metric definitions, and
* field help.
*
- * InfoTip is Tooltip with `triggerBehavior="toggle"` on a named button: Tooltip
- * opens, pins, announces, and closes the help. The info icon resolves from
+ * InfoTip is a press-to-pin Tooltip on a named button: Tooltip opens, pins,
+ * announces, and closes the help. The info icon resolves from
* the icon registry, so themes can replace it.
*
* @example
@@ -157,7 +157,7 @@ export function InfoTip({
// stack takes Escape, so one press never closes both the help and an
// enclosing Dialog.
return (
- <Tooltip
+ <TooltipWithTriggerBehavior
content={content}
// The tooltip is the button's only purpose. A click, a tap, Enter, or
// Space pins it open, and the press stops at the button. So an InfoTip's
@@ -179,7 +179,7 @@ export function InfoTip({
)}>
<Icon icon="info" size={size} />
</button>
- </Tooltip>
+ </TooltipWithTriggerBehavior>
);
}
diff --git a/packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts b/packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts
index 7a3cbde0f2..8ba6a72bf8 100644
--- a/packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts
+++ b/packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts
@@ -11,8 +11,8 @@
* the trigger, never opens for a touch that turns into a scroll, and a
* tap-opened layer closes when a tap outside lifts or a scroll starts
* outside.
- * Each `triggerBehavior` value answers a finger or pen tap as it says, and
- * a toggle trigger pins on a press, also under a mouse.
+ * A plain Tooltip and InfoTip's press-to-pin each answer a finger or pen
+ * tap as they say, and InfoTip pins on a press, also under a mouse.
* @position Run with `pnpm test:a11y-contract`. Only a real engine decides
* whether a touch is a tap, a scroll or a long press, so these outcomes
* cannot be shown in jsdom; the unit suites (Tooltip.test.tsx,
@@ -201,7 +201,7 @@ for (const {name, story, trigger, action, layer} of cases) {
});
}
-test.describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9, FR10)', () => {
+test.describe('Tooltip press-to-pin through InfoTip (component:Tooltip FR9, FR10)', () => {
const STORY = 'a11y-tooltip-toggle-behavior--button-toggle';
const CARD_STORY = 'a11y-tooltip-toggle-behavior--in-a-clickable-card';
const LAYER = '.astryx-tooltip:popover-open';
@@ -275,7 +275,7 @@ test.describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9, FR10)',
});
});
-test.describe('Tooltip triggerBehavior under a finger and a pen (component:Tooltip FR5, FR9)', () => {
+test.describe('Tooltip and InfoTip under a finger and a pen (component:Tooltip FR5, FR9)', () => {
const STORY = 'a11y-tooltip-toggle-behavior--trigger-behaviors';
const LAYER = '.astryx-tooltip:popover-open';
const term = (page: Page, name: string) =>
@@ -309,13 +309,10 @@ test.describe('Tooltip triggerBehavior under a finger and a pen (component:Toolt
}
for (const pointer of ['finger', 'pen'] as const) {
- test(`a ${pointer} tap never opens hover, opens adaptive, and pins toggle`, async ({
+ test(`a ${pointer} tap opens a plain Tooltip term and pins an InfoTip`, async ({
page,
}) => {
const finger = await openStory(page, STORY);
- await tapWith(page, finger, term(page, 'Hover term'), pointer);
- await page.waitForTimeout(300);
- await expect(page.locator(LAYER)).toHaveCount(0);
await tapWith(page, finger, term(page, 'Adaptive term'), pointer);
await expect(page.locator(LAYER)).toHaveText('Adaptive: a tap opens it');
const toggle = page.getByRole('button', {name: 'Toggle term'});
@@ -358,40 +355,4 @@ test.describe('a pinned layer under a mouse (component:Tooltip FR9)', () => {
await expect(layer).toHaveCount(1);
await expect(button).toHaveAttribute('aria-expanded', 'true');
});
-
- test('a click on an anchored trigger runs its own click handler and pins it, and the card around it ignores the press', async ({
- page,
- }) => {
- await open(page, 'a11y-tooltip-toggle-behavior--anchored-action-in-a-card');
- const button = page.getByRole('button', {name: 'What is this?'});
- const layer = page.locator('.astryx-tooltip:popover-open');
- const opened = page.getByText(/^Card opened \d+ times$/);
- const pressed = page.getByText(/^Button pressed \d+ times$/);
- await expect(opened).toHaveText('Card opened 0 times');
- await expect(pressed).toHaveText('Button pressed 0 times');
- await button.click();
- await expect(layer).toHaveCount(1);
- await expect(button).toHaveAttribute('aria-expanded', 'true');
- await expect(pressed).toHaveText('Button pressed 1 times');
- await expect(opened).toHaveText('Card opened 0 times');
- await button.click();
- await expect(layer).toHaveCount(0);
- await expect(pressed).toHaveText('Button pressed 2 times');
- await expect(opened).toHaveText('Card opened 0 times');
- });
-
- test('with focusTrigger="never", Tab to another control closes a pinned tooltip', async ({
- page,
- }) => {
- await open(page, 'a11y-tooltip-toggle-behavior--focus-trigger-never');
- const button = page.getByRole('button', {name: 'What is this?'});
- const layer = page.locator('.astryx-tooltip:popover-open');
- await button.click();
- await expect(layer).toHaveCount(1);
- await expect(button).toBeFocused();
- await page.keyboard.press('Tab');
- await expect(page.getByRole('button', {name: 'Next'})).toBeFocused();
- await expect(layer).toHaveCount(0);
- await expect(button).toHaveAttribute('aria-expanded', 'false');
- });
});
diff --git a/packages/core/src/Layer/layerDismissalFamilies.test.tsx b/packages/core/src/Layer/layerDismissalFamilies.test.tsx
index c59471ac3c..18bde17cbf 100644
--- a/packages/core/src/Layer/layerDismissalFamilies.test.tsx
+++ b/packages/core/src/Layer/layerDismissalFamilies.test.tsx
@@ -3,7 +3,7 @@
/**
* @file layerDismissalFamilies.test.tsx
* @input Uses vitest, @testing-library/react, BottomSheet, Dialog, Lightbox,
- * MobileNav, HoverCard, Tooltip (also pinned by `triggerBehavior="toggle"`)
+ * MobileNav, HoverCard, Tooltip (also pinned through its press-to-pin path)
* @output Tests that every overlay family shares the one dismissal stack
* @position Colocated with layerStack; the families' own behavior is tested in
* their own files, this one only asks who takes the press
@@ -37,7 +37,7 @@ import {Dialog} from '../Dialog/Dialog';
import {HoverCard} from '../HoverCard/HoverCard';
import {Lightbox} from '../Lightbox/Lightbox';
import {MobileNav} from '../MobileNav/MobileNav';
-import {Tooltip} from '../Tooltip/Tooltip';
+import {Tooltip, TooltipWithTriggerBehavior} from '../Tooltip/Tooltip';
import {resetLayerStackForTests} from './layerStack';
const originalMatches = HTMLElement.prototype.matches;
@@ -438,9 +438,11 @@ describe('overlay families on the shared dismissal stack', () => {
render(
<Dialog isOpen={true} onOpenChange={onDialogChange} aria-label="Host">
- <Tooltip content="Pinned tip" triggerBehavior="toggle">
+ <TooltipWithTriggerBehavior
+ content="Pinned tip"
+ triggerBehavior="toggle">
<button type="button">Info</button>
- </Tooltip>
+ </TooltipWithTriggerBehavior>
</Dialog>,
);
fireEvent.click(screen.getByRole('button', {name: 'Info'}));
diff --git a/packages/core/src/Layer/usePressPin.calls.test.tsx b/packages/core/src/Layer/usePressPin.calls.test.tsx
index 211489e1a6..b32859a898 100644
--- a/packages/core/src/Layer/usePressPin.calls.test.tsx
+++ b/packages/core/src/Layer/usePressPin.calls.test.tsx
@@ -77,7 +77,7 @@ vi.mock('./useLayerDismissal', async importOriginal => {
};
});
-const {Tooltip} = await import('../Tooltip/Tooltip');
+const {TooltipWithTriggerBehavior} = await import('../Tooltip/Tooltip');
beforeEach(() => {
calls.pin = 0;
@@ -98,11 +98,11 @@ function expectOneCallPerRender() {
describe('usePressPin is each layer’s one call (react-component-runtime INV16)', () => {
it('Tooltip: one usePressPin call per render, the only path to the touch trigger', () => {
render(
- <Tooltip
+ <TooltipWithTriggerBehavior
content="Billed on the first of each month"
triggerBehavior="toggle">
<button type="button">About billing</button>
- </Tooltip>,
+ </TooltipWithTriggerBehavior>,
);
fireEvent.click(screen.getByRole('button', {name: 'About billing'}));
expectOneCallPerRender();
diff --git a/packages/core/src/Layer/usePressPin.test.tsx b/packages/core/src/Layer/usePressPin.test.tsx
index 5f6b1e9ac5..a0c471b767 100644
--- a/packages/core/src/Layer/usePressPin.test.tsx
+++ b/packages/core/src/Layer/usePressPin.test.tsx
@@ -3,7 +3,7 @@
/**
* @file usePressPin.test.tsx
* @input Uses vitest, @testing-library/react, Tooltip, usePressPin
- * @output Tests of `triggerBehavior="toggle"`: a press pins and closes the
+ * @output Tests of Tooltip's press-to-pin path: a press pins and closes the
* layer, and a pin stays when the pointer leaves. Escape, a second press, a
* press outside, or focus leaving closes it. The trigger carries the toggle
* state, the press stops at the trigger, and a non-button trigger warns.
@@ -30,7 +30,7 @@ import {
type ReactElement,
type ReactNode,
} from 'react';
-import {Tooltip} from '../Tooltip/Tooltip';
+import {Tooltip, TooltipWithTriggerBehavior} from '../Tooltip/Tooltip';
import {HoverCard} from '../HoverCard/HoverCard';
import {ClickableCard} from '../ClickableCard/ClickableCard';
import {Dialog} from '../Dialog/Dialog';
@@ -137,7 +137,7 @@ function InfoTooltip({
onOpenChange?: (isOpen: boolean) => void;
}): ReactElement {
return (
- <Tooltip
+ <TooltipWithTriggerBehavior
content="Billed on the first of each month"
triggerBehavior="toggle"
{...props}>
@@ -146,13 +146,13 @@ function InfoTooltip({
i
</button>
)}
- </Tooltip>
+ </TooltipWithTriggerBehavior>
);
}
const TIP = 'Billed on the first of each month';
-describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
+describe('Tooltip press-to-pin (component:Tooltip FR9)', () => {
it('a click pins the tooltip open, and the same click closes it', () => {
render(<InfoTooltip />);
const trigger = screen.getByRole('button', {name: 'About billing'});
@@ -328,22 +328,22 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
expect(trigger).toHaveAttribute('aria-expanded', 'true');
});
- it('a triggerBehavior that turns to toggle after mount wires the trigger', () => {
+ it('a trigger behavior that turns to toggle after mount wires the trigger', () => {
const {rerender} = render(
- <Tooltip content={TIP}>
+ <TooltipWithTriggerBehavior content={TIP}>
<button type="button" aria-label="About billing">
i
</button>
- </Tooltip>,
+ </TooltipWithTriggerBehavior>,
);
const trigger = screen.getByRole('button', {name: 'About billing'});
expect(trigger).not.toHaveAttribute('aria-expanded');
rerender(
- <Tooltip content={TIP} triggerBehavior="toggle">
+ <TooltipWithTriggerBehavior content={TIP} triggerBehavior="toggle">
<button type="button" aria-label="About billing">
i
</button>
- </Tooltip>,
+ </TooltipWithTriggerBehavior>,
);
expect(trigger).toHaveAttribute('aria-expanded', 'false');
click(trigger);
@@ -362,11 +362,14 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
it('with focusTrigger="never", focus moving to another control closes a pinned tooltip', () => {
render(
<>
- <Tooltip content={TIP} triggerBehavior="toggle" focusTrigger="never">
+ <TooltipWithTriggerBehavior
+ content={TIP}
+ triggerBehavior="toggle"
+ focusTrigger="never">
<button type="button" aria-label="About billing">
i
</button>
- </Tooltip>
+ </TooltipWithTriggerBehavior>
<button type="button">Next field</button>
</>,
);
@@ -383,14 +386,16 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
expect(trigger).toHaveAttribute('aria-expanded', 'false');
});
- it('a pinned tooltip whose triggerBehavior turns to adaptive closes on leave again', () => {
+ it('a pinned tooltip whose trigger behavior turns to adaptive closes on leave again', () => {
vi.useFakeTimers();
const tip = (triggerBehavior?: 'toggle') => (
- <Tooltip content={TIP} triggerBehavior={triggerBehavior}>
+ <TooltipWithTriggerBehavior
+ content={TIP}
+ triggerBehavior={triggerBehavior}>
<button type="button" aria-label="About billing">
i
</button>
- </Tooltip>
+ </TooltipWithTriggerBehavior>
);
const {rerender} = render(tip('toggle'));
const trigger = screen.getByRole('button', {name: 'About billing'});
@@ -421,7 +426,7 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
</InfoTooltip>,
);
expect(warn).toHaveBeenCalledWith(
- expect.stringContaining('triggerBehavior="toggle"'),
+ expect.stringContaining('A press-to-pin tooltip'),
);
const trigger = screen.getByText('Billing');
click(trigger);
@@ -438,15 +443,18 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
try {
const tip = (delay: number) => (
- <Tooltip content={TIP} triggerBehavior="toggle" delay={delay}>
+ <TooltipWithTriggerBehavior
+ content={TIP}
+ triggerBehavior="toggle"
+ delay={delay}>
<span tabIndex={0}>Billing</span>
- </Tooltip>
+ </TooltipWithTriggerBehavior>
);
const {rerender} = render(tip(200));
rerender(tip(300));
rerender(tip(400));
const calls = warn.mock.calls.filter(([message]) =>
- String(message).includes('triggerBehavior="toggle"'),
+ String(message).includes('A press-to-pin tooltip'),
);
expect(calls).toHaveLength(1);
} finally {
@@ -455,40 +463,21 @@ describe('Tooltip triggerBehavior="toggle" (component:Tooltip FR9)', () => {
});
});
-describe('Tooltip triggerBehavior="adaptive" and "hover" (component:Tooltip FR5)', () => {
- /** An info-only trigger: a tap on it performs no action of its own. */
- function Hint(props: {triggerBehavior?: 'adaptive' | 'hover'}): ReactElement {
- return (
- <Tooltip content={TIP} {...props}>
+describe('Tooltip without press-to-pin (component:Tooltip FR5)', () => {
+ it('a tap on an info-only trigger opens it, and no press pins it', () => {
+ render(
+ <Tooltip content={TIP}>
<span tabIndex={0}>Billing</span>
- </Tooltip>
+ </Tooltip>,
);
- }
-
- it('adaptive, the default: a tap on an info-only trigger opens it', () => {
- render(<Hint />);
- tap(screen.getByText('Billing'));
- expect(shows(TIP)).toBe(true);
- });
-
- it('hover: a tap never opens it, a mouse hover still previews it, and no press pins it', () => {
- vi.useFakeTimers();
- render(<Hint triggerBehavior="hover" />);
const trigger = screen.getByText('Billing');
tap(trigger);
- expect(shows(TIP)).toBe(false);
- fireEvent.pointerEnter(trigger, {pointerType: 'mouse'});
- fireEvent.mouseEnter(trigger);
- act(() => {
- vi.advanceTimersByTime(500);
- });
expect(shows(TIP)).toBe(true);
- click(trigger);
expect(trigger).not.toHaveAttribute('aria-expanded');
});
});
-describe('Tooltip triggerBehavior="toggle" trigger state (component:Tooltip FR10)', () => {
+describe('Tooltip press-to-pin trigger state (component:Tooltip FR10)', () => {
it('carries aria-expanded, true only while pinned, and aria-controls while it shows', () => {
render(<InfoTooltip />);
const trigger = screen.getByRole('button', {name: 'About billing'});
@@ -633,7 +622,11 @@ describe('a toggle press stops at its trigger', () => {
}}>
i
</button>
- <Tooltip content={TIP} anchorRef={ref} triggerBehavior="toggle" />
+ <TooltipWithTriggerBehavior
+ content={TIP}
+ anchorRef={ref}
+ triggerBehavior="toggle"
+ />
</>
);
}
diff --git a/packages/core/src/Layer/usePressPin.ts b/packages/core/src/Layer/usePressPin.ts
index 1d68c69213..fec178eb7f 100644
--- a/packages/core/src/Layer/usePressPin.ts
+++ b/packages/core/src/Layer/usePressPin.ts
@@ -35,12 +35,10 @@ import {
/**
* How the trigger opens the layer. `adaptive`, the default, previews it on
- * hover and focus, and a tap opens it unless the trigger acts. While
- * `touchTrigger` remains, it decides those taps. `hover` previews it on hover
- * and focus, and no touch or pen tap opens it. `toggle` pins it on every
- * press of a button trigger.
+ * hover and focus, and `touchTrigger` decides taps. `toggle` pins it on every
+ * press of a button trigger. Internal: InfoTip's press-to-pin uses `toggle`.
*/
-export type LayerTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
+export type LayerTriggerBehavior = 'adaptive' | 'toggle';
/** The clicks a press pin answered, so the wrapper can stop them (`stopPressPinClick`). */
const pressPinClicks = new WeakSet<Event>();
@@ -214,11 +212,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
clearTapOpen,
armOutsideDismiss,
} = useTouchTriggerInternal({
- touchTrigger: isToggleMode
- ? 'tap'
- : triggerBehavior === 'hover'
- ? 'none'
- : options.touchTrigger,
+ touchTrigger: isToggleMode ? 'tap' : options.touchTrigger,
isEnabled: options.isEnabled,
isControlled: isOpen !== undefined,
isOpen: isLayerOpen,
@@ -466,7 +460,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
const isWired = isToggleMode && offeredKind === 'button';
useDevWarning(
options.component,
- '`triggerBehavior="toggle"` pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.',
+ 'A press-to-pin tooltip pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.',
isToggleMode && offeredKind === 'other',
);
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index d13ce2b91f..a4125c6926 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -24,16 +24,29 @@ export const docs = {
playground: {
defaults: {
content: 'Helpful tooltip text',
- children: {__element: 'Button', props: {label: 'Hover me', variant: 'secondary'}},
+ children: {
+ __element: 'Button',
+ props: {label: 'Hover me', variant: 'secondary'},
+ },
},
},
- keywords: ["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],
+ keywords: [
+ 'tooltip',
+ 'hint',
+ 'infotip',
+ 'title',
+ 'hover',
+ 'flyout',
+ 'balloon',
+ 'helpertext',
+ ],
components: [
{
name: 'Tooltip',
displayName: 'Tooltip',
description:
- 'Component wrapper for tooltip display triggered on hover or focus.', props: [
+ 'Component wrapper for tooltip display triggered on hover or focus.',
+ props: [
{
name: 'children',
type: 'ReactNode',
@@ -48,18 +61,26 @@ export const docs = {
name: 'content',
type: 'ReactNode',
description: 'Tooltip content, typically short text.',
- slotElements: [{__element: 'Text', props: {type: 'body'}, children: 'Content text'}],
+ slotElements: [
+ {
+ __element: 'Text',
+ props: {type: 'body'},
+ children: 'Content text',
+ },
+ ],
},
{
name: 'placement',
type: "'above' | 'below' | 'start' | 'end'",
- description: "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+ description:
+ "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
default: "'above'",
},
{
name: 'alignment',
type: "'start' | 'center' | 'end'",
- description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+ description:
+ "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
default: "'center'",
},
{
@@ -84,16 +105,9 @@ export const docs = {
name: 'touchTrigger',
type: "'auto' | 'tap' | 'none'",
description:
- 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens. none never opens on touch. It decides only under triggerBehavior="adaptive", the default.',
+ 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens, for a button whose only job is to reveal the tooltip; for an info icon, use InfoTip. none never opens on touch.',
default: "'auto'",
},
- {
- name: 'triggerBehavior',
- type: "'adaptive' | 'hover' | 'toggle'",
- description:
- 'How the trigger opens the tooltip. adaptive (the default): hover and focus preview it, and a tap opens it unless the trigger performs an action of its own, as touchTrigger decides while it remains. hover: hover and focus preview it, and no touch or pen tap opens it. toggle, on a button trigger: a click, a tap, Enter, or Space pins the tooltip and the same press closes it, while hover and keyboard focus still preview it. A pinned tooltip stays until Escape, a second press, a press outside, or focus leaving, and the press stops at the trigger, so a clickable row or card around it does not activate (with anchorRef, the anchored trigger still runs its own onClick, Astryx clickable rows and cards ignore the press except an Item row when the anchor is not a native button, and a plain onClick element around the anchor receives it unless that onClick stops it). The trigger reports aria-expanded and aria-controls, and the text is announced once when it pins. Use it for an info icon or any button whose only job is revealing the tooltip.',
- default: "'adaptive'",
- },
{
name: 'isEnabled',
type: 'boolean',
@@ -115,7 +129,8 @@ export const docs = {
{
name: 'isDefaultOpen',
type: 'boolean',
- description: 'Whether the tooltip should be shown on mount. Still dismissible.',
+ description:
+ 'Whether the tooltip should be shown on mount. Still dismissible.',
},
{
name: 'isOpen',
@@ -126,20 +141,38 @@ export const docs = {
},
],
theming: {
- targets: [
- {className: 'astryx-tooltip'},
- ],
+ targets: [{className: 'astryx-tooltip'}],
},
usage: {
anatomy,
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
- {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: true, description: 'Set triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
- {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+ {
+ guidance: true,
+ description:
+ 'Keep tooltip content concise: aim for under 140 characters of plain text.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use tooltips for essential information that users must see to complete a task.',
+ },
],
},
};
@@ -152,8 +185,7 @@ export const docsZh = {
{
name: 'Tooltip',
displayName: 'Tooltip',
- description:
- '工具提示显示的组件包装器,通过悬停或聚焦触发。',
+ description: '工具提示显示的组件包装器,通过悬停或聚焦触发。',
props: [
{
name: 'children',
@@ -173,13 +205,15 @@ export const docsZh = {
{
name: 'placement',
type: "'above' | 'below' | 'start' | 'end'",
- description: '相对于锚点元素的位置。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',
+ description:
+ '相对于锚点元素的位置。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',
default: "'above'",
},
{
name: 'alignment',
type: "'start' | 'center' | 'end'",
- description: '沿放置轴的对齐方式。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',
+ description:
+ '沿放置轴的对齐方式。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',
default: "'center'",
},
{
@@ -204,16 +238,9 @@ export const docsZh = {
name: 'touchTrigger',
type: "'auto' | 'tap' | 'none'",
description:
- '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有;设置了 aria-disabled 的控件不执行操作,因此轻点它会显示其原因。tap:始终轻点打开。none:触摸永不打开。仅在 triggerBehavior 为 adaptive(默认)时生效。',
+ '在没有悬停的触摸设备上,轻点的行为。auto:轻点即打开,除非触发元素本身会执行操作(按钮、链接、表单控件),此时轻点归该控件所有;设置了 aria-disabled 的控件不执行操作,因此轻点它会显示其原因。tap:始终轻点打开,适用于唯一作用是显示工具提示的按钮;信息图标请使用 InfoTip。none:触摸永不打开。',
default: "'auto'",
},
- {
- name: 'triggerBehavior',
- type: "'adaptive' | 'hover' | 'toggle'",
- description:
- '触发元素如何打开工具提示。adaptive(默认):悬停和聚焦会预览;轻点即打开,除非触发元素本身会执行操作(在 touchTrigger 仍存在期间由它决定)。hover:悬停和聚焦会预览,触摸或触控笔轻点都不会打开。toggle(仅限按钮触发元素):单击、轻点、Enter 或空格键固定打开,再按一次关闭;悬停和键盘聚焦仍会预览。固定后,直到按 Escape、再次按下、在外部按下或焦点移出才关闭;这次按下止于触发元素,外层可点击的行或卡片不会被激活(使用 anchorRef 时,锚定元素自身的 onClick 仍会运行,Astryx 的可点击行和卡片会忽略这次按下,但锚定元素不是原生按钮时,Item 行仍会响应,锚定元素外层普通的 onClick 元素仍会收到,除非锚定元素的 onClick 阻止它)。触发元素会报告 aria-expanded 和 aria-controls,固定时朗读一次文本。适用于信息图标等唯一作用就是显示工具提示的按钮。',
- default: "'adaptive'",
- },
{
name: 'isEnabled',
type: 'boolean',
@@ -241,37 +268,76 @@ export const docsZh = {
},
],
theming: {
- targets: [
- {className: 'astryx-tooltip'},
- ],
+ targets: [{className: 'astryx-tooltip'}],
},
usage: {
anatomy,
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
- {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: true, description: 'Set triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
- {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+ {
+ guidance: true,
+ description:
+ 'Keep tooltip content concise: aim for under 140 characters of plain text.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use tooltips for essential information that users must see to complete a task.',
+ },
],
},
};
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
+ description:
+ 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
usage: {
anatomy,
description:
'A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.',
bestPractices: [
- {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
- {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
- {guidance: true, description: 'Set triggerBehavior to toggle when the trigger is a button whose only job is revealing the tooltip, such as an info icon: a click, a tap, Enter, or Space pins it, and the press stops at the trigger.'},
- {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
- {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
+ {
+ guidance: true,
+ description:
+ 'Keep tooltip content concise: aim for under 140 characters of plain text.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Add a tooltip to icon-only buttons and controls that lack a visible label.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip: touch has no hover, and auto keeps the tap for triggers that perform an action. For an info icon, use InfoTip, which also pins its help on a press.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use tooltips for essential information that users must see to complete a task.',
+ },
],
},
components: [
@@ -283,15 +349,18 @@ export const docsDense = {
children: 'Trigger element(s) that activate tooltip.',
anchorRef: 'External anchor ref for sibling mode.',
content: 'Tooltip content, typically short text.',
- placement: 'Position relative to anchor. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
- alignment: 'Alignment along placement axis. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+ placement:
+ "Position relative to anchor. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
+ alignment:
+ "Alignment along placement axis. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
delay: 'Show delay in ms.',
hideDelay: 'Hide delay in ms.',
focusTrigger: 'Controls when focus events trigger tooltip.',
- touchTrigger: 'Tap behavior where there is no hover, under triggerBehavior="adaptive" only. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens; none = never on touch.',
- triggerBehavior: 'adaptive (default) = hover/focus preview, a tap opens unless the trigger acts; hover = hover/focus preview, no touch/pen tap opens; toggle = a click/tap/Enter/Space on a button trigger pins the tooltip (aria-expanded, announced once), the same press closes it, and the press stops at the trigger.',
+ touchTrigger:
+ 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (a button whose only job is the tooltip; for an info icon use InfoTip); none = never on touch.',
isEnabled: 'Enables/disables tooltip triggers.',
- onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
+ onOpenChange:
+ 'Callback when visibility changes; true=shown, false=hidden.',
hasHoverIndication: 'Dashed underline on trigger element.',
isDefaultOpen: 'Show tooltip on mount. Still dismissible.',
},
diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsx
index 45be9bfeb6..f48c2b1109 100644
--- a/packages/core/src/Tooltip/Tooltip.test.tsx
+++ b/packages/core/src/Tooltip/Tooltip.test.tsx
@@ -25,8 +25,8 @@ import {
fireEvent,
waitFor,
} from '@testing-library/react';
-import {useRef} from 'react';
-import {Tooltip} from './Tooltip';
+import {useRef, type ComponentProps} from 'react';
+import {Tooltip, TooltipWithTriggerBehavior} from './Tooltip';
import {ClickableCard} from '../ClickableCard/ClickableCard';
import {Item} from '../Item/Item';
import {Token} from '../Token/Token';
@@ -979,12 +979,12 @@ describe('Tooltip surface press', () => {
});
});
-describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)', () => {
+describe('Tooltip, and its press-to-pin path, on every input (component:Tooltip FR5, FR9)', () => {
beforeEach(() => {
__resetInteractionModalityForTest();
});
- type Behavior = 'adaptive' | 'hover' | 'toggle';
+ type Behavior = 'adaptive' | 'toggle';
/** An info-only trigger: a span, or under the toggle the button it pins. */
function setup(
@@ -994,7 +994,7 @@ describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)',
) {
const onOpenChange = vi.fn<(open: boolean) => void>();
render(
- <Tooltip
+ <TooltipWithTriggerBehavior
content="Billed monthly"
delay={0}
onOpenChange={onOpenChange}
@@ -1005,7 +1005,7 @@ describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)',
) : (
<span tabIndex={0}>Billing</span>
)}
- </Tooltip>,
+ </TooltipWithTriggerBehavior>,
);
const opened = () => onOpenChange.mock.calls.some(([open]) => open);
return {trigger: screen.getByText('Billing'), opened};
@@ -1029,7 +1029,6 @@ describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)',
describe.each([
['adaptive by default', undefined, true],
['adaptive', 'adaptive', true],
- ['hover', 'hover', false],
['toggle', 'toggle', true],
] as const)('%s', (_, behavior, tapOpens) => {
it('a mouse hover previews it', async () => {
@@ -1082,7 +1081,6 @@ describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)',
it.each([
['adaptive', 'none', 'span', 'decides: no tap opens it', false],
['adaptive', 'tap', 'button', 'decides: every tap opens it', true],
- ['hover', 'tap', 'button', 'is ignored: no tap opens it', false],
['toggle', 'none', 'button', 'is ignored: a tap pins it', true],
] as const)(
'beside triggerBehavior="%s", touchTrigger="%s" on a %s %s',
@@ -1097,3 +1095,22 @@ describe('Tooltip triggerBehavior on every input (component:Tooltip FR5, FR9)',
},
);
});
+
+describe('Tooltip keeps press-to-pin internal', () => {
+ it('a spread props object that carries triggerBehavior at runtime pins nothing', () => {
+ const props = {
+ content: 'Billed monthly',
+ triggerBehavior: 'toggle',
+ } as unknown as ComponentProps<typeof Tooltip>;
+ render(
+ <Tooltip {...props}>
+ <button type="button">Billing</button>
+ </Tooltip>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Billing'});
+ fireEvent.pointerDown(trigger, {pointerType: 'mouse'});
+ fireEvent.pointerUp(trigger, {pointerType: 'mouse'});
+ fireEvent.click(trigger, {detail: 1});
+ expect(trigger).not.toHaveAttribute('aria-expanded');
+ });
+});
diff --git a/packages/core/src/Tooltip/Tooltip.tsx b/packages/core/src/Tooltip/Tooltip.tsx
index 4c447623d7..ea59fc16a7 100644
--- a/packages/core/src/Tooltip/Tooltip.tsx
+++ b/packages/core/src/Tooltip/Tooltip.tsx
@@ -5,7 +5,8 @@
/**
* @file Tooltip.tsx
* @input Uses React, useTooltip hook
- * @output Exports Tooltip component for hover/focus triggered tooltips
+ * @output Exports Tooltip component for hover/focus triggered tooltips, and the
+ * module-only TooltipWithTriggerBehavior that InfoTip's press-to-pin uses
* @position Layer component; uses display:contents wrapper to avoid cloneElement
*
* SYNC: When modified, update these files to stay in sync:
@@ -23,20 +24,18 @@ import React, {
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import * as stylex from '@stylexjs/stylex';
import {
- useTooltip,
+ useTooltipWithTriggerBehavior,
type TooltipFocusTrigger,
- type TooltipTriggerBehavior,
type TooltipTouchTrigger,
} from './useTooltip';
-import {stopPressPinClick} from '../Layer/usePressPin';
+import {
+ stopPressPinClick,
+ type LayerTriggerBehavior,
+} from '../Layer/usePressPin';
import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {colorVars} from '../theme/tokens.stylex';
-export type {
- TooltipFocusTrigger,
- TooltipTriggerBehavior,
- TooltipTouchTrigger,
-} from './useTooltip';
+export type {TooltipFocusTrigger, TooltipTouchTrigger} from './useTooltip';
const styles = stylex.create({
wrapperContents: {
@@ -118,37 +117,10 @@ export interface TooltipProps {
* - `tap`: tap always opens the tooltip, even on a trigger that acts
* - `none`: touch never opens the tooltip
*
- * It decides only under `triggerBehavior="adaptive"`, the default.
- *
* @default 'auto'
*/
touchTrigger?: TooltipTouchTrigger;
- /**
- * How the trigger opens the tooltip:
- * - `adaptive` (the default): hover and focus preview it. A tap opens it
- * unless the trigger performs an action of its own. While `touchTrigger`
- * remains, it decides those taps.
- * - `hover`: hover and focus preview it; no touch or pen tap opens it.
- * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
- * tooltip open, and the same press closes it. Hover and keyboard focus
- * still preview it. A pinned tooltip stays until Escape, a second press,
- * a press outside, or focus leaving. The press stops at the trigger. Its
- * default action is prevented, and the trigger's own handlers still run.
- * No clickable row or card around the trigger activates. With
- * `anchorRef`, the anchor's own `onClick` runs, and a plain `onClick`
- * element around it receives the press unless that `onClick` stops it.
- * Astryx clickable rows, cards, and containers ignore it, except an Item
- * row when the anchor is not a native button. The trigger reports
- * `aria-expanded` and `aria-controls`, and the tooltip's text is
- * announced once when it pins. Use it for a trigger whose information
- * lives only in the tooltip, such as an info icon. `touchTrigger` is
- * ignored.
- *
- * @default 'adaptive'
- */
- triggerBehavior?: TooltipTriggerBehavior;
-
/**
* Whether the tooltip is enabled.
* When false, hover/focus triggers are disabled.
@@ -222,7 +194,32 @@ function mergeIds(...ids: (string | undefined | null)[]): string | undefined {
* </Tooltip>
* ```
*/
-export function Tooltip({
+export function Tooltip(props: TooltipProps): ReactElement {
+ // The option is fixed to `adaptive`, so a spread object that carries it at
+ // runtime cannot reach the press-to-pin path.
+ return <TooltipWithTriggerBehavior {...props} triggerBehavior="adaptive" />;
+}
+
+/**
+ * Module-only props for `TooltipWithTriggerBehavior`. Not exported from the
+ * package.
+ */
+export interface TooltipWithTriggerBehaviorProps extends TooltipProps {
+ /**
+ * How the trigger opens the tooltip. `toggle` pins it on a click, a tap,
+ * Enter, or Space on a button trigger, and stops that press at the trigger
+ * (see `useTooltipWithTriggerBehavior`). InfoTip uses it.
+ *
+ * @default 'adaptive'
+ */
+ triggerBehavior?: LayerTriggerBehavior;
+}
+
+/**
+ * `Tooltip` with a trigger behavior. Module-only: InfoTip's press-to-pin goes
+ * through it, and the package does not export it.
+ */
+export function TooltipWithTriggerBehavior({
children,
anchorRef,
content,
@@ -238,7 +235,7 @@ export function Tooltip({
hasHoverIndication = 'auto',
isOpen,
isDefaultOpen,
-}: TooltipProps): ReactElement {
+}: TooltipWithTriggerBehaviorProps): ReactElement {
const wrapperRef = useRef<HTMLDivElement>(null);
const textOnly = children != null ? isTextOnly(children) : false;
@@ -255,7 +252,7 @@ export function Tooltip({
}, [onOpenChange]);
// Use the hook for all tooltip behavior
- const tooltip = useTooltip({
+ const tooltip = useTooltipWithTriggerBehavior({
placement,
alignment,
delay,
diff --git a/packages/core/src/Tooltip/index.ts b/packages/core/src/Tooltip/index.ts
index 1dcef4e7d8..99d411531f 100644
--- a/packages/core/src/Tooltip/index.ts
+++ b/packages/core/src/Tooltip/index.ts
@@ -15,7 +15,6 @@
export {useTooltip} from './useTooltip';
export type {
TooltipFocusTrigger,
- TooltipTriggerBehavior,
TooltipTouchTrigger,
TooltipOptions,
TooltipReturn,
diff --git a/packages/core/src/Tooltip/useTooltip.doc.mjs b/packages/core/src/Tooltip/useTooltip.doc.mjs
index f6373172bb..e1ece96f65 100644
--- a/packages/core/src/Tooltip/useTooltip.doc.mjs
+++ b/packages/core/src/Tooltip/useTooltip.doc.mjs
@@ -7,33 +7,129 @@ export const docs = {
group: 'Tooltip',
keywords: ['tooltip', 'hint', 'label', 'hover', 'info', 'title', 'floating'],
params: [
- {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
- {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
- {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
- {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
- {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.', default: "'auto'"},
- {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch. It decides only under triggerBehavior="adaptive", the default.', default: "'auto'"},
- {name: 'triggerBehavior', type: "'adaptive' | 'hover' | 'toggle'", description: 'How the trigger opens the tooltip. adaptive (the default) previews on hover and focus and opens on a tap unless the trigger acts (touchTrigger decides while it remains); hover previews on hover and focus, and no touch or pen tap opens it; toggle, on a button trigger, pins on a click, a tap, Enter, or Space and closes on the same press, Escape, a press outside, or focus leaving. The trigger carries aria-expanded and aria-controls, the tooltip is announced once when it pins. Astryx clickable rows and cards ignore the pinning press, except an Item row on a trigger that is not a native button; a plain onClick ancestor still receives it from the hook (the Tooltip component stops it at a child trigger).', default: "'adaptive'"},
- {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
- {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
- {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},
- {name: 'onShow', type: '() => void', description: 'Callback fired when the tooltip becomes visible.'},
- {name: 'onHide', type: '() => void', description: 'Callback fired when the tooltip is hidden.'},
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description:
+ "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+ default: "'above'",
+ },
+ {
+ name: 'alignment',
+ type: "'start' | 'center' | 'end'",
+ description:
+ "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+ default: "'center'",
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Delay before showing on hover, in milliseconds.',
+ default: '200',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description:
+ 'Delay before hiding after mouse or focus leaves, in milliseconds.',
+ default: '0',
+ },
+ {
+ name: 'focusTrigger',
+ type: "'auto' | 'always' | 'never'",
+ description:
+ 'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
+ default: "'auto'",
+ },
+ {
+ name: 'touchTrigger',
+ type: "'auto' | 'tap' | 'none'",
+ description:
+ 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (a button whose only job is revealing the tooltip); none never opens on touch.',
+ default: "'auto'",
+ },
+ {
+ name: 'isEnabled',
+ type: 'boolean',
+ description: 'Whether hover and focus triggers are enabled.',
+ default: 'true',
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description:
+ 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+ },
+ {
+ name: 'isDefaultOpen',
+ type: 'boolean',
+ description: 'Whether the tooltip should be shown on mount.',
+ default: 'false',
+ },
+ {
+ name: 'onShow',
+ type: '() => void',
+ description: 'Callback fired when the tooltip becomes visible.',
+ },
+ {
+ name: 'onHide',
+ type: '() => void',
+ description: 'Callback fired when the tooltip is hidden.',
+ },
],
returns: [
- {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
- {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element.'},
- {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element.'},
- {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
- {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
- {name: 'renderTooltip', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.'},
+ {
+ name: 'ref',
+ type: 'RefCallback<HTMLElement>',
+ description:
+ 'Combined ref that sets both position and interaction on the same trigger element.',
+ },
+ {
+ name: 'positionRef',
+ type: 'RefCallback<HTMLElement>',
+ description: 'Ref for the positioning anchor element.',
+ },
+ {
+ name: 'interactionRef',
+ type: 'RefCallback<HTMLElement>',
+ description: 'Ref for the hover/focus interaction element.',
+ },
+ {
+ name: 'anchorId',
+ type: 'string',
+ description: 'CSS anchor name for advanced positioning cases.',
+ },
+ {
+ name: 'describedBy',
+ type: 'string',
+ description: 'ID to compose into aria-describedby on the trigger.',
+ },
+ {
+ name: 'renderTooltip',
+ type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
+ description:
+ 'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.',
+ },
],
usage: {
- description: 'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
+ description:
+ 'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
bestPractices: [
- {guidance: true, description: 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.'},
- {guidance: true, description: 'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.'},
- {guidance: false, description: 'Put interactive content inside tooltips: use Popover or HoverCard instead.'},
+ {
+ guidance: true,
+ description:
+ 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Put interactive content inside tooltips: use Popover or HoverCard instead.',
+ },
],
},
relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -44,17 +140,22 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
- description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+ description:
+ 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
paramDescriptions: {
- placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
- alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+ placement:
+ "position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
+ alignment:
+ "alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
delay: 'show delay in ms.',
hideDelay: 'hide delay after mouse/focus leave in ms.',
- focusTrigger: 'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
- touchTrigger: 'tap behavior with no hover, under triggerBehavior adaptive only; auto = tap unless trigger acts, tap = always, none = never.',
- triggerBehavior: 'adaptive (default) = hover/focus preview, tap opens unless the trigger acts; hover = no touch/pen tap opens; toggle = a press on a button trigger pins and closes; clickable rows and cards ignore it (an Item row only on a native-button trigger), and the Tooltip component also stops it at a child trigger.',
+ focusTrigger:
+ 'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
+ touchTrigger:
+ 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
isEnabled: 'whether hover/focus triggers are enabled.',
- isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+ isOpen:
+ 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
isDefaultOpen: 'show on mount.',
onShow: 'fires when tooltip becomes visible.',
onHide: 'fires when tooltip hides.',
@@ -68,11 +169,24 @@ export const docsDense = {
renderTooltip: 'renders anchor-positioned tooltip content.',
},
usage: {
- description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+ description:
+ 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
bestPractices: [
- {guidance: true, description: 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.'},
- {guidance: true, description: 'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.'},
- {guidance: false, description: 'Put interactive content in tooltips: use Popover / HoverCard instead.'},
+ {
+ guidance: true,
+ description:
+ 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Put interactive content in tooltips: use Popover / HoverCard instead.',
+ },
],
},
};
diff --git a/packages/core/src/Tooltip/useTooltip.test.tsx b/packages/core/src/Tooltip/useTooltip.test.tsx
index 506f8adf68..228afbc901 100644
--- a/packages/core/src/Tooltip/useTooltip.test.tsx
+++ b/packages/core/src/Tooltip/useTooltip.test.tsx
@@ -4,7 +4,7 @@
* @file useTooltip.test.tsx
* @input Uses vitest, @testing-library/react, useTooltip hook
* @output Unit tests for the tooltip show/hide timers and controlled state,
- * and for a press on a caller's trigger under `triggerBehavior="toggle"`
+ * and for a press on a caller's trigger through the press-to-pin path
* @position Testing; validates useTooltip.tsx timing contract. Component-level
* behavior lives in Tooltip.test.tsx — this file pins the delays, the
* hover-bridge constant, and timer teardown, which are invisible from there.
@@ -23,7 +23,11 @@ import {
afterEach,
} from 'vitest';
import {render, screen, fireEvent, act} from '@testing-library/react';
-import {useTooltip, type TooltipOptions} from './useTooltip';
+import {
+ useTooltip,
+ useTooltipWithTriggerBehavior,
+ type TooltipOptions,
+} from './useTooltip';
import {useLayer} from '../Layer/useLayer';
import {ClickableCard} from '../ClickableCard/ClickableCard';
import type {MouseEvent as ReactMouseEvent} from 'react';
@@ -599,13 +603,16 @@ describe('useTooltip — focusTrigger="auto" decides when focus arrives', () =>
});
});
-describe('useTooltip with a caller’s trigger under triggerBehavior="toggle" (component:Tooltip FR9)', () => {
+describe('useTooltip’s press-to-pin path with a caller’s trigger (component:Tooltip FR9)', () => {
function Tip({
onTriggerClick,
}: {
onTriggerClick?: (event: ReactMouseEvent) => void;
}) {
- const tooltip = useTooltip({triggerBehavior: 'toggle', delay: 0});
+ const tooltip = useTooltipWithTriggerBehavior({
+ triggerBehavior: 'toggle',
+ delay: 0,
+ });
return (
<>
<button type="button" ref={tooltip.ref} onClick={onTriggerClick}>
@@ -655,3 +662,27 @@ describe('useTooltip with a caller’s trigger under triggerBehavior="toggle" (c
expect(onRow).not.toHaveBeenCalled();
});
});
+
+describe('useTooltip keeps press-to-pin internal', () => {
+ it('an options object that carries triggerBehavior at runtime pins nothing', () => {
+ const options = {
+ triggerBehavior: 'toggle',
+ delay: 0,
+ } as unknown as TooltipOptions;
+ function Tip() {
+ const tooltip = useTooltip(options);
+ return (
+ <>
+ <button type="button" ref={tooltip.ref}>
+ What is this?
+ </button>
+ {tooltip.renderTooltip('Billed monthly')}
+ </>
+ );
+ }
+ render(<Tip />);
+ const trigger = screen.getByRole('button', {name: 'What is this?'});
+ fireEvent.click(trigger, {detail: 1});
+ expect(trigger).not.toHaveAttribute('aria-expanded');
+ });
+});
diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx
index 589a037d60..1805903c9b 100644
--- a/packages/core/src/Tooltip/useTooltip.tsx
+++ b/packages/core/src/Tooltip/useTooltip.tsx
@@ -5,7 +5,8 @@
/**
* @file useTooltip.tsx
* @input Uses useLayer, usePressPin, React hooks
- * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips,
+ * and the module-only useTooltipWithTriggerBehavior that InfoTip's press-to-pin uses
* @position Layer hook; builds on useLayer for tooltip behavior
*
* SYNC: When modified, update:
@@ -31,7 +32,7 @@ import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {registerLayerSurface} from '../Layer/layerSurfacePress';
-import {usePressPin} from '../Layer/usePressPin';
+import {usePressPin, type LayerTriggerBehavior} from '../Layer/usePressPin';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {themeProps} from '../utils/themeProps';
import {
@@ -83,14 +84,6 @@ export type TooltipFocusTrigger = 'auto' | 'always' | 'never';
*/
export type TooltipTouchTrigger = LayerTouchTrigger;
-/**
- * How the trigger opens the tooltip. `adaptive`, the default, previews it on
- * hover and focus, and a tap opens it unless the trigger acts. `hover`
- * previews it on hover and focus, and no touch or pen tap opens it. `toggle`
- * pins it on a click, tap, Enter, or Space on a button trigger.
- */
-export type TooltipTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
-
export interface TooltipOptions {
/**
* Position placement relative to anchor
@@ -135,32 +128,10 @@ export interface TooltipOptions {
* - `tap`: tap always opens the tooltip, even on a trigger that acts
* - `none`: touch never opens the tooltip
*
- * It decides only under `triggerBehavior="adaptive"`, the default.
- *
* @default 'auto'
*/
touchTrigger?: TooltipTouchTrigger;
- /**
- * How the trigger opens the tooltip:
- * - `adaptive` (the default): hover and focus preview it. A tap opens it
- * unless the trigger performs an action of its own. While `touchTrigger`
- * remains, it decides those taps.
- * - `hover`: hover and focus preview it; no touch or pen tap opens it.
- * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
- * tooltip open, and the same press closes it. Hover and keyboard focus
- * still preview it. A pinned tooltip stays until Escape, a second press,
- * a press outside, or focus leaving. Astryx clickable rows and cards
- * ignore the pinning press, except an Item row on a trigger that is not
- * a native button. The `Tooltip` component also stops it at a child
- * trigger. A hook caller stops a plain `onClick` ancestor itself. The
- * trigger reports `aria-expanded` and `aria-controls`, and the tooltip's
- * text is announced once when it pins. `touchTrigger` is ignored.
- *
- * @default 'adaptive'
- */
- triggerBehavior?: TooltipTriggerBehavior;
-
/**
* Whether the tooltip is enabled.
* When false, hover/focus triggers are disabled.
@@ -296,6 +267,42 @@ function isFocusable(element: HTMLElement): boolean {
*/
export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
+ // The option is fixed to `adaptive`, so an options object that carries it at
+ // runtime cannot reach the press-to-pin path.
+ return useTooltipWithTriggerBehavior({
+ ...options,
+ triggerBehavior: 'adaptive',
+ });
+}
+
+/**
+ * Module-only options for `useTooltipWithTriggerBehavior`. Not exported from
+ * the package.
+ */
+export interface TooltipWithTriggerBehaviorOptions extends TooltipOptions {
+ /**
+ * How the trigger opens the tooltip:
+ * - `adaptive` (the default): hover and focus preview it. `touchTrigger`
+ * decides taps.
+ * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
+ * tooltip open, and the same press closes it. Hover and keyboard focus
+ * still preview it. A pinned tooltip stays until Escape, a second press,
+ * a press outside, or focus leaving. The trigger reports `aria-expanded`
+ * and `aria-controls`, and the tooltip's text is announced once when it
+ * pins. `touchTrigger` is ignored. InfoTip uses it.
+ *
+ * @default 'adaptive'
+ */
+ triggerBehavior?: LayerTriggerBehavior;
+}
+
+/**
+ * `useTooltip` with a trigger behavior. Module-only: InfoTip's press-to-pin
+ * goes through it, and the package does not export it.
+ */
+export function useTooltipWithTriggerBehavior(
+ options: TooltipWithTriggerBehaviorOptions = {},
+): TooltipReturn {
const {
placement = 'above',
alignment = 'center',
diff --git a/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx b/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx
index 81d7cd056d..7272ea33ea 100644
--- a/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx
+++ b/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx
@@ -68,7 +68,7 @@ const {BaseTypeahead} = await import('../Typeahead/BaseTypeahead');
const {TokenizerWithPresentation} =
await import('../internal/tokenizer-presentation');
const {createStaticSource} = await import('../Typeahead/createStaticSource');
-const {Tooltip} = await import('../Tooltip');
+const {TooltipWithTriggerBehavior} = await import('../Tooltip/Tooltip');
const source = createStaticSource([{id: 'apple', label: 'Apple'}]);
@@ -169,11 +169,11 @@ const ADOPTERS: Record<string, () => Promise<void>> = {
'Tooltip/useTooltip.tsx': async () => {
// A tooltip a press pinned says its own text (component:Tooltip FR10).
render(
- <Tooltip
+ <TooltipWithTriggerBehavior
content="Billed on the first of each month"
triggerBehavior="toggle">
<button type="button">About billing</button>
- </Tooltip>,
+ </TooltipWithTriggerBehavior>,
);
fireEvent.click(screen.getByRole('button', {name: 'About billing'}));
await expectDelegated('Billed on the first of each month');