DropdownMenu

docs/content/ActionList.mdx

@@ -63,5 +63,5 @@ An `ActionList` is a list of items which can be activated or selected. `ActionLi
 | Name          | Type                                |      Default      | Description                                                                                                                                             |
 | :------------ | :---------------------------------- | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | items         | `ItemProps[]`                       |    `undefined`    | Required. A list of item objects conforming to the `ActionList.Item` props interface.                                                                   |
-| renderItems   | `(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.                       |
+| 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. |

docs/content/DropdownMenu.mdx

@@ -0,0 +1,42 @@
+---
+title: DropdownMenu
+---
+
+A `DropdownMenu` provides an anchor (button by default) that will open a floating menu of selectable items.  The menu can be opened and navigated using keyboard or mouse.  When an item is selected, the menu will close and the `onChange` callback will be called.  If the default anchor button is used, the anchor contents will be updated with the selection.
+
+## Example
+
+```javascript live noinline
+function DemoComponent() {
+  const items = React.useMemo(() => [{text: '🔵 Cyan', id: 5}, {text: '🔴 Magenta'}, {text: '🟡 Yellow'}], [])
+  const [selectedItem, setSelectedItem] = React.useState()
+
+  return (
+    <DropdownMenu
+      renderAnchor={({children, 'aria-labelledby': ariaLabelledBy, ...anchorProps}) => (
+        <DropdownButton aria-labelledby={`favorite-color-label ${ariaLabelledBy}`} {...anchorProps}>
+          {children}
+        </DropdownButton>
+      )}
+      placeholder="🎨"
+      items={items}
+      selectedItem={selectedItem}
+      onChange={setSelectedItem}
+    />
+  )
+}
+
+render(<DemoComponent />)
+```
+
+## Component props
+
+| Name             | Type                                          |      Default      | Description                                                                                                                                                                                    |
+| :--------------- | :-------------------------------------------- | :---------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items            | `ItemProps[]`                                 |    `undefined`    | Required. A list of item objects to display in the menu                                                                                                                                        |
+| selectedItem     | `ItemInput`                                   |    `undefined`    | An `ItemProps` item from the list of `items` which is currently selected. This item will receive a checkmark next to it in the menu.                                                           |
+| onChange? | (item?: ItemInput) => unknown                 |    `undefined`    | A callback which receives the selected item or `undefined` when an item is activated in the menu. If the activated item is the same as the current `selectedItem`, `undefined` will be passed. |
+| placeholder      | `string`                                      |    `undefined`    | Optional. A placeholder value to display when there is no current selection.                                                                                                                   |
+| renderAnchor     | `(props: DropdownButtonProps) => JSX.Element` | `DropdownButton`  | 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.                           |
+| renderItem       | `(props: ItemProps) => JSX.Element`           | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for custom item rendering.                                                                                |
+| groupMetadata    | `GroupProps[]`                                |    `undefined`    | Optional. If defined, `DropdownMenu` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property.                                      |

docs/content/Overlay.mdx

@@ -7,18 +7,17 @@ An `Overlay` is a flexible floating surface, used to display transient content s
 Behaviors include:
 
 - Rendering the overlay in a React Portal so that it always renders on top of other content on the page
-- Positioning the overlay according to passed in settings, using our context-aware positioning algorithms
 - Trapping focus
 - Calling a user provided function when the user presses `Escape`
 - Calling a user provided function when the user clicks outside of the container
-- Focusing either  user provided element, or the first focusable element in the container when it is opened
+- Focusing either user provided element, or the first focusable element in the container when it is opened
 - Returning focus to an element when container is closed
 
 ## Accessibility considerations
 
 - The `Overlay` must either have:
-   - A value set for the `aria-labelledby` attribute that refers to a visible title.
-   - An  `aria-label` attribute
+  - A value set for the `aria-labelledby` attribute that refers to a visible title.
+  - An `aria-label` attribute
 - If the `Overlay` should also have a longer description, use `aria-describedby`
 - The `Overlay` component has a `role="dialog"` set on it, if you are using `Overlay` for alerts, you can pass in `role="alertdialog"` instead. Please read the [W3C guidelines](https://www.w3.org/TR/wai-aria-1.1/#alertdialog) to determine which role is best for your use case
 - The `Overlay` component has `aria-modal` set to `true` by default and should not be overridden as all `Overlay`s behave as modals.
@@ -39,9 +38,8 @@ const Demo = () => {
         open overlay
       </Button>
       {/* be sure to conditionally render the Overlay. This helps with performance and is required. */}
-      {isOpen &&
+      {isOpen && (
         <Overlay
-          anchorRef={anchorRef}
           initialFocusRef={noButtonRef}
           returnFocusRef={anchorRef}
           ignoreClickRefs={[anchorRef]}
@@ -51,17 +49,16 @@ const Demo = () => {
         >
           <Flex flexDirection="column" p={2}>
             <Text id="title">Are you sure you would like to delete this item?</Text>
-            <Button >yes</Button>
+            <Button>yes</Button>
             <Button ref={noButtonRef}>no</Button>
           </Flex>
         </Overlay>
-      }
-
+      )}
     </>
   )
 }
 
-render(<Demo/>)
+render(<Demo />)
 ```
 
 ## System props
@@ -70,15 +67,13 @@ render(<Demo/>)
 
 ## Component props
 
-| Name | Type   | Default | Description                         |
-| :--- | :----- | :-----: | :---------------------------------- |
-| positionSettings | See the [`PositionSettings interface`]() section of the `anchoredPosition` docs | `{side: 'outside-bottom', align: 'start', anchorOffset: 4, alignmentOffset: 4, allowOutOfBounds: false }` | Optional. Settings used to position the `Overlay`. If none are provided, `Overlay` is positioned on the bottom left of the `anchorRef`. |
-| positionDeps | `React.DependencyList` | `undefined` | Optional. If defined, the position of the `Overlay` will only be recalulated when one of the dependencies in this array changes. |
-| ignoreClickRefs   | `React.RefObject<HTMLElement> []` | `undefined` | Optional. An array of ref objects to ignore clicks on in the `onOutsideClick` behavior. This is often used to ignore clicking on the element that toggles the open/closed state for the `Overlay` to prevent the `Overlay` from being toggled twice. |
-| initialFocusRef  | `React.RefObject<HTMLElement>` | `undefined` | Optional. Ref for the element to focus when the `Overlay` is opened. If nothing is provided, the first focusable element in the `Overlay` body is focused.  |
-| anchorRef | `React.RefObject<HTMLElement>` | `undefined` | Required. Element the `Overlay` should be anchored to. |
-| returnFocusRef  | `React.RefObject<HTMLElement>` | `undefined` | Required. Ref for the element to focus when the `Overlay` is closed.  |
-| onClickOutside  | `function` | `undefined` | Required. Function to call when clicking outside of the `Overlay`. Typically this function sets the `Overlay` visibility state to `false`.  |
-| onEscape  | `function` | `undefined` | Required. Function to call when user presses `Escape`. Typically this function sets the `Overlay` visibility state to `false`.  |
-| width  | `'sm', 'md', 'lg', 'xl', 'auto'` | `auto` | Sets the width of the `Overlay`, pick from our set list of widths, or pass `auto` to automatically set the width based on the content of the `Overlay`. `sm` corresponds to `256px`, `md` corresponds to `320px`, `lg` corresponds to `480px`, and `xl` corresponds to `640px`.  |
-| height  | `'sm', 'md', 'auto'` | `auto` | Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`. `sm` corresponds to `480px` and `md` corresponds to `640px`.  |
+| Name            | Type                              |   Default   | Description                                                                                                                                                                                                                                                                     |
+| :-------------- | :-------------------------------- | :---------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ignoreClickRefs | `React.RefObject<HTMLElement> []` | `undefined` | Optional. An array of ref objects to ignore clicks on in the `onOutsideClick` behavior. This is often used to ignore clicking on the element that toggles the open/closed state for the `Overlay` to prevent the `Overlay` from being toggled twice.                            |
+| initialFocusRef | `React.RefObject<HTMLElement>`    | `undefined` | Optional. Ref for the element to focus when the `Overlay` is opened. If nothing is provided, the first focusable element in the `Overlay` body is focused.                                                                                                                      |
+| anchorRef       | `React.RefObject<HTMLElement>`    | `undefined` | Required. Element the `Overlay` should be anchored to.                                                                                                                                                                                                                          |
+| returnFocusRef  | `React.RefObject<HTMLElement>`    | `undefined` | Required. Ref for the element to focus when the `Overlay` is closed.                                                                                                                                                                                                            |
+| onClickOutside  | `function`                        | `undefined` | Required. Function to call when clicking outside of the `Overlay`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                      |
+| onEscape        | `function`                        | `undefined` | Required. Function to call when user presses `Escape`. Typically this function sets the `Overlay` visibility state to `false`.                                                                                                                                                  |
+| width           | `'sm', 'md', 'lg', 'xl', 'auto'`  |   `auto`    | Sets the width of the `Overlay`, pick from our set list of widths, or pass `auto` to automatically set the width based on the content of the `Overlay`. `sm` corresponds to `256px`, `md` corresponds to `320px`, `lg` corresponds to `480px`, and `xl` corresponds to `640px`. |
+| height          | `'sm', 'md', 'auto'`              |   `auto`    | Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`. `sm` corresponds to `480px` and `md` corresponds to `640px`.                                                         |

src/ActionList/Item.tsx

@@ -1,8 +1,9 @@
-import type {IconProps} from '@primer/octicons-react'
+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'
 
 /**
  * Contract for props passed to the `Item` component.
@@ -38,6 +39,11 @@ export interface ItemProps extends React.ComponentPropsWithoutRef<'div'>, SxProp
    * - `"danger"` - A destructive action `Item`.
    */
   variant?: 'default' | 'danger'
+
+  /**
+   * For `Item`s which can be selected, whether the `Item` is currently selected.
+   */
+  selected?: boolean
 }
 
 const StyledItem = styled.div<{variant: ItemProps['variant']} & SxProp>`
@@ -98,12 +104,14 @@ export function Item({
   text,
   description,
   descriptionVariant = 'inline',
+  selected,
   leadingVisual: LeadingVisual,
   variant = 'default',
   ...props
-}: Partial<ItemProps>): JSX.Element {
+}: Partial<ItemProps> & {item: ItemInput}): JSX.Element {
   return (
-    <StyledItem variant={variant} {...props}>
+    <StyledItem tabIndex={-1} variant={variant} aria-selected={selected} {...props}>
+      {!!selected === selected && <LeadingVisualContainer>{selected && <CheckIcon />}</LeadingVisualContainer>}
       {LeadingVisual && (
         <LeadingVisualContainer>
           <LeadingVisual />

src/ActionList/List.tsx

@@ -1,3 +1,4 @@
+import type {AriaRole} from '../utils/types'
 import {Group, GroupProps} from './Group'
 import {Item, ItemProps} from './Item'
 import React from 'react'
@@ -6,28 +7,35 @@ import styled from 'styled-components'
 import {get} from '../constants'
 import {SystemCssProperties} from '@styled-system/css'
 
+export type ItemInput = ItemProps | (Partial<ItemProps> & {renderItem: typeof Item})
+
 /**
  * Contract for props passed to the `List` component.
  */
-interface ListPropsBase {
+export interface ListPropsBase {
   /**
    * A collection of `Item` props and `Item`-level custom `Item` renderers.
    */
-  items: (ItemProps | (Partial<ItemProps> & {renderItem: typeof Item}))[]
+  items: ItemInput[]
+
+  /**
+   * The ARIA role describing the function of `List` component. `listbox` is a common value.
+   */
+  role?: AriaRole
 
   /**
    * A `List`-level custom `Item` renderer. Every `Item` within this `List`
    * without a `Group`-level or `Item`-level custom `Item` renderer will be
    * rendered using this function component.
    */
-  renderItem?: (props: ItemProps) => JSX.Element
+  renderItem?: typeof Item
 
   /**
    * A `List`-level custom `Group` renderer. Every `Group` within this `List`
    * without a `Group`-level custom `Item` renderer will be rendered using
    * this function component.
    */
-  renderGroup?: (props: GroupProps) => JSX.Element
+  renderGroup?: typeof Group
 
   /**
    * Style variations. Usage is discretionary.
@@ -41,7 +49,7 @@ interface ListPropsBase {
 /**
  * Contract for props passed to the `List` component, when its `Item`s are collected in `Group`s.
  */
-interface GroupedListProps extends ListPropsBase {
+export interface GroupedListProps extends ListPropsBase {
   /**
    * A collection of `Group` props (except `items`), plus a unique group identifier
    * and `Group`-level custom `Item` or `Group` renderers.
@@ -123,10 +131,11 @@ export function List(props: ListProps): JSX.Element {
    * An `Item`-level, `Group`-level, or `List`-level custom `Item` renderer,
    * or the default `Item` renderer.
    */
-  const renderItem = (itemProps: ItemProps | (Partial<ItemProps> & {renderItem: typeof Item})) =>
-    ((('renderItem' in itemProps && itemProps.renderItem) ?? props.renderItem) || Item).call(null, {
+  const renderItem = (itemProps: ItemInput, item: ItemInput) =>
+    (('renderItem' in itemProps && itemProps.renderItem) || props.renderItem || Item).call(null, {
       ...itemProps,
-      sx: {...itemStyle, ...itemProps.sx}
+      sx: {...itemStyle, ...itemProps.sx},
+      item
     })
 
   /**
@@ -138,7 +147,7 @@ export function List(props: ListProps): JSX.Element {
 
   if (!isGroupedListProps(props)) {
     // When no `groupMetadata`s is provided, collect rendered `Item`s into a single anonymous `Group`.
-    groups = [{items: props.items?.map(renderItem)}]
+    groups = [{items: props.items?.map(item => renderItem(item, item))}]
   } else {
     // When `groupMetadata` is provided, collect rendered `Item`s into their associated `Group`s.
 
@@ -159,7 +168,13 @@ export function List(props: ListProps): JSX.Element {
         ...group,
         items: [
           ...(group?.items ?? []),
-          renderItem({...(group && 'renderItem' in group && {renderItem: group.renderItem}), ...itemProps})
+          renderItem(
+            {
+              ...(group && 'renderItem' in group && {renderItem: group.renderItem}),
+              ...itemProps
+            },
+            itemProps
+          )
         ]
       })
     }

src/DropdownMenu/DropdownButton.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import {TriangleDownIcon} from '@primer/octicons-react'
+import Button, {ButtonProps} from '../Button/Button'
+import StyledOcticon from '../StyledOcticon'
+
+export type DropdownButtonProps = ButtonProps
+
+export const DropdownButton = React.forwardRef<HTMLElement, React.PropsWithChildren<DropdownButtonProps>>(
+  ({children, ...props}: React.PropsWithChildren<DropdownButtonProps>, ref): JSX.Element => (
+    <Button ref={ref} {...props}>
+      {children}
+      <StyledOcticon icon={TriangleDownIcon} ml={1} />
+    </Button>
+  )
+)