Anchored overlay can take an external AnchorRef (#1266)

Co-authored-by: Dusty Greif <[email protected]>

Author: VanAnderson

.changeset/odd-chairs-attack.md

@@ -0,0 +1,5 @@
+---
+"@primer/components": patch
+---
+
+Anchored overlay can take an external anchorRef.

src/ActionMenu.tsx

@@ -6,15 +6,38 @@ import React, {useCallback, useMemo} from 'react'
 import {AnchoredOverlay} from './AnchoredOverlay'
 import {useProvidedStateOrCreate} from './hooks/useProvidedStateOrCreate'
 import {OverlayProps} from './Overlay'
-export interface ActionMenuProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
+import {useProvidedRefOrCreate} from './hooks'
+
+interface ActionMenuPropsWithAnchor {
   /**
    * 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
+  renderAnchor?: <T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element
+
+  /**
+   * An override to the internal renderAnchor ref that will be spread on to the renderAnchor,
+   * When renderAnchor is defined, this prop will be spread on to the rendAnchor
+   * component that is passed in.
+   */
+  anchorRef?: React.RefObject<HTMLElement>
+}
+
+interface ActionMenuPropsWithoutAnchor {
+  /**
+   * A custom function component used to render the anchor element.
+   * When renderAnchor is null, an anchorRef is required.
+   */
+  renderAnchor: null
 
+  /**
+   * An override to the internal renderAnchor ref. When renderAnchor is null this can be
+   * used to make an anchor that is detached from ActionMenu.
+   */
+  anchorRef: React.RefObject<HTMLElement>
+}
+interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
   /**
    * Content that is passed into the renderAnchor component, which is a button by default.
    */
@@ -41,13 +64,16 @@ export interface ActionMenuProps extends Partial<Omit<GroupedListProps, keyof Li
   overlayProps?: Partial<OverlayProps>
 }
 
+export type ActionMenuProps = ActionMenuBaseProps & (ActionMenuPropsWithAnchor | ActionMenuPropsWithoutAnchor)
+
 const ActionMenuItem = (props: ItemProps) => <Item role="menuitem" {...props} />
 
 ActionMenuItem.displayName = 'ActionMenu.Item'
 
 const ActionMenuBase = ({
   anchorContent,
   renderAnchor = <T extends ButtonProps>(props: T) => <Button {...props} />,
+  anchorRef: externalAnchorRef,
   onAction,
   open,
   setOpen,
@@ -56,19 +82,22 @@ const ActionMenuBase = ({
   ...listProps
 }: ActionMenuProps): JSX.Element => {
   const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, setOpen, false)
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const onOpen = useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
   const onClose = useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
 
-  const renderMenuAnchor = useCallback(
-    <T extends React.HTMLAttributes<HTMLElement>>(props: T) => {
+  const renderMenuAnchor = useMemo(() => {
+    if (renderAnchor === null) {
+      return null
+    }
+    return <T extends React.HTMLAttributes<HTMLElement>>(props: T) => {
       return renderAnchor({
         'aria-label': 'menu',
         children: anchorContent,
         ...props
       })
-    },
-    [anchorContent, renderAnchor]
-  )
+    }
+  }, [anchorContent, renderAnchor])
 
   const itemsToRender = useMemo(() => {
     return items.map(item => {
@@ -89,6 +118,7 @@ const ActionMenuBase = ({
   return (
     <AnchoredOverlay
       renderAnchor={renderMenuAnchor}
+      anchorRef={anchorRef}
       open={combinedOpenState}
       onOpen={onOpen}
       onClose={onClose}

src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -1,17 +1,38 @@
-import React, {useCallback, useMemo, useRef} from 'react'
+import React, {useCallback, useMemo} from 'react'
 import Overlay, {OverlayProps} from '../Overlay'
 import {FocusTrapHookSettings, useFocusTrap} from '../hooks/useFocusTrap'
 import {FocusZoneHookSettings, useFocusZone} from '../hooks/useFocusZone'
-import {useAnchoredPosition, useRenderForcingRef} from '../hooks'
+import {useAnchoredPosition, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
 import {uniqueId} from '../utils/uniqueId'
 
-export interface AnchoredOverlayProps extends Pick<OverlayProps, 'height' | 'width'> {
+interface AnchoredOverlayPropsWithAnchor {
   /**
    * A custom function component used to render the anchor element.
    * Will receive the selected text as `children` prop when an item is activated.
    */
   renderAnchor: <T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element
 
+  /**
+   * An override to the internal ref that will be spread on to the renderAnchor
+   */
+  anchorRef?: React.RefObject<HTMLElement>
+}
+
+interface AnchoredOverlayPropsWithoutAnchor {
+  /**
+   * A custom function component used to render the anchor element.
+   * When renderAnchor is null, an anchorRef is required.
+   */
+  renderAnchor: null
+
+  /**
+   * An override to the internal renderAnchor ref that will be used to position the overlay.
+   * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
+   */
+  anchorRef: React.RefObject<HTMLElement>
+}
+
+interface AnchoredOverlayBaseProps extends Pick<OverlayProps, 'height' | 'width'> {
   /**
    * Determines whether the overlay portion of the component should be shown or not
    */
@@ -43,12 +64,16 @@ export interface AnchoredOverlayProps extends Pick<OverlayProps, 'height' | 'wid
   focusZoneSettings?: Partial<FocusZoneHookSettings>
 }
 
+export type AnchoredOverlayProps = AnchoredOverlayBaseProps &
+  (AnchoredOverlayPropsWithAnchor | AnchoredOverlayPropsWithoutAnchor)
+
 /**
  * An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
  * The overlay can be opened and navigated using keyboard or mouse.
  */
 export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
   renderAnchor,
+  anchorRef: externalAnchorRef,
   children,
   open,
   onOpen,
@@ -59,7 +84,7 @@ export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
   focusTrapSettings,
   focusZoneSettings
 }) => {
-  const anchorRef = useRef<HTMLElement>(null)
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
   const anchorId = useMemo(uniqueId, [])
 
@@ -106,15 +131,16 @@ export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
 
   return (
     <>
-      {renderAnchor({
-        ref: anchorRef,
-        id: anchorId,
-        'aria-labelledby': anchorId,
-        'aria-haspopup': 'listbox',
-        tabIndex: 0,
-        onClick: onAnchorClick,
-        onKeyDown: onAnchorKeyDown
-      })}
+      {renderAnchor &&
+        renderAnchor({
+          ref: anchorRef,
+          id: anchorId,
+          'aria-labelledby': anchorId,
+          'aria-haspopup': 'listbox',
+          tabIndex: 0,
+          onClick: onAnchorClick,
+          onKeyDown: onAnchorKeyDown
+        })}
       {open ? (
         <Overlay
           returnFocusRef={anchorRef}

src/SelectPanel/SelectPanel.tsx

@@ -21,7 +21,7 @@ interface SelectPanelMultiSelection {
 }
 
 interface SelectPanelBaseProps {
-  renderAnchor?: AnchoredOverlayProps['renderAnchor']
+  renderAnchor?: <T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element
   onOpenChange: (
     open: boolean,
     gesture: 'anchor-click' | 'anchor-key-press' | 'click-outside' | 'escape' | 'selection'
@@ -82,8 +82,8 @@ export function SelectPanel({
     [onOpenChange]
   )
 
-  const renderMenuAnchor: AnchoredOverlayProps['renderAnchor'] = useCallback(
-    props => {
+  const renderMenuAnchor = useCallback(
+    <T extends React.HTMLAttributes<HTMLElement>>(props: T) => {
       const selectedItems = Array.isArray(selected) ? selected : [...(selected ? [selected] : [])]
 
       return renderAnchor({

src/stories/ActionMenu.stories.tsx

@@ -11,7 +11,7 @@ import {
   ArrowRightIcon
 } from '@primer/octicons-react'
 import {Meta} from '@storybook/react'
-import React, {useCallback, useState} from 'react'
+import React, {useCallback, useState, useRef} from 'react'
 import styled from 'styled-components'
 import {ThemeProvider} from '..'
 import {ActionMenu} from '../ActionMenu'
@@ -247,3 +247,28 @@ export function CustomTrigger(): JSX.Element {
   )
 }
 CustomTrigger.storyName = 'Custom Trigger'
+
+export function ActionMenuWithExternalAnchor(): JSX.Element {
+  const [isOpen, setIsOpen] = useState(false)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  return (
+    <>
+      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
+        Open Menu
+      </Button>
+      <ActionMenu
+        renderAnchor={null}
+        anchorRef={buttonRef}
+        open={isOpen}
+        setOpen={setIsOpen}
+        items={[
+          {text: 'New file'},
+          ActionList.Divider,
+          {text: 'Copy link'},
+          {text: 'Edit file'},
+          {text: 'Delete file', variant: 'danger'}
+        ]}
+      />
+    </>
+  )
+}

src/stories/Overlay.stories.tsx

@@ -1,7 +1,6 @@
 import React, {useState, useRef} from 'react'
 import {Meta} from '@storybook/react'
 import styled from 'styled-components'
-
 import {BaseStyles, Overlay, Button, Text, ButtonDanger, ThemeProvider, Position, Flex} from '..'
 
 export default {