@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/CascadingMenu.js

@@ -1,56 +1,460 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useState } from 'react';
-import ChevronRight from '@mui/icons-material/ChevronRight';
-import { Divider, ListItemIcon, ListItemText, ListSubheader, Menu, MenuItem, } from '@mui/material';
-import CascadingMenuHelpIconButton from "./CascadingMenuHelpIconButton.js";
-import HoverMenu from "./HoverMenu.js";
-import { MenuItemEndDecoration } from "./MenuItems.js";
-function labelToTestId(label) {
-    if (typeof label === 'string') {
-        return label.toLowerCase().replace(/\s+/g, '_');
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, memo, use, useEffect, useMemo, useState } from 'react';
+import { Divider, ListItemIcon, ListItemText, ListSubheader, Menu, MenuItem, Tooltip, } from '@mui/material';
+import { observer } from 'mobx-react';
+import { makeStyles } from '../util/tss-react/index.js';
+import HoverMenu from './HoverMenu.js';
+import { MenuItemTrailing } from './MenuItemTrailing.js';
+import { resolveSubMenu, staysOpenOnClick } from './MenuTypes.js';
+import { hasMenuItemAdornment } from './menuItemAdornment.js';
+import { isAimedAtPanel } from './submenuAim.js';
+// Compact section headers so tall menus (e.g. a display's flat "Show..."
+// settings list with several subHeader-separated radio groups) stay short.
+// Row heights are left at the MUI default.
+const useStyles = makeStyles()(theme => ({
+    subHeader: {
+        lineHeight: '1.8em',
+        fontSize: '0.7rem',
+        textTransform: 'uppercase',
+        letterSpacing: '0.05em',
+        color: theme.palette.text.secondary,
+        // doubles as the section divider: a rule above the header groups the rows
+        // beneath it without spending a separate divider row
+        borderTop: `1px solid ${theme.palette.divider}`,
+        marginTop: 4,
+    },
+    // a leading subHeader has no rows above it to divide from, so the rule and
+    // its space would float against the menu's top edge
+    leadingSubHeader: {
+        borderTopWidth: 0,
+        marginTop: 0,
+    },
+}));
+const CascadingMenuContext = createContext(undefined);
+function useCascadingMenu() {
+    const shared = use(CascadingMenuContext);
+    if (!shared) {
+        throw new Error('menu row rendered outside a CascadingMenu');
     }
-    return undefined;
+    return shared;
 }
-function CascadingSubmenu({ title, Icon, inset, menuItems, onMenuItemClick, closeAfterItemClick, onCloseRoot, isOpen, onOpen, onClose, }) {
-    const [anchorEl, setAnchorEl] = useState(null);
-    const testId = labelToTestId(title);
-    return (_jsxs(_Fragment, { children: [_jsxs(MenuItem, { ref: setAnchorEl, "data-testid": testId ? `cascading-submenu-${testId}` : undefined, onMouseOver: onOpen, onFocus: onOpen, onClick: onOpen, children: [Icon ? (_jsx(ListItemIcon, { children: _jsx(Icon, {}) })) : null, _jsx(ListItemText, { primary: title, inset: inset }), _jsx(ChevronRight, {})] }), _jsx(HoverMenu, { open: isOpen, anchorEl: anchorEl, onClose: onClose, anchorOrigin: { vertical: 'top', horizontal: 'right' }, transformOrigin: { vertical: 'top', horizontal: 'left' }, children: _jsx(CascadingMenuList, { closeAfterItemClick: closeAfterItemClick, onMenuItemClick: onMenuItemClick, menuItems: menuItems, onCloseRoot: onCloseRoot }) })] }));
-}
-function CascadingMenuList({ onMenuItemClick, closeAfterItemClick, menuItems, onCloseRoot, }) {
-    const [openSubmenuIdx, setOpenSubmenuIdx] = useState();
-    const closeSubmenu = () => {
-        setOpenSubmenuIdx(undefined);
+/**
+ * How long a change deferred by the aim cone waits before it happens anyway.
+ *
+ * Only a pointer INSIDE the cone is ever deferred, and every further move
+ * inside it re-arms this — so it expires only once the pointer has stopped
+ * while still aimed at the panel, which is someone who set out for the submenu
+ * and changed their mind. A pointer that keeps traveling reaches the panel; one
+ * that veers off leaves the cone and is acted on at once. That is what lets
+ * this be short: it is a backstop for a stalled pointer, not the mechanism.
+ *
+ * Read it as the pause budget, because that is what it is once the cone is
+ * doing the work: whoever changes it is choosing how long a pointer may stop
+ * part way to a submenu before losing it, not how fast the menu answers. The
+ * paths a user feels as slow — veering off, heading straight down the list —
+ * never reach this timer at all.
+ *
+ * What stops it going shorter still is that a moving pointer re-arms it from
+ * mousemove, and mousemove stops arriving while the main thread is busy — a
+ * track finishing a fetch and repainting behind the menu is enough. Below the
+ * length of a stall like that, the panel would close under a pointer that never
+ * paused, which is the bug this whole mechanism exists to prevent, arriving by
+ * a different route. The cone is what made the number small; it cannot make it
+ * zero.
+ */
+const submenuAimGraceMs = 120;
+/**
+ * The hover intent that moves which submenu of ONE list is open.
+ *
+ * A click or ArrowRight says where the pointer meant to go and acts at once. A
+ * hover is read against {@link isAimedAtPanel}: outside the cone it acts at
+ * once too, and inside it defers, because the rows between a submenu row and
+ * its panel are exactly the ones a pointer on its way there has to cross.
+ *
+ * Built once per list, so every row gets the same handlers and a row whose
+ * open state didn't change skips the re-render a hover triggers.
+ */
+function createSubmenuHover(setOpenSubmenu) {
+    let openKey;
+    // the open panel's paper, so the cone has a real edge to open onto. Written
+    // by whichever CascadingSubmenu is open and cleared as it closes, so at most
+    // one submenu of this list ever owns it
+    const panelRef = { current: null };
+    // where the pointer was when the open panel opened — the cone's tip
+    let apex;
+    // where the pointer last was while a panel is up. A row that slides under a
+    // resting pointer — the menu grew a fetch later and MUI moved it back into
+    // the viewport, or rows landed above — gets a mouseenter at that same point,
+    // and it is the layout that moved, not the pointer, so it is no hover.
+    let lastPoint;
+    let pending;
+    const cancelPending = () => {
+        if (pending) {
+            clearTimeout(pending.timer);
+            pending = undefined;
+        }
+    };
+    const commit = (key, point) => {
+        cancelPending();
+        apex = key === undefined ? undefined : point;
+        lastPoint = point;
+        openKey = key;
+        setOpenSubmenu(key);
+    };
+    const restingUnderOpenPanel = (point) => openKey !== undefined &&
+        lastPoint !== undefined &&
+        point.x === lastPoint.x &&
+        point.y === lastPoint.y;
+    // 'unmeasured' is its own answer, not a lenient 'inside': a cone pointing at
+    // nothing would call every row crossed a veer-off, and a move handler that
+    // re-armed on it would hold the panel open for as long as the pointer kept
+    // moving anywhere at all
+    const aimAt = (point) => {
+        const panel = panelRef.current;
+        if (!panel || !apex) {
+            return 'unmeasured';
+        }
+        const rect = panel.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+            return 'unmeasured';
+        }
+        return isAimedAtPanel(point, apex, rect) ? 'inside' : 'outside';
     };
-    const hasIcon = menuItems.some(m => 'icon' in m && m.icon);
+    const defer = (key, point) => {
+        cancelPending();
+        pending = {
+            key,
+            point,
+            timer: setTimeout(() => {
+                commit(key, point);
+            }, submenuAimGraceMs),
+        };
+    };
+    // the pointer arrived at a row wanting `key` open — undefined from a row with
+    // no submenu, i.e. "close whatever is"
+    const hoverSubmenu = (key, point) => {
+        if (key === openKey) {
+            cancelPending();
+        }
+        else if (restingUnderOpenPanel(point)) {
+            return;
+        }
+        else if (openKey === undefined || aimAt(point) === 'outside') {
+            // nothing to protect, or a pointer that was never heading for the open
+            // panel: either way there is nothing to wait for
+            commit(key, point);
+        }
+        else {
+            defer(key, point);
+        }
+    };
+    return {
+        panelRef,
+        setSubmenu: commit,
+        cancelPending,
+        hoverSubmenu,
+        // every row a pointer can rest on asks for the open panel to go away; only
+        // a row that owns a submenu, or the panel itself, keeps one up
+        closeOnHover: (event) => {
+            hoverSubmenu(undefined, { x: event.clientX, y: event.clientY });
+        },
+        // Watched only while a panel is up, and only a deferred change is waiting
+        // on it. A row's own hover cannot answer this alone: the pointer can leave
+        // the cone without ever crossing into another row, by turning around inside
+        // the one it is already on.
+        onPointerMove: (event) => {
+            lastPoint = { x: event.clientX, y: event.clientY };
+            const deferred = pending;
+            if (!deferred) {
+                return;
+            }
+            const aim = aimAt({ x: event.clientX, y: event.clientY });
+            if (aim === 'outside') {
+                commit(deferred.key, deferred.point);
+            }
+            else if (aim === 'inside') {
+                // still traveling, so the grace starts over — it is there to catch a
+                // pointer that stops, and this one has not
+                defer(deferred.key, deferred.point);
+            }
+        },
+    };
+}
+function useSubmenuHover() {
+    const [openSubmenu, setOpenSubmenu] = useState();
+    const [hover] = useState(() => createSubmenuHover(setOpenSubmenu));
+    useEffect(() => hover.cancelPending, [hover]);
+    useEffect(() => {
+        if (openSubmenu === undefined) {
+            return;
+        }
+        document.addEventListener('mousemove', hover.onPointerMove);
+        return () => {
+            document.removeEventListener('mousemove', hover.onPointerMove);
+        };
+    }, [openSubmenu, hover]);
+    return { openSubmenu, hover };
+}
+// One key per row, unique WITHIN the level — the React key, and for a submenu row
+// also the identity of "which submenu is open".
+//
+// A row is named by its `id`, or by its label where it has none. Deliberately not
+// the array index: the items are re-derived on every observable change (a checkbox
+// toggle can add or drop a row above), so an index-keyed "open" flag would follow
+// the position rather than the submenu and the open panel would jump to whichever
+// row landed at that index.
+//
+// A NAME THAT REPEATS TAKES AN OCCURRENCE SUFFIX, so the level's keys are unique
+// whatever its rows are called. Two ways a name repeats, and both shipped: a
+// `label` is a `React.ReactNode`, so an element interpolates to `[object Object]`
+// and a menu of them named every row the same — the favorites and recently-used
+// track dropdowns did — and a label can simply be shared, since a list may dedupe
+// on something other than its text, as the recent locations dedupe on the
+// location. Handling it here rather than asking every caller for an `id` means
+// neither case can reach React as one key for several rows; only the rows that
+// genuinely repeat depend on their order among each other, and `id` is then a way
+// to keep a row's identity across a reorder rather than a correctness obligation.
+//
+// The kind prefix is the render branch below: a submenu row and a clickable row
+// sharing a label draw different components, which must not share a key.
+function rowKeys(items) {
+    const seen = new Map();
+    return items.map(item => {
+        const kind = 'subMenu' in item
+            ? 'subMenu'
+            : item.type === 'divider' || item.type === 'subHeader'
+                ? item.type
+                : item.type === 'custom'
+                    ? 'custom'
+                    : 'menuitem';
+        // a divider has no identity beyond its position among the other dividers.
+        // `'id' in item` rather than `item.id`: a divider and a subHeader are their
+        // own interfaces and carry neither an `id` nor, for the divider, a label
+        const name = item.type === 'divider'
+            ? ''
+            : ('id' in item && item.id) || `${item.label}`;
+        const base = `${kind}-${name}`;
+        const seenBefore = seen.get(base) ?? 0;
+        seen.set(base, seenBefore + 1);
+        // The count LEADS, and every row carries one. A trailing suffix is drawn
+        // from the same alphabet as the label it disambiguates, so `x#1` beside two
+        // rows called `x` collided all over again — the second `x` took the first
+        // one's key. Leading, the count is the digits before the first `-` and the
+        // base is everything after, and `kind` always starts with a letter, so no
+        // two (count, base) pairs can spell one key.
+        return `${seenBefore}-${base}`;
+    });
+}
+// Where the aim cone's tip goes for a submenu opened from the keyboard, which
+// has no pointer to put it at: the middle of the row, so a pointer picked up
+// afterwards is judged by a cone the same shape hovering the row would have
+// given it. The row's leading edge, not its trailing one — a tip level with the
+// panel's near edge leaves no gap to open a cone across.
+function rowCentre(row) {
+    if (!row) {
+        return undefined;
+    }
+    const rect = row.getBoundingClientRect();
+    return { x: (rect.left + rect.right) / 2, y: (rect.top + rect.bottom) / 2 };
+}
+// Build a `cascading-<kind>-<label>` data-testid, or undefined for non-string
+// labels that can't be slugified
+function makeTestId(kind, label) {
+    return typeof label === 'string'
+        ? `cascading-${kind}-${label.toLowerCase().replaceAll(/\s+/g, '_')}`
+        : undefined;
+}
+// Leading icon slot shared by submenu rows and clickable rows; renders nothing
+// when the item has no icon (the row insets instead to stay column-aligned).
+function MenuItemLeadingIcon({ Icon, }) {
+    return Icon ? (_jsx(ListItemIcon, { children: _jsx(Icon, {}) })) : null;
+}
+// Which decoration columns the menu needs, computed menu-wide (true if ANY row
+// needs it) so every row reserves matching slots and the decorations stack into
+// aligned columns down the menu. Per list, so a submenu's own rows answer it for
+// themselves. `hasIcon` is the leading column; `columns` is the trailing stack
+// `MenuItemTrailing` draws for both row kinds, and every predicate below counts
+// submenu rows and clickable rows alike because both draw that stack.
+function getMenuColumnFlags(menuItems) {
+    // a disabled row surfaces its help as a hover tooltip instead of the "?"
+    // button (see DisabledTooltip), so it must not claim the column either — or a
+    // menu whose only help row is disabled reserves a spacer on every row for a
+    // button that never renders
     const hasCheckboxOrRadioWithHelp = menuItems.some(m => (m.type === 'checkbox' || m.type === 'radio') &&
+        m.helpText &&
+        !m.disabled);
+    const hasEndAdornment = menuItems.some(m => hasMenuItemAdornment(m));
+    // a single row carrying both a help "?" and a trailing adornment (e.g. pin) is
+    // the only case that genuinely needs help and adornment in separate columns
+    const hasRowWithHelpAndAdornment = menuItems.some(m => hasMenuItemAdornment(m) &&
         'helpText' in m &&
-        m.helpText);
-    const sortedItems = menuItems.toSorted((a, b) => (b.priority || 0) - (a.priority || 0));
+        m.helpText &&
+        !('disabled' in m && m.disabled));
+    return {
+        hasIcon: menuItems.some(m => 'icon' in m && m.icon),
+        columns: {
+            hasCheckboxOrRadioWithHelp,
+            hasEndAdornment,
+            // Gated on a submenu row that actually draws help, not on there being a
+            // submenu at all: the reservation exists to pull the clickable rows' "?"
+            // into the column a chevron pushes a submenu row's "?" out of. In a menu
+            // where no submenu row has help there is nothing to line up with, and
+            // reserving it there would only unalign a checkbox glyph from the chevron
+            // it currently sits level with.
+            hasSubmenuWithHelp: menuItems.some(m => 'subMenu' in m && m.helpText && !m.disabled),
+            // when help and adornment never collide on one row, they collapse into
+            // one shared trailing column instead of each claiming its own, so a menu
+            // mixing help-only and pin-only rows doesn't reserve a wasted third
+            // column
+            sharedActionColumn: hasCheckboxOrRadioWithHelp &&
+                hasEndAdornment &&
+                !hasRowWithHelpAndAdornment,
+        },
+    };
+}
+// Renders arbitrary React content (e.g. a slider) as a plain list row, not a
+// MenuItem: no click-to-close. Pointer/key events are kept local: the menu is
+// portaled in the DOM but is still a React descendant of the view, so without
+// this a slider drag bubbles (via React's synthetic-event tree) into the LGV's
+// click-drag side-scroll, and arrow-key nudging gets stolen by the menu's own
+// arrow navigation.
+//
+// Escape is the exception, and has to be: MUI's Modal reads it off the same
+// React tree, so a row that swallowed every key left the menu with no way out
+// for anyone whose focus was inside the slider.
+function CustomMenuRow({ item, onHover, }) {
+    const { onCloseRoot } = useCascadingMenu();
+    return (_jsx("li", { style: { padding: '4px 16px' }, onMouseEnter: onHover, onMouseDown: e => {
+            e.stopPropagation();
+        }, onKeyDown: e => {
+            if (e.key !== 'Escape') {
+                e.stopPropagation();
+            }
+        }, children: item.render(onCloseRoot) }));
+}
+// A disabled MenuItem has pointer-events:none, so a Tooltip placed directly on
+// it never fires; the span wrapper (per MUI guidance) restores hover. Disabled
+// rows aren't keyboard-focusable, so the extra wrapper doesn't affect menu
+// navigation. Renders children untouched unless the item is disabled and has
+// disabledHelpText.
+function DisabledTooltip({ item, children, }) {
+    return item.disabled && item.disabledHelpText ? (_jsx(Tooltip, { title: item.disabledHelpText, placement: "left", children: _jsx("span", { children: children }) })) : (children);
+}
+// One submenu row: label (with optional leading icon), the same trailing
+// decorations a clickable row draws, and the panel it opens.
+//
+// A submenu row carries its own `helpText` — for the question the rows inside it
+// are answers to, which an option table of individually-helped entries still
+// leaves nowhere to state — and its own trailing adornment (a color swatch, a
+// toggle), whose content stops its own click so using it doesn't also open the
+// submenu. Both go through `MenuItemTrailing`, so they land in the columns the
+// clickable rows reserve rather than in a hand-assembled copy of them.
+const CascadingSubmenu = memo(function CascadingSubmenu({ item, itemKey, inset, columns, open, hover, onNavigateBack, }) {
+    const { zIndex } = useCascadingMenu();
+    const [anchorEl, setAnchorEl] = useState(null);
+    // a rebuild can disable the row while its panel is up, and a disabled row has
+    // no way left to close it
+    const isOpen = open && !item.disabled;
+    return (_jsxs(_Fragment, { children: [_jsx(DisabledTooltip, { item: item, children: _jsxs(MenuItem, { ref: setAnchorEl, "data-testid": makeTestId('submenu', item.label), disabled: item.disabled, "aria-haspopup": "menu", "aria-expanded": isOpen, 
+                    // keeps the panel visually attached to the row it hangs off: that
+                    // row's own hover highlight is gone the moment the pointer moves
+                    // into the panel. Presentational on a `menuitem` — MUI derives
+                    // aria-checked from `selected` only for the checkbox/radio roles.
+                    selected: isOpen, onMouseEnter: e => {
+                        hover.hoverSubmenu(itemKey, { x: e.clientX, y: e.clientY });
+                    }, onClick: e => {
+                        hover.setSubmenu(itemKey, { x: e.clientX, y: e.clientY });
+                    }, onKeyDown: e => {
+                        if (e.key === 'ArrowRight') {
+                            hover.setSubmenu(itemKey, rowCentre(anchorEl));
+                        }
+                        else if (e.key === 'ArrowLeft') {
+                            e.stopPropagation();
+                            onNavigateBack?.();
+                        }
+                    }, children: [_jsx(MenuItemLeadingIcon, { Icon: item.icon }), _jsx(ListItemText, { primary: item.label, inset: inset }), _jsx(MenuItemTrailing, { item: item, columns: columns })] }) }), isOpen ? (_jsx(HoverMenu, { anchorEl: anchorEl, anchorOrigin: { vertical: 'top', horizontal: 'right' }, transformOrigin: { vertical: 'top', horizontal: 'left' }, zIndex: zIndex, 
+                // the pointer completed the trip, so drop the close a row it crossed
+                // on the way scheduled
+                onMouseEnter: hover.cancelPending, paperRef: hover.panelRef, onClose: () => {
+                    hover.setSubmenu(undefined);
+                }, children: _jsx(SubMenuList, { item: item, onNavigateBack: () => {
+                        hover.setSubmenu(undefined);
+                        anchorEl?.focus();
+                    } }) })) : null] }));
+});
+// Resolves the rows inside the panel, which mounts only while it is open:
+// a function-form `subMenu` is not called by listing the parent menu. An
+// observer so the observables that builder reads re-render the open panel, the
+// way an array built in the root observer's render already did.
+const SubMenuList = observer(function SubMenuList({ item, onNavigateBack, }) {
+    return (_jsx(CascadingMenuList, { menuItems: resolveSubMenu(item), onNavigateBack: onNavigateBack }));
+});
+// One clickable menu row: label (with optional leading icon) plus its trailing
+// value/help/adornment decorations. The menu-wide `columns` flags let every row
+// reserve matching decoration slots so the columns line up down the menu.
+const CascadingMenuItem = memo(function CascadingMenuItem({ item, inset, columns, onNavigateBack, onHover, }) {
+    const { closeAfterItemClick, onMenuItemClick, onCloseRoot } = useCascadingMenu();
+    return (_jsx(DisabledTooltip, { item: item, children: _jsxs(MenuItem, { "data-testid": makeTestId('menuitem', item.label), disabled: item.disabled, 
+            // A checkbox or radio row states its own value. The glyph
+            // `MenuItemEndDecoration` swaps is an `aria-hidden` icon, so without
+            // these a screen reader reads "Curved lines" identically whether the
+            // setting is on or off, and a test has no way to ask but the MUI icon's
+            // internal testid.
+            role: item.type === 'checkbox'
+                ? 'menuitemcheckbox'
+                : item.type === 'radio'
+                    ? 'menuitemradio'
+                    : undefined, "aria-checked": item.type === 'checkbox' || item.type === 'radio'
+                ? item.checked
+                : undefined, onClick: () => {
+                // onCloseRoot runs before the callback, so item.onClick must NOT read
+                // model state that closing clears (e.g. a right-click menu's ephemeral
+                // hit/context fields): capture that state when the menu items are
+                // built, not live inside onClick.
+                if (closeAfterItemClick && !staysOpenOnClick(item)) {
+                    onCloseRoot();
+                }
+                onMenuItemClick(item.onClick);
+            }, onMouseEnter: onHover, onKeyDown: e => {
+                if (e.key === 'ArrowLeft') {
+                    e.stopPropagation();
+                    onNavigateBack?.();
+                }
+            }, children: [_jsx(MenuItemLeadingIcon, { Icon: item.icon }), _jsx(ListItemText, { primary: item.label, secondary: item.subLabel, inset: inset }), _jsx(MenuItemTrailing, { item: item, columns: columns })] }) }));
+});
+function CascadingMenuList({ menuItems, onNavigateBack, }) {
+    const { classes, cx } = useStyles();
+    const { openSubmenu, hover } = useSubmenuHover();
+    const { closeOnHover } = hover;
+    const { hasIcon, columns } = useMemo(() => getMenuColumnFlags(menuItems), [menuItems]);
+    const sortedItems = useMemo(() => menuItems.toSorted((a, b) => (b.priority ?? 0) - (a.priority ?? 0)), [menuItems]);
+    // keyed after the sort, so an occurrence suffix counts up the level in the
+    // order it is drawn
+    const keys = useMemo(() => rowKeys(sortedItems), [sortedItems]);
     return (_jsx(_Fragment, { children: sortedItems.map((item, idx) => {
+            const key = keys[idx];
             if ('subMenu' in item) {
-                return (_jsx(CascadingSubmenu, { title: item.label, Icon: item.icon, inset: hasIcon && !item.icon, onMenuItemClick: onMenuItemClick, menuItems: item.subMenu, closeAfterItemClick: closeAfterItemClick, onCloseRoot: onCloseRoot, isOpen: openSubmenuIdx === idx, onOpen: () => {
-                        setOpenSubmenuIdx(idx);
-                    }, onClose: closeSubmenu }, `subMenu-${item.label}-${idx}`));
+                return (_jsx(CascadingSubmenu, { itemKey: key, item: item, inset: hasIcon && !item.icon, columns: columns, open: openSubmenu === key, hover: hover, onNavigateBack: onNavigateBack }, key));
             }
             if (item.type === 'divider') {
-                return _jsx(Divider, { component: "li" }, `divider-${idx}`);
+                return _jsx(Divider, { component: "li" }, key);
             }
             if (item.type === 'subHeader') {
-                return (_jsx(ListSubheader, { children: item.label }, `subHeader-${item.label}-${idx}`));
-            }
-            const actionItem = item;
-            const helpText = actionItem.helpText;
-            const isCheckOrRadio = actionItem.type === 'checkbox' || actionItem.type === 'radio';
-            const itemTestId = labelToTestId(actionItem.label);
-            return (_jsxs(MenuItem, { "data-testid": itemTestId ? `cascading-menuitem-${itemTestId}` : undefined, disabled: Boolean(actionItem.disabled), onClick: event => {
-                    if (closeAfterItemClick) {
-                        onCloseRoot();
-                    }
-                    onMenuItemClick(event, actionItem.onClick);
-                }, onMouseOver: closeSubmenu, children: [actionItem.icon ? (_jsx(ListItemIcon, { children: _jsx(actionItem.icon, {}) })) : null, _jsx(ListItemText, { primary: actionItem.label, secondary: actionItem.subLabel, inset: hasIcon && !actionItem.icon }), _jsx("div", { style: { flexGrow: 1, minWidth: 10 } }), isCheckOrRadio ? (_jsx(MenuItemEndDecoration, { type: actionItem.type, checked: actionItem.checked, disabled: actionItem.disabled })) : null, helpText ? (_jsx(CascadingMenuHelpIconButton, { helpText: helpText, label: actionItem.label })) : isCheckOrRadio && hasCheckboxOrRadioWithHelp ? (_jsx("div", { style: { marginLeft: 4, padding: 4, width: 28, height: 28 } })) : null] }, `${actionItem.label}-${idx}`));
+                return (_jsx(ListSubheader, { className: cx(classes.subHeader, idx === 0 && classes.leadingSubHeader), onMouseEnter: closeOnHover, children: item.label }, key));
+            }
+            if (item.type === 'custom') {
+                return _jsx(CustomMenuRow, { item: item, onHover: closeOnHover }, key);
+            }
+            return (_jsx(CascadingMenuItem, { item: item, inset: hasIcon && !item.icon, columns: columns, onNavigateBack: onNavigateBack, onHover: closeOnHover }, key));
         }) }));
 }
-export default function CascadingMenu({ onMenuItemClick, closeAfterItemClick = true, menuItems, open, onClose, anchorEl, anchorOrigin, transformOrigin, anchorReference, anchorPosition, slotProps, marginThreshold, style, }) {
+const CascadingMenu = observer(function CascadingMenu({ onMenuItemClick, closeAfterItemClick = true, menuItems, open, onClose, anchorEl, anchorOrigin, transformOrigin, anchorReference, anchorPosition, style, }) {
     const items = Array.isArray(menuItems) ? menuItems : menuItems();
-    return (_jsx(Menu, { anchorEl: anchorEl, open: open, onClose: onClose, anchorOrigin: anchorOrigin, transformOrigin: transformOrigin, anchorReference: anchorReference, anchorPosition: anchorPosition, slotProps: slotProps, marginThreshold: marginThreshold ?? undefined, style: style, children: _jsx(CascadingMenuList, { menuItems: items, closeAfterItemClick: closeAfterItemClick, onMenuItemClick: onMenuItemClick, onCloseRoot: onClose }) }));
-}
+    return (_jsx(Menu, { anchorEl: anchorEl, open: open, onClose: onClose, anchorOrigin: anchorOrigin, transformOrigin: transformOrigin, anchorReference: anchorReference, anchorPosition: anchorPosition, style: style, children: _jsx(CascadingMenuContext, { value: {
+                closeAfterItemClick,
+                onMenuItemClick,
+                onCloseRoot: onClose,
+                zIndex: style?.zIndex,
+            }, children: _jsx(CascadingMenuList, { menuItems: items }) }) }));
+});
+export default CascadingMenu;

package/esm/ui/CascadingMenuButton.d.ts

@@ -1,26 +1,24 @@
 import type { MenuItemsGetter } from './CascadingMenu.tsx';
-declare function CascadingMenuButton({ children, menuItems, closeAfterItemClick, stopPropagation, disabled, setOpen, ButtonComponent, onClick: onClickExtra, anchorOrigin, transformOrigin, marginThreshold, ...rest }: {
+import type { MenuItemClickHandler } from './MenuTypes.ts';
+import type { PopoverOrigin } from '@mui/material';
+declare function CascadingMenuButton({ children, menuItems, closeAfterItemClick, stopPropagation, disabled, setOpen, ButtonComponent, onClick: onClickExtra, onMenuItemClick, anchorOrigin, transformOrigin, tooltip, ...rest }: {
     children?: React.ReactNode;
     menuItems: MenuItemsGetter;
     closeAfterItemClick?: boolean;
     stopPropagation?: boolean;
     disabled?: boolean;
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    onMenuItemClick?: (callback: MenuItemClickHandler) => void;
     setOpen?: (arg: boolean) => void;
     ButtonComponent?: React.FC<{
         onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
         disabled?: boolean;
         children?: React.ReactNode;
+        'aria-label'?: string;
     }>;
-    anchorOrigin?: {
-        vertical: 'top' | 'center' | 'bottom';
-        horizontal: 'left' | 'center' | 'right';
-    };
-    transformOrigin?: {
-        vertical: 'top' | 'center' | 'bottom';
-        horizontal: 'left' | 'center' | 'right';
-    };
-    marginThreshold?: number | null;
+    anchorOrigin?: PopoverOrigin;
+    transformOrigin?: PopoverOrigin;
+    tooltip?: string;
     [key: string]: unknown;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 export default CascadingMenuButton;

package/esm/ui/CascadingMenuButton.js

@@ -1,24 +1,42 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
-import { IconButton } from '@mui/material';
-import CascadingMenu from "./CascadingMenu.js";
-function CascadingMenuButton({ children, menuItems, closeAfterItemClick = true, stopPropagation, disabled, setOpen, ButtonComponent = IconButton, onClick: onClickExtra, anchorOrigin, transformOrigin, marginThreshold, ...rest }) {
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import IconButton from '@mui/material/IconButton';
+import Tooltip from '@mui/material/Tooltip';
+import CascadingMenu from './CascadingMenu.js';
+// drop the menu below the trigger icon rather than overlapping it (MUI's
+// default top/left anchor)
+const dropdownAnchorOrigin = { vertical: 'bottom', horizontal: 'left' };
+const dropdownTransformOrigin = { vertical: 'top', horizontal: 'left' };
+// A disabled button has pointer-events:none, so a Tooltip placed directly on it
+// never fires; wrap it in a span (per MUI guidance) to restore the hover. The
+// wrapper is only added when disabled, so enabled buttons keep their layout.
+function MaybeTooltip({ title, disabled, children, }) {
+    return title ? (_jsx(Tooltip, { title: title, children: disabled ? _jsx("span", { children: children }) : children })) : (children);
+}
+function CascadingMenuButton({ children, menuItems, closeAfterItemClick = true, stopPropagation, disabled, setOpen, ButtonComponent = IconButton, onClick: onClickExtra, onMenuItemClick = callback => {
+    callback();
+}, anchorOrigin = dropdownAnchorOrigin, transformOrigin = dropdownTransformOrigin, tooltip, ...rest }) {
     const [anchorEl, setAnchorEl] = useState(null);
     const open = Boolean(anchorEl);
-    useEffect(() => {
-        setOpen?.(open);
-    }, [open, setOpen]);
+    // an empty array can be detected up front to grey out the button; a getter
+    // can't be checked without calling it, which we defer to click time below.
+    // callers that know a getter may be empty can pass `disabled` explicitly
     const isDisabled = disabled ?? (Array.isArray(menuItems) && menuItems.length === 0);
-    return (_jsxs(_Fragment, { children: [_jsx(ButtonComponent, { onClick: event => {
-                    if (stopPropagation) {
-                        event.stopPropagation();
-                    }
-                    setAnchorEl(event.currentTarget);
-                    onClickExtra?.(event);
-                }, ...rest, disabled: isDisabled, children: children }), open ? (_jsx(CascadingMenu, { open: open, onClose: () => {
+    return (_jsxs(_Fragment, { children: [_jsx(MaybeTooltip, { title: tooltip, disabled: isDisabled, children: _jsx(ButtonComponent, { "aria-label": tooltip, onClick: event => {
+                        if (stopPropagation) {
+                            event.stopPropagation();
+                        }
+                        // resolve here (only on click, never per-render) so a getter that
+                        // yields no items opens nothing rather than an empty popover
+                        const items = Array.isArray(menuItems) ? menuItems : menuItems();
+                        if (items.length > 0) {
+                            setAnchorEl(event.currentTarget);
+                            setOpen?.(true);
+                        }
+                        onClickExtra?.(event);
+                    }, ...rest, disabled: isDisabled, children: children }) }), open ? (_jsx(CascadingMenu, { open: open, onClose: () => {
                     setAnchorEl(null);
-                }, anchorEl: anchorEl, anchorOrigin: anchorOrigin, transformOrigin: transformOrigin, marginThreshold: marginThreshold, menuItems: menuItems, closeAfterItemClick: closeAfterItemClick, onMenuItemClick: (_, callback) => {
-                    callback();
-                } })) : null] }));
+                    setOpen?.(false);
+                }, anchorEl: anchorEl, anchorOrigin: anchorOrigin, transformOrigin: transformOrigin, menuItems: menuItems, closeAfterItemClick: closeAfterItemClick, onMenuItemClick: onMenuItemClick })) : null] }));
 }
 export default CascadingMenuButton;

package/esm/ui/CascadingMenuHelpDialog.d.ts

@@ -1,5 +1,5 @@
 export default function CascadingMenuHelpDialog({ onClose, helpText, label, }: {
-    onClose: (event: React.MouseEvent | React.KeyboardEvent) => void;
+    onClose: () => void;
     helpText: React.ReactNode;
     label?: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;

package/esm/ui/CascadingMenuHelpDialog.js

@@ -1,10 +1,9 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { DialogContent } from '@mui/material';
-import Dialog from "./Dialog.js";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import InfoDialog from './InfoDialog.js';
 export default function CascadingMenuHelpDialog({ onClose, helpText, label, }) {
-    return (_jsx(Dialog, { open: true, onClose: onClose, title: "Help", titleNode: label ? _jsxs(_Fragment, { children: ["Help: ", label] }) : undefined, onClick: e => {
+    return (_jsx(InfoDialog, { open: true, onClose: onClose, title: "Help", titleNode: label ? _jsxs(_Fragment, { children: ["Help: ", label] }) : undefined, onClick: e => {
             e.stopPropagation();
         }, onMouseDown: e => {
             e.stopPropagation();
-        }, children: _jsx(DialogContent, { children: helpText }) }));
+        }, children: helpText }));
 }

package/esm/ui/CascadingMenuHelpIconButton.d.ts

@@ -1,5 +1,6 @@
 import type React from 'react';
+export declare function CascadingMenuHelpIconSpacer(): React.JSX.Element;
 export default function CascadingMenuHelpIconButton({ helpText, label, }: {
     helpText: string;
     label?: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;