@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/ui/CascadingMenu.js

@@ -1,56 +1,405 @@
-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, use, useEffect, useRef, 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 { useEventCallback } from '../util/useEventCallback.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;
+/**
+ * Which submenu of ONE list is open, plus the hover intent that moves it.
+ *
+ * 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.
+ */
+function useSubmenuHover() {
+    const [openSubmenu, setOpenSubmenu] = useState();
+    // 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 = useRef(null);
+    // where the pointer was when the open panel opened — the cone's tip
+    const apex = useRef(undefined);
+    const pending = useRef(undefined);
+    const cancelPending = () => {
+        if (pending.current) {
+            clearTimeout(pending.current.timer);
+            pending.current = undefined;
+        }
+    };
+    useEffect(() => () => {
+        if (pending.current) {
+            clearTimeout(pending.current.timer);
+        }
+    }, []);
+    const commit = (key, point) => {
+        cancelPending();
+        apex.current = key === undefined ? undefined : point;
+        setOpenSubmenu(key);
+    };
+    // '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;
+        const tip = apex.current;
+        if (!panel || !tip) {
+            return 'unmeasured';
+        }
+        const rect = panel.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+            return 'unmeasured';
+        }
+        return isAimedAtPanel(point, tip, rect) ? 'inside' : 'outside';
+    };
+    const defer = (key, point) => {
+        cancelPending();
+        pending.current = {
+            key,
+            point,
+            timer: setTimeout(() => {
+                commit(key, point);
+            }, submenuAimGraceMs),
+        };
+    };
+    // 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.
+    const onPointerMove = useEventCallback((event) => {
+        const deferred = pending.current;
+        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);
+        }
+    });
+    useEffect(() => {
+        if (openSubmenu === undefined) {
+            return;
+        }
+        document.addEventListener('mousemove', onPointerMove);
+        return () => {
+            document.removeEventListener('mousemove', onPointerMove);
+        };
+    }, [openSubmenu, onPointerMove]);
+    return {
+        openSubmenu,
+        panelRef,
+        setSubmenu: commit,
+        // the pointer reached the open panel, so whatever was scheduled is stale
+        keepSubmenuOpen: cancelPending,
+        // the pointer arrived at a row wanting `key` open — undefined from a row
+        // with no submenu, i.e. "close whatever is"
+        hoverSubmenu: (key, point) => {
+            if (key === openSubmenu) {
+                cancelPending();
+            }
+            else if (openSubmenu === 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);
+            }
+        },
     };
-    const hasIcon = menuItems.some(m => 'icon' in m && m.icon);
+}
+// Identity of a submenu row, used both as its React key and to remember which
+// submenu is open. 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.
+function submenuKey(label) {
+    return `subMenu-${label}`;
+}
+// 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.
+function CascadingSubmenu({ item, itemKey, inset, columns, 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 = hover.openSubmenu === itemKey && !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 })] }) }), _jsx(HoverMenu, { open: isOpen, 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.keepSubmenuOpen, 
+                // only while open: a panel MUI is still fading out is not something to
+                // aim at, and this list keeps one cone target for whichever submenu is
+                // up
+                paperRef: isOpen ? hover.panelRef : undefined, onClose: () => {
+                    hover.setSubmenu(undefined);
+                }, children: _jsx(SubMenuList, { item: item, onNavigateBack: () => {
+                        hover.setSubmenu(undefined);
+                        anchorEl?.focus();
+                    } }) })] }));
+}
+// Resolves the rows inside the panel, which MUI 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.
+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 hover = useSubmenuHover();
+    // 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. Whether the ask
+    // is granted now or waited out is the aim cone's call, which is why the
+    // pointer comes with it
+    const closeOnHover = (event) => {
+        hover.hoverSubmenu(undefined, { x: event.clientX, y: event.clientY });
+    };
+    const { hasIcon, columns } = getMenuColumnFlags(menuItems);
+    const sortedItems = menuItems.toSorted((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
     return (_jsx(_Fragment, { children: sortedItems.map((item, 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}`));
+                const key = submenuKey(item.label);
+                return (_jsx(CascadingSubmenu, { itemKey: key, item: item, inset: hasIcon && !item.icon, columns: columns, hover: hover, onNavigateBack: onNavigateBack }, key));
             }
             if (item.type === 'divider') {
+                // eslint-disable-next-line @eslint-react/no-array-index-key -- dividers have no identifying field, list order is fixed
                 return _jsx(Divider, { component: "li" }, `divider-${idx}`);
             }
             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 }, `subHeader-${item.label}`));
+            }
+            if (item.type === 'custom') {
+                return (_jsx(CustomMenuRow, { item: item, onHover: closeOnHover }, `custom-${item.label}`));
+            }
+            return (_jsx(CascadingMenuItem, { item: item, inset: hasIcon && !item.icon, columns: columns, onNavigateBack: onNavigateBack, onHover: closeOnHover }, `menuitem-${item.label}`));
         }) }));
 }
-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;

package/esm/ui/CascadingMenuHelpIconButton.js

@@ -1,15 +1,24 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Suspense, useState } from 'react';
-import HelpOutline from '@mui/icons-material/HelpOutline';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import HelpOutlined from '@mui/icons-material/HelpOutlined';
 import { IconButton } from '@mui/material';
-import CascadingMenuHelpDialog from "./CascadingMenuHelpDialog.js";
+import CascadingMenuHelpDialog from './CascadingMenuHelpDialog.js';
+const buttonStyle = { marginLeft: 4, padding: 4 };
+// Invisible button that reserves the exact same footprint as the help icon, so
+// rows without help text keep their end decoration (radio/checkbox) aligned
+// with rows that have one
+export function CascadingMenuHelpIconSpacer() {
+    return (_jsx(IconButton, { size: "small", disabled: true, style: { ...buttonStyle, visibility: 'hidden' }, children: _jsx(HelpOutlined, { fontSize: "small" }) }));
+}
 export default function CascadingMenuHelpIconButton({ helpText, label, }) {
     const [helpDialogOpen, setHelpDialogOpen] = useState(false);
-    return (_jsxs(_Fragment, { children: [_jsx(IconButton, { size: "small", onClick: event => {
+    return (_jsxs(_Fragment, { children: [_jsx(IconButton, { size: "small", "aria-label": typeof label === 'string' ? `Help for ${label}` : 'Help for this item', onClick: event => {
                     event.stopPropagation();
                     setHelpDialogOpen(true);
-                }, style: { marginLeft: 4, padding: 4 }, children: _jsx(HelpOutline, { fontSize: "small" }) }), helpDialogOpen ? (_jsxs(Suspense, { fallback: null, children: [_jsx(CascadingMenuHelpDialog, { helpText: helpText, label: label, onClose: event => {
-                            event.stopPropagation();
-                            setHelpDialogOpen(false);
-                        } }), ' '] })) : null] }));
+                }, style: buttonStyle, children: _jsx(HelpOutlined, { fontSize: "small" }) }), helpDialogOpen ? (_jsx(CascadingMenuHelpDialog, { helpText: helpText, label: label, 
+                // the dialog stops click/mousedown propagation on its own root, so
+                // closing it can't reach the menu underneath
+                onClose: () => {
+                    setHelpDialogOpen(false);
+                } })) : null] }));
 }