diff --git a/.changeset/keen-newts-fly.md b/.changeset/keen-newts-fly.md new file mode 100644 index 0000000000..ee7837302f --- /dev/null +++ b/.changeset/keen-newts-fly.md @@ -0,0 +1,26 @@ +--- +"@patternfly/elements": major +--- + +Added `` replacing ``. Tooltip now follows +PatternFly v6 design specs. + +```html + + + +``` + +**Breaking changes from v5:** + +- Tag name changed from `pf-v5-tooltip` to `pf-v6-tooltip` +- `visible` attribute replaces programmatic-only visibility +- `entry-delay` and `exit-delay` attributes added (300ms default) +- `alignment` attribute replaces `isContentLeftAligned` (accepts `start`/`end`) +- `no-flip` inverted boolean replaces `enableFlip` +- `content` slot added for rich HTML content +- Cancelable `show`/`hide` events with `reason` property +- `silent` attribute for suppressing screen reader announcements +- CSS custom properties replace inline style props (`maxWidth`, etc.) + +Users who need the react component's `trigger` prop are advised to use `` instead, or to use the cancellable `show`/`hide` events to prevent default behaviour. diff --git a/.claude/ADVICE.md b/.claude/ADVICE.md index 1fbe778d51..f31ecf4a41 100644 --- a/.claude/ADVICE.md +++ b/.claude/ADVICE.md @@ -641,8 +641,13 @@ Icons are decorative or informational, not interactive. Click handlers belong on > "You must not add click listeners to icons." (PFE PR #2951) +### Use a static live-region announcer for tooltip/popover content +Tooltip and popover content lives in shadow DOM, which prevents `aria-describedby` from working cross-root. Use a shared static `role="status"` announcer element (visually hidden, appended to `document.body`) to announce content to screen readers. Announce on show, clear on hide. Provide a `silent` boolean attribute to opt out when authors provide their own accessible label. + +> Pattern established in `rh-tooltip` (RHDS): static `initAnnouncer()` + `announce(text)` in `show()`, clear in `hide()`. Adopted in `pf-v6-tooltip` (PFE). + ### Consider cross-root ARIA limitations -When composing elements across shadow boundaries, cross-root ARIA references don't work declaratively yet. This may require duplicating internal elements as a workaround. Client-side, ARIA IDL DOM properties (baseline 2025) can resolve cross-root references imperatively via JavaScript. Upcoming APIs like Reference Target will provide declarative solutions. +When composing elements across shadow boundaries, cross-root ARIA references don't work declaratively yet. `ariaDescribedByElements` and similar IDL properties silently fail for light-to-shadow references. The [WPT test](https://github.com/web-platform-tests/wpt/blob/master/custom-elements/element-internals-aria-element-reflection.html) explicitly asserts cross-root refs produce an empty computed label. See also [WICG/aom#192](https://github.com/WICG/aom/issues/192) and [whatwg/html#5401](https://github.com/whatwg/html/issues/5401). Upcoming APIs like Reference Target ([WICG/webcomponents#1086](https://github.com/WICG/webcomponents/issues/1086)) will provide solutions. Keep cross-root IDL assignments as progressive enhancement. > "We can't use pf-button until browser vendors ship a solution for x-root aria." (PFE PR #2676) diff --git a/docs/framework-integration/react.md b/docs/framework-integration/react.md index 20f8185666..52b146f474 100644 --- a/docs/framework-integration/react.md +++ b/docs/framework-integration/react.md @@ -132,7 +132,7 @@ tags: import { Card } from "@patternfly/elements/react/pf-v5-card/pf-v5-card.js"; import { Switch } from "@patternfly/elements/react/pf-v6-switch/pf-v6-switch.js"; import { Popover } from "@patternfly/elements/react/pf-v5-popover/pf-v5-popover.js"; - import { Tooltip } from "@patternfly/elements/react/pf-v5-tooltip/pf-v5-tooltip.js"; + import { Tooltip } from "@patternfly/elements/react/pf-v6-tooltip/pf-v6-tooltip.js"; import "./App.css"; ``` @@ -208,7 +208,7 @@ tags: ### Tooltip Now we have a card, button, and switch component, let's add - [`pf-v5-tooltip`][pf-v5-tooltip] web component in our app. We will show the tooltip + [`pf-v6-tooltip`][pf-v6-tooltip] web component in our app. We will show the tooltip text on mouseover. ```js @@ -356,7 +356,7 @@ tags: [pf-v5-button]: https://patternflyelements.org/components/button/ [pf-v5-card]: https://patternflyelements.org/components/card/ [pf-v6-switch]: https://patternflyelements.org/components/switch/ -[pf-v5-tooltip]: https://patternflyelements.org/components/tooltip/ +[pf-v6-tooltip]: https://patternflyelements.org/components/tooltip/ [pf-v5-popover]: https://patternflyelements.org/components/popover/ [inng]: https://medium.com/patternfly-elements/using-patternfly-elements-web-components-in-your-angular-app-4b18b1c9c363 [invue]: https://patternflyelements.org/framework-integration/vue/ diff --git a/elements/pf-v5-chip/demo/long-chip-with-tooltip.html b/elements/pf-v5-chip/demo/long-chip-with-tooltip.html index 03ebabe000..9c1c49331e 100644 --- a/elements/pf-v5-chip/demo/long-chip-with-tooltip.html +++ b/elements/pf-v5-chip/demo/long-chip-with-tooltip.html @@ -1,7 +1,7 @@ - + Really long chip that goes on and on Really long chip that goes on and on - + diff --git a/elements/pf-v5-tooltip/demo/custom-styles.html b/elements/pf-v5-tooltip/demo/custom-styles.html deleted file mode 100644 index fb085c2edc..0000000000 --- a/elements/pf-v5-tooltip/demo/custom-styles.html +++ /dev/null @@ -1,60 +0,0 @@ -
-

Toggle Container Width

- - - -
- -
-

Tooltips can be styled using CSS custom properties. For example, a tooltip may have - - custom text color - , - - a custom shadow - , or - - custom content padding - . -

-
- - - - diff --git a/elements/pf-v5-tooltip/demo/flip.html b/elements/pf-v5-tooltip/demo/flip.html deleted file mode 100644 index 7350a12512..0000000000 --- a/elements/pf-v5-tooltip/demo/flip.html +++ /dev/null @@ -1,95 +0,0 @@ -
- - Tooltip! - - - -
Flip fallback
-
- -
- - Tooltip! - -
No flip
-
- - - - - diff --git a/elements/pf-v5-tooltip/demo/index.html b/elements/pf-v5-tooltip/demo/index.html deleted file mode 100644 index c1c58858f5..0000000000 --- a/elements/pf-v5-tooltip/demo/index.html +++ /dev/null @@ -1,37 +0,0 @@ -
-

Toggle Container Width

- - - -
- -
-

- A Tooltip - is a piece of flow content with an associated secondary piece of hidden flow content. - Tooltips which wrap non-interactive content must have a tabindex of 0. -

-
- - - - diff --git a/elements/pf-v5-tooltip/demo/performance.html b/elements/pf-v5-tooltip/demo/performance.html deleted file mode 100644 index 40d8734e1d..0000000000 --- a/elements/pf-v5-tooltip/demo/performance.html +++ /dev/null @@ -1,63 +0,0 @@ -
-

Performance

-

This demo measures the time needed to render 10000 tooltip elements then toggle the first tooltip.

-
- Render - Reset - -
-
-
- - - - diff --git a/elements/pf-v5-tooltip/demo/placement.html b/elements/pf-v5-tooltip/demo/placement.html deleted file mode 100644 index ff72f0ad07..0000000000 --- a/elements/pf-v5-tooltip/demo/placement.html +++ /dev/null @@ -1,70 +0,0 @@ -
-

Toggle Container Width

- - - -
- -
-

- Tooltips can be anchored to the left: - Left, - Left Start, - Left End. - They can be anchored to the right: - Right, - Right Start, - Right End. - They can be anchored to the top: - Top, - Top Start, - Top End. - They can be anchored to the bottom: - Bottom, - Bottom Start, - Bottom End. -

-

- Tooltips can have content which wraps lines, but this is discouraged, - because tooltips are meant to contain as little content as possible. - When tooltips have lengthy content anchored to the left, it looks like this: - Left, - Left Start, - Left End. - When tooltips have lengthy content anchored to the right, it looks like this: - Right, - Right Start, - Right End. - When tooltips have lengthy content anchored to the top, it looks like this: - Top, - Top Start, - Top End. - When tooltips have lengthy content anchored to the bottom, it looks like this: - Bottom, - Bottom Start, - Bottom End. -

-
- - - - diff --git a/elements/pf-v5-tooltip/demo/slotted-content.html b/elements/pf-v5-tooltip/demo/slotted-content.html deleted file mode 100644 index cf93206d22..0000000000 --- a/elements/pf-v5-tooltip/demo/slotted-content.html +++ /dev/null @@ -1,42 +0,0 @@ -
-

Toggle Container Width

- - - -
- -
-

A tooltip may contain - - HTML content - - Slotted content can be formatted, using HTML - tags like em, strong, or code. - - by using the content slot. - Slotted content must be phrasing content, so no <p>s. -

-
- - - - diff --git a/elements/pf-v5-tooltip/demo/trigger.html b/elements/pf-v5-tooltip/demo/trigger.html deleted file mode 100644 index c5ae928272..0000000000 --- a/elements/pf-v5-tooltip/demo/trigger.html +++ /dev/null @@ -1,15 +0,0 @@ -
- - Button -
- - - - diff --git a/elements/pf-v5-tooltip/docs/CHANGELOG.old.md b/elements/pf-v5-tooltip/docs/CHANGELOG.old.md deleted file mode 100644 index 845280705c..0000000000 --- a/elements/pf-v5-tooltip/docs/CHANGELOG.old.md +++ /dev/null @@ -1,125 +0,0 @@ -# @patternfly/pfe-tooltip - -## 2.0.0-next.9 - -### Patch Changes - -- 457eaa9d0: `pfe-tools`: Set typescript compilerOptions `composite: true` - - `pfe-tooltip`: Added return type for anonymous function for content in constructor - -- Updated dependencies [82da44c11] - - @patternfly/pfe-core@2.0.0-next.14 - -## 2.0.0-next.8 - -### Major Changes - -- b841afe40: ``: - - - updated `FloatingDOMController` - - removed `offset` attribute - - added `content` attribute - - simplified DOM and CSS - -### Patch Changes - -- Updated dependencies [b841afe40] -- Updated dependencies [0fe6c52db] -- Updated dependencies [0fe6c52db] - - @patternfly/pfe-core@2.0.0-next.13 - -## 1.1.0-next.7 - -### Patch Changes - -- b51b551f: Use `NumberListConverter` from pfe-core -- Updated dependencies [6b6e2617] - - @patternfly/pfe-core@2.0.0-next.12 - -## 1.1.0-next.6 - -### Minor Changes - -- daba8a53: Adds styles to slotted timestamps. - - ```html - - - Last updated on - - - - - ``` - -## 1.1.0-next.5 - -### Patch Changes - -- 07ad1d3d: Updates use of `` -- Updated dependencies [07ad1d3d] - - @patternfly/pfe-core@2.0.0-next.10 - -## 1.1.0-next.4 - -### Minor Changes - -- 166ecee1: Improves performance of floating DOM (tooltip) by lazily initializing - -### Patch Changes - -- 0b90b899: Null check in tooltip's `show()` method -- Updated dependencies [166ecee1] - - @patternfly/pfe-core@2.0.0-next.9 - -## 1.1.0-next.3 - -### Patch Changes - -- bfad8b4b: Updates dependencies -- Updated dependencies [bfad8b4b] - - @patternfly/pfe-core@2.0.0-next.8 - -## 1.1.0-next.2 - -### Patch Changes - -- f25258e9: Updating the README.md, fixing an scss variable found in pfe-tooltip for the background color. - -## 1.1.0-next.1 - -### Patch Changes - -- b5fe1d3e: Use popper version from pfe-core - -## 1.1.0-next.0 - -### Minor Changes - -- 7c9b85cc: Adding `pfe-tooltip` - - ```html - - - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Mi eget mauris - pharetra et ultrices. - - ``` - -### Patch Changes - -- Updated dependencies [7c9b85cc] - - @patternfly/pfe-core@2.0.0-next.7 diff --git a/elements/pf-v5-tooltip/docs/pf-v5-tooltip.md b/elements/pf-v5-tooltip/docs/pf-v5-tooltip.md deleted file mode 100644 index 2688f24a4b..0000000000 --- a/elements/pf-v5-tooltip/docs/pf-v5-tooltip.md +++ /dev/null @@ -1,106 +0,0 @@ -{% renderInstallation %} {% endrenderInstallation %} - -{% renderOverview %} - ### Default - - Tooltip - -{% endrenderOverview %} - -{% band header="Usage" %} - ### Left Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Left-Start Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Left-End Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Right Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Right-Start Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Right-End Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Top Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Top-Start Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Top-End Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Bottom Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Bottom-Start Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} - - ### Bottom-End Tooltip - {% htmlexample %} - - Tooltip - - {% endhtmlexample %} -{% endband %} - -{% renderSlots %}{% endrenderSlots %} - -{% renderAttributes %}{% endrenderAttributes %} - -{% renderMethods %}{% endrenderMethods %} - -{% renderEvents %}{% endrenderEvents %} - -{% renderCssCustomProperties %}{% endrenderCssCustomProperties %} - -{% renderCssParts %}{% endrenderCssParts %} diff --git a/elements/pf-v5-tooltip/docs/screenshot.png b/elements/pf-v5-tooltip/docs/screenshot.png deleted file mode 100644 index 54986c4291..0000000000 Binary files a/elements/pf-v5-tooltip/docs/screenshot.png and /dev/null differ diff --git a/elements/pf-v5-tooltip/pf-v5-tooltip.css b/elements/pf-v5-tooltip/pf-v5-tooltip.css deleted file mode 100644 index 7fe60ddfdc..0000000000 --- a/elements/pf-v5-tooltip/pf-v5-tooltip.css +++ /dev/null @@ -1,108 +0,0 @@ -:host { - --_timestamp-text-decoration: underline dashed 1px; - --_timestamp-text-underline-offset: 4px; - display: inline; -} - -* { box-sizing: border-box; } - -#container { - display: inline-flex; - position: relative; - max-width: 100%; - /** Tooltip arrow width */ - --_floating-arrow-size: var(--pf-v5-c-tooltip__arrow--Width, 0.5rem); -} - -#tooltip, -#tooltip::after { - position: absolute; -} - -#tooltip { - --_timestamp-text-decoration: none; - --_timestamp-text-underline-offset: initial; - user-select: none; - display: block; - opacity: 0; - pointer-events: none; - z-index: 10000; - transition: opacity 300ms cubic-bezier(0.54, 1.5, 0.38, 1.11) 0s; - text-align: center; - word-break: break-word; - translate: var(--_floating-content-translate); - max-width: calc(100vw - 10px); - width: max-content; - top: 0; - left: 0; - will-change: opacity; - /** Sets the font color for the tooltip content */ - line-height: var(--pf-v5-c-tooltip--line-height, 1.5); - /** Maximum width for the tooltip */ - max-width: var(--pf-v5-c-tooltip--MaxWidth, 18.75rem); - /** Box shadow for the tooltip */ - box-shadow: var(--pf-v5-c-tooltip--BoxShadow, - var(--pf-global--BoxShadow--md, - 0 0.25rem 0.5rem 0rem rgba(3, 3, 3, 0.12), - 0 0 0.25rem 0 rgba(3, 3, 3, 0.06))); - /** Tooltip padding (top, right, bottom, left) */ - padding: - var(--pf-v5-c-tooltip__content--PaddingTop, - var(--pf-global--spacer--sm, 0.5rem)) - var(--pf-v5-c-tooltip__content--PaddingRight, - var(--pf-global--spacer--sm, 0.5rem)) - var(--pf-v5-c-tooltip__content--PaddingBottom, - var(--pf-global--spacer--sm, 0.5rem)) - var(--pf-v5-c-tooltip__content--PaddingLeft, - var(--pf-global--spacer--sm, 0.5rem)); - /** Font size for the tooltip content */ - font-size: var(--pf-v5-c-tooltip__content--FontSize, - var(--pf-global--FontSize--sm, 0.875rem)); - /** Sets the font color for the tooltip content */ - color: var(--pf-v5-c-tooltip__content--Color, - var(--pf-global--Color--light-100, #ffffff)); - /** Sets the background color for the tooltip content */ - background-color: var(--pf-v5-c-tooltip__content--BackgroundColor, - var(--pf-global--BackgroundColor--dark-100, #151515)); -} - -#tooltip::after { - display: block; - content: ''; - rotate: 45deg; - width: var(--_floating-arrow-size); - height: var(--_floating-arrow-size); - will-change: left top right bottom; - background-color: var(--pf-v5-c-tooltip__content--BackgroundColor, - var(--pf-global--BackgroundColor--dark-100, #151515)); -} - -.open #tooltip { - opacity: 1; - user-select: initial; -} - -/* LEFT */ -.left #tooltip::after { right: calc(-0.5 * var(--_floating-arrow-size)); } -.left.center #tooltip::after { top: calc(50% - 0.5 * var(--_floating-arrow-size)); } -.left.start #tooltip::after { top: var(--_floating-arrow-size); } -.left.end #tooltip::after { bottom: var(--_floating-arrow-size); } - -/* TOP */ -.top #tooltip::after { top: calc(100% - 0.5 * var(--_floating-arrow-size)); } -.top.center #tooltip::after { right: calc(50% - 0.5 * var(--_floating-arrow-size)); } -.top.start #tooltip::after { left: var(--_floating-arrow-size); } -.top.end #tooltip::after { right: var(--_floating-arrow-size); } - -/* RIGHT */ -.right #tooltip::after { right: calc(100% - 0.5 * var(--_floating-arrow-size)); } -.right.center #tooltip::after { top: calc(50% - 0.5 * var(--_floating-arrow-size)); } -.right.start #tooltip::after { top: var(--_floating-arrow-size); } -.right.end #tooltip::after { bottom: var(--_floating-arrow-size); } - -/* BOTTOM */ -.bottom #tooltip::after { bottom: calc(100% - 0.5 * var(--_floating-arrow-size)); } -.bottom.center #tooltip::after { right: calc(50% - 0.5 * var(--_floating-arrow-size)); } -.bottom.start #tooltip::after { left: var(--_floating-arrow-size); } -.bottom.end #tooltip::after { right: var(--_floating-arrow-size); } - diff --git a/elements/pf-v5-tooltip/pf-v5-tooltip.ts b/elements/pf-v5-tooltip/pf-v5-tooltip.ts deleted file mode 100644 index 12f1682dba..0000000000 --- a/elements/pf-v5-tooltip/pf-v5-tooltip.ts +++ /dev/null @@ -1,184 +0,0 @@ -import type { PropertyValues, TemplateResult } from 'lit'; -import { LitElement, html, isServer } from 'lit'; -import { customElement } from 'lit/decorators/custom-element.js'; -import { property } from 'lit/decorators/property.js'; -import { styleMap } from 'lit/directives/style-map.js'; -import { classMap } from 'lit/directives/class-map.js'; - -import { - FloatingDOMController, - type Placement, -} from '@patternfly/pfe-core/controllers/floating-dom-controller.js'; - -import { bound } from '@patternfly/pfe-core/decorators/bound.js'; - -import { StringListConverter } from '@patternfly/pfe-core'; - -import styles from './pf-v5-tooltip.css'; - -const EnterEvents = ['focusin', 'tap', 'click', 'mouseenter']; -const ExitEvents = ['focusout', 'blur', 'mouseleave']; - -/** - * A **tooltip** is in-app messaging used to identify elements on a page with short, - * clarifying text. - * @summary Toggle the visibility of helpful or contextual information. - * @alias Tooltip - */ -@customElement('pf-v5-tooltip') -export class PfV5Tooltip extends LitElement { - static readonly styles: CSSStyleSheet[] = [styles]; - - /** The position of the tooltip, relative to the invoking content */ - @property() position: Placement = 'top'; - - /** Tooltip content. Overridden by the content slot */ - @property() content?: string; - - /** If false, prevents the tooltip from trying to remain in view by flipping itself when necessary */ - @property({ type: Boolean, attribute: 'no-flip' }) noFlip = false; - - @property() trigger?: string | Element; - - /** - * The flip order when flip is enabled and the initial position is not possible. - * There are 12 options: `top`, `bottom`, `left`, `right`, `top-start`, `top-end`, - * `bottom-start`, `bottom-end`, `left-start`, `left-end`,`right-start`, `right-end`. - * The default is [oppositePlacement], where only the opposite placement is tried. - */ - @property({ - attribute: 'flip-behavior', - converter: StringListConverter, - }) flipBehavior?: Placement[]; - - get #invoker(): HTMLSlotElement | null { - return this.shadowRoot?.querySelector?.('#invoker') ?? null; - } - - get #content(): HTMLElement | null { - return this.shadowRoot?.querySelector?.('#tooltip') ?? null; - } - - #referenceTrigger?: HTMLElement | null; - - #float = new FloatingDOMController(this, { - content: (): HTMLElement | null | undefined => this.#content, - invoker: (): HTMLElement | null | undefined => { - if (this.#referenceTrigger) { - return this.#referenceTrigger; - } else if (this.#invoker instanceof HTMLSlotElement - && this.#invoker.assignedElements().length > 0) { - return this.#invoker.assignedElements().at(0) as HTMLElement; - } else { - return this.#invoker; - } - }, - }); - - override connectedCallback(): void { - super.connectedCallback(); - this.#invokerChanged(); - this.#updateTrigger(); - } - - /** - * Removes event listeners from the old trigger element and attaches - * them to the new trigger element. - * @param changed changed properties - */ - override willUpdate(changed: PropertyValues): void { - if (changed.has('trigger')) { - this.#updateTrigger(); - } - } - - override render(): TemplateResult<1> { - const { alignment, anchor, open, styles } = this.#float; - - const blockInvoker = - this.#invoker?.assignedElements().length === 0 - && this.#invoker?.assignedNodes().length > 0; - const display = blockInvoker ? 'block' : 'contents'; - - return html` -
-
- - -
-
- - ${this.content} -
-
- `; - } - - /** the invoker slot should render at block level if it only has text nodes */ - #invokerChanged() { - this.requestUpdate(); - } - - #getReferenceTrigger() { - return (this.getRootNode() as Document | ShadowRoot) - .getElementById(this.trigger?.normalize() ?? ''); - } - - #updateTrigger() { - if (!isServer) { - const oldReferenceTrigger = this.#referenceTrigger; - this.#referenceTrigger = - this.trigger instanceof HTMLElement ? this.trigger - : typeof this.trigger === 'string' ? this.#getReferenceTrigger() - : null; - for (const evt of EnterEvents) { - if (this.#referenceTrigger) { - this.removeEventListener(evt, this.show); - this.#referenceTrigger.addEventListener(evt, this.show); - } else { - oldReferenceTrigger?.removeEventListener(evt, this.show); - this.addEventListener(evt, this.show); - } - } - for (const evt of ExitEvents) { - if (this.#referenceTrigger) { - this.removeEventListener(evt, this.hide); - this.#referenceTrigger.addEventListener(evt, this.hide); - } else { - oldReferenceTrigger?.removeEventListener(evt, this.hide); - this.addEventListener(evt, this.hide); - } - } - } - } - - @bound async show(): Promise { - await this.updateComplete; - const placement = this.position; - const offset = - !placement?.match(/top|bottom/) ? 15 - : { mainAxis: 15, alignmentAxis: -4 }; - await this.#float.show({ - offset, - placement, - flip: !this.noFlip, - fallbackPlacements: this.flipBehavior, - }); - } - - @bound async hide(): Promise { - await this.#float.hide(); - } -} - -declare global { - interface HTMLElementTagNameMap { - 'pf-v5-tooltip': PfV5Tooltip; - } -} diff --git a/elements/pf-v5-tooltip/test/pf-tooltip.e2e.ts b/elements/pf-v5-tooltip/test/pf-tooltip.e2e.ts deleted file mode 100644 index e51a80a7fb..0000000000 --- a/elements/pf-v5-tooltip/test/pf-tooltip.e2e.ts +++ /dev/null @@ -1,25 +0,0 @@ -import { test } from '@playwright/test'; -import { PfeDemoPage } from '@patternfly/pfe-tools/test/playwright/PfeDemoPage.js'; -import { SSRPage } from '@patternfly/pfe-tools/test/playwright/SSRPage.js'; - -const tagName = 'pf-v5-tooltip'; - -test.describe(tagName, () => { - test('snapshot', async ({ page }) => { - const componentPage = new PfeDemoPage(page, tagName); - await componentPage.navigate(); - await componentPage.snapshot(); - }); - - test('ssr', async ({ browser }) => { - const fixture = new SSRPage({ - tagName, - browser, - demoDir: new URL('../demo/', import.meta.url), - importSpecifiers: [ - `@patternfly/elements/${tagName}/${tagName}.js`, - ], - }); - await fixture.snapshots(); - }); -}); diff --git a/elements/pf-v5-tooltip/test/pf-tooltip.spec.ts b/elements/pf-v5-tooltip/test/pf-tooltip.spec.ts deleted file mode 100644 index 48482ce25b..0000000000 --- a/elements/pf-v5-tooltip/test/pf-tooltip.spec.ts +++ /dev/null @@ -1,57 +0,0 @@ -import { expect, html, fixture } from '@open-wc/testing'; - -import { PfV5Tooltip } from '../pf-v5-tooltip.js'; -import { setViewport, sendMouse } from '@web/test-runner-commands'; -import { a11ySnapshot } from '@patternfly/pfe-tools/test/a11y-snapshot.js'; - -describe('', function() { - let element: PfV5Tooltip; - - beforeEach(async function() { - await setViewport({ width: 1000, height: 1000 }); - }); - - it('imperatively instantiates', function() { - expect(document.createElement('pf-v5-tooltip')).to.be.an.instanceof(PfV5Tooltip); - }); - - it('should upgrade', async function() { - element = await fixture(html``); - const klass = customElements.get('pf-v5-tooltip'); - expect(element) - .to.be.an.instanceOf(klass) - .and - .to.be.an.instanceOf(PfV5Tooltip); - }); - - describe('typical usage', function() { - beforeEach(async function() { - element = await fixture(html` - Tooltip - `); - }); - - it('should be accessible', async function() { - await expect(element).shadowDom.to.be.accessible(); - }); - - it('should hide tooltip content from assistive technology', async function() { - const snapshot = await a11ySnapshot(); - expect(snapshot).to.axContainName('Tooltip'); - expect(snapshot).to.not.axContainName('Content'); - }); - - describe('hovering the element', function() { - beforeEach(async function() { - const { x, y } = element.getBoundingClientRect(); - await sendMouse({ position: [x + 5, y + 5], type: 'move' }); - await element.updateComplete; - }); - it('should show tooltip content to assistive technology', async function() { - const snapshot = await a11ySnapshot(); - expect(snapshot).to.axContainName('Tooltip'); - expect(snapshot).to.axContainName('Content'); - }); - }); - }); -}); diff --git a/elements/pf-v6-tooltip/README.md b/elements/pf-v6-tooltip/README.md new file mode 100644 index 0000000000..0abfbbf934 --- /dev/null +++ b/elements/pf-v6-tooltip/README.md @@ -0,0 +1,77 @@ +# Tooltip + +`` - in-app messaging used to identify elements with short, +clarifying text. Shows on hover or focus. + +## Usage + +```html + + + +``` + +Rich content via slot: + +```html + + + Tooltip with rich content + +``` + +External trigger (element id — not an event type): + +```html + + +``` + +> **Note:** `trigger` is an idref (or Element via the property). Values like +> `"click"` or `"manual"` are treated as element IDs, not open modes. The +> tooltip always opens on mouseenter + focusin. React-style `trigger="click"` +> is not supported and should not be emulated with this component — for +> click-triggered overlays, use the native Popover API (`popover` + +> `popovertarget`). To suppress default hover/focus and control visibility +> programmatically, cancel `show`/`hide` (see the manual-trigger demo). + +## Divergences from React `Tooltip` + +### Not implemented + +| React prop | Notes | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `appendTo` | Web component renders in its own shadow DOM; no portal needed | +| `aria` | No `labelledby` or `none` mode. A11y is provided via a `role="status"` live region; `ariaDescribedByElements` is set as progressive enhancement but doesn't work cross-root today. For icon-only buttons where the tooltip provides the accessible *name*, set `silent` and add `aria-label` to the trigger manually. | +| `aria-live` | Not implemented | +| `position="auto"` | Not supported by `FloatingDOMController` / `Placement`. Prefer an explicit `position` and leave flip enabled (default). | +| `flipBehavior="flip"` | The special `"flip"` string (opposite-side flip) is not supported. Pass an explicit fallback list via `flip-behavior` instead (e.g. `top,right,left`). | +| `minWidth` | No CSS custom property exposed | + +### Changed API + +| React prop | Web component | Difference | +| -------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `trigger` (event types) | Cancelable `show`/`hide` events | React's `trigger` prop sets open modes (`'mouseenter focus'`, `'click'`, `'manual'`). That prop has **no** string equivalent here — the WC always opens on mouseenter + focusin. Do not pass `"click"` / `"manual"` to the WC `trigger` attribute. For React `'click'`, use the native Popover API instead of emulating with this tooltip. For React `'manual'`, cancel `show`/`hide` and call `.show()` / `.hide()` (see the manual-trigger demo). | +| `content` (required prop) | `content` attribute or `content` slot | Attribute is optional when slot is used | +| `enableFlip` | `no-flip` | Inverted boolean; flip enabled by default | +| `flipBehavior` | `flip-behavior` | Attribute accepts comma-separated list instead of array | +| `isContentLeftAligned` | `alignment` | Accepts `'start'` or `'end'` instead of boolean; uses logical properties for RTL support | +| `maxWidth` | `--pf-v6-c-tooltip--MaxWidth` | CSS custom property instead of prop | +| `children` / `triggerRef` | default slot or `trigger` attribute | WC `trigger` means *which* element (ID string or Element ref), same role as React `triggerRef` — **not** React's event-type `trigger` prop | +| `onTooltipHidden` | `hide` event | DOM event with `reason` (`mouseleave` / `focusout` / `escape`). Cancelable except Escape, which always dismisses. Also fires `show` (no React equivalent) | +| `animationDuration` | CSS transitions | Override via stylesheet instead of prop | +| `distance` | Hardcoded 15px | Not configurable; React default also 15 | +| `isVisible` | `visible` | Boolean attribute; also controllable via `.show()` / `.hide()` methods | +| `zIndex` | `--pf-v6-c-tooltip--ZIndex` | CSS custom property instead of prop; defaults to 10000 | +| `className` | CSS custom properties | Standard web component styling mechanisms | + +### Added + +| Web component API | Notes | +| ----------------------------- | ------------------------------------------------------------------- | +| `show` event | Cancelable event before tooltip shows, with trigger `reason` | +| `hide` event | Event before tooltip hides, with `reason`. Cancelable for mouseleave/focusout; Escape (`reason: 'escape'`) is never cancelable | +| `.show()` / `.hide()` methods | Programmatic visibility control | +| `content` slot | Rich HTML content, not available in React (which takes `ReactNode`) | + diff --git a/elements/pf-v6-tooltip/demo/color-scheme.html b/elements/pf-v6-tooltip/demo/color-scheme.html new file mode 100644 index 0000000000..20b40f4b21 --- /dev/null +++ b/elements/pf-v6-tooltip/demo/color-scheme.html @@ -0,0 +1,44 @@ +--- +description: Tooltip inverts to contrast with the page color scheme. +--- +
+

Light mode

+ + Light page trigger + +
+ +
+

Dark mode

+ + Dark page trigger + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/dynamic-content.html b/elements/pf-v6-tooltip/demo/dynamic-content.html new file mode 100644 index 0000000000..d9c53f9886 --- /dev/null +++ b/elements/pf-v6-tooltip/demo/dynamic-content.html @@ -0,0 +1,39 @@ +--- +description: Tooltip content that updates dynamically. +--- +
+ + + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/index.html b/elements/pf-v6-tooltip/demo/index.html new file mode 100644 index 0000000000..6aa1df171a --- /dev/null +++ b/elements/pf-v6-tooltip/demo/index.html @@ -0,0 +1,20 @@ +--- +description: A tooltip wrapping a button, shown on hover or focus. +--- +
+ + I have a tooltip! + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/manual-trigger.html b/elements/pf-v6-tooltip/demo/manual-trigger.html new file mode 100644 index 0000000000..cee1043d75 --- /dev/null +++ b/elements/pf-v6-tooltip/demo/manual-trigger.html @@ -0,0 +1,60 @@ +--- +description: > + Manually controlled tooltip using show() and hide() methods. Visibility is + controlled only by those methods (the checkbox below). Hover and focus do + not open or close the tooltip — default triggers are canceled. Screen + readers announce when show() runs, not when the target is focused. +--- +
+

+ Visibility is controlled only by the checkbox (show() / + hide()). Hover and focus do not open or close the tooltip. + Screen readers announce when the tooltip is shown, not when the target + is focused. +

+
+ +
+ +
+ +
+ + Target element + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/options.html b/elements/pf-v6-tooltip/demo/options.html new file mode 100644 index 0000000000..fed5ef159f --- /dev/null +++ b/elements/pf-v6-tooltip/demo/options.html @@ -0,0 +1,101 @@ +--- +description: Interactive playground for tooltip options. +--- +
+
+ Position + +
+ +
+ Alignment + +
+ +
+ Delays + + +
+ +
+ Flip + +
+
+ +
+ + Tooltip + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/placement.html b/elements/pf-v6-tooltip/demo/placement.html new file mode 100644 index 0000000000..54e3fd3a1a --- /dev/null +++ b/elements/pf-v6-tooltip/demo/placement.html @@ -0,0 +1,61 @@ +--- +description: Tooltips can be positioned on any side of the trigger element. +--- +
+
+ + Top + + + Top Start + + + Top End + + + Bottom + + + Bottom Start + + + Bottom End + + + Left + + + Left Start + + + Left End + + + Right + + + Right Start + + + Right End + +
+
+ + + + diff --git a/elements/pf-v6-tooltip/demo/slotted-content.html b/elements/pf-v6-tooltip/demo/slotted-content.html new file mode 100644 index 0000000000..59261c22e5 --- /dev/null +++ b/elements/pf-v6-tooltip/demo/slotted-content.html @@ -0,0 +1,36 @@ +--- +description: Tooltip content can include formatted HTML via the content slot. +--- +
+

A tooltip may contain + + + + Slotted content can be formatted, using HTML + tags like em, strong, or code. + + by using the content slot. +

+
+ + + + diff --git a/elements/pf-v6-tooltip/demo/trigger-element.html b/elements/pf-v6-tooltip/demo/trigger-element.html new file mode 100644 index 0000000000..7aafa98ebc --- /dev/null +++ b/elements/pf-v6-tooltip/demo/trigger-element.html @@ -0,0 +1,25 @@ +--- +description: Setting the trigger property to an Element reference directly. +--- +
+ Tooltip via element reference + + +
+ + + + diff --git a/elements/pf-v6-tooltip/demo/trigger-ref.html b/elements/pf-v6-tooltip/demo/trigger-ref.html new file mode 100644 index 0000000000..1ca0b91e65 --- /dev/null +++ b/elements/pf-v6-tooltip/demo/trigger-ref.html @@ -0,0 +1,21 @@ +--- +description: A tooltip referencing an external element as its trigger. +--- +
+ Tooltip attached via trigger ref + + +
+ + + + diff --git a/elements/pf-v6-tooltip/pf-v6-tooltip.css b/elements/pf-v6-tooltip/pf-v6-tooltip.css new file mode 100644 index 0000000000..3c65351f2a --- /dev/null +++ b/elements/pf-v6-tooltip/pf-v6-tooltip.css @@ -0,0 +1,75 @@ +:host { + display: inline; +} + +* { + box-sizing: border-box; +} + +#tooltip { + position: absolute; + user-select: none; + opacity: 0; + pointer-events: none; + z-index: var(--pf-v6-c-tooltip--ZIndex, 10000); + transition: opacity 300ms cubic-bezier(0.54, 1.5, 0.38, 1.11); + translate: var(--_floating-content-translate); + max-width: var(--pf-v6-c-tooltip--MaxWidth, 18.75rem); + box-shadow: var(--pf-v6-c-tooltip--BoxShadow, + var(--pf-t--global--box-shadow--md, + 0 0.25rem 0.5625rem 0 rgba(0, 0, 0, 0.5))); + width: max-content; + inset-block-start: 0; + inset-inline-start: 0; + will-change: opacity; + + &.open { + opacity: 1; + user-select: auto; + pointer-events: auto; + } +} + +/* Fix for Firefox: FF doesn't propagate `inert` through to slotted light DOM content */ +#content[inert] ::slotted(*) { + visibility: hidden; +} + +#content { + position: relative; + text-align: center; + word-break: break-word; + line-height: 1.5; + padding-block-start: var(--pf-v6-c-tooltip__content--PaddingBlockStart, + var(--pf-t--global--spacer--sm, 0.5rem)); + padding-inline-end: var(--pf-v6-c-tooltip__content--PaddingInlineEnd, + var(--pf-t--global--spacer--md, 1rem)); + padding-block-end: var(--pf-v6-c-tooltip__content--PaddingBlockEnd, + var(--pf-t--global--spacer--sm, 0.5rem)); + padding-inline-start: var(--pf-v6-c-tooltip__content--PaddingInlineStart, + var(--pf-t--global--spacer--md, 1rem)); + font-size: var(--pf-v6-c-tooltip__content--FontSize, + var(--pf-t--global--font--size--body--sm, 0.75rem)); + color: var(--pf-v6-c-tooltip__content--Color, + var(--pf-t--global--text--color--inverse, + light-dark(#fff, #1f1f1f))); + background-color: var(--pf-v6-c-tooltip__content--BackgroundColor, + var(--pf-t--global--background--color--inverse--default, + light-dark(#1b1d21, #f2f2f2))); + border-radius: var(--pf-v6-c-tooltip__content--BorderRadius, + var(--pf-t--global--border--radius--small, 6px)); +} + +#arrow { + position: absolute; + width: var(--pf-v6-c-tooltip__arrow--Width, 0.9375rem); + height: var(--pf-v6-c-tooltip__arrow--Height, 0.9375rem); + pointer-events: none; + background-color: var(--pf-v6-c-tooltip__arrow--BackgroundColor, + var(--pf-t--global--background--color--inverse--default, + light-dark(#1b1d21, #f2f2f2))); + box-shadow: var(--pf-v6-c-tooltip__arrow--BoxShadow, + var(--pf-t--global--box-shadow--md, + 0 0.25rem 0.5625rem 0 rgba(0, 0, 0, 0.5))); + rotate: 45deg; +} diff --git a/elements/pf-v6-tooltip/pf-v6-tooltip.ts b/elements/pf-v6-tooltip/pf-v6-tooltip.ts new file mode 100644 index 0000000000..00674078ca --- /dev/null +++ b/elements/pf-v6-tooltip/pf-v6-tooltip.ts @@ -0,0 +1,456 @@ +/* eslint-disable lit-a11y/accessible-name -- tooltip content text IS the accessible name */ +import type { PropertyValues, TemplateResult } from 'lit'; +import { LitElement, html, isServer } from 'lit'; +import { customElement } from 'lit/decorators/custom-element.js'; +import { property } from 'lit/decorators/property.js'; +import { styleMap } from 'lit/directives/style-map.js'; +import { classMap } from 'lit/directives/class-map.js'; + +import { observes } from '@patternfly/pfe-core/decorators/observes.js'; + +import { + FloatingDOMController, + type Placement, +} from '@patternfly/pfe-core/controllers/floating-dom-controller.js'; + +import { StringListConverter } from '@patternfly/pfe-core'; + +import styles from './pf-v6-tooltip.css'; + +export type { Placement }; + +export type TooltipAlignment = 'start' | 'end'; + +export type TooltipTriggerReason = + | 'mouseenter' + | 'focusin' + | 'mouseleave' + | 'focusout' + | 'escape'; + +export class TooltipShowEvent extends Event { + constructor(public reason: TooltipTriggerReason) { + super('show', { bubbles: true, cancelable: true }); + } +} + +export class TooltipHideEvent extends Event { + /** + * @param reason - What caused the hide + * @param cancelable - False for Escape so a11y dismiss cannot be blocked + */ + constructor(public reason: TooltipTriggerReason, cancelable = true) { + super('hide', { bubbles: true, cancelable }); + } +} + +const ENTRY_EVENTS: readonly string[] = ['focusin', 'mouseenter']; +const EXIT_EVENTS: readonly string[] = ['focusout', 'mouseleave']; + +/** + * A tooltip provides short, clarifying text for a UI element when the user + * hovers over or focuses the trigger. Use tooltips for supplementary + * information that SHOULD NOT contain interactive content. The trigger element + * MUST be focusable so keyboard and screen reader users can access the tooltip. + * + * Accessibility is provided via a shared `role="status"` live region that + * announces tooltip content to screen readers when shown. The tooltip also + * attempts to set `aria-describedby` on the trigger via the cross-root + * `ariaDescribedByElements` IDL property, but this is a progressive + * enhancement — browsers currently reject light-to-shadow element references + * (see WICG/aom#192, whatwg/html#5401). Until Reference Target ships, + * the live-region announcer is the working a11y path. + * + * Pressing Escape dismisses an open tooltip (fires a non-cancelable `hide` + * event with `reason: 'escape'`). Focus remains on the trigger while the + * tooltip is visible. + * + * Colors invert automatically via `light-dark()` using PatternFly inverse + * background and text tokens (`--pf-t--global--background--color--inverse--default`, + * `--pf-t--global--text--color--inverse`). + * + * @summary Supplementary text popup on hover or focus. + * + * @slot - Focusable trigger element. MUST be keyboard-accessible (e.g. ` + + `); + }); + + it('should be accessible', async function() { + await expect(element).shadowDom.to.be.accessible(); + }); + + it('should hide tooltip content from assistive technology when closed', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Trigger'); + expect(snapshot).to.not.axContainName('Tooltip text'); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should show tooltip content to assistive technology', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Trigger'); + expect(snapshot).to.axContainName('Tooltip text'); + }); + + // Documents the cross-root ARIA gap: ariaDescribedByElements doesn't + // work light→shadow today (WICG/aom#192). This test will intentionally + // fail once Reference Target ships, signaling it's time to gate/remove + // the live-region announcer to avoid double-announcement. + it('trigger has no computed description (cross-root ARIA gap)', async function() { + const snapshot = await a11ySnapshot(); + const trigger = snapshot.children?.find( + (n: { role: string }) => n.role === 'button', + ); + expect(trigger?.description).to.be.undefined; + }); + }); + + describe('after calling hide()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + await element.hide(); + await element.updateComplete; + }); + + it('should hide tooltip content from assistive technology', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Trigger'); + expect(snapshot).to.not.axContainName('Tooltip text'); + }); + }); + + describe('hovering the element', function() { + beforeEach(async function() { + const { x, y } = element.getBoundingClientRect(); + await sendMouse({ position: [x + 5, y + 5], type: 'move' }); + await new Promise(r => setTimeout(r, 400)); + await element.updateComplete; + }); + + it('should show tooltip content to assistive technology', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Trigger'); + expect(snapshot).to.axContainName('Tooltip text'); + }); + }); + }); + + describe('with content slot', function() { + beforeEach(async function() { + element = await fixture(html` + + + Rich tooltip content + + `); + }); + + it('should hide slotted content from assistive technology when closed', async function() { + const snapshot = await a11ySnapshot(); + const text = JSON.stringify(snapshot); + expect(text).to.not.include('Rich'); + expect(text).to.not.include('tooltip content'); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should show slotted content', async function() { + const snapshot = await a11ySnapshot(); + const text = JSON.stringify(snapshot); + expect(text).to.include('Rich'); + expect(text).to.include('tooltip'); + }); + }); + }); + + describe('with both content attribute and content slot', function() { + beforeEach(async function() { + element = await fixture(html` + + + Slot content + + `); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should show slotted content instead of attribute content', async function() { + const snapshot = await a11ySnapshot(); + const text = JSON.stringify(snapshot); + expect(text).to.include('Slot content'); + expect(text).to.not.include('Attribute content'); + }); + }); + }); + + describe('with position attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should accept position attribute', function() { + expect(element.position).to.equal('bottom'); + }); + }); + + describe('with no-flip attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should accept no-flip attribute', function() { + expect(element.noFlip).to.be.true; + }); + }); + + describe('with flip-behavior attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should parse comma-separated placements', function() { + expect(element.flipBehavior).to.deep.equal(['top', 'bottom']); + }); + }); + + describe('with entry-delay and exit-delay', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should accept delay attributes', function() { + expect(element.entryDelay).to.equal(100); + expect(element.exitDelay).to.equal(50); + }); + }); + + describe('with alignment attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should accept alignment attribute', function() { + expect(element.alignment).to.equal('start'); + }); + }); + + describe('with visible attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + await element.updateComplete; + await new Promise(r => setTimeout(r, 100)); + }); + + it('should show tooltip content', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Visible'); + }); + }); + + describe('with trigger attribute', function() { + let triggerButton: HTMLButtonElement; + + beforeEach(async function() { + const container = await fixture(html` +
+ + +
+ `); + triggerButton = container.querySelector('#ext-trigger')!; + element = container.querySelector('pf-v6-tooltip')!; + await element.updateComplete; + }); + + it('should accept trigger attribute', function() { + expect(element.trigger).to.equal('ext-trigger'); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should show tooltip content', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('External tooltip'); + }); + }); + }); + + describe('with trigger property set to Element reference', function() { + let triggerButton: HTMLButtonElement; + + beforeEach(async function() { + triggerButton = await fixture(html` + + `); + element = await fixture(html` + + `); + element.trigger = triggerButton; + await element.updateComplete; + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should show tooltip content', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Ref tooltip'); + }); + }); + }); + + describe('show event', function() { + let showEvent: TooltipShowEvent | null; + + beforeEach(async function() { + showEvent = null; + element = await fixture(html` + + + + `); + element.addEventListener('show', function(e) { + showEvent = e as TooltipShowEvent; + }); + }); + + describe('hovering the element', function() { + beforeEach(async function() { + const { x, y } = element.getBoundingClientRect(); + await sendMouse({ position: [x + 5, y + 5], type: 'move' }); + await new Promise(r => setTimeout(r, 50)); + }); + + it('should fire show event with reason', function() { + expect(showEvent).to.be.an.instanceOf(TooltipShowEvent); + expect(showEvent!.reason).to.equal('mouseenter'); + }); + }); + }); + + describe('hide event', function() { + let hideEvent: TooltipHideEvent | null; + + beforeEach(async function() { + hideEvent = null; + element = await fixture(html` + + + + `); + element.addEventListener('hide', function(e) { + hideEvent = e as TooltipHideEvent; + }); + }); + + describe('hovering then leaving the element', function() { + beforeEach(async function() { + const { x, y } = element.getBoundingClientRect(); + await sendMouse({ position: [x + 5, y + 5], type: 'move' }); + await new Promise(r => setTimeout(r, 50)); + await sendMouse({ position: [0, 0], type: 'move' }); + await new Promise(r => setTimeout(r, 50)); + }); + + it('should fire hide event with reason', function() { + expect(hideEvent).to.be.an.instanceOf(TooltipHideEvent); + expect(hideEvent!.reason).to.equal('mouseleave'); + }); + }); + }); + + describe('cancelling show event', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + element.addEventListener('show', function(e) { + e.preventDefault(); + }); + }); + + describe('hovering the element', function() { + beforeEach(async function() { + const { x, y } = element.getBoundingClientRect(); + await sendMouse({ position: [x + 5, y + 5], type: 'move' }); + await new Promise(r => setTimeout(r, 100)); + await element.updateComplete; + }); + + it('should not show tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Prevented'); + }); + }); + }); + + describe('cancelling hide event', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + await element.show(); + await element.updateComplete; + element.addEventListener('hide', function(e) { + e.preventDefault(); + }); + }); + + describe('leaving the element', function() { + beforeEach(async function() { + await sendMouse({ position: [0, 0], type: 'move' }); + await new Promise(r => setTimeout(r, 100)); + await element.updateComplete; + }); + + it('should remain visible', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Stay visible'); + }); + }); + }); + + describe('focus triggers', function() { + let button: HTMLButtonElement; + + beforeEach(async function() { + element = await fixture(html` + + + + `); + button = element.querySelector('button')!; + }); + + describe('focusing the trigger', function() { + beforeEach(async function() { + button.focus(); + await new Promise(r => setTimeout(r, 50)); + await element.updateComplete; + }); + + it('should show tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Focus tip'); + }); + + describe('then blurring the trigger', function() { + beforeEach(async function() { + button.blur(); + await new Promise(r => setTimeout(r, 50)); + await element.updateComplete; + }); + + it('should hide tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Focus tip'); + }); + }); + }); + }); + + describe('Escape key', function() { + let hideEvent: TooltipHideEvent | null; + + beforeEach(async function() { + hideEvent = null; + element = await fixture(html` + + + + `); + element.addEventListener('hide', function(e) { + hideEvent = e as TooltipHideEvent; + }); + await element.show(); + await element.updateComplete; + }); + + describe('pressing Escape', function() { + beforeEach(async function() { + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); + await element.updateComplete; + await new Promise(r => setTimeout(r, 50)); + }); + + it('should fire non-cancelable hide with reason escape', function() { + expect(hideEvent).to.be.an.instanceOf(TooltipHideEvent); + expect(hideEvent!.reason).to.equal('escape'); + expect(hideEvent!.cancelable).to.be.false; + }); + + it('should hide tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Escapable'); + }); + }); + + describe('pressing Escape with preventDefault on hide', function() { + beforeEach(async function() { + element.addEventListener('hide', function(e) { + e.preventDefault(); + }); + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); + await element.updateComplete; + await new Promise(r => setTimeout(r, 50)); + }); + + it('should still hide tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Escapable'); + }); + }); + }); + + describe('Escape key with external trigger', function() { + let triggerButton: HTMLButtonElement; + + beforeEach(async function() { + const container = await fixture(html` +
+ + +
+ `); + triggerButton = container.querySelector('#esc-trigger')!; + element = container.querySelector('pf-v6-tooltip')!; + await element.updateComplete; + await element.show(); + await element.updateComplete; + }); + + describe('pressing Escape on document', function() { + beforeEach(async function() { + document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); + await element.updateComplete; + await new Promise(r => setTimeout(r, 50)); + }); + + it('should hide tooltip', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Escape external'); + }); + }); + }); + + describe('announcer live region', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should populate the live region with tooltip content', async function() { + const snapshot = await a11ySnapshot(); + const text = JSON.stringify(snapshot); + expect(text).to.include('Announced text'); + }); + + describe('then calling hide()', function() { + beforeEach(async function() { + await element.hide(); + await element.updateComplete; + }); + + it('should clear the live region', async function() { + const snapshot = await a11ySnapshot(); + const text = JSON.stringify(snapshot); + expect(text).to.not.include('Announced text'); + }); + }); + }); + }); + + describe('tooltip content inert state', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should exclude tooltip content from ax tree when hidden', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.not.axContainName('Inert test'); + }); + + describe('after calling show()', function() { + beforeEach(async function() { + await element.show(); + await element.updateComplete; + }); + + it('should include tooltip content in ax tree when visible', async function() { + const snapshot = await a11ySnapshot(); + expect(snapshot).to.axContainName('Inert test'); + }); + }); + }); + + describe('with silent attribute', function() { + beforeEach(async function() { + element = await fixture(html` + + + + `); + }); + + it('should accept silent attribute', function() { + expect(element.silent).to.be.true; + }); + + it('should not announce when shown', async function() { + const announcer = document.querySelector('[role="status"]')!; + announcer.textContent = ''; + await element.show(); + await element.updateComplete; + expect(announcer.textContent).to.equal(''); + }); + }); +});