Add elementRef prop to Popover component

This is a ref for the popover's outermost element, like `elementRef` for other
components. This is useful for downstream code which needs information about the
geometry of the rendered popover.  Downstream code could use a ref on the
popover's content instead, but that doesn't include any padding which the
popover has.

Author: robertknight

src/components/feedback/Popover.tsx

@@ -1,10 +1,12 @@
 import classnames from 'classnames';
 import type { ComponentChildren, JSX, RefObject } from 'preact';
-import { useCallback, useEffect, useLayoutEffect, useRef } from 'preact/hooks';
+import { useCallback, useEffect, useLayoutEffect } from 'preact/hooks';
 
 import { useClickAway } from '../../hooks/use-click-away';
 import { useKeyPress } from '../../hooks/use-key-press';
+import { useSyncedRef } from '../../hooks/use-synced-ref';
 import { ListenerCollection } from '../../util/listener-collection';
+import { downcastRef } from '../../util/typing';
 
 /** Small space to apply between the anchor element and the popover */
 const POPOVER_ANCHOR_EL_GAP = '.15rem';
@@ -225,6 +227,9 @@ export type PopoverProps = {
   classes?: string | string[];
   variant?: 'panel' | 'custom';
 
+  /** Ref for the popover element. */
+  elementRef?: RefObject<HTMLElement>;
+
   /** Whether the popover is currently open or not */
   open: boolean;
 
@@ -328,10 +333,11 @@ export default function Popover({
   classes,
   variant = 'panel',
   onScroll,
+  elementRef,
   /* eslint-disable-next-line no-prototype-builtins */
   asNativePopover = HTMLElement.prototype.hasOwnProperty('popover'),
 }: PopoverProps) {
-  const popoverRef = useRef<HTMLDivElement | null>(null);
+  const popoverRef = useSyncedRef<HTMLElement>(elementRef);
 
   usePopoverPositioning(
     anchorElementRef,
@@ -370,7 +376,7 @@ export default function Popover({
         },
         classes,
       )}
-      ref={popoverRef}
+      ref={downcastRef(popoverRef)}
       popover={asNativePopover && 'auto'}
       onScroll={onScroll}
       data-testid="popover"

src/components/feedback/test/Popover-test.js

@@ -440,4 +440,15 @@ describe('Popover', () => {
       });
     });
   });
+
+  it('sets `elementRef`', () => {
+    const elementRef = { current: null };
+    const wrapper = createComponent({ elementRef });
+
+    assert.instanceOf(elementRef.current, HTMLDivElement);
+
+    wrapper.unmount();
+
+    assert.isNull(elementRef.current);
+  });
 });

src/pattern-library/components/patterns/feedback/PopoverPage.tsx

@@ -127,6 +127,18 @@ export default function PopoverPage() {
               </Library.InfoItem>
             </Library.Info>
           </Library.SectionL3>
+          <Library.SectionL3 title="elementRef">
+            <Library.Info>
+              <Library.InfoItem label="description">
+                Ref for the popover{"'"}s outermost element.
+              </Library.InfoItem>
+              <Library.InfoItem label="type">
+                <code>
+                  RefObject{'<'}HTMLElement{'>'}
+                </code>
+              </Library.InfoItem>
+            </Library.Info>
+          </Library.SectionL3>
           <Library.SectionL3 title="onClose">
             <Library.Info>
               <Library.InfoItem label="description">