@trackunit/react-components 2.5.2-alpha-3b19e5fe058.0 → 2.6.2-alpha-770d9994af7.0

package/index.esm.js

@@ -1,8 +1,8 @@
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation } from '@trackunit/i18n-library-translation';
 import { twMerge } from 'tailwind-merge';
 import { objectKeys, uuidv4, parseTailwindArbitraryValue, objectEntries, nonNullable, objectValues, filterByMultiple } from '@trackunit/shared-utils';
-import { useRef, useMemo, useEffect, useState, createContext, useContext, isValidElement, cloneElement, createElement, useLayoutEffect, useCallback, Fragment as Fragment$1, memo, forwardRef, useId, useReducer, Children } from 'react';
+import { useRef, useMemo, useEffect, useSyncExternalStore, useState, useLayoutEffect, createContext, useContext, isValidElement, cloneElement, createElement, useCallback, Fragment as Fragment$1, memo, forwardRef, useId, useReducer, Children } from 'react';
 import { rentalStatusPalette, sitesPalette, utilizationPalette, activityPalette, criticalityPalette, generalPalette, intentPalette, themeScreenSizeAsNumber, themeContainerSize, color } from '@trackunit/ui-design-tokens';
 import { iconNames } from '@trackunit/ui-icons';
 import IconSpriteMicro from '@trackunit/ui-icons/icons-sprite-micro.svg';
@@ -11,11 +11,12 @@ 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 { useFloating, autoUpdate, offset, flip, shift, size, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } 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 } 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';
 import { useVirtualizer } from '@tanstack/react-virtual';
+import { isTypeableElement } from '@floating-ui/react/utils';
 import { HelmetProvider, Helmet } from 'react-helmet-async';
 import { Trigger, Content as Content$1, List as List$1, Root } from '@radix-ui/react-tabs';
 import { gzipSync, gunzipSync } from 'fflate';
@@ -26,7 +27,6 @@ import { dequal } from 'dequal';
 var defaultTranslations = {
 	"breadcrumb.backButton": "back",
 	"breadcrumb.expandButton": "expand",
-	"cardHeader.closeButton": "Close",
 	"moreMenu.buttonLabel": "Show more"
 };
 
@@ -212,7 +212,212 @@ const Icon = ({ name, size = "medium", className, "data-testid": dataTestId, col
     return (jsx("span", { ...rest, "aria-describedby": ariaDescribedBy, "aria-hidden": ariaHidden, "aria-label": ariaLabel ? ariaLabel : titleCase(iconName), "aria-labelledby": ariaLabelledBy, className: cvaIcon({ color, size, fontSize, className }), "data-testid": dataTestId, id: iconContainerId, onClick: onClick, ref: ref, style: style, children: jsx("svg", { "aria-labelledby": iconContainerId, "data-testid": dataTestId ? `${dataTestId}-${iconName}` : iconName, role: "img", viewBox: correctViewBox, children: jsx("use", { href: href[correctIconType], ref: useTagRef }) }) }));
 };
 
+/**
+ * Emitted on the tree's event emitter whenever a node transitions to open, so `MenuTree` can close
+ * that node's siblings. See `usePopover`'s emit side and `MenuTree`'s listener below.
+ */
+const MENU_TREE_OPEN_EVENT = "menuopen";
+/**
+ * Emitted whenever a node transitions to closed, so siblings can tell when a `reason: "click"` open
+ * (see `MenuTreeOpenEvent`) has been dismissed and stop treating that branch as click-pinned. See
+ * `usePopover`'s emit side and its `openSiblingPinned` listener.
+ */
+const MENU_TREE_CLOSE_EVENT = "menuclose";
+/**
+ * Returns whether a pointer event landed on any `MenuTree` member's trigger or floating surface.
+ * Used by nested `Popover`s to avoid treating a click on a sibling row (or the parent panel) as an
+ * outside press that dismisses the whole branch.
+ */
+const isPressInsideMenuTree = (event, tree) => {
+    const { target } = event;
+    if (!(target instanceof Node)) {
+        return false;
+    }
+    return tree.nodesRef.current.some(node => {
+        const floating = node.context?.refs.floating.current;
+        const reference = node.context?.refs.reference.current;
+        return ((floating instanceof Element && floating.contains(target)) ||
+            (reference instanceof Element && reference.contains(target)));
+    });
+};
+/**
+ * Reads (and joins) the nearest `MenuTree` boundary, if any.
+ *
+ * Returns explicit tree state so fully custom nested-menu UI can be built without going through
+ * `Popover`/`PopoverTrigger`/`PopoverContent`'s implicit prop-cloning. `Popover` is one consumer of
+ * this hook, not the only way to participate in a `MenuTree`.
+ *
+ * Safe to call outside a `<MenuTree>`: `parentId`/`tree` are `null` and `isNested` is `false`.
+ *
+ * @returns {UseMenuTreeType} Explicit tree state for the calling node
+ */
+const useMenuTree = () => {
+    const nodeId = useFloatingNodeId();
+    const parentId = useFloatingParentNodeId();
+    const tree = useFloatingTree();
+    return useMemo(() => ({ nodeId, parentId, isNested: parentId !== null, tree }), [nodeId, parentId, tree]);
+};
+const MenuTreeSiblingCloseBoundary = ({ children }) => {
+    const tree = useFloatingTree();
+    useEffect(() => {
+        if (!tree) {
+            return;
+        }
+        const closeSiblings = ({ nodeId, parentId }) => {
+            tree.nodesRef.current
+                .filter(node => node.id !== nodeId && node.parentId === parentId && node.context?.open === true)
+                .forEach(node => node.context?.onOpenChange(false));
+        };
+        tree.events.on(MENU_TREE_OPEN_EVENT, closeSiblings);
+        return () => {
+            tree.events.off(MENU_TREE_OPEN_EVENT, closeSiblings);
+        };
+    }, [tree]);
+    return jsx(Fragment, { children: children });
+};
+/**
+ * Opt-in tree-coordination boundary for a family of `Popover`s: sibling-close-on-open, dismiss
+ * bubbling (Escape closes one level at a time; outside-press is scoped per node so sibling rows
+ * don't collapse the root), and hover safe-polygon between nested rows. Every `Popover` rendered
+ * automatically joins it — there is no per-instance flag to set. A `Popover` outside any `MenuTree`
+ * is unaffected and behaves exactly as it does today.
+ *
+ * Only the immediate siblings of a newly-opened node (nodes sharing the same parent) are closed.
+ * Closing a node cascades to close its own open subtree as a structural consequence of
+ * `PopoverContent` unmounting when its `Popover` closes, not extra logic here.
+ *
+ * ### When to use
+ * Wrap a family of nested `Popover`s (e.g. a menu bar or a filter bar's flyouts) that should
+ * coordinate open/close state with each other.
+ *
+ * ### When not to use
+ * Do not wrap unrelated `Popover`s that merely happen to render inside each other's React tree —
+ * they will incorrectly join tree coordination and can be closed by sibling opens.
+ *
+ * ### Click-opened rows vs. sibling hovers
+ * `hover: { delayed: true }` on a nested `Popover` (used below, instead of a plain `hover: true`)
+ * keeps a row opened by a click open while the cursor passes over its siblings, matching what
+ * `MenuItem`'s `submenu` prop already does internally. See the "Advanced" section of the
+ * `Components/Menu/Nested Menu` docs page for the full explanation.
+ *
+ * @example
+ * ```tsx
+ * import { MenuTree, Popover, PopoverContent, PopoverTrigger } from "@trackunit/react-components";
+ *
+ * const NestedMenu = () => (
+ *   <MenuTree>
+ *     <Popover placement="bottom-start">
+ *       <PopoverTrigger>Open</PopoverTrigger>
+ *       <PopoverContent>
+ *         <Popover activation={{ click: true, hover: { delayed: true } }} placement="right-start">
+ *           <PopoverTrigger>Row A</PopoverTrigger>
+ *           <PopoverContent>Row A's flyout</PopoverContent>
+ *         </Popover>
+ *         <Popover activation={{ click: true, hover: { delayed: true } }} placement="right-start">
+ *           <PopoverTrigger>Row B</PopoverTrigger>
+ *           <PopoverContent>Row B's flyout</PopoverContent>
+ *         </Popover>
+ *       </PopoverContent>
+ *     </Popover>
+ *   </MenuTree>
+ * );
+ * ```
+ * @param {object} props The props for MenuTree
+ * @param {ReactNode} props.children The `Popover`s (and anything else) to coordinate
+ * @returns {ReactElement} A `FloatingTree` provider wired up for sibling-close coordination
+ */
+const MenuTree = ({ children }) => {
+    return (jsx(FloatingTree, { children: jsx(MenuTreeSiblingCloseBoundary, { children: children }) }));
+};
+
+/**
+ * The parent Popover's own floating panel element, found via the `MenuTree`'s Floating UI tree
+ * bookkeeping rather than by walking the DOM -- this is the exact element `PopoverContent` set as
+ * `context.refs.floating.current` when it rendered, so its rect is the parent panel's true visual
+ * boundary (border, shadow, and any internal scrollbar all already baked in), regardless of how
+ * deeply the current node's own trigger row is nested inside it.
+ *
+ * @param tree The `MenuTree`'s Floating UI tree, or `null` outside a `MenuTree`
+ * @param parentId The nearest ancestor node's id from `useMenuTree`, or `null` at the tree's root
+ * @returns {HTMLElement | null} The parent's floating panel element, or `null` if there isn't one
+ */
+const getParentPanelElement = (tree, parentId) => {
+    if (tree === null || parentId === null) {
+        return null;
+    }
+    return tree.nodesRef.current.find(node => node.id === parentId)?.context?.refs.floating.current ?? null;
+};
+/**
+ * Extra horizontal offset (in pixels) a `right`/`left`-placed submenu needs so it clears its parent
+ * Popover panel's true edge, rather than sitting flush with (or overlapping) whatever is at the edge
+ * of the specific row that triggered it.
+ *
+ * A submenu's `elements.reference` is the trigger row it opened from, not the parent panel itself --
+ * and that row's own edge is inset from the panel's true visual boundary by the panel's padding and,
+ * when the panel's list happens to be scrolling, by its scrollbar too. Measuring against the parent
+ * panel's actual rendered edge (via `getParentPanelElement` above) gets both of those for free and
+ * keeps the visual gap identical whether or not the parent list happens to be scrolling -- rather
+ * than re-deriving "how much padding/scrollbar is in the way" and landing on a different visual gap
+ * depending on the parent's internal layout.
+ *
+ * @param parentPanelElement The parent Popover's own floating panel element
+ * @param referenceElement The trigger element the submenu is anchored to
+ * @param resolvedPlacement Floating UI's resolved placement (e.g. `"right-start"`)
+ * @returns {number} Additional pixels to add to the base `offset()` `mainAxis` value
+ */
+const getNestedSubmenuClearance = (parentPanelElement, referenceElement, resolvedPlacement) => {
+    const panelRect = parentPanelElement.getBoundingClientRect();
+    const referenceRect = referenceElement.getBoundingClientRect();
+    if (resolvedPlacement.startsWith("right")) {
+        return Math.max(0, panelRect.right - referenceRect.right);
+    }
+    if (resolvedPlacement.startsWith("left")) {
+        return Math.max(0, referenceRect.left - panelRect.left);
+    }
+    return 0;
+};
+const rectsOverlap = (a, b) => !(a.x + a.width <= b.x || a.x >= b.x + b.width || a.y + a.height <= b.y || a.y >= b.y + b.height);
+/**
+ * When a nested submenu has shifted horizontally over its parent (cascade-with-overlap), it must
+ * not cover the trigger row that opened it. Returns a new `y` that places the floating panel
+ * entirely below or above the reference -- whichever side has more room -- or `null` when the
+ * panels do not overlap and no adjustment is needed.
+ */
+const getYToClearReference = ({ floatingX, floatingY, floatingWidth, floatingHeight, reference, gap, viewportHeight, padding, }) => {
+    const floating = { x: floatingX, y: floatingY, width: floatingWidth, height: floatingHeight };
+    if (!rectsOverlap(floating, reference)) {
+        return null;
+    }
+    const spaceBelow = viewportHeight - padding - (reference.y + reference.height);
+    const spaceAbove = reference.y - padding;
+    if (spaceBelow >= spaceAbove) {
+        return reference.y + reference.height + gap;
+    }
+    return reference.y - floatingHeight - gap;
+};
+
 const PADDING = 12;
+/**
+ * Width budget passed into `getMaxWidthValue` / `getMinWidthValue` from `size()`'s `apply()`.
+ *
+ * For nested horizontal submenus, Floating UI's side-relative `availableWidth` is only the
+ * remaining strip beside the parent panel. Capping to that shrinks the panel until `shift` no
+ * longer sees overflow -- so the intentional "cascade with overlap" path never runs, and any
+ * CSS min-width on the content (e.g. `MenuContent`'s `min-w-[200px]`) then overflows the
+ * wrapper and the page.
+ *
+ * Using the viewport width as the budget keeps the panel at its preferred size; `flip` still
+ * tries both sides, and `shift` slides it over the parent when neither side fits.
+ */
+const getFloatingWidthBudget = ({ availableWidth, viewportWidth, preferViewportBudget, }) => (preferViewportBudget ? viewportWidth : availableWidth);
+/**
+ * Options for Floating UI's `shift()` middleware.
+ *
+ * For `right`/`left` placement, `shift`'s default only moves along the alignment (vertical) axis.
+ * Nested horizontal submenus need `crossAxis: true` so they can slide horizontally over the parent
+ * when neither side has room -- the "cascade with overlap" path paired with `getFloatingWidthBudget`.
+ */
+const getShiftOptions = ({ isNestedHorizontal, }) => isNestedHorizontal ? { padding: PADDING, crossAxis: true } : { padding: PADDING };
 /**
  * Converts a width size value into a CSS dimension value for max constraints
  *
@@ -239,13 +444,20 @@ const getMaxWidthValue = ({ value, referenceWidth, availableWidth }) => {
     }
 };
 /**
- * Converts a width size value into a CSS dimension value for min constraints
+ * Converts a width size value into a CSS dimension value for min constraints.
+ *
+ * A numeric `value` is clamped to `availableWidth` so a caller's desired minimum can never force the
+ * floating panel wider than the viewport space `size()` already determined was safe -- without this, a
+ * fixed minWidth would win a losing fight against `getMaxWidthValue`'s cap (CSS resolves `min-width` over
+ * `max-width` on conflict) and the panel would overflow past its container/viewport edge instead of
+ * shrinking to fit.
  *
  * @param params - The parameters object
  * @param params.value - The size value: number for pixels, "trigger-width" to match trigger, "none" for no constraint
  * @param params.referenceWidth - The width of the trigger element in pixels
+ * @param params.availableWidth - The available width in the viewport
  */
-const getMinWidthValue = ({ value, referenceWidth, }) => {
+const getMinWidthValue = ({ value, referenceWidth, availableWidth }) => {
     switch (value) {
         case "trigger-width": {
             return `${referenceWidth}px`;
@@ -256,7 +468,7 @@ const getMinWidthValue = ({ value, referenceWidth, }) => {
         }
         default: {
             if (typeof value === "number") {
-                return `${value}px`;
+                return `${Math.max(0, Math.min(value, availableWidth - PADDING * 2))}px`;
             }
             throw new Error(`${value} is not known`);
         }
@@ -304,6 +516,248 @@ const getMinHeightValue = ({ value }) => {
     }
 };
 
+/**
+ * Module-level (not React state) tracking of whether hover-driven `Popover` opening should be
+ * held back right now, because scrolling is either happening or has not yet settled.
+ *
+ * ### Root cause this guards against
+ * Scrolling any container recomputes the browser's pointer hit-test target on every frame, which
+ * fires real `pointerenter`/`pointerleave` pairs on whichever element now sits under an
+ * otherwise-stationary cursor -- indistinguishable, at the DOM level, from the user actually
+ * hovering that element. A hover-activated `Popover` reacting to those phantom events opens every
+ * row a scrolling list happens to carry under the cursor (most visible with `MenuItem`'s nested
+ * submenus in a scrolling list, but the same browser behavior affects any hover-activated
+ * `Popover`, e.g. a `Tooltip` over a scrolling table row).
+ *
+ * ### Why "settled", not "next pointer move"
+ * An earlier version of this guard cleared suppression on the next genuine `pointermove`, so a
+ * still-scrolling list would keep flipping back and forth between "suppressed" and "open the row
+ * the cursor happens to be over this frame" the moment the user so much as twitched the mouse
+ * mid-scroll. That's backwards from how this is meant to feel: while the list is moving, whatever
+ * was hovered before the scroll started should just stay put, and only once the scroll actually
+ * comes to rest should the row the cursor now stably rests over take over. Debouncing off the
+ * `scroll` event itself -- clearing suppression only after a lull longer than
+ * {@link SCROLL_SETTLE_DELAY_MS} with no further scroll events -- gets exactly that: suppression
+ * spans the whole scroll gesture (however bumpy), not just individual frames of it.
+ *
+ * ### Why not intercept/cancel the phantom event instead
+ * `mouseenter`/`pointerenter` don't natively bubble, so React simulates their capture/bubble
+ * dispatch internally -- not a stable surface to hook into from outside, and Floating UI's
+ * `useHover` owns that event handling anyway (it also drives `handleClose`/`safePolygon`, which
+ * still needs to work normally). Gating hover on "no scroll event anywhere in the last
+ * {@link SCROLL_SETTLE_DELAY_MS}ms" gets the same real-world result without any of that.
+ *
+ * ### Why page-wide listeners, not scoped to a particular scroll container
+ * A `scroll` event reaches a capturing-phase listener on `document` regardless of which element
+ * scrolled or whether the event itself bubbles, so a single pair of listeners here -- shared by
+ * every *opted-in* hover instance on the page, rather than each one attaching its own -- is both
+ * simpler and cheaper than resolving each `Popover`'s own scrollable ancestors. Subscription is
+ * gated in `usePopover` to delayed-hover nested `MenuTree` members only (ADR-0002), so plain
+ * Popovers/tooltips never attach the listeners or inherit suppression. The remaining trade-off is
+ * that scrolling *anywhere* briefly holds back hover-opens for those opted-in menu rows, not just
+ * near the scrolling container; acceptable since the guard clears itself shortly after scrolling
+ * settles, wherever the cursor then happens to rest.
+ *
+ * ### Visual hover highlight (CSS)
+ * The same scroll-induced `:hover` flips that would open phantom submenus also restyle every row
+ * the cursor passes over via CSS `:hover` backgrounds -- even while this guard holds the *open*
+ * state still. Consumers that want the highlight to freeze with the open state (notably
+ * `MenuItem`) key off {@link HOVER_SCROLL_SUPPRESSED_ATTR} on `<html>`, which this module mirrors
+ * onto the document in lockstep with suppression, so the highlight can follow open-state rules
+ * without re-rendering every row on each scroll tick.
+ *
+ * ### Why this also tracks the last real pointer position
+ * Once scrolling settles, `useHoverScrollGuard` needs to know which element the cursor now rests
+ * over so it can open that one. The obvious answer -- ask the browser via `:hover` -- turns out
+ * not to work: browsers only recompute an element's cached `:hover` state in response to a new
+ * real pointer event, not just because a re-render or attribute change made it hit-testable again.
+ * Since scrolling itself is exactly what carried the cursor's hit-test target across a run of rows
+ * without the physical mouse ever moving, there's typically no fresh pointer event left to trigger
+ * that recomputation right when settling happens -- so `:hover` stays stuck reporting whatever it
+ * last had, easily confirmed by comparing it against `document.elementFromPoint` at the same
+ * coordinates, which performs a fresh, on-demand hit-test instead of reading a cached flag. Tracking
+ * real client coordinates here (via a `pointermove` listener, sharing this module's lifecycle) lets
+ * `useHoverScrollGuard` run that same fresh `elementFromPoint` check itself once settled, rather
+ * than trusting a pseudo-class the browser hasn't gotten around to updating yet.
+ */
+const HOVER_SCROLL_SUPPRESSED_ATTR = "data-hover-scroll-suppressed";
+/**
+ * How long a lull in `scroll` events must last before scrolling is considered "settled" and
+ * suppression clears. Long enough to swallow the gap between individual momentum-scroll frames
+ * (which can easily exceed a single animation frame), short enough that the now-stable hover
+ * still feels immediate once the list actually stops.
+ */
+const SCROLL_SETTLE_DELAY_MS = 100;
+let isSuppressed = false;
+let settleTimeoutId = null;
+const listeners = new Set();
+let listenerRefCount = 0;
+/** Last real pointer position seen anywhere on the page, in viewport (`clientX`/`clientY`) coordinates. */
+let lastPointerPosition = null;
+const notify = () => {
+    listeners.forEach(listener => listener());
+};
+const setSuppressed = (next) => {
+    if (isSuppressed === next) {
+        return;
+    }
+    isSuppressed = next;
+    if (next) {
+        document.documentElement.setAttribute(HOVER_SCROLL_SUPPRESSED_ATTR, "");
+    }
+    else {
+        document.documentElement.removeAttribute(HOVER_SCROLL_SUPPRESSED_ATTR);
+    }
+    notify();
+};
+const clearSettleTimeout = () => {
+    if (settleTimeoutId !== null) {
+        clearTimeout(settleTimeoutId);
+        settleTimeoutId = null;
+    }
+};
+const handleScroll = () => {
+    setSuppressed(true);
+    // Every scroll event pushes the settle deadline back out -- suppression only clears once a full
+    // `SCROLL_SETTLE_DELAY_MS` lull passes with no further scrolling, however long the gesture itself
+    // (or its momentum tail) runs.
+    clearSettleTimeout();
+    settleTimeoutId = setTimeout(() => {
+        settleTimeoutId = null;
+        setSuppressed(false);
+    }, SCROLL_SETTLE_DELAY_MS);
+};
+const handlePointerMove = (event) => {
+    lastPointerPosition = { x: event.clientX, y: event.clientY };
+};
+const hoverScrollGuard = {
+    isSuppressed: () => isSuppressed,
+    /**
+     * The last real pointer position seen anywhere on the page, or `null` if no `pointermove` has
+     * happened yet (e.g. scrolling driven by keyboard/touch before any mouse input). See this
+     * module's doc comment for why consumers should use this over reading `:hover` directly.
+     */
+    getLastPointerPosition: () => lastPointerPosition,
+    /**
+     * Subscribes to changes in suppression state, lazily attaching the shared `scroll` listener on
+     * first subscriber and tearing it down once the last one unsubscribes.
+     *
+     * @param listener Called whenever suppression state flips
+     * @returns {() => void} Unsubscribe function
+     */
+    subscribe: (listener) => {
+        listeners.add(listener);
+        if (listenerRefCount === 0) {
+            document.addEventListener("scroll", handleScroll, { capture: true, passive: true });
+            document.addEventListener("pointermove", handlePointerMove, { capture: true, passive: true });
+        }
+        listenerRefCount += 1;
+        return () => {
+            listeners.delete(listener);
+            listenerRefCount -= 1;
+            if (listenerRefCount === 0) {
+                document.removeEventListener("scroll", handleScroll, { capture: true });
+                document.removeEventListener("pointermove", handlePointerMove, { capture: true });
+                // Tear down can race a mid-suppression unmount (e.g. the whole menu closing while the list
+                // is still scrolling). Clear the pending timeout and the root attribute here so neither can
+                // outlive every consumer.
+                clearSettleTimeout();
+                setSuppressed(false);
+                lastPointerPosition = null;
+            }
+        };
+    },
+};
+
+const subscribeNoop = (_onStoreChange) => () => undefined;
+const alwaysFalse = () => false;
+/**
+ * Wires a single `Popover`'s hover interaction up to the shared `hoverScrollGuard`: holds its
+ * hover-opens back for as long as scrolling anywhere on the page hasn't yet settled (see
+ * `hoverScrollGuard`'s own doc comment for the full root-cause rationale), and -- once it settles
+ * -- imperatively opens this `Popover` if the cursor turns out to be resting on it, bypassing any
+ * open delay.
+ *
+ * ### Why the open needs its own imperative check
+ * Scrolling can carry the cursor's hit-test target across a whole run of rows without the physical
+ * cursor ever moving, so by the time scrolling settles there is no fresh `pointerenter` left for
+ * `useHover` to react to on whichever row the cursor ends up over: entering already happened
+ * (suppressed) while the list was still moving, not as a new enter.
+ *
+ * ### Why `elementFromPoint`, not `:hover`
+ * The obvious way to ask "is the cursor over this element right now" is `element.matches(":hover")`
+ * -- but browsers only recompute that cached flag in response to a *new* real pointer event, not
+ * just because the element became hit-testable again. Scrolling is exactly what leaves no such event
+ * behind at the moment settling happens, so `:hover` reports stale information right when it's
+ * needed most. `document.elementFromPoint` performs a fresh, on-demand hit-test instead of reading a
+ * cached flag, so it agrees with reality even when `:hover` hasn't caught up yet. It's checked
+ * against the last real pointer position `hoverScrollGuard` tracked (see that module's doc comment)
+ * rather than this reference's own bounding box, so it naturally returns nothing (and this correctly
+ * no-ops) if another element -- e.g. a still-open popover -- now sits on top of it.
+ *
+ * @param options See `UseHoverScrollGuardOptions`
+ * @param options.enabled Whether this consumer should subscribe to the shared scroll guard
+ * @param options.hoverEnabled Whether this `Popover`'s own `activation.hover` is enabled at all
+ * @param options.openSiblingPinned See `usePopover`'s own `openSiblingPinned`
+ * @param options.isOpen Whether this `Popover` is already open
+ * @param options.popoverContext This `Popover`'s own Floating UI context
+ * @param options.referenceRef This `Popover`'s reference element ref
+ * @returns {boolean} Whether hover-opens should be held back right now -- fold into `useHover`'s
+ * own `enabled` option alongside this `Popover`'s other activation conditions
+ */
+const useHoverScrollGuard = ({ enabled, hoverEnabled, openSiblingPinned, isOpen, popoverContext, referenceRef, }) => {
+    // Subscribe only while this Popover opts into the guard. The shared store lazily attaches
+    // document listeners on the first subscriber — gating here keeps plain Popovers/tooltips from
+    // pulling the page-wide suppression net in (ADR-0002).
+    const isHoverScrollSuppressed = useSyncExternalStore(enabled ? hoverScrollGuard.subscribe : subscribeNoop, enabled ? hoverScrollGuard.isSuppressed : alwaysFalse, alwaysFalse);
+    // Read fresh inside the transition effect below via `.current`, rather than listed as that
+    // effect's own dependencies -- it only actually needs to look at the *edge* of suppression
+    // turning off, not re-run this check on every unrelated render any of these happen to change on
+    // too (e.g. the floating position recomputing on every scroll frame while still suppressed).
+    const latestGateRef = useRef({ enabled, hoverEnabled, openSiblingPinned, isOpen, popoverContext, referenceRef });
+    useEffect(() => {
+        latestGateRef.current = { enabled, hoverEnabled, openSiblingPinned, isOpen, popoverContext, referenceRef };
+    }, [enabled, hoverEnabled, openSiblingPinned, isOpen, popoverContext, referenceRef]);
+    // Tracks whether the *previous* run of the effect below saw suppression active, so that effect
+    // can tell a genuine "just settled" transition apart from simply mounting into an already-clear
+    // state. Without this, every fresh mount whose `isHoverScrollSuppressed` happens to already be
+    // `false` (the common case -- most `Popover`s mount outside of any scroll gesture) would run the
+    // open-check below regardless, with no real settle having ever happened. That's most visible for
+    // a freshly-opened `MenuTree`: the cursor is still resting wherever the trigger button was
+    // clicked, which is often right where the first row now renders, so every row's guard would
+    // otherwise treat its own very first mount as if scrolling had just settled over it and hover-open
+    // itself instantly, bypassing the open delay entirely.
+    const wasSuppressedRef = useRef(isHoverScrollSuppressed);
+    useEffect(() => {
+        const wasSuppressed = wasSuppressedRef.current;
+        wasSuppressedRef.current = isHoverScrollSuppressed;
+        if (!enabled || isHoverScrollSuppressed || !wasSuppressed) {
+            return;
+        }
+        const { hoverEnabled: latestHoverEnabled, openSiblingPinned: latestOpenSiblingPinned, isOpen: latestIsOpen, popoverContext: latestPopoverContext, referenceRef: latestReferenceRef, } = latestGateRef.current;
+        if (!latestHoverEnabled || latestOpenSiblingPinned || latestIsOpen) {
+            return;
+        }
+        const referenceElement = latestReferenceRef.current;
+        const pointerPosition = hoverScrollGuard.getLastPointerPosition();
+        // jsdom (used by every non-browser test in this repo) doesn't implement `elementFromPoint` at
+        // all, unlike every real browser -- guarded rather than assumed so tests exercising this
+        // codepath incidentally (e.g. via `userEvent.hover` tracking a pointer position) don't crash.
+        if (referenceElement instanceof Element &&
+            pointerPosition !== null &&
+            typeof document.elementFromPoint === "function") {
+            const elementAtPointer = document.elementFromPoint(pointerPosition.x, pointerPosition.y);
+            if (elementAtPointer !== null && referenceElement.contains(elementAtPointer)) {
+                // No real triggering event to forward: scrolling settling isn't itself a pointer event, and
+                // by this point there may be no fresh `pointerenter` at all for this reference (see the doc
+                // comment above).
+                latestPopoverContext.onOpenChange(true, undefined, "hover");
+            }
+        }
+    }, [enabled, isHoverScrollSuppressed]);
+    return enabled && isHoverScrollSuppressed;
+};
+
 const DEFAULT_ACTIVATION = { click: true, hover: false, keyboardHandlers: true };
 const DEFAULT_DISMISSAL = {
     enabled: true,
@@ -316,6 +770,60 @@ const DEFAULT_SIZING = {
     minHeight: "none",
     maxHeight: "none",
 };
+const isVerticalPlacement = (resolvedPlacement) => resolvedPlacement.startsWith("top") || resolvedPlacement.startsWith("bottom");
+/**
+ * The sole fallback for a nested horizontal submenu's `flip` (see `middleware` below): the mirrored
+ * placement on the opposite horizontal side, same alignment. Deliberately excludes any vertical
+ * placement -- a submenu that can't fit on either horizontal side should stay horizontal and
+ * cascade with overlap (via `shift({ crossAxis: true })` below) rather than flip above/below the
+ * parent panel. When that overlap would cover the trigger row, a follow-up middleware nudges the
+ * submenu above or below the trigger so the invoking item stays visible.
+ */
+const getOppositeHorizontalPlacement = (placement) => {
+    switch (placement) {
+        case "right":
+            return "left";
+        case "right-start":
+            return "left-start";
+        case "right-end":
+            return "left-end";
+        case "left":
+            return "right";
+        case "left-start":
+            return "right-start";
+        case "left-end":
+            return "right-end";
+        default:
+            return placement;
+    }
+};
+/**
+ * The gap between a nested submenu and its parent panel, along whichever axis it opens on --
+ * shared so the vertical and horizontal nested-placement branches below stay in sync.
+ */
+const NESTED_SUBMENU_GAP = 2;
+/**
+ * Once a branch is already "engaged" (see `hasOpenSibling` below), how long the pointer must stop
+ * moving over a sibling row before it switches to it. Deliberately short -- long enough to filter
+ * out a row the cursor merely swept across while heading elsewhere, short enough that a genuine
+ * hover still feels instant, matching native menu-bar behavior.
+ */
+const SIBLING_HOVER_SWITCH_REST_MS = 75;
+/**
+ * When a nested submenu falls back to a vertical placement, slide it as far as
+ * possible along the cross axis (left or right) so it visually separates from the
+ * parent panel instead of sitting almost flush on top of it.
+ */
+const getNestedVerticalAlignmentAxis = ({ rects }) => {
+    const refRect = rects.reference;
+    const floatingWidth = rects.floating.width;
+    const spaceRight = window.innerWidth - PADDING - refRect.x - floatingWidth;
+    const spaceLeft = refRect.x - PADDING;
+    if (spaceRight >= spaceLeft) {
+        return Math.max(0, spaceRight);
+    }
+    return -Math.max(0, spaceLeft);
+};
 /**
  * The hook that powers the Popover component.
  * It should not be used directly, but rather through the Popover component.
@@ -323,67 +831,308 @@ const DEFAULT_SIZING = {
  * @param {PopoverProps} options The options for the popover
  * @returns {UsePopoverType} The data for the popover
  */
-const usePopover = ({ initialOpen = false, placement = "bottom", isModal, isOpen: controlledIsOpen, activation = DEFAULT_ACTIVATION, dismissal = DEFAULT_DISMISSAL, sizing = DEFAULT_SIZING, onOpenStateChange, id, className, "data-testid": dataTestId, }) => {
+const usePopover = ({ initialOpen = false, placement = "bottom", isModal, isOpen: controlledIsOpen, activation = DEFAULT_ACTIVATION, dismissal = DEFAULT_DISMISSAL, sizing = DEFAULT_SIZING, onOpenStateChange, role = "dialog", id, className, "data-testid": dataTestId, }) => {
     const [uncontrolledIsOpen, setUncontrolledIsOpen] = useState(initialOpen);
     const [labelId, setLabelId] = useState();
     const [descriptionId, setDescriptionId] = useState();
     const isOpen = controlledIsOpen ?? uncontrolledIsOpen;
+    const { nodeId, parentId, isNested, tree } = useMenuTree();
+    const isInsideMenuTree = tree !== null && isNested;
+    const isHorizontallyPlaced = placement.startsWith("right") || placement.startsWith("left");
+    const middleware = useMemo(() => [
+        // `offset()` must run before `flip()`/`shift()` -- Floating UI evaluates those against the
+        // *current* computed position, so they only see the gap `offset()` adds (including the
+        // scrollbar clearance below) if it has already run. With the order reversed, `flip()` would
+        // decide whether a nested submenu fits using the reference's bare edge, then `offset()` could
+        // push it past the boundary `flip()` just approved. `flip()` resets the lifecycle whenever it
+        // changes the placement, so `offset()` below still re-runs (and re-resolves its
+        // placement-dependent branches) for whichever placement `flip()` settles on.
+        offset(placementState => {
+            const { placement: resolvedPlacement, elements } = placementState;
+            if (isInsideMenuTree && isVerticalPlacement(resolvedPlacement)) {
+                return {
+                    mainAxis: NESTED_SUBMENU_GAP,
+                    alignmentAxis: getNestedVerticalAlignmentAxis(placementState),
+                };
+            }
+            // A nested submenu's `elements.reference` is its trigger row, not the parent panel -- and
+            // that row's own edge is inset from the parent panel's true edge by the panel's padding
+            // (and, when its list is scrolling, by its scrollbar too). Clearing the parent panel's
+            // actual edge instead keeps the visual gap identical either way.
+            if (isInsideMenuTree && elements.reference instanceof HTMLElement) {
+                const parentPanel = getParentPanelElement(tree, parentId);
+                if (parentPanel !== null) {
+                    return {
+                        mainAxis: NESTED_SUBMENU_GAP + getNestedSubmenuClearance(parentPanel, elements.reference, resolvedPlacement),
+                    };
+                }
+            }
+            return 8;
+        }),
+        isInsideMenuTree && isHorizontallyPlaced
+            ? flip({ crossAxis: false, fallbackPlacements: [getOppositeHorizontalPlacement(placement)] })
+            : flip({ fallbackPlacements: ["top", "bottom", "right", "left"] }),
+        shift(getShiftOptions({ isNestedHorizontal: isInsideMenuTree && isHorizontallyPlaced })),
+        {
+            // After horizontal cascade-with-overlap, keep the trigger row uncovered by sliding the
+            // submenu above or below it (see `getYToClearReference`). Side-by-side placement leaves
+            // the trigger clear already, so this is a no-op in that case.
+            name: "clearNestedTrigger",
+            fn({ x, y, rects }) {
+                if (!(isInsideMenuTree && isHorizontallyPlaced)) {
+                    return {};
+                }
+                const nextY = getYToClearReference({
+                    floatingX: x,
+                    floatingY: y,
+                    floatingWidth: rects.floating.width,
+                    floatingHeight: rects.floating.height,
+                    reference: rects.reference,
+                    gap: NESTED_SUBMENU_GAP,
+                    viewportHeight: window.innerHeight,
+                    padding: PADDING,
+                });
+                return nextY === null ? {} : { y: nextY };
+            },
+        },
+        size({
+            apply({ availableWidth, availableHeight, elements }) {
+                const { floating, reference } = elements;
+                const resolvedSizing = typeof sizing === "function" ? sizing(DEFAULT_SIZING) : sizing;
+                const refRect = reference.getBoundingClientRect();
+                // Nested horizontal submenus must keep a viewport-sized width budget so `shift` can
+                // cascade with overlap when neither side fits -- see `getFloatingWidthBudget`.
+                const widthBudget = getFloatingWidthBudget({
+                    availableWidth,
+                    viewportWidth: window.innerWidth,
+                    preferViewportBudget: isInsideMenuTree && isHorizontallyPlaced,
+                });
+                Object.assign(floating.style, {
+                    maxWidth: getMaxWidthValue({
+                        value: resolvedSizing.maxWidth,
+                        referenceWidth: refRect.width,
+                        availableWidth: widthBudget,
+                    }),
+                    minWidth: getMinWidthValue({
+                        value: resolvedSizing.minWidth,
+                        referenceWidth: refRect.width,
+                        availableWidth: widthBudget,
+                    }),
+                    maxHeight: getMaxHeightValue({
+                        value: resolvedSizing.maxHeight,
+                        availableHeight,
+                    }),
+                    minHeight: getMinHeightValue({
+                        value: resolvedSizing.minHeight,
+                    }),
+                });
+            },
+        }),
+    ], [isInsideMenuTree, isHorizontallyPlaced, placement, sizing, tree, parentId]);
+    // Remembers *how* this node was last (re-)opened (see `MenuTreeOpenEvent.reason`) so it can be
+    // relayed to siblings on the `MENU_TREE_OPEN_EVENT` emit below. State, not a ref: Floating UI's
+    // `useClick` calls `onOpenChange(true, event, "click")` on every click of the reference *even
+    // while already open* (its "reaffirm" behavior for `stickIfOpen`) without that changing `isOpen`
+    // itself -- e.g. the row was already open from a hover, and the user then clicks it. That reason
+    // upgrade (hover -> click) needs its own render so the emit effect below re-runs and rebroadcasts
+    // it; a ref's mutation wouldn't be visible to that effect's dependency array.
+    const [openReason, setOpenReason] = useState(undefined);
     const popoverData = useFloating({
+        nodeId,
         placement,
         open: isOpen,
-        onOpenChange: open => {
+        onOpenChange: (open, _event, reason) => {
             setUncontrolledIsOpen(open);
             onOpenStateChange?.(open);
+            // Reset to `undefined` on close (regardless of *how* it closed) rather than keeping the close
+            // reason around -- a later open that bypasses `onOpenChange` entirely (e.g. `MenuItem`'s
+            // `ArrowRight` keyboard shortcut, which sets the controlled `isOpen` state directly) should
+            // never be judged against a stale reason left over from a previous open/close cycle.
+            setOpenReason(open ? reason : undefined);
         },
         whileElementsMounted: autoUpdate,
-        middleware: [
-            offset(8),
-            flip({ fallbackPlacements: ["top", "bottom", "right", "left"] }),
-            shift({ padding: PADDING }),
-            size({
-                apply({ availableWidth, availableHeight, elements }) {
-                    const { floating, reference } = elements;
-                    const resolvedSizing = typeof sizing === "function" ? sizing(DEFAULT_SIZING) : sizing;
-                    const refRect = reference.getBoundingClientRect();
-                    Object.assign(floating.style, {
-                        maxWidth: getMaxWidthValue({
-                            value: resolvedSizing.maxWidth,
-                            referenceWidth: refRect.width,
-                            availableWidth,
-                        }),
-                        minWidth: getMinWidthValue({
-                            value: resolvedSizing.minWidth,
-                            referenceWidth: refRect.width,
-                        }),
-                        maxHeight: getMaxHeightValue({
-                            value: resolvedSizing.maxHeight,
-                            availableHeight,
-                        }),
-                        minHeight: getMinHeightValue({
-                            value: resolvedSizing.minHeight,
-                        }),
-                    });
-                },
-            }),
-        ],
+        middleware,
     });
+    const updatePositionRef = useRef(popoverData.update);
+    // useFloating keeps the last resolved x/y/placement across close cycles. Painting the
+    // floating node at those stale coordinates before the next compute corrupts flip/shift
+    // overflow measurements (seen when reopening a submenu after a viewport resize).
+    const isPlacementReady = isOpen && popoverData.isPositioned;
+    useLayoutEffect(() => {
+        const updatePosition = popoverData.update;
+        updatePositionRef.current = updatePosition;
+        if (!isOpen) {
+            return;
+        }
+        updatePosition();
+        const frame = requestAnimationFrame(() => {
+            updatePositionRef.current();
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [isOpen, popoverData.update]);
     const popoverContext = popoverData.context;
     const resolvedActivation = typeof activation === "function" ? activation(DEFAULT_ACTIVATION) : activation;
     const resolvedDismissal = typeof dismissal === "function" ? dismissal(DEFAULT_DISMISSAL) : dismissal;
+    const { outsidePress: configuredOutsidePress, ...restDismissal } = resolvedDismissal;
     const clickInteraction = useClick(popoverContext, {
         enabled: resolvedActivation.click,
         keyboardHandlers: resolvedActivation.keyboardHandlers,
     });
-    const dismissInteraction = useDismiss(popoverContext, resolvedDismissal);
+    // Whether this node is part of a `MenuTree` at all (root or nested) -- as opposed to
+    // `isInsideMenuTree`, which is only true for *nested* members. A tree's root has no ancestor to
+    // defer to, but it's exactly as likely as a nested node to have a click land on one of its own
+    // (possibly deeply nested) open descendants, so it needs the same tree-aware outside-press check.
+    const isPartOfMenuTree = tree !== null;
+    const dismissInteraction = useDismiss(popoverContext, {
+        ...restDismissal,
+        outsidePress: event => {
+            if (typeof configuredOutsidePress === "function") {
+                if (!configuredOutsidePress(event)) {
+                    return false;
+                }
+            }
+            else if (configuredOutsidePress === false) {
+                return false;
+            }
+            // A press anywhere inside the tree (this node's own content, a sibling row, or a nested
+            // descendant's floating panel) is never "outside" for *any* tree member -- root included.
+            // Without this, a root `Popover` falls back to Floating UI's own DOM-containment check,
+            // which isn't reliable the instant a descendant opens/closes and reflows the tree's DOM
+            // (e.g. a hover-delayed submenu finishing its open transition), and can spuriously collapse
+            // the whole tree instead of just switching between sibling rows.
+            if (isPartOfMenuTree) {
+                return !isPressInsideMenuTree(event, tree);
+            }
+            return true;
+        },
+        // Nested in a MenuTree: Escape closes one level at a time (doesn't bubble to ancestors).
+        // Outside-press bubbles only when the press is genuinely outside the tree; sibling-row
+        // presses are filtered above so they don't collapse the root menu.
+        bubbles: isInsideMenuTree ? { escapeKey: false, outsidePress: true } : undefined,
+    });
     const hoverOptions = typeof resolvedActivation.hover === "object" ? resolvedActivation.hover : undefined;
     const hoverEnabled = hoverOptions ? (hoverOptions.active ?? true) : resolvedActivation.hover === true;
     const hoverInteractable = hoverOptions?.interactable ?? true;
+    const isHoverDelayed = hoverOptions?.delayed === true;
+    // Once a sibling under the same parent has opened *via hover*, this branch of the tree is
+    // already "engaged" -- hovering between sibling rows should switch instantly from then on,
+    // matching native OS/browser menu-bar behavior, instead of re-running the accidental-open guard
+    // delay for every single row. Without this, switching from an already-open sibling to this row
+    // hits the full open delay on *every* hover, leaving neither submenu visible for that whole
+    // window. Only tracked when this node actually uses a delayed hover-open -- other `Popover`s
+    // don't pay for the extra tree subscription.
+    const [hasOpenSibling, setHasOpenSibling] = useState(false);
+    // A sibling opened by an explicit action (a click, or any reason other than a bare hover --
+    // e.g. the `ArrowRight` keyboard shortcut) reflects deliberate user intent to inspect *that* row,
+    // not "I'm passing through the list". Hovering a different row shouldn't steal it away the moment
+    // the cursor happens to drift, so hover-to-open is disabled outright for the rest of the branch
+    // until that click-opened sibling closes again (`MENU_TREE_CLOSE_EVENT` below clears this).
+    const [openSiblingPinned, setOpenSiblingPinned] = useState(false);
+    // Which sibling is currently responsible for `openSiblingPinned` being `true`, so a *different*
+    // sibling closing doesn't clear it. Needed because clicking a sibling while another one is
+    // already open (click-)pinned emits two tree events in sequence: this row's own
+    // `MENU_TREE_OPEN_EVENT` (which pins everyone else), immediately followed by the previously-open
+    // sibling's cascade `MENU_TREE_CLOSE_EVENT` once `MenuTreeSiblingCloseBoundary` closes it. Without
+    // tracking the source, that stale close event would wipe out the pin the newer open just set. A
+    // ref (not state): read and written only from within the event handlers below, never needs to
+    // trigger a render itself.
+    const pinnedBySiblingIdRef = useRef(null);
+    useEffect(() => {
+        if (!tree || !isHoverDelayed) {
+            return;
+        }
+        const handleSiblingOpen = ({ nodeId: openedNodeId, parentId: openedParentId, reason, isMenuRow, }) => {
+            if (!isMenuRow || openedNodeId === nodeId || openedParentId !== parentId) {
+                return;
+            }
+            if (reason === "hover") {
+                setHasOpenSibling(true);
+                setOpenSiblingPinned(false);
+                pinnedBySiblingIdRef.current = null;
+            }
+            else {
+                setOpenSiblingPinned(true);
+                pinnedBySiblingIdRef.current = openedNodeId;
+            }
+        };
+        const handleSiblingClose = ({ nodeId: closedNodeId, parentId: closedParentId, isMenuRow, }) => {
+            if (isMenuRow &&
+                closedNodeId !== nodeId &&
+                closedParentId === parentId &&
+                pinnedBySiblingIdRef.current === closedNodeId) {
+                setOpenSiblingPinned(false);
+                pinnedBySiblingIdRef.current = null;
+            }
+        };
+        tree.events.on(MENU_TREE_OPEN_EVENT, handleSiblingOpen);
+        tree.events.on(MENU_TREE_CLOSE_EVENT, handleSiblingClose);
+        return () => {
+            tree.events.off(MENU_TREE_OPEN_EVENT, handleSiblingOpen);
+            tree.events.off(MENU_TREE_CLOSE_EVENT, handleSiblingClose);
+        };
+    }, [tree, nodeId, parentId, isHoverDelayed]);
+    // See `useHoverScrollGuard`'s doc comment for the full rationale: holds hover-opens back while a
+    // scroll anywhere on the page is more recent than the last genuine pointer move, so a list
+    // scrolling underneath a stationary cursor can't fire a cascade of phantom opens.
+    // Scoped to delayed-hover *nested* MenuTree members so plain Popovers/tooltips stay unaffected
+    // (ADR-0002 opt-in boundary).
+    const isHoverScrollSuppressed = useHoverScrollGuard({
+        enabled: isInsideMenuTree && isHoverDelayed,
+        hoverEnabled,
+        openSiblingPinned,
+        isOpen,
+        popoverContext,
+        referenceRef: popoverData.refs.reference,
+    });
     const hoverInteraction = useHover$1(popoverContext, {
-        enabled: hoverEnabled,
-        delay: hoverOptions?.delayed === true ? { open: 400 } : undefined,
-        handleClose: hoverEnabled === true && hoverInteractable === true ? safePolygon() : undefined,
+        enabled: hoverEnabled && !openSiblingPinned && !isHoverScrollSuppressed,
+        delay: isHoverDelayed && !hasOpenSibling ? { open: 400 } : undefined,
+        // Once a sibling is already open, switching rows drops the upfront delay above to feel
+        // instant -- but with no delay/`restMs` at all, a cursor merely *passing through* this row en
+        // route to the already-open sibling's submenu (e.g. cutting diagonally across the list to
+        // reach a flyout that opens further up or down) would flash this row open too, stealing the
+        // flyout away from the row the user was actually heading toward. `restMs` only starts counting
+        // once `mousemove` stops moving *significantly* within this row -- every further significant
+        // move resets it -- so a fast pass-through never accumulates enough dwell time to open, while a
+        // genuine stop (even a brief one) still switches near-instantly. Only meaningful in the
+        // `hasOpenSibling` branch: `PopoverTrigger` force-exempts every `MenuTree` row from the
+        // `blockPointerEvents` block below via `pointer-events-auto` (see its own comment) so rows stay
+        // clickable while that block is active elsewhere in the branch -- which also means a row's
+        // *own* hover keeps firing for a merely passing-through cursor unless gated here.
+        restMs: isHoverDelayed && hasOpenSibling ? SIBLING_HOVER_SWITCH_REST_MS : undefined,
+        // Floating UI's default `move: true` also opens on a bare `mousemove` over the reference (not
+        // just `mouseenter`) -- meant for content that appears under an already-resting cursor. That's
+        // not a real intent signal for a MenuTree row (a mousemove without a preceding mouseenter is
+        // most often the browser positioning the cursor for an unrelated click), so it's disabled here
+        // to avoid opening a sibling's submenu from incidental cursor movement. Scoped to MenuTree
+        // members -- standalone (non-tree) Popovers keep today's exact behavior.
+        move: isPartOfMenuTree ? false : undefined,
+        // blockPointerEvents lets a nested row's submenu survive the cursor travelling diagonally
+        // from the trigger to the panel instead of closing when it briefly leaves both elements.
+        // Scoped to MenuTree members so standalone (non-tree) Popovers keep today's exact behavior.
+        handleClose: hoverEnabled === true && hoverInteractable === true
+            ? safePolygon({ blockPointerEvents: isInsideMenuTree })
+            : undefined,
     });
-    const roleInteraction = useRole(popoverContext);
+    const roleInteraction = useRole(popoverContext, { role });
+    // Distinguishes a genuine open -> close transition from this node simply mounting closed (the
+    // common case: every unrelated sibling elsewhere in the tree mounts with `isOpen === false`).
+    // Without this, that initial "closed" render would emit `MENU_TREE_CLOSE_EVENT` regardless, and
+    // any such unrelated sibling mounting while *this* node happens to be click-pinned open would
+    // spuriously clear the pin.
+    const wasOpenRef = useRef(isOpen);
+    useEffect(() => {
+        if (!tree) {
+            return;
+        }
+        if (isOpen) {
+            tree.events.emit(MENU_TREE_OPEN_EVENT, { nodeId, parentId, reason: openReason, isMenuRow: isHoverDelayed });
+        }
+        else if (wasOpenRef.current) {
+            tree.events.emit(MENU_TREE_CLOSE_EVENT, { nodeId, parentId, isMenuRow: isHoverDelayed });
+        }
+        wasOpenRef.current = isOpen;
+    }, [isOpen, openReason, tree, nodeId, parentId, isHoverDelayed]);
     const combinedInteractions = useInteractions([
         clickInteraction,
         hoverInteraction,
@@ -394,19 +1143,21 @@ const usePopover = ({ initialOpen = false, placement = "bottom", isModal, isOpen
         isOpen,
         setIsOpen: setUncontrolledIsOpen,
         ...omit(popoverData, ["middlewareData", "floatingStyles", "elements"]),
-        x: popoverData.x,
-        y: popoverData.y,
-        isPositioned: popoverData.isPositioned,
+        x: isPlacementReady ? popoverData.x : 0,
+        y: isPlacementReady ? popoverData.y : 0,
+        isPositioned: isPlacementReady,
         refs: popoverData.refs,
         update: popoverData.update,
-        placement: popoverData.placement,
+        placement: isPlacementReady ? popoverData.placement : placement,
         strategy: popoverData.strategy,
         ...combinedInteractions,
         isModal,
+        isNested,
         labelId,
         descriptionId,
         setLabelId,
         setDescriptionId,
+        nodeId,
         customProps: {
             id,
             className,
@@ -414,7 +1165,11 @@ const usePopover = ({ initialOpen = false, placement = "bottom", isModal, isOpen
         },
     }), [
         isOpen,
+        isPlacementReady,
+        placement,
         setUncontrolledIsOpen,
+        nodeId,
+        isNested,
         combinedInteractions,
         popoverData,
         isModal,
@@ -427,6 +1182,14 @@ const usePopover = ({ initialOpen = false, placement = "bottom", isModal, isOpen
 };
 
 const PopoverContext = createContext(null);
+/**
+ * Like `usePopoverContext`, but returns `null` instead of throwing when called outside a `<Popover />`.
+ * Used by components (e.g. `MenuContent`) that support being rendered either inside a `Popover` or fully
+ * standalone.
+ *
+ * @returns {ContextType} The popover context, or `null` if there is no ancestor `Popover`
+ */
+const useOptionalPopoverContext = () => useContext(PopoverContext);
 /**
  * A hook to get the popover context.
  * It should only be used by the Popover components.
@@ -434,7 +1197,7 @@ const PopoverContext = createContext(null);
  * @returns {ContextType} The popover context
  */
 const usePopoverContext = () => {
-    const context = useContext(PopoverContext);
+    const context = useOptionalPopoverContext();
     if (context === null) {
         throw new Error("Popover components must be wrapped in <Popover />");
     }
@@ -496,9 +1259,9 @@ const usePopoverContext = () => {
  */
 const Popover = ({ children, isModal = false, ...restOptions }) => {
     const popover = usePopover({ isModal, ...restOptions });
-    return (jsx(PopoverContext.Provider, { value: popover, children: typeof children === "function"
-            ? children({ isOpen: popover.isOpen, setIsOpen: popover.setIsOpen, placement: popover.placement })
-            : children }));
+    return (jsx(FloatingNode, { id: popover.nodeId, children: jsx(PopoverContext.Provider, { value: popover, children: typeof children === "function"
+                ? children({ isOpen: popover.isOpen, setIsOpen: popover.setIsOpen, placement: popover.placement })
+                : children }) }));
 };
 
 /** @internal */
@@ -559,7 +1322,46 @@ const Portal = (props) => {
     return jsx(FloatingPortal, { ...props, root: props.root ?? getDefaultPortalContainer() });
 };
 
-const cvaPopoverContainer = cvaMerge(["component-popover-border", "z-popover", "animate-fade-in-fast"]);
+const OVERFLOW_CLIPS = new Set(["auto", "scroll", "hidden", "clip"]);
+const clips = (overflow) => OVERFLOW_CLIPS.has(overflow);
+const rectsDisjoint = (a, b) => a.right <= b.left || a.left >= b.right || a.bottom <= b.top || a.top >= b.bottom;
+/**
+ * Whether `element` is currently visible to the user -- not clipped out by any scrollable/clipping
+ * ancestor (the browser fact `PopoverContent`'s `returnFocus` needs to respect: focusing a clipped
+ * element still succeeds, and browsers then auto-scroll it into view, fighting whatever caused it
+ * to be clipped in the first place -- see that module's doc comment) and not clipped by the
+ * viewport itself.
+ *
+ * Deliberately synchronous (plain `getBoundingClientRect`/`getComputedStyle` reads) rather than an
+ * `IntersectionObserver`, which only reports asynchronously on its own schedule and can't answer
+ * "is it visible right now" at the exact moment a popover is closing.
+ *
+ * @param element The element to check
+ * @returns {boolean} `false` if `element` (or any ancestor up to the viewport) clips it out
+ */
+const isElementVisible = (element) => {
+    const elementRect = element.getBoundingClientRect();
+    if (elementRect.width === 0 && elementRect.height === 0) {
+        return false;
+    }
+    const viewportRect = { left: 0, top: 0, right: window.innerWidth, bottom: window.innerHeight };
+    if (rectsDisjoint(elementRect, viewportRect)) {
+        return false;
+    }
+    let ancestor = element.parentElement;
+    while (ancestor !== null) {
+        const style = getComputedStyle(ancestor);
+        if (clips(style.overflowX) || clips(style.overflowY)) {
+            if (rectsDisjoint(elementRect, ancestor.getBoundingClientRect())) {
+                return false;
+            }
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return true;
+};
+
+const cvaPopoverContainer = cvaMerge(["z-popover", "animate-fade-in-fast"]);
 const cvaPopoverTitleContainer = cvaMerge(["flex", "items-center", "px-2", "py-1"], {
     variants: {
         divider: {
@@ -570,6 +1372,25 @@ const cvaPopoverTitleContainer = cvaMerge(["flex", "items-center", "px-2", "py-1
 });
 const cvaPopoverTitleText = cvaMerge(["flex-1", "text-neutral-500"]);
 
+/**
+ * Wraps a `returnFocus` ref so Floating UI's live `ref.current` read at close time (see
+ * `FloatingFocusManager`'s `getReturnElement`, which reads `.current` fresh inside its close
+ * cleanup rather than caching it) transparently gets a visibility check first. A getter -- not a
+ * value computed once -- is what makes this "live": consumers just keep the underlying ref pointed
+ * at their normal target and never need to know it might be temporarily unsafe to focus.
+ *
+ * Falls back to Floating UI's own hidden, off-screen fallback element (via returning `null`,
+ * exactly like an empty ref) whenever the target isn't currently visible -- e.g. a `MenuItem` row
+ * that has scrolled out of its list. Without this, focusing a clipped element still succeeds, and
+ * browsers then auto-scroll it into view, fighting whatever caused it to be clipped in the first
+ * place.
+ */
+const withVisibilityCheck = (sourceRef) => ({
+    get current() {
+        const target = sourceRef.current;
+        return target !== null && isElementVisible(target) ? target : null;
+    },
+});
 /**
  * PopoverContent displays the floating content inside a Popover.
  * It renders in a portal and manages focus, positioning, and accessibility. Must be a child of a Popover.
@@ -608,7 +1429,11 @@ const cvaPopoverTitleText = cvaMerge(["flex-1", "text-neutral-500"]);
 const PopoverContent = function PopoverContent({ className, "data-testid": dataTestId, children, portalId, initialFocus, returnFocus = true, ref: propRef, ...props }) {
     const { context: floatingContext, customProps, ...context } = usePopoverContext();
     const ref = useMergeRefs$1([context.refs.setFloating, propRef]);
-    return (jsx(Portal, { id: portalId, children: context.isOpen === true ? (jsx(FloatingFocusManager, { closeOnFocusOut: false, context: floatingContext, guards: true, initialFocus: initialFocus, modal: context.isModal, order: ["reference", "content"], returnFocus: returnFocus, children: jsx("div", { "aria-describedby": context.descriptionId, "aria-labelledby": context.labelId, className: cvaPopoverContainer({ className: className ?? customProps.className }), "data-testid": dataTestId ?? customProps["data-testid"] ?? "popover-content", ref: ref, style: {
+    // Only a ref-based `returnFocus` has a concrete target to check -- the `boolean` case defers to
+    // Floating UI's own app-wide "previously focused element" tracking, which isn't exposed here to
+    // check against.
+    const resolvedReturnFocus = typeof returnFocus === "boolean" ? returnFocus : withVisibilityCheck(returnFocus);
+    return (jsx(Portal, { id: portalId, children: context.isOpen === true ? (jsx(FloatingFocusManager, { closeOnFocusOut: false, context: floatingContext, guards: true, initialFocus: initialFocus, modal: context.isModal, order: ["reference", "content"], returnFocus: resolvedReturnFocus, children: jsx("div", { "aria-describedby": context.descriptionId, "aria-labelledby": context.labelId, className: cvaPopoverContainer({ className: className ?? customProps.className }), "data-testid": dataTestId ?? customProps["data-testid"] ?? "popover-content", ref: ref, style: {
                     position: context.strategy,
                     top: context.y,
                     left: context.x,
@@ -1112,6 +1937,12 @@ const PopoverTrigger = function PopoverTrigger({ children, renderButton = false,
     const context = usePopoverContext();
     const ref = useMergeRefs$1([context.refs.setReference, propRef]);
     const dataState = context.isOpen === true ? "open" : "closed";
+    // While any `MenuTree` member is hover-open with `handleClose`'s `blockPointerEvents`, Floating
+    // UI sets `document.body`'s pointer-events to `none` and only exempts *that* member's own
+    // reference/floating pair -- every sibling row inherits `none` and silently swallows clicks for
+    // as long as the block is active. Forcing `pointer-events: auto` here keeps every tree member's
+    // own trigger clickable regardless of which sibling currently owns that block.
+    const { tree } = useMenuTree();
     if (!renderButton && isValidElement(children)) {
         const referenceProps = context.getReferenceProps({
             ...props,
@@ -1120,9 +1951,14 @@ const PopoverTrigger = function PopoverTrigger({ children, renderButton = false,
         });
         const cloneProps = { ...referenceProps };
         cloneProps.ref = ref;
+        if (tree !== null) {
+            const childClassName = typeof children.props.className === "string" ? children.props.className : "";
+            cloneProps.className = twMerge(childClassName, "pointer-events-auto");
+        }
         return cloneElement(children, cloneProps);
     }
-    return (jsx(Button, { "data-state": dataState, ref: ref, type: "button", ...context.getReferenceProps(props), children: children }));
+    const buttonProps = context.getReferenceProps(props);
+    return (jsx(Button, { "data-state": dataState, ref: ref, type: "button", ...buttonProps, className: tree !== null ? twMerge(props.className, "pointer-events-auto") : props.className, children: children }));
 };
 
 const cvaText = cvaMerge(["text-black", "m-0", "relative", "text-sm", "font-normal"], {
@@ -6390,25 +7226,25 @@ const cvaMenuListMultiSelect = cvaMerge([
 const cvaMenuListItem = cvaMerge("max-w-full");
 
 /**
- * MenuDivider renders a horizontal line to visually separate groups of items within a MenuList.
+ * MenuDivider renders a horizontal line to visually separate groups of items within a MenuContent.
  *
  * ### When to use
  * Use MenuDivider between groups of related `MenuItem` elements to create logical sections within a menu.
  *
  * ### When not to use
- * Do not use MenuDivider outside of a `MenuList`. For general-purpose dividers, use `Spacer` with `border`.
+ * Do not use MenuDivider outside of a `MenuContent`. For general-purpose dividers, use `Spacer` with `border`.
  *
  * @example Menu with grouped sections
  * ```tsx
- * import { MenuList, MenuItem, MenuDivider, Icon } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, MenuDivider, Icon } from "@trackunit/react-components";
  *
  * const GroupedMenu = () => (
- *   <MenuList>
+ *   <MenuContent>
  *     <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
  *     <MenuItem id="duplicate" label="Duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />} />
  *     <MenuDivider />
  *     <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
- *   </MenuList>
+ *   </MenuContent>
  * );
  * ```
  * @returns {ReactElement} MenuDivider component
@@ -6430,7 +7266,38 @@ const cvaMenuItem = (props) => {
         focus: focused === true ? "focused" : "unfocused",
     }), className);
 };
-const cvaMenuItemStyle = cvaMerge(["px-2", "h-auto", "flex", "flex-row", "items-center", "gap-x-2", "select-none", "rounded"], {
+const cvaMenuItemStyle = cvaMerge(
+// `min-w-0` overrides the flex/grid item default of `min-width: auto`, which otherwise refuses to
+// shrink this row below the intrinsic (unwrapped) width of its `truncate`d label -- without it, the
+// label's ellipsis truncation never kicks in and the ancestor menu list scrolls horizontally instead.
+//
+// `outline-hidden`: `MenuContent`'s roving-tabindex keyboard nav calls this element's own `.focus()`
+// on hover too (to keep keyboard nav in sync with the pointer -- see `onMouseMove` on `MenuItemProps`),
+// and Chromium's `:focus-visible` heuristic treats a script-triggered `.focus()` on a non-native
+// control as visible-by-default, so the browser's native ring was showing on every hover. The active
+// item is already indicated by `cvaInteractableItem`'s `hover:`/`focus-within:` background tint, so the
+// native ring is redundant (and, via hover, actively misleading) for both mouse and keyboard users.
+//
+// `data-[state=open]:…` / `data-hover-scroll-suppressed`: a submenu trigger's open state is held still
+// across scroll-induced phantom `:hover` flips (see `hoverScrollGuard`), but CSS `:hover` backgrounds
+// would still chase the cursor across sibling rows. Pin the open-row tint via `data-state` (set by
+// `PopoverTrigger`), and while the guard's root attribute is set, take non-open rows out of hit-testing
+// so their `:hover` styles can't fire either -- matching the open-state freeze without a React render
+// per scroll tick. `!` beats `PopoverTrigger`'s MenuTree `pointer-events-auto` exemption.
+[
+    "px-2",
+    "h-auto",
+    "flex",
+    "flex-row",
+    "items-center",
+    "gap-x-2",
+    "select-none",
+    "rounded",
+    "min-w-0",
+    "outline-hidden",
+    "data-[state=open]:bg-neutral-600/5",
+    "[:root[data-hover-scroll-suppressed]_&:not([data-state=open])]:!pointer-events-none",
+], {
     variants: {
         fieldSize: {
             small: ["text-xs", "py-1.5"],
@@ -6442,6 +7309,7 @@ const cvaMenuItemStyle = cvaMerge(["px-2", "h-auto", "flex", "flex-row", "items-
             danger: [
                 "text-danger-600",
                 "hover:!bg-danger-100",
+                "data-[state=open]:!bg-danger-100",
                 "focus:!bg-danger-200",
                 "hover:!text-danger-700",
                 "focus:!text-danger-800",
@@ -6471,7 +7339,12 @@ const cvaMenuItemStyle = cvaMerge(["px-2", "h-auto", "flex", "flex-row", "items-
         disabled: false,
     },
 });
-const cvaMenuItemLabel = cvaMerge(["flex-grow", "truncate", "text-black", "font-normal", "flex", "items-center"], {
+const cvaMenuItemLabel = cvaMerge(
+// No `truncate` here: `text-overflow: ellipsis` only applies to block containers, not flex containers,
+// and this wrapper is `flex` (to align prefix/label/description). The actual truncation lives on the
+// nested label `<span>` in `MenuItem.tsx`, which gets auto-blockified for being a flex item. `min-w-0`
+// (rather than `truncate`'s `overflow-hidden`) is what lets this wrapper shrink below its content size.
+["flex-grow", "min-w-0", "text-black", "font-normal", "flex", "items-center"], {
     variants: {
         variant: {
             primary: [],
@@ -6537,21 +7410,34 @@ const cvaMenuItemSuffix = cvaMerge(["text-neutral-400", "text-sm", "flex", "item
 });
 
 /**
- * MenuItem represents a single actionable item within a MenuList.
- * It supports labels, icons (prefix/suffix), selected and focused states, and danger variants.
+ * 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
+ * render it directly wherever it's needed instead of passing a pre-built element around.
+ *
+ * Purely presentational: every DOM-facing prop (`className`, `tabIndex`, event handlers, ...) is
+ * expected to arrive already fully resolved and is forwarded onto the root `div` as-is via `...rest`.
+ * This matters because when rendered inside `PopoverTrigger`, Floating UI clones this element to
+ * inject its own reference props (`data-state`, click/keyboard activation, ...) -- resolving values
+ * here instead would shadow that injection.
+ */
+const MenuItemRow = ({ label, children, prefix, suffix, selected = false, disabled = false, variant = "primary", optionLabelDescription, optionPrefix, dataTestId, hasSubmenu, ...rest }) => (jsxs("div", { "aria-disabled": disabled, "data-testid": dataTestId ? `${dataTestId}-menu-item` : "menu-item", role: "menuitem", ...rest, children: [prefix !== null && prefix !== undefined ? (jsx("div", { className: cvaMenuItemPrefix({ selected, variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-prefix` : "menu-item-prefix", children: prefix })) : null, children !== null && children !== undefined && typeof children !== "string" ? (children) : (jsxs("div", { className: cvaMenuItemLabel({ variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-label` : "menu-item-label", children: [optionPrefix !== null && optionPrefix !== undefined ? optionPrefix : null, jsx("span", { className: "min-w-0 flex-1 truncate", children: children ?? label }), optionLabelDescription !== undefined && optionLabelDescription !== "" ? (jsxs("span", { className: "ml-1 text-neutral-400", children: ["(", optionLabelDescription, ")"] })) : null] })), suffix !== null && suffix !== undefined ? (jsx("div", { className: cvaMenuItemSuffix({ selected, variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-suffix` : "menu-item-suffix", children: suffix })) : hasSubmenu ? (jsx("div", { className: cvaMenuItemSuffix({ selected, variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-suffix` : "menu-item-suffix", children: jsx(Icon, { name: "ChevronRight", size: "small" }) })) : null] }));
+/**
+ * MenuItem represents a single actionable item within a MenuContent.
+ * It supports labels, icons (prefix/suffix), selected and focused states, danger variants, and — via the
+ * `submenu` prop — nested submenus.
  *
  * ### When to use
- * Use MenuItem inside a `MenuList` for individual actions (edit, delete, duplicate) or selectable options.
+ * Use MenuItem inside a `MenuContent` for individual actions (edit, delete, duplicate) or selectable options.
  *
  * ### When not to use
- * Do not use MenuItem outside of a `MenuList` context. For standalone clickable items, use `Button` or `ListItem`.
+ * Do not use MenuItem outside of a `MenuContent` context. For standalone clickable items, use `Button` or `ListItem`.
  *
  * @example MenuItem with icon prefix
  * ```tsx
- * import { MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, Icon } from "@trackunit/react-components";
  *
  * const ActionMenu = () => (
- *   <MenuList>
+ *   <MenuContent>
  *     <MenuItem
  *       id="edit"
  *       label="Edit asset"
@@ -6565,15 +7451,82 @@ const cvaMenuItemSuffix = cvaMerge(["text-neutral-400", "text-sm", "flex", "item
  *       variant="danger"
  *       onClick={() => console.log("Delete clicked")}
  *     />
- *   </MenuList>
+ *   </MenuContent>
+ * );
+ * ```
+ * @example MenuItem with a submenu
+ * ```tsx
+ * import { MenuContent, MenuItem } from "@trackunit/react-components";
+ *
+ * const StatusMenu = () => (
+ *   <MenuContent>
+ *     <MenuItem
+ *       label="Status"
+ *       submenu={
+ *         <MenuContent>
+ *           <MenuItem id="active" label="Active" />
+ *           <MenuItem id="idle" label="Idle" />
+ *         </MenuContent>
+ *       }
+ *     />
+ *   </MenuContent>
  * );
  * ```
  * @param {MenuItemProps} props - The props for the MenuItem component
  * @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, }) => {
+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();
@@ -6582,37 +7535,82 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
             onClick(e);
         }
     };
-    return (jsxs("div", { "aria-disabled": disabled, className: cvaMenuItem({
-            selected,
-            fieldSize,
-            disabled,
-            className,
-            variant,
-            focused,
-        }), "data-testid": dataTestId ? `${dataTestId}-menu-item` : "menu-item", id: id, onClick: e => {
-            if (stopPropagation) {
-                e.stopPropagation();
-            }
-            onClick?.(e);
-        }, onKeyDown: handleKeyDown, ref: ref, role: "menuitem", style: style, tabIndex: disabled ? -1 : (tabIndex ?? 0), children: [prefix !== null && prefix !== undefined ? (jsx("div", { className: cvaMenuItemPrefix({ selected, variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-prefix` : "menu-item-prefix", children: prefix })) : null, children !== null && children !== undefined && typeof children !== "string" ? (children) : (jsxs("div", { className: cvaMenuItemLabel({ variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-label` : "menu-item-label", children: [optionPrefix !== null && optionPrefix !== undefined ? optionPrefix : null, children ?? label, optionLabelDescription !== undefined && optionLabelDescription !== "" ? (jsxs("span", { className: "ml-1 text-neutral-400", children: ["(", optionLabelDescription, ")"] })) : null] })), suffix !== null && suffix !== undefined ? (jsx("div", { className: cvaMenuItemSuffix({ selected, variant, disabled }), "data-testid": dataTestId ? `${dataTestId}-suffix` : "menu-item-suffix", children: suffix })) : null] }));
+    const handleItemClick = e => {
+        if (stopPropagation) {
+            e.stopPropagation();
+        }
+        onClick?.(e);
+    };
+    const itemRowProps = {
+        id,
+        label,
+        children,
+        prefix,
+        suffix,
+        selected,
+        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),
+    };
+    if (submenu === undefined) {
+        return jsx(MenuItemRow, { ...itemRowProps, ref: ref });
+    }
+    // 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
+    // Floating UI's dialog haspopup so the trigger still advertises a submenu.
+    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 })] }));
 };
 
 /**
- * The MenuList is a popover menu that appears above all other content on the page. The menu offers a list of actions or functions that a user can access by clicking on a trigger.
+ * 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 MenuList if you have limited space and need to display overflow actions in a list.
- * - Use the MenuList for actions that are not essential to completing workflows.
- * - Don't use the MenuList to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
+ * - 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 MenuList with action items
+ * @example MenuContent with action items
  * ```tsx
- * import { MenuList, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
  *
  * const ActionsMenu = () => (
  *   <MoreMenu>
  *     {(close) => (
- *       <MenuList onClick={close}>
+ *       <MenuContent onClick={close}>
  *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
  *           Edit
  *         </MenuItem>
@@ -6622,14 +7620,14 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
  *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
  *           Delete
  *         </MenuItem>
- *       </MenuList>
+ *       </MenuContent>
  *     )}
  *   </MoreMenu>
  * );
  * ```
- * @example Multi-select MenuList
+ * @example Multi-select MenuContent
  * ```tsx
- * import { MenuList, MenuItem, MoreMenu } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, MoreMenu } from "@trackunit/react-components";
  * import { useState } from "react";
  *
  * const FilterMenu = () => {
@@ -6637,7 +7635,7 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
  *
  *   return (
  *     <MoreMenu label="Filter by status">
- *       <MenuList
+ *       <MenuContent
  *         isMulti
  *         selectedItems={selected}
  *         onSelectionChange={setSelected}
@@ -6645,18 +7643,52 @@ const MenuItem = ({ className, "data-testid": dataTestId, label, children, selec
  *         <MenuItem id="active">Active</MenuItem>
  *         <MenuItem id="idle">Idle</MenuItem>
  *         <MenuItem id="offline">Offline</MenuItem>
- *       </MenuList>
+ *       </MenuContent>
  *     </MoreMenu>
  *   );
  * };
  * ```
- * @param {MenuListProps} props - The props for the MenuList component
- * @returns {ReactElement} MenuList component
+ * @param {MenuContentProps} props - The props for the MenuContent component
+ * @returns {ReactElement} MenuContent component
  */
-const MenuList = ({ "data-testid": dataTestId, className, children, isMulti = false, selectedItems: controlledSelectedItems, onSelectionChange, style, ref, ...args }) => {
-    const childrenArr = Children.toArray(children);
+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)
@@ -6670,27 +7702,85 @@ const MenuList = ({ "data-testid": dataTestId, className, children, isMulti = fa
             setInternalSelectedItems(newSelectedItems);
         }
     }, [isMulti, selectedItems, onSelectionChange]);
-    return (jsx("div", { className: cvaMenu({ className, limitWidth: true }), "data-testid": dataTestId ? `${dataTestId}-menu-list` : "menu-list", onClick: args.onClick, ref: ref, role: "list", style: style, tabIndex: 0, children: jsx("div", { className: cvaMenuList(), children: childrenArr.map((menuItem, index) => {
-                if (isValidElement(menuItem)) {
-                    const isSelected = (selectedItems.includes(menuItem.props.id ?? `${index}`) || menuItem.props.selected) ?? false;
-                    return cloneElement(menuItem, {
-                        ...menuItem.props,
-                        key: index,
+    // 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 (menuItem.props.disabled !== true) {
+                            if (!disabled) {
                                 handleItemClick(menuItem.props.id ?? `${index}`);
                             }
                         },
-                        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),
-                    });
-                }
-                return null;
+                    }),
+                    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),
+                });
             }) }) }));
 };
 
@@ -6698,7 +7788,7 @@ const cvaMoreMenu = cvaMerge(["p-0"]);
 
 /**
  * MoreMenu (kebab menu) renders a three-dot button that opens a popover with a list of actions.
- * It is typically filled with a MenuList containing MenuItem elements.
+ * It is typically filled with a MenuContent containing MenuItem elements.
  *
  * ### When to use
  * Use MoreMenu when you have overflow actions that don't fit in the main UI. Common for row-level actions in tables, card headers, or list items.
@@ -6708,30 +7798,30 @@ const cvaMoreMenu = cvaMerge(["p-0"]);
  *
  * @example Action items with render prop — Pass a function as `children` to receive the `close` callback and dismiss the menu after an action.
  * ```tsx
- * import { MoreMenu, MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ * import { MoreMenu, MenuContent, MenuItem, Icon } from "@trackunit/react-components";
  *
  * const AssetActions = () => (
  *   <MoreMenu>
  *     {(close) => (
- *       <MenuList onClick={close}>
+ *       <MenuContent onClick={close}>
  *         <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
  *         <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
- *       </MenuList>
+ *       </MenuContent>
  *     )}
  *   </MoreMenu>
  * );
  * ```
  * @example Custom trigger button — Use `customButton` to replace the default kebab icon with any element, like a labeled Button.
  * ```tsx
- * import { MoreMenu, MenuList, MenuItem, Button } from "@trackunit/react-components";
+ * import { MoreMenu, MenuContent, MenuItem, Button } from "@trackunit/react-components";
  *
  * const CustomTriggerMenu = () => (
  *   <MoreMenu customButton={<Button variant="secondary" size="small">Actions</Button>}>
  *     {(close) => (
- *       <MenuList onClick={close}>
+ *       <MenuContent onClick={close}>
  *         <MenuItem id="export" label="Export" />
  *         <MenuItem id="archive" label="Archive" />
- *       </MenuList>
+ *       </MenuContent>
  *     )}
  *   </MoreMenu>
  * );
@@ -6751,7 +7841,7 @@ const MoreMenu = ({ className, "data-testid": dataTestId, popoverProps, iconProp
     const actionMenuRef = useRef(null);
     const mergedRef = useMergeRefs([actionMenuRef, ref]);
     const resolvedButtonLabel = iconButtonProps.title ?? buttonLabel ?? t("moreMenu.buttonLabel");
-    return (jsx("div", { className: cvaMoreMenu({ className }), "data-testid": dataTestId ? dataTestId : undefined, ref: mergedRef, style: style, children: jsxs(Popover, { placement: "bottom-end", ...popoverProps, children: [jsx(PopoverTrigger, { children: customButton ?? (jsx(IconButton, { ...iconButtonProps, "data-testid": iconButtonProps["data-testid"] ?? "more-menu-icon", icon: jsx(Icon, { name: "EllipsisHorizontal", ...iconProps }), title: resolvedButtonLabel })) }), jsx(PopoverContent, { portalId: customPortalId, children: close => (typeof children === "function" ? children(close) : children) })] }) }));
+    return (jsx("div", { className: cvaMoreMenu({ className }), "data-testid": dataTestId ? dataTestId : undefined, ref: mergedRef, style: style, children: jsx(MenuTree, { children: jsxs(Popover, { placement: "bottom-end", ...popoverProps, children: [jsx(PopoverTrigger, { children: customButton ?? (jsx(IconButton, { ...iconButtonProps, "data-testid": iconButtonProps["data-testid"] ?? "more-menu-icon", icon: jsx(Icon, { name: "EllipsisHorizontal", ...iconProps }), title: resolvedButtonLabel })) }), jsx(PopoverContent, { portalId: customPortalId, children: close => (typeof children === "function" ? children(close) : children) })] }) }) }));
 };
 
 const cvaNotice = cvaMerge(["flex", "items-center", "gap-1"]);
@@ -7113,7 +8203,7 @@ const PageHeaderSecondaryActions = ({ actions, hasPrimaryAction = false, groupAc
                 return [danger, [...others, action]];
             }
         }, [[], []]);
-        return (jsx("div", { className: className, "data-testid": dataTestId, ref: ref, style: style, children: jsx(MoreMenu, { "data-testid": "secondary-actions-more-menu", iconButtonProps: { size: "small", variant: "secondary" }, children: close => (jsxs(MenuList, { className: "min-w-[160px]", children: [otherActions.map((action, index) => (jsx(ActionRenderer, { action: action, externalOnClick: close, isMenuItem: true }, `${action.actionText}-${index}`))), dangerActions.length > 0 ? jsx(MenuDivider, {}) : null, dangerActions.map((action, index) => (jsx(ActionRenderer, { action: action, externalOnClick: close, isMenuItem: true }, `${action.actionText}-${index}`)))] })) }) }));
+        return (jsx("div", { className: className, "data-testid": dataTestId, ref: ref, style: style, children: jsx(MoreMenu, { "data-testid": "secondary-actions-more-menu", iconButtonProps: { size: "small", variant: "secondary" }, children: close => (jsxs(MenuContent, { className: "min-w-[160px]", children: [otherActions.map((action, index) => (jsx(ActionRenderer, { action: action, externalOnClick: close, isMenuItem: true }, `${action.actionText}-${index}`))), dangerActions.length > 0 ? jsx(MenuDivider, {}) : null, dangerActions.map((action, index) => (jsx(ActionRenderer, { action: action, externalOnClick: close, isMenuItem: true }, `${action.actionText}-${index}`)))] })) }) }));
     }
     // Otherwise, render them inline as buttons
     return (jsx("div", { className: twMerge("flex flex-row items-center gap-2", className), "data-testid": dataTestId, ref: ref, style: style, children: enabledActions
@@ -9086,6 +10176,25 @@ const useSheetMeasurements = ({ shouldRender, state, dockingEnabled, snapping, e
     ]);
 };
 
+/**
+ * The layout-reserved width of `element`'s own vertical scrollbar (in pixels), or `0` when it
+ * isn't currently reserving any (no overflow, or an overlay-style scrollbar that doesn't consume
+ * layout space, e.g. macOS's default).
+ *
+ * `offsetWidth` includes the element's border and any reserved scrollbar; `clientWidth` excludes
+ * both. Subtracting the (computed) border widths from that difference isolates the scrollbar
+ * itself -- a naive `offsetWidth - clientWidth` would wrongly fold border width into the result.
+ *
+ * @param element The element to measure
+ * @returns {number} The scrollbar's reserved width in pixels, or `0`
+ */
+const getScrollbarWidth = (element) => {
+    const style = window.getComputedStyle(element);
+    const borderLeft = parseFloat(style.borderLeftWidth) || 0;
+    const borderRight = parseFloat(style.borderRightWidth) || 0;
+    return Math.max(0, element.offsetWidth - borderLeft - borderRight - element.clientWidth);
+};
+
 /**
  * Blocks scrolling on the document and compensates for scrollbar width to prevent layout shift.
  * Uses scrollbar-gutter: stable to reserve space for the scrollbar when hiding overflow,
@@ -9104,10 +10213,7 @@ const blockDocumentScroll = () => {
     // Check html scrollbar: window.innerWidth includes scrollbar, clientWidth doesn't
     const htmlScrollbarWidth = window.innerWidth - html.clientWidth;
     // Check body scrollbar: offsetWidth includes border+scrollbar, clientWidth excludes both
-    const bodyStyle = window.getComputedStyle(body);
-    const bodyBorderLeft = parseInt(bodyStyle.borderLeftWidth) || 0;
-    const bodyBorderRight = parseInt(bodyStyle.borderRightWidth) || 0;
-    const bodyScrollbarWidth = body.offsetWidth - bodyBorderLeft - bodyBorderRight - body.clientWidth;
+    const bodyScrollbarWidth = getScrollbarWidth(body);
     // Use whichever scrollbar is present
     const hasVisibleScrollbar = htmlScrollbarWidth > 0 || bodyScrollbarWidth > 0;
     // Store original values before modifying
@@ -9166,13 +10272,7 @@ const restoreDocumentScroll = (originalStyles) => {
  */
 const blockContainerScroll = (container) => {
     // Check if there's a visible scrollbar before we hide it
-    // offsetWidth includes border + scrollbar, clientWidth excludes both
-    // We need to subtract borders to isolate the scrollbar width
-    const style = window.getComputedStyle(container);
-    const borderLeft = parseInt(style.borderLeftWidth) || 0;
-    const borderRight = parseInt(style.borderRightWidth) || 0;
-    const scrollbarWidth = container.offsetWidth - borderLeft - borderRight - container.clientWidth;
-    const hasVisibleScrollbar = scrollbarWidth > 0;
+    const hasVisibleScrollbar = getScrollbarWidth(container) > 0;
     const originalStyles = {
         container: {
             overflow: container.style.overflow,
@@ -10051,7 +11151,7 @@ const Sidebar = ({ childContainerClassName, children, breakpoint = "lg", classNa
                     });
                 }) }), overflowItemCount > 0 ? (jsx(MoreMenu, { iconButtonProps: {
                     variant: "ghost-neutral",
-                }, ...moreMenuProps, className: moreMenuProps?.className, "data-testid": `${dataTestId}-more-menu`, children: close => (jsx(MenuList, { ...menuListProps, "data-testid": dataTestId, children: Children.map(children, child => {
+                }, ...moreMenuProps, className: moreMenuProps?.className, "data-testid": `${dataTestId}-more-menu`, children: close => (jsx(MenuContent, { ...menuListProps, "data-testid": dataTestId, children: Children.map(children, child => {
                         return itemOverflowMap[child.props.id] === true
                             ? cloneElement(child, {
                                 onClick: e => {
@@ -11946,6 +13046,19 @@ const useStorageKey = (key, userId) => {
     return useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
 };
 
+/**
+ * Raw localStorage access, kept in one place so this file's exemption from the
+ * no-direct-storage-access rule is centralised rather than repeated at each call site.
+ *
+ * TODO: migrate to the useLocalStorage hook — this file was exempted when the
+ * no-direct-storage-access rule was introduced.
+ */
+/* eslint-disable no-restricted-globals */
+const rawLocalStorage = {
+    read: (key) => localStorage.getItem(key),
+    write: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+};
 /**
  * Generic persistence hook that loads state from a URL slot (search param
  * or hash fragment, depending on `urlLocation`) with localStorage fallback,
@@ -11969,6 +13082,11 @@ const useStorageKey = (key, userId) => {
  * `toUrlValue` + encoding). Duplicate writes where the state has not
  * changed (deep equality) are skipped.
  *
+ * `clearState` removes the entry from localStorage and from the URL slot,
+ * rather than writing an empty value. Use it when the state a consumer
+ * derives has become empty, so no leftover entry is stored for a value the
+ * user has reset. It is idempotent — clearing an absent entry is a no-op.
+ *
  * @param options - Configuration for the persisted state.
  * @param options.key - Unique identifier used for both the URL slot and the localStorage key.
  * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
@@ -12083,9 +13201,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         let storageState;
         if (localStorageEnabled) {
             try {
-                // TODO: migrate to useLocalStorage hook — this file was exempted when the no-direct-storage-access rule was introduced
-                // eslint-disable-next-line no-restricted-globals
-                const raw = localStorage.getItem(storageKey);
+                const raw = rawLocalStorage.read(storageKey);
                 if (raw) {
                     const parsed = storageSerializer.deserialize(raw);
                     storageState = validateState(parsed);
@@ -12220,8 +13336,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
                 const serialized = serializeRef.current
                     ? serializeRef.current(migrated)
                     : storageSerializer.serialize(migrated);
-                // eslint-disable-next-line no-restricted-globals
-                localStorage.setItem(storageKey, serialized);
+                rawLocalStorage.write(storageKey, serialized);
             }
             const urlValue = toUrlValueRef.current ? toUrlValueRef.current(migrated) : migrated;
             const encoded = encode(urlValue);
@@ -12235,14 +13350,20 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         lastPersistedRef.current = state;
         if (localStorageEnabled) {
             const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
-            // eslint-disable-next-line no-restricted-globals
-            localStorage.setItem(storageKey, serialized);
+            rawLocalStorage.write(storageKey, serialized);
         }
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
         const encoded = encode(urlValue);
         updateSearchParam(encoded);
     }, [storageKey, encode, localStorageEnabled, updateSearchParam]);
-    return useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
+    const clearState = useCallback(() => {
+        lastPersistedRef.current = undefined;
+        if (localStorageEnabled) {
+            rawLocalStorage.remove(storageKey);
+        }
+        updateSearchParam(undefined);
+    }, [localStorageEnabled, storageKey, updateSearchParam]);
+    return useMemo(() => ({ initialState, persistState, clearState }), [initialState, persistState, clearState]);
 };
 
 const OVERSCAN = 10;
@@ -13444,4 +14565,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
  */
 setupLibraryTranslations();
 
-export { Alert, Badge, Breadcrumb, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, LabeledValue, LabeledValueList, List, ListItem, MAX_HASH_LENGTH, MAX_URL_LENGTH, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, storageSerializer, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHashParamSync, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { Alert, Badge, Breadcrumb, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, LabeledValue, LabeledValueList, List, ListItem, MAX_HASH_LENGTH, MAX_URL_LENGTH, MenuContent, MenuDivider, MenuItem, MenuTree, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, storageSerializer, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHashParamSync, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMenuTree, useMergeRefs, useModifierKey, useOptionalPopoverContext, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };