Drafts: Composable DropdownMenu v2 #1735
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| '@primer/react': patch | ||
| --- | ||
|
|
||
| Add composable `DropdownMenu` to `@primer/components/drafts` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,379 @@ | ||||||
| --- | ||||||
| component_id: dropdown_menu | ||||||
| title: DropdownMenu v2 | ||||||
| status: Alpha | ||||||
| source: https://github.com/primer/react/tree/main/src/DropdownMenu2.tsx | ||||||
| storybook: '/react/storybook?path=/story/composite-components-dropdownmenu2' | ||||||
| description: Use DropdownMenu to select a single option from a list of menu options. | ||||||
| --- | ||||||
|
|
||||||
| import {Box, Avatar} from '@primer/react' | ||||||
| import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| import {Props} from '../../src/props' | ||||||
| import State from '../../components/State' | ||||||
| import {CalendarIcon, IterationsIcon, NumberIcon, SingleSelectIcon, TypographyIcon} from '@primer/octicons-react' | ||||||
|
|
||||||
| <br /> | ||||||
|
|
||||||
| <State default={1}> | ||||||
|
There was a problem hiding this comment. This example appears at the top of docs, but with more recent updates we've been moving them under examples heading and keeping import statements at the top. Can we do the same here for consistency? There was a problem hiding this comment. I want to vote for keeping it 🤔 I've done this for ActionList and ActionMenu as well to quickly see what this component is. Meanwhile, the examples slowly build up starting from an easy example to more complex ones. There was a problem hiding this comment. Looks quite nice actually, almost like a preview / hero. 👍 .. we'll need to comm this to others so we can consider doing same elsewhere. |
||||||
| {([selectedIndex, setSelectedIndex]) => { | ||||||
| const fieldTypes = [ | ||||||
| {icon: TypographyIcon, name: 'Text'}, | ||||||
| {icon: NumberIcon, name: 'Number'}, | ||||||
| {icon: CalendarIcon, name: 'Date'}, | ||||||
| {icon: SingleSelectIcon, name: 'Single select'}, | ||||||
| {icon: IterationsIcon, name: 'Iteration'} | ||||||
| ] | ||||||
| const selectedType = fieldTypes[selectedIndex] | ||||||
| return ( | ||||||
| <Box sx={{border: '1px solid', borderColor: 'border.default', borderRadius: 2, padding: 6}}> | ||||||
| <DropdownMenu> | ||||||
| <DropdownMenu.Button aria-label="Select field type" leadingIcon={selectedType.icon}> | ||||||
| {selectedType.name} | ||||||
| </DropdownMenu.Button> | ||||||
| <DropdownMenu.Overlay width="medium"> | ||||||
| <ActionList> | ||||||
| {fieldTypes.map(({icon: Icon, name}, index) => ( | ||||||
| <ActionList.Item | ||||||
| key={index} | ||||||
| selected={index === selectedIndex} | ||||||
| onSelect={() => setSelectedIndex(index)} | ||||||
| > | ||||||
| <Icon /> {name} | ||||||
| </ActionList.Item> | ||||||
| ))} | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| </Box> | ||||||
| ) | ||||||
| }} | ||||||
| </State> | ||||||
|
|
||||||
| <br /> | ||||||
|
|
||||||
| ```js | ||||||
| import {DropdownMenu} from '@primer/react/drafts' | ||||||
|
There was a problem hiding this comment. I like that you're giving readers an easy thing to copy and paste to import the component. @colebemis - maybe we should consider adding this as we do #1701. What do you think? There was a problem hiding this comment. Can we also hoist the import to the top of the page? There was a problem hiding this comment. Aw this is short lived, would need to remove this after #1785 is merged |
||||||
| ``` | ||||||
|
|
||||||
| <br /> | ||||||
|
|
||||||
| ## Examples | ||||||
|
|
||||||
| ### Minimal example | ||||||
|
|
||||||
| `DropdownMenu` ships with `DropdownMenu.Button` which is an accessible trigger for the overlay. It's recommended to compose `ActionList` with `DropdownMenu.Overlay` | ||||||
|
|
||||||
| | ||||||
|
|
||||||
| ```javascript live noinline | ||||||
| // import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| const {DropdownMenu, ActionList} = drafts // ignore docs silliness; import like that ↑ | ||||||
|
|
||||||
| const fieldTypes = [ | ||||||
| {icon: TypographyIcon, name: 'Text'}, | ||||||
| {icon: NumberIcon, name: 'Number'}, | ||||||
| {icon: CalendarIcon, name: 'Date'}, | ||||||
| {icon: SingleSelectIcon, name: 'Single select'}, | ||||||
| {icon: IterationsIcon, name: 'Iteration'} | ||||||
| ] | ||||||
|
|
||||||
| const Example = () => { | ||||||
| const [selectedIndex, setSelectedIndex] = React.useState(1) | ||||||
| const selectedType = fieldTypes[selectedIndex] | ||||||
|
|
||||||
| return ( | ||||||
| <DropdownMenu> | ||||||
| <DropdownMenu.Button aria-label="Select field type" leadingIcon={selectedType.icon}> | ||||||
| {selectedType.name} | ||||||
| </DropdownMenu.Button> | ||||||
| <DropdownMenu.Overlay width="medium"> | ||||||
| <ActionList> | ||||||
| {fieldTypes.map((type, index) => ( | ||||||
siddharthkp marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| <ActionList.Item key={index} selected={index === selectedIndex} onSelect={() => setSelectedIndex(index)}> | ||||||
| <type.icon /> {type.name} | ||||||
| </ActionList.Item> | ||||||
| ))} | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| ) | ||||||
| } | ||||||
|
|
||||||
| render(<Example />) | ||||||
| ``` | ||||||
|
|
||||||
| ### Customise Button | ||||||
|
|
||||||
| `Dropdown.Button` uses `Button v2` so you can pass props like `variant` and `leadingIcon` that `Button v2` accepts. | ||||||
|
|
||||||
| ```javascript live noinline | ||||||
| // import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| const {DropdownMenu, ActionList} = drafts // ignore docs silliness; import like that ↑ | ||||||
|
|
||||||
| const Example = () => { | ||||||
| const [duration, setDuration] = React.useState(1) | ||||||
|
|
||||||
| return ( | ||||||
| <DropdownMenu> | ||||||
| <DropdownMenu.Button variant="invisible" aria-label="Select iteration duration"> | ||||||
| {duration} {duration > 1 ? 'weeks' : 'week'} | ||||||
| </DropdownMenu.Button> | ||||||
| <DropdownMenu.Overlay width="medium"> | ||||||
| <ActionList> | ||||||
| {[1, 2, 3, 4, 5, 6].map(weeks => ( | ||||||
| <ActionList.Item key={weeks} selected={duration === weeks} onSelect={() => setDuration(weeks)}> | ||||||
| {weeks} {weeks > 1 ? 'weeks' : 'week'} | ||||||
| </ActionList.Item> | ||||||
| ))} | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| ) | ||||||
| } | ||||||
|
|
||||||
| render(<Example />) | ||||||
| ``` | ||||||
|
|
||||||
| ### With External Anchor | ||||||
|
|
||||||
| To create an anchor outside of the menu, you need to switch to controlled mode for the menu and pass `open` and `onOpenChange` along with an `anchorRef` to `DropdownMenu`: | ||||||
|
|
||||||
| ```javascript live noinline | ||||||
| // import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| const {DropdownMenu, ActionList} = drafts // ignore docs silliness; import like that ↑ | ||||||
|
|
||||||
| const Example = () => { | ||||||
| const [open, setOpen] = React.useState(false) | ||||||
| const anchorRef = React.createRef() | ||||||
|
|
||||||
| return ( | ||||||
| <> | ||||||
| <Button ref={anchorRef} onClick={() => setOpen(!open)}> | ||||||
| {open ? 'Close Menu' : 'Open Menu'} | ||||||
| </Button> | ||||||
|
|
||||||
| <DropdownMenu open={open} onOpenChange={setOpen} anchorRef={anchorRef}> | ||||||
| <DropdownMenu.Overlay> | ||||||
| <ActionList> | ||||||
| <ActionList.Item selected={true}>Text</ActionList.Item> | ||||||
| <ActionList.Item>Number</ActionList.Item> | ||||||
| <ActionList.Item>Date</ActionList.Item> | ||||||
| <ActionList.Item>Iteration</ActionList.Item> | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| </> | ||||||
| ) | ||||||
| } | ||||||
|
|
||||||
| render(<Example />) | ||||||
| ``` | ||||||
|
|
||||||
| ### With Overlay Props | ||||||
|
|
||||||
| ```javascript live noinline | ||||||
| // import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| const {DropdownMenu, ActionList} = drafts // ignore docs silliness; import like that ↑ | ||||||
|
|
||||||
| const fieldTypes = [ | ||||||
| {icon: TypographyIcon, name: 'Text'}, | ||||||
| {icon: NumberIcon, name: 'Number'}, | ||||||
| {icon: CalendarIcon, name: 'Date'}, | ||||||
| {icon: SingleSelectIcon, name: 'Single select'}, | ||||||
| {icon: IterationsIcon, name: 'Iteration'} | ||||||
| ] | ||||||
|
|
||||||
| const Example = () => { | ||||||
| const handleEscape = () => alert('you hit escape!') | ||||||
|
|
||||||
| const [selectedIndex, setSelectedIndex] = React.useState(1) | ||||||
| const selectedType = fieldTypes[selectedIndex] | ||||||
|
|
||||||
| return ( | ||||||
| <DropdownMenu> | ||||||
| <DropdownMenu.Button aria-label="Select field type" leadingIcon={selectedType.icon}> | ||||||
| {selectedType.name} | ||||||
| </DropdownMenu.Button> | ||||||
| <DropdownMenu.Overlay width="medium" onEscape={handleEscape}> | ||||||
| <ActionList> | ||||||
| {fieldTypes.map((type, index) => ( | ||||||
| <ActionList.Item key={index} selected={index === selectedIndex} onSelect={() => setSelectedIndex(index)}> | ||||||
| <type.icon /> {type.name} | ||||||
| </ActionList.Item> | ||||||
| ))} | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| ) | ||||||
| } | ||||||
|
|
||||||
| render(<Example />) | ||||||
| ``` | ||||||
|
|
||||||
| ### With a custom anchor | ||||||
|
There was a problem hiding this comment. Could anchor in this title be confusing for readers as it's used in a different context further up?
Suggested change
There was a problem hiding this comment. We call this |
||||||
|
|
||||||
| You can choose to have a different _anchor_ for the Menu dependending on the application's context. | ||||||
|
|
||||||
| | ||||||
|
|
||||||
| ```javascript live noinline | ||||||
| // import {DropdownMenu, ActionList} from '@primer/react/drafts' | ||||||
| const {DropdownMenu, ActionList} = drafts // ignore docs silliness; import like that ↑ | ||||||
|
|
||||||
| render( | ||||||
| <DropdownMenu> | ||||||
| <DropdownMenu.Anchor> | ||||||
| <button>Select a field type</button> | ||||||
| </DropdownMenu.Anchor> | ||||||
|
|
||||||
| <DropdownMenu.Overlay> | ||||||
| <ActionList> | ||||||
| <ActionList.Item selected={true}>Text</ActionList.Item> | ||||||
| <ActionList.Item>Number</ActionList.Item> | ||||||
| <ActionList.Item>Date</ActionList.Item> | ||||||
| <ActionList.Item>Iteration</ActionList.Item> | ||||||
| </ActionList> | ||||||
| </DropdownMenu.Overlay> | ||||||
| </DropdownMenu> | ||||||
| ) | ||||||
| ``` | ||||||
|
|
||||||
| <Note variant="warning"> | ||||||
|
|
||||||
| Use `DropdownMenu` to select an option from a small list. If you’re looking for filters or multiple selection, use [SelectPanel](/SelectPanel) instead. | ||||||
|
There was a problem hiding this comment. This feels quite important, shall we hoist it near the top of page so it has better visibility? We've done this for other components before. There was a problem hiding this comment. This came up before with ActionMenu. What we decided was that interface guidelines is the first place where you learn which component to use, and this is the second note near |
||||||
|
|
||||||
| </Note> | ||||||
|
|
||||||
| ## Props | ||||||
|
|
||||||
| ### DropdownMenu | ||||||
|
|
||||||
| <PropsTable> | ||||||
| <PropsTableRow | ||||||
| required | ||||||
| name="children" | ||||||
| type="React.ReactElement[]" | ||||||
| description={ | ||||||
| <> | ||||||
| Recommended: <InlineCode>DropdownMenu.Button</InlineCode> or <InlineCode>DropdownMenu.Anchor</InlineCode> with{' '} | ||||||
| <InlineCode>DropdownMenu.Overlay</InlineCode> | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| <PropsTableRow | ||||||
| name="open" | ||||||
| type="boolean" | ||||||
| description={ | ||||||
| <> | ||||||
| If defined, will control the open/closed state of the overlay. Must be used in conjuction with{' '} | ||||||
| <InlineCode>onOpenChange</InlineCode> | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| <PropsTableRow | ||||||
| name="onOpenChange" | ||||||
| type="(open: boolean) => void" | ||||||
| description={ | ||||||
| <> | ||||||
| If defined, will control the open/closed state of the overlay. Must be used in conjuction with{' '} | ||||||
| <InlineCode>open</InlineCode> | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| <PropsTableRow | ||||||
| name="anchorRef" | ||||||
| type="React.RefObject<HTMLElement>" | ||||||
| description="Useful for defining an external anchor" | ||||||
| /> | ||||||
| </PropsTable> | ||||||
|
|
||||||
| ### DropdownMenu.Button | ||||||
|
|
||||||
| <PropsTable> | ||||||
| <PropsTableRow | ||||||
| name="ButtonProps" | ||||||
| type={ | ||||||
| <> | ||||||
| <Link href="/drafts/Button2#api-reference">ButtonProps</Link> | ||||||
| </> | ||||||
| } | ||||||
| description={ | ||||||
| <> | ||||||
| You can pass all of the props that you would pass to a{' '} | ||||||
| <Link href="/drafts/Button2#api-reference"> | ||||||
| <InlineCode>Button</InlineCode> | ||||||
| </Link>{' '} | ||||||
| component like <InlineCode>variant</InlineCode>, <InlineCode>leadingIcon</InlineCode>,{' '} | ||||||
| <InlineCode>sx</InlineCode>, etc. | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| </PropsTable> | ||||||
|
|
||||||
| ### DropdownMenu.Anchor | ||||||
|
|
||||||
| <PropsTable> | ||||||
| <PropsTableRow required name="children" type="React.ReactElement" description="Accepts a single child" /> | ||||||
| </PropsTable> | ||||||
|
|
||||||
| ### DropdownMenu.Overlay | ||||||
|
|
||||||
| <PropsTable> | ||||||
| <PropsTableRow | ||||||
| required | ||||||
| name="children" | ||||||
| type="React.ReactElement[]" | ||||||
| description={ | ||||||
| <> | ||||||
| Recommended:{' '} | ||||||
| <Link href="/drafts/ActionList2"> | ||||||
| <InlineCode>ActionList</InlineCode> | ||||||
| </Link> | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| <PropsTableRow | ||||||
| name="OverlayProps" | ||||||
| type="OverlayProps" | ||||||
| description={ | ||||||
| <> | ||||||
| Props to be spread on the internal{' '} | ||||||
| <Link href="/AnchoredOverlay"> | ||||||
| <InlineCode>AnchoredOverlay</InlineCode> | ||||||
| </Link> | ||||||
| </> | ||||||
| } | ||||||
| /> | ||||||
| </PropsTable> | ||||||
|
|
||||||
| ## Status | ||||||
|
|
||||||
| <ComponentChecklist | ||||||
| items={{ | ||||||
| propsDocumented: true, | ||||||
| noUnnecessaryDeps: true, | ||||||
| adaptsToThemes: true, | ||||||
| adaptsToScreenSizes: true, | ||||||
| fullTestCoverage: true, | ||||||
| usedInProduction: false, | ||||||
| usageExamplesDocumented: true, | ||||||
| hasStorybookStories: true, | ||||||
| designReviewed: false, | ||||||
| a11yReviewed: false, | ||||||
| stableApi: false, | ||||||
| addressedApiFeedback: false, | ||||||
| hasDesignGuidelines: true, | ||||||
| hasFigmaComponent: true | ||||||
| }} | ||||||
| /> | ||||||
|
|
||||||
| ## Further reading | ||||||
|
|
||||||
| [Interface guidelines: Action List + Menu](https://primer.style/design/components/action-list) | ||||||
|
|
||||||
| ## Related components | ||||||
|
|
||||||
| - [ActionList](/drafts/ActionList2) | ||||||
| - [ActionMenu](/ActionMenu2) | ||||||
| - [SelectPanel](/SelectPanel) | ||||||
siddharthkp marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.