diff --git a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md index 07f5584992..b7d8c217ef 100644 --- a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md +++ b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md @@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - New Tooltip widgets now default to Open on Hover,focus, so keyboard users can see the tooltip. Existing widgets keep their setting. +- Custom tooltip content now loads together with the page instead of when the tooltip first opens, so screen readers can announce it. Data sources inside custom content run at page load. + ### Fixed - We fixed an issue where the tooltip in Click mode didn't open when the trigger was an action button: with an action set, it didn't open on click, Enter or Space; without one, it didn't open on Enter or Space. @@ -24,6 +26,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - We fixed an issue where pressing Tab from a Hover,focus trigger into custom tooltip content closed the tooltip and moved focus to the top of the page. The tooltip now stays open while focus is inside its content. +- We fixed an issue where screen readers did not announce tooltip content on interactive elements. + ## [1.5.1] - 2026-02-10 ### Added diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/.openspec.yaml b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/.openspec.yaml new file mode 100644 index 0000000000..90080a9210 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-16 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/design.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/design.md new file mode 100644 index 0000000000..0f88b083c9 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/design.md @@ -0,0 +1,27 @@ +## Context + +`Tooltip.tsx` renders one content element whenever `textMessage` or `htmlMessage` is truthy for the selected render method. Closed, it uses `.widget-tooltip-sr-only`, `aria-hidden="true"` and `inert`, which keep it in the layout but visually hidden. A truthy `htmlMessage` does not mean anything is shown, because widgets inside it can be hidden by conditional visibility. + +## Goals / Non-Goals + +**Goals:** restore normal tabbing, and never describe a trigger with, or open, empty content. + +**Non-Goals:** + +- Changing how open content looks or is positioned. +- Detecting content that is present but visually empty for other reasons, such as text styled to be invisible. + +## Decisions + +- **Hide closed content with the `hidden` attribute.** It applies `display: none`, so the content cannot take focus and leaves page order, which removes the trap. Accessible description computation still reads hidden content when a trigger references it directly through `aria-describedby`. Because `display: none` already hides the content from assistive technology and focus, `inert`, `aria-hidden` and `.widget-tooltip-sr-only` are removed. _Alternative:_ add `display: none` and keep `inert`, as QA tested. Rejected because `inert` adds nothing once the element is not displayed. +- **Measure rendered content.** A layout effect sets `hasVisibleContent` from the content element: true when its trimmed `textContent` is not empty, or when it contains `img`, `svg`, `video`, `canvas`, `iframe`, `input`, `select` or `textarea`. A `MutationObserver` on the element repeats the check when children, text or attributes change, so conditional visibility updates the result. Measuring works while hidden, because `textContent` and queries do not depend on layout. +- **Gate the open state.** The widget passes `showTooltip && hasVisibleContent` to Floating UI and to rendering, so empty content never opens. If content becomes visible while the trigger is hovered or focused, the tooltip opens. +- **Gate the description.** The `aria-describedby` effect also requires `hasVisibleContent`, and its cleanup removes the id when content becomes empty. +- **Trim text.** `textMessage?.trim()` decides whether Text mode has content, so whitespace-only text renders no element. +- **Preview counts as visible.** In Studio Pro preview, the custom content drop zone must show even when empty, so `hasVisibleContent` is always true there. + +## Risks / Trade-offs + +- [A screen reader might not read a description from `display: none` content] → Referenced hidden content is part of the description computation in browsers, and task 3.2 checks VoiceOver and NVDA. +- [Content that shows only a CSS background or icon font has no text or media, so it counts as empty] → Rare for a tooltip. Adding visible text or an image avoids it. +- [The content observer runs on every DOM change inside the tooltip] → The check is one `textContent` read and one query, and it stops on cleanup. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/proposal.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/proposal.md new file mode 100644 index 0000000000..4d6fa464d0 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/proposal.md @@ -0,0 +1,30 @@ +## Why + +QA testing of WC-3404 found three problems with `unify-tooltip-content-rendering`: + +1. **Keyboard trap.** With Custom content that contains a focusable widget, Tab and Shift+Tab stop moving focus around the trigger, even while the tooltip is closed or after closing it with Escape. In 1.5.1, Tab moves on normally. QA reports that the Mendix client moves focus to the next element in page order itself, which is now inside the closed, `inert` content, and that adding `display: none` restored normal tabbing in browser tests. +2. **Empty description and empty tooltip.** When conditional visibility hides all Custom content widgets, the trigger still references an empty element, and focusing it opens an empty tooltip about 12px high. +3. **Whitespace-only text.** In Text mode, text such as `' '` gives the trigger an empty description. + +## What Changes + +- Hide closed content with `display: none` instead of visually hiding it, and remove `inert`, `aria-hidden` and the `.widget-tooltip-sr-only` styles. +- Treat content as empty when it renders no text and no media, and update this when its widgets show or hide. +- With empty content, add no `aria-describedby` and do not open the tooltip. +- Trim Text mode content before deciding whether it exists. + +## Capabilities + +### New Capabilities + + + +### Modified Capabilities + +- `tooltip-screen-reader-description`: Closed content is hidden with `display: none`, and content that renders nothing visible counts as no content. + +## Impact + +- `src/components/Tooltip.tsx`, `src/ui/Tooltip.scss`, `src/components/__tests__/Tooltip.spec.tsx`. +- No XML, typings, dependency or changelog changes beyond the existing "Fixed" entry. +- Depends on `fix-tooltip-screen-reader-description` and `unify-tooltip-content-rendering`, so archive this change after them. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/specs/tooltip-screen-reader-description/spec.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/specs/tooltip-screen-reader-description/spec.md new file mode 100644 index 0000000000..e4d9b56eee --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/specs/tooltip-screen-reader-description/spec.md @@ -0,0 +1,61 @@ +## MODIFIED Requirements + +### Requirement: Tooltip content is available before the tooltip opens + +When the content for the selected render method exists, the widget SHALL keep exactly one content element in the DOM, whether or not the tooltip is open. While closed, the element SHALL be hidden with `display: none`, so it cannot take focus or affect keyboard navigation. While open, it SHALL be shown as the tooltip. Text mode content SHALL count as existing only if it is not empty after trimming. When the selected render method has no content, the widget SHALL NOT render the element. + +#### Scenario: Tooltip is closed + +- **WHEN** the selected render method has content and the tooltip is closed +- **THEN** the content element is in the DOM and hidden with `display: none` + +#### Scenario: Tooltip is open + +- **WHEN** the tooltip opens +- **THEN** the same element is shown as the tooltip and the content appears exactly once in the DOM + +#### Scenario: Tabbing past a trigger with focusable custom content + +- **WHEN** the tooltip is closed, custom content contains a button, and the user presses Tab on the trigger +- **THEN** focus moves to the next focusable element after the tooltip, and Shift+Tab from that element moves focus back to the trigger + +#### Scenario: Custom widgets across open and close + +- **WHEN** the tooltip opens and closes +- **THEN** custom widgets stay mounted and are not remounted + +#### Scenario: Text mode with leftover custom content + +- **WHEN** the render method is `text`, the text is empty and custom widgets are configured +- **THEN** the content element is not rendered and no description is added + +#### Scenario: Whitespace-only text + +- **WHEN** the render method is `text` and the text contains only whitespace +- **THEN** the content element is not rendered and no description is added + +## ADDED Requirements + +### Requirement: Empty rendered content is treated as no content + +The widget SHALL treat content as empty when the content element has no text after trimming and contains no image, SVG, video, canvas, iframe or form field. With empty content, the widget SHALL NOT add its id to `aria-describedby` and SHALL NOT open the tooltip. The widget SHALL update this when the rendered content changes. In the Studio Pro preview, content SHALL always count as not empty. + +#### Scenario: All custom widgets are hidden + +- **WHEN** conditional visibility hides every widget in the custom content +- **THEN** trigger elements do not reference the content element, and focusing, hovering or clicking the trigger does not open a tooltip + +#### Scenario: Hidden custom widgets become visible + +- **WHEN** a hidden custom content widget becomes visible +- **THEN** trigger elements reference the content element again, and the tooltip can open + +#### Scenario: Custom content with only an image + +- **WHEN** custom content renders only an image +- **THEN** the content counts as not empty + +#### Scenario: Empty custom content in preview + +- **WHEN** the widget renders in preview with empty custom content +- **THEN** the custom content drop zone is still shown diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/tasks.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/tasks.md new file mode 100644 index 0000000000..e885e9652e --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-closed-and-empty-tooltip-content/tasks.md @@ -0,0 +1,27 @@ +## 1. Implementation + +- [x] 1.1 In `src/components/Tooltip.tsx`, hide closed content with the `hidden` attribute, and remove the `inert` effect, `aria-hidden` and the `.widget-tooltip-sr-only` class +- [x] 1.2 Remove the `.widget-tooltip-sr-only` rule from `src/ui/Tooltip.scss` +- [x] 1.3 Trim `textMessage` when deciding whether Text mode has content +- [x] 1.4 Add `hasVisibleContent`, measured in a layout effect and kept current with a `MutationObserver` on the content element, and always true in preview +- [x] 1.5 Use `showTooltip && hasVisibleContent` as the open state for Floating UI and rendering +- [x] 1.6 Require `hasVisibleContent` before adding `aria-describedby` + +## 2. Unit tests + +- [x] 2.1 Replace the inert test: closed content has `hidden` and no `inert` or `aria-hidden`, and open content has none of them +- [x] 2.2 Test that Custom content rendering nothing adds no description and does not open on click +- [x] 2.3 Test that when Custom content changes from empty to visible, the description is added and the tooltip opens, and the reverse removes it +- [x] 2.4 Test that whitespace-only text renders no content element and adds no description +- [x] 2.5 Test that Custom content with only an image counts as visible +- [x] 2.6 Test that empty Custom content in preview still renders the drop zone +- [x] 2.7 Check that the snapshot is unchanged, as it shows open content +- [x] 2.8 `pnpm run test` and `pnpm run lint` pass in `packages/pluggableWidgets/tooltip-web` + +## 3. Manual QA + +- [ ] 3.1 QA finding 1: with Custom content containing a button, link or text box, Tab and Shift+Tab move past the trigger with the tooltip closed and after closing it with Escape +- [ ] 3.2 VoiceOver and NVDA announce text and Custom content on focus, with the tooltip closed and open +- [ ] 3.3 QA finding 2: with all Custom content hidden by conditional visibility, the trigger has no `aria-describedby` and no tooltip opens; showing the content again restores both +- [ ] 3.4 QA finding 3: whitespace-only text gives no `aria-describedby` +- [ ] 3.5 Open content is focusable and usable, and the tooltip opens, closes and positions as before in all `Open on` modes diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/.openspec.yaml b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/.openspec.yaml new file mode 100644 index 0000000000..a7587c5f07 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-02 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/design.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/design.md new file mode 100644 index 0000000000..2e41a1c2b2 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/design.md @@ -0,0 +1,30 @@ +## Context + +`useRole` from `@floating-ui/react` sets `aria-describedby` on the `.widget-tooltip-trigger` wrapper, and only while the tooltip is open. The wrapper is not the element that receives focus, because the trigger is made of arbitrary Mendix widgets placed inside it. + +## Goals / Non-Goals + +**Goals:** expose tooltip content as the accessible description of focusable trigger elements, without changing how the tooltip looks or opens. + +**Non-Goals:** + +- Describing triggers that have no focusable elements. +- Changing the Floating UI positioning or interaction hooks. + +## Decisions + +- **Always-rendered hidden element, referenced by `aria-describedby`.** The description has to exist before the tooltip opens. The element has `aria-hidden="true"` so browse mode does not read it as separate page content, while `aria-describedby` can still reference it. _Alternative:_ `aria-live`. Rejected because it announces on change rather than describing the element in focus. +- **Set the attribute through the DOM.** The widget does not control the markup of the widgets in its `trigger` slot, so it cannot pass them props. It queries the wrapper for focusable elements instead. +- **Merge ids rather than overwrite.** Trigger elements can already have a description, such as validation or help text. Removing only the tooltip id during cleanup restores the earlier value without having to store it. +- **Watch the wrapper with a `MutationObserver`.** Mendix widgets can render late and can reset attributes they manage. The observer callback writes only when the tooltip id is missing, so its own writes do not cause a loop. +- **Use `.widget-tooltip-sr-only`.** A prefixed class avoids a global rule that would affect other widgets using `.sr-only`. + +## Risks / Trade-offs + +- [Custom content renders twice while the tooltip is open, which can duplicate widget side effects and ids] → Open question, to be settled by manual testing (task 3.3). +- [Focusable elements in custom content stay tabbable inside the `aria-hidden` element, because it is hidden only visually] → Open question, to be settled by manual testing (task 3.4). +- [The observer runs on every DOM change in the trigger] → The callback is one query plus attribute checks, and it stops on cleanup. + +## Open Questions + +- Should Custom mode keep a second rendered copy of its widgets? This depends on the results of tasks 3.3 and 3.4. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/proposal.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/proposal.md new file mode 100644 index 0000000000..7e367859be --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/proposal.md @@ -0,0 +1,27 @@ +## Why + +Screen reader users who tab to an interactive tooltip trigger hear nothing (WC-3404). The tooltip content is only in the DOM while the tooltip is open, and the `aria-describedby` set by Floating UI sits on the non-focusable trigger wrapper. The goal is to announce the content on interactive trigger elements, in line with the Deque tooltip pattern, with no other change in behavior. + +## What Changes + +- Tooltip content is always in the DOM in a visually hidden, widget-prefixed element. +- Focusable elements inside the trigger reference that element through `aria-describedby`. +- Existing `aria-describedby` values on those elements are kept, and only the tooltip id is removed during cleanup. +- Focusable elements that mount later, and elements whose attribute gets reset, receive the description through a `MutationObserver` on the trigger wrapper. +- A CHANGELOG "Fixed" entry. + +## Capabilities + +### New Capabilities + +- `tooltip-screen-reader-description`: Focusable elements in the tooltip trigger expose the tooltip content as their accessible description. + +### Modified Capabilities + + + +## Impact + +- `src/components/Tooltip.tsx`, `src/ui/Tooltip.scss`, `src/components/__tests__/Tooltip.spec.tsx` and its snapshot, `CHANGELOG.md`. +- No XML, typings or dependency changes. +- Patch-level fix. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/specs/tooltip-screen-reader-description/spec.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/specs/tooltip-screen-reader-description/spec.md new file mode 100644 index 0000000000..3ae9504c64 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/specs/tooltip-screen-reader-description/spec.md @@ -0,0 +1,53 @@ +## ADDED Requirements + +### Requirement: Tooltip content is available before the tooltip opens + +When the widget has tooltip content, it SHALL keep that content in the DOM in a visually hidden element, whether or not the visible tooltip is open. The hidden element SHALL have `aria-hidden="true"`. When the widget has no tooltip content, it SHALL NOT render the hidden element. + +#### Scenario: Tooltip is closed + +- **WHEN** the widget has tooltip content and the tooltip is closed +- **THEN** the hidden element contains the content and no visible tooltip is rendered + +#### Scenario: Custom render method + +- **WHEN** the render method is `custom` and custom content is configured +- **THEN** the hidden element contains the custom content + +#### Scenario: No content + +- **WHEN** the widget has no tooltip content +- **THEN** the hidden element is not rendered + +### Requirement: Focusable trigger elements are described by the tooltip + +The widget SHALL add the hidden element's id to `aria-describedby` on every focusable element inside the trigger. + +#### Scenario: Trigger with several focusable elements + +- **WHEN** the trigger contains several buttons and links +- **THEN** each of them references the hidden element through `aria-describedby` + +#### Scenario: Element mounts later + +- **WHEN** a focusable element is added to the trigger after the widget has mounted +- **THEN** that element also references the hidden element + +### Requirement: Existing descriptions are preserved + +The widget SHALL keep other ids in `aria-describedby` on trigger elements. When the description no longer applies, the widget SHALL remove only its own id, and SHALL remove the attribute only if no other ids remain. + +#### Scenario: Element already has a description + +- **WHEN** a focusable trigger element already has an `aria-describedby` value +- **THEN** the attribute contains the existing value and the tooltip id + +#### Scenario: Attribute is reset + +- **WHEN** a trigger widget replaces the `aria-describedby` value of its element +- **THEN** the widget adds the tooltip id back without removing the new value + +#### Scenario: Tooltip content is removed + +- **WHEN** tooltip content is no longer available +- **THEN** the original `aria-describedby` value is left in place, and the attribute is removed from elements that only referenced the tooltip diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/tasks.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/tasks.md new file mode 100644 index 0000000000..07ccf843d6 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/fix-tooltip-screen-reader-description/tasks.md @@ -0,0 +1,26 @@ +## 1. Implementation + +- [x] 1.1 In `src/components/Tooltip.tsx`, always render tooltip content in a hidden element when content exists +- [x] 1.2 Add the hidden element's id to `aria-describedby` on focusable trigger elements, keeping existing values +- [x] 1.3 Remove only the tooltip id during cleanup +- [x] 1.4 Observe the trigger wrapper for late-mounted elements and attribute resets +- [x] 1.5 Add `.widget-tooltip-sr-only` to `src/ui/Tooltip.scss` + +## 2. Unit tests and changelog + +- [x] 2.1 Test that hidden content is in the DOM before the tooltip opens, for text and custom content +- [x] 2.2 Test that all focusable trigger elements get the description +- [x] 2.3 Test that an existing `aria-describedby` is kept and restored +- [x] 2.4 Test late-mounted elements and attribute resets +- [x] 2.5 Add a "Fixed" entry under `[Unreleased]` in `CHANGELOG.md` +- [x] 2.6 `pnpm run test` and `pnpm run lint` pass in `packages/pluggableWidgets/tooltip-web` + +## 3. Manual QA + +- [ ] 3.1 Tooltip opens, closes and positions as before in all `Open on` modes +- [ ] 3.2 VoiceOver and NVDA announce the tooltip text on focusable triggers in all `Open on` modes, and browse mode does not reach the hidden element +- [ ] 3.3 Custom content with a data-loading widget: check for duplicate ids and doubled requests +- [ ] 3.4 Custom content with a link or button: focus must not land on the hidden copy +- [ ] 3.5 Text box with a validation message inside the trigger: message stays announced +- [ ] 3.6 Trigger shown later through conditional visibility: tooltip text is announced +- [ ] 3.7 Hidden text is never visible, and no scrollbars or layout shifts appear diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/.openspec.yaml b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/.openspec.yaml new file mode 100644 index 0000000000..a7587c5f07 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-02 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/design.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/design.md new file mode 100644 index 0000000000..862ad7de9a --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/design.md @@ -0,0 +1,27 @@ +## Context + +`Tooltip.tsx` currently renders `.widget-tooltip-sr-only` whenever content exists, and `.widget-tooltip-content` while open. Both receive the same `textMessage` or `htmlMessage`. Floating UI's `useRole` gives the floating element an id and points the trigger wrapper's `aria-describedby` at that id while open. + +## Goals / Non-Goals + +**Goals:** keep the screen reader description while removing the side effects of the second copy. + +**Non-Goals:** + +- Changing `Open on` modes. Deque's pattern opens tooltips on both focus and hover, while this widget's default `Hover` mode does not open on focus. WC-3404 asks for no other behavior change, so this needs its own ticket. +- Extending the focusable element selector. + +## Decisions + +- **One element for both states.** It stays mounted while content exists, so custom widgets keep their state across open and close. Closed, it has `.widget-tooltip-sr-only` and `aria-hidden="true"`. Open, it has `.widget-tooltip-content`, floating styles and the arrow. _Alternative:_ keep two copies and make the hidden one inert. Rejected because it still duplicates widgets. +- **Attach the floating ref only while open.** `refs.setFloating` is passed only while open, so `autoUpdate` and outside-press detection stay limited to the open tooltip. +- **Use one id.** Trigger elements use the id from `getFloatingProps()`, so wrapper and trigger elements reference the same element and `useId` is removed. +- **Set `inert` through the DOM.** An effect toggles the attribute based on `showTooltip`. React 18 and 19 treat a JSX `inert` prop differently, so `toggleAttribute` works the same on both. +- **Derive content once.** `const content = renderMethod === "text" ? textMessage : htmlMessage`, and content exists only if this value is truthy. +- **Skip `aria-describedby` management in preview.** The effect returns early when `preview` is set, as the preview has no screen reader use. + +## Risks / Trade-offs + +- [Custom widgets mount at page load instead of on first open, so data widgets load early, and many tooltips in a list multiply this] → The current implementation has the same cost, doubled while open, and a description needs content in the DOM. _Alternative:_ describe Text mode only and mount custom content on open as on `main`, which fully keeps "no other change" but leaves Custom mode unannounced. This is the decision for review. +- [`inert` could remove the element from description computation in some browser and screen reader pairs] → Task 3.2 checks this. If it fails, remove only the `inert` attribute and revisit focus handling. +- [Reusing one element changes the DOM of the closed state] → Unit tests and existing E2E screenshots cover open state rendering. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/proposal.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/proposal.md new file mode 100644 index 0000000000..ec75f3655b --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/proposal.md @@ -0,0 +1,32 @@ +## Why + +`fix-tooltip-screen-reader-description` renders tooltip content in a hidden element and again in the visible tooltip. WC-3404 asks for no other change in behavior, but this has side effects: + +- While the tooltip is open, custom content exists twice, which can duplicate widget side effects and ids. +- Focusable elements in custom content stay tabbable while hidden, because the element is only visually hidden. Keyboard users can land on invisible content inside `aria-hidden`. +- In Studio Pro, the preview is always open, so the custom content drop zone renders twice. +- `hasTooltipContent` ignores the render method. In Text mode with widgets left in the custom content slot and no text, the trigger gets an empty description and an empty tooltip can open. + +## What Changes + +- Render one content element, visually hidden while closed and shown as the tooltip while open. +- Make closed content inert, so it cannot receive focus. +- Decide whether content exists from the selected render method only. +- Do not manage `aria-describedby` in the Studio Pro preview. +- Make the "no tooltip content" unit test check the trigger element instead of its parent. + +## Capabilities + +### New Capabilities + + + +### Modified Capabilities + +- `tooltip-screen-reader-description`: Content is rendered once, closed content cannot take focus, and content follows the selected render method. + +## Impact + +- `src/components/Tooltip.tsx`, `src/components/__tests__/Tooltip.spec.tsx` and its snapshot. +- No XML, typings, dependency or changelog changes beyond the existing "Fixed" entry. +- Depends on `fix-tooltip-screen-reader-description`, so archive that change first. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/specs/tooltip-screen-reader-description/spec.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/specs/tooltip-screen-reader-description/spec.md new file mode 100644 index 0000000000..c2d5349131 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/specs/tooltip-screen-reader-description/spec.md @@ -0,0 +1,41 @@ +## MODIFIED Requirements + +### Requirement: Tooltip content is available before the tooltip opens + +When the content for the selected render method exists, the widget SHALL keep exactly one content element in the DOM, whether or not the tooltip is open. While closed, the element SHALL be visually hidden, have `aria-hidden="true"` and be `inert`. While open, it SHALL be shown as the tooltip without those states. When the selected render method has no content, the widget SHALL NOT render the element. + +#### Scenario: Tooltip is closed + +- **WHEN** the selected render method has content and the tooltip is closed +- **THEN** the content element is in the DOM, visually hidden, `aria-hidden` and `inert` + +#### Scenario: Tooltip is open + +- **WHEN** the tooltip opens +- **THEN** the same element is shown as the tooltip and the content appears exactly once in the DOM + +#### Scenario: Custom content contains a focusable element + +- **WHEN** the tooltip is closed and custom content contains a button +- **THEN** pressing Tab does not move focus to that button + +#### Scenario: Custom widgets across open and close + +- **WHEN** the tooltip opens and closes +- **THEN** custom widgets stay mounted and are not remounted + +#### Scenario: Text mode with leftover custom content + +- **WHEN** the render method is `text`, the text is empty and custom widgets are configured +- **THEN** the content element is not rendered and no description is added + +## ADDED Requirements + +### Requirement: Studio Pro preview is not affected by the description + +The widget SHALL render preview content once and SHALL NOT manage `aria-describedby` in the Studio Pro preview. + +#### Scenario: Custom content in preview + +- **WHEN** the widget renders in preview with the `custom` render method +- **THEN** the custom content drop zone appears once and trigger elements get no tooltip description diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/tasks.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/tasks.md new file mode 100644 index 0000000000..2f0e98acfd --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/unify-tooltip-content-rendering/tasks.md @@ -0,0 +1,27 @@ +## 1. Implementation + +- [x] 1.1 In `src/components/Tooltip.tsx`, derive `content` from `renderMethod` and use it for the content check +- [x] 1.2 Replace the two content elements with one that switches between closed and open state +- [x] 1.3 Attach `refs.setFloating`, floating styles and the arrow only while open +- [x] 1.4 Use the id from `getFloatingProps()` for `aria-describedby` and remove `useId` +- [x] 1.5 Toggle `inert` on the content element based on `showTooltip` +- [x] 1.6 Skip `aria-describedby` management when `preview` is set + +## 2. Unit tests + +- [x] 2.1 Test that open custom content renders exactly once, and that a custom widget does not remount on open and close +- [x] 2.2 Test that closed content is `inert` and `aria-hidden`, and that an open tooltip is neither +- [x] 2.3 Test that a button in closed custom content is inside the `inert` element (jsdom ignores `inert` when tabbing, so task 3.4 covers real focus) +- [x] 2.4 Test that Text mode with empty text and custom content adds no description and renders no content +- [x] 2.5 Test that preview mode renders content once and adds no `aria-describedby` +- [x] 2.6 Make the "no tooltip content" test check the trigger element +- [x] 2.7 Update the snapshot and check that its diff shows only the expected change +- [x] 2.8 `pnpm run test` and `pnpm run lint` pass in `packages/pluggableWidgets/tooltip-web` + +## 3. Manual QA + +- [ ] 3.1 Tooltip opens, closes and positions as on `main` in all `Open on` modes +- [ ] 3.2 VoiceOver and NVDA announce text and custom content on focus with the tooltip closed and open +- [ ] 3.3 Custom content with a data-loading widget: one request and no duplicate ids +- [ ] 3.4 Custom content with a link or button: closed content takes no focus, open content is usable +- [ ] 3.5 Studio Pro preview shows one custom content drop zone diff --git a/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx b/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx index 3d8b520b20..3d1e393341 100644 --- a/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx +++ b/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx @@ -1,6 +1,15 @@ import { Placement } from "@floating-ui/react"; import classNames from "classnames"; -import { CSSProperties, ReactElement, ReactNode, useState } from "react"; +import { + CSSProperties, + ReactElement, + ReactNode, + useCallback, + useEffect, + useLayoutEffect, + useRef, + useState +} from "react"; import { OpenOnEnum, RenderMethodEnum } from "../../typings/TooltipProps"; import { useFloatingUI } from "../utils/useFloatingUI"; @@ -18,10 +27,29 @@ export interface TooltipProps { preview?: boolean; } +const FOCUSABLE_SELECTOR = 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])'; + +const MEDIA_SELECTOR = "img, svg, video, canvas, iframe, input, select, textarea"; + +const getDescribedByIds = (element: HTMLElement): string[] => + element.getAttribute("aria-describedby")?.split(/\s+/).filter(Boolean) ?? []; + +const hasRenderedContent = (element: HTMLElement): boolean => + !!element.textContent?.trim() || !!element.querySelector(MEDIA_SELECTOR); + export const Tooltip = (props: TooltipProps): ReactElement => { const { trigger, htmlMessage, textMessage, openOn, position, preview, renderMethod } = props; const [showTooltip, setShowTooltip] = useState(preview ?? false); const [arrowElement, setArrowElement] = useState(null); + const [hasVisibleContent, setHasVisibleContent] = useState(false); + const content = renderMethod === "text" ? textMessage : htmlMessage; + const hasTooltipContent = renderMethod === "text" ? !!textMessage?.trim() : !!htmlMessage; + // The preview always shows its content so the drop zone stays usable + const isContentVisible = !!preview || hasVisibleContent; + const isOpen = showTooltip && isContentVisible; + const triggerWrapperRef = useRef(null); + const contentRef = useRef(null); + const { arrowStyles, blurFocusEvents, @@ -33,33 +61,124 @@ export const Tooltip = (props: TooltipProps): ReactElement => { staticSide } = useFloatingUI({ position, - showTooltip, + showTooltip: isOpen, setShowTooltip, arrowElement, openOn }); + const floatingProps = getFloatingProps?.(openOn === "hoverFocus" ? floatingFocusEvents : undefined); + const contentId = floatingProps?.id as string | undefined; + + // Add the tooltip to the aria-describedby of all focusable elements inside the trigger wrapper. + // Trigger widgets can render late or reset the attribute, so keep watching the wrapper. + useEffect(() => { + const wrapper = triggerWrapperRef.current; + if (preview || !hasTooltipContent || !hasVisibleContent || !contentId || !wrapper) { + return; + } + + // Elements of a nested tooltip get that tooltip's description, not this one + const owner = wrapper.closest(".widget-tooltip"); + + const applyDescription = (): void => { + wrapper.querySelectorAll(FOCUSABLE_SELECTOR).forEach(element => { + if (element.closest(".widget-tooltip") !== owner) { + return; + } + const ids = getDescribedByIds(element); + if (!ids.includes(contentId)) { + element.setAttribute("aria-describedby", [...ids, contentId].join(" ")); + } + }); + }; + + applyDescription(); + const observer = new MutationObserver(applyDescription); + observer.observe(wrapper, { + attributes: true, + attributeFilter: ["aria-describedby", "href", "tabindex"], + childList: true, + subtree: true + }); + + return () => { + observer.disconnect(); + wrapper.querySelectorAll("[aria-describedby]").forEach(element => { + const ids = getDescribedByIds(element).filter(id => id !== contentId); + if (ids.length > 0) { + element.setAttribute("aria-describedby", ids.join(" ")); + } else { + element.removeAttribute("aria-describedby"); + } + }); + }; + }, [hasTooltipContent, hasVisibleContent, contentId, preview]); + + // Merge our ref with floating-ui's ref + const setTriggerRef = useCallback( + (node: HTMLDivElement | null) => { + triggerWrapperRef.current = node; + if (refs?.setReference) { + refs.setReference(node); + } + }, + [refs] + ); + + // Floating UI only tracks the content while the tooltip is open + const setContentRef = useCallback( + (node: HTMLDivElement | null) => { + contentRef.current = node; + refs?.setFloating?.(isOpen ? node : null); + }, + [refs, isOpen] + ); + + // Custom widgets can be hidden by conditional visibility, so check what the content actually renders + useLayoutEffect(() => { + const element = contentRef.current; + if (!element) { + setHasVisibleContent(false); + return; + } + + const updateVisibleContent = (): void => setHasVisibleContent(hasRenderedContent(element)); + updateVisibleContent(); + const observer = new MutationObserver(updateVisibleContent); + observer.observe(element, { characterData: true, childList: true, subtree: true }); + + return () => observer.disconnect(); + }, [hasTooltipContent]); return (
{trigger}
- {showTooltip && (textMessage || htmlMessage) ? ( + {/* Always in the DOM so aria-describedby can reference it, display: none while closed */} + {hasTooltipContent ? ( } textMessage={undefined} /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const triggerElement = screen.getByTestId("tooltip-trigger"); + + expect(triggerElement).not.toHaveAttribute("aria-describedby"); + + await user.click(triggerElement); + expect(screen.queryByText("Custom content")).toBeNull(); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("renders preview content once without adding a description", () => { + render( + Drop zone
} + textMessage={undefined} + /> + ); + + expect(screen.getAllByText("Drop zone")).toHaveLength(1); + expect(screen.getByTestId("tooltip-trigger")).not.toHaveAttribute("aria-describedby"); + }); + + it("adds no description and does not open when custom content renders nothing", async () => { + const EmptyWidget = (): null => null; + render( + } + textMessage={undefined} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const triggerElement = screen.getByTestId("tooltip-trigger"); + + expect(triggerElement).not.toHaveAttribute("aria-describedby"); + + await user.click(triggerElement); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("follows custom content as it is shown and hidden", async () => { + const ConditionalWidget = ({ visible }: { visible: boolean }): ReactElement | null => + visible ? Conditional content : null; + const renderTooltip = (visible: boolean): ReactElement => ( + } + textMessage={undefined} + /> + ); + const { rerender } = render(renderTooltip(false)); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const triggerElement = screen.getByTestId("tooltip-trigger"); + + await act(async () => { + rerender(renderTooltip(true)); + }); + expect(triggerElement).toHaveAttribute("aria-describedby", getContentElement()?.id); + + await user.click(triggerElement); + expect(screen.getByRole("tooltip")).toHaveTextContent("Conditional content"); + + await act(async () => { + rerender(renderTooltip(false)); + }); + expect(triggerElement).not.toHaveAttribute("aria-describedby"); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("renders no content and adds no description for whitespace-only text", () => { + render(); + + expect(getContentElement()).toBeNull(); + expect(screen.getByTestId("tooltip-trigger")).not.toHaveAttribute("aria-describedby"); + }); + + it("treats custom content with only an image as visible", () => { + render( + } + textMessage={undefined} + /> + ); + + expect(screen.getByTestId("tooltip-trigger")).toHaveAttribute("aria-describedby", getContentElement()?.id); + }); + + it("shows empty custom content in preview", () => { + const EmptyWidget = (): null => null; + render( + } + textMessage={undefined} + /> + ); + + expect(getContentElement()).toBeInTheDocument(); + expect(getContentElement()).not.toHaveAttribute("hidden"); + }); + + it("adds aria-describedby to all focusable elements in trigger", () => { + render( + + + + + Link + + + } + /> + ); + + const button1 = screen.getByTestId("button1"); + const button2 = screen.getByTestId("button2"); + const link = screen.getByTestId("link1"); + + // All focusable elements should have aria-describedby + expect(button1).toHaveAttribute("aria-describedby"); + expect(button2).toHaveAttribute("aria-describedby"); + expect(link).toHaveAttribute("aria-describedby"); + + // All should point to the same sr-only content + const ariaDescribedBy1 = button1.getAttribute("aria-describedby"); + const ariaDescribedBy2 = button2.getAttribute("aria-describedby"); + const ariaDescribedBy3 = link.getAttribute("aria-describedby"); + + expect(ariaDescribedBy1).toBe(ariaDescribedBy2); + expect(ariaDescribedBy2).toBe(ariaDescribedBy3); + }); + + it("does not add its description to elements of a nested tooltip", () => { + render( + + Inside inner tooltip} + trigger={} + /> + + } + /> + ); + + const innerButton = screen.getByRole("button", { name: "Inner button" }); + const describedBy = innerButton.getAttribute("aria-describedby")?.split(" ") ?? []; + + expect(describedBy).toHaveLength(1); + expect(document.getElementById(describedBy[0])).toHaveTextContent("Inside inner tooltip"); + expect(screen.getByText("Inside inner tooltip")).not.toHaveAttribute("aria-describedby"); + }); + + it("keeps an existing aria-describedby and restores it when the content is removed", () => { + const trigger = ; + const { rerender } = render(); + const input = screen.getByTestId("input"); + const contentId = getContentElement()?.id; + + expect(input).toHaveAttribute("aria-describedby", `help-text ${contentId}`); + + rerender(); + + expect(input).toHaveAttribute("aria-describedby", "help-text"); + }); + + it("removes aria-describedby when it only contained the tooltip", () => { + const trigger = ; + const { rerender } = render(); + + rerender(); + + expect(screen.getByTestId("button")).not.toHaveAttribute("aria-describedby"); + }); + + it("adds aria-describedby to focusable elements that mount later", async () => { + const { rerender } = render(Loading} />); + const contentId = getContentElement()?.id; + + await act(async () => { + rerender(Button} />); + }); + + expect(screen.getByTestId("button")).toHaveAttribute("aria-describedby", contentId); + }); + + it("adds the tooltip back when the trigger resets aria-describedby", async () => { + render(Button} />); + const button = screen.getByTestId("button"); + const contentId = getContentElement()?.id; + + await act(async () => { + button.setAttribute("aria-describedby", "validation-message"); + }); + + expect(button).toHaveAttribute("aria-describedby", `validation-message ${contentId}`); + }); + }); }); diff --git a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/__snapshots__/Tooltip.spec.tsx.snap b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/__snapshots__/Tooltip.spec.tsx.snap index 0cd7f01fc3..59eb078455 100644 --- a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/__snapshots__/Tooltip.spec.tsx.snap +++ b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/__snapshots__/Tooltip.spec.tsx.snap @@ -10,6 +10,7 @@ exports[`Tooltip render DOM structure 1`] = ` class="widget-tooltip-trigger" >