Skip to content

Commit e333f0a

Browse files
committed
docs(tooltip-web): replace AGENTS.md with OpenSpec changes
1 parent a9eb655 commit e333f0a

12 files changed

Lines changed: 268 additions & 307 deletions

File tree

‎packages/pluggableWidgets/tooltip-web/AGENTS.md‎

Lines changed: 0 additions & 306 deletions
This file was deleted.

‎packages/pluggableWidgets/tooltip-web/CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
88

99
### Fixed
1010

11-
- We fixed an accessibility issue where tooltip content was not announced by screen readers. Tooltip text is now immediately accessible when focusing or hovering over trigger elements through the use of `aria-describedby` pointing to always-present sr-only content.
11+
- We fixed an issue where screen readers did not announce tooltip content on interactive elements.
1212

1313
## [1.5.1] - 2026-02-10
1414

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
schema: spec-driven
2+
created: 2026-11-02
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
## Context
2+
3+
`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.
4+
5+
## Goals / Non-Goals
6+
7+
**Goals:** expose tooltip content as the accessible description of focusable trigger elements, without changing how the tooltip looks or opens.
8+
9+
**Non-Goals:**
10+
11+
- Describing triggers that have no focusable elements.
12+
- Changing the Floating UI positioning or interaction hooks.
13+
14+
## Decisions
15+
16+
- **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.
17+
- **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.
18+
- **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.
19+
- **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.
20+
- **Use `.widget-tooltip-sr-only`.** A prefixed class avoids a global rule that would affect other widgets using `.sr-only`.
21+
22+
## Risks / Trade-offs
23+
24+
- [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).
25+
- [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).
26+
- [The observer runs on every DOM change in the trigger] → The callback is one query plus attribute checks, and it stops on cleanup.
27+
28+
## Open Questions
29+
30+
- Should Custom mode keep a second rendered copy of its widgets? This depends on the results of tasks 3.3 and 3.4.
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Why
2+
3+
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.
4+
5+
## What Changes
6+
7+
- Tooltip content is always in the DOM in a visually hidden, widget-prefixed element.
8+
- Focusable elements inside the trigger reference that element through `aria-describedby`.
9+
- Existing `aria-describedby` values on those elements are kept, and only the tooltip id is removed during cleanup.
10+
- Focusable elements that mount later, and elements whose attribute gets reset, receive the description through a `MutationObserver` on the trigger wrapper.
11+
- A CHANGELOG "Fixed" entry.
12+
13+
## Capabilities
14+
15+
### New Capabilities
16+
17+
- `tooltip-screen-reader-description`: Focusable elements in the tooltip trigger expose the tooltip content as their accessible description.
18+
19+
### Modified Capabilities
20+
21+
<!-- None: tooltip-web has no existing specs. -->
22+
23+
## Impact
24+
25+
- `src/components/Tooltip.tsx`, `src/ui/Tooltip.scss`, `src/components/__tests__/Tooltip.spec.tsx` and its snapshot, `CHANGELOG.md`.
26+
- No XML, typings or dependency changes.
27+
- Patch-level fix.

0 commit comments

Comments
 (0)