Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update DropdownMenu readme #13410

Merged
merged 5 commits into from
Jan 22, 2019
Merged

Update DropdownMenu readme #13410

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
90b6cc1
Update DropdownMenu readme
melchoyce Jan 17, 2019
8fa1a3b
Update "don't" image to use correct format
melchoyce Jan 21, 2019
700a6c0
Update all example images
melchoyce Jan 21, 2019
33803f9
Clarify "don't" copy.
melchoyce Jan 21, 2019
a4378a5
Clarify behavior content.
melchoyce Jan 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 59 additions & 7 deletions packages/components/src/dropdown-menu/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,60 @@
# Dropdown Menu
# DropdownMenu

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

gutenberg/packages/components/src/dropdown-menu/index.js

Line 74 in 45da3cf

<IconButton

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.


## Usage
![An expanded DropdownMenu, containing a list of MenuItems.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuExample.png)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/ 😞

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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). 🤷‍♂️


## Table of contents

1. [Design guidelines](#design-guidelines)
2. [Development guidelines](#development-guidelines)

## Anatomy

![Anatomy of a DropdownMenu.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuAnatomy.png)

1. Popover: a container component in which the DropdownMenu is wrapped.
2. Parent button: the icon or button that is used to toggle the display of the Popover containing the DropdownMenu.
3. MenuItem: the list items within the DropdownMenu.

## Design guidelines

### Usage

#### When to use a DropdownMenu

Use a DropdownMenu when you want users to:

- Choose an action or change a setting from a list, AND
- Only see the available choices contextually.

If you need to display all the available options at all times, consider using a Toolbar instead.

![Use a DropdownMenu to display a list of actions after the user interacts with an icon.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuDo.png)

**Do**
Use a DropdownMenu to display a list of actions after the user interacts with an icon.

![Don’t use a DropdownMenu for important actions that should always be visible. Use a Toolbar instead.](https://wordpress.org/gutenberg/files/2019/01/DropdownMenuDont.png)

**Don’t**
Don’t use a DropdownMenu for frequently used actions. Use a Toolbar instead.

#### Behavior

The parent button should (have|not have) a triangular icon to the right of the icon or text to indicate that interacting with it will show a DropdownMenu.
melchoyce marked this conversation as resolved.
Show resolved Hide resolved

The parent button should retain the same visual styling regardless of whether the DropdownMenu is displayed or not.

#### Placement

The DropdownMenu should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full DropdownMenu, it can be displayed instead above the parent button.

## Development guidelines

DropdownMenu 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.

### Usage

Render a Dropdown Menu with a set of controls:

Expand Down Expand Up @@ -39,11 +91,11 @@ const MyDropdownMenu = () => (
);
```

## Props
### Props

The component accepts the following props:

### icon
#### icon

The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug to be shown in the collapsed menu button.

Expand All @@ -53,14 +105,14 @@ The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug to

See also: [https://developer.wordpress.org/resource/dashicons/](https://developer.wordpress.org/resource/dashicons/)

### label
#### label

A human-readable label to present as accessibility text on the focused collapsed menu button.

- Type: `String`
- Required: Yes

### controls
#### controls

An array of objects describing the options to be shown in the expanded menu.

Expand Down