From 4c8aeb7fe80f8cf54b822ca6247384c89190c762 Mon Sep 17 00:00:00 2001 From: gjulivan Date: Wed, 11 Nov 2026 23:59:30 +0100 Subject: [PATCH 1/5] fix(tooltip-web): default to hover and focus, open click tooltips from 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 --- .../pluggableWidgets/tooltip-web/CHANGELOG.md | 8 + .../tooltip-web/src/Tooltip.xml | 4 +- .../src/components/__tests__/Tooltip.spec.tsx | 256 +++++++++++++++++- .../tooltip-web/src/utils/useFloatingUI.ts | 4 +- .../tooltip-web/src/utils/useKeyboardClick.ts | 91 +++++++ 5 files changed, 358 insertions(+), 5 deletions(-) create mode 100644 packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts diff --git a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md index af5fada629..3a66c7b879 100644 --- a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md +++ b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md @@ -6,6 +6,14 @@ 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. + ## [1.5.1] - 2026-02-10 ### Added diff --git a/packages/pluggableWidgets/tooltip-web/src/Tooltip.xml b/packages/pluggableWidgets/tooltip-web/src/Tooltip.xml index d64c05a5e4..72ce7d2024 100644 --- a/packages/pluggableWidgets/tooltip-web/src/Tooltip.xml +++ b/packages/pluggableWidgets/tooltip-web/src/Tooltip.xml @@ -49,9 +49,9 @@ End - + Open on - How the tooltip is triggered - click, hover, hover and focus. On mobile device “hover” will be triggered on touch. + 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. Click Hover diff --git a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx index f4f221c772..6c15804914 100644 --- a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx +++ b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx @@ -2,6 +2,7 @@ import { act, render, screen } from "@testing-library/react"; import "@testing-library/jest-dom"; import userEvent from "@testing-library/user-event"; +import { ReactElement } from "react"; import { Tooltip, TooltipProps } from "../Tooltip"; jest.useFakeTimers(); @@ -51,7 +52,7 @@ describe("Tooltip", () => { await user.unhover(triggerElement); expect(screen.queryByRole("tooltip")).toBeNull(); - // focus + // focus: Hover opens on mouse hover only await user.keyboard("{Tab}"); expect(triggerElement).toEqual(document.activeElement); expect(screen.queryByRole("tooltip")).toBeNull(); @@ -62,6 +63,259 @@ describe("Tooltip", () => { expect(screen.queryByRole("tooltip")).toBeNull(); }); + describe("keyboard focus in Hover,focus mode", () => { + const buttonTrigger = ; + + it("opens on focus and closes on blur", async () => { + render(); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Trigger button" }); + + await user.keyboard("{Tab}"); + expect(button).toHaveFocus(); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard("{Tab}"); + expect(button).not.toHaveFocus(); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("stays open while the user types in a text box", async () => { + render(} />); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const input = screen.getByRole("textbox", { name: "Name" }); + + await user.keyboard("{Tab}"); + expect(input).toHaveFocus(); + await user.keyboard("Some text and spaces"); + expect(input).toHaveValue("Some text and spaces"); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + }); + + it("shows custom content on focus without moving focus into the tooltip", async () => { + render( + Custom content} + textMessage={undefined} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Trigger button" }); + + await user.keyboard("{Tab}"); + expect(screen.queryByRole("tooltip")).toHaveTextContent("Custom content"); + expect(button).toHaveFocus(); + }); + + it("Escape closes the tooltip, keeps focus and doesn't reopen", async () => { + render(); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Trigger button" }); + + await user.keyboard("{Tab}"); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard("{Escape}"); + expect(screen.queryByRole("tooltip")).toBeNull(); + expect(button).toHaveFocus(); + + act(() => { + jest.advanceTimersByTime(500); + }); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + }); + + describe("keyboard in click mode", () => { + // Like the Mendix action button: handles Enter and Space itself, so the browser dispatches no click + const NoNativeClickButton = (): ReactElement => ( + + ); + + it.each(["{Enter}", " "])("toggles with %s on a button that dispatches no click", async key => { + const clickSpy = jest.fn(); + render( + + + + } + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}"); + expect(screen.getByRole("button", { name: "Action button" })).toHaveFocus(); + expect(screen.queryByRole("tooltip")).toBeNull(); + + await user.keyboard(key); + expect(clickSpy).not.toHaveBeenCalled(); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard(key); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it.each(["{Enter}", " "])("toggles once with %s on a native button", async key => { + const clickSpy = jest.fn(); + render( + + Native button + + } + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}"); + await user.keyboard(key); + expect(clickSpy).toHaveBeenCalledTimes(1); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard(key); + expect(clickSpy).toHaveBeenCalledTimes(2); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + // Like a Mendix action button with an action: runs it and stops propagation of click and keydown + const ActionButton = ({ onAction }: { onAction: () => void }): ReactElement => ( + + ); + + it("opens on mouse click on a button that stops propagation, and the button action still runs", async () => { + const action = jest.fn(); + render(} />); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Button with action" }); + + await user.click(button); + expect(action).toHaveBeenCalledTimes(1); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.click(button); + expect(action).toHaveBeenCalledTimes(2); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it.each(["{Enter}", " "])( + "toggles with %s on a button that stops propagation, and the button action still runs", + async key => { + const action = jest.fn(); + render( + } /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}"); + await user.keyboard(key); + expect(action).toHaveBeenCalledTimes(1); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard(key); + expect(action).toHaveBeenCalledTimes(2); + expect(screen.queryByRole("tooltip")).toBeNull(); + } + ); + + it("opens on a synthetic click without key events, as screen readers send", () => { + render( + Native button} + /> + ); + + act(() => { + screen.getByRole("button", { name: "Native button" }).click(); + }); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + }); + + it("doesn't swallow a mouse click after a key toggle on a button that dispatches no click", async () => { + render(} />); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Action button" }); + + await user.keyboard("{Tab}"); + await user.keyboard("{Enter}"); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.click(button); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("doesn't toggle on Enter or Space in a text input, or on focus", async () => { + render(} />); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const input = screen.getByRole("textbox", { name: "Name" }); + + await user.keyboard("{Tab}"); + expect(input).toHaveFocus(); + expect(screen.queryByRole("tooltip")).toBeNull(); + + await user.keyboard("a b{Enter}"); + expect(input).toHaveValue("a b"); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("Escape closes the tooltip and keeps focus on the button", async () => { + render( + Native button} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const button = screen.getByRole("button", { name: "Native button" }); + + await user.keyboard("{Tab}"); + await user.keyboard("{Enter}"); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard("{Escape}"); + expect(screen.queryByRole("tooltip")).toBeNull(); + expect(button).toHaveFocus(); + }); + }); + it("open tooltip onClick", async () => { render(); const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); diff --git a/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts b/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts index 2b01bdb341..a62939f3d6 100644 --- a/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts +++ b/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts @@ -7,7 +7,6 @@ import { ReferenceElement, safePolygon, shift, - useClick, useDismiss, useFloating, UseFloatingReturn, @@ -17,6 +16,7 @@ import { useRole } from "@floating-ui/react"; import { Dispatch, SetStateAction, useCallback } from "react"; +import { useKeyboardClick } from "./useKeyboardClick"; import { OpenOnEnum } from "../../typings/TooltipProps"; interface FloatingProps { position: Placement; @@ -73,7 +73,7 @@ export function useFloatingUI(props: FloatingProps): FloatingPropsReturn { handleClose: safePolygon() }); const focus = useFocus(context, { enabled: openOn === "hoverFocus" }); - const click = useClick(context, { toggle: showTooltip, enabled: openOn === "click" }); + const click = useKeyboardClick(context, { enabled: openOn === "click" }); const dismiss = useDismiss(context, { outsidePress: true }); const role = useRole(context, { role: "tooltip" }); diff --git a/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts b/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts new file mode 100644 index 0000000000..8b0f1722c3 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts @@ -0,0 +1,91 @@ +import { ElementProps, FloatingRootContext } from "@floating-ui/react"; +import { KeyboardEvent, MouseEvent, useMemo, useRef } from "react"; + +// Elements that a user activates with Enter or Space. Text inputs and other typeable elements are left out on purpose. +const ACTIVATABLE_SELECTOR = [ + "button", + "a[href]", + 'input[type="button"]', + 'input[type="submit"]', + 'input[type="reset"]', + '[role="button"]', + '[role="link"]' +].join(","); + +function isActivatable(target: EventTarget | null): boolean { + return target instanceof HTMLElement && !target.isContentEditable && target.matches(ACTIVATABLE_SELECTOR); +} + +interface UseKeyboardClickProps { + enabled: boolean; +} + +/** + * Toggles the tooltip on click, Enter and Space. + * + * Floating UI's `useClick` relies on the browser dispatching a native `click` when Enter or Space is + * pressed on a button. Some trigger widgets, like the Mendix action button, handle those keys + * themselves and dispatch no `click`, so the tooltip never opened from the keyboard. + * This hook toggles on the key itself and skips the native `click` that may follow it. + * + * The handlers run in the capture phase: a Mendix action button with an action stops propagation + * of `click` and `keydown`, so bubble-phase handlers on the wrapper never see them. The handlers + * never stop propagation or prevent default, so the trigger's own action still runs. + */ +export function useKeyboardClick( + context: Pick, + { enabled }: UseKeyboardClickProps +): ElementProps { + const { open, onOpenChange } = context; + // Set when a key press toggled the tooltip, so the native click of the same activation is skipped + const keyToggledRef = useRef(false); + const spaceDownRef = useRef(false); + + const reference = useMemo(() => { + const toggle = (event: KeyboardEvent | MouseEvent): void => { + onOpenChange(!open, event.nativeEvent, "click"); + }; + + return { + onKeyDownCapture(event: KeyboardEvent) { + keyToggledRef.current = false; + if (!isActivatable(event.target)) { + return; + } + if (event.key === "Enter") { + keyToggledRef.current = true; + toggle(event); + } else if (event.key === " ") { + spaceDownRef.current = true; + } + }, + onKeyUpCapture(event: KeyboardEvent) { + if (event.key !== " " || !spaceDownRef.current) { + return; + } + spaceDownRef.current = false; + if (isActivatable(event.target)) { + keyToggledRef.current = true; + toggle(event); + } + }, + onPointerDownCapture() { + keyToggledRef.current = false; + spaceDownRef.current = false; + }, + onBlur() { + keyToggledRef.current = false; + spaceDownRef.current = false; + }, + onClickCapture(event: MouseEvent) { + if (keyToggledRef.current) { + keyToggledRef.current = false; + return; + } + toggle(event); + } + }; + }, [open, onOpenChange]); + + return useMemo(() => (enabled ? { reference } : {}), [enabled, reference]); +} From 4c1d2f05cde4daac55221c9901c533e46ab6f1c1 Mon Sep 17 00:00:00 2001 From: gjulivan Date: Wed, 11 Nov 2026 23:59:32 +0100 Subject: [PATCH 2/5] docs(tooltip-web): add OpenSpec spec for tooltip keyboard access WC-3663 Co-Authored-By: Claude Opus 5.5 --- .../.openspec.yaml | 2 + .../design.md | 84 ++++++++++++ .../proposal.md | 35 +++++ .../specs/tooltip-keyboard-access/spec.md | 120 +++++++++++++++++ .../tasks.md | 46 +++++++ .../tooltip-web/openspec/config.yaml | 20 +++ .../specs/tooltip-keyboard-access/spec.md | 126 ++++++++++++++++++ 7 files changed, 433 insertions(+) create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/.openspec.yaml create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/design.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/proposal.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/specs/tooltip-keyboard-access/spec.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/tasks.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/config.yaml create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/specs/tooltip-keyboard-access/spec.md diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/.openspec.yaml b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/.openspec.yaml new file mode 100644 index 0000000000..2a7773d65e --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-11 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/design.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/design.md new file mode 100644 index 0000000000..49c7677e72 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-11-open-tooltip-on-keyboard-focus/design.md @@ -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 `} + /> + ); + const button = screen.getByRole("button", { name: "Native button" }); + + // Holding a key sends one keydown, then repeated keydowns with repeat set + fireEvent.keyDown(button, { key: "Enter" }); + fireEvent.keyDown(button, { key: "Enter", repeat: true }); + fireEvent.keyDown(button, { key: "Enter", repeat: true }); + fireEvent.keyDown(button, { key: "Enter", repeat: true }); + fireEvent.keyUp(button, { key: "Enter" }); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + }); + + it("a click in a text box opens the tooltip and a second click doesn't close it", async () => { + render(} />); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const input = screen.getByRole("textbox", { name: "Name" }); + + await user.click(input); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + await user.click(input); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + }); + + it("Space on a check box opens the tooltip and doesn't close it on the next Space", async () => { + render( + } + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + const checkbox = screen.getByRole("checkbox", { name: "Agree" }); + + await user.keyboard("{Tab}"); + await user.keyboard(" "); + expect(checkbox).toBeChecked(); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard(" "); + expect(checkbox).not.toBeChecked(); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + }); + + it("Enter on a nested tooltip's trigger opens only the nested tooltip", async () => { + render( + + Inner button} + /> + + } + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}"); + expect(screen.getByRole("button", { name: "Inner button" })).toHaveFocus(); + await user.keyboard("{Enter}"); + expect(screen.getAllByRole("tooltip").map(tooltip => tooltip.textContent)).toEqual(["Inner text"]); + + await user.keyboard("{Enter}"); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); }); it("open tooltip onClick", async () => { diff --git a/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts b/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts index 8b0f1722c3..ba3030252f 100644 --- a/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts +++ b/packages/pluggableWidgets/tooltip-web/src/utils/useKeyboardClick.ts @@ -12,10 +12,34 @@ const ACTIVATABLE_SELECTOR = [ '[role="link"]' ].join(","); +// Form controls that a user types in or changes. A click on them opens the tooltip but never closes it, +// so moving the cursor in a text box or ticking a check box doesn't hide it. +const FORM_CONTROL_SELECTOR = "input, textarea, select, label"; + function isActivatable(target: EventTarget | null): boolean { return target instanceof HTMLElement && !target.isContentEditable && target.matches(ACTIVATABLE_SELECTOR); } +function isFormControl(target: EventTarget | null): boolean { + return ( + target instanceof HTMLElement && + !isActivatable(target) && + (target.isContentEditable || target.closest(FORM_CONTROL_SELECTOR) !== null) + ); +} + +/** + * True when the event comes from this tooltip's own trigger, not from a tooltip nested inside it. + * Without this check, Enter on a nested trigger toggles the outer tooltip too. + */ +function isOwnEvent(event: KeyboardEvent | MouseEvent): boolean { + const target = event.target; + if (!(target instanceof Element)) { + return false; + } + return target.closest(".widget-tooltip") === event.currentTarget.closest(".widget-tooltip"); +} + interface UseKeyboardClickProps { enabled: boolean; } @@ -45,11 +69,22 @@ export function useKeyboardClick( const toggle = (event: KeyboardEvent | MouseEvent): void => { onOpenChange(!open, event.nativeEvent, "click"); }; + const openOnly = (event: MouseEvent): void => { + if (!open) { + onOpenChange(true, event.nativeEvent, "click"); + } + }; return { onKeyDownCapture(event: KeyboardEvent) { keyToggledRef.current = false; - if (!isActivatable(event.target)) { + if (!isOwnEvent(event) || !isActivatable(event.target)) { + return; + } + if (event.repeat) { + // Holding a key sends repeated keydowns. Toggle once per press and skip the native + // click a repeated Enter dispatches on a button. + keyToggledRef.current = event.key === "Enter"; return; } if (event.key === "Enter") { @@ -60,7 +95,7 @@ export function useKeyboardClick( } }, onKeyUpCapture(event: KeyboardEvent) { - if (event.key !== " " || !spaceDownRef.current) { + if (event.key !== " " || !spaceDownRef.current || !isOwnEvent(event)) { return; } spaceDownRef.current = false; @@ -82,6 +117,13 @@ export function useKeyboardClick( keyToggledRef.current = false; return; } + if (!isOwnEvent(event)) { + return; + } + if (isFormControl(event.target)) { + openOnly(event); + return; + } toggle(event); } }; From d8bf2100dd2fb0919f71da6ee9fca84e69c37b89 Mon Sep 17 00:00:00 2001 From: Yordan Stoyanov Date: Mon, 16 Nov 2026 14:56:52 +0100 Subject: [PATCH 4/5] fix(tooltip-web): keep keyboard focus near the tooltip 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. --- .../pluggableWidgets/tooltip-web/CHANGELOG.md | 4 ++ .../tooltip-web/src/components/Tooltip.tsx | 26 ++++--- .../src/components/__tests__/Tooltip.spec.tsx | 72 +++++++++++++++++++ .../tooltip-web/src/utils/useFloatingUI.ts | 61 ++++++++++++++-- 4 files changed, 149 insertions(+), 14 deletions(-) diff --git a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md index 474d3ec83b..07f5584992 100644 --- a/packages/pluggableWidgets/tooltip-web/CHANGELOG.md +++ b/packages/pluggableWidgets/tooltip-web/CHANGELOG.md @@ -20,6 +20,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - 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 diff --git a/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx b/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx index 231885c1c3..3d8b520b20 100644 --- a/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx +++ b/packages/pluggableWidgets/tooltip-web/src/components/Tooltip.tsx @@ -22,14 +22,22 @@ 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 { arrowStyles, blurFocusEvents, floatingStyles, getFloatingProps, getReferenceProps, refs, staticSide } = - useFloatingUI({ - position, - showTooltip, - setShowTooltip, - arrowElement, - openOn - }); + const { + arrowStyles, + blurFocusEvents, + floatingFocusEvents, + floatingStyles, + getFloatingProps, + getReferenceProps, + refs, + staticSide + } = useFloatingUI({ + position, + showTooltip, + setShowTooltip, + arrowElement, + openOn + }); return (
@@ -47,7 +55,7 @@ export const Tooltip = (props: TooltipProps): ReactElement => { className="widget-tooltip-content" ref={refs?.setFloating} style={floatingStyles} - {...getFloatingProps?.()} + {...getFloatingProps?.(openOn === "hoverFocus" ? floatingFocusEvents : undefined)} data-overlay-content > {renderMethod === "text" ? textMessage : htmlMessage} diff --git a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx index 1ee3aaf604..c657e6b57e 100644 --- a/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx +++ b/packages/pluggableWidgets/tooltip-web/src/components/__tests__/Tooltip.spec.tsx @@ -128,6 +128,57 @@ describe("Tooltip", () => { }); expect(screen.queryByRole("tooltip")).toBeNull(); }); + + it("stays open while focus moves into custom content, and closes when focus leaves it", async () => { + render( + Inside tooltip} + textMessage={undefined} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}"); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard("{Tab}"); + act(() => { + jest.advanceTimersByTime(100); + }); + expect(screen.getByRole("button", { name: "Inside tooltip" })).toHaveFocus(); + expect(screen.queryByRole("tooltip")).toBeInTheDocument(); + + await user.keyboard("{Tab}"); + act(() => { + jest.advanceTimersByTime(100); + }); + expect(screen.queryByRole("tooltip")).toBeNull(); + }); + + it("Escape inside custom content closes the tooltip and moves focus back to the trigger", async () => { + render( + Inside tooltip} + textMessage={undefined} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}{Tab}"); + expect(screen.getByRole("button", { name: "Inside tooltip" })).toHaveFocus(); + + await user.keyboard("{Escape}"); + expect(screen.queryByRole("tooltip")).toBeNull(); + expect(screen.getByRole("button", { name: "Trigger button" })).toHaveFocus(); + }); }); describe("keyboard in click mode", () => { @@ -394,6 +445,27 @@ describe("Tooltip", () => { await user.keyboard("{Enter}"); expect(screen.queryByRole("tooltip")).toBeNull(); }); + + it("Escape inside custom content closes the tooltip and moves focus back to the trigger", async () => { + render( + Native button} + renderMethod="custom" + htmlMessage={} + textMessage={undefined} + /> + ); + const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime }); + + await user.keyboard("{Tab}{Enter}{Tab}"); + expect(screen.getByRole("button", { name: "Inside tooltip" })).toHaveFocus(); + + await user.keyboard("{Escape}"); + expect(screen.queryByRole("tooltip")).toBeNull(); + expect(screen.getByRole("button", { name: "Native button" })).toHaveFocus(); + }); }); it("open tooltip onClick", async () => { diff --git a/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts b/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts index a62939f3d6..a6d4124a60 100644 --- a/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts +++ b/packages/pluggableWidgets/tooltip-web/src/utils/useFloatingUI.ts @@ -15,7 +15,7 @@ import { useInteractions, useRole } from "@floating-ui/react"; -import { Dispatch, SetStateAction, useCallback } from "react"; +import { Dispatch, FocusEvent, SetStateAction, useCallback, useEffect, useRef } from "react"; import { useKeyboardClick } from "./useKeyboardClick"; import { OpenOnEnum } from "../../typings/TooltipProps"; interface FloatingProps { @@ -36,8 +36,24 @@ interface InternalFloatingProps { }; blurFocusEvents: { onFocus: () => void; - onBlur: () => void; + onBlur: (event: FocusEvent) => void; }; + floatingFocusEvents: { + onBlur: (event: FocusEvent) => void; + }; +} + +const FOCUSABLE_SELECTOR = [ + "button:not([disabled])", + "a[href]", + "input:not([disabled]):not([type='hidden'])", + "select:not([disabled])", + "textarea:not([disabled])", + "[tabindex]:not([tabindex='-1'])" +].join(","); + +function contains(parent: Element | null | undefined, child: EventTarget | null): boolean { + return !!parent && child instanceof Node && parent.contains(child); } type FloatingPropsReturn = Partial> & @@ -46,11 +62,29 @@ type FloatingPropsReturn = Partial> & export function useFloatingUI(props: FloatingProps): FloatingPropsReturn { const { position, showTooltip, setShowTooltip, arrowElement, openOn } = props; + const elementsRef = useRef<{ reference: Element | null; floating: HTMLElement | null }>({ + reference: null, + floating: null + }); + + const onOpenChange = useCallback( + (open: boolean, _event?: Event, reason?: string): void => { + const { reference, floating } = elementsRef.current; + // Escape removes the tooltip content. If focus was inside it, the browser drops focus to the + // top of the page, so move it back to the trigger first. + if (!open && reason === "escape-key" && contains(floating, document.activeElement)) { + reference?.querySelector(FOCUSABLE_SELECTOR)?.focus(); + } + setShowTooltip(open); + }, + [setShowTooltip] + ); + const { refs, floatingStyles, context, middlewareData, placement } = useFloating({ strategy: "fixed", placement: position, open: showTooltip, - onOpenChange: setShowTooltip, + onOpenChange, middleware: [ offset(8), flip({ @@ -77,9 +111,25 @@ export function useFloatingUI(props: FloatingProps): FloatingPropsReturn { const dismiss = useDismiss(context, { outsidePress: true }); const role = useRole(context, { role: "tooltip" }); + useEffect(() => { + elementsRef.current = { reference: refs.domReference.current, floating: refs.floating.current }; + }); + const onShow = useCallback(() => setShowTooltip(true), [setShowTooltip]); - const onHide = useCallback(() => setShowTooltip(false), [setShowTooltip]); - const blurFocusEvents = { onFocus: onShow, onBlur: onHide }; + // Keep the tooltip open while focus moves between the trigger and its content, so a keyboard user can + // reach a button inside custom content. Close it when focus leaves both. + const onFocusOut = useCallback( + (event: FocusEvent) => { + const next = event.relatedTarget; + if (contains(refs.domReference.current, next) || contains(refs.floating.current, next)) { + return; + } + setShowTooltip(false); + }, + [refs, setShowTooltip] + ); + const blurFocusEvents = { onFocus: onShow, onBlur: onFocusOut }; + const floatingFocusEvents = { onBlur: onFocusOut }; const side = placement.split("-")[0]; const alignment = placement.split("-")[1]; @@ -104,6 +154,7 @@ export function useFloatingUI(props: FloatingProps): FloatingPropsReturn { return { arrowStyles, blurFocusEvents, + floatingFocusEvents, floatingStyles, getFloatingProps, getReferenceProps, From 1245e4807cfc64866e5ffe8f84c34aa25dc60c32 Mon Sep 17 00:00:00 2001 From: Yordan Stoyanov Date: Mon, 16 Nov 2026 14:57:13 +0100 Subject: [PATCH 5/5] docs(tooltip-web): spec keyboard and focus fixes from QA --- .../.openspec.yaml | 2 + .../design.md | 28 +++++ .../proposal.md | 37 ++++++ .../specs/tooltip-keyboard-access/spec.md | 118 ++++++++++++++++++ .../tasks.md | 26 ++++ .../specs/tooltip-keyboard-access/spec.md | 43 ++++++- 6 files changed, 250 insertions(+), 4 deletions(-) create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/.openspec.yaml create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/design.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/proposal.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/specs/tooltip-keyboard-access/spec.md create mode 100644 packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/tasks.md diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/.openspec.yaml b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/.openspec.yaml new file mode 100644 index 0000000000..90080a9210 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-16 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/design.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/design.md new file mode 100644 index 0000000000..d7cd5e6d06 --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/design.md @@ -0,0 +1,28 @@ +## Context + +`useKeyboardClick` toggles a `Click` tooltip from capture-phase handlers on the trigger wrapper, so it sees events that the trigger widget stops. That made three problems possible: every repeated keydown toggled, every click in a form control toggled, and a nested tooltip's events also reached the outer wrapper. Separately, the tooltip content is rendered next to the trigger. When it is removed while it has focus, the browser moves focus to ``. The widget's own `onBlur` handler in `Hover,focus` mode closed the tooltip on any blur, including a move into the content. + +## Goals / Non-Goals + +**Goals:** + +- Fix the five QA findings on PR 2526 and the focus loss on Tab in `Hover,focus` mode. +- Keep the trigger's own action running once per activation. + +**Non-Goals:** + +- Escape handling across nested tooltips. Each tooltip still closes on its own Escape listener. A Floating UI `FloatingTree` would coordinate them, but no reported problem needs it. +- Making interactive custom content unreachable. See the open question in the proposal. + +## Decisions + +- **Key repeat:** skip keydowns with `event.repeat`. A repeated Enter on a native button still fires a `click`, so the repeat also sets the "key toggled" flag that skips that click. +- **Form controls open only:** a click on `input`, `textarea`, `select`, `label` or `contenteditable` that isn't a button opens the tooltip and never closes it. Alternative: ignore those clicks. Rejected, because a mouse user who clicks a text box trigger expects the tooltip, as before. +- **Nested tooltips:** a handler ignores an event when `event.target.closest(".widget-tooltip")` isn't the wrapper of the handling trigger. This also covers clicks inside a nested tooltip's content. +- **Focus return:** the `onOpenChange` passed to `useFloating` checks the close reason. On `escape-key` with focus inside the content, it focuses the first focusable element in the trigger before the content is removed. Other close reasons don't move focus. An outside click already moves focus where the user clicked. +- **Focus into content:** the widget's blur handlers on the trigger and on the content close the tooltip only when `relatedTarget` is outside both. Floating UI's `useFocus` already keeps the tooltip open in that case. + +## Risks / Trade-offs + +- [The first focusable element in the trigger isn't the one the user started from, when the trigger has several] → Acceptable: focus stays near the tooltip instead of jumping to the top of the page. +- [The DOM selector `.widget-tooltip` ties the nested-tooltip check to the widget's class name] → The class is part of the widget's styling contract and is stable. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/proposal.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/proposal.md new file mode 100644 index 0000000000..22d7d2e2ee --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/proposal.md @@ -0,0 +1,37 @@ +## Why + +QA on PR 2526 (WC-3663) found five keyboard and focus problems in the Tooltip changes, and a retest found a sixth. We reproduced all six in a running app (SampleWidgetProject, Mendix 11.12.0, Tooltip 1.5.1 built from the branch), by hand and with Playwright: + +1. In `Click` mode, holding Enter on a button made the tooltip flicker. Every repeated keydown toggled it. +2. In `Click` mode, the second click in a text box closed the tooltip, and the third reopened it. +3. In `Click` mode, Space on a check box toggled the check box and the tooltip together. +4. With a `Click` tooltip nested in another `Click` tooltip, Enter on the inner button opened both. Escape closed only the inner one, and after that each Enter swapped which one was open. +5. Escape while focus was on a button inside custom tooltip content closed the tooltip, and focus fell to the top of the page. +6. In `Hover,focus` mode, Tab from the trigger into custom tooltip content closed the tooltip, and focus fell to the top of the page. + +## What Changes + +- In `Click` mode, a held key toggles the tooltip once. Repeated keydowns are ignored. +- In `Click` mode, a click on a form control inside the trigger (text box, text area, drop-down, check box, radio button, label) opens the tooltip but doesn't close it. Buttons and links still toggle it. +- In `Click` mode, a tooltip ignores clicks and key presses that come from a tooltip nested inside its trigger. +- In every mode, when Escape closes the tooltip while focus is inside its content, focus moves to the first focusable element in the trigger. +- In `Hover,focus` mode, the tooltip stays open while focus moves between the trigger and the tooltip content, and closes when focus leaves both. +- CHANGELOG "Fixed" entries for each problem. + +## Capabilities + +### New Capabilities + + + +### Modified Capabilities + +- `tooltip-keyboard-access`: Hover,focus keeps the tooltip open while focus is in its content, Escape returns focus to the trigger from the content, and Click mode handles held keys, form controls and nested tooltips. + +## Impact + +- `src/utils/useKeyboardClick.ts`: key repeat, form controls, nested tooltips. +- `src/utils/useFloatingUI.ts` and `src/components/Tooltip.tsx`: focus return on Escape, and focus moving into the content in `Hover,focus` mode. +- `src/components/__tests__/Tooltip.spec.tsx`: seven new unit tests. +- `CHANGELOG.md`: five "Fixed" entries. +- Open question for the PR: custom content with a button stays reachable with Tab in `Click` and `Hover,focus` modes. This follows from the content's place in the DOM. Strictly, a tooltip with interactive content acts like a popover. The change keeps it reachable, because hiding it would leave keyboard users unable to use that button. diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/specs/tooltip-keyboard-access/spec.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/specs/tooltip-keyboard-access/spec.md new file mode 100644 index 0000000000..b96771e7fc --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/specs/tooltip-keyboard-access/spec.md @@ -0,0 +1,118 @@ +## MODIFIED Requirements + +### 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 or the tooltip content. Opening the tooltip SHALL NOT move focus. Moving focus out of both the trigger and the tooltip content 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 into custom content + +- **WHEN** the tooltip shows custom content with a button, its trigger has focus, and the user presses Tab +- **THEN** focus moves to the button in the tooltip, and the tooltip stays open + +#### Scenario: Tab out of custom content + +- **WHEN** focus is on a button in the tooltip content, and the user presses Tab to move focus past the tooltip +- **THEN** the tooltip closes, and focus moves to the next element on the page + +#### Scenario: Tab past the trigger + +- **WHEN** the tooltip is open because its trigger has focus, and the user presses Tab to move focus to an element outside the trigger and the tooltip +- **THEN** the tooltip closes + +### 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. When focus is inside the trigger, focus SHALL stay on the element that had it. When focus is inside the tooltip content, focus SHALL move to the first focusable element in the trigger, so it doesn't fall to the top of the page. + +#### 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 + +#### Scenario: Escape while the tooltip content has focus + +- **WHEN** a tooltip shows custom content, a button in that content has focus, and the user presses Escape +- **THEN** the tooltip closes, focus moves to the button in the trigger, and the next Tab moves on from 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, and a held key SHALL count as one activation. A click on a form control inside the trigger that isn't a button (a text box, text area, drop-down, check box, radio button or label) SHALL open the tooltip and SHALL NOT close it. 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. A tooltip SHALL ignore clicks and key presses that come from another tooltip nested inside its trigger. + +#### 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: Holding Enter + +- **WHEN** **Open on** is `Click`, a button inside the trigger has focus, and the user holds Enter down so the browser repeats the key +- **THEN** the tooltip opens once and stays open until the next press + +#### 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: Clicking in a text box + +- **WHEN** **Open on** is `Click`, the trigger is a text box, and the user clicks in it and then clicks again to move the cursor +- **THEN** the first click opens the tooltip, and the second click leaves it open + +#### Scenario: Space on a check box + +- **WHEN** **Open on** is `Click`, the trigger is a check box, and the user presses Space on it twice +- **THEN** the check box is checked and then unchecked, and the tooltip opens on the first Space and stays open + +#### Scenario: Nested Click tooltip + +- **WHEN** a `Click` tooltip's trigger contains another `Click` tooltip, and the user presses Enter or Space on the nested tooltip's button +- **THEN** only the nested tooltip toggles, and the outer 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 diff --git a/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/tasks.md b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/tasks.md new file mode 100644 index 0000000000..54de54ddbf --- /dev/null +++ b/packages/pluggableWidgets/tooltip-web/openspec/changes/archive/2026-11-16-fix-tooltip-keyboard-qa-findings/tasks.md @@ -0,0 +1,26 @@ +## 1. Click mode (`src/utils/useKeyboardClick.ts`) + +- [x] 1.1 Ignore keydowns with `event.repeat`, and skip the native `click` that a repeated Enter dispatches on a button +- [x] 1.2 Open the tooltip, but don't close it, on a click whose target is a form control (`input`, `textarea`, `select`, `label`, `contenteditable`) that isn't a button +- [x] 1.3 Ignore events whose target belongs to another `.widget-tooltip` than the one that handles them + +## 2. Focus (`src/utils/useFloatingUI.ts`, `src/components/Tooltip.tsx`) + +- [x] 2.1 When Escape closes the tooltip and focus is inside the tooltip content, move focus to the first focusable element in the trigger +- [x] 2.2 In `Hover,focus` mode, close the tooltip on blur only when focus leaves both the trigger and the tooltip content + +## 3. Unit tests (`src/components/__tests__/Tooltip.spec.tsx`) + +- [x] 3.1 Hover,focus: the tooltip stays open while focus moves into custom content, and closes when focus leaves it +- [x] 3.2 Hover,focus: Escape inside custom content closes the tooltip and moves focus back to the trigger +- [x] 3.3 Click: holding Enter toggles the tooltip once +- [x] 3.4 Click: a second click in a text box doesn't close the tooltip +- [x] 3.5 Click: Space on a check box opens the tooltip and the next Space doesn't close it +- [x] 3.6 Click: Enter on a nested tooltip's trigger opens only the nested tooltip +- [x] 3.7 Click: Escape inside custom content closes the tooltip and moves focus back to the trigger + +## 4. Verify and document + +- [x] 4.1 Add CHANGELOG "Fixed" entries for each problem +- [x] 4.2 Retest in SampleWidgetProject (`TooltipTest.Tooltip_Keyboard`) with Playwright: all eight sections pass, and button actions still run once per activation +- [ ] 4.3 Reply to the QA comment in WC-3663 with the results, and raise the question about interactive custom content diff --git a/packages/pluggableWidgets/tooltip-web/openspec/specs/tooltip-keyboard-access/spec.md b/packages/pluggableWidgets/tooltip-web/openspec/specs/tooltip-keyboard-access/spec.md index be2202b6f4..d1479b85c0 100644 --- a/packages/pluggableWidgets/tooltip-web/openspec/specs/tooltip-keyboard-access/spec.md +++ b/packages/pluggableWidgets/tooltip-web/openspec/specs/tooltip-keyboard-access/spec.md @@ -22,7 +22,7 @@ The default value of **Open on** SHALL be `Hover,focus`. A widget that already h ### 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. +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 or the tooltip content. Opening the tooltip SHALL NOT move focus. Moving focus out of both the trigger and the tooltip content SHALL close the tooltip. #### Scenario: Tab to a button @@ -39,9 +39,19 @@ When **Open on** is `Hover,focus`, the widget SHALL open the tooltip when an ele - **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 into custom content + +- **WHEN** the tooltip shows custom content with a button, its trigger has focus, and the user presses Tab +- **THEN** focus moves to the button in the tooltip, and the tooltip stays open + +#### Scenario: Tab out of custom content + +- **WHEN** focus is on a button in the tooltip content, and the user presses Tab to move focus past the tooltip +- **THEN** the tooltip closes, and focus moves to the next element on the page + #### 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 +- **WHEN** the tooltip is open because its trigger has focus, and the user presses Tab to move focus to an element outside the trigger and the tooltip - **THEN** the tooltip closes ### Requirement: Hover opens on mouse hover only @@ -60,7 +70,7 @@ When **Open on** is `Hover`, the widget SHALL open and close the tooltip on poin ### 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. +In every **Open on** mode, the widget SHALL close an open tooltip when the user presses Escape. When focus is inside the trigger, focus SHALL stay on the element that had it. When focus is inside the tooltip content, focus SHALL move to the first focusable element in the trigger, so it doesn't fall to the top of the page. #### Scenario: Escape while the trigger has focus @@ -72,9 +82,14 @@ In every **Open on** mode, the widget SHALL close an open tooltip when the user - **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 +#### Scenario: Escape while the tooltip content has focus + +- **WHEN** a tooltip shows custom content, a button in that content has focus, and the user presses Escape +- **THEN** the tooltip closes, focus moves to the button in the trigger, and the next Tab moves on from 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. +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, and a held key SHALL count as one activation. A click on a form control inside the trigger that isn't a button (a text box, text area, drop-down, check box, radio button or label) SHALL open the tooltip and SHALL NOT close it. 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. A tooltip SHALL ignore clicks and key presses that come from another tooltip nested inside its trigger. #### Scenario: Enter on a Mendix action button @@ -106,11 +121,31 @@ When **Open on** is `Click`, the widget SHALL toggle the tooltip on a mouse clic - **WHEN** a Click-mode tooltip is open and the user presses Enter again on the same button - **THEN** the tooltip closes +#### Scenario: Holding Enter + +- **WHEN** **Open on** is `Click`, a button inside the trigger has focus, and the user holds Enter down so the browser repeats the key +- **THEN** the tooltip opens once and stays open until the next press + #### 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: Clicking in a text box + +- **WHEN** **Open on** is `Click`, the trigger is a text box, and the user clicks in it and then clicks again to move the cursor +- **THEN** the first click opens the tooltip, and the second click leaves it open + +#### Scenario: Space on a check box + +- **WHEN** **Open on** is `Click`, the trigger is a check box, and the user presses Space on it twice +- **THEN** the check box is checked and then unchecked, and the tooltip opens on the first Space and stays open + +#### Scenario: Nested Click tooltip + +- **WHEN** a `Click` tooltip's trigger contains another `Click` tooltip, and the user presses Enter or Space on the nested tooltip's button +- **THEN** only the nested tooltip toggles, and the outer tooltip doesn't change state + #### Scenario: Focus only - **WHEN** **Open on** is `Click` and the user tabs to a button inside the trigger