@primer/components 33.0.0 → 33.1.0-rc.6856bcf5

package/docs/content/CounterLabel.md

@@ -0,0 +1,22 @@
+---
+title: CounterLabel
+status: Alpha
+---
+
+Use the CounterLabel component to add a count to navigational elements and buttons.
+
+## Default example
+
+```jsx live
+<>
+  <CounterLabel>12</CounterLabel>
+  <CounterLabel scheme="primary">13</CounterLabel>
+  <CounterLabel scheme="secondary">13</CounterLabel>
+</>
+```
+
+## Component props
+
+| Name   | Type   | Default | Description                                                                                                                                                                        |
+| :----- | :----- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| scheme | String |         | Pass in 'primary' for a darker background and inverse text, or 'gray-light' for a lighter background and primary text. Omitting the scheme prop renders the default counter scheme |

package/docs/content/Details.md

@@ -0,0 +1,102 @@
+---
+title: Details
+status: Alpha
+---
+
+`Details` is a styled `details` element for use with the `useDetails` hook. The `useDetails` hook returns the `open` state, a `setOpen` function to manually change the open state, and **`getDetailsProps` which must be spread onto your `Details` element in order for `Details` to get receive the proper behaviors provided by the hook**. See Kent Dodd's article on this pattern [here](https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters).
+
+The `useDetails` hook also takes a few configuration options as parameters which are noted in the table below.
+
+You must use a `summary` element as your `Details` trigger button. To style your summary element like a [Button](./Button), you can use the `as` prop (see example below).
+
+It's also possible to use the `useDetails` hook with components other than the Primer `Details`, such as a custom `Details` or `Modal` wrapper in your consuming application. All that matters is that the outer element is a `details` and it contains a `summary` for the button that opens and closes the component, and that `getDetailsProps` is properly spread onto the component rendering your `details` element.
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">Hello</Button>
+        This is some content
+      </Details>
+    )
+  }}
+</State>
+```
+
+You can use the `open` state returned from the hook to conditionally render content:
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, open} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">{open ? 'open' : 'close'}</Button>
+        This is some content
+      </Details>
+    )
+  }}
+</State>
+```
+
+You can also manually show/hide the content using the `setOpen` function returned from the hook. This can be useful if you have action items in the content of the component such as confirmation buttons:
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, setOpen} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">Delete item</Button>
+        Are you sure?
+        <ButtonDanger onClick={() => setOpen(false)}>Yes I'm sure</ButtonDanger>
+      </Details>
+    )
+  }}
+</State>
+```
+
+In previous versions of Primer React Components, we allowed users to pass in a custom `onToggle` function. You can do this now by overriding the `onToggle` function returned in `getDetailsProps`. Please note that in most cases, you'll want the hook's handling of `onToggle` to be run as well, so that the internal state is properly updated. To do this, manually call the `onToggle` handler returned from `useDetails` before executing your custom `onToggle` code.
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, open, setOpen} = useDetails({closeOnOutsideClick: true})
+    const {onToggle, ...detailsProps} = getDetailsProps()
+    const customToggle = e => {
+      onToggle(e)
+      window.alert('hi')
+    }
+    return (
+      <Details {...detailsProps} onToggle={customToggle}>
+        <Button as="summary">{open ? 'Open' : 'Closed'}</Button>
+        Hello World
+      </Details>
+    )
+  }}
+</State>
+```
+
+## Details props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+## `useDetails` hook configuration options
+
+| Name                | Type      | Default | Description                                                               |
+| :------------------ | :-------- | :-----: | :------------------------------------------------------------------------ |
+| defaultOpen         | Boolean   |         | Sets the initial open/closed state                                        |
+| closeOnOutsideClick | Boolean   |  false  | Sets whether or not element will close when the user clicks outside of it |
+| ref                 | React ref |         | optional ref to pass down to Details component                            |
+
+### Values returned by the `useDetails` hook
+
+| Name            | Type     | Description                                                                                                                                                                                                                              |
+| :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| open            | string   | Whether or not Details is currently open                                                                                                                                                                                                 |
+| setOpen         | function | Used to manually change the open state of the Details component                                                                                                                                                                          |
+| getDetailsProps | Object   | Contains an `onToggle` function, the `ref` to pass down to `Details` and the `open` attribute. In most cases, you won't need to interact with any of these values directly, but if you'd like to override any of these yourself you may. |

package/docs/content/Dialog.md

@@ -0,0 +1,106 @@
+---
+title: Dialog
+status: Deprecated
+---
+
+import State from '../components/State'
+
+The dialog component is used for all modals. It renders on top of the rest of the app with an overlay.
+
+You'll need to manage the `isOpen` state in a wrapper component of your own and pass in a function to be used to close the Dialog. For documentation purposes only we've created a mock `State` to handle this, but you should handle the state in the component you consume `Dialog` in or in a wrapper component.
+
+### Accessibility
+
+A few considerations must be made to ensure your use of the `Dialog` component is accessible:
+
+- Always be sure to provide either `aria-labelledby` or `aria-label` to your `Dialog` component. In most cases you should use `aria-labelledby` and pass it the `id` of your `Dialog.Header`. If there is no text in your header, or you chose not to use a header, you can use `aria-label` to describe the purpose of the `Dialog`.
+
+- Be sure to pass a ref to return the focus back to once the `Dialog` closes via the `returnFocusRef` prop. In most cases this should be the element that opened the Dialog. If you decide to manage focus within your application and want to bypass Primer React Components from doing so when the `Dialog` closes, you can omit the `returnFocusProp`.
+
+### Z-index
+
+If you're running into z-index issues or are rendering the component inside of an absolutely positioned element, you can wrap your `Dialog` in a [React Portal](https://reactjs.org/docs/portals.html).
+
+### Examples
+
+```jsx live
+<State default={false}>
+  {([isOpen, setIsOpen]) => {
+    const returnFocusRef = React.useRef(null)
+    return (
+      <>
+        <Button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
+          Open
+        </Button>
+        <Dialog
+          returnFocusRef={returnFocusRef}
+          isOpen={isOpen}
+          onDismiss={() => setIsOpen(false)}
+          aria-labelledby="header-id"
+        >
+          <Dialog.Header id="header-id">Title</Dialog.Header>
+          <Box p={3}>
+            <Text fontFamily="sans-serif">Some content</Text>
+          </Box>
+        </Dialog>
+      </>
+    )
+  }}
+</State>
+```
+
+You can also pass any non-text content into the header:
+
+```jsx live
+<State default={false}>
+  {([isOpen, setIsOpen]) => {
+    const returnFocusRef = React.useRef(null)
+    return (
+      <>
+        <Button ref={returnFocusRef} onClick={() => setIsOpen(true)}>
+          Open
+        </Button>
+        <Dialog
+          isOpen={isOpen}
+          returnFocusRef={returnFocusRef}
+          onDismiss={() => setIsOpen(false)}
+          aria-labelledby="label"
+        >
+          <Dialog.Header>
+            <ZapIcon />
+          </Dialog.Header>
+          <Box p={3}>
+            <Text id="label" fontFamily="sans-serif">
+              Are you sure you'd like to delete this issue?
+            </Text>
+            <Box display="flex" mt={3} justifyContent="flex-end">
+              <Button sx={{mr: 1}}>Cancel</Button>
+              <ButtonDanger>Delete</ButtonDanger>
+            </Box>
+          </Box>
+        </Dialog>
+      </>
+    )
+  }}
+</State>
+```
+
+## Component props
+
+### Dialog
+
+| Prop name       | Type              | Default | Description                                                                                                                                               |
+| :-------------- | :---------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| isOpen          | Boolean           |         | Set whether or not the dialog is shown                                                                                                                    |
+| onDismiss       | Function          |         | A user-provided function that should close the dialog                                                                                                     |
+| returnFocusRef  | React ref         |         | The element to restore focus back to after the `Dialog` is closed                                                                                         |
+| initialFocusRef | React ref         |         | Element inside of the `Dialog` you'd like to be focused when the Dialog is opened. If nothing is passed to `initialFocusRef` the close button is focused. |
+| aria-labelledby | string            |         | Pass an id to use for the aria-label. Use either a `aria-label` or an `aria-labelledby` but not both.                                                     |
+| aria-label      | string            |         | Pass a label to be used to describe the Dialog. Use either a `aria-label` or an `aria-labelledby` but not both.                                           |
+| sx              | SystemStyleObject | {}      | Style to be applied to the component                                                                                                                      |
+
+### Dialog.Header
+
+| Prop name | Type              | Default | Description                          |
+| :-------- | :---------------- | :------ | :----------------------------------- |
+| sx        | SystemStyleObject | {}      | Style to be applied to the component |

package/docs/content/Dialog2.mdx

@@ -0,0 +1,181 @@
+---
+title: Dialog v2
+status: Alpha
+---
+
+import State from '../components/State'
+
+The dialog component the Primer implementation of the ARIA design pattern [Dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal). A dialog is a type of overlay that can be used for confirming actions, asking for disambiguation, and presenting small forms. They generally allow the user to focus on a quick task without having to navigate to a different page.
+
+**Dialogs appear in the page after a direct user interaction**. Don't show dialogs on page load or as system alerts.
+
+**Dialogs appear centered in the page**, with a visible backdrop that dims the rest of the window for focus.
+
+**All dialogs should have a title and a close button**. Use the `title` prop to set the title. The close button is created automatically, but must be handled with an `onClose` prop.
+
+**Dialogs are modal**. Dialogs can be dismissed by clicking on the close button, or by interacting with another button in the overlay. To avoid losing information and missing important messages, clicking outside of the dialog will not close it.
+
+**(Coming soon) Make sure larger dialogs remain mobile-friendly**. Even large dialogs need to be responsive. A dialog's width and height will be readjusted depending on the screen size and should never exceed the available space. Use responsive solutions to adjust the UI so they behave well on smaller screens.
+
+**(Coming soon) Simple and small dialogs can remain as-is on mobile**. As more elements are added to it, mobile-specific style variations such as **Bottom sheet** and **Full-screen** should be considered.
+
+### State
+
+The dialog component is completely stateless. The parent component must conditionally render a dialog based on the necessary criteria. The parent component can be notified by a gesture to close the dialog (e.g. by clicking the "X" button or by pressing the Escape key) by passing in the `onClose` prop.
+
+### Accessibility
+
+The dialog component is fully accessible out-of-the-box. The dialog's title is used for `aria-labelledby`, and the dialog's description is used for `aria-describedby`. The `aria-modal="true"` attribute is used to inform screen readers that the rest of the content on the page is inert.
+
+#### Keyboard
+
+The default keyboard API for a dialog employs three mechanisms:
+
+1. The Escape key can be pressed to close the dialog.
+2. Focus is trapped within the top-most dialog. When a dialog is opened, the close button receives initial focus by default, or on a button defined with `autoFocus: true`.
+3. If there are buttons in the dialog footer, focus can be moved between them with left and right arrow keys or tab/shift+tab.
+4. When a dialog is closed, it can optionally handle returning focus to the element that was focused immediately before the dialog was opened. Otherwise, it is the consumer's responsibility to move focus to a suitable element.
+
+### Custom rendering
+
+**Note: using custom rendering allows breaking out of the defined design, UX, and accessibility patterns of the dialog. Use only as a last resort.**
+
+By default, the Dialog component implements the design and interactions defined by the Primer design system. If necessary, you can provide custom renderers for the header, body, or footer using the `renderHeader`, `renderBody`, and `renderFooter` props, respectively. The JSX produced by these render props will render full-bleed into their respective areas of the dialog. If you are using the custom renderers, you should use the provided sub-components `Dialog.Header`, `Dialog.Title`, `Dialog.Subtitle`, `Dialog.CloseButton`, `Dialog.Body`, `Dialog.Footer`, and `Dialog.Buttons` to the extent possible.
+
+### Example
+
+```jsx live
+<State default={false}>
+  {([isOpen, setIsOpen]) => {
+    const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])
+    const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])
+    return (
+      <>
+        <Button onClick={openDialog}>Open</Button>
+        {isOpen && (
+          <Dialog2
+            title="Dialog example"
+            subtitle={
+              <>
+                This is a <b>description</b> of the dialog.
+              </>
+            }
+            footerButtons={[{content: 'Ok', onClick: closeDialog}]}
+            onClose={closeDialog}
+          >
+            <Text fontFamily="sans-serif">Some content</Text>
+          </Dialog2>
+        )}
+      </>
+    )
+  }}
+</State>
+```
+
+## Component props
+
+### DialogProps
+
+| Prop name     | Type                                           | Default    | Description                                                                                                                                                                                                                                                             |
+| :------------ | :--------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| title         | `React.ReactNode`                              | `"Dialog"` | Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute.                                                                                                                                                                         |
+| subtitle      | `React.ReactNode`                              |            | Optional. Sets the subtitle of the dialog, which by default is also used as the `aria-describedby` attribute.                                                                                                                                                           |
+| renderHeader  | `(props: DialogHeaderProps) => JSX.Element`    |            | Optional. Custom render the dialog header. See "Custom rendering" above for more info.                                                                                                                                                                                  |
+| renderBody    | `(props: DialogProps) => JSX.Element`          |            | Optional. Custom render the dialog body. See "Custom rendering" above for more info.                                                                                                                                                                                    |
+| renderFooter  | `(props: DialogProps) => JSX.Element`          |            | Optional. Custom render the dialog footer. See "Custom rendering" above for more info.                                                                                                                                                                                  |
+| footerButtons | `DialogButtonProps[]`                          |            | Optional. Specify buttons that will be rendered in the footer of the dialog.                                                                                                                                                                                            |
+| onClose       | `(gesture: 'close-button' │ 'escape') => void` |            | Required. This method is invoked when a gesture to close the dialog is used (either an Escape key press or clicking the "X" in the top-right corner). The gesture argument indicates the gesture that was used to close the dialog (either 'close-button' or 'escape'). |
+| role          | `"dialog" │ "alertdialog"`                     | `"dialog"` | The ARIA role given to the dialog element. More info: [dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), [alertdialog](https://www.w3.org/TR/wai-aria-practices-1.1/#alertdialog)                                                                    |
+| width         | `"small" │ "medium" │ "large" │ "xlarge"`      | `"xlarge"` | The fixed width of the dialog.                                                                                                                                                                                                                                          |
+| height        | `"small" │ "large" │ "auto"`                   | `"auto"`   | The fixed height of the dialog, or, auto to adjust the height based on its contents.                                                                                                                                                                                    |
+| sx            | `SystemStyleObject`                            | {}         | Style to be applied to the component                                                                                                                                                                                                                                    |
+
+### DialogHeaderProps
+
+The `DialogHeaderProps` interface extends `DialogProps` and adds these additional properties:
+
+| Prop name           | Type     | Description                                                                                                                                                     |
+| :------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| dialogLabelId       | `string` | ID of the element that will be used as the `aria-labelledby` attribute on the dialog. This ID should be set to the element that renders the dialog's title.     |
+| dialogDescriptionId | `string` | ID of the element that will be used as the `aria-describedby` attribute on the dialog. This ID should be set to the element that renders the dialog's subtitle. |
+
+### DialogButtonProps
+
+The `DialogButtonProps` interface extends `ButtonProps` (see Button) and adds these additional properties:
+
+| Prop name  | Type                              | Default  | Description                                                                                                                                                        |
+| :--------- | :-------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| buttonType | `"normal" │ "primary" │ "danger"` | `Button` | The type of button to render                                                                                                                                       |
+| content    | `React.ReactNode`                 |          | Required. The button's inner content.                                                                                                                              |
+| autoFocus  | `boolean`                         | false    | If true, this button will be automatically focused when the dialog is first rendered. If `autoFocus` is true on subsequent button definitions, it will be ignored. |
+
+## ConfirmationDialog
+
+A `ConfirmationDialog` is a special kind of dialog with more rigid behavior. It is used to confirm a user action. `ConfirmationDialog`s always have exactly two buttons: one to cancel the action and one to confirm it. No custom rendering capabilities are provided for ConfirmationDialog.
+
+### useConfirm hook
+
+An alternate way to use `ConfirmationDialog` is with the `useConfirm()` hook. It takes no parameters and returns an `async` function, `confirm`. When `confirm` is called (see ConfirmOptions below for its argument), it shows the confirmation dialog. When the dialog is dismissed, a promise is resolved with `true` or `false` depending on whether or not the confirm button was used.
+
+### Example (with `useConfirm` hook)
+
+```javascript live noinline
+function ShorthandExample2() {
+  const confirm = useConfirm()
+  const buttonClick = React.useCallback(
+    async function (e) {
+      if (await confirm({title: 'Are you sure?', content: 'You must confirm this action to continue.'})) {
+        e.target.textContent = 'Confirmed!'
+      }
+    },
+    [confirm]
+  )
+  return (
+    <>
+      <Button onClick={buttonClick}>Confirmable action</Button>
+    </>
+  )
+}
+render(<ShorthandExample2 />)
+```
+
+### Example (using the full `ConfirmationDialog` component)
+
+```jsx live
+<State default={false}>
+  {([isOpen, setIsOpen]) => {
+    const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])
+    const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])
+    return (
+      <>
+        <Button onClick={openDialog}>Open</Button>
+        {isOpen && (
+          <ConfirmationDialog title="Confirm action?" onClose={closeDialog}>
+            Are you sure you want to confirm this action?
+          </ConfirmationDialog>
+        )}
+      </>
+    )
+  }}
+</State>
+```
+
+### ConfirmationDialogProps
+
+| Prop name            | Type                                                                  | Default    | Description                                                                                                                   |
+| :------------------- | :-------------------------------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------- |
+| title                | `React.ReactNode`                                                     |            | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute.                     |
+| onClose              | `(gesture: 'confirm' │ 'cancel' │ 'close-button' │ 'escape') => void` |            | Required. This callback is invoked when a gesture to close the dialog is performed. The first argument indicates the gesture. |
+| cancelButtonContent  | `React.ReactNode`                                                     | `"Cancel"` | The content to use for the cancel button.                                                                                     |
+| confirmButtonContent | `React.ReactNode`                                                     | `"OK"`     | The content to use for the confirm button.                                                                                    |
+| confirmButtonType    | `"normal" │ "primary" │ "danger"`                                     | `Button`   | The type of button to use for the confirm button.                                                                             |
+
+### ConfirmOptions
+
+| Prop name            | Type                              | Default    | Description                                                                                               |
+| :------------------- | :-------------------------------- | :--------- | :-------------------------------------------------------------------------------------------------------- |
+| title                | `React.ReactNode`                 |            | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |
+| content              | `React.ReactNode`                 |            | Required. Used as the body of the ConfirmationDialog that is displayed.                                   |
+| cancelButtonContent  | `React.ReactNode`                 | `"Cancel"` | The content to use for the cancel button.                                                                 |
+| confirmButtonContent | `React.ReactNode`                 | `"OK"`     | The content to use for the confirm button.                                                                |
+| confirmButtonType    | `"normal" │ "primary" │ "danger"` | `Button`   | The type of button to use for the confirm button.                                                         |

package/docs/content/Dropdown.md

@@ -0,0 +1,66 @@
+---
+title: Dropdown
+status: Deprecated
+---
+
+The Dropdown component is a lightweight context menu for housing navigation and actions.
+
+Use `Dropdown.Button` as the trigger for the dropdown, or use a custom `summary` element if you would like. **You must use a `summary` tag in order for the dropdown to behave properly!**. You should also add `aria-haspopup="true"` to custom dropdown triggers for accessibility purposes. You can use the `Dropdown.Caret` component to add a caret to a custom dropdown trigger.
+
+Dropdown.Menu wraps your menu content. Be sure to pass a `direction` prop to this component to position the menu in relation to the Dropdown.Button.
+
+## Default example
+
+```jsx live
+<Dropdown>
+  <Dropdown.Button>Dropdown</Dropdown.Button>
+  <Dropdown.Menu direction="sw">
+    <Dropdown.Item>Item 1</Dropdown.Item>
+    <Dropdown.Item>Item 2</Dropdown.Item>
+    <Dropdown.Item>Item 3</Dropdown.Item>
+  </Dropdown.Menu>
+</Dropdown>
+```
+
+## With custom button
+
+```jsx live
+<Dropdown>
+  <summary>
+    Dropdown
+    <Dropdown.Caret />
+  </summary>
+  <Dropdown.Menu direction="sw">
+    <Dropdown.Item>Item 1</Dropdown.Item>
+    <Dropdown.Item>Item 2</Dropdown.Item>
+    <Dropdown.Item>Item 3</Dropdown.Item>
+  </Dropdown.Menu>
+</Dropdown>
+```
+
+## Component props
+
+The Dropdown component is extended from the [`Details`](/Details) component and gets all props that the [`Details`](/Details) component gets.
+
+#### Dropdown.Menu
+
+| Name      | Type              | Default | Description                                                                           |
+| :-------- | :---------------- | :-----: | :------------------------------------------------------------------------------------ |
+| direction | String            |  'sw'   | Sets the direction of the dropdown menu. Pick from 'ne', 'e', 'se', 's', 'sw', or 'w' |
+| sx        | SystemStyleObject |   {}    | Style to be applied to the component                                                  |
+
+#### Dropdown.Button
+
+See https://primer.style/react/Buttons#component-props
+
+#### Dropdown.Caret
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+#### Dropdown.Item
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |

package/docs/content/DropdownMenu.mdx

@@ -0,0 +1,50 @@
+---
+title: DropdownMenu
+status: Alpha
+---
+
+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, key: 'cyan'},
+      {text: '🔴 Magenta', key: 'magenta'},
+      {text: '🟡 Yellow', key: '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.                                      |

package/docs/content/FilterList.md

@@ -0,0 +1,38 @@
+---
+title: FilterList
+status: Alpha
+---
+
+The FilterList component is a menu with filter options that filter the main content of the page.
+
+## Default example
+
+```jsx live
+<FilterList>
+  <FilterList.Item selected count={32} href="#foo">
+    First Filter
+  </FilterList.Item>
+  <FilterList.Item count={2} href="#bar">
+    Second Filter
+  </FilterList.Item>
+  <FilterList.Item href="#baz">Third Filter</FilterList.Item>
+</FilterList>
+```
+
+## Component props
+
+#### FilterList
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+#### FilterList.Item
+
+| Name     | Type              | Default | Description                                                      |
+| :------- | :---------------- | :-----: | :--------------------------------------------------------------- |
+| count    | Number            |         | Number to be displayed in the list item                          |
+| as       | String            |   `a`   | sets the HTML tag for the component                              |
+| selected | Boolean           |         | Used to set selected style                                       |
+| small    | Boolean           |  false  | Used to create a smaller version of the standard FilterList.Item |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component                             |

package/docs/content/FilteredSearch.md

@@ -0,0 +1,33 @@
+---
+title: FilteredSearch
+status: Alpha
+---
+
+The FilteredSearch component helps style a Dropdown and a TextInput side-by-side.
+
+**Note:** You _must_ use a `TextInput` and `Dropdown` (or native `<details>` and `<summary>`) in order for this component to work properly.
+
+## Default example
+
+```jsx live
+<FilteredSearch>
+  <Dropdown>
+    <Dropdown.Button>Filter</Dropdown.Button>
+    <Dropdown.Menu direction="sw">
+      <Dropdown.Item>Item 1</Dropdown.Item>
+      <Dropdown.Item>Item 2</Dropdown.Item>
+      <Dropdown.Item>Item 3</Dropdown.Item>
+    </Dropdown.Menu>
+  </Dropdown>
+  <TextInput icon={SearchIcon} />
+</FilteredSearch>
+```
+
+## Component props
+
+#### FilteredSearch.Children
+
+| Name     | Type              | Default | Description                                                                                              |
+| :------- | :---------------- | :-----: | :------------------------------------------------------------------------------------------------------- |
+| children |                   |         | FilteredSearch is expected to contain a [`Dropdown`](/Dropdown) followed by a [`TextInput`](/TextInput). |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component                                                                     |

package/docs/content/Flash.md

@@ -0,0 +1,36 @@
+---
+title: Flash
+status: Alpha
+---
+
+The Flash component informs users of successful or pending actions.
+
+## Default example
+
+```jsx live
+<>
+  <Flash>Default Flash</Flash>
+  <Flash variant="success">Success Flash</Flash>
+  <Flash variant="warning">Warning Flash</Flash>
+  <Flash variant="danger">Danger Flash</Flash>
+</>
+```
+
+## With an icon
+
+Flash components with icons inside of them will automatically set the correct color for the icon depending on the type of Flash, as well as applying the correct right margin.
+
+```jsx live
+<Flash variant="success">
+  <StyledOcticon icon={CheckIcon} />
+  Success!
+</Flash>
+```
+
+## Component props
+
+| Name    | Type              | Default | Description                                                                                                              |
+| :------ | :---------------- | :-----: | :----------------------------------------------------------------------------------------------------------------------- |
+| full    | Boolean           |         | Creates a full width Flash component                                                                                     |
+| sx      | SystemStyleObject |   {}    | Style to be applied to the component                                                                                     |
+| variant | String            | default | Can be one of `default`, `success`, `warning`, or `danger` - sets the background color and border of the Flash component |