feat(tooltip)!: port to pf-v6-tooltip

[bennypowers]

Summary

• New pf-v6-tooltip element ported from v5 with v6 design tokens
• FloatingDOMController with arrow element positioning
• Cancellable TooltipShowEvent/TooltipHideEvent with reason enum for selective trigger prevention
• trigger attribute (IDREF) and property (Element ref) for external trigger elements
• entry-delay/exit-delay (default 300ms), alignment (start/end/left/right), position, no-flip, flip-behavior
• light-dark() CSS fallbacks for correct inverse color scheme
• ariaDescribedByElements wiring between trigger and tooltip content
• 9 demos: basic, placement, trigger-ref, trigger-element, slotted-content, dynamic-content, left-aligned, color-scheme, options playground
• 17 unit tests

Test plan

• Verify tooltip shows on hover and focus in all demos
• Verify tooltip hides on mouseleave, focusout, and Escape
• Verify light-dark color scheme inversion in color-scheme demo
• Verify external trigger via IDREF (trigger-ref) and Element ref (trigger-element)
• Verify alignment attribute changes text-align
• Verify entry-delay/exit-delay in options playground
• Verify no-flip disables repositioning
• Run /review-a11y, /review-api, /review-demos
• Visual parity with patternfly.org tooltip

Closes #3048

[changeset-bot]

🦋 Changeset detected

Latest commit: 782a0d3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@patternfly/elements	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

✅ Commitlint tests passed!

More Info

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "input": "feat(tooltip)!: port to `pf-v6-tooltip`"
}

[github-actions]

✅ Deploy Preview for patternfly-elements ready!

Name	Link
🔨 Latest commit	dc44db5
😎 Deploy Preview	https://deploy-preview-3141--patternfly-elements.netlify.app/

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

SSR Test Run for 4e4a328: Report

[github-actions]

SSR Test Run for 6b79b33: Report

[github-actions]

SSR Test Run for d88bd77: Report

[bennypowers]

Cross-root aria-describedby limitation

The tooltip sets ariaDescribedByElements on the trigger to reference the shadow-internal #content div. This is the correct API for cross-root ARIA relationships, but it silently fails in all browsers today: the accessibility tree shows no describedby relationship.

Per the current spec, ARIA element reflection only works when shadow roots are in an ancestor/descendant relationship, and even then only in the shadow-to-light direction. Our use case (light DOM trigger referencing shadow DOM content) goes the wrong way. The WPT test explicitly asserts that cross-root refs produce an empty computed label.

This means tooltip triggers currently have no programmatic describedby relationship in any browser. The tooltip content is still announced when visible (via role="tooltip" and proximity in the accessibility tree), but there is no formal ARIA association.

The Reference Target proposal (Chrome origin trial) would solve the slotted trigger case. The external trigger case (sibling elements) would need the relaxation discussed in WICG/aom#192. Both whatwg/html#5401 and whatwg/html#10707 track the broader spec work.

Keeping the ariaDescribedByElements call as progressive enhancement -- it will start working once browsers ship a solution. No workaround attempted; the alternatives (hidden light DOM spans, aria-label mirroring) add complexity for a temporary gap.

@adamjohnson and @hellogreg -- could you verify the actual screen reader experience here? Want to confirm the tooltip content is still announced via proximity/role="tooltip" even without the formal describedby association.

[zeroedin]

Rename PR feat(tooltip)!: port to pf-v6-tooltip

[bennypowers]

NB: i found no instances of react Tooltip component's minWidth prop in the wild, scanning across 510 repos (160 importing Tooltip). I found one instance of Popover react component's minWidth prop, so I think we're justified in removing it, since there's a (already popularly used) workaround - using minWidth css on the contents.

See generated report below. I don't endorse every recommendation here, this is just for reference.

Tooltip Audit Summary

2296 instances across 105/160 repos | 48 spread usages

Props: PF React vs Actual Usage

Prop	PF React	Used	Count	Recommendation
content	yes	yes	2277 (99%)	Keep - core prop
position	yes	yes	629 (27%)	Keep
children	yes	yes	(implicit)	Keep - trigger slot
triggerRef	yes	yes	125 (5%)	Keep - ref-based trigger
trigger	yes	yes	110 (5%)	Keep (simplified) - mostly mouseenter/click/manual
id	yes	yes	63 (3%)	Native HTML
isContentLeftAligned	yes	yes	59 (3%)	Keep (simplified) - CSS class toggle
enableFlip	yes	yes	56 (2%)	Keep - Popper/Floating UI concern
entryDelay	yes	yes	52 (2%)	Keep
isVisible	yes	yes	40 (2%)	Keep - programmatic control
aria	yes	yes	24 (1%)	Keep (simplified) - describedby/labelledby/none
aria-live	yes	yes	20 (1%)	Keep
maxWidth	yes	yes	21 (1%)	Keep - CSS custom property
appendTo	yes	yes	21 (1%)	Drop candidate - web components handle shadow DOM differently
distance	yes	yes	20 (1%)	Keep - CSS custom property
exitDelay	yes	yes	19 (1%)	Keep
flipBehavior	yes	yes	15 (1%)	Keep (simplified) - Floating UI handles natively
className	yes	yes	28 (1%)	Native HTML - class
animationDuration	yes	yes	8 (<1%)	Keep - CSS custom property
onTooltipHidden	yes	yes	6 (<1%)	Keep - event
hidden	HTML	yes	38 (2%)	Native HTML
removeFindDomNode	yes	yes	7 (<1%)	Drop - React-specific workaround
zIndex	yes	yes	1 (<1%)	Drop candidate - CSS custom property
minWidth	yes	yes	1 (<1%)	Drop candidate - 1 usage across 2296 instances
role	HTML	yes	2 (<1%)	Native HTML
data-testid	HTML	yes	28 (1%)	Native HTML
data-test	HTML	yes	5 (<1%)	Native HTML
aria-label	HTML	yes	30 (1%)	Native HTML

Web Component API Recommendations

Core attributes: content, position, trigger, distance, entry-delay, exit-delay, max-width, animation-duration, enable-flip

Boolean attributes: content-left-aligned, visible, no-flip (invert of enableFlip)

Events: pf-hidden (replaces onTooltipHidden)

Drop: minWidth, zIndex, removeFindDomNode, appendTo, flipBehavior (Floating UI handles). All handleable via CSS custom properties or Floating UI defaults.

48 spread usages may pass unlisted props -- worth spot-checking those repos.

[github-actions]

SSR Test Run for 2ddb73a: Report

[github-actions]

SSR Test Run for 1f120c6: Report

[github-actions]

SSR Test Run for 60c1a86: Report

[adamjohnson]

@adamjohnson and @hellogreg -- could you verify the actual screen reader experience here? Want to confirm the tooltip content is still announced via proximity/role="tooltip" even without the formal describedby association.

I can confirm from manual testing that the tooltip content is still available without describedby, but SR announcement today depends on the live-region workaround, not role="tooltip" alone.

I pushed some docs changes to further note/document the limitations of ariaDescribedByElements lightdom -> shadowdom and how we work around that with the announcer (role="status"). Added some tests around this as well.

[github-actions]

SSR Test Run for 75dfc7f: Report

[github-actions]

SSR Test Run for dc44db5: Report

[hellogreg]

Checked the demos with the usual screen reader suspects. Two notes:

The click trigger demo tooltip displays on keyboard focus, not just on click. The Windows screen readers read the tooltip content when this happens. Mac VoiceOver does not read the tooltip content in this demo ever--neither on click nor on focus.

The manual trigger demo reads the tooltip when the trigger checkbox is checked, but does not also read it when the button associated with the tooltip receives focus. Not sure if this is intended or not, but thought I'd point it out.