@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/menu/index.jsx

@@ -0,0 +1,671 @@
+// Ported from react-aria-components Menu.tsx (MenuTrigger, SubmenuTrigger, Menu, MenuSection, MenuItem,
+// MenuLoadMoreItem; MenuContext, MenuStateContext, RootMenuTriggerStateContext, MenuItemContext)
+// (packages/react-aria-components/src/Menu.tsx), Apache-2.0, © Adobe.
+//
+// RAC composition: `<MenuTrigger><Button/><Popover><Menu><MenuItem/>…</Menu></Popover></MenuTrigger>`,
+// sections (`MenuSection` + `Header`), `Separator`, `SubmenuTrigger` (`<MenuItem/>` + `<Popover><Menu/></Popover>`),
+// `trigger` "press" | "longPress" | "contextMenu".
+// Rivet:
+// - live collection (`../collections/components.tsx`): parts render their DOM in place (`data-key`); ONE
+//   delegated handler on the menu element (`menuEvent`, ./behaviour.tsx) runs useMenu + every useMenuItem /
+//   useSubmenuTrigger against the DOM, so items carry no handlers (resumable, nothing loads before the first
+//   interaction). Item callbacks (`onAction`, press / hover / focus events, `shouldCloseOnSelect`) are
+//   registered into the menu state by key (`registerMenuItem`), section rules by section key.
+// - MenuTrigger renders no element: it provides MenuContext / OverlayTriggerStateContext /
+//   RootMenuTriggerStateContext / PopoverContext and a `PressResponder` whose trigger props reach the user's
+//   `<Button>` (accessors for `aria-expanded` / `aria-controls` / `isPressed`).
+// - SubmenuTrigger: the trigger MenuItem binds its own key to the submenu state (`bindSubmenuTrigger`); the
+//   submenu Popover is portaled into the root popover's group container; the safe-triangle pointer tracking
+//   (useSafelyMouseToSubmenu) attaches while the submenu is mounted.
+// - render props are accessors; `data-hovered` / `data-pressed` / `data-focus-visible` are written by the
+//   delegated handler (signals only when a `class` / `style` / `children` function asks for them).
+// - `class` = RAC `className` (defaults `rv-Menu`, `rv-MenuItem`, `rv-MenuSection`, `rv-MenuLoadingIndicator`).
+// - SelectableCollectionContext (Autocomplete) merges under the menu props: `shouldUseVirtualFocus` /
+//   `disallowTypeAhead` / `autoFocus` may be accessors (read in bindings; a client effect mirrors them into
+//   the menu state options the delegated handler reads); `filter` hides items in place (each item's own
+//   `Show`, live collection); `onFocusIn` goes on the menu element; `react-aria-focus` /
+//   `react-aria-clear-focus` are handled on the menu element.
+// `render` (RAC DOMRenderProps) on Menu (`<div>`), MenuSection (`<section>`) and MenuItem (`<div>` / `<a>`): given, the attributes object goes to `render(attrs, renderProps)`. Deviations: no FocusScope around the menu (the popover's focus scope contains focus;
+//   a standalone menu has no FocusManager); no virtualizer; `isEmpty` counts rendered (visible) items (live
+//   collection); live-mode filtering keeps empty sections (RAC drops them); no `--trigger-width` on the popover.
+import { _regionState, onCleanup, signal, untrack, useContext } from "@rivetjs/reactivity";
+import { Show, clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { isSlot } from "@rivetjs/runtime/slot";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { createContext } from "@rivetjs/reactivity";
+import { DEFAULT_SLOT, Provider, contextProps, createSlotId, mergeRefValues, renderProps, slotIdRef, } from "../slots/index.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { dataBool } from "../utils/data-attrs.jsx";
+import { PressResponder } from "../interactions/pressable.jsx";
+import { OverlayTriggerStateContext, PopoverContext } from "../overlay/contexts.js";
+import { CollectionRendererContext, Collection, SectionContext, createBranchComponent, createLeafComponent, isCollectionProbe, isHidden, } from "../collections/components.jsx";
+import { CollectionNode, ItemNode, LoaderNode, SectionNode } from "../collections/base.js";
+import { HeaderContext } from "../header/index.jsx";
+import { SeparatorContext } from "../separator/index.jsx";
+import { TextContext } from "../text/index.jsx";
+import { probeSlots } from "#server";
+import { KeyboardContext } from "../keyboard/index.jsx";
+import { useLocale } from "../i18n/index.js";
+import { idSignal } from "../utils/id.js";
+import { loadMoreSentinel } from "../utils/load-more-sentinel.jsx";
+import { controllable } from "../interactions/controllable.js";
+import { bindSubmenuTrigger, closeMenu, createMenuState, createMenuTriggerState, createSubmenuTriggerState, registerMenuItem, registerMenuSection, registerSubmenu, selectionOf, submenuId, closeAllSubmenus, closeSubmenu, openSubmenu, } from "../state/menu.js";
+import { getItemId, itemDisabled, itemFocused, itemSelected, itemTabIndex, collectionTabIndex } from "../state/list.js";
+import { FieldInputContext, SelectableCollectionContext } from "../autocomplete/contexts.js";
+import { menuAutoFocus, menuClearVirtualFocus, menuCollectionUpdated, menuEvent, menuKeys, menuSubmenuClosed, menuSubmenuOpened, menuTriggerProps, menuVirtualFocus, } from "./behaviour.jsx";
+import { hasLive, isLive, liveAt, liveOptions, liveKeys, liveView } from "../utils/live.jsx";
+/** A live MenuItem `isDisabled` (with the Menu's `disabledKeys`): a returned arrow (resumable). */
+function liveItemDisabled(state, key, own) {
+    return () => itemDisabled(state, key, !!own());
+}
+/** `aria-disabled` of a live disabled flag. */
+function ariaDisabledOf(disabled) {
+    return () => (disabled() ? "true" : undefined);
+}
+/** `data-disabled` of a live disabled flag. */
+function dataDisabledOf(disabled) {
+    return () => dataBool(disabled());
+}
+import { liveRenderProps } from "../slots/index.jsx";
+// =================================================================================================
+// Contexts
+// =================================================================================================
+/** RAC `MenuContext`: props for the Menu inside a MenuTrigger / SubmenuTrigger. */
+export const MenuContext = resumableContext(createContext(null, { id: "rv-menu" }));
+/** RAC `MenuStateContext`: the state of the nearest Menu (Rivet: `MenuState`, the menu's tree / list state). */
+export const MenuStateContext = resumableContext(createContext(null, { id: "rv-menu-state" }));
+/** RAC `RootMenuTriggerStateContext`: the root menu trigger state (open submenus stack). */
+export const RootMenuTriggerStateContext = resumableContext(createContext(null, { id: "rv-root-menu-trigger-state" }));
+/** RAC `MenuItemContext` (not exported upstream; Rivet exports it for custom containers). */
+export const MenuItemContext = resumableContext(createContext(null, { id: "rv-menu-item" }));
+/** Rivet: the key of the MenuSection an item renders in (RAC `SelectionManagerContext` → the section's selection). */
+const MenuSectionKeyContext = resumableContext(createContext(null, { id: "rv-menu-section-key" }));
+const SubmenuScopeContext = resumableContext(createContext(null, { id: "rv-submenu-scope" }));
+const MenuCollectionScopeContext = resumableContext(createContext(null, { id: "rv-menu-collection-scope" }));
+const isFn = (v) => typeof v === "function" && !isSlot(v);
+const read = (v) => (typeof v === "function" ? v() : v);
+/** A menu trigger wraps a button and a popover with a menu, opening the menu on press (RAC `MenuTrigger`). */
+export function MenuTrigger(props) {
+    // Live props: a controlled `isOpen={open()}` stays live (accessor; `controllable` reads it, never writes it).
+    const state = createMenuTriggerState(liveOptions(props, [], ["isOpen"]));
+    const triggerRef = _regionState(() => createRef());
+    // If within a collection (e.g. Tabs), render nothing.
+    if (isHidden())
+        return null;
+    const trigger = props.trigger;
+    const { locale } = useLocale();
+    const { menuTriggerProps: triggerProps, menuProps: triggerMenuProps, longPressDescription } = menuTriggerProps({ trigger, locale }, state);
+    // RA mergeIds: a Button `id` / Menu `id` replaces the generated id; aria-labelledby / aria-controls follow it.
+    const triggerId = idSignal(state.triggerId), menuId = idSignal(state.menuId);
+    const mp = { ...triggerMenuProps, "aria-labelledby": () => triggerId(), idRef: menuId };
+    const tp = trigger === "contextMenu" ? triggerProps : { ...triggerProps, "aria-controls": () => (state.isOpen() ? menuId() : undefined) };
+    const children = props.children;
+    const description = longPressDescription;
+    return (<Provider values={[
+            [MenuContext, mp],
+            [OverlayTriggerStateContext, state],
+            [RootMenuTriggerStateContext, state],
+            [
+                PopoverContext,
+                {
+                    trigger: "MenuTrigger",
+                    triggerRef,
+                    placement: "bottom start",
+                    "aria-labelledby": () => triggerId(),
+                    ...(trigger === "contextMenu" ? { offset: 0 } : {}),
+                },
+            ],
+        ]}>
+      <PressResponder {...tp} ref={triggerRef} isPressed={() => state.isOpen()}>
+        {children}
+      </PressResponder>
+      {description ? (<span id={description.id} hidden>
+          {description.text}
+        </span>) : null}
+    </Provider>);
+}
+class SubmenuTriggerNode extends CollectionNode {
+    static type = "submenutrigger";
+}
+/** A submenu trigger wraps a submenu's trigger item and the submenu itself (RAC `SubmenuTrigger`). */
+export const SubmenuTrigger = /*#__PURE__*/ createBranchComponent(SubmenuTriggerNode, function SubmenuTrigger(props, _ref, item) {
+    const { CollectionBranch } = useContext(CollectionRendererContext);
+    const state = useContext(MenuStateContext);
+    const root = useContext(RootMenuTriggerStateContext);
+    // The trigger item binds its own key (bindSubmenuTrigger) and fills the submenu's Menu / Popover
+    // context values (ids from that key) when it renders: it renders before the Popover sibling.
+    const sub = createSubmenuTriggerState({ triggerKey: item.key }, root, state.level);
+    const itemRef = createRef();
+    const menu = {
+        onClose: () => closeAllSubmenus(sub),
+        autoFocus: () => sub.focusStrategy() ?? undefined,
+    };
+    const popover = {
+        trigger: "SubmenuTrigger",
+        triggerRef: itemRef,
+        placement: "end top",
+        isNonModal: true,
+        // menu["aria-labelledby"] = the trigger item id, filled by bindSubmenuItem.
+        shouldCloseOnInteractOutside: (target) => target.id !== menu["aria-labelledby"],
+    };
+    // The submenu's overlay state (RAC: the SubmenuTriggerState): open = this level of the root stack.
+    // Controlled by the accessor; writes (closeOverlay) go through onChange. Object-literal arrows: resume
+    // symbols (arrows passed only as call arguments are not).
+    const ctl = {
+        isOpen: () => sub.isOpen(),
+        onChange: (open) => (open ? openSubmenu(sub) : closeSubmenu(sub)),
+    };
+    const overlay = {
+        isOpen: sub.isOpen,
+        point: signal(null),
+        open: controllable(ctl.isOpen, false, ctl.onChange),
+    };
+    const delay = props.delay;
+    const scope = { sub, parentId: state.id, delay, menu, popover, itemRef };
+    return (<Provider values={[
+            [SubmenuScopeContext, scope],
+            [MenuContext, menu],
+            [OverlayTriggerStateContext, overlay],
+            [PopoverContext, popover],
+        ]}>
+        {() => CollectionBranch({ collection: null, parent: item })}
+      </Provider>);
+});
+/** The trigger item of a SubmenuTrigger: bind its key, fill the submenu Menu / Popover context values. */
+function bindSubmenuItem(scope, parent, key) {
+    bindSubmenuTrigger(scope.sub, key);
+    const triggerId = getItemId(parent, key);
+    scope.menu.id = submenuId(parent, key);
+    scope.menu["aria-labelledby"] = triggerId;
+    scope.popover["aria-labelledby"] = triggerId;
+}
+/** Global DOM events the menu handles itself (delegated); the user's handlers run after its own. */
+const MENU_OWNED = [
+    "onKeyDown",
+    "onKeyUp",
+    "onPointerDown",
+    "onPointerUp",
+    "onPointerCancel",
+    "onClick",
+    "onMouseDown",
+    "onPointerOver",
+    "onPointerOut",
+    "onFocusIn",
+    "onFocusOut",
+    "onDragStart",
+    "onScroll",
+    "style",
+];
+/** A menu displays a list of actions or options that a user can choose (RAC `Menu`). */
+export function Menu(inProps) {
+    const [menuProps, menuRef] = contextProps(inProps, inProps.ref, MenuContext);
+    // Inside a collection's build pass a menu registers nothing (RAC: the hidden tree keeps it). Autocomplete's server id
+    // probe: merge the own id into the collection id first (as below).
+    if (isHidden()) {
+        if (isCollectionProbe())
+            contextProps(menuProps, undefined, SelectableCollectionContext);
+        return null;
+    }
+    // RAC MenuInner: the Autocomplete's collection props merge under the menu props.
+    const [props, contextRef] = contextProps(menuProps, menuRef, SelectableCollectionContext);
+    const shouldUseVirtualFocus = props.shouldUseVirtualFocus, disallowTypeAhead = props.disallowTypeAhead, filter = props.filter;
+    const virtualFocus = () => !!read(shouldUseVirtualFocus);
+    const triggerState = useContext(RootMenuTriggerStateContext);
+    const scope = useContext(SubmenuScopeContext);
+    const userOnClose = props.onClose;
+    const state = createMenuState({
+        selectionMode: props.selectionMode,
+        // Live props: a controlled `selectedKeys={keys()}` stays live (accessor; never written).
+        selectedKeys: liveKeys(props, "selectedKeys"),
+        defaultSelectedKeys: props.defaultSelectedKeys,
+        onSelectionChange: props.onSelectionChange,
+        disabledKeys: props.disabledKeys,
+        disallowEmptySelection: props.disallowEmptySelection,
+        shouldFocusWrap: props.shouldFocusWrap,
+        escapeKeyBehavior: props.escapeKeyBehavior,
+        onAction: props.onAction,
+        // Inline arrow (a resume symbol); upstream: props.onClose ?? the trigger state close.
+        onClose: () => (userOnClose ? userOnClose() : triggerState ? closeMenu(triggerState) : undefined),
+        shouldCloseOnSelect: props.shouldCloseOnSelect,
+        shouldUseVirtualFocus: untrack(virtualFocus),
+        disallowTypeAhead: untrack(() => !!read(disallowTypeAhead)),
+    }, {
+        ...(triggerState ? { root: triggerState } : {}),
+        level: scope ? scope.sub.submenuLevel + 1 : 0,
+        ...(scope ? { submenuTrigger: scope.sub, parentId: scope.parentId } : {}),
+        ...(props.id ? { id: props.id } : {}),
+    });
+    // MenuTrigger's reactive menu id (DialogContext `idRef` pattern): the trigger's aria-controls follows a Menu `id`
+    // (RA mergeIds; on a resumed page the merge runs in the browser, where idSignal has no updaters).
+    const idRef = props.idRef;
+    if (idRef && untrack(idRef) !== state.id)
+        idRef.set(state.id);
+    const isEmpty = () => state.itemCount() === 0;
+    const rp = untrack(() => renderProps({ class: props.class, style: props.style, defaultClassName: "rv-Menu", values: { isEmpty } }, hasLive(props) ? liveRenderProps(props) : undefined));
+    const aria = {
+        "aria-label": props["aria-label"],
+        "aria-labelledby": props["aria-labelledby"],
+        "aria-describedby": props["aria-describedby"],
+        escapeKeyBehavior: props.escapeKeyBehavior,
+        onKeyDown: props.onKeyDown,
+        onKeyUp: props.onKeyUp,
+    };
+    const { onPointerDown, onPointerUp, onPointerCancel, onClick, onMouseDown, onPointerOver, onPointerOut, onFocusIn, onFocusOut, onDragStart, onScroll } = props;
+    const element = createRef();
+    const ref = mergeRefValues(element, contextRef);
+    const autoFocus = props.autoFocus;
+    // Accessor options (Autocomplete): mirror into the state options the delegated handler reads.
+    if (typeof shouldUseVirtualFocus === "function" || typeof disallowTypeAhead === "function")
+        clientEffect(() => {
+            state.options.shouldUseVirtualFocus = virtualFocus();
+            state.options.disallowTypeAhead = !!read(disallowTypeAhead);
+        });
+    // useSelectableCollection: the items changed (filter / load) → a pending "virtual focus first". React runs
+    // it after the commit; here the count changes while the list's DOM is still being reconciled in the same
+    // flush (an item's cleanup runs before its parent insertion removes its nodes), so it runs after the flush.
+    clientEffect(() => {
+        state.itemCount();
+        const el = element();
+        if (el)
+            queueMicrotask(() => el.isConnected && untrack(() => menuCollectionUpdated(state, el)));
+    });
+    clientEffect(() => {
+        const el = element();
+        if (!el)
+            return;
+        return untrack(() => {
+            menuAutoFocus(state, el, read(autoFocus) ?? false);
+            const sub = state.submenuTrigger;
+            if (!sub)
+                return;
+            const parentMenu = state.parentId ? el.ownerDocument.getElementById(state.parentId) : null;
+            menuSubmenuOpened(sub, parentMenu, el);
+            return () => menuSubmenuClosed(sub);
+        });
+    });
+    const items = props.items, children = props.children;
+    const content = () => <Collection items={items} children={children}/>;
+    const { CollectionRoot } = useContext(CollectionRendererContext);
+    // Items first (they count themselves for `data-empty`), then the element.
+    const body = (<Provider values={[
+            [MenuStateContext, state],
+            [SeparatorContext, { elementType: "div" }],
+            [SectionContext, { name: "MenuSection", render: MenuSectionInner }],
+            [MenuItemContext, { shouldCloseOnSelect: props.shouldCloseOnSelect }],
+            [MenuSectionKeyContext, null],
+            [SubmenuScopeContext, null],
+            [MenuCollectionScopeContext, { filter, virtualFocus }],
+            [SelectableCollectionContext, null],
+            [FieldInputContext, null],
+            // Ensure the root MenuTriggerState is defined, in case Menu is rendered outside a MenuTrigger.
+            [RootMenuTriggerStateContext, state.root],
+        ]}>
+      {() => CollectionRoot({ collection: null, content })}
+    </Provider>);
+    const renderEmptyState = props.renderEmptyState;
+    const dom = globalDOMProps(props, MENU_OWNED);
+    const slot = props.slot || undefined, ariaLabel = aria["aria-label"], ariaLabelledby = aria["aria-labelledby"], ariaDescribedby = aria["aria-describedby"];
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id: state.id,
+            role: "menu",
+            slot,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "aria-label": ariaLabel,
+            "aria-labelledby": () => read(ariaLabelledby),
+            "aria-describedby": ariaDescribedby,
+            "aria-multiselectable": state.selectionMode === "multiple" ? "true" : undefined,
+            "data-collection": state.id,
+            "data-rk": menuKeys(state),
+            "data-empty": () => dataBool(isEmpty()),
+            tabindex: () => (virtualFocus() ? undefined : collectionTabIndex(state)),
+            onKeyDown: (e) => menuEvent(e, aria, state),
+            onKeyUp: (e) => menuEvent(e, aria, state),
+            onPointerDown: (e) => {
+                menuEvent(e, aria, state);
+                onPointerDown?.(e);
+            },
+            onPointerUp: (e) => {
+                menuEvent(e, aria, state);
+                onPointerUp?.(e);
+            },
+            onPointerCancel: (e) => {
+                menuEvent(e, aria, state);
+                onPointerCancel?.(e);
+            },
+            onClick: (e) => {
+                menuEvent(e, aria, state);
+                onClick?.(e);
+            },
+            onMouseDown: (e) => {
+                menuEvent(e, aria, state);
+                onMouseDown?.(e);
+            },
+            onPointerOver: (e) => {
+                menuEvent(e, aria, state);
+                onPointerOver?.(e);
+            },
+            onPointerOut: (e) => {
+                menuEvent(e, aria, state);
+                onPointerOut?.(e);
+            },
+            onFocusIn: (e) => {
+                menuEvent(e, aria, state);
+                onFocusIn?.(e);
+            },
+            onFocusOut: (e) => {
+                menuEvent(e, aria, state);
+                onFocusOut?.(e);
+            },
+            onDragStart: (e) => {
+                menuEvent(e, aria, state);
+                onDragStart?.(e);
+            },
+            onScroll: (e) => {
+                menuEvent(e, aria, state);
+                onScroll?.(e);
+            },
+            // Custom events: the spread takes `on<Type>` keys (no `on:` form). Contract: libs/runtime/dom-v2-spread.ts (~L121) strips
+            // `on`, lowercases the rest (`react-aria-focus`) and binds non-delegated types with addEventListener. Tested in
+            // render-collections.browser.test.tsx ("Menu virtual-focus custom events").
+            "onReact-aria-focus": (e) => menuVirtualFocus(e, state),
+            "onReact-aria-clear-focus": (e) => menuClearVirtualFocus(e, state),
+            children: () => [
+                body,
+                renderEmptyState ? (<Show when={isEmpty}>
+            {() => (<div role="menuitem" style={{ display: "contents" }}>
+                {renderEmptyState()}
+              </div>)}
+          </Show>) : null,
+            ],
+        };
+        return props.render(attrs, { isEmpty });
+    }
+    return (<div {...dom} ref={ref} id={state.id} role="menu" slot={slot} class={rp.class()} style={rp.style()} aria-label={ariaLabel} aria-labelledby={read(ariaLabelledby)} aria-describedby={ariaDescribedby} aria-multiselectable={state.selectionMode === "multiple" ? "true" : undefined} data-collection={state.id} data-rk={menuKeys(state)} data-empty={dataBool(isEmpty())} tabIndex={virtualFocus() ? undefined : collectionTabIndex(state)} onKeyDown={(e) => menuEvent(e, aria, state)} onKeyUp={(e) => menuEvent(e, aria, state)} onPointerDown={(e) => {
+            menuEvent(e, aria, state);
+            onPointerDown?.(e);
+        }} onPointerUp={(e) => {
+            menuEvent(e, aria, state);
+            onPointerUp?.(e);
+        }} onPointerCancel={(e) => {
+            menuEvent(e, aria, state);
+            onPointerCancel?.(e);
+        }} onClick={(e) => {
+            menuEvent(e, aria, state);
+            onClick?.(e);
+        }} onMouseDown={(e) => {
+            menuEvent(e, aria, state);
+            onMouseDown?.(e);
+        }} onPointerOver={(e) => {
+            menuEvent(e, aria, state);
+            onPointerOver?.(e);
+        }} onPointerOut={(e) => {
+            menuEvent(e, aria, state);
+            onPointerOut?.(e);
+        }} onFocusIn={(e) => {
+            menuEvent(e, aria, state);
+            onFocusIn?.(e);
+        }} onFocusOut={(e) => {
+            menuEvent(e, aria, state);
+            onFocusOut?.(e);
+        }} onDragStart={(e) => {
+            menuEvent(e, aria, state);
+            onDragStart?.(e);
+        }} onScroll={(e) => {
+            menuEvent(e, aria, state);
+            onScroll?.(e);
+        }} on:react-aria-focus={(e) => menuVirtualFocus(e, state)} on:react-aria-clear-focus={(e) => menuClearVirtualFocus(e, state)}>
+      {body}
+      {renderEmptyState ? (<Show when={isEmpty}>
+          {() => (<div role="menuitem" style={{ display: "contents" }}>
+              {renderEmptyState()}
+            </div>)}
+        </Show>) : null}
+    </div>);
+}
+const SECTION_OWNED = ["style"];
+function MenuSectionInner(props, ref, section, className = "rv-MenuSection") {
+    const state = useContext(MenuStateContext);
+    const { CollectionBranch } = useContext(CollectionRendererContext);
+    const closeOnSelect = useContext(MenuItemContext)?.shouldCloseOnSelect;
+    const key = section.key;
+    registerMenuSection(state, key, {
+        shouldCloseOnSelect: props.shouldCloseOnSelect ?? closeOnSelect,
+        selectionMode: props.selectionMode,
+        selectedKeys: liveKeys(props, "selectedKeys"),
+        defaultSelectedKeys: props.defaultSelectedKeys,
+        onSelectionChange: props.onSelectionChange,
+        disallowEmptySelection: props.disallowEmptySelection,
+    });
+    // useMenuSection: the heading labels the group when it renders (RA useSlot).
+    const heading = createSlotId(getItemId(state, key) + "-heading");
+    const body = (<Provider values={[
+            [HeaderContext, { id: heading, role: "presentation" }],
+            [MenuSectionKeyContext, key],
+            [MenuItemContext, { shouldCloseOnSelect: props.shouldCloseOnSelect ?? closeOnSelect }],
+        ]}>
+      {() => CollectionBranch({ collection: null, parent: section })}
+    </Provider>);
+    const dom = globalDOMProps(props, SECTION_OWNED);
+    const sectionRef = mergeRefValues(createRef(), ref);
+    const ariaLabel = props["aria-label"], cls = props.class ?? className, style = props.style;
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            ref: sectionRef,
+            class: cls,
+            style,
+            role: "group",
+            "data-section": "",
+            "data-key": String(key),
+            "data-key-type": typeof key === "number" ? "number" : undefined,
+            "aria-label": ariaLabel,
+            "aria-labelledby": () => slotIdRef(heading),
+            children: () => body,
+        };
+        return props.render(attrs, undefined);
+    }
+    return (<section {...dom} ref={sectionRef} class={cls} style={style} role="group" data-section="" data-key={String(key)} data-key-type={typeof key === "number" ? "number" : undefined} aria-label={ariaLabel} aria-labelledby={slotIdRef(heading)}>
+      {body}
+    </section>);
+}
+/** A MenuSection represents a section within a Menu (RAC `MenuSection`). */
+export const MenuSection = /*#__PURE__*/ createBranchComponent(SectionNode, MenuSectionInner);
+// The menu's delegated handler runs the item behaviour; the item's own DOM handlers stay on the item element
+// (they run first, while the event bubbles to the menu — RAC mergeProps(DOMProps, menuItemProps)).
+const ITEM_OWNED = ["style"];
+/** A MenuItem represents an individual action in a Menu (RAC `MenuItem`). */
+export const MenuItem = /*#__PURE__*/ createLeafComponent(ItemNode, function MenuItem(inProps, forwardedRef, item) {
+    const [props, ref] = contextProps(inProps, forwardedRef, MenuItemContext);
+    const state = useContext(MenuStateContext);
+    if (!state)
+        throw new Error("MenuItem must be rendered inside a Menu.");
+    const sectionKey = useContext(MenuSectionKeyContext);
+    const scope = useContext(SubmenuScopeContext);
+    const key = item.key;
+    // Live `isDisabled` (LIVE-SWEEP round 2): an accessor read in the bindings; the DOM collection (handlers,
+    // keyboard navigation) reads the item's `aria-disabled`, so a live item is not registered in `disabledKeys`.
+    const ownDisabled = isLive(props, "isDisabled")
+        ? liveAt(liveView(props, ["isDisabled"]), "isDisabled")
+        : !!props.isDisabled;
+    const liveDisabled = typeof ownDisabled === "function" ? ownDisabled : undefined;
+    const isDisabled = liveDisabled ? false : ownDisabled;
+    const collectionScope = useContext(MenuCollectionScopeContext);
+    const virtualFocus = collectionScope?.virtualFocus;
+    // Live collection size (RAC `collection.size`): visible items count themselves.
+    const count = () => {
+        state.itemCount.set(untrack(state.itemCount) + 1);
+        onCleanup(() => state.itemCount.set(untrack(state.itemCount) - 1));
+    };
+    // A SubmenuTrigger's trigger item: bind the key, register the submenu (hover delay).
+    const sub = scope?.sub;
+    if (sub) {
+        bindSubmenuItem(scope, state, key);
+        registerSubmenu(state, key, sub, scope.delay);
+    }
+    const wantsStates = isFn(props.class) || isFn(props.style) || isFn(props.children);
+    const states = wantsStates ? { hovered: signal(false), pressed: signal(false), focusVisible: signal(false) } : undefined;
+    registerMenuItem(state, key, {
+        isDisabled,
+        onAction: sub ? undefined : props.onAction,
+        shouldCloseOnSelect: props.shouldCloseOnSelect,
+        routerOptions: props.routerOptions,
+        onPressStart: props.onPressStart,
+        onPressEnd: props.onPressEnd,
+        onPressUp: props.onPressUp,
+        onPress: props.onPress,
+        onPressChange: props.onPressChange,
+        onHoverStart: props.onHoverStart,
+        onHoverEnd: props.onHoverEnd,
+        onHoverChange: props.onHoverChange,
+        onFocus: props.onFocus,
+        onBlur: props.onBlur,
+        onFocusChange: props.onFocusChange,
+        ...(states ? { states } : {}),
+    });
+    const selection = selectionOf(state, sectionKey ?? undefined);
+    const selectionMode = selection.selectionMode;
+    const id = getItemId(state, key);
+    const disabled = liveDisabled ? liveItemDisabled(state, key, liveDisabled) : itemDisabled(state, key, isDisabled);
+    const hasSubmenu = !!sub;
+    const isOpen = sub ? () => sub.isOpen() : () => false;
+    const isSelected = () => selectionMode !== "none" && !hasSubmenu && !!itemSelected(selection, key, isDisabled || !!liveDisabled?.());
+    const isFocused = () => itemFocused(state, key);
+    const values = {
+        isHovered: () => !!states?.hovered(),
+        isPressed: () => !!states?.pressed(),
+        isSelected,
+        isFocused,
+        isFocusVisible: () => !!states?.focusVisible(),
+        isDisabled: () => read(disabled),
+        selectionMode,
+        selectionBehavior: "toggle",
+        hasSubmenu,
+        isOpen,
+    };
+    // useMenuItem slot ids: label / description / keyboard shortcut (RA useSlotId).
+    const label = createSlotId(id + "-label"), description = createSlotId(id + "-description"), kbd = createSlotId(id + "-kbd");
+    const rp = untrack(() => renderProps({
+        class: props.class,
+        style: props.style,
+        children: props.children,
+        defaultClassName: "rv-MenuItem",
+        values,
+    }, hasLive(props) ? liveRenderProps(props) : undefined));
+    // Children first (they mark the slot ids rendered), then the element.
+    const body = () => (<Provider values={[
+            [TextContext, { slots: { [DEFAULT_SLOT]: { id: label }, label: { id: label }, description: { id: description } } }],
+            [KeyboardContext, { id: kbd }],
+            [SubmenuScopeContext, null],
+        ]}>
+      {() => rp.children()}
+    </Provider>);
+    // Rivet (server): the children render in a binding after the item's attributes: probe which slotted parts render
+    // (label / description Text, Keyboard; same providers as `body`), so `aria-labelledby` / `aria-describedby` name only
+    // those (no dangling IDREF).
+    if (typeof document === "undefined")
+        probeSlots([
+            [TextContext, { slots: { [DEFAULT_SLOT]: { id: label }, label: { id: label }, description: { id: description } } }],
+            [KeyboardContext, { id: kbd }],
+            [SubmenuScopeContext, null],
+        ], () => rp.children());
+    const role = hasSubmenu ? "menuitem" : selectionMode === "single" ? "menuitemradio" : selectionMode === "multiple" ? "menuitemcheckbox" : "menuitem";
+    const dom = globalDOMProps(props, ITEM_OWNED);
+    const ariaLabel = props["aria-label"], href = props.href, 
+    // Link attributes as locals: the item render closure must not capture `props` (PROPS-CAPTURE).
+    hrefLang = props.hrefLang, target = props.target, rel = props.rel, download = props.download === true ? "" : props.download || undefined, linkExtra = { ping: props.ping, referrerpolicy: props.referrerPolicy }, controls = sub ? submenuId(state, key) : undefined;
+    const describedBy = () => [slotIdRef(description, false), slotIdRef(kbd, false)].filter(Boolean).join(" ") || undefined;
+    const tabIndex = () => {
+        const t = itemTabIndex(state, key, isDisabled || !!liveDisabled?.());
+        // If a submenu is expanded, set the tabIndex to -1 so that shift tabbing goes out of the menu.
+        if (virtualFocus?.())
+            return undefined;
+        return t != null && isOpen() && !state.options.shouldUseVirtualFocus ? -1 : t;
+    };
+    // The item element: the submenu popover's trigger ref (+ the user's / context ref).
+    const element = scope ? scope.itemRef : createRef();
+    const r = mergeRefValues(element, ref);
+    const attrs = {
+        id,
+        role,
+        "data-key": String(key),
+        "data-key-type": typeof key === "number" ? "number" : undefined,
+        "data-text": props.textValue,
+        "aria-label": ariaLabel,
+        "aria-disabled": typeof disabled === "function" ? ariaDisabledOf(disabled) : disabled ? "true" : undefined,
+        "data-disabled": typeof disabled === "function" ? dataDisabledOf(disabled) : dataBool(disabled),
+        "aria-haspopup": hasSubmenu ? "menu" : undefined,
+        "data-has-submenu": dataBool(hasSubmenu),
+    };
+    const renderItem = () => {
+        count();
+        const content = body();
+        if (props.render) {
+            const common = {
+                ...dom,
+                ...attrs,
+                ref: r,
+                class: () => rp.class(),
+                style: () => rp.style(),
+                "aria-labelledby": () => slotIdRef(label, false),
+                "aria-describedby": () => describedBy(),
+                "aria-checked": selectionMode !== "none" && !hasSubmenu ? () => String(isSelected()) : undefined,
+                "aria-expanded": hasSubmenu ? () => String(isOpen()) : undefined,
+                "aria-controls": () => (hasSubmenu && isOpen() ? controls : undefined),
+                "data-focused": () => dataBool(isFocused()),
+                "data-selected": () => dataBool(isSelected()),
+                "data-selection-mode": selectionMode === "none" ? undefined : selectionMode,
+                "data-open": () => dataBool(isOpen()),
+                children: () => content,
+            };
+            return props.render((href
+                ? {
+                    ...common,
+                    href,
+                    hreflang: hrefLang,
+                    target,
+                    rel,
+                    download,
+                    ...linkExtra,
+                    tabindex: () => (virtualFocus?.() ? undefined : (tabIndex() ?? -1)),
+                }
+                : { ...common, tabindex: () => tabIndex() }), values);
+        }
+        if (href)
+            return (<a {...dom} {...attrs} ref={r} href={href} hreflang={hrefLang} target={target} rel={rel} download={download} {...linkExtra} class={rp.class()} style={rp.style()} aria-labelledby={slotIdRef(label, false)} aria-describedby={describedBy()} aria-checked={selectionMode !== "none" && !hasSubmenu ? String(isSelected()) : undefined} aria-expanded={hasSubmenu ? String(isOpen()) : undefined} aria-controls={hasSubmenu && isOpen() ? controls : undefined} tabIndex={virtualFocus?.() ? undefined : (tabIndex() ?? -1)} data-focused={dataBool(isFocused())} data-selected={dataBool(isSelected())} data-selection-mode={selectionMode === "none" ? undefined : selectionMode} data-open={dataBool(isOpen())}>
+          {content}
+        </a>);
+        return (<div {...dom} {...attrs} ref={r} class={rp.class()} style={rp.style()} aria-labelledby={slotIdRef(label, false)} aria-describedby={describedBy()} aria-checked={selectionMode !== "none" && !hasSubmenu ? String(isSelected()) : undefined} aria-expanded={hasSubmenu ? String(isOpen()) : undefined} aria-controls={hasSubmenu && isOpen() ? controls : undefined} tabIndex={tabIndex()} data-focused={dataBool(isFocused())} data-selected={dataBool(isSelected())} data-selection-mode={selectionMode === "none" ? undefined : selectionMode} data-open={dataBool(isOpen())}>
+        {content}
+      </div>);
+    };
+    // Live-mode filtering (SelectableCollectionContext `filter`): the item hides itself.
+    const filter = collectionScope?.filter;
+    if (filter) {
+        const itemText = item.textValue ?? props.textValue ?? "", itemValue = item.value;
+        const visible = () => filter(itemText, { key, type: "item", textValue: itemText, value: itemValue });
+        return <Show when={visible}>{renderItem}</Show>;
+    }
+    return renderItem();
+});
+/** A sentinel that loads more items when scrolled into view, plus a loading row (RAC `MenuLoadMoreItem`). */
+export const MenuLoadMoreItem = /*#__PURE__*/ createLeafComponent(LoaderNode, function MenuLoadingIndicator(props, ref) {
+    const state = useContext(MenuStateContext);
+    const sentinel = createRef();
+    const { isLoading, onLoadMore, scrollOffset, children } = props;
+    loadMoreSentinel({ collection: () => state?.itemCount(), onLoadMore, scrollOffset }, sentinel);
+    const dom = globalDOMProps(props, ["style"]);
+    const cls = props.class ?? "rv-MenuLoadingIndicator", style = props.style;
+    return (<>
+      <div style={{ position: "relative", width: "0", height: "0" }} inert>
+        <div data-testid="loadMoreSentinel" ref={sentinel} style={{ position: "absolute", height: "1px", width: "1px" }}/>
+      </div>
+      {read(isLoading) && children ? (<div {...dom} class={cls} style={style} role="menuitem" tabIndex={-1} ref={ref}>
+          {children}
+        </div>) : null}
+    </>);
+});