Action Menu

docs/content/ActionMenu.mdx

@@ -0,0 +1,74 @@
+---
+title: ActionMenu
+---
+
+An `ActionMenu` is an ActionList-based component for creating a menu of actions that expands through a trigger button.
+
+## Default example
+
+```jsx live
+<ActionMenu
+  anchorContent="Menu"
+  onAction={({text}) => console.log(text)}
+  items={[
+    {text: 'New file'},
+    ActionMenu.Divider,
+    {text: 'Copy link'},
+    {text: 'Edit file'},
+    {text: 'Delete file', variant: 'danger'}
+  ]}
+/>
+```
+
+## Example with grouped items
+
+```jsx live
+<ActionMenu
+  anchorContent="Menu"
+  onAction={({text}) => console.log(text)}
+  groupMetadata={[
+    {groupId: '0'},
+    {groupId: '1', header: {title: 'Live query', variant: 'subtle'}},
+    {groupId: '2', header: {title: 'Layout', variant: 'subtle'}},
+    {groupId: '3'},
+    {groupId: '4'}
+  ]}
+  items={[
+    {leadingVisual: TypographyIcon, text: 'Rename', groupId: '0'},
+    {leadingVisual: VersionsIcon, text: 'Duplicate', groupId: '0'},
+    {leadingVisual: SearchIcon, text: 'repo:github/github', groupId: '1'},
+    {
+      leadingVisual: NoteIcon,
+      text: 'Table',
+      description: 'Information-dense table optimized for operations across teams',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      leadingVisual: ProjectIcon,
+      text: 'Board',
+      description: 'Kanban-style board focused on visual states',
+      descriptionVariant: 'block',
+      groupId: '2'
+    },
+    {
+      leadingVisual: FilterIcon,
+      text: 'Save sort and filters to current view',
+      groupId: '3'
+    },
+    {leadingVisual: FilterIcon, text: 'Save sort and filters to new view', groupId: '3'},
+    {leadingVisual: GearIcon, text: 'View settings', groupId: '4'}
+  ]}
+/>
+```
+
+## Component props
+
+| Name          | Type                                  |      Default      | Description                                                                                                                                                          |
+| :------------ | :------------------------------------ | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items         | `ItemProps[]`                         |    `undefined`    | Required. A list of item objects conforming to the `ActionList.Item` props interface.                                                                                |
+| renderItem    | `(props: ItemProps) => JSX.Element`   | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for `ActionList`-wide custom item rendering.                                    |
+| groupMetadata | `GroupProps[]`                        |    `undefined`    | Optional. If defined, `ActionList` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property.              |
+| renderAnchor  | `(props: ButtonProps) => JSX.Element` |     `Button`      | Optional. If defined, provided component will be used to render the menu anchor. Will receive the selected `Item` text as `children` prop when an item is activated. |
+| anchorContent | React.ReactNode                       |    `undefined`    | Optional. If defined, it will be passed to the trigger as the elements child.                                                                                        |
+| onAction      | (props: ItemProps) => void            |    `undefined`    | Optional. If defined, this function will be called when a menu item is activated either by a click or a keyboard press.                                              |

docs/src/@primer/gatsby-theme-doctocat/live-code-scope.js

@@ -11,7 +11,13 @@ import {
   MailIcon,
   GitCommitIcon,
   FlameIcon,
-  MarkGithubIcon
+  MarkGithubIcon,
+  NoteIcon,
+  ProjectIcon,
+  FilterIcon,
+  GearIcon,
+  TypographyIcon,
+  VersionsIcon
 } from '@primer/octicons-react'
 import State from '../../../components/State'
 
@@ -29,5 +35,11 @@ export default {
   MailIcon,
   GitCommitIcon,
   FlameIcon,
-  MarkGithubIcon
+  MarkGithubIcon,
+  NoteIcon,
+  ProjectIcon,
+  FilterIcon,
+  GearIcon,
+  TypographyIcon,
+  VersionsIcon
 }

src/ActionList/Item.tsx

@@ -1,9 +1,9 @@
 import {CheckIcon, IconProps} from '@primer/octicons-react'
 import React from 'react'
-import styled from 'styled-components'
 import {get} from '../constants'
 import sx, {SxProp} from '../sx'
 import {ItemInput} from './List'
+import styled from 'styled-components'
 
 /**
  * Contract for props passed to the `Item` component.
@@ -32,6 +32,16 @@ export interface ItemProps extends React.ComponentPropsWithoutRef<'div'>, SxProp
    */
   leadingVisual?: React.FunctionComponent<IconProps>
 
+  /**
+   * Icon (or similar) positioned after `Item` text.
+   */
+  trailingIcon?: React.FunctionComponent<IconProps>
+
+  /**
+   * Text positioned after `Item` text and optional trailing icon.
+   */
+  trailingText?: string
+
   /**
    * Style variations associated with various `Item` types.
    *
@@ -44,6 +54,11 @@ export interface ItemProps extends React.ComponentPropsWithoutRef<'div'>, SxProp
    * For `Item`s which can be selected, whether the `Item` is currently selected.
    */
   selected?: boolean
+
+  /**
+   * Designates the group that an item belongs to.
+   */
+  groupId?: string
 }
 
 const StyledItem = styled.div<{variant: ItemProps['variant']} & SxProp>`
@@ -72,14 +87,10 @@ const StyledTextContainer = styled.div<{descriptionVariant: ItemProps['descripti
   flex-direction: ${({descriptionVariant}) => (descriptionVariant === 'inline' ? 'row' : 'column')};
 `
 
-const LeadingVisualContainer = styled.div`
-   {
-    /* Match visual height to adjacent text line height.
-     *
-     * TODO: When rem-based spacing on a 4px scale lands, replace
-     * hardcoded '20px' with '${get('space.s20')}'.
-     */
-  }
+const BaseVisualContainer = styled.div`
+  // Match visual height to adjacent text line height.
+  // TODO: When rem-based spacing on a 4px scale lands, replace
+  // hardcoded '20px' with '${get('space.s20')}'.
   height: 20px;
   width: ${get('space.3')};
   display: flex;
@@ -93,6 +104,20 @@ const LeadingVisualContainer = styled.div`
   }
 `
 
+const LeadingVisualContainer = styled(BaseVisualContainer)``
+
+const TrailingVisualContainer = styled(BaseVisualContainer)`
+  color: ${get('colors.icon.tertiary')};
+  margin-left: auto;
+  margin-right: 0;
+  div:nth-child(2) {
+    margin-left: ${get('space.2')};
+  }
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-end;
+`
+
 const DescriptionContainer = styled.span`
   color: ${get('colors.text.secondary')};
 `
@@ -106,9 +131,11 @@ export function Item({
   descriptionVariant = 'inline',
   selected,
   leadingVisual: LeadingVisual,
+  trailingIcon: TrailingIcon,
+  trailingText,
   variant = 'default',
   ...props
-}: Partial<ItemProps> & {item: ItemInput}): JSX.Element {
+}: Partial<ItemProps> & {item?: ItemInput}): JSX.Element {
   return (
     <StyledItem tabIndex={-1} variant={variant} aria-selected={selected} {...props}>
       {!!selected === selected && <LeadingVisualContainer>{selected && <CheckIcon />}</LeadingVisualContainer>}
@@ -121,6 +148,16 @@ export function Item({
         <div>{text}</div>
         {description && <DescriptionContainer>{description}</DescriptionContainer>}
       </StyledTextContainer>
+      {(TrailingIcon || trailingText) && (
+        <TrailingVisualContainer>
+          {trailingText && <div>{trailingText}</div>}
+          {TrailingIcon && (
+            <div>
+              <TrailingIcon />
+            </div>
+          )}
+        </TrailingVisualContainer>
+      )}
     </StyledItem>
   )
 }

src/ActionList/List.tsx

@@ -1,7 +1,7 @@
+import React from 'react'
 import type {AriaRole} from '../utils/types'
 import {Group, GroupProps} from './Group'
 import {Item, ItemProps} from './Item'
-import React from 'react'
 import {Divider} from './Divider'
 import styled from 'styled-components'
 import {get} from '../constants'

src/ActionMenu.tsx

@@ -0,0 +1,132 @@
+import {List, ListPropsBase, GroupedListProps} from './ActionList/List'
+import {Item, ItemProps} from './ActionList/Item'
+import {Divider} from './ActionList/Divider'
+import Button, {ButtonProps} from './Button'
+import React, {useCallback, useRef, useState} from 'react'
+import Overlay from './Overlay'
+import {useFocusTrap} from './hooks/useFocusTrap'
+import {useFocusZone} from './hooks/useFocusZone'
+import {useAnchoredPosition} from './hooks/useAnchoredPosition'
+import {useRenderForcingRef} from './hooks/useRenderForcingRef'
+import {uniqueId} from './utils/uniqueId'
+
+export interface ActionMenuProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  renderAnchor?: (props: any) => JSX.Element
+  anchorContent?: React.ReactNode
+  onAction?: (props: ItemProps) => void
+}
+
+const ActionMenuItem = (props: ItemProps) => <Item role="menuitem" {...props} />
+
+ActionMenuItem.displayName = 'ActionMenu.Item'
+
+const ActionMenuBase = ({
+  anchorContent,
+  renderAnchor = <T extends ButtonProps>(props: T) => <Button {...props}>{anchorContent}</Button>,
+  renderItem = Item,
+  onAction,
+  ...listProps
+}: ActionMenuProps): JSX.Element => {
+  const anchorRef = useRef<HTMLElement>(null)
+  const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
+  const anchorId = `dropdownMenuAnchor-${uniqueId()}`
+  const [open, setOpen] = useState<boolean>(false)
+  const [state, setState] = useState<'closed' | 'buttonFocus' | 'listFocus'>('closed')
+  const onDismiss = useCallback(() => {
+    setOpen(false)
+    setState('closed')
+  }, [])
+
+  const onAnchorKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      if (!event.defaultPrevented) {
+        if (state === 'closed') {
+          if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            setState('listFocus')
+            setOpen(true)
+            event.preventDefault()
+          } else if (event.key === ' ' || event.key === 'Enter') {
+            setState('buttonFocus')
+            setOpen(true)
+            event.preventDefault()
+          }
+        } else if (state === 'buttonFocus') {
+          if (['ArrowDown', 'ArrowUp', 'Tab', 'Enter'].indexOf(event.key) !== -1) {
+            setState('listFocus')
+            event.preventDefault()
+          } else if (event.key === 'Escape') {
+            setState('closed')
+            onDismiss()
+            event.preventDefault()
+          }
+        }
+      }
+    },
+    [state, onDismiss]
+  )
+  const onAnchorClick = useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      if (!event.defaultPrevented && event.button === 0 && !open) {
+        setOpen(true)
+        setState('buttonFocus')
+      }
+    },
+    [open]
+  )
+
+  const {position} = useAnchoredPosition({anchorElementRef: anchorRef, floatingElementRef: overlayRef})
+
+  useFocusZone({containerRef: overlayRef, disabled: !open || state !== 'listFocus'}, [position])
+  useFocusTrap({containerRef: overlayRef, disabled: !open || state !== 'listFocus'}, [position])
+
+  return (
+    <>
+      {renderAnchor({
+        ref: anchorRef,
+        id: anchorId,
+        'aria-labelledby': anchorId,
+        'aria-haspopup': 'listbox',
+        'aria-label': 'menu',
+        onClick: onAnchorClick,
+        onKeyDown: onAnchorKeyDown,
+        children: anchorContent,
+        tabIndex: 0
+      })}
+      {open ? (
+        <Overlay
+          initialFocusRef={anchorRef}
+          returnFocusRef={anchorRef}
+          onClickOutside={onDismiss}
+          onEscape={onDismiss}
+          ref={updateOverlayRef}
+          {...position}
+        >
+          <List
+            {...listProps}
+            role="menu"
+            renderItem={({onClick, ...itemProps}) =>
+              renderItem({
+                ...itemProps,
+                role: 'menuitem',
+                onKeyPress: _event => {
+                  onAction?.(itemProps as ItemProps)
+                  onDismiss()
+                },
+                onClick: event => {
+                  onAction?.(itemProps as ItemProps)
+                  onClick?.(event)
+                  onDismiss()
+                }
+              })
+            }
+          />
+        </Overlay>
+      ) : null}
+    </>
+  )
+}
+
+ActionMenuBase.displayName = 'ActionMenu'
+
+export const ActionMenu = Object.assign(ActionMenuBase, {Divider: Divider, Item: ActionMenuItem})