diff --git a/site/src/pages/components/menu.explainer.mdx b/site/src/pages/components/menu.explainer.mdx index 1567d183..efc94184 100644 --- a/site/src/pages/components/menu.explainer.mdx +++ b/site/src/pages/components/menu.explainer.mdx @@ -81,22 +81,25 @@ model. See https://github.com/openui/open-ui/issues/1194 for more discussion abo `` -* Menubar should be used to represent a series of ``s that can then open submenus of commands. -* In a menubar, a menuitem’s most common purpose is to invoke submenus (menulists). -* An **in-page** menu that can contain a list of `` -* Menuitems within a menubar are displayed horizontally by default. -* Supports :disabled, disabled attribute +* Menubars commonly represent a series of ``s that are used to open their own submenus (menulists) of commands. +* Unlike menulists, menubars are rendered part of normal flow rather than as a popover, so their menuitems are persistently available. +* Menubars, and thus their menuitems, are commonly rendered horizontally. +* Supports :disabled, disabled attribute. If a menubar is disabled then all of its descendent menuitems are also disabled. `` -* Menulist should be used to represent submenus of commands. -* In a menulist, a menu item's most common purpose is to invoke actions (commands) or other submenus (menulists). -* A **popover** menu that can contain a list of `` -* Anchored to the button which is declaratively set up to open it -* Attributes - * disabled, open, name? +* Menulist should be used to represent a listing, or submenu listing of commands. +* In a menulist, a menuitem's most common purpose is to invoke actions (commands) or other submenus (menulists). +* Menulists are commonly rendered as a **popover**. Submenus are also commonly rendered as adjacent popovers on larger viewports. + * On smaller viewports, submenus may overlay or replace the higher-level menulist from which they were invoked. + * A "back" menuitem may be rendered to allow a user to "navigate up" to the higher-level menulist. +* The menulist popover is anchored to the button or menuitem which invoked it +* Supports :disabled, disabled attribute. If a menulist is disabled then all of its descendent menuitems are also disabled. -**Question: Is `
` necessary to group `` together?** +**Question:** are the `open` or `name` attributes needed for `menubar` or `menulist`? +??? + +**Question: Is `
` necessary to group `` elements together?** Yes. While, we can use the ["name"](https://html.spec.whatwg.org/C#attr-fe-name) attribute to logically group exclusive checkable ``s together, to support captioned groups @@ -106,7 +109,7 @@ without a `
`, they are grouped together under their parent ` but are logically separate and are not checkable. Note, `
` is a more general grouping element than ``, which we briefly -considered, but decided against since it is used for grouping options. +considered, but decided against since it is used, and named, specifically for grouping options. Our proposal includes adding a `checkable` attribute on `
`, to group ``s as either radios or checkboxes, instead of introducing new `` and `` @@ -140,21 +143,21 @@ Similarly to customizable select, we expect everything to be wrapped inside `` and `` to help group the menu items together. -We should support specific use cases of interactive elements outside the ``. For example, if the user wants to add an `` element, it should not be wrapped inside a `` and should instead be a sibling of ``s. +We should support specific use cases of interactive elements that can be found within native operating system menus, as siblings to `` elements. For example, if the user wants to add an `` element, it should not be allowed as a child of a ``. Rather, it should be allowed as the first or last child element of a `` or `` element. -menubar examples with search input as a sibling of menuitems +examples of text fields as the first child of menulist popups. The first example shows a text field where a percentage can be adjusted, it is followed by a number of menuitems to zoom or adjust an editable canvas. The second example shows a search text field as the first item in a menulist invoked from a Help menuitem of a menubar. Two additional menuitems follow the search text field in this menulist popup. ## Questions -### When to use Select vs Menu +### When to use Select vs Menulist -Just like a select element, the menu element has a list of choices to pick from. And with customizable select now available, users might be confused on which one to use. +Just like a select element, the menulist element will represent a series of choices to pick from. And with customizable select now available, users might be confused on which one to use. The `