better-mui-menu 1.4.0 → 1.5.0

package/README.md

@@ -2,28 +2,27 @@
 
 [![CI](https://github.com/eggei/better-mui-menu/actions/workflows/ci.yml/badge.svg)](https://github.com/eggei/better-mui-menu/actions/workflows/ci.yml) [![Security](https://github.com/eggei/better-mui-menu/actions/workflows/security.yml/badge.svg)](https://github.com/eggei/better-mui-menu/actions/workflows/security.yml) [![coverage](https://codecov.io/gh/eggei/better-mui-menu/branch/main/graph/badge.svg)](https://codecov.io/gh/eggei/better-mui-menu) [![npm version](https://img.shields.io/npm/v/better-mui-menu.svg?color=brightgreen)](https://www.npmjs.com/package/better-mui-menu) [![npm downloads](https://img.shields.io/npm/dt/better-mui-menu.svg?color=informational)](https://www.npmjs.com/package/better-mui-menu) [![License: MIT](https://img.shields.io/npm/l/better-mui-menu.svg)](https://opensource.org/licenses/MIT)
 
-`better-mui-menu` is a lightweight drop-in for Material UI that keeps a normal `Menu` structure while adding nested menus and full keyboard accessibility so nothing breaks audits or expectations in an MUI app.
+`better-mui-menu` is a zero-dependency wrapper for Material UI Menu to support nested menus and full keyboard accessibility with **proper focus management**.
 
 ## Live demo
 
-Try it:
-
-[StackBlitz playground](https://stackblitz.com/edit/vitejs-vite-autejxh8?embed=1&file=src%2FMenuDemo.tsx&view=preview).
-
 [![Edit better-mui-menu-demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/9j2z7n)
 
+[Edit in StackBlitz](https://stackblitz.com/edit/vitejs-vite-autejxh8?embed=1&file=src%2FMenuDemo.tsx&view=preview)
+
 ![Menu demo preview](./app/demo/assets/bmm-demo.gif)
 
 ## Features
 
+- **Excellent Keyboard Navigation for Accessibility** – navigate with arrow keys, open submenus with right arrow or Enter, close them with left arrow or Escape, and have the menu stack stay in sync with focus.
 - **Unlimited nesting** – describe every submenu with an `items` array and `better-mui-menu` renders `NestedMenuItem` poppers that stay synchronized with their parents.
-- **Keyboard accessible** – arrow keys, Enter/Space, and Escape behave like desktop menus, while focus management and ARIA attributes make the tree readable by assistive tech.
+- **Customizable** – style your menu and menu items using MUI's Menu and MenuItem props.
 - **Data-driven API** – you keep work in a single `MenuItem[]` list; leaves, dividers, and nested branches all live alongside each other.
 
 ## Installation
 
 ```bash
-npm install better-mui-menu
+(yarn | npm | pnpm) install better-mui-menu
 ```
 
 Since the component renders Material UI primitives, also install the peer dependencies:
@@ -32,15 +31,9 @@ Since the component renders Material UI primitives, also install the peer depend
 npm install @mui/material @emotion/react @emotion/styled @mui/icons-material
 ```
 
-The `@mui/icons-material` peer is optional unless you use `startIcon`/`endIcon` helpers but we list it so consumers don’t need extra typings setup.
-
 ## Usage
 
 ```tsx
-import { useState } from 'react'
-import Button from '@mui/material/Button'
-import Cloud from '@mui/icons-material/Cloud'
-import Save from '@mui/icons-material/Save'
 import { Menu, type MenuItem } from 'better-mui-menu'
 
 const menuItems: MenuItem[] = [
@@ -52,7 +45,14 @@ const menuItems: MenuItem[] = [
   },
   { type: 'divider' },
   {
-    label: 'Cloud actions',
+    label: (
+      <Stack>
+        Cloud actions
+        <Typography variant="caption" color="text.secondary">
+          Requires internet connection
+        </Typography>
+      </Stack>
+    ),
     startIcon: <Cloud fontSize='small' sx={{ ml: 0.5 }} />,
     items: [
       { label: 'Upload', onClick: () => console.log('Upload') },
@@ -82,29 +82,12 @@ export function FileMenu() {
 
 ## Items shape
 
-`MenuItem` extends `@mui/material/MenuItemProps` (excluding `children`) so you can still pass `dense`, `disabled`, `divider`, `aria-selected`, etc. The `better-mui-menu` shape adds:
+`MenuItem` extends `@mui/material/MenuItemProps` (excluding `children`) so you can still pass `dense`, `disabled`, `aria-selected`, etc.
+The `better-mui-menu` adds:
 
 - `type?: 'item' | 'divider'` – render a `Divider` when `'divider'` is supplied.
 - `id?: string` – optional stable ID for ARIA attributes; one is generated automatically otherwise.
 - `label: ReactNode` – the label shown in the menu row.
 - `startIcon` / `endIcon` – pass either a `SvgIconComponent` (for example `Save`) or a JSX element (for example `<Save fontSize='large' sx={{ ml: 0.5 }} />`).
 - `items?: MenuItem[]` – nested entries that render as submenus.
-- `onClick?: MenuItemProps['onClick']` – leaves bubble clicks and close the menu stack so the consumer can handle the action.
-
-## Accessibility & interactions
-
-- Nested menus render in `Popper` instances positioned `right-start` from the trigger and fade in/out with a shared transition helper.
-- Hover keeps a submenu open while the mouse moves between trigger and popper; leaving the area closes the branch.
-- Keyboard navigation covers `ArrowUp`/`ArrowDown` through siblings, `ArrowRight` or `Enter/Space` to open children, `ArrowLeft` to back out, and `Escape` to dismiss every layer.
-- ARIA helpers (`aria-haspopup`, `aria-controls`, `aria-expanded`, `aria-labelledby`) are wired automatically so assistive tech understands the structure.
-
-## Development
-
-The library lives inside `package/better-mui-menu`.
-
-- `npm run dev` – rebuilds `src` into `dist` with `tsup --watch`.
-- `npm run build` – creates production bundles ready for publication.
-- `npm run test` – runs the Jest suite located at `src/**/*.test.{ts,tsx}`.
-- `npm run test:coverage` – runs tests with coverage and writes reports to `coverage/`.
-
-From the repository root you can use `npm run dev:lib` and `npm run dev:demo` together so the demo app consumes the rebuilt workspace link. Keep `npm run dev` (or `npm run build`) running before refreshing the demo because the Vite app imports the package via `file:`.
+- `onClick?: MenuItemProps['onClick']` – callback function when the menu item is clicked.

package/dist/index.cjs

@@ -155,6 +155,9 @@ var NestedMenuItem = (props) => {
       if (item.type === "divider") {
         return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_material3.Divider, {}, `divider-${index}`);
       }
+      if (item.type === "header") {
+        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_material3.ListSubheader, { children: item.label }, `header-${index}`);
+      }
       const {
         type: __,
         items: entryItems,
@@ -301,6 +304,9 @@ function Menu({ items, elevation = DEFAULT_ELEVATION, ...rest }) {
     if (item.type === "divider") {
       return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_material4.Divider, {}, `divider-${index}`);
     }
+    if (item.type === "header") {
+      return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_material4.ListSubheader, { children: item.label }, `header-${index}`);
+    }
     const {
       type: _,
       id,

package/dist/index.d.cts

@@ -4,20 +4,25 @@ import React, { ReactNode, ReactElement } from 'react';
 import { SvgIconComponent } from '@mui/icons-material';
 
 type MenuIcon = SvgIconComponent | ReactElement;
-type MenuItemBase = {
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | undefined;
+};
+type MenuDividerItem = {
     type: 'divider';
-} | {
+} & DataAttributes;
+type MenuHeaderItem = {
+    type: 'header';
+    label: ReactNode;
+} & DataAttributes;
+type MenuActionItem = {
     type?: 'item';
     id?: string;
     label: ReactNode;
     startIcon?: MenuIcon;
     endIcon?: MenuIcon;
     items?: MenuItem[];
-};
-type DataAttributes = {
-    [K in `data-${string}`]?: string | number | boolean | undefined;
-};
-type MenuItem = MenuItemBase & Omit<MenuItemProps, 'children'> & DataAttributes;
+} & Omit<MenuItemProps, 'children' | 'type'> & DataAttributes;
+type MenuItem = MenuDividerItem | MenuHeaderItem | MenuActionItem;
 
 type Props = {
     items: MenuItem[];

package/dist/index.d.ts

@@ -4,20 +4,25 @@ import React, { ReactNode, ReactElement } from 'react';
 import { SvgIconComponent } from '@mui/icons-material';
 
 type MenuIcon = SvgIconComponent | ReactElement;
-type MenuItemBase = {
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | undefined;
+};
+type MenuDividerItem = {
     type: 'divider';
-} | {
+} & DataAttributes;
+type MenuHeaderItem = {
+    type: 'header';
+    label: ReactNode;
+} & DataAttributes;
+type MenuActionItem = {
     type?: 'item';
     id?: string;
     label: ReactNode;
     startIcon?: MenuIcon;
     endIcon?: MenuIcon;
     items?: MenuItem[];
-};
-type DataAttributes = {
-    [K in `data-${string}`]?: string | number | boolean | undefined;
-};
-type MenuItem = MenuItemBase & Omit<MenuItemProps, 'children'> & DataAttributes;
+} & Omit<MenuItemProps, 'children' | 'type'> & DataAttributes;
+type MenuItem = MenuDividerItem | MenuHeaderItem | MenuActionItem;
 
 type Props = {
     items: MenuItem[];

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/Menu/index.tsx
-import { Divider as Divider2, Menu as MuiMenu } from "@mui/material";
+import { Divider as Divider2, ListSubheader as ListSubheader2, Menu as MuiMenu } from "@mui/material";
 import { useId as useId2 } from "react";
 
 // src/Menu/NestedMenuItem.tsx
@@ -15,7 +15,7 @@ var ArrowRight_default = createSvgIcon(/* @__PURE__ */ _jsx("path", {
 }), "ArrowRight");
 
 // src/Menu/NestedMenuItem.tsx
-import { Divider, Fade as Fade2, MenuItem as MuiMenuItem2, MenuList, Paper, Popper } from "@mui/material";
+import { Divider, Fade as Fade2, ListSubheader, MenuItem as MuiMenuItem2, MenuList, Paper, Popper } from "@mui/material";
 
 // src/Menu/MenuEntry.tsx
 import { forwardRef, isValidElement } from "react";
@@ -129,6 +129,9 @@ var NestedMenuItem = (props) => {
       if (item.type === "divider") {
         return /* @__PURE__ */ jsx2(Divider, {}, `divider-${index}`);
       }
+      if (item.type === "header") {
+        return /* @__PURE__ */ jsx2(ListSubheader, { children: item.label }, `header-${index}`);
+      }
       const {
         type: __,
         items: entryItems,
@@ -275,6 +278,9 @@ function Menu({ items, elevation = DEFAULT_ELEVATION, ...rest }) {
     if (item.type === "divider") {
       return /* @__PURE__ */ jsx3(Divider2, {}, `divider-${index}`);
     }
+    if (item.type === "header") {
+      return /* @__PURE__ */ jsx3(ListSubheader2, { children: item.label }, `header-${index}`);
+    }
     const {
       type: _,
       id,

package/package.json

@@ -9,7 +9,7 @@
   "bugs": {
     "url": "https://github.com/eggei/better-mui-menu/issues"
   },
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "sideEffects": false,
   "files": [