better-mui-menu 0.1.0

package/src/MultiLevelMenu/MultiLevelMenu.test.tsx

@@ -0,0 +1,369 @@
+/**
+ * @jest-environment jsdom
+ */
+/// <reference types="@testing-library/jest-dom" />
+import type { MouseEvent } from 'react';
+import { useState } from 'react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import Cloud from '@mui/icons-material/Cloud';
+import ContentCopy from '@mui/icons-material/ContentCopy';
+import ContentCut from '@mui/icons-material/ContentCut';
+import ContentPaste from '@mui/icons-material/ContentPaste';
+import type { MultiLevelMenuItem } from './types';
+import { MultiLevelMenu } from './index';
+
+const buildMenuItems = () => {
+  const spies = {
+    cut: jest.fn(),
+    google: jest.fn(),
+    deep: jest.fn(),
+  };
+
+  const items: MultiLevelMenuItem[] = [
+    {
+      id: 'cut',
+      label: 'Cut',
+      startIcon: ContentCut,
+      onClick: spies.cut,
+    },
+    {
+      id: 'web-clipboard',
+      label: 'Web Clipboard',
+      startIcon: Cloud,
+      items: [
+        {
+          id: 'google-cloud',
+          label: 'Google Cloud',
+          startIcon: ContentCopy,
+          onClick: spies.google,
+        },
+        {
+          id: 'deep-options',
+          label: 'Deep Options',
+          startIcon: ContentPaste,
+          items: [
+            {
+              id: 'deep-item',
+              label: 'Deep Item',
+              startIcon: Cloud,
+              onClick: spies.deep,
+            },
+          ],
+        },
+      ],
+    },
+  ];
+
+  return { items, spies };
+};
+
+function MenuWithTrigger({ items }: { items: MultiLevelMenuItem[] }) {
+  const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null);
+
+  const handleOpen = (event: MouseEvent<HTMLButtonElement>) => {
+    setAnchorEl(event.currentTarget);
+  };
+
+  const handleClose = () => {
+    setAnchorEl(null);
+  };
+
+  return (
+    <>
+      <button
+        type='button'
+        aria-controls={anchorEl ? 'icon-menu' : undefined}
+        aria-haspopup='true'
+        aria-expanded={anchorEl ? 'true' : undefined}
+        onClick={handleOpen}
+      >
+        Menu Actions
+      </button>
+      <MultiLevelMenu anchorEl={anchorEl} open={Boolean(anchorEl)} onClose={handleClose} items={items} />
+    </>
+  );
+}
+
+const setupMenu = () => {
+  const user = userEvent.setup();
+  const { items, spies } = buildMenuItems();
+  render(<MenuWithTrigger items={items} />);
+  const toggleButton = screen.getByRole('button', { name: /menu actions/i });
+  return { user, toggleButton, spies };
+};
+
+describe('MultiLevelMenu', () => {
+  it('closes the root menu after selecting a leaf action', async () => {
+    const { user, toggleButton, spies } = setupMenu();
+    await user.click(toggleButton);
+    await waitFor(() => {
+      expect(toggleButton).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    const cutItem = await screen.findByRole('menuitem', { name: 'Cut' });
+    await user.click(cutItem);
+
+    expect(spies.cut).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(toggleButton).not.toHaveAttribute('aria-expanded');
+    });
+  });
+
+  it('handles actions when callers omit explicit ids', async () => {
+    const user = userEvent.setup();
+    const spies = {
+      copy: jest.fn(),
+      nested: jest.fn(),
+    };
+    const items: MultiLevelMenuItem[] = [
+      {
+        label: 'Copy',
+        startIcon: ContentCopy,
+        onClick: spies.copy,
+      },
+      {
+        label: 'More options',
+        startIcon: Cloud,
+        items: [
+          {
+            label: 'Nested action',
+            startIcon: ContentCopy,
+            onClick: spies.nested,
+          },
+        ],
+      },
+    ];
+
+    render(<MenuWithTrigger items={items} />);
+    const toggleButton = screen.getByRole('button', { name: /menu actions/i });
+    await user.click(toggleButton);
+
+    const copyItem = await screen.findByRole('menuitem', { name: 'Copy' });
+    await user.click(copyItem);
+
+    expect(spies.copy).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(toggleButton).not.toHaveAttribute('aria-expanded');
+    });
+
+    await user.click(toggleButton);
+    const nestedTrigger = await screen.findByRole('menuitem', { name: 'More options' });
+    await user.hover(nestedTrigger);
+    const nestedAction = await screen.findByRole('menuitem', { name: 'Nested action' });
+    await user.click(nestedAction);
+
+    expect(spies.nested).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(toggleButton).not.toHaveAttribute('aria-expanded');
+    });
+  });
+
+  it('invokes a nested menu action and closes both menus', async () => {
+    const { user, toggleButton, spies } = setupMenu();
+    await user.click(toggleButton);
+
+    const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+    await user.hover(nestedTrigger);
+
+    const googleItem = await screen.findByRole('menuitem', { name: 'Google Cloud' });
+    await user.click(googleItem);
+
+    expect(spies.google).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+    });
+    expect(toggleButton).not.toHaveAttribute('aria-expanded');
+  });
+
+  it('fires deep-nested actions and closes the root menu', async () => {
+    const { user, toggleButton, spies } = setupMenu();
+    await user.click(toggleButton);
+
+    const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+    await user.hover(nestedTrigger);
+
+    const deepTrigger = await screen.findByRole('menuitem', { name: 'Deep Options' });
+    await user.hover(deepTrigger);
+
+    const deepItem = await screen.findByRole('menuitem', { name: 'Deep Item' });
+    await user.click(deepItem);
+
+    expect(spies.deep).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+    });
+    expect(toggleButton).not.toHaveAttribute('aria-expanded');
+  });
+
+  it('keeps the submenu open when the mouse leaves the trigger toward the submenu (critical feature)', async () => {
+    const { user, toggleButton } = setupMenu();
+    await user.click(toggleButton);
+
+    const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+    await user.hover(nestedTrigger);
+
+    const nestedMenu = await screen.findByRole('menu', { name: 'Web Clipboard' });
+    fireEvent.mouseLeave(nestedTrigger, { relatedTarget: nestedMenu });
+    fireEvent.mouseLeave(nestedMenu, { relatedTarget: nestedTrigger });
+
+    expect(nestedMenu).toBeVisible();
+  });
+
+  it('closes the submenu when the mouse leaves away from the trigger (critical Popper behavior)', async () => {
+    const { user, toggleButton } = setupMenu();
+    await user.click(toggleButton);
+
+    const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+    await user.hover(nestedTrigger);
+
+    const nestedMenu = await screen.findByRole('menu', { name: 'Web Clipboard' });
+    fireEvent.mouseLeave(nestedMenu, { relatedTarget: document.body });
+
+    await waitFor(() => {
+      expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+    });
+    expect(nestedTrigger).not.toHaveAttribute('aria-expanded');
+  });
+
+  describe('Accessibility features', () => {
+    it('exposes ARIA relationships so screen readers can describe nested menus', async () => {
+      const { user, toggleButton } = setupMenu();
+      await user.click(toggleButton);
+
+      const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+      expect(nestedTrigger).toHaveAttribute('aria-haspopup', 'menu');
+      expect(nestedTrigger).toHaveAttribute('aria-controls', 'web-clipboard-submenu');
+      expect(nestedTrigger.id).toBe('web-clipboard');
+      expect(nestedTrigger).not.toHaveAttribute('aria-expanded');
+
+      await user.hover(nestedTrigger);
+      const nestedMenu = await screen.findByRole('menu', { name: 'Web Clipboard' });
+      expect(nestedMenu).toHaveAttribute('id', 'web-clipboard-submenu');
+      expect(nestedMenu).toHaveAttribute('aria-labelledby', nestedTrigger.id);
+      expect(nestedMenu).toHaveAttribute('role', 'menu');
+      expect(nestedTrigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('supports keyboard navigation so focus stays with the active branch', async () => {
+      const { user, toggleButton } = setupMenu();
+      await user.click(toggleButton);
+
+      const nestedTrigger = await screen.findByRole('menuitem', { name: 'Web Clipboard' });
+      await act(() => {
+        nestedTrigger.focus();
+      });
+
+      await user.keyboard('{ArrowRight}');
+      const firstNestedItem = await screen.findByRole('menuitem', { name: 'Google Cloud' });
+      await waitFor(() => {
+        expect(firstNestedItem).toHaveFocus();
+      });
+
+      await user.keyboard('{ArrowLeft}');
+      await waitFor(() => {
+        expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+        expect(nestedTrigger).toHaveFocus();
+      });
+
+      await user.keyboard('{Enter}');
+      const reopenedItem = await screen.findByRole('menuitem', { name: 'Google Cloud' });
+      await waitFor(() => {
+        expect(reopenedItem).toHaveFocus();
+      });
+    });
+
+    describe('Keyboard actions & Focus management', () => {
+      it('traversing down to deepest level and back with keyboard', async () => {
+        const { user, toggleButton } = setupMenu();
+        await user.click(toggleButton);
+        await waitFor(async () => {
+          expect(screen.getByTestId('root-menu')).toBeVisible();
+          // jump in the menu
+          await user.keyboard('{ArrowDown}');
+        });
+
+        // Step 1: Open Web Clipboard submenu
+        await user.keyboard('{ArrowDown}{ArrowDown}{ArrowRight}');
+        await waitFor(() => {
+          expect(screen.getByTestId('web-clipboard-submenu')).toBeVisible();
+        });
+        expect(screen.getByRole('menuitem', { name: 'Google Cloud' })).toHaveFocus();
+
+        // Step 2: Open Deep Options submenu
+        await user.keyboard('{ArrowDown}{ArrowRight}');
+        await waitFor(() => {
+          expect(screen.getByRole('menu', { name: 'Deep Options' })).toBeVisible();
+        });
+        expect(screen.getByRole('menuitem', { name: 'Deep Item' })).toHaveFocus();
+
+        // Step 3: Close Deep Options submenu
+        await user.keyboard('{ArrowLeft}');
+        const deepOptionsTrigger = screen.getByRole('menuitem', { name: 'Deep Options' });
+        await waitFor(() => {
+          expect(screen.queryByRole('menu', { name: 'Deep Options' })).not.toBeInTheDocument();
+          expect(deepOptionsTrigger).toHaveFocus();
+        });
+
+        // Step 4: Close Web Clipboard submenu
+        await user.keyboard('{ArrowLeft}');
+        const webClipboardTrigger = screen.getByRole('menuitem', { name: 'Web Clipboard' });
+        await waitFor(() => {
+          expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+          expect(webClipboardTrigger).toHaveFocus();
+        });
+      });
+
+      it('traversing down to deepest level and back using mouse', async () => {
+        const { user, toggleButton } = setupMenu();
+        await user.click(toggleButton);
+        await waitFor(() => {
+          expect(screen.getByTestId('root-menu')).toBeVisible();
+        });
+        // Step 1: Open Web Clipboard submenu
+        const webClipboardTrigger = screen.getByRole('menuitem', { name: 'Web Clipboard' });
+        await user.hover(webClipboardTrigger);
+        await waitFor(() => {
+          expect(screen.getByTestId('web-clipboard-submenu')).toBeVisible();
+        });
+
+        // Step 2: Open Deep Options submenu
+        const deepOptionsTrigger = screen.getByRole('menuitem', { name: 'Deep Options' });
+        await user.hover(deepOptionsTrigger);
+        await waitFor(() => {
+          expect(screen.getByRole('menu', { name: 'Deep Options' })).toBeVisible();
+        });
+
+        // Step 3: Go in the deep options menu
+        const deepItem = screen.getByRole('menuitem', { name: 'Deep Item' });
+        await user.hover(deepItem);
+
+        // Step 4: Hover deep options trigger and expect submenu to not close
+        await user.hover(deepOptionsTrigger);
+        expect(screen.getByRole('menu', { name: 'Deep Options' })).toBeVisible();
+
+        // Step 5: Hover Google Cloud trigger and expect deep options submenu to close
+        const googleCloudTrigger = screen.getByRole('menuitem', { name: 'Google Cloud' });
+        await user.hover(googleCloudTrigger);
+        await waitFor(() => {
+          expect(screen.queryByRole('menu', { name: 'Deep Options' })).not.toBeInTheDocument();
+        });
+
+        // Step 6: Hover Cut trigger and expect Web Clipboard submenu to close
+        const cutTrigger = screen.getByRole('menuitem', { name: 'Cut' });
+        await user.hover(cutTrigger);
+        await waitFor(() => {
+          expect(screen.queryByRole('menu', { name: 'Web Clipboard' })).not.toBeInTheDocument();
+        });
+
+        // Finally, click out side and expect root menu to close
+        const backdrop = document.querySelector('[class*="MuiBackdrop-root"]');
+        if (!backdrop) throw new Error('Backdrop not found');
+        await user.click(backdrop);
+        await waitFor(() => {
+          expect(screen.queryByTestId('root-menu')).not.toBeInTheDocument();
+        });
+      });
+    });
+  });
+});

package/src/MultiLevelMenu/NestedMenuItem.tsx

@@ -0,0 +1,241 @@
+import type { FC, ReactNode, MouseEvent, KeyboardEvent } from 'react';
+import { Children, cloneElement, isValidElement, useCallback, useId, useRef, useState } from 'react';
+import Fade from '@mui/material/Fade';
+import type { MenuItemProps } from '@mui/material/MenuItem';
+import MenuItem from '@mui/material/MenuItem';
+import Divider from '@mui/material/Divider';
+import ArrowRightIcon from '@mui/icons-material/ArrowRight';
+import type { SvgIconComponent } from '@mui/icons-material';
+import { MenuList, Paper, Popper, Typography } from '@mui/material';
+import type { MultiLevelMenuItem } from './types';
+import { MenuItemContent, transitionConfig } from './common';
+
+type NestedMenuItemProps = MenuItemProps & {
+  label: ReactNode;
+  startIcon?: SvgIconComponent;
+  endIcon?: SvgIconComponent;
+  parentMenuClose: () => void;
+  children?: ReactNode;
+  items?: MultiLevelMenuItem[];
+};
+
+const isNodeInstance = (target: EventTarget | null): target is Node => target instanceof Node;
+
+export const NestedMenuItem: FC<NestedMenuItemProps> = props => {
+  const {
+    id: providedId,
+    label,
+    startIcon: StartIconComponent,
+    parentMenuClose,
+    children,
+    items,
+    endIcon: _,
+    ...menuItemProps
+  } = props;
+  const [subMenuAnchorEl, setSubMenuAnchorEl] = useState<null | HTMLElement>(null);
+  const open = Boolean(subMenuAnchorEl);
+  const menuItemRef = useRef<HTMLLIElement>(null);
+  const subMenuRef = useRef<HTMLDivElement>(null);
+  const generatedId = useId();
+  const menuItemId = providedId ?? `nested-menu-trigger-${generatedId}`;
+  const subMenuId = `${menuItemId}-submenu`;
+
+  const handleOpen = (event: MouseEvent<HTMLLIElement> | KeyboardEvent<HTMLLIElement>) => {
+    setSubMenuAnchorEl(event.currentTarget);
+  };
+
+  const handleClose = useCallback(() => {
+    setSubMenuAnchorEl(null);
+  }, []);
+
+  const renderChildren = Children.map(children, child => {
+    if (!isValidElement(child)) return child;
+
+    // Ensure we only process MUI MenuItem children
+    if (child.type === MenuItem) {
+      const childOnClick = (child.props as MenuItemProps).onClick;
+      // Merge any user-defined click logic with the submenu closing behavior.
+      const clonedOnClick = (event: MouseEvent<HTMLLIElement>) => {
+        childOnClick?.(event);
+        handleClose(); // Close the submenu
+        parentMenuClose();
+      };
+      return cloneElement(child, { onClick: clonedOnClick } as Partial<MenuItemProps>);
+    }
+    return child;
+  });
+
+  const renderItemsFromData = () => {
+    if (!items || items.length === 0) return null;
+
+    return items.map((item, index) => {
+      if (item.type === 'divider') {
+
+        return <Divider key={`divider-${index}`} />;
+      }
+
+      const {
+        type: __,
+        items: entryItems,
+        startIcon: NestedMenuItemStartIcon,
+        endIcon: NestedMenuItemEndIcon,
+        label: entryLabel,
+        onClick,
+        id,
+      } = item;
+      const entryId = id ?? `${menuItemId}-entry-${index}`;
+      const entryKey = `nested-entry-${entryId}`;
+      const entryLabelValue = entryLabel ?? entryId;
+
+      if (entryItems && entryItems.length > 0) {
+        return (
+          <NestedMenuItem
+            key={entryKey}
+            id={entryId}
+            label={entryLabelValue}
+            startIcon={NestedMenuItemStartIcon}
+            endIcon={NestedMenuItemEndIcon}
+            parentMenuClose={parentMenuClose}
+            items={entryItems}
+          />
+        );
+      }
+
+      const handleItemClick = (event: MouseEvent<HTMLLIElement>) => {
+        onClick?.(event);
+        handleClose();
+        parentMenuClose();
+      };
+
+      return (
+        <MenuItem key={entryKey} onClick={handleItemClick}>
+          <MenuItemContent>
+            {NestedMenuItemStartIcon ? <NestedMenuItemStartIcon /> : null}
+            <Typography sx={{ flex: 1 }}>{entryLabelValue}</Typography>
+            {NestedMenuItemEndIcon ? <NestedMenuItemEndIcon /> : null}
+          </MenuItemContent>
+        </MenuItem>
+      );
+    });
+  };
+
+  const renderedSubMenuItems = items && items.length > 0 ? renderItemsFromData() : renderChildren;
+
+  return (
+    <>
+      <MenuItem
+        data-testid={`${menuItemId}-trigger`}
+        id={menuItemId}
+        ref={menuItemRef}
+        onMouseEnter={handleOpen}
+        onMouseLeave={e => {
+          // CRITICAL FEATURE:
+          // Checking whether cursor left the menu item onto the related menu. If so, do not close.
+          // TODO(ege): There can be a timeout here before we execute closing to improve UX - in case user is not very precise with mouse.
+          if (isNodeInstance(e.relatedTarget) && subMenuRef.current?.contains(e.relatedTarget)) return;
+          // If the cursor leaves to anywhere else, close the submenu.
+          handleClose();
+        }}
+        onKeyDown={e => {
+          e.preventDefault();
+          if (e.key === 'ArrowLeft') {
+            handleClose();
+          }
+          if (e.key === 'ArrowRight' || e.key === 'Enter' || e.key === ' ') {
+            handleOpen(e);
+          }
+        }}
+        aria-haspopup='menu'
+        aria-controls={subMenuId}
+        aria-expanded={open ? 'true' : undefined}
+        {...menuItemProps}
+      >
+        <MenuItemContent>
+          {StartIconComponent ? <StartIconComponent /> : null}
+          <Typography sx={{ flex: 1 }}>{label}</Typography>
+          <ArrowRightIcon />
+        </MenuItemContent>
+      </MenuItem>
+
+      <Popper
+        data-testid={`${menuItemId}-submenu`}
+        open={open}
+        ref={subMenuRef}
+        anchorEl={subMenuAnchorEl}
+        transition
+        sx={{ zIndex: t => t.zIndex.modal + 1 }}
+        placement='right-start'
+        onKeyDown={e => {
+          if (e.key === 'ArrowLeft') {
+            e.preventDefault();
+            handleClose();
+            menuItemRef.current?.focus();
+          }
+          if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
+            e.preventDefault();
+            e.stopPropagation();
+          }
+        }}
+        onMouseLeave={e => {
+          // CRITICAL FEATURE:
+          // Checking whether cursor left the submenu onto the related trigger item. If so, do not close.
+          // TODO(ege): There can be a timeout here before we execute closing to improve UX - in case user is not very precise with mouse.
+          if (isNodeInstance(e.relatedTarget) && menuItemRef.current?.contains(e.relatedTarget)) return;
+          // If the cursor leaves to anywhere else, close the submenu.
+          handleClose();
+        }}
+      >
+        {({ TransitionProps }) => (
+          <Fade {...TransitionProps} timeout={transitionConfig.timeout}>
+            <Paper
+              elevation={2}
+              sx={{
+                borderRadius: 1,
+                bgcolor: 'background.default',
+              }}
+            >
+              <MenuList
+                autoFocusItem
+                id={subMenuId}
+                aria-labelledby={menuItemId}
+                role='menu'
+                onKeyDown={e => {
+                  if (e.key === 'ArrowLeft') {
+                    const { nativeEvent } = e as KeyboardEvent<HTMLUListElement> & {
+                      nativeEvent: KeyboardEvent & {
+                        // our custom flag to avoid duplicate handling in nested menus
+                        __nestedMenuArrowLeftHandled?: boolean;
+                      };
+                    };
+                    if (nativeEvent.__nestedMenuArrowLeftHandled) {
+                      // return early if we have already handled this event in a nested menu
+                      // prevents duplicate logic when the browser bubbles the same keypress through multiple nodes
+                      return;
+                    }
+                    if (!subMenuRef.current?.contains(e.target as Node)) {
+                      // confirm the event’s target is still inside this submenu;
+                      // if the keypress originated elsewhere, we don’t continue so other menus can handle it
+                      return;
+                    }
+                    // Mark this event as handled to prevent parent menus from also processing it
+                    nativeEvent.__nestedMenuArrowLeftHandled = true;
+                    e.preventDefault();
+                    e.stopPropagation();
+                    // immediately halt any other listeners so we have exclusive control now
+                    nativeEvent.stopImmediatePropagation();
+                    // close the sub menu
+                    handleClose();
+                    // move focus back to the parent MenuItem, letting the user continue navigation up the menu hierarchy
+                    menuItemRef.current?.focus();
+                  }
+                }}
+              >
+                {renderedSubMenuItems}
+              </MenuList>
+            </Paper>
+          </Fade>
+        )}
+      </Popper>
+    </>
+  );
+};

package/src/MultiLevelMenu/common.ts

@@ -0,0 +1,18 @@
+import { Stack, styled } from '@mui/material';
+import Fade from '@mui/material/Fade';
+
+export const transitionConfig = {
+  type: Fade,
+  timeout: { enter: 100, exit: 100 },
+};
+
+export const MenuItemContent = styled(Stack)(({ theme }) => ({
+  flexDirection: 'row',
+  alignItems: 'center',
+  gap: theme.spacing(1),
+  fontSize: theme.typography.body1.fontSize,
+  '& .MuiSvgIcon-root': {
+    fontSize: theme.typography.body2.fontSize,
+  },
+  padding: 0,
+}));