Implement options to make the Menu compatible with WAI-ARIA recommendations for navigation

docs/src/pages/core/menu.mdx

@@ -32,8 +32,8 @@ Set `trigger="hover"` to reveal dropdown when hovers over menu target and dropdo
 `closeDelay` and `openDelay` props can be used to control open and close delay in ms.
 Note that:
 
-- If you set `closeDelay={0}` then menu will close before user will reach dropdown, set `offset={0}` to remove space between target element and dropdown
-- Menu with `trigger="hover"` is not accessible – users that navigate with keyboard will not be able to use it
+- If you set `closeDelay={0}` then menu will close before user will reach dropdown, set `offset={0}` to remove space between target element and dropdown.
+- Menu with `trigger="hover"` is not accessible – users that navigate with keyboard will not be able to use it. If you need click-hover hover and click triggers, use `trigger="click-hover"`.
 
 <Demo data={MenuDemos.hover} />
 
@@ -104,23 +104,28 @@ function Demo() {
 
 ## Accessibility
 
-Menu follows [WAI-ARIA recommendations](https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-links.html):
+Menu follows [WAI-ARIA recommendations](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-links/):
 
 - Dropdown element has `role="menu"` and `aria-labelledby="target-id"` attributes
 - Target element has `aria-haspopup="menu"`, `aria-expanded`, `aria-controls="dropdown-id"` attributes
 - Menu item has `role="menuitem"` attribute
 
-## Supported target elements
+### Supported target elements
 
 Uncontrolled Menu with `trigger="click"` (default) will be accessible only when used with `button` element or component that renders it ([Button](/core/button/), [ActionIcon](/core/action-icon/), etc.).
 Other elements will not support `Space` and `Enter` key presses.
 
-## Hover menu
+### Hover menu
 
-Menu with `trigger="hover"` is not accessible – it cannot be accessed with keyboard,
-use it only if you do not care about accessibility.
+Menu with `trigger="hover"` is not accessible – it cannot be accessed with keyboard, use it only if you do not care about accessibility. If you need click-hover hover and click triggers, use `trigger="click-hover"`.
 
-## Keyboard interactions
+### Navigation
+
+If you are using the Menu to build a Navigation, you can use the options from the demo below to follow the [WAI-ARIA recommendations for navigation](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/).
+
+<Demo data={MenuDemos.navigation} />
+
+### Keyboard interactions
 
 <KeyboardEventsTable
   data={[
@@ -156,3 +161,5 @@ use it only if you do not care about accessibility.
     },
   ]}
 />
+
+If you also need to support `Tab` and `Shift + Tab` then set `menuItemTabIndex={0}`.

packages/@docs/demos/src/demos/core/Menu/Menu.demo.navigation.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Menu, Group } from '@mantine/core';
+import { MantineDemo } from '@mantinex/demo';
+import { DemoMenuItems } from './_menu-items';
+
+const code = `
+import { Menu, Group } from '@mantine/core';
+
+function Demo() {
+  return (
+    <Group>
+      <Menu trigger="click-hover" loop={false} withinPortal={false} trapFocus={false} menuItemTabIndex={0}>
+        {/* ... menu items */}
+      </Menu>
+      <Menu trigger="click-hover" loop={false} withinPortal={false} trapFocus={false} menuItemTabIndex={0}>
+        {/* ... menu items */}
+      </Menu>
+    </Group>
+  );
+}
+`;
+
+function Demo() {
+  return (
+    <Group>
+      <Menu
+        trigger="click-hover"
+        loop={false}
+        withinPortal={false}
+        trapFocus={false}
+        menuItemTabIndex={0}
+      >
+        <DemoMenuItems />
+      </Menu>
+      <Menu
+        trigger="click-hover"
+        loop={false}
+        withinPortal={false}
+        trapFocus={false}
+        menuItemTabIndex={0}
+      >
+        <DemoMenuItems />
+      </Menu>
+    </Group>
+  );
+}
+
+export const navigation: MantineDemo = {
+  type: 'code',
+  code,
+  component: Demo,
+  centered: true,
+};

packages/@docs/demos/src/demos/core/Menu/Menu.demos.story.tsx

@@ -47,3 +47,8 @@ export const DemoClickHover = {
   name: '⭐ Demo: clickHover',
   render: renderDemo(demos.clickHover),
 };
+
+export const DemoNavigation = {
+  name: '⭐ Demo: navigation',
+  render: renderDemo(demos.navigation),
+};

packages/@docs/demos/src/demos/core/Menu/index.ts

@@ -7,3 +7,4 @@ export { positionConfigurator } from './Menu.demo.positionConfigurator';
 export { disabled } from './Menu.demo.disabled';
 export { customControl } from './Menu.demo.customControl';
 export { clickHover } from './Menu.demo.clickHover';
+export { navigation } from './Menu.demo.navigation';

packages/@mantine/core/src/components/Menu/Menu.context.ts

@@ -15,6 +15,7 @@ interface MenuContext {
   opened: boolean;
   unstyled: boolean | undefined;
   getStyles: GetStylesApi<MenuFactory>;
+  menuItemTabIndex: -1 | 0 | undefined;
 }
 
 export const [MenuContextProvider, useMenuContext] = createSafeContext<MenuContext>(

packages/@mantine/core/src/components/Menu/Menu.tsx

@@ -46,6 +46,9 @@ export interface MenuProps extends __PopoverProps, StylesApiProps<MenuFactory> {
   /** Uncontrolled menu initial opened state */
   defaultOpened?: boolean;
 
+  /** Determines whether dropdown should trap focus of keyboard events */
+  trapFocus?: boolean;
+
   /** Called when menu opened state changes */
   onChange?: (opened: boolean) => void;
 
@@ -61,7 +64,7 @@ export interface MenuProps extends __PopoverProps, StylesApiProps<MenuFactory> {
   /** Determines whether arrow key presses should loop though items (first to last and last to first) */
   loop?: boolean;
 
-  /** Determines whether dropdown should be closed when Escape key is pressed, defaults to true */
+  /** Determines whether dropdown should be closed when Escape key is pressed */
   closeOnEscape?: boolean;
 
   /** Event which should open menu */
@@ -73,22 +76,28 @@ export interface MenuProps extends __PopoverProps, StylesApiProps<MenuFactory> {
   /** Close delay in ms, applicable only to trigger="hover" variant */
   closeDelay?: number;
 
-  /** Determines whether dropdown should be closed on outside clicks, default to true */
+  /** Determines whether dropdown should be closed on outside clicks */
   closeOnClickOutside?: boolean;
 
   /** Events that trigger outside clicks */
   clickOutsideEvents?: string[];
 
   /** id base to create accessibility connections */
   id?: string;
+
+  /** Set the `tabindex` on all menu items. Defaults to -1 */
+  menuItemTabIndex?: -1 | 0;
 }
 
 const defaultProps: Partial<MenuProps> = {
+  trapFocus: true,
   closeOnItemClick: true,
+  clickOutsideEvents: ['mousedown', 'touchstart', 'keydown'],
   loop: true,
   trigger: 'click',
   openDelay: 0,
   closeDelay: 100,
+  menuItemTabIndex: -1,
 };
 
 export function Menu(_props: MenuProps) {
@@ -99,6 +108,7 @@ export function Menu(_props: MenuProps) {
     onClose,
     opened,
     defaultOpened,
+    trapFocus,
     onChange,
     closeOnItemClick,
     loop,
@@ -111,6 +121,7 @@ export function Menu(_props: MenuProps) {
     unstyled,
     variant,
     vars,
+    menuItemTabIndex,
     ...others
   } = props;
 
@@ -176,14 +187,15 @@ export function Menu(_props: MenuProps) {
         loop,
         trigger,
         unstyled,
+        menuItemTabIndex,
       }}
     >
       <Popover
         {...others}
         opened={_opened}
         onChange={toggleDropdown}
         defaultOpened={defaultOpened}
-        trapFocus={trigger === 'click' && _opened}
+        trapFocus={trapFocus}
         closeOnEscape={closeOnEscape}
         __staticSelector="Menu"
         classNames={resolvedClassNames}

packages/@mantine/core/src/components/Menu/MenuItem/MenuItem.tsx

@@ -96,7 +96,7 @@ export const MenuItem = polymorphicFactory<MenuItemFactory>((props, ref) => {
     <UnstyledButton
       {...others}
       unstyled={ctx.unstyled}
-      tabIndex={-1}
+      tabIndex={ctx.menuItemTabIndex}
       onFocus={handleFocus}
       {...ctx.getStyles('item', { className, style, styles, classNames })}
       ref={useMergedRef(itemRef, ref)}