fix(design-system): Dialog 밖 Popover·Tooltip이 Dialog의 Escape를 막지 않는다

앞 커밋은 Popover와 보이는 Tooltip이 Escape를 document capture 단계에서
받아 기본 동작을 막게 했다(1112/05-11). 그런데 대상이 어디인지 보지 않는다.
열린 popover를 Tab으로 벗어나 키보드로 Dialog를 열거나, tooltip이 보이는
채로 Dialog가 열리면, Dialog 안의 첫 Escape를 뒤쪽 층이 먹고 Dialog는 닫히지
않는다. 고치기 전에는 둘 다 닫혔다(확인 리뷰).

고른 방법: escape-layer.ts의 escapeIsForLayer가 Escape를 누른 곳이 그 층을
품지 않은 dialog 안이면 그 Escape를 dialog 것으로 본다. 층 안, 층을 품은
dialog 안, 요소 밖(포커스가 body)에서 누른 Escape는 층의 것이다. Popover와
Tooltip이 이것을 묻는다. 버린 대안: 대상이 층 안일 때만 받기(WebKit은 클릭한
버튼에 포커스를 주지 않아 열린 popover가 Escape로 닫히지 않는다).

위험·한계: native <dialog>가 아닌 modal(role="dialog"만 단 것)은 이 판정이
모른다. 템플릿의 Dialog·Drawer는 <dialog>다.

검증: design-system-a11y.test.tsx의 새 시험 셋(Dialog 밖 Popover, Dialog 밖
Tooltip, body에서 누른 Escape)이 고치기 전 코드에서 앞 둘이 실패하고 셋째는
통과(대조)하며, 고친 뒤 모두 통과한다(desktop, PR 본문).

Refs: 1112/05-11
This commit is contained in:
DongHyeonka
2026-11-13 00:05:26 +09:00
parent 353bed7ac2
commit 42b183f72c
4 changed files with 95 additions and 6 deletions
@@ -0,0 +1,15 @@
/**
* 1112/05-11. Whether an Escape is for a layer drawn over the page (a
* Popover or a shown Tooltip) whose root is `root`. Not when it was pressed
* inside a dialog that does not hold the layer: that Escape is the dialog's.
* An Escape from the layer, from a dialog around it, or from no element
* (focus on the body, as after a click in WebKit) is the layer's.
*/
export function escapeIsForLayer(event: KeyboardEvent, root: Element | null): boolean {
const target = event.target;
if (root === null || !(target instanceof Element) || root.contains(target)) {
return true;
}
const dialog = target.closest("dialog");
return dialog === null || dialog.contains(root);
}
@@ -1,6 +1,7 @@
import { useEffect, useId, useRef, useState } from "react";
import { Button } from "./button.tsx";
import { escapeIsForLayer } from "./escape-layer.ts";
export type PopoverProps = Readonly<{
triggerLabel: string;
@@ -26,9 +27,14 @@ export function Popover({ triggerLabel, children }: PopoverProps) {
}
}
// Capture phase, and the default prevented: the Escape closes this
// layer only, not a Dialog around it (1112/05-11).
// layer only, not a Dialog around it (1112/05-11). An Escape pressed in
// a Dialog this popover is not in is the Dialog's.
function closeOnEscape(event: KeyboardEvent) {
if (event.key === "Escape" && !event.defaultPrevented) {
if (
event.key === "Escape" &&
!event.defaultPrevented &&
escapeIsForLayer(event, rootRef.current)
) {
event.preventDefault();
setOpen(false);
triggerRef.current?.focus();
@@ -1,4 +1,6 @@
import { cloneElement, useEffect, useId, useState } from "react";
import { cloneElement, useEffect, useId, useRef, useState } from "react";
import { escapeIsForLayer } from "./escape-layer.ts";
export type TooltipProps = Readonly<{
content: string;
@@ -15,15 +17,22 @@ export function Tooltip({ content, children }: TooltipProps) {
const [dismissed, setDismissed] = useState(false);
const [hovered, setHovered] = useState(false);
const [focused, setFocused] = useState(false);
const rootRef = useRef<HTMLSpanElement | null>(null);
const shown = (hovered || focused) && !dismissed;
useEffect(() => {
if (!shown) return;
// Document level: a hovered trigger does not have keyboard focus. Capture
// phase, and the default prevented: this Escape hides the tooltip only,
// not a Dialog around it (1112/05-11). A tooltip that is not shown leaves
// the Escape alone.
// not a Dialog around it (1112/05-11). A tooltip that is not shown, or
// one outside the Dialog the Escape was pressed in, leaves it alone.
function dismissOnEscape(event: KeyboardEvent) {
if (event.key !== "Escape" || event.defaultPrevented) return;
if (
event.key !== "Escape" ||
event.defaultPrevented ||
!escapeIsForLayer(event, rootRef.current)
) {
return;
}
event.preventDefault();
setDismissed(true);
}
@@ -36,6 +45,7 @@ export function Tooltip({ content, children }: TooltipProps) {
return (
<span
className="ui-tooltip"
ref={rootRef}
onBlur={(event) => {
if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
}}
@@ -105,6 +105,64 @@ describe("Escape inside a Dialog", () => {
expect(onClose).not.toHaveBeenCalled();
});
// round9 confirm review. A popover or tooltip left open outside a Dialog
// does not take the Dialog's Escape: the Escape belongs to the Dialog it
// was pressed in.
it.each([
[
"a Popover",
(
<Popover key="layer" triggerLabel="설명 열기">
<Button>내부 작업</Button>
</Popover>
),
(user: ReturnType<typeof userEvent.setup>) => user.click(screen.getByRole("button", { name: "설명 열기" })),
],
[
"a Tooltip",
(
<Tooltip key="layer" content="자세한 설명">
<Button>도움말</Button>
</Tooltip>
),
(user: ReturnType<typeof userEvent.setup>) => user.hover(screen.getByRole("button", { name: "도움말" })),
],
])("closes the Dialog when %s outside it is open", async (_label, layer, openLayer) => {
const user = userEvent.setup();
const onClose = vi.fn();
render(
<>
{layer}
<DialogWith onClose={onClose}>
<Button>안쪽 버튼</Button>
</DialogWith>
</>,
);
await openLayer(user);
screen.getByRole("button", { name: "안쪽 버튼" }).focus();
await user.keyboard("{Escape}");
expect(onClose).toHaveBeenCalledTimes(1);
});
// WebKit does not focus a clicked button: an Escape with focus on the body
// still closes the open Popover.
it("closes an open Popover on an Escape from the body", async () => {
const user = userEvent.setup();
render(
<Popover triggerLabel="설명 열기">
<Button>내부 작업</Button>
</Popover>,
);
await user.click(screen.getByRole("button", { name: "설명 열기" }));
(document.activeElement as HTMLElement | null)?.blur();
await user.keyboard("{Escape}");
expect(screen.queryByRole("button", { name: "내부 작업" })).not.toBeInTheDocument();
});
it("closes the Dialog when no inner layer is open", async () => {
const user = userEvent.setup();
const onClose = vi.fn();