RAC: Submenu support (#5648)

* initialize RAC submenu

* use cached children

* cleanup

* use one useRenderProps

* types

* cleanup

* fix trigger ref

* typescript

* add chevron style to submenu trigger

* types

* cleanup

* pass submenu ref

* add submenu story to menu story file

* fix nested case

* cleanup

* add nested story

* fix trigger attribute

* add tests

* update jsdoc

* add docs

* update storybook styles

* fix docs types

* cleanup tests

* move imports in docs closer to example

* typescript

* add example to homepage

* close all submenus if underlay is clicked

* revert autoformatting from headwind

* add to small example, fix imports and labels

* render via portal

* add render props and data attributes

* add || undefined

* add many items example

* add keys for storybook

* imrove styles on docs page

* improve homepage styles

* move chevron into item wrapper

* ts lint

* lint

* story style update

* style isSubmenuOpen states

* add dynamic example to dcs

* don't allow submenu trigger to be a link

* clarify submenutrigger children order in types

* use proper hover state from useHover

* update tests

* update docs to clarify children

* remove top -5 offset

* add disabled submenu example

* fix iOS VO submenu closing issue

* add Select story with many items

* move docs chevron styles from inline to CSS snippet

* export SubmenuTrigger directly without forwardRef

* update render props

* fix indentation

* add has-submenu to tailwind plugin

* remove offset

* fix homepage example styles

* fix docs example dark mode style

* focus trigger on escape

* add test for focus menu trigger after submenu closes via escape

* add alpha tag to docs

* add JSDoc

* fix restoring focus to menu trigger after nested submenu closed via Esc key

* lint

* Render popover outside menu item div

fixes hover event handling (events bubble through portals)

* support a custom delay prop in hook and RAC

* remove from homepage and tailwind starter for now

* revert auto-formatting

---------

Co-authored-by: Devon Govett <[email protected]>
Co-authored-by: Daniel Lu <[email protected]>

Author: 3 people

packages/@react-aria/menu/src/useSubmenuTrigger.ts

@@ -30,7 +30,12 @@ export interface AriaSubmenuTriggerProps {
   /** Ref of the menu that contains the submenu trigger. */
   parentMenuRef: RefObject<HTMLElement>,
   /** Ref of the submenu opened by the submenu trigger. */
-  submenuRef: RefObject<HTMLElement>
+  submenuRef: RefObject<HTMLElement>,
+  /**
+   * The delay time in milliseconds for the submenu to appear after hovering over the trigger.
+   * @default 200
+   */
+  delay?: number
 }
 
 interface SubmenuTriggerProps extends AriaMenuItemProps {
@@ -59,7 +64,7 @@ export interface SubmenuTriggerAria<T> {
  * @param ref - Ref to the submenu trigger element.
  */
 export function UNSTABLE_useSubmenuTrigger<T>(props: AriaSubmenuTriggerProps, state: SubmenuTriggerState, ref: RefObject<FocusableElement>): SubmenuTriggerAria<T> {
-  let {parentMenuRef, submenuRef, type = 'menu', isDisabled, node} = props;
+  let {parentMenuRef, submenuRef, type = 'menu', isDisabled, node, delay = 200} = props;
   let submenuTriggerId = useId();
   let overlayId = useId();
   let {direction} = useLocale();
@@ -188,7 +193,7 @@ export function UNSTABLE_useSubmenuTrigger<T>(props: AriaSubmenuTriggerProps, st
         if (!openTimeout.current) {
           openTimeout.current = setTimeout(() => {
             onSubmenuOpen();
-          }, 200);
+          }, delay);
         }
       } else if (!isHovered) {
         cancelOpenTimeout();

packages/@react-aria/selection/src/useSelectableCollection.ts

@@ -409,7 +409,10 @@ export function useSelectableCollection(options: AriaSelectableCollectionOptions
         if (!isVirtualized) {
           scrollIntoView(scrollRef.current, element);
         }
-        scrollIntoViewport(element, {containingElement: ref.current});
+        // Avoid scroll in iOS VO, since it may cause overlay to close (i.e. RAC submenu)
+        if (modality !== 'virtual') {
+          scrollIntoViewport(element, {containingElement: ref.current});
+        }
       }
     }
 

packages/react-aria-components/docs/Menu.mdx

@@ -11,7 +11,7 @@ import {Layout} from '@react-spectrum/docs';
 export default Layout;
 
 import docs from 'docs:react-aria-components';
-import {PropTable, HeaderInfo, TypeLink, PageDescription, StateTable, ContextTable} from '@react-spectrum/docs';
+import {PropTable, HeaderInfo, TypeLink, PageDescription, StateTable, ContextTable, VersionBadge} from '@react-spectrum/docs';
 import styles from '@react-spectrum/docs/src/docs.css';
 import packageData from 'react-aria-components/package.json';
 import Anatomy from './MenuAnatomy.svg';
@@ -38,7 +38,7 @@ type: component
 
 <HeaderInfo
   packageData={packageData}
-  componentNames={['MenuTrigger', 'Menu']}
+  componentNames={['MenuTrigger', 'Menu', 'SubmenuTrigger']}
   sourceData={[
     {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/patterns/menu/'}
   ]} />
@@ -226,7 +226,18 @@ function MyMenuButton<T extends object>({label, children, ...props}: MyMenuButto
 }
 
 function MyItem(props: MenuItemProps) {
-  return <MenuItem {...props} className={({isFocused, isSelected}) => `my-item ${isFocused ? 'focused' : ''}`} />
+  return (
+    <MenuItem {...props} className={({isFocused, isSelected, isOpen}) => `my-item ${isFocused ? 'focused' : ''} ${isOpen ? 'open' : ''}`}>
+      {({hasSubmenu}) => (
+        <>
+          {props.children}
+          {hasSubmenu && (
+            <svg className="chevron" viewBox="0 0 24 24"><path d="m9 18 6-6-6-6" /></svg>
+          )}
+        </>
+      )}
+    </MenuItem>
+  );
 }
 
 <MyMenuButton label="Edit">
@@ -254,6 +265,23 @@ function MyItem(props: MenuItemProps) {
     background: #e70073;
     color: white;
   }
+  &.open:not(.focused) {
+    background: rgba(192, 192, 192, 0.3);
+    color: var(--text-color);
+  }
+  .chevron {
+    width: 20;
+    height: 20;
+    fill: none;
+    stroke: currentColor;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    stroke-width: 2;
+    position: absolute;
+    right: 0;
+    top: 0;
+    height: 100%;
+  }
 }
 
 @media (forced-colors: active) {
@@ -658,12 +686,106 @@ function Example() {
 }
 ```
 
+## Submenus <VersionBadge version="alpha" style={{marginLeft: 4, verticalAlign: 'bottom'}} />
+
+Submenus can be created by wrapping an item and a submenu in a `SubmenuTrigger`. The `SubmenuTrigger` accepts exactly two children: the first child should be the `MenuItem` which triggers opening of the submenu, and second child should be the `Popover` containing the submenu.
+
+### Static
+
+```tsx example
+import {Menu, Popover, SubmenuTrigger} from 'react-aria-components';
+
+<MyMenuButton label="Actions">
+  <MyItem>Cut</MyItem>
+  <MyItem>Copy</MyItem>
+  <MyItem>Delete</MyItem>
+  <SubmenuTrigger>
+    <MyItem aria-label="Share">Share</MyItem>
+    <Popover>
+      <Menu>
+        <MyItem>SMS</MyItem>
+        <MyItem>Twitter</MyItem>
+        <SubmenuTrigger>
+          <MyItem aria-label="Email">Email</MyItem>
+          <Popover>
+            <Menu>
+              <MyItem>Work</MyItem>
+              <MyItem>Personal</MyItem>
+            </Menu>
+          </Popover>
+        </SubmenuTrigger>
+      </Menu>
+    </Popover>
+  </SubmenuTrigger>
+</MyMenuButton>
+```
+
+### Dynamic
+
+You can define a recursive function to render the nested menu items dynamically.
+
+```tsx example
+import {Menu, Popover, SubmenuTrigger} from 'react-aria-components';
+
+let items = [
+  {id: 'cut', name: 'Cut'},
+  {id: 'copy', name: 'Copy'},
+  {id: 'delete', name: 'Delete'},
+  {id: 'share', name: 'Share', children: [
+    {id: 'sms', name: 'SMS'},
+    {id: 'twitter', name: 'Twitter'},
+    {id: 'email', name: 'Email', children: [
+      {id: 'work', name: 'Work'},
+      {id: 'personal', name: 'Personal'},
+    ]}
+  ]}
+];
+
+<MyMenuButton label="Actions" items={items}>
+  {function renderSubmenu(item) {
+    if (item.children) {
+      return (
+        <SubmenuTrigger>
+          <MyItem key={item.name} aria-label={item.name}>{item.name}</MyItem>
+          <Popover>
+            <Menu items={item.children}>
+              {(item) => renderSubmenu(item)}
+            </Menu>
+          </Popover>
+        </SubmenuTrigger>
+      );
+    } else {
+      return <MyItem key={item.name}>{item.name}</MyItem>;
+    }
+  }}
+</MyMenuButton>
+```
+
+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>
+
+```css
+.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="right"] {
+  margin-left: -5px;
+}
+
+.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="left"] {
+  margin-right: -5px;
+}
+```
+
+</details>
+
 ## Props
 
 ### MenuTrigger
 
 <PropTable component={docs.exports.MenuTrigger} links={docs.links} />
 
+### SubmenuTrigger
+
+<PropTable component={docs.exports.SubmenuTrigger} links={docs.links} />
+
 ### Button
 
 A `<Button>` accepts its contents as `children`. Other props such as `onPress` and `isDisabled` will be set by the `MenuTrigger`.
@@ -812,6 +934,18 @@ Within a MenuTrigger, the popover will have the `data-trigger="MenuTrigger"` att
 }
 ```
 
+Within a SubmenuTrigger, the popover will have the `data-trigger="SubmenuTrigger"` attribute, which can be used to define submenu-specific styles.
+
+```css render=false
+.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="right"] {
+  transform: translateX(-5px);
+}
+
+.react-aria-Popover[data-trigger=SubmenuTrigger][data-placement="left"] {
+  transform: translateX(5px);
+}
+```
+
 ### Menu
 
 A `Menu` can be targeted with the `.react-aria-Menu` CSS selector, or by overriding with a custom `className`.

packages/react-aria-components/example/index.css

@@ -15,6 +15,8 @@ html {
 .menu, .group {
   padding: 0;
   list-style: none;
+  overflow-y: auto;
+  max-height: inherit;
 }
 
 .item {
@@ -43,11 +45,20 @@ html {
   }
 }
 
+.item[data-disabled] {
+  opacity: 0.4;
+}
+
 .item.focused {
   background: gray;
   color: white;
 }
 
+.item.open:not(.focused) {
+  background: lightslategray;
+  color: white;
+}
+
 .item.item.hovered {
   background: lightsalmon;
   color: white;
@@ -58,6 +69,20 @@ html {
   color: white;
 }
 
+.item[data-has-submenu]::after {
+  content: '›';
+  content: '›' / '';
+  justify-self: end;
+}
+
+.popover[data-trigger=SubmenuTrigger][data-placement="right"] {
+  margin-left: -8px;
+}
+
+.popover[data-trigger=SubmenuTrigger][data-placement="left"] {
+  margin-right: -8px;
+}
+
 .wrapper {
   display: flex;
   flex-direction: column;

packages/react-aria-components/package.json

@@ -41,8 +41,10 @@
     "@internationalized/string": "^3.2.0",
     "@react-aria/focus": "^3.16.0",
     "@react-aria/interactions": "^3.20.1",
+    "@react-aria/menu": "^3.12.0",
     "@react-aria/toolbar": "3.0.0-beta.1",
     "@react-aria/utils": "^3.23.0",
+    "@react-stately/menu": "^3.6.0",
     "@react-stately/table": "^3.11.4",
     "@react-stately/utils": "^3.9.0",
     "@react-types/form": "^3.7.1",