Feat: popover implement click outside

.changeset/chilled-rules-boil.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Feat: popover implement click outside

e2e/components/Popover.test.ts

@@ -11,6 +11,10 @@ const stories = [
     title: 'Playground',
     id: 'components-popover--playground',
   },
+  {
+    title: 'Close On Click Outside',
+    id: 'components-popover-features--close-on-click-outside',
+  },
 ] as const
 
 test.describe('Popover', () => {

packages/react/src/PageLayout/PageLayout.module.css

@@ -70,6 +70,9 @@ body[data-page-layout-dragging='true'] * {
   margin-right: auto;
   margin-left: auto;
   flex-wrap: wrap;
+  /* the wrapper should match the Root's dimensions by default */
+  width: 100%;
+  height: 100%;
 
   &:where([data-width='medium']) {
     max-width: 768px;

packages/react/src/Popover/Popover.docs.json

@@ -62,6 +62,16 @@
           "type": "| 'auto' | 'hidden' | 'scroll' | 'visible'",
           "defaultValue": "'auto'",
           "description": "Sets the overflow behavior of the popover content."
+        },
+        {
+          "name": "onClickOutside",
+          "type": "(event: MouseEvent | TouchEvent) => void",
+          "description": "Callback fired when a click is detected outside the popover content"
+        },
+        {
+          "name": "ignoreClickRefs",
+          "type": "React.RefObject<HTMLElement>[]",
+          "description": "Refs to elements that should be ignored when detecting outside clicks"
         }
       ]
     }

packages/react/src/Popover/Popover.features.stories.tsx

@@ -0,0 +1,38 @@
+import type {Meta} from '@storybook/react-vite'
+import Heading from '../Heading'
+import Popover from './Popover'
+import Text from '../Text'
+import {Button} from '../Button'
+import React from 'react'
+
+export default {
+  title: 'Components/Popover/Features',
+  component: Popover,
+} as Meta<typeof Popover>
+
+export const CloseOnClickOutside = () => {
+  const [open, setOpen] = React.useState(true)
+  const buttonRef = React.useRef<HTMLButtonElement>(null)
+  return (
+    <>
+      <Button
+        style={{marginLeft: 'auto', marginRight: 'auto', marginBottom: 'var(--base-size-4)'}}
+        ref={buttonRef}
+        onClick={() => setOpen(prev => !prev)}
+      >
+        Toggle Popover
+      </Button>
+      <Popover relative open={open} caret="top">
+        <Popover.Content
+          style={{marginTop: 'var(--base-size-8)'}}
+          onClickOutside={() => setOpen(false)}
+          ignoreClickRefs={[buttonRef]}
+        >
+          <Heading style={{fontSize: 'var(--text-title-size-small)'}}>Popover heading</Heading>
+          <Text as="p">Message about popovers</Text>
+          <Button>Got it!</Button>
+        </Popover.Content>
+      </Popover>
+    </>
+  )
+}

packages/react/src/Popover/Popover.tsx

@@ -1,7 +1,11 @@
 import {clsx} from 'clsx'
 import classes from './Popover.module.css'
 import type {HTMLProps} from 'react'
-import React from 'react'
+import React, {useRef} from 'react'
+import {useOnOutsideClick} from '../hooks'
+
+// Stable empty array reference to avoid unnecessary re-renders
+const EMPTY_IGNORE_CLICK_REFS: React.RefObject<HTMLElement>[] = []
 
 type CaretPosition =
   | 'top'
@@ -51,15 +55,43 @@ export type PopoverContentProps = {
   width?: 'xsmall' | 'small' | 'large' | 'medium' | 'auto' | 'xlarge'
   height?: 'small' | 'large' | 'medium' | 'auto' | 'xlarge' | 'fit-content'
   overflow?: 'auto' | 'hidden' | 'scroll' | 'visible'
+  /*
+   * Callback fired when a click is detected outside the popover content
+   */
+  onClickOutside?: (event: MouseEvent | TouchEvent) => void
+  /*
+   * Refs to elements that should be ignored when detecting outside clicks
+   */
+  ignoreClickRefs?: React.RefObject<HTMLElement>[]
 } & HTMLProps<HTMLDivElement>
 
 const PopoverContent: React.FC<React.PropsWithChildren<PopoverContentProps>> = ({
   className,
   width = 'small',
   height = 'fit-content',
+  onClickOutside,
+  ignoreClickRefs,
   ...props
 }) => {
-  return <div data-width={width} data-height={height} className={clsx(className, classes.PopoverContent)} {...props} />
+  const divRef = useRef(null)
+
+  const outsideClickHandler = onClickOutside ?? (() => {})
+
+  useOnOutsideClick({
+    onClickOutside: outsideClickHandler,
+    containerRef: divRef,
+    ignoreClickRefs: ignoreClickRefs ?? EMPTY_IGNORE_CLICK_REFS,
+  })
+
+  return (
+    <div
+      ref={divRef}
+      data-width={width}
+      data-height={height}
+      className={clsx(className, classes.PopoverContent)}
+      {...props}
+    />
+  )
 }
 
 PopoverContent.displayName = 'Popover.Content'