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
18 changes: 18 additions & 0 deletions packages/pluggableWidgets/tooltip-web/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

## [Unreleased]

### Changed

- New Tooltip widgets now default to Open on Hover,focus, so keyboard users can see the tooltip. Existing widgets keep their setting.

### 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.

- We fixed an issue where holding Enter on a trigger in Click mode made the tooltip flicker.

- We fixed an issue where a click in a text box or on a check box in Click mode closed the tooltip. A click there now opens the tooltip but doesn't close it.

- We fixed an issue where Enter or Space on a tooltip nested inside another Click tooltip also opened the outer tooltip.

- We fixed an issue where pressing Escape while focus was inside custom tooltip content moved focus to the top of the page. Focus now returns to the trigger.

- 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.

## [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-11
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
## Context

The Tooltip widget uses Floating UI (`@floating-ui/react` 0.26.28) for its interactions. `useFloatingUI.ts` sets up the hooks per **Open on** mode:

- `useHover` is enabled for `hover` and `hoverFocus`.
- `useFocus` is enabled only for `hoverFocus`. `Tooltip.tsx` also passes `blurFocusEvents` (`onFocus` opens, `onBlur` closes) for `hoverFocus`.
- `useClick` is enabled only for `click`.
- `useDismiss` (Escape and outside press) and `useRole("tooltip")` are always on.

The reference props sit on the `widget-tooltip-trigger` wrapper `div`, not on the focusable element inside it.

`Tooltip.xml` sets `openOn` to `hover` by default, so a new Tooltip doesn't open on keyboard focus.

We reproduced both problems in a running app (SampleWidgetProject, page `TooltipTest.Tooltip_Focus_WC3663`, Tooltip 1.4.2 and 1.5.1, Chrome):

- **Hover**: tabbing to a trigger opens nothing, and mouse hover works. This is the intended Hover behavior.
- **Hover,focus**: Tab opens the tooltip. Escape closes it, and focus stays on the button.
- **Click, action button with no action**: a mouse click opens the tooltip. Enter and Space don't. The button dispatches `keydown` and `keyup` but no `click` for Enter, while a plain `<button>` on the same page does dispatch `click`. `useClick` ignores `keydown` on `BUTTON` targets (`isButtonTarget`) because it expects that native click.
- **Click, action button with an action**: nothing opens the tooltip, not even a mouse click. The button stops propagation of `click` and `keydown`, so the bubble-phase handlers on the wrapper never run. The button's action itself runs normally.

WC-3404 (PR 2175, open) rewrites most of `Tooltip.tsx`, so the content stays in the DOM as a visually hidden description. This change doesn't touch `Tooltip.tsx`.

## Goals / Non-Goals

**Goals:**

- New Tooltip widgets open on hover and keyboard focus by default.
- In Click mode, a mouse click, Enter and Space toggle the tooltip on any Mendix trigger, and the trigger's own action still runs.
- Escape closes the tooltip in every mode without moving focus.

**Non-Goals:**

- Changing `Hover` behavior. It stays mouse-only. WC-3663 decided to keep `Hover` and `Hover,focus` as separate options.
- Migrating existing widgets from `Hover` to `Hover,focus`. App developers choose the option.
- Making a trigger that contains no focusable element focusable, for example by adding `tabindex` to the wrapper.
- Opening a Click-mode tooltip on focus alone.

## Decisions

### 1. Change the default instead of the Hover behavior

Set `defaultValue="hoverFocus"` on `openOn` in `Tooltip.xml`, and leave the hover and focus code as it is.

- **Why**: it gives keyboard users the tooltip in the default configuration, and keeps `Hover` as an explicit mouse-only choice. Existing apps don't change behavior.
- **Checked**: after updating the widget definition in the sample project (`mxcli fix widgets`), all existing tooltips kept their stored `openOn` value (`hover`, `hoverFocus`, `click`). Mendix stores enumeration values on each widget, so a new default only applies when a widget is added. Studio Pro's **Update widget** wasn't checked separately.
- **Alternative**: make `Hover` open on focus too. This was implemented first, and then rejected in WC-3663 so the two options stay distinct.

### 2. Click mode handles click and keys itself, in the capture phase

Replace `useClick` with a `useKeyboardClick` hook in `src/utils/useKeyboardClick.ts`. It returns reference props that run in the capture phase:

- `onKeyDownCapture`: on Enter on a button or link (`button`, `a[href]`, `input` of type button, submit or reset, `[role="button"]`, `[role="link"]`), toggle the tooltip and record that a key toggled it. On Space on such a target, mark that the key went down.
- `onKeyUpCapture`: on Space marked on keydown, toggle the tooltip and record the toggle. This follows native button activation, which happens on keyup for Space.
- `onClickCapture`: toggle the tooltip, unless a key press already toggled it for this activation. In that case, clear the record and skip.
- `onPointerDownCapture` and `onBlur` clear the record, so a stale record can't swallow a later mouse click. This matters for buttons that dispatch no `click` after a key press.

The handlers never stop propagation or prevent default. Text inputs and other typeable elements never match the selector, so typing doesn't toggle the tooltip.

- **Why capture phase**: a Mendix action button with an action stops propagation of `click` and `keydown`. Capture-phase handlers on the wrapper run before the button's own handlers, so they always see the event. Because they don't block it, the button's action runs as before.
- **Why handle keys directly**: some trigger widgets dispatch a native `click` for Enter and Space, and some don't. Handling the key works for both, and the record of a key toggle stops a double toggle.
- **Why not ignore `click` with `event.detail === 0`**: screen readers activate controls with a synthetic `click` with `detail === 0`, often with no key events. Ignoring those would break the tooltip for screen reader users.
- **Why not keep `useClick` and add handlers**: Floating UI runs every merged handler, so ours couldn't stop `useClick` from toggling a second time. `useClick` also listens in the bubble phase, which doesn't fix the action-button case.

`useDismiss` stays as it is, so Escape and outside press keep closing the tooltip.

### 3. Update the Open on description

The description explains the options: "How the tooltip is triggered. Hover,focus opens it on mouse hover and on keyboard focus, so keyboard users can see it. Hover opens it on mouse hover only. Click opens it on click, Enter or Space. On mobile devices, hover is triggered on touch." Changing the description and the default doesn't change `typings/TooltipProps.d.ts`.

## Risks / Trade-offs

- [Existing apps that use `Hover` stay inaccessible to keyboard users.] → This was decided in WC-3663. The new description tells app developers why to pick `Hover,focus`, and the docs page will say the same.
- [Click-mode tooltips on action buttons now open, where before they never did. This could surprise apps that relied on the tooltip not opening.] → That earlier behavior was a bug. The CHANGELOG states the fix.
- [Capture-phase handlers run even when a trigger widget wants to stop the event, for example a widget that handles Enter itself.] → The handlers only toggle the tooltip and don't block the event, so the widget's own handling is unaffected. Only buttons and links match for keys.
- [The button-or-link check could miss custom widgets that render a `div` with a click handler and no role.] → Such elements aren't keyboard-operable on their own either. Widgets that set `role="button"` are covered.
- [Merge conflict with PR 2175 in `useFloatingUI.ts` if it changes the hook list.] → Rebase after it merges.

## Migration Plan

No migration. The XML keys and typings don't change, and existing widgets keep their stored **Open on** value. To roll back, install the previous widget version.

## Open Questions

- Should the WC-3663 acceptance criteria in Jira be rewritten to match this decision? They still say Hover mode opens on focus.
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## Why

With the default settings, keyboard users can't reach tooltip content (WC-3663). The default **Open on** value is `Hover`, which opens the tooltip on mouse hover only, so a keyboard user who tabs to the trigger sees nothing. The Deque tooltip pattern says a tooltip must open on both focus and hover. `Hover,focus` already does this. A second problem also blocks keyboard users: in `Click` mode, the tooltip doesn't open when the trigger is a Mendix action button. With an action set, it doesn't open on click, Enter or Space. With no action, it doesn't open on Enter or Space.

`Hover` and `Hover,focus` stay separate options, and `Hover` keeps opening on mouse hover only. This is a product decision made in WC-3663: app developers keep the choice, and existing apps don't change behavior.

We reproduced both problems in a running app with Tooltip 1.4.2. In Hover mode, tooltips opened on mouse hover but not on Tab. `Hover,focus` opened on focus, and Escape closed it. The Click-mode tooltip on an action button didn't open from the keyboard, and on a button with an action it didn't open on mouse click either.

## What Changes

- The default **Open on** value changes from `Hover` to `Hover,focus`, so new Tooltip widgets open on keyboard focus. Widgets already in apps keep their stored value.
- `Hover` and `Hover,focus` behave as before.
- In `Click` mode, the tooltip toggles on click, Enter and Space on a button or link inside the trigger. This also works when the trigger dispatches no native `click` for the key, or stops propagation of the event. The trigger's own action still runs.
- The **Open on** description in `Tooltip.xml` explains the difference between the options.
- CHANGELOG "Changed" and "Fixed" entries.

## Capabilities

### New Capabilities

- `tooltip-keyboard-access`: Keyboard users can open the tooltip with the default settings and in Click mode, following the Deque tooltip pattern.

### Modified Capabilities

<!-- None: tooltip-web has no archived specs on main. WC-3404 (PR 2175) adds `tooltip-screen-reader-description`, which this change doesn't modify. -->

## Impact

- `src/Tooltip.xml`: the `openOn` default value and description. No new keys or values, so `typings/TooltipProps.d.ts` doesn't change.
- `src/utils/useFloatingUI.ts` and a new `src/utils/useKeyboardClick.ts`: Click-mode interaction.
- `src/components/__tests__/Tooltip.spec.tsx` and `e2e/Tooltip.spec.js`: new keyboard tests.
- `CHANGELOG.md`. At release, the new default calls for a minor version bump.
- Docs follow-up: the **Open on** section of the Tooltip page in `mendix/docs`, including the new default.
- Jira follow-up: WC-3663's acceptance criteria still say Hover mode opens on focus. Update them to match this decision.
- Depends on WC-3404 (PR 2175), which also changes `Tooltip.tsx` and `useFloatingUI.ts`. Rebase this change onto it after it merges.
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
## ADDED Requirements

### Requirement: New widgets open on hover and focus by default

The default value of **Open on** SHALL be `Hover,focus`. A widget that already has a stored **Open on** value SHALL keep it.

#### Scenario: Add a new Tooltip

- **WHEN** an app developer adds a new Tooltip widget to a page
- **THEN** **Open on** is `Hover,focus`

#### Scenario: Existing widget set to Hover

- **WHEN** an app that has a Tooltip with **Open on** set to `Hover` updates to this widget version
- **THEN** the widget keeps `Hover` and opens on mouse hover only

### Requirement: Hover,focus opens on keyboard focus

When **Open on** is `Hover,focus`, the widget SHALL open the tooltip when an element inside the trigger receives focus, and SHALL keep it open while focus stays inside the trigger. Focus SHALL stay on the trigger element. Moving focus out of the trigger SHALL close the tooltip.

#### Scenario: Tab to a button

- **WHEN** **Open on** is `Hover,focus` and the user presses Tab until a button inside the trigger has focus
- **THEN** the tooltip opens, and focus stays on the button

#### Scenario: Tab to a text box

- **WHEN** **Open on** is `Hover,focus` and the user tabs into a text box inside the trigger and types
- **THEN** the tooltip opens and stays open while the user types

#### Scenario: Custom content

- **WHEN** the render method is `custom`, **Open on** is `Hover,focus`, and a button inside the trigger receives focus
- **THEN** the tooltip shows the custom content, and focus doesn't move into the tooltip

#### Scenario: Tab past the trigger

- **WHEN** the tooltip is open because its trigger has focus, and the user presses Tab to move focus past the trigger
- **THEN** the tooltip closes

### Requirement: Hover opens on mouse hover only

When **Open on** is `Hover`, the widget SHALL open and close the tooltip on pointer enter and leave, and SHALL NOT open it on focus.

#### Scenario: Hover with the mouse

- **WHEN** **Open on** is `Hover` and the pointer enters the trigger
- **THEN** the tooltip opens, and it closes when the pointer leaves the trigger and the tooltip

#### Scenario: Tab to the trigger

- **WHEN** **Open on** is `Hover` and the user tabs to a button inside the trigger
- **THEN** the tooltip stays closed

### Requirement: Escape dismisses the tooltip without moving focus

In every **Open on** mode, the widget SHALL close an open tooltip when the user presses Escape, and focus SHALL stay on the element that had it.

#### Scenario: Escape while the trigger has focus

- **WHEN** a tooltip is open and a button inside its trigger has focus, and the user presses Escape
- **THEN** the tooltip closes and the button keeps focus

#### Scenario: Escape doesn't reopen on the same focus

- **WHEN** the user closed a `Hover,focus` tooltip with Escape and the trigger still has focus
- **THEN** the tooltip stays closed until focus leaves and returns, or the pointer hovers the trigger

### Requirement: Click mode works with the mouse and the keyboard

When **Open on** is `Click`, the widget SHALL toggle the tooltip on a mouse click inside the trigger, and when the user presses Enter or Space on a button or link inside the trigger. This SHALL also work when that element doesn't dispatch a native `click` event for the key, or stops propagation of the event. The widget SHALL NOT stop propagation or prevent default, so the trigger's own action runs. A single activation SHALL toggle the tooltip once. Enter and Space typed in a text input inside the trigger SHALL NOT toggle the tooltip. Focus alone SHALL NOT open the tooltip in Click mode.

#### Scenario: Enter on a Mendix action button

- **WHEN** **Open on** is `Click`, a Mendix action button inside the trigger has focus, and the user presses Enter
- **THEN** the tooltip opens

#### Scenario: Space on a Mendix action button

- **WHEN** **Open on** is `Click`, a Mendix action button inside the trigger has focus, and the user presses Space
- **THEN** the tooltip opens

#### Scenario: Button action still runs

- **WHEN** **Open on** is `Click`, the trigger is a Mendix action button whose action shows a hidden container, and the user clicks it or presses Enter or Space on it
- **THEN** the tooltip toggles and the container is shown, each once per activation

#### Scenario: Trigger stops event propagation

- **WHEN** **Open on** is `Click` and the trigger element stops propagation of `click` and `keydown`, as a Mendix action button with an action does
- **THEN** a mouse click, Enter and Space still toggle the tooltip

#### Scenario: Native button doesn't double toggle

- **WHEN** **Open on** is `Click`, a native button that dispatches `click` for Enter has focus, and the user presses Enter
- **THEN** the tooltip opens and stays open

#### Scenario: Second key press closes

- **WHEN** a Click-mode tooltip is open and the user presses Enter again on the same button
- **THEN** the tooltip closes

#### Scenario: Typing in a text input

- **WHEN** **Open on** is `Click` and the user types a space or presses Enter in a text input inside the trigger
- **THEN** the tooltip doesn't change state

#### Scenario: Focus only

- **WHEN** **Open on** is `Click` and the user tabs to a button inside the trigger
- **THEN** the tooltip stays closed

### Requirement: Screen reader output is unchanged

Opening the tooltip by keyboard in Click mode SHALL NOT add live-region announcements, and SHALL NOT change the accessible name or description of the trigger elements.

#### Scenario: Enter opens a Click tooltip

- **WHEN** a screen reader user presses Enter on a button inside a `Click` trigger
- **THEN** the button's accessible name and description are the same as before this change, and the tooltip content isn't announced twice
Loading
Loading