Update DropdownMenu readme #13410
Update DropdownMenu readme #13410
Conversation
Adding documentation to describe the use and functionality of the DropdownMenu component. Thanks @sarahmonster and @jasmussen for drafting this.
|
|
||
| ## Usage | ||
|  |
There was a problem hiding this comment.
I see that is a common way of handling images for docs. I'm wondering if it wouldn't be better to keep them on GitHub instead. This would make it open for everyone. At the moment there is a very small group of maintainer who can override the existing files or add new ones.
There was a problem hiding this comment.
That would definitely be easier to update — the reason we've been hosting them over on wp.org is that images uploaded to GitHub are blocked from appearing on the mirror over at https://wordpress.org/gutenberg/handbook/ 😞
There was a problem hiding this comment.
Yeah, we've had a couple conversations about this 😞 I think there's also a worry that the images will bloat the repo. Would love to find a more sustainable solution!
There was a problem hiding this comment.
Right, it makes a lot of sense. I think there still are some images referenced. I remember seeing @nosolosw using GitHub hosted image. I will have to double check whether it works.
There was a problem hiding this comment.
It looks like it is possible. See this page:
https://wordpress.org/gutenberg/handbook/designers-developers/developers/tutorials/plugin-sidebar-0/plugin-sidebar-1-up-and-running/
However I agree that it might negatively impact the download size of repository. It is also not clear how URL should look like. I see something like this in the source:
https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/assets/sidebar-up-and-running.png
There was a problem hiding this comment.
Yeah, I've asked about that a few times. I think the tutorials I wrote all use the Github raw CDN because that was what I had access to and what other doc folks were doing. It's a bit tricky because you have to use the image URL for when the image is deployed to master (so you don't see it during reviews). 🤷♂️
Adding documentation to describe the use and functionality of the DropdownMenu component. Thanks @sarahmonster and @jasmussen for drafting this.
Adding documentation to describe the use and functionality of the DropdownMenu component. Thanks @sarahmonster and @jasmussen for drafting this.
|
|
||
| Dropdown Menu is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button. | ||
| The DropdownMenu displays a list of actions (each contained in a MenuItem, MenuItemsChoice, or MenuGroup) in a compact way. It appears in a Popover after the user has interacted with an element (a button or icon) or when they perform a specific action. |
There was a problem hiding this comment.
While it probably should use MenuItem, MenuItemsChoice, and MenuGroup components, it doesn't currently, nor did at the time of this pull request. This confused me for a moment in my debugging of #14754 (comment) .
Right now it's only rendering its own IconButton for each control.
I'll see if in the course of resolving #14754 that it could be updated to at least render MenuItem. I'm not really sure what combination of controls prop for this component would be expected to result in MenuGroup or MenuItemsChoice being rendered, however.
The way it's implemented currently, it does support grouping of controls, but notably lacks any way of expressing a label to use for a MenuGroup, so I don't know that it would be an appropriate use of that component.
<DropdownMenu
controls={ [
[
{
title: 'Group 1, Control 1',
icon: 'arrow-up-alt',
},
{
title: 'Group 1, Control 2',
icon: 'arrow-up-alt',
},
],
[
{
title: 'Group 2, Control 1',
icon: 'arrow-up-alt',
},
{
title: 'Group 2, Control 2',
icon: 'arrow-up-alt',
},
]
] }
/>From these other related component documentations, I also note the phrasing "are intended to be used in a DropDownMenu", which may be misleading in that they're used by DropdownMenu, but the developer doesn't really have the choice of providing DropdownMenu with any of these components.
Updating documentation to describe the use and functionality of the DropdownMenu component.
Thanks to @sarahmonster, @jasmussen, and @kjellr for helping draft this.