Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions packages/pluggableWidgets/tooltip-web/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-16
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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

<!-- None. -->

### 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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-02
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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

<!-- None: tooltip-web has no existing specs. -->

## 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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-02
Loading
Loading