[core] feat(MenuItem): new prop 'roleStructure' (#5377)

packages/core/src/components/menu/menuItem.tsx

@@ -77,6 +77,28 @@ export interface IMenuItemProps extends ActionProps, LinkProps {
      */
     labelElement?: React.ReactNode;
 
+    /**
+     * Changes the ARIA `role` property structure of this MenuItem to accomodate for various
+     * different `role`s of the parent Menu `ul` element.
+     *
+     * If `menuitem`, role structure becomes:
+     *
+     * `<li role="none"`
+     *     `<a role="menuitem"`
+     *
+     * which is proper role structure for a `<ul role="menu"` parent (this is the default `role` of a `Menu`).
+     *
+     * If `listoption`, role structure becomes:
+     *
+     * `<li role="option"`
+     *     `<a role=undefined`
+     *
+     *  which is proper role structure for a `<ul role="listbox"` parent, or a `<select>` parent.
+     *
+     * @default "menuitem"
+     */
+    roleStructure?: "menuitem" | "listoption";
+
     /**
      * Whether the text should be allowed to wrap to multiple lines.
      * If `false`, text will be truncated with an ellipsis when it reaches `max-width`.
@@ -153,6 +175,7 @@ export class MenuItem extends AbstractPureComponent2<MenuItemProps & React.Ancho
             labelElement,
             multiline,
             popoverProps,
+            roleStructure = "menuitem",
             selected,
             shouldDismissPopover,
             submenuProps,
@@ -180,10 +203,15 @@ export class MenuItem extends AbstractPureComponent2<MenuItemProps & React.Ancho
             className,
         );
 
+        const [liRole, targetRole, ariaSelected] =
+            roleStructure === "listoption"
+                ? ["option", undefined, active || selected] // parent has listbox role, or is a <select>
+                : ["none", "menuitem", undefined]; // parent has menu role
+
         const target = React.createElement(
             tagName,
             {
-                role: "menuitem",
+                role: targetRole,
                 tabIndex: 0,
                 ...htmlProps,
                 ...(disabled ? DISABLED_PROPS : {}),
@@ -205,7 +233,7 @@ export class MenuItem extends AbstractPureComponent2<MenuItemProps & React.Ancho
 
         const liClasses = classNames({ [Classes.MENU_SUBMENU]: hasSubmenu });
         return (
-            <li className={liClasses} role="none">
+            <li className={liClasses} role={liRole} aria-selected={ariaSelected}>
                 {this.maybeRenderPopover(target, children)}
             </li>
         );

packages/core/test/menu/menuItemTests.tsx

@@ -58,6 +58,18 @@ describe("MenuItem", () => {
         assert.lengthOf(submenu.props.children, 3);
     });
 
+    it("default role prop structure is correct for a menuitem that is a an item of a ul with role=menu", () => {
+        const wrapper = mount(<MenuItem text="Roles" />);
+        assert.equal(wrapper.find("li").prop("role"), "none");
+        assert.equal(wrapper.find("a").prop("role"), "menuitem");
+    });
+
+    it("can set roleStructure to change role prop structure to that of a listbox or select item", () => {
+        const wrapper = mount(<MenuItem text="Roles" roleStructure="listoption" />);
+        assert.equal(wrapper.find("li").prop("role"), "option");
+        assert.equal(wrapper.find("a").prop("role"), undefined);
+    });
+
     it("disabled MenuItem will not show its submenu", () => {
         const wrapper = shallow(
             <MenuItem disabled={true} icon="style" text="Style">

packages/docs-app/src/common/filmSelect.tsx

@@ -69,7 +69,7 @@ export default function ({ allowCreate = false, fill, ...restProps }: Props) {
             createNewItemFromQuery={maybeCreateNewItemFromQuery}
             createNewItemRenderer={maybeCreateNewItemRenderer}
             itemsEqual={areFilmsEqual}
-            noResults={<MenuItem disabled={true} text="No results." />}
+            noResults={<MenuItem disabled={true} text="No results." roleStructure="listoption" />}
             onItemSelect={handleItemSelect}
             items={items}
             fill={fill}

packages/docs-app/src/common/films.tsx

@@ -142,6 +142,7 @@ export const renderFilm: ItemRenderer<IFilm> = (film, { handleClick, handleFocus
             active={modifiers.active}
             disabled={modifiers.disabled}
             label={film.year.toString()}
+            roleStructure="listoption"
             key={film.rank}
             onClick={handleClick}
             onFocus={handleFocus}
@@ -158,6 +159,7 @@ export const renderCreateFilmOption = (
     <MenuItem
         icon="add"
         text={`Create "${query}"`}
+        roleStructure="listoption"
         active={active}
         onClick={handleClick}
         shouldDismissPopover={false}

packages/docs-app/src/examples/select-examples/multiSelectExample.tsx

@@ -105,7 +105,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         });
 
         const initialContent = this.state.hasInitialContent ? (
-            <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} />
+            <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} roleStructure="listoption" />
         ) : // explicit undefined (not null) for default behavior (show full list)
         undefined;
         const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
@@ -124,7 +124,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     // we may customize the default filmSelectProps.items by
                     // adding newly created items to the list, so pass our own
                     items={this.state.items}
-                    noResults={<MenuItem disabled={true} text="No results." />}
+                    noResults={<MenuItem disabled={true} text="No results." roleStructure="listoption" />}
                     onClear={this.state.showClearButton ? this.handleClear : undefined}
                     onItemSelect={this.handleFilmSelect}
                     onItemsPaste={this.handleFilmsPaste}
@@ -250,9 +250,9 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         }
         return (
             <MenuItem
-                aria-selected={this.isFilmSelected(film)}
                 selected={modifiers.active}
                 icon={this.isFilmSelected(film) ? "tick" : "blank"}
+                roleStructure="listoption"
                 key={film.rank}
                 label={film.year.toString()}
                 onClick={handleClick}

packages/docs-app/src/examples/select-examples/selectExample.tsx

@@ -84,7 +84,7 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         const { allowCreate, disabled, disableItems, matchTargetWidth, minimal, ...flags } = this.state;
 
         const initialContent = this.state.hasInitialContent ? (
-            <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} />
+            <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} roleStructure="listoption" />
         ) : undefined;
 
         return (

packages/docs-app/src/examples/select-examples/suggestExample.tsx

@@ -104,7 +104,7 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
                     // we may customize the default filmSelectProps.items by
                     // adding newly created items to the list, so pass our own.
                     items={this.state.items}
-                    noResults={<MenuItem disabled={true} text="No results." />}
+                    noResults={<MenuItem disabled={true} text="No results." roleStructure="listoption" />}
                     onItemSelect={this.handleValueChange}
                     popoverProps={{ matchTargetWidth, minimal }}
                 />

packages/select/src/common/listItemsProps.ts

@@ -126,6 +126,8 @@ export interface IListItemsProps<T> extends Props {
      * If omitted, nothing will be rendered in this case.
      *
      * This prop is ignored if a custom `itemListRenderer` is supplied.
+     *
+     * NOTE: if passing a `MenuItem`, ensure it has `roleStructure="listoption"` prop.
      */
     noResults?: React.ReactNode;
 

packages/select/src/components/select/select2.md

@@ -40,7 +40,7 @@ ReactDOM.render(
         items={Films.items}
         itemPredicate={Films.itemPredicate}
         itemRenderer={Films.itemRenderer}
-        noResults={<MenuItem disabled={true} text="No results." />}
+        noResults={<MenuItem disabled={true} text="No results."  roleStructure="listoption" />}
         onItemSelect={...}
     >
         {/* children become the popover target; render value here */}
@@ -124,10 +124,10 @@ If you wish, you can allow users to select a brand new item that doesn't appear
 in the list, based on the current query string. Use `createNewItemFromQuery` and
 `createNewItemRenderer` to enable this:
 - `createNewItemFromQuery`: Specifies how to convert a user-entered query string
-into an item of type `<T>` that `Select2` understands.
+    into an item of type `<T>` that `Select2` understands.
 - `createNewItemRenderer`: Renders a custom "Create Item" element that will be
-shown at the bottom of the list. When selected via click or `Enter`, this element
-will invoke `onItemSelect` with the item returned from `createNewItemFromQuery`.
+    shown at the bottom of the list. When selected via click or `Enter`, this element
+    will invoke `onItemSelect` with the item returned from `createNewItemFromQuery`.
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-info-sign">
     <h4 class="@ns-heading">Avoiding type conflicts</h4>
@@ -158,6 +158,7 @@ function renderCreateFilmOption(
         <MenuItem
             icon="add"
             text={`Create "${query}"`}
+            roleStructure="listoption"
             selected={active}
             onClick={handleClick}
             shouldDismissPopover={false}
@@ -172,7 +173,7 @@ ReactDOM.render(
         items={Films.items}
         itemPredicate={Films.itemPredicate}
         itemRenderer={Films.itemRenderer}
-        noResults={<MenuItem disabled={true} text="No results." />}
+        noResults={<MenuItem disabled={true} text="No results."  roleStructure="listoption" />}
         onItemSelect={...}
     />,
     document.querySelector("#root")
@@ -257,12 +258,13 @@ const renderFilm: ItemRenderer<Film> = (film, { handleClick, handleFocus, modifi
     }
     return (
         <MenuItem
+            text={film.title}
+            label={film.year}
+            roleStructure="listoption"
             selected={modifiers.active}
             key={film.title}
-            label={film.year}
             onClick={handleClick}
             onFocus={handleFocus}
-            text={film.title}
         />
     );
 };
@@ -286,6 +288,7 @@ const renderMenu: ItemListRenderer<Film> = ({ items, itemsParentRef, query, rend
             <MenuItem
                 disabled={true}
                 text={`Found ${renderedItems.length} items matching "${query}"`}
+                roleStructure="listoption"
             />
             {renderedItems}
         </Menu>