onMouseDown passthrough in ActionMenu and AnchoredOverlay

.changeset/wet-plums-fetch.md

@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+onMouseDown passthrough from ActionMenu to AnchoredOverlay.

src/ActionMenu.tsx

@@ -6,12 +6,38 @@ import React, {useCallback, useEffect, useRef} from 'react'
 import {AnchoredOverlay} from './AnchoredOverlay'
 import {useProvidedStateOrCreate} from './hooks/useProvidedStateOrCreate'
 export interface ActionMenuProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
+  /**
+   * A custom function component used to render the anchor element.
+   * Will receive the `anchoredContent` prop as `children` prop.
+   * Uses a `Button` by default.
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   renderAnchor?: (props: any) => JSX.Element
+
+  /**
+   * Content that is passed into the renderAnchor component, which is a button by default.
+   */
   anchorContent?: React.ReactNode
+
+  /**
+   * A callback that triggers both on clicks and keyboard events. This callback will be overridden by item level `onAction` callbacks.
+   */
   onAction?: (props: ItemProps, event?: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => void
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `setOpen`.
+   */
   open?: boolean
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.
+   */
   setOpen?: (s: boolean) => void
+
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Record<string, unknown>
 }
 
 const ActionMenuItem = (props: ItemProps) => <Item role="menuitem" {...props} />
@@ -25,6 +51,7 @@ const ActionMenuBase = ({
   onAction,
   open,
   setOpen,
+  overlayProps,
   ...listProps
 }: ActionMenuProps): JSX.Element => {
   const pendingActionRef = useRef<() => unknown>()
@@ -69,7 +96,13 @@ const ActionMenuBase = ({
   }, [open])
 
   return (
-    <AnchoredOverlay renderAnchor={renderMenuAnchor} open={combinedOpenState} onOpen={onOpen} onClose={onClose}>
+    <AnchoredOverlay
+      renderAnchor={renderMenuAnchor}
+      open={combinedOpenState}
+      onOpen={onOpen}
+      onClose={onClose}
+      overlayProps={overlayProps}
+    >
       <List {...listProps} role="menu" renderItem={renderMenuItem} />
     </AnchoredOverlay>
   )

src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -5,10 +5,6 @@ import {useFocusZone} from '../hooks/useFocusZone'
 import {useAnchoredPosition, useRenderForcingRef} from '../hooks'
 import {uniqueId} from '../utils/uniqueId'
 
-function preventDefault(event: React.UIEvent) {
-  event.preventDefault()
-}
-
 export interface AnchoredOverlayProps extends Pick<OverlayProps, 'height' | 'width'> {
   /**
    * A custom function component used to render the anchor element.
@@ -30,6 +26,16 @@ export interface AnchoredOverlayProps extends Pick<OverlayProps, 'height' | 'wid
    * A callback which is called whenever the overlay is currently open and a "close gesture" is detected.
    */
   onClose?: (gesture: 'click-outside' | 'escape') => unknown
+
+  /**
+   * A callback that occurs when a user presses a mouse button over an element.
+   */
+  onMouseDown?: (event: React.MouseEvent) => unknown
+
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Record<string, unknown>
 }
 
 /**
@@ -43,6 +49,7 @@ export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
   onOpen,
   onClose,
   height,
+  overlayProps,
   width
 }) => {
   const anchorRef = useRef<HTMLElement>(null)
@@ -129,11 +136,10 @@ export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
           ref={updateOverlayRef}
           role="listbox"
           visibility={position ? 'visible' : 'hidden'}
-          onMouseDown={preventDefault}
-          onClick={preventDefault}
           height={height}
           width={width}
           {...overlayPosition}
+          {...overlayProps}
         >
           {children}
         </Overlay>

src/DropdownMenu/DropdownMenu.tsx

@@ -27,6 +27,11 @@ export interface DropdownMenuProps extends Partial<Omit<GroupedListProps, keyof
    * `selectedItem`, `undefined` will be passed.
    */
   onChange?: (item?: ItemInput) => unknown
+
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Record<string, unknown>
 }
 
 /**
@@ -40,6 +45,7 @@ export function DropdownMenu({
   placeholder,
   selectedItem,
   onChange,
+  overlayProps,
   ...listProps
 }: DropdownMenuProps): JSX.Element {
   const [open, setOpen] = useState(false)
@@ -79,7 +85,13 @@ export function DropdownMenu({
   )
 
   return (
-    <AnchoredOverlay renderAnchor={renderMenuAnchor} open={open} onOpen={onOpen} onClose={onClose}>
+    <AnchoredOverlay
+      renderAnchor={renderMenuAnchor}
+      open={open}
+      onOpen={onOpen}
+      onClose={onClose}
+      overlayProps={overlayProps}
+    >
       <List {...listProps} role="listbox" renderItem={renderMenuItem} />
     </AnchoredOverlay>
   )

src/stories/ActionMenu.stories.tsx

@@ -96,6 +96,11 @@ export function SimpleListStory(): JSX.Element {
         <ActionMenu
           onAction={onAction}
           anchorContent="Menu"
+          overlayProps={{
+            onMouseDown: (e: React.MouseEvent) =>
+              // eslint-disable-next-line no-console
+              console.log('onMouseDown in the interal Overlay can be useful for controlling event interactions', e)
+          }}
           items={[
             {text: 'New file', trailingText: '⌘O', disabled: true, leadingVisual: ProjectIcon},
             ActionList.Divider,