diff --git a/docs/reference/ui-primitives.md b/docs/reference/ui-primitives.md index a76c36fae..188fdf52c 100644 --- a/docs/reference/ui-primitives.md +++ b/docs/reference/ui-primitives.md @@ -319,6 +319,8 @@ import { Dialog } from '@ui/components/Dialog' `Dialog` traps focus, restores it on close, escape-closes, click-outside-closes (configurable). Modal by default. Replaces native `alert()` / `confirm()` (which are banned by `no-native-browser-dialogs.test.ts`). +**Modal shells must bind Escape on `document`, not as a React `onKeyDown` on the dialog element.** React's delegated handler only fires while focus sits inside the dialog subtree, and a click on any non-focusable spot in a panel blurs to `` — outside that subtree — leaving Escape silently dead while backdrop click still works. Pair it with `tabIndex={-1}` on the panel so such clicks land on the panel instead of `` and the Tab trap holds. + --- ## `Tooltip` @@ -333,6 +335,8 @@ import { Tooltip } from '@ui/components/Tooltip' Replaces native `title="..."` (gated by `no-native-title-tooltips.test.ts`). Works on disabled buttons because `mouseenter` fires on disabled `