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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:44:38 +09:00
co-authored by Claude Opus 5.5
parent 38db97a564
commit 21233e8d9b
2 changed files with 95 additions and 6 deletions
@@ -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 (
<span className="ui-tooltip">
<span aria-describedby={tooltipId} className="ui-tooltip__trigger">
{children}
</span>
<span className="ui-tooltip__content" id={tooltipId} role="tooltip">
<span
className="ui-tooltip"
onFocus={() => setDismissed(false)}
onMouseEnter={() => setDismissed(false)}
>
{cloneElement(children, { "aria-describedby": describedBy })}
<span
className="ui-tooltip__content"
hidden={dismissed}
id={tooltipId}
role="tooltip"
>
{content}
</span>
</span>
+63
View File
@@ -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(
<>
<p id="existing-hint">Existing hint</p>
<Tooltip content="Optional detail">
<Button aria-describedby="existing-hint">Help</Button>
</Tooltip>
</>,
);
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(
<>
<Tooltip content="Optional detail">
<Button>Help</Button>
</Tooltip>
<Button>Elsewhere</Button>
</>,
);
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(
<Tooltip content="Optional detail">
<Button>Help</Button>
</Tooltip>,
);
await user.hover(screen.getByRole("button", { name: "Help" }));
await user.keyboard("{Escape}");
expect(screen.getByRole("tooltip", { hidden: true })).not.toBeVisible();
});
});