Introduce Menu component (aka DropdownMenu v2)

[ciampo]

Related to #49271

We would like to build a mode modular, accessible, and feature-rich (eg. with support for sub-menus) version of the DropdownMenu component.

Given how tricky it can be to implement this feature in an accessible and usable way, we're going to leverage ariakit and its Menu component. We initially tested Radix UI but found some blockers.

Choosing an API approach

After some initial discussion, we've landed on an approach:

• Keep ariakit as an internal implementation detail as much as possible
• Expose as few props as needed
• Expose low-level, granular components, to allow for greater flexibility
• Consider adding as many guidelines, examples, and any other tools to help consumers use the component correctly.

---

Next steps:

• Create a radix-ui based component (Add new experimental version of DropdownMenu #49473)
  • Add Radix UI as a dependency
  • Experiment with the component and land on an API approach: should we expose low-level, granular components, or high-level components? Should we limit the number of props that we expose from Radix? Should we avoid referencing Radix at all ?
  • Wrap an initial version of the component internal to the components package, and available to other packages in Gutenberg via lock/unlock
• Test and tweak the radix-ui version of the component
  • DropdownMenu: Design feedback #50910
  • DropdownMenu v2: change default placement to match the legacy DropdownMenu component #51133
  • DropdownMenu v2: Render in the default Popover.Slot #51046
  • DropdownMenu v2: tweak styles, add toolbar-specific styles #51097
  • Refine the approach to icon alignment between different menu item types (see comment)
    • Should it be at the group level or at the "content" level ?
  • Accessibility checks in all major Mac OS browsers (Introduce Menu component (aka DropdownMenu v2) #50459 (comment))
• Create an alternative version using ariakit, borrowing as much as possible from the API that we landed on while working on the Radix version (Add new ariakit-based DropdownMenu component #54939)
• Test and tweak the new ariakit-based component
  • DropdownMenu v2: Design tweaks #55933
  • DropdownMenu v2: align component to shared styles and theme variables #50971
  • DropdownMenuV2: inherit placement for nested submenus #56213
  • DropdownMenuV2Ariakit: prevent prefix collapsing if all radios or checkboxes are unselected #56720
  • DropdownMenu V2: add fallback styles for when subgrid is not supported #57327
  • DropdownMenuV2: add GroupLabel subcomponent #64854
  • DropdownMenuV2: break menu item help text on multiple lines for better truncation #63916
  • DropdownMenuV2: use overloaded naming conventions #64654
  • Refactor experimental dropdown menu usages to latest version #55625
  • Delete experimental radix-ui based DropdownMenu component #55626
  • DropdownMenuV2: update animation #64868
  • API tweak (@wordpress/components: high-level API strategy for compound components #63704)
    • Split to more granular sub-components
    • gutter+shift vs offset
    • Collapse empty groups?
  • Menu: use ariakit types #68206
  • Menu: auto-generate README #68249
  • Evaluate portal behaviour (@wordpress/components: portal behavior of popover-based components #63697):
    - does it behave differently (ie. renders inline) when non-modal? Does it make a difference if the popover slot is defined?
    - Should we expose the portal element (similar to inline prop on Popover )?
    - Should we expose the portalElement prop instead of slotName ?
  • useContext needs rethinking
  • Menu: Add "destructive" state #61079
  • Fix Menu component ARIA pattern #67078
  • Evaluate modality (see @wordpress/components: modality of popover-based components #63674)
  • Test: menu, opening a modal, with a menu inside opening a second modal
  • Add more unit tests
  • Known issues:
    • Ariakit.MenuItemRadio not supporting defaultChecked ariakit/ariakit#2914
    • Ariakit.MenuItemCheckbox not supporting defaultChecked ariakit/ariakit#2913
    • MenuItemRadio: support accessing the radio's value ariakit/ariakit#2915
    • MenuItemCheck doesn't populate the values in the menu store on first render ariakit/ariakit#2916
    • DropdownMenu V2: Focus goes out when pressing Tab key #58040
    • DropdownMenuV2: remove flashing styles when moving focus with keyboard #64873
  • DropdownMenuV2: invert animation direction #63443
• Use in the editor:
  • Try to fix Experimental Page List: Ensure sorting by doesn't cover up other drop downs #55169
  • Template actions with DropDownMenuV2 #51043
  • Block Editor Settings: use v2 DropdownMenu #51400
  • Data view: Search & Filtering #55100 (comment)
  • Migrate DropdownMenu instances to Menu #61094
• Publish the component:
  • Understand if there's any chance of replacing the legacy DropdownMenu component via a back-compat layer
  • Apart from DropdownMenu, add back-compat to MenuGroup and MenuItem to render correctly if they detect that they are being rendered as part of DropdownMenuv2 (this could be done via context, having both v1 and v2 dropdowns setting that variable for the menu item and menu group to read)
  • In case back-compat layer is not an option, come up with a well-defined strategy for publishing a new version of the DropdownMenu component (example: "v2" strategy as done for blocks)
  • Come up with a well-defined strategy for namespacing and potentially adding, in the future,
• DropdownMenu: Render in a sheet/drawer on small viewports #57228

This may close #18537

[alexstine]

Please let me know when ready for accessibility testing. Added a couple required checks above to ensure it is not missed before publishing the package.

[ciampo]

Hey all, an experimental version of the new DropdownMenu component has been added to the repository:

• Storybook example
• Code

These are still very early days, but it is a great time to gather some early feedback on all aspects:

• accessibility (cc @alexstine @andrewhayward)
• design (cc @SaxonF @jameskoster @jasmussen )
• overall code architecture
• overall component, including supported and missing features (cc @richtabor @mtias )

In order to keep this issue as a tracking issue, it would be great if y'all could open separate issues — we can link them all in this issue's description.

In the upcoming days, I'm going to start testing the new component in the editor, in order to spot any issues and missing features, and I'll start work on adding support for using the component with SlotFill.

Thanks!

[jameskoster]

That's looking great already ✨

Seems like the visual design is based on some rough explorations I worked on in Figma. Here's the link to that in case anyone else would like to riff on the appearance.

[alexstine]

@ciampo This seems to be testing well on Windows. Would be nice to get a Mac review. CC: @afercia .

[SaxonF]

Nice work!

(Edit by @ciampo : moved the feedback to a separate issue: #50910)

[andrewhayward]

Was playing around with the Storybook example, and I noticed that pressing escape collapses the entire menu. This is fine at the top level, but submenus should collapse up to their parent. I checked the underlying Radix UI component, and it behaves the same, so I'm guessing it's a problem there rather than with this. Will need to raise a ticket on that project to resolve.

[andrewhayward]

Will need to raise a ticket on that project to resolve.

Looks like a ticket was already raised, and closed as "won't fix". Not a blocker, by any stretch, but probably worth making note of.

[alexstine]

I would prefer the escape to take me out of submenus before closing the entire menu especially if you were multiple levels deep. The argument about Mac OS in that issue is invalid for Windows. Opening a Windows context menu, then submenu, and pressing escape will focus the submenu trigger.

I am not sure it should be a blocker for the first implementation but I am not a fan of how the contributors dismissed that issue. This could come back to haunt us later. It's the risk you take with 3rd-party.

[ciampo]

It's the risk you take with 3rd-party.

Yup, and it is a calculated one. Using a well-known and actively maintained third-party library allowed us to iterate on this otherwise fairly complex component quite quickly and with very good results. We can definitely expect situations like this one, but the hope is that there won't be many and that the trade-off will be advantageous for the project.

[andrewhayward]

I think we've got a few options at this point:

1. Leave things as they are, and accept the situation for what it is.
2. Work with the upstream project, if not to change the current behaviour (evidently that's unlikely to happen), then at least to contribute something that would give us more flexibility to do things to our preference.
3. Fork the upstream project and make adjustments.
4. Make adjustments within our component. Given that we're not exposing any upstream primitives, we can override specific event handlers without causing complexity for component consumers.

I'm not a huge fan of 1, but it might be sufficient for the immediate term to get something working. 2 runs the risk of being rejected, at which point we'd be back to this conversation. 3 is (from my perspective anyway) a total non-starter. And 4 is arguably something of a hack, but could probably be done relatively cleanly, at least from a code perspective.

[mirka]

Leave things as they are, and accept the situation for what it is

To be honest, I was kind of persuaded by all the reasoning that was given in closing the upstream issue as wontfix. The left arrow key will always return you to the closest parent, whereas Escape is the only key that will escape you out completely no matter what. (I'm imagining a situation where the focus is in a submenu nested two or more levels deep.)

So given that there is a functional advantage, plus the ARIA APG being ambiguous, plus two major reference implementations (Windows and macOS) diverging on this, I don't see the current Escape behavior as a clearly bad thing we should fix.

[alexstine]

Yes, I think it is likely fine the way it is and should not be blocked. I just wanted to highlight the fact that if we do go down the road of implementing more 3rd-party components, these types of issues might not be so clear-cut. There is also a reason why people with disabilities continue to keep Windows at the top of the operating system list. Anyone here who has tried to use Mac Voiceover I am sure understands why.

Anyway, super excited for this to continue. This will be a nice submenu implementation that very closely mocks Google Drive and now Gmail context menus.

Thanks for the work here.

[andrewhayward]

Ultimately the upstream dependency isn't wrong, as there's no normative right in this context, and their reasoning isn't way off base.

I think using MacOS as the primary example isn't great, and more people would probably expect escape to go up a level rather than collapsing the whole thing. But it does work, so I think it's fine to leave it as is until/unless we get overwhelming feedback otherwise.

[alexstine]

I did check the submenu implementation in Google Drive and escape does collapse the whole menu. I agree, non-standard ARIA can be annoying.

[mtias]

Thank you all for driving and engaging on this one. Can't wait to leverage it to improve several areas of the current user interface that are unnecessarily long and disorganized.

[richtabor]

@ciampo are you thinking this may make it into 6.3 (re #51400)?

[ciampo]

@ciampo are you thinking this may make it into 6.3 (re #51400)?

Hey Rich, I've just posted an update directly on the PR. The TL;DR is that we've hit a bit of a wall around how the DropdownMenu enforces its "modality" and how it interacts with other Popover-based components.

I'll continue exploring more solutions in the next days, but as of today I'm not sure we'll be able to land #51400 before the 6.3 release.

In the meantime, it would be great to start getting some feedback about that PR anyway!

[ciampo]

Quick update: after #51400 surfaced a few critical limitations with using radix-ui for the new DropdownMenu component in the block editor, I tested ariakit as an alternative with encouraging results.

In the upcoming days, I will go ahead and try to put together a version of DropdownMenu based off ariakit, and then I'll try it again in the block settings dropdown — hopefully we should be on a good path 🤞

I will also update this issue's TODOs to better reflect the new plan of action.

[afercia]

I'd like to propose to consider to make the new dropdown component handle automatically the case where the passed items are only 1 item. See #56792 for the current droopdown.
We should avoid the component to render a dropdown that contains only one item as that's not a great UX. Could this be handled automatically? Cc @jorgefilipecosta

[andrewhayward]

We should avoid the component to render a dropdown that contains only one item as that's not a great UX. Could this be handled automatically?

A couple of thoughts...

First, I'm not sure how we could reasonably translate any generic menu item into a button in an automated way, given the number of variables involved. In the example above, we've going from a menu item with text and no icon, to an action button with an icon but no text. Not saying it's not possible, but certainly not straightforward. The API for doing so could get quite complex quite quickly.

Second, while I agree that we should ideally avoid action menus with one item, there's also an argument for consistency. There's a lot out there on macro consistency (including SC 3.2.3 and SC 3.2.4), but not so much on micro consistency. So this is isn't a suggestion either way, but we should definitely think about whether (in cases like this specifically) it's actually more confusing to have a mix of different modalities.

[youknowriad]

Just a comment as a regular user. If I have in the same table, two rows and maybe one row is editable and the other not. which would mean, for one row, you have two items in the "more menu" and for the other only one. I'd definitely favor consistency over having the button in different places across the two rows. So IMO, it's not something to be handled at the DropdownMenu component level.

[jameskoster]

FWIW it should be very rare for the ellipsis menu in data views to only contain a single action. The idea is for it to also contain quick edit actions like 'rename', 'view revisions', 'make sticky'... essentially everything you can do in the 'quick edit' experience in wp-admin. An older mockup for pages:

[jorgefilipecosta]

I'd like to propose to consider to make the new dropdown component handle automatically the case where the passed items are only 1 item. See #56792 for the current droopdown. We should avoid the component to render a dropdown that contains only one item as that's not a great UX. Could this be handled automatically? Cc @jorgefilipecosta

I guess automatically avoiding rendering dropdown menus with only one item is not feasible. It depends on what triggers the dropdown menu to open. It may be a simple button, it may be a small toolbar button, etc. But when using dropdown menus if the possibility of having only one item exists we should add the logic to avoid that.