@trackunit/react-components 2.10.25 → 2.10.27-alpha-20b461ca062.0

package/index.esm.js

@@ -12,7 +12,7 @@ import IconSpriteOutline from '@trackunit/ui-icons/icons-sprite-outline.svg';
 import IconSpriteSolid from '@trackunit/ui-icons/icons-sprite-solid.svg';
 import { snakeCase, titleCase } from 'string-ts';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
-import { FloatingTree, useFloatingNodeId, useFloatingParentNodeId, useFloatingTree, offset, flip, shift, size, useFloating, autoUpdate, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingNode, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow, useListNavigation, useTypeahead } from '@floating-ui/react';
+import { FloatingTree, useFloatingNodeId, useFloatingParentNodeId, useFloatingTree, offset, flip, shift, size, useFloating, autoUpdate, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingNode, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow, useListNavigation, useTypeahead, FloatingList, useListItem } from '@floating-ui/react';
 import { Slot, Slottable } from '@radix-ui/react-slot';
 import { omit, isEqual } from 'es-toolkit';
 import { Link, useBlocker, useNavigate, useLocation, useRouter, useSearch } from '@tanstack/react-router';
@@ -7278,6 +7278,257 @@ const cvaMenuListMultiSelect = cvaMerge([
 ]);
 const cvaMenuListItem = cvaMerge("max-w-full");
 
+const MenuContentContext = createContext(null);
+/**
+ * Like `useOptionalPopoverContext`, but for the nearest `MenuContent`.
+ * `MenuItem` is used without a menu in places, so a missing ancestor must not throw.
+ *
+ * @returns {MenuContentContextValue | null} The menu context, or `null` when there is no ancestor `MenuContent`
+ */
+const useOptionalMenuContentContext = () => useContext(MenuContentContext);
+
+/**
+ * FloatingList only grows `elementsRef` / `labelsRef`. On unmount, `useListItem` nulls the element
+ * but writes the label back, so a removed row stays a live typeahead target on a dead slot.
+ * Re-establish both arrays from currently mounted nodes after each commit.
+ *
+ * @param elementsRef The FloatingList elements array
+ * @param labelsRef The FloatingList typeahead labels array, kept in lockstep with `elementsRef`
+ */
+const compactFloatingListRefs = (elementsRef, labelsRef) => {
+    const elements = elementsRef.current;
+    const labels = labelsRef.current;
+    const length = Math.max(elements.length, labels.length);
+    for (let index = 0; index < length; index++) {
+        if (!elements[index]) {
+            labels[index] = null;
+        }
+    }
+    let lastLive = -1;
+    for (let index = 0; index < length; index++) {
+        if (elements[index]) {
+            lastLive = index;
+        }
+    }
+    elements.length = lastLive + 1;
+    labels.length = lastLive + 1;
+};
+/**
+ * Index of the first registered item that is not `aria-disabled`. Used as the initial tab stop
+ * when `activeIndex` is still null.
+ *
+ * @param elementsRef The FloatingList elements array
+ * @returns {number} The first enabled index, or `0` when the list has no enabled item
+ */
+const firstEnabledListIndex = (elementsRef) => {
+    const index = elementsRef.current.findIndex(element => {
+        if (!element) {
+            return false;
+        }
+        return element.getAttribute("aria-disabled") !== "true";
+    });
+    return index === -1 ? 0 : index;
+};
+
+const UNMANAGED_SELECTION = [];
+/**
+ * Owns MenuContent's list registration, selection, and typeable-child key handling so the
+ * component file stays the shell + JSX.
+ */
+const useMenuContentState = ({ children, isMulti, selectedItems: controlledSelectedItems, onSelectionChange, ref, }) => {
+    const selectionManaged = controlledSelectedItems !== undefined || onSelectionChange !== undefined;
+    const [internalSelectedItems, setInternalSelectedItems] = useState(controlledSelectedItems ?? []);
+    const selectedItems = selectionManaged ? (controlledSelectedItems ?? internalSelectedItems) : UNMANAGED_SELECTION;
+    const [activeIndex, setActiveIndex] = useState(null);
+    const [firstEnabledIndex, setFirstEnabledIndex] = useState(0);
+    const listRef = useRef([]);
+    const labelsRef = useRef([]);
+    const ambientPopover = useOptionalPopoverContext();
+    // Falls back to a local, always-open floating context when there is no ambient `Popover` (e.g. `MenuContent`
+    // rendered standalone inside a `Collapse`) -- `useFloating` must still be called unconditionally per the
+    // Rules of Hooks, so this is cheap and simply unused whenever `ambientPopover` is present. When ambient, the
+    // enclosing `PopoverContent` already calls `context.refs.setFloating` on this same DOM node, so
+    // `elements.floating` is already populated there; standalone, nothing else does that, so this component's own
+    // root node must be wired up as the floating element itself for `useListNavigation`'s internal effects (which
+    // gate on `elements.floating`) to run.
+    const { context: standaloneContext, refs: standaloneRefs } = useFloating({ open: true });
+    const context = ambientPopover?.context ?? standaloneContext;
+    const floatingRef = useMergeRefs$1([ambientPopover ? null : standaloneRefs.setFloating, ref]);
+    // Reads the ambient popover's own `isNested` (resolved by its `usePopover()` call *before* it
+    // wraps this content in `<FloatingNode>`) rather than calling `useMenuTree()` again from here --
+    // from this position, beneath that `FloatingNode`, `useMenuTree()` would resolve the ambient
+    // parent id to the enclosing popover's *own* id and misreport every menu (root included) as
+    // nested. Standalone (no ambient `Popover`) is never nested.
+    const isNested = ambientPopover?.isNested ?? false;
+    const listNavigation = useListNavigation(context, {
+        listRef,
+        activeIndex,
+        onNavigate: setActiveIndex,
+        loop: true,
+        nested: isNested,
+    });
+    const typeahead = useTypeahead(context, {
+        listRef: labelsRef,
+        activeIndex,
+        onMatch: setActiveIndex,
+        resetMs: 500,
+    });
+    const { getFloatingProps, getItemProps } = useInteractions([listNavigation, typeahead]);
+    const syncRegisteredList = useCallback(() => {
+        compactFloatingListRefs(listRef, labelsRef);
+        const nextFirstEnabled = firstEnabledListIndex(listRef);
+        setFirstEnabledIndex(current => (current === nextFirstEnabled ? current : nextFirstEnabled));
+        setActiveIndex(current => {
+            if (current === null) {
+                return current;
+            }
+            // Truncation sets `elements.length = lastLive + 1`, so an activeIndex past the new end
+            // reads `undefined`, not `null`.
+            const activeElement = listRef.current[current];
+            if (activeElement === null || activeElement === undefined) {
+                return null;
+            }
+            return current;
+        });
+    }, []);
+    // Compact after this commit, not from a departing MenuItem's layout cleanup: React runs that
+    // cleanup before it detaches the row's list ref, so compaction would still see a live slot.
+    // Trailing removals do not shift sibling indices, so only this post-commit pass truncates them.
+    useLayoutEffect(() => {
+        syncRegisteredList();
+    }, [children, syncRegisteredList]);
+    const handleItemClick = useCallback((id) => {
+        if (!selectionManaged) {
+            return;
+        }
+        const newSelectedItems = isMulti
+            ? selectedItems.includes(id)
+                ? selectedItems.filter(item => item !== id)
+                : [...selectedItems, id]
+            : [id];
+        if (onSelectionChange !== undefined) {
+            onSelectionChange(newSelectedItems);
+        }
+        else {
+            setInternalSelectedItems(newSelectedItems);
+        }
+    }, [isMulti, selectedItems, onSelectionChange, selectionManaged]);
+    const menuContext = useMemo(() => ({
+        activeIndex,
+        firstEnabledIndex,
+        getItemProps,
+        isMulti,
+        selectedItems,
+        handleItemClick,
+        syncRegisteredList,
+    }), [activeIndex, firstEnabledIndex, getItemProps, isMulti, selectedItems, handleItemClick, syncRegisteredList]);
+    // Printable characters and Home/End/Left/Right stay native in nested inputs (e.g. FilterBar
+    // Search). ArrowDown is left alone so a typeable child can enter the registered list.
+    const handleKeyDownCapture = useCallback((event) => {
+        if (!isTypeableElement(event.target)) {
+            return;
+        }
+        if (event.key === "ArrowDown") {
+            return;
+        }
+        // ArrowUp is stopped so wrapping does not jump to the last item while the user is in Search.
+        // Phase 2 (FilterBar) adds the reverse path: ArrowUp on the first row returns to Search.
+        if (event.key.length === 1 ||
+            event.key === "Home" ||
+            event.key === "End" ||
+            event.key === "ArrowLeft" ||
+            event.key === "ArrowRight" ||
+            event.key === "ArrowUp") {
+            event.stopPropagation();
+        }
+    }, []);
+    return useMemo(() => ({
+        floatingRef,
+        getFloatingProps,
+        handleKeyDownCapture,
+        listRef,
+        labelsRef,
+        menuContext,
+    }), [floatingRef, getFloatingProps, handleKeyDownCapture, menuContext]);
+};
+
+/**
+ * MenuContent (formerly MenuList) is a popover menu that appears above all other content on the page. It offers a
+ * list of actions or functions that a user can access by clicking on a trigger, with full keyboard support:
+ * roving-tabindex Up/Down navigation (wrapping), Home/End, typeahead, and — via `MenuItem`'s `submenu` prop —
+ * nested submenu entry/exit.
+ *
+ * Items join this menu themselves via `FloatingList` + `useListItem`, so wrapping components do not hide them
+ * from the keyboard loop. Non-item children (search inputs, headings, dividers) render untouched.
+ *
+ * Typically rendered inside a `Popover` (directly, or as `PopoverContent`'s children), in which case it reads
+ * the popover's floating context to power its keyboard navigation. Also works standalone (e.g. inside a
+ * `Collapse`, with no ambient `Popover`), falling back to its own local, always-open floating context.
+ *
+ * **When to use**
+ * - Use the MenuContent if you have limited space and need to display overflow actions in a list.
+ * - Use the MenuContent for actions that are not essential to completing workflows.
+ * - Don't use the MenuContent to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
+ *
+ * @example MenuContent with action items
+ * ```tsx
+ * import { MenuContent, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
+ *
+ * const ActionsMenu = () => (
+ *   <MoreMenu>
+ *     {(close) => (
+ *       <MenuContent onClick={close}>
+ *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
+ *           Edit
+ *         </MenuItem>
+ *         <MenuItem id="duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />}>
+ *           Duplicate
+ *         </MenuItem>
+ *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
+ *           Delete
+ *         </MenuItem>
+ *       </MenuContent>
+ *     )}
+ *   </MoreMenu>
+ * );
+ * ```
+ * @example Multi-select MenuContent
+ * ```tsx
+ * import { MenuContent, MenuItem, MoreMenu } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const FilterMenu = () => {
+ *   const [selected, setSelected] = useState<string[]>(["active"]);
+ *
+ *   return (
+ *     <MoreMenu label="Filter by status">
+ *       <MenuContent
+ *         isMulti
+ *         selectedItems={selected}
+ *         onSelectionChange={setSelected}
+ *       >
+ *         <MenuItem id="active">Active</MenuItem>
+ *         <MenuItem id="idle">Idle</MenuItem>
+ *         <MenuItem id="offline">Offline</MenuItem>
+ *       </MenuContent>
+ *     </MoreMenu>
+ *   );
+ * };
+ * ```
+ * @param {MenuContentProps} props - The props for the MenuContent component
+ * @returns {ReactElement} MenuContent component
+ */
+const MenuContent = ({ "data-testid": dataTestId, className, listClassName, children, isMulti = false, selectedItems, onSelectionChange, style, ref, "aria-label": ariaLabel, ...args }) => {
+    const { floatingRef, getFloatingProps, handleKeyDownCapture, listRef, labelsRef, menuContext } = useMenuContentState({
+        children,
+        isMulti,
+        selectedItems,
+        onSelectionChange,
+        ref,
+    });
+    return (jsx("div", { "aria-label": ariaLabel, className: cvaMenu({ className, limitWidth: true }), "data-testid": dataTestId ? `${dataTestId}-menu-list` : "menu-list", onKeyDownCapture: handleKeyDownCapture, ref: floatingRef, role: "menu", style: style, tabIndex: -1, ...getFloatingProps({ onClick: args.onClick }), children: jsx("div", { className: cvaMenuList({ className: listClassName }), children: jsx(MenuContentContext.Provider, { value: menuContext, children: jsx(FloatingList, { elementsRef: listRef, labelsRef: labelsRef, children: children }) }) }) }));
+};
+
 /**
  * MenuDivider renders a horizontal line to visually separate groups of items within a MenuContent.
  *
@@ -7481,6 +7732,182 @@ const cvaMenuItemSuffix = cvaMerge(["text-neutral-400", "text-sm", "flex", "item
     },
 });
 
+/**
+ * A submenu's trigger row commonly lives inside a scrollable `MenuContent` list. Without this, a
+ * submenu opened from a row that later scrolls out of view stays open, floating disconnected from
+ * any visible row -- and (since nothing else would ever close it) stays that way even once the row
+ * scrolls back into view. `IntersectionObserver` (rather than e.g. the `Popover`'s own
+ * `ancestorScroll` dismissal) is what lets this react to the row's actual visibility instead of
+ * firing on every scroll tick of any ancestor, however small or unrelated to this row -- browsers
+ * compute intersection against every ancestor's overflow-clip box, not just an explicit `root`, so
+ * this fires as soon as *this* row's clipped out, even if some other list ancestor keeps scrolling.
+ * Only observing while `open` (rather than unconditionally) means the effect's own close
+ * never re-triggers itself, which is also exactly what keeps the submenu from reopening on its own
+ * once the row scrolls back into view -- there's no observer left running to notice that happen.
+ */
+const useCloseWhenScrolledOut = ({ open, nodeRef, returnFocusRef, onClose, }) => {
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        const node = nodeRef.current;
+        if (node === null) {
+            return;
+        }
+        returnFocusRef.current = node;
+        const observer = new IntersectionObserver(([entry]) => {
+            if (entry !== undefined && !entry.isIntersecting) {
+                // The row itself is what just scrolled out -- not a safe place to return focus to.
+                // `PopoverContent`'s `returnFocus` checks the target's visibility itself right at close
+                // time and falls back to its own hidden, off-screen element when it isn't visible, so
+                // this doesn't need to clear `returnFocusRef` by hand first.
+                onClose();
+            }
+        }, { threshold: 0 });
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [open, nodeRef, onClose, returnFocusRef]);
+};
+
+const getTypeaheadLabel = ({ disabled, label, children, }) => {
+    if (disabled === true) {
+        return null;
+    }
+    if (typeof label === "string" && label !== "") {
+        return label;
+    }
+    if (typeof children === "string") {
+        return children;
+    }
+    return null;
+};
+/**
+ * When `activeIndex` is still null (nothing keyboard-navigated yet), the first *enabled*
+ * registered item keeps `tabIndex={0}` so Tab can land in the list.
+ */
+const isActiveInMenu = (menu, index, disabled) => {
+    if (index < 0 || disabled) {
+        return false;
+    }
+    if (menu.activeIndex === index) {
+        return true;
+    }
+    return menu.activeIndex === null && index === menu.firstEnabledIndex;
+};
+/**
+ * Registers this row with the nearest `MenuContent` (no-op when there isn't one) and resolves the
+ * interaction / selection / tabIndex props the row needs. Submenu open state lives here so the
+ * scroll-out closer can share it.
+ */
+const useMenuItemBehavior = ({ className, label, children, selected, disabled, onClick, stopPropagation, id, tabIndex, ref, submenu, suffix, onFocus, onMouseMove, onPointerLeave, }) => {
+    const [submenuOpen, setSubmenuOpen] = useState(false);
+    const closeSubmenu = useCallback(() => setSubmenuOpen(false), []);
+    const triggerRowRef = useRef(null);
+    const menu = useOptionalMenuContentContext();
+    // Always called: without a `FloatingList` ancestor this is a no-op, so standalone `MenuItem` still renders.
+    const { ref: listItemRef, index } = useListItem({ label: getTypeaheadLabel({ disabled, label, children }) });
+    const syncRegisteredList = menu?.syncRegisteredList;
+    useLayoutEffect(() => {
+        if (index < 0) {
+            return;
+        }
+        syncRegisteredList?.();
+    }, [index, syncRegisteredList, disabled]);
+    const mergedTriggerRef = useMergeRefs$1([listItemRef, ref, triggerRowRef]);
+    const mergedRowRef = useMergeRefs$1([listItemRef, ref]);
+    // Where `PopoverContent` below returns focus to once the submenu closes -- normally the trigger
+    // row itself (kept in sync below). `PopoverContent`'s own `returnFocus` is visibility-aware, so
+    // this doesn't need to be cleared by hand right before the scroll-out auto-close further down --
+    // see that prop's own doc comment for why.
+    const returnFocusRef = useRef(null);
+    useCloseWhenScrolledOut({
+        open: submenuOpen,
+        nodeRef: triggerRowRef,
+        returnFocusRef,
+        onClose: closeSubmenu,
+    });
+    const handleKeyDown = useCallback((e) => {
+        // Enter/Space are already handled by the internal Popover's `activation: { click: true }`
+        // (`useClick`'s standard button-like keyboard semantics) -- only ArrowRight needs wiring up
+        // by hand here, since arrow keys aren't part of click/button semantics.
+        if (submenu !== undefined && disabled !== true && e.key === "ArrowRight") {
+            e.preventDefault();
+            e.stopPropagation();
+            setSubmenuOpen(true);
+            return;
+        }
+        if (e.key === "Enter" && onClick !== undefined && disabled !== true) {
+            if (stopPropagation) {
+                e.stopPropagation();
+            }
+            // eslint-disable-next-line @trackunit/no-typescript-assertion
+            onClick(e);
+        }
+    }, [disabled, onClick, stopPropagation, submenu]);
+    const handleItemClick = useCallback(e => {
+        if (stopPropagation) {
+            e.stopPropagation();
+        }
+        onClick?.(e);
+        if (menu !== null && disabled !== true) {
+            menu.handleItemClick(id ?? `${index}`);
+        }
+    }, [disabled, id, index, menu, onClick, stopPropagation]);
+    const isSelected = menu !== null ? Boolean(selected || menu.selectedItems.includes(id ?? `${index}`)) : selected;
+    const listClassName = menu === null
+        ? className
+        : menu.isMulti && isSelected
+            ? cvaMenuListMultiSelect({ className })
+            : cvaMenuListItem({ className });
+    const resolvedTabIndex = disabled
+        ? -1
+        : menu === null
+            ? (tabIndex ?? 0)
+            : isActiveInMenu(menu, index, disabled)
+                ? 0
+                : -1;
+    // Consumer suffix wins; otherwise multi-select may inject a check. `undefined` (not `null`) is
+    // required so `MenuItemRow` can still auto-render the submenu chevron when neither applies.
+    const resolvedSuffix = useMemo(() => suffix ??
+        (menu?.isMulti === true && isSelected ? (jsx(Icon, { className: "text-primary-600 block", name: "Check", size: "medium" })) : undefined), [suffix, menu?.isMulti, isSelected]);
+    const interactionProps = useMemo(() => menu === null
+        ? {
+            onClick: handleItemClick,
+            onFocus,
+            onMouseMove,
+            onPointerLeave,
+            onKeyDown: handleKeyDown,
+        }
+        : menu.getItemProps({
+            onClick: handleItemClick,
+            onFocus,
+            onMouseMove,
+            onPointerLeave,
+            onKeyDown: handleKeyDown,
+        }), [handleItemClick, handleKeyDown, menu, onFocus, onMouseMove, onPointerLeave]);
+    return useMemo(() => ({
+        mergedRowRef,
+        mergedTriggerRef,
+        submenuOpen,
+        setSubmenuOpen,
+        returnFocusRef,
+        isSelected,
+        resolvedSuffix,
+        listClassName,
+        resolvedTabIndex,
+        interactionProps,
+    }), [
+        mergedRowRef,
+        mergedTriggerRef,
+        submenuOpen,
+        isSelected,
+        resolvedSuffix,
+        listClassName,
+        resolvedTabIndex,
+        interactionProps,
+    ]);
+};
+
 /**
  * The row markup shared by both the submenu-less and submenu-bearing shapes of `MenuItem` -- pulled
  * out into its own component (rather than a JSX variable held in `MenuItem`) so each shape can
@@ -7548,95 +7975,43 @@ const MenuItemRow = ({ label, children, prefix, suffix, selected = false, disabl
  * @returns {ReactElement} MenuItem component
  */
 const MenuItem = ({ className, "data-testid": dataTestId, label, children, selected = false, focused = false, prefix, suffix, disabled = false, onClick, stopPropagation = true, id, tabIndex, optionLabelDescription, optionPrefix, fieldSize = "medium", variant = "primary", style, ref, submenu, submenuSizing, onFocus, onMouseMove, onPointerLeave, }) => {
-    const [submenuOpen, setSubmenuOpen] = useState(false);
-    const triggerRowRef = useRef(null);
-    const mergedTriggerRef = useMergeRefs$1([ref, triggerRowRef]);
-    // Where `PopoverContent` below returns focus to once the submenu closes -- normally the trigger
-    // row itself (kept in sync below). `PopoverContent`'s own `returnFocus` is visibility-aware, so
-    // this doesn't need to be cleared by hand right before the scroll-out auto-close further down --
-    // see that prop's own doc comment for why.
-    const returnFocusRef = useRef(null);
-    // A submenu's trigger row commonly lives inside a scrollable `MenuContent` list. Without this, a
-    // submenu opened from a row that later scrolls out of view stays open, floating disconnected from
-    // any visible row -- and (since nothing else would ever close it) stays that way even once the row
-    // scrolls back into view. `IntersectionObserver` (rather than e.g. the `Popover`'s own
-    // `ancestorScroll` dismissal) is what lets this react to the row's actual visibility instead of
-    // firing on every scroll tick of any ancestor, however small or unrelated to this row -- browsers
-    // compute intersection against every ancestor's overflow-clip box, not just an explicit `root`, so
-    // this fires as soon as *this* row's clipped out, even if some other list ancestor keeps scrolling.
-    // Only observing while `submenuOpen` (rather than unconditionally) means the effect's own close
-    // never re-triggers itself, which is also exactly what keeps the submenu from reopening on its own
-    // once the row scrolls back into view -- there's no observer left running to notice that happen.
-    useEffect(() => {
-        if (!submenuOpen) {
-            return;
-        }
-        const node = triggerRowRef.current;
-        if (node === null) {
-            return;
-        }
-        returnFocusRef.current = node;
-        const observer = new IntersectionObserver(([entry]) => {
-            if (entry !== undefined && !entry.isIntersecting) {
-                // The row itself is what just scrolled out -- not a safe place to return focus to.
-                // `PopoverContent`'s `returnFocus` checks the target's visibility itself right at close
-                // time and falls back to its own hidden, off-screen element when it isn't visible, so
-                // this doesn't need to clear `returnFocusRef` by hand first.
-                setSubmenuOpen(false);
-            }
-        }, { threshold: 0 });
-        observer.observe(node);
-        return () => observer.disconnect();
-    }, [submenuOpen]);
-    /* Handle tab navigation */
-    const handleKeyDown = (e) => {
-        // Enter/Space are already handled by the internal Popover's `activation: { click: true }`
-        // (`useClick`'s standard button-like keyboard semantics) -- only ArrowRight needs wiring up
-        // by hand here, since arrow keys aren't part of click/button semantics.
-        if (submenu !== undefined && disabled !== true && e.key === "ArrowRight") {
-            e.preventDefault();
-            e.stopPropagation();
-            setSubmenuOpen(true);
-            return;
-        }
-        if (e.key === "Enter" && onClick !== undefined && disabled !== true) {
-            if (stopPropagation) {
-                e.stopPropagation();
-            }
-            // eslint-disable-next-line @trackunit/no-typescript-assertion
-            onClick(e);
-        }
-    };
-    const handleItemClick = e => {
-        if (stopPropagation) {
-            e.stopPropagation();
-        }
-        onClick?.(e);
-    };
+    const { mergedRowRef, mergedTriggerRef, submenuOpen, setSubmenuOpen, returnFocusRef, isSelected, resolvedSuffix, listClassName, resolvedTabIndex, interactionProps, } = useMenuItemBehavior({
+        className,
+        label,
+        children,
+        selected,
+        disabled,
+        onClick,
+        stopPropagation,
+        id,
+        tabIndex,
+        ref,
+        submenu,
+        suffix,
+        onFocus,
+        onMouseMove,
+        onPointerLeave,
+    });
     const itemRowProps = {
         id,
         label,
         children,
         prefix,
-        suffix,
-        selected,
+        suffix: resolvedSuffix,
+        selected: isSelected,
         disabled,
         variant,
         optionLabelDescription,
         optionPrefix,
         style,
-        onFocus,
-        onMouseMove,
-        onPointerLeave,
-        onClick: handleItemClick,
-        onKeyDown: handleKeyDown,
         dataTestId,
         hasSubmenu: submenu !== undefined,
-        className: cvaMenuItem({ selected, fieldSize, disabled, className, variant, focused }),
-        tabIndex: disabled ? -1 : (tabIndex ?? 0),
+        ...interactionProps,
+        className: cvaMenuItem({ selected: isSelected, fieldSize, disabled, className: listClassName, variant, focused }),
+        tabIndex: resolvedTabIndex,
     };
     if (submenu === undefined) {
-        return jsx(MenuItemRow, { ...itemRowProps, ref: ref });
+        return jsx(MenuItemRow, { ...itemRowProps, ref: mergedRowRef });
     }
     // Menu role lives on the nested `MenuContent` only — the Popover keeps its default `dialog`
     // floating role so SRs don't see nested `role="menu"`. `aria-haspopup="menu"` overrides
@@ -7644,218 +8019,6 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
     return (jsxs(Popover, { activation: { click: !disabled, hover: disabled ? false : { delayed: true } }, isOpen: submenuOpen, onOpenStateChange: setSubmenuOpen, placement: "right-start", sizing: submenuSizing, children: [jsx(PopoverTrigger, { ref: mergedTriggerRef, children: jsx(MenuItemRow, { ...itemRowProps, "aria-expanded": submenuOpen, "aria-haspopup": "menu" }) }), jsx(PopoverContent, { initialFocus: 1, returnFocus: returnFocusRef, children: submenu })] }));
 };
 
-/**
- * Derives the plain-text label used for typeahead matching. Disabled items are excluded (`null`)
- * so typing never lands focus on an item the user can't act on.
- */
-const getTypeaheadLabel = (props) => {
-    if (props.disabled === true) {
-        return null;
-    }
-    if (typeof props.label === "string" && props.label !== "") {
-        return props.label;
-    }
-    if (typeof props.children === "string") {
-        return props.children;
-    }
-    return null;
-};
-/**
- * MenuContent (formerly MenuList) is a popover menu that appears above all other content on the page. It offers a
- * list of actions or functions that a user can access by clicking on a trigger, with full keyboard support:
- * roving-tabindex Up/Down navigation (wrapping), Home/End, typeahead, and — via `MenuItem`'s `submenu` prop —
- * nested submenu entry/exit.
- *
- * Typically rendered inside a `Popover` (directly, or as `PopoverContent`'s children), in which case it reads
- * the popover's floating context to power its keyboard navigation. Also works standalone (e.g. inside a
- * `Collapse`, with no ambient `Popover`), falling back to its own local, always-open floating context.
- *
- * **When to use**
- * - Use the MenuContent if you have limited space and need to display overflow actions in a list.
- * - Use the MenuContent for actions that are not essential to completing workflows.
- * - Don't use the MenuContent to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
- *
- * @example MenuContent with action items
- * ```tsx
- * import { MenuContent, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
- *
- * const ActionsMenu = () => (
- *   <MoreMenu>
- *     {(close) => (
- *       <MenuContent onClick={close}>
- *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
- *           Edit
- *         </MenuItem>
- *         <MenuItem id="duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />}>
- *           Duplicate
- *         </MenuItem>
- *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
- *           Delete
- *         </MenuItem>
- *       </MenuContent>
- *     )}
- *   </MoreMenu>
- * );
- * ```
- * @example Multi-select MenuContent
- * ```tsx
- * import { MenuContent, MenuItem, MoreMenu } from "@trackunit/react-components";
- * import { useState } from "react";
- *
- * const FilterMenu = () => {
- *   const [selected, setSelected] = useState<string[]>(["active"]);
- *
- *   return (
- *     <MoreMenu label="Filter by status">
- *       <MenuContent
- *         isMulti
- *         selectedItems={selected}
- *         onSelectionChange={setSelected}
- *       >
- *         <MenuItem id="active">Active</MenuItem>
- *         <MenuItem id="idle">Idle</MenuItem>
- *         <MenuItem id="offline">Offline</MenuItem>
- *       </MenuContent>
- *     </MoreMenu>
- *   );
- * };
- * ```
- * @param {MenuContentProps} props - The props for the MenuContent component
- * @returns {ReactElement} MenuContent component
- */
-const MenuContent = ({ "data-testid": dataTestId, className, listClassName, children, isMulti = false, selectedItems: controlledSelectedItems, onSelectionChange, style, ref, ...args }) => {
-    const childrenArr = useMemo(() => Children.toArray(children), [children]);
-    const [internalSelectedItems, setInternalSelectedItems] = useState(controlledSelectedItems ?? []);
-    const selectedItems = controlledSelectedItems ?? internalSelectedItems;
-    const [activeIndex, setActiveIndex] = useState(null);
-    const listRef = useRef([]);
-    const labelsRef = useRef([]);
-    const ambientPopover = useOptionalPopoverContext();
-    // Falls back to a local, always-open floating context when there is no ambient `Popover` (e.g. `MenuContent`
-    // rendered standalone inside a `Collapse`) -- `useFloating` must still be called unconditionally per the
-    // Rules of Hooks, so this is cheap and simply unused whenever `ambientPopover` is present. When ambient, the
-    // enclosing `PopoverContent` already calls `context.refs.setFloating` on this same DOM node, so
-    // `elements.floating` is already populated there; standalone, nothing else does that, so this component's own
-    // root node must be wired up as the floating element itself for `useListNavigation`'s internal effects (which
-    // gate on `elements.floating`) to run.
-    const { context: standaloneContext, refs: standaloneRefs } = useFloating({ open: true });
-    const context = ambientPopover?.context ?? standaloneContext;
-    const floatingRef = useMergeRefs$1([ambientPopover ? null : standaloneRefs.setFloating, ref]);
-    // Reads the ambient popover's own `isNested` (resolved by its `usePopover()` call *before* it
-    // wraps this content in `<FloatingNode>`) rather than calling `useMenuTree()` again from here --
-    // from this position, beneath that `FloatingNode`, `useMenuTree()` would resolve the ambient
-    // parent id to the enclosing popover's *own* id and misreport every menu (root included) as
-    // nested. Standalone (no ambient `Popover`) is never nested.
-    const isNested = ambientPopover?.isNested ?? false;
-    const listNavigation = useListNavigation(context, {
-        listRef,
-        activeIndex,
-        onNavigate: setActiveIndex,
-        loop: true,
-        nested: isNested,
-    });
-    const typeahead = useTypeahead(context, {
-        listRef: labelsRef,
-        activeIndex,
-        onMatch: setActiveIndex,
-        resetMs: 500,
-    });
-    const { getFloatingProps, getItemProps } = useInteractions([listNavigation, typeahead]);
-    const handleItemClick = useCallback((id) => {
-        const newSelectedItems = isMulti
-            ? selectedItems.includes(id)
-                ? selectedItems.filter(item => item !== id)
-                : [...selectedItems, id]
-            : [id];
-        if (onSelectionChange !== undefined) {
-            onSelectionChange(newSelectedItems);
-        }
-        else {
-            setInternalSelectedItems(newSelectedItems);
-        }
-    }, [isMulti, selectedItems, onSelectionChange]);
-    // Only real `MenuItem`s participate in keyboard navigation. Arbitrary content (e.g. a `Search` input or a
-    // list of checkboxes, via `Filter`'s children) can be rendered alongside them, but is excluded from the nav
-    // list and rendered untouched -- `useListNavigation`/`useTypeahead` treat every registered item as a single
-    // atomic focus target, an assumption that breaks down for a wrapper `<div>` holding several of its own
-    // independently-focusable descendants (arrow keys skipping over it, its own click/focus handlers stealing
-    // DOM focus from whatever's inside it). Computed as plain, memoized values (never touching listRef/labelsRef
-    // here -- see the layout effect below, since refs must not be read/written during render).
-    const { navIndicesByChildIndex, navLabels, firstEnabledNavIndex } = useMemo(() => {
-        const indices = [];
-        const labels = [];
-        let itemCount = 0;
-        let firstEnabledIndex = -1;
-        childrenArr.forEach(child => {
-            if (isValidElement(child) && child.type === MenuItem) {
-                if (firstEnabledIndex === -1 && child.props.disabled !== true) {
-                    firstEnabledIndex = itemCount;
-                }
-                indices.push(itemCount);
-                labels.push(getTypeaheadLabel(child.props));
-                itemCount += 1;
-            }
-            else {
-                indices.push(-1);
-            }
-        });
-        return { navIndicesByChildIndex: indices, navLabels: labels, firstEnabledNavIndex: firstEnabledIndex };
-    }, [childrenArr]);
-    useLayoutEffect(() => {
-        listRef.current.length = navLabels.length;
-        labelsRef.current = navLabels;
-    }, [navLabels]);
-    // A focused descendant's own keydown would otherwise be swallowed by `useTypeahead` as a single-character
-    // match attempt (see `getFloatingProps` below); this leaves native typing in nested content (e.g. a `Search`
-    // input rendered as one of `MenuContent`'s non-`MenuItem` children) untouched.
-    const handleKeyDownCapture = (event) => {
-        if (isTypeableElement(event.target)) {
-            event.stopPropagation();
-        }
-    };
-    const createItemRefSetter = useCallback((itemNavIndex) => (node) => {
-        listRef.current[itemNavIndex] = node;
-    }, []);
-    return (jsx("div", { className: cvaMenu({ className, limitWidth: true }), "data-testid": dataTestId ? `${dataTestId}-menu-list` : "menu-list", onKeyDownCapture: handleKeyDownCapture, ref: floatingRef, role: "menu", style: style, tabIndex: -1, ...getFloatingProps({ onClick: args.onClick }), children: jsx("div", { className: cvaMenuList({ className: listClassName }), children: childrenArr.map((menuItem, index) => {
-                if (!isValidElement(menuItem)) {
-                    return null;
-                }
-                if (menuItem.type === MenuDivider) {
-                    return cloneElement(menuItem, { key: index });
-                }
-                // Arbitrary, non-`MenuItem` content (see the comment on `navIndicesByChildIndex` above) is rendered
-                // untouched, participating in neither roving tabindex nor typeahead -- its own interactive
-                // descendants (inputs, checkboxes, buttons, ...) keep their native focus/click/keydown behavior.
-                if (menuItem.type !== MenuItem) {
-                    return cloneElement(menuItem, { key: index });
-                }
-                const itemNavIndex = navIndicesByChildIndex[index] ?? -1;
-                const disabled = menuItem.props.disabled ?? false;
-                const isSelected = (selectedItems.includes(menuItem.props.id ?? `${index}`) || menuItem.props.selected) ?? false;
-                const isActive = activeIndex === itemNavIndex || (activeIndex === null && itemNavIndex === firstEnabledNavIndex);
-                return cloneElement(menuItem, {
-                    ...menuItem.props,
-                    key: index,
-                    ...getItemProps({
-                        onClick: (event) => {
-                            menuItem.props.onClick?.(event);
-                            if (!disabled) {
-                                handleItemClick(menuItem.props.id ?? `${index}`);
-                            }
-                        },
-                    }),
-                    tabIndex: disabled ? -1 : isActive ? 0 : -1,
-                    ref: createItemRefSetter(itemNavIndex),
-                    className: isMulti && isSelected
-                        ? cvaMenuListMultiSelect({ className: menuItem.props.className })
-                        : cvaMenuListItem({ className: menuItem.props.className }),
-                    selected: isSelected,
-                    suffix: menuItem.props.suffix ??
-                        (isMulti && isSelected ? jsx(Icon, { className: "text-primary-600 block", name: "Check", size: "medium" }) : null),
-                });
-            }) }) }));
-};
-
 const cvaMoreMenu = cvaMerge(["p-0"]);
 
 /**