[PopoverOverlay] Escape only closes popover if event.target is a descendant (#7332)

### WHY are these changes introduced?

Fixes #7329

When multiple Polaris Popovers are open and pressing `Escape`, then all
Popovers close. This creates conflict in moving focus to activator of a
Popover, especially if a Popover is a child of another Popover. In the
case of a parent child relationship, when both Popovers close, then the
child Popover no longer has the activator available within the DOM to
move focus to, so focus goes to the `body`.

### WHAT is this pull request doing?

PopoverOverlay has a global listener for `Escape` key presses, so all
Popovers respond to the `Escape` key presses and attempt to close. This
pull request will only close the Popover where the event target of the
keypress is either a descendant of the Popover or the associated
activator. As a result, Popovers will iteratively close based on the
presence of focus.

<details>
  <summary>Demo of fix</summary>
<img
src="https://user-images.githubusercontent.com/86790511/193919419-1dc57b3f-2ee6-4062-9670-d3f24a0af55a.gif"
alt="Demo of fix">
</details>

### How to 🎩

Validate `Escape` Popover behavior within the following codesandbox,
which has a snapshot of Polaris with the change in this PR.

https://codesandbox.io/s/polaris-double-popover-escape-with-fix-0od2c3

### 🎩 checklist

- [x] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [x] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [x] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Author: mattkubej

.changeset/violet-rice-appear.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': patch
+---
+
+`PopoverOverlay` closes focused `Popover` when pressing `Escape`

polaris-react/src/components/Combobox/tests/Combobox.test.tsx

@@ -302,8 +302,14 @@ describe('<Combobox />', () => {
 
       triggerFocus(combobox);
 
+      const target = combobox.find(TextField)!.find('input')!.domNode;
+      const keyupEvent = new KeyboardEvent('keyup', {
+        keyCode: Key.Escape,
+        bubbles: true,
+      });
+
       combobox.act(() => {
-        dispatchKeyup(Key.Escape);
+        target?.dispatchEvent(keyupEvent);
       });
 
       expect(combobox).toContainReactComponent(Popover, {
@@ -433,8 +439,3 @@ function triggerOptionSelected(combobox: any) {
 }
 
 function noop() {}
-
-function dispatchKeyup(key: Key) {
-  const event: KeyboardEventInit & {keyCode: Key} = {keyCode: key};
-  document.dispatchEvent(new KeyboardEvent('keyup', event));
-}

polaris-react/src/components/Popover/components/PopoverOverlay/PopoverOverlay.tsx

@@ -299,8 +299,19 @@ export class PopoverOverlay extends PureComponent<PopoverOverlayProps, State> {
     this.props.onClose(PopoverCloseSource.ScrollOut);
   };
 
-  private handleEscape = () => {
-    this.props.onClose(PopoverCloseSource.EscapeKeypress);
+  private handleEscape = (event: Event) => {
+    const target = event.target as HTMLElement;
+    const {
+      contentNode,
+      props: {activator},
+    } = this;
+    const composedPath = event.composedPath();
+    const wasDescendant = wasContentNodeDescendant(composedPath, contentNode);
+    const isActivatorDescendant = nodeContainsDescendant(activator, target);
+
+    if (wasDescendant || isActivatorDescendant) {
+      this.props.onClose(PopoverCloseSource.EscapeKeypress);
+    }
   };
 
   private handleFocusFirstItem = () => {

polaris-react/src/components/Popover/components/PopoverOverlay/tests/PopoverOverlay.test.tsx

@@ -8,29 +8,10 @@ import {PositionedOverlay} from '../../../../PositionedOverlay';
 import {PopoverOverlay} from '../PopoverOverlay';
 import {Popover} from '../../../Popover';
 
-interface HandlerMap {
-  [eventName: string]: (event: any) => void;
-}
-
-const listenerMap: HandlerMap = {};
-
 describe('<PopoverOverlay />', () => {
-  let addEventListener: jest.SpyInstance;
-  let removeEventListener: jest.SpyInstance;
-
   let rafSpy: jest.SpyInstance;
 
   beforeEach(() => {
-    addEventListener = jest.spyOn(document, 'addEventListener');
-    addEventListener.mockImplementation((event, callback) => {
-      listenerMap[event] = callback;
-    });
-
-    removeEventListener = jest.spyOn(document, 'removeEventListener');
-    removeEventListener.mockImplementation((event) => {
-      listenerMap[event] = noop;
-    });
-
     rafSpy = jest.spyOn(window, 'requestAnimationFrame');
     rafSpy.mockImplementation((callback) => callback());
   });
@@ -40,9 +21,6 @@ describe('<PopoverOverlay />', () => {
       (document.activeElement as HTMLElement).blur();
     }
 
-    addEventListener.mockRestore();
-    removeEventListener.mockRestore();
-
     rafSpy.mockRestore();
   });
 
@@ -204,24 +182,6 @@ describe('<PopoverOverlay />', () => {
     });
   });
 
-  it('calls the onClose callback when the escape key is pressed', () => {
-    const spy = jest.fn();
-
-    mountWithApp(
-      <PopoverOverlay
-        active
-        id="PopoverOverlay-1"
-        activator={activator}
-        onClose={spy}
-      >
-        {children}
-      </PopoverOverlay>,
-    );
-
-    listenerMap.keyup({keyCode: Key.Escape});
-    expect(spy).toHaveBeenCalledTimes(1);
-  });
-
   it('does not call the onClose callback when a descendent HTMLElement is clicked', () => {
     const spy = jest.fn();
 
@@ -316,6 +276,77 @@ describe('<PopoverOverlay />', () => {
     expect(spy).not.toHaveBeenCalled();
   });
 
+  describe('when the Escape key is pressed', () => {
+    it('calls the onClose callback if event target is descendant', () => {
+      const spy = jest.fn();
+
+      const popoverOverlay = mountWithApp(
+        <PopoverOverlay
+          active
+          id="PopoverOverlay-1"
+          activator={activator}
+          onClose={spy}
+        >
+          <TextField
+            label="Store name"
+            value="Click me"
+            onChange={() => {}}
+            autoComplete="off"
+          />
+        </PopoverOverlay>,
+      );
+
+      const target = popoverOverlay.find(TextField)!.find('input')!.domNode!;
+      triggerEscape(target);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
+
+    it('calls the onClose callback if event target is activator descendant', () => {
+      const spy = jest.fn();
+
+      const popoverOverlay = mountWithApp(
+        <PopoverOverlay
+          active
+          id="PopoverOverlay-1"
+          activator={activator}
+          onClose={spy}
+        >
+          <TextField
+            label="Store name"
+            value="Click me"
+            onChange={() => {}}
+            autoComplete="off"
+          />
+        </PopoverOverlay>,
+      );
+
+      const target = popoverOverlay.find(TextField)!.find('input')!.domNode!;
+      triggerEscape(target);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not call the onClose callback if event target is not descendant or activator descendant', () => {
+      const spy = jest.fn();
+
+      mountWithApp(
+        <PopoverOverlay
+          active
+          id="PopoverOverlay-1"
+          activator={activator}
+          onClose={spy}
+        >
+          {children}
+        </PopoverOverlay>,
+      );
+
+      triggerEscape();
+
+      expect(spy).toHaveBeenCalledTimes(0);
+    });
+  });
+
   describe('deleting descendant elements', () => {
     const DeleteButton = () => {
       const [show, setShow] = React.useState(true);
@@ -567,3 +598,12 @@ describe('<PopoverOverlay />', () => {
 });
 
 function noop() {}
+
+function triggerEscape(target?: Element) {
+  const keyupEvent = new KeyboardEvent('keyup', {
+    keyCode: Key.Escape,
+    bubbles: true,
+  });
+
+  (target || document).dispatchEvent(keyupEvent);
+}