Exposed close function on Popover

.changeset/nervous-plums-end.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Exposed a `close` function on popovers imperative handle

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

@@ -189,7 +189,7 @@ describe('<Combobox />', () => {
   it('calls Popover.forceUpdatePosition() when onOptionSelected is triggered and allowMultiple is true and there are children', () => {
     const mockForceUpdatePosition = jest.fn();
     mockUseImperativeHandle.mockImplementation(
-      (ref: {current: PopoverPublicAPI}) => {
+      (ref: {current: Partial<PopoverPublicAPI>}) => {
         ref.current = {
           forceUpdatePosition: mockForceUpdatePosition,
         };

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

@@ -82,8 +82,10 @@ export interface PopoverProps {
   captureOverscroll?: boolean;
 }
 
+type CloseTarget = 'activator' | 'next-node';
 export interface PopoverPublicAPI {
   forceUpdatePosition(): void;
+  close(target?: CloseTarget): void;
 }
 
 // TypeScript can't generate types that correctly infer the typing of
@@ -120,36 +122,6 @@ const PopoverComponent = forwardRef<PopoverPublicAPI, PopoverProps>(
       overlayRef.current?.forceUpdatePosition();
     }
 
-    useImperativeHandle(ref, () => {
-      return {
-        forceUpdatePosition,
-      };
-    });
-
-    const setAccessibilityAttributes = useCallback(() => {
-      if (activatorContainer.current == null) {
-        return;
-      }
-
-      const firstFocusable = findFirstFocusableNodeIncludingDisabled(
-        activatorContainer.current,
-      );
-      const focusableActivator: HTMLElement & {
-        disabled?: boolean;
-      } = firstFocusable || activatorContainer.current;
-
-      const activatorDisabled =
-        'disabled' in focusableActivator &&
-        Boolean(focusableActivator.disabled);
-
-      setActivatorAttributes(focusableActivator, {
-        id,
-        active,
-        ariaHaspopup,
-        activatorDisabled,
-      });
-    }, [id, active, ariaHaspopup]);
-
     const handleClose = (source: PopoverCloseSource) => {
       onClose(source);
       if (activatorContainer.current == null || preventFocusOnClose) {
@@ -181,6 +153,44 @@ const PopoverComponent = forwardRef<PopoverPublicAPI, PopoverProps>(
       }
     };
 
+    useImperativeHandle(ref, () => {
+      return {
+        forceUpdatePosition,
+        close: (target = 'activator') => {
+          const source =
+            target === 'activator'
+              ? PopoverCloseSource.EscapeKeypress
+              : PopoverCloseSource.FocusOut;
+
+          handleClose(source);
+        },
+      };
+    });
+
+    const setAccessibilityAttributes = useCallback(() => {
+      if (activatorContainer.current == null) {
+        return;
+      }
+
+      const firstFocusable = findFirstFocusableNodeIncludingDisabled(
+        activatorContainer.current,
+      );
+      const focusableActivator: HTMLElement & {
+        disabled?: boolean;
+      } = firstFocusable || activatorContainer.current;
+
+      const activatorDisabled =
+        'disabled' in focusableActivator &&
+        Boolean(focusableActivator.disabled);
+
+      setActivatorAttributes(focusableActivator, {
+        id,
+        active,
+        ariaHaspopup,
+        activatorDisabled,
+      });
+    }, [id, active, ariaHaspopup]);
+
     useEffect(() => {
       if (!activatorNode && activatorContainer.current) {
         setActivatorNode(

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

@@ -1,5 +1,6 @@
 import React, {useCallback, useRef, useState} from 'react';
 import {mountWithApp} from 'tests/utilities';
+import {act} from 'react-dom/test-utils';
 
 import {Portal} from '../../Portal';
 import {PositionedOverlay} from '../../PositionedOverlay';
@@ -396,14 +397,75 @@ describe('<Popover />', () => {
 
       mountWithApp(<Test />);
 
-      expect(popoverRef).toStrictEqual({
+      expect(popoverRef).toMatchObject({
         current: {
           forceUpdatePosition: expect.anything(),
         },
       });
     });
   });
 
+  describe('close', () => {
+    it('exposes a function that closes the popover & focuses the activator by default', () => {
+      const activatorId = 'focus-target';
+      let popoverRef: React.RefObject<PopoverPublicAPI> | null = null;
+
+      function Test() {
+        popoverRef = useRef(null);
+
+        return (
+          <Popover
+            ref={popoverRef}
+            active
+            activator={<button id={activatorId} />}
+            onClose={noop}
+          />
+        );
+      }
+
+      const popover = mountWithApp(<Test />);
+
+      act(() => {
+        popoverRef?.current?.close();
+      });
+
+      const focusTarget = popover.find('button', {id: activatorId})!.domNode;
+
+      expect(document.activeElement).toBe(focusTarget);
+    });
+
+    it('exposes a function that closes the popover & focuses the next node when the next-node option is used', () => {
+      const nextFocusedId = 'focus-target2';
+      let popoverRef: React.RefObject<PopoverPublicAPI> | null = null;
+
+      function Test() {
+        popoverRef = useRef(null);
+
+        return (
+          <>
+            <Popover
+              ref={popoverRef}
+              active
+              activator={<button />}
+              onClose={noop}
+            />
+            <button id={nextFocusedId} />
+          </>
+        );
+      }
+
+      const popover = mountWithApp(<Test />);
+
+      act(() => {
+        popoverRef?.current?.close('next-node');
+      });
+
+      const focusTarget = popover.find('button', {id: nextFocusedId})!.domNode;
+
+      expect(document.activeElement).toBe(focusTarget);
+    });
+  });
+
   describe('captureOverscroll', () => {
     const TestActivator = <button>Activator</button>;