fix(Modal): allow Escape to close ContextualMenu before closing Modal

[koushik717]

Problem

Fixes #1305

When a ContextualMenu is open inside a Modal, pressing Escape closes the Modal immediately rather than the menu first. This breaks the expected layered-dismiss UX and is an accessibility issue.

Root cause

Modal.tsx called stopImmediatePropagation() unconditionally. Because ContextualMenu renders via a Portal (a DOM sibling, not a React child), its own document keydown listener was silenced before it could fire.

Fix — component-agnostic global LIFO escape-key stack

Following @edlerd's exploration in #1305, this implements the global handler-stack approach used by every major overlay library (Radix UI, Headless UI, Chakra UI).

New: src/hooks/useEscapeStack.ts

A module-level LIFO array of callbacks. A single document keydown listener calls only the top-of-stack handler and then calls stopImmediatePropagation() — no component needs to know about any other.

// low-level imperative API (used internally)
const unregister = pushEscapeHandler(() => closeMyOverlay());

// React hook API (for consumers)
useEscapeStack(() => closeMyOverlay(), { isActive: isOpen });

useOnEscapePressed — delegates to pushEscapeHandler

No API change; existing call-sites are unaffected.

Modal — uses useOnEscapePressed

The Escape branch is removed from Modal's manual keydown map. Modal now registers via the stack, so it naturally yields to any overlay opened after it.

usePortal — registers on the stack only while open

A new useEffect([isOpen, closeOnEsc, …]) registers the handler when the portal opens and pops it when it closes. The stack always reflects the current visual overlay depth.

Result

The most recently opened overlay handles Escape first, regardless of component type, DOM position, or whether it is a consumer-defined overlay (consumers can call useEscapeStack or pushEscapeHandler to join the same stack).

Two-step dismiss for Modal + ContextualMenu:

1. First Escape → ContextualMenu closes (top of stack)
2. Second Escape → Modal closes (now top of stack)

Changes

• src/hooks/useEscapeStack.ts — New: LIFO stack + useEscapeStack hook + pushEscapeHandler
• src/hooks/useEscapeStack.test.ts — New: unit tests for stack ordering and propagation
• src/hooks/useOnEscapePressed.ts — Delegates to pushEscapeHandler
• src/components/Modal/Modal.tsx — Uses useOnEscapePressed; Escape removed from keydown map
• src/components/Modal/Modal.test.tsx — Updated + regression test for ContextualMenu cannot be closed with ESCAPE key when inside a Modal #1305
• src/external/usePortal.ts — Registers on escape stack only while portal is open
• src/hooks/index.ts / src/index.ts — Export new hook and utility

Testing

yarn lint  ✓  (0 errors)
yarn test  ✓  (837 tests, 103 suites)

[webteam-app]

koushik717 is not a collaborator of the repo

[jmuzina]

Thanks for the contribution @koushik717 and apologies that this slipped beneath the radar - leaving a comment below with a suggestion for improvement!

[jmuzina]

This would make this behavior reliant on maintaining a list of other components that register their own escape focus handlers within Modal - making it quite tightly coupled with other components and tough to maintain. It would also reduce interoperability with custom consumer components that might register their own escape focus handlers (as they are not included in this query selector). I think any solution to this issue needs to be agnostic to the specific relationships between components.

@edlerd posted a thorough exploration of this problem with some options to try out - maybe that can help improve this solution

[koushik717]

Thanks for the thorough feedback! I've reworked the fix completely the CSS selector approach is gone.

The new implementation introduces a component-agnostic global LIFO escape-key stack (src/hooks/useEscapeStack.ts), following the approach @edlerd outlined. A single document listener sits in front of the stack and invokes only the top handler per keypress no component needs any knowledge of any other.

Both Modal (via useOnEscapePressed) and usePortal (with an open-aware useEffect) now register through the same stack. The most recently opened overlay always handles Escape first, regardless of component type, DOM position, or portal placement. Custom consumer overlays can join the same stack via the exported useEscapeStack hook or pushEscapeHandler utility.

All 837 tests pass. Happy to adjust anything further!