Improve Popover API

packages/circuit-ui/components/Popover/Popover.spec.tsx

@@ -17,7 +17,6 @@
 
 import { CirclePlus, Zap } from '@sumup/icons';
 import { Placement } from '@popperjs/core';
-import { forwardRef } from 'react';
 
 import {
   axe,
@@ -90,11 +89,7 @@ describe('Popover', () => {
   const renderPopover = (props: Omit<PopoverProps, 'component'>) =>
     render(
       <Popover
-        component={forwardRef<HTMLButtonElement>((triggerProps, ref) => (
-          <button ref={ref} {...triggerProps}>
-            Button
-          </button>
-        ))}
+        component={(triggerProps) => <button {...triggerProps}>Button</button>}
         {...props}
       />,
     );
@@ -108,6 +103,8 @@ describe('Popover', () => {
       },
       { type: 'divider' },
     ],
+    isOpen: true,
+    toggleOpen: jest.fn(),
   };
 
   describe('styles', () => {
@@ -140,48 +137,32 @@ describe('Popover', () => {
   });
 
   describe('business logic', () => {
-    it('should close the popover when clicking outside', async () => {
-      const { getByRole, queryByRole } = renderPopover(baseProps);
-
-      const popoverTrigger = getByRole('button');
+    it('should close the popover when clicking outside', () => {
+      const { queryByRole } = renderPopover(baseProps);
 
-      userEvent.click(popoverTrigger);
-
-      await waitFor(() => {
-        expect(queryByRole('menu')).toBeVisible();
-      });
+      expect(queryByRole('menu')).toBeVisible();
 
       userEvent.click(document.body);
 
-      await waitFor(() => {
-        expect(queryByRole('menu')).toBeNull();
-      });
+      expect(baseProps.toggleOpen).toHaveBeenCalled();
     });
 
     it('should close popover when clicking the trigger element', async () => {
       const { getByRole, queryByRole } = renderPopover(baseProps);
 
       const popoverTrigger = getByRole('button');
 
-      userEvent.click(popoverTrigger);
-
       await waitFor(() => {
         expect(queryByRole('menu')).toBeVisible();
       });
 
       userEvent.click(popoverTrigger);
 
-      await waitFor(() => {
-        expect(queryByRole('menu')).toBeNull();
-      });
+      expect(baseProps.toggleOpen).toHaveBeenCalled();
     });
 
     it('should close popover when clicking the ESC key', async () => {
-      const { getByRole, queryByRole } = renderPopover(baseProps);
-
-      const popoverTrigger = getByRole('button');
-
-      userEvent.click(popoverTrigger);
+      const { queryByRole } = renderPopover(baseProps);
 
       await waitFor(() => {
         expect(queryByRole('menu')).toBeVisible();
@@ -191,9 +172,7 @@ describe('Popover', () => {
         key: 'Escape',
       });
 
-      await waitFor(() => {
-        expect(queryByRole('menu')).toBeNull();
-      });
+      expect(baseProps.toggleOpen).toHaveBeenCalled();
     });
 
     /**

packages/circuit-ui/components/Popover/Popover.stories.tsx

@@ -15,9 +15,10 @@
 
 /* eslint-disable react/display-name */
 
-import { forwardRef } from 'react';
 import { action } from '@storybook/addon-actions';
 import { CirclePlus, PenStroke, Bin } from '@sumup/icons';
+import { JSXElement } from 'jscodeshift';
+import { useState } from 'react';
 
 import Button from '../Button';
 
@@ -55,16 +56,26 @@ const actions = [
   },
 ];
 
-export const Base = (args: PopoverProps): JSX.Element => (
-  <Popover
-    {...args}
-    component={forwardRef((props, ref) => (
-      <Button size="kilo" variant="primary" ref={ref} {...props}>
-        Open popover
-      </Button>
-    ))}
-  />
-);
+export const Base = (args: PopoverProps): JSXElement => {
+  const [isOpen, setOpen] = useState(false);
+
+  const handleClick = () => {
+    setOpen((prev) => !prev);
+  };
+
+  return (
+    <Popover
+      {...args}
+      isOpen={isOpen}
+      toggleOpen={handleClick}
+      component={(props) => (
+        <Button size="kilo" variant="primary" {...props}>
+          Open popover
+        </Button>
+      )}
+    />
+  );
+};
 
 Base.args = {
   actions,

packages/circuit-ui/components/Popover/Popover.tsx

@@ -181,6 +181,14 @@ function isDivider(action: Action): action is Divider {
 }
 
 export interface PopoverProps {
+  /**
+   * Determine whether the Popover is opened or closed.
+   */
+  isOpen: boolean;
+  /**
+   * Function that is called when closing the Popover.
+   */
+  toggleOpen: (open: boolean | ((prevOpen: boolean) => boolean)) => void;
   /**
    * An array of PopoverItem or Divider.
    */
@@ -198,22 +206,23 @@ export interface PopoverProps {
    */
   component: (props: {
     'onClick': (event: MouseEvent | KeyboardEvent) => void;
-    'ref': Ref<HTMLButtonElement>;
     'id': string;
     'aria-haspopup': boolean;
     'aria-controls': string;
+    'aria-expanded': boolean;
   }) => JSX.Element;
 }
 
 export const Popover = ({
+  isOpen = false,
+  toggleOpen,
   actions,
   placement = 'bottom',
   fallbackPlacements = ['top', 'right', 'left'],
   component: Component,
   ...props
 }: PopoverProps): JSX.Element | null => {
-  const [isOpen, setOpen] = useState(false);
-  const triggerRef = useRef<HTMLButtonElement>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
   const theme = useTheme<Theme>();
   const id = uniqueId('popover_');
   const triggerId = uniqueId('trigger_');
@@ -272,15 +281,15 @@ export const Popover = ({
     }
     const handleEscapePress = (event: Event) => {
       if (isEscape(event)) {
-        setOpen(false);
+        toggleOpen(false);
       }
     };
 
     document.addEventListener('keydown', handleEscapePress);
     return () => {
       document.removeEventListener('keydown', handleEscapePress);
     };
-  }, [isOpen]);
+  }, [isOpen, toggleOpen]);
 
   useClickAway(popperRef, (event) => {
     // The reference element has its own click handler to toggle the popover.
@@ -290,18 +299,20 @@ export const Popover = ({
     ) {
       return;
     }
-    setOpen(false);
+    toggleOpen(false);
   });
 
   return (
     <Fragment>
-      <Component
-        ref={triggerRef}
-        id={triggerId}
-        aria-haspopup={true}
-        aria-controls={id}
-        onClick={() => setOpen((prev) => !prev)}
-      />
+      <div ref={triggerRef}>
+        <Component
+          id={triggerId}
+          aria-haspopup={true}
+          aria-controls={id}
+          aria-expanded={isOpen}
+          onClick={() => toggleOpen((prev) => !prev)}
+        />
+      </div>
       {isOpen && (
         <Fragment>
           <Overlay />