Skip to content

[WC-3663]: Default tooltip to Hover,focus and open Click tooltips from the keyboard - #2526

Merged
yordan-st merged 5 commits into
mainfrom
tooltip/open-on-keyboard-focus
Nov 18, 2026
Merged

yordan-st merged 5 commits into
mainfrom
tooltip/open-on-keyboard-focus

Conversation

@gjulivan

@gjulivan gjulivan commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Pull request type

Bug fix (non-breaking change which fixes an issue)


Description

Keyboard users can't see the tooltip with the default settings (WC-3663). The default Open on value is Hover, which opens on mouse hover only. The Deque tooltip pattern says a tooltip must open on both hover and focus.

We decided to keep Hover and Hover,focus as separate options, and to change the default instead:

  • Open on now defaults to Hover,focus. New tooltips open on keyboard focus. Existing widgets keep their stored value. Checked by updating the widget definition in a test app: all existing tooltips kept hover, hoverFocus or click.
  • Hover and Hover,focus behave as before. Only the Open on description is reworded to explain the difference.

While reproducing the issue, we found that Click mode didn't work with Mendix action buttons:

  • A button with no action dispatches no click for Enter, and Floating UI's useClick ignores keydown on buttons. Enter and Space did nothing.
  • A button with an action stops propagation of click and keydown. The tooltip didn't open at all, not even on a mouse click. The button's action still ran.

useClick is replaced with useKeyboardClick (src/utils/useKeyboardClick.ts). It toggles on click, Enter (keydown) and Space (keyup) for buttons and links, in the capture phase. It never stops propagation or prevents default, so the trigger's own action still runs. A key press records that it toggled the tooltip, so a native click that follows doesn't toggle it again. Text inputs never match, so typing doesn't toggle the tooltip.

The OpenSpec spec is in openspec/specs/tooltip-keyboard-access/, and the archived change with the design is in openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/.

Related: #2175 (WC-3404, screen reader description). That PR announces the tooltip to screen readers in every mode, and this one covers sighted keyboard users. They touch different source files (Tooltip.tsx there, useFloatingUI.ts here), so only CHANGELOG.md and Tooltip.spec.tsx should conflict.

Not done yet:

  • E2E tests. The tooltip-web test project needs pages with action button triggers in each mode.
  • Docs update for the Open on section of the Tooltip page, including the new default.

Unit tests (22, 15 new) and lint pass locally.

What should be covered while testing?

In an app with Tooltips on action buttons, one with an action and one with Do nothing:

  • A new Tooltip in Studio Pro has Open on set to Hover,focus
  • Update widget on an existing Hover tooltip keeps Hover
  • Hover: Tab doesn't open the tooltip, and mouse hover does
  • Hover,focus: Tab opens the tooltip, Tab past closes it, and Escape closes it with focus kept
  • Click: mouse click, Enter and Space toggle the tooltip on both buttons, and the button's action runs once per activation
  • Click: typing Space or Enter in a text box inside the trigger doesn't toggle the tooltip
  • Screen reader: opening a Click tooltip with Enter announces the content once

@gjulivan
gjulivan requested a review from a team as a code owner November 11, 2026 23:00
@github-actions

This comment has been minimized.

iobuhov
iobuhov previously approved these changes Nov 12, 2026
gjulivan and others added 2 commits November 16, 2026 09:30
…m the keyboard

Open on now defaults to Hover,focus, so new tooltips open on keyboard
focus. Existing widgets keep their stored value, and Hover stays
mouse-only.

Click mode toggles the tooltip on click, Enter and Space in the capture
phase. This also works for Mendix action buttons, which dispatch no
click for Enter and stop propagation of click and keydown when they
have an action. The trigger's own action still runs.

WC-3663

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
WC-3663

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yordan-st
yordan-st force-pushed the tooltip/open-on-keyboard-focus branch from c6e114b to 4c1d2f0 Compare November 16, 2026 09:13
@github-actions

This comment has been minimized.

Ignore repeated keydowns from a held key, only open (never close) on clicks
in form controls such as text boxes and check boxes, and ignore events from
a tooltip nested inside the trigger.
Move focus back to the trigger when Escape closes the tooltip while focus is
inside its content, and keep a Hover,focus tooltip open while focus moves
between the trigger and its content.
@github-actions

Copy link
Copy Markdown
Contributor

AI Code Review

✅ Approved — no issues found


What was reviewed

File Change
tooltip-web/src/Tooltip.xml openOn default changed from hover to hoverFocus, and the description reworded
tooltip-web/src/utils/useKeyboardClick.ts New hook. It toggles on click, Enter and Space in the capture phase, and replaces Floating UI's useClick
tooltip-web/src/utils/useFloatingUI.ts Uses useKeyboardClick. Focus returns to the trigger on Escape. The tooltip stays open while focus moves between the trigger and its content
tooltip-web/src/components/Tooltip.tsx Passes the floating blur handlers through to the tooltip content
tooltip-web/src/components/__tests__/Tooltip.spec.tsx 15 new unit tests
tooltip-web/CHANGELOG.md Entries under Unreleased
tooltip-web/openspec/** Per-package OpenSpec spec and archived changes

Skipped (out of scope): lockfiles and generated files.

CI: pending: Run code quality check, Plan E2E matrix, sigridci · unrelated failures: security/snyk (external scanner, while the code and license Snyk checks pass)


Questions

  • The E2E tests and the docs update are listed as not done. Will they land in this PR or in a follow-up? The changed keyboard behaviour in Click mode and Hover,focus mode has only unit-test coverage so far.

Positives

  • The new default only affects new widgets. Existing configurations keep their stored openOn value, and the PR says this was checked with Update widget in a test app. Because of that, I did not treat the default change as breaking.
  • useKeyboardClick never stops propagation or prevents default, so the trigger's own action still runs. It guards against double-toggling from a key press followed by a native click, against key repeat, and against nested tooltips.
  • The changelog entries are user-facing and follow the repo voice.

@yordan-st yordan-st self-assigned this Nov 16, 2026
@yordan-st
yordan-st merged commit 6e149d2 into main Nov 18, 2026
13 of 14 checks passed
@yordan-st
yordan-st deleted the tooltip/open-on-keyboard-focus branch November 18, 2026 12:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants