From 21233e8d9b2d3de006cc22fc81ef4e20bc1b9400 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:22:49 +0900 Subject: [PATCH] fix(presentation): describe the tooltip trigger and close it with Escape (Q-6.8-11) Tooltip injects `aria-describedby` into its focusable child (merged with any existing value) instead of a non-focusable wrapper span, and Escape hides the tooltip until the next hover or focus (WCAG 1.4.13). The listener is on the document so a hovered, unfocused trigger closes too. Verified with tests/component/tooltip.test.tsx (RED: 3 of 3 failed before the change) and the lane gates. Co-Authored-By: Claude Opus 5.5 --- .../design-system/primitives/overlays.tsx | 38 +++++++++-- tests/component/tooltip.test.tsx | 63 +++++++++++++++++++ 2 files changed, 95 insertions(+), 6 deletions(-) create mode 100644 tests/component/tooltip.test.tsx diff --git a/src/presentation/design-system/primitives/overlays.tsx b/src/presentation/design-system/primitives/overlays.tsx index 2a75cc2c..2b7aba07 100644 --- a/src/presentation/design-system/primitives/overlays.tsx +++ b/src/presentation/design-system/primitives/overlays.tsx @@ -1,4 +1,5 @@ import { + cloneElement, createContext, useCallback, useContext, @@ -104,17 +105,42 @@ export function Popover({ triggerLabel, children }: PopoverProps) { export type TooltipProps = Readonly<{ content: string; - children: React.ReactElement; + children: React.ReactElement<{ "aria-describedby"?: string | undefined }>; }>; +/** + * Describes its focusable child (WCAG 1.4.13): the child carries + * `aria-describedby`, and Escape hides the tooltip until the next hover or + * focus. + */ export function Tooltip({ content, children }: TooltipProps) { const tooltipId = useId(); + const [dismissed, setDismissed] = useState(false); + useEffect(() => { + if (dismissed) return; + // Document level: a hovered trigger does not have keyboard focus. + function dismissOnEscape(event: KeyboardEvent) { + if (event.key === "Escape") setDismissed(true); + } + document.addEventListener("keydown", dismissOnEscape); + return () => document.removeEventListener("keydown", dismissOnEscape); + }, [dismissed]); + const describedBy = [children.props["aria-describedby"], tooltipId] + .filter(Boolean) + .join(" "); return ( - - - {children} - - + setDismissed(false)} + onMouseEnter={() => setDismissed(false)} + > + {cloneElement(children, { "aria-describedby": describedBy })} + diff --git a/tests/component/tooltip.test.tsx b/tests/component/tooltip.test.tsx new file mode 100644 index 00000000..24d4eebb --- /dev/null +++ b/tests/component/tooltip.test.tsx @@ -0,0 +1,63 @@ +// @vitest-environment jsdom + +import { render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { describe, expect, it } from "vitest"; + +import { Button, Tooltip } from "../../src/presentation/design-system/index.ts"; + +describe("Tooltip", () => { + it("describes the focusable trigger itself", async () => { + const user = userEvent.setup(); + render( + <> +

Existing hint

+ + + + , + ); + + await user.tab(); + const trigger = screen.getByRole("button", { name: "Help" }); + expect(trigger).toHaveFocus(); + expect(trigger).toHaveAccessibleDescription("Existing hint Optional detail"); + }); + + it("closes with Escape and opens again on the next focus", async () => { + const user = userEvent.setup(); + render( + <> + + + + + , + ); + + await user.tab(); + const tooltip = screen.getByRole("tooltip"); + expect(tooltip).toBeVisible(); + + await user.keyboard("{Escape}"); + expect(tooltip).not.toBeVisible(); + expect(screen.getByRole("button", { name: "Help" })).toHaveFocus(); + + await user.tab(); + await user.tab({ shift: true }); + expect(screen.getByRole("tooltip")).toBeVisible(); + }); + + it("closes a hovered tooltip with Escape", async () => { + const user = userEvent.setup(); + render( + + + , + ); + + await user.hover(screen.getByRole("button", { name: "Help" })); + await user.keyboard("{Escape}"); + expect(screen.getByRole("tooltip", { hidden: true })).not.toBeVisible(); + }); +});