@proyecto-viviana/solidaria-components 0.3.2 → 0.4.0

package/src/Menu.tsx

@@ -26,6 +26,7 @@ import {
   createHover,
   createButton,
   createInteractOutside,
+  createScrollIntoViewOnFocus,
   mergeProps,
   FocusScope,
   type AriaMenuProps,
@@ -86,7 +87,7 @@ export interface MenuRenderProps {
 
 export interface MenuProps<T>
   extends
-    Omit<AriaMenuProps, "children">,
+    Omit<AriaMenuProps<T>, "children">,
     SlotProps,
     Pick<
       MenuStateProps<T>,
@@ -108,8 +109,10 @@ export interface MenuProps<T>
   getDisabled?: (item: T) => boolean;
   /** Keys of disabled items. */
   disabledKeys?: Iterable<Key>;
-  /** Handler called when an item is activated. */
-  onAction?: (key: Key) => void;
+  /** Whether disabled items can still receive focus. */
+  disabledBehavior?: "selection" | "all";
+  /** Handler called when an item is activated, with the activated item's value. */
+  onAction?: (key: Key, value: T) => void;
   /** Handler called when the menu should close. */
   onClose?: () => void;
   /** The children of the component. A function may be provided to render each item. */
@@ -125,12 +128,9 @@ export interface MenuProps<T>
   /** Whether the menu should close when an item is selected. */
   shouldCloseOnSelect?: boolean;
   /** Ref for the menu element. */
-  ref?: RefLike<HTMLUListElement>;
+  ref?: RefLike<HTMLDivElement>;
   /** Custom renderer for the menu element. */
-  render?: (
-    props: JSX.HTMLAttributes<HTMLUListElement>,
-    renderProps: MenuRenderProps,
-  ) => JSX.Element;
+  render?: (props: JSX.HTMLAttributes<HTMLDivElement>, renderProps: MenuRenderProps) => JSX.Element;
   /** Drag and drop hooks from `useDragAndDrop`. */
   dragAndDropHooks?: DragAndDropHooks<T>;
 }
@@ -154,9 +154,22 @@ export interface MenuItemRenderProps {
   hasSubmenu: boolean;
   /** Whether the submenu is currently open. */
   isOpen: boolean;
+  /**
+   * Internal: props (carrying the slot `id` the item's `aria-describedby`
+   * references) for the item's description text element. Threaded to the styled
+   * `Text slot="description"` so it receives the id — mirrors upstream's
+   * `TextContext` description-slot delegation.
+   */
+  descriptionProps?: JSX.HTMLAttributes<HTMLElement>;
+  /**
+   * Internal: props (id + `aria-hidden`) for the item's keyboard-shortcut
+   * element, threaded to the styled `Keyboard`.
+   */
+  keyboardShortcutProps?: JSX.HTMLAttributes<HTMLElement>;
 }
 
-export interface MenuItemProps<T> extends Omit<AriaMenuItemProps, "children" | "key">, SlotProps {
+export interface MenuItemProps<T>
+  extends Omit<AriaMenuItemProps, "children" | "key" | "id">, SlotProps {
   /** The unique key for the item. */
   id: Key;
   /** The item value. */
@@ -185,11 +198,11 @@ export interface MenuItemProps<T> extends Omit<AriaMenuItemProps, "children" | "
   onHoverEnd?: () => void;
   /** Handler called when hover state changes. */
   onHoverChange?: (isHovered: boolean) => void;
-  /** Ref for the menu item element. */
-  ref?: RefLike<HTMLLIElement>;
+  /** Ref for the menu item element (a `<div>`, or an `<a>` for link items). */
+  ref?: RefLike<HTMLElement>;
   /** Custom renderer for the menu item element. */
   render?: (
-    props: JSX.HTMLAttributes<HTMLLIElement>,
+    props: JSX.HTMLAttributes<HTMLElement>,
     renderProps: MenuItemRenderProps,
   ) => JSX.Element;
 }
@@ -249,13 +262,15 @@ interface MenuTriggerContextValue {
   state: OverlayTriggerState;
   triggerProps: JSX.HTMLAttributes<HTMLElement>;
   menuProps: JSX.HTMLAttributes<HTMLElement>;
+  isPressed?: () => boolean;
+  onPressStart?: (e: { pointerType?: string }) => void;
 }
 
 interface MenuItemContextValue {
   props?: () => JSX.HTMLAttributes<HTMLElement>;
   closeOnSelect?: boolean;
   onAction?: () => void;
-  setItemRef?: (el: HTMLLIElement | null) => void;
+  setItemRef?: (el: HTMLElement | null) => void;
 }
 
 interface StaticMenuCollectionItem {
@@ -283,6 +298,12 @@ interface MenuSectionSelectionRegistryContextValue {
   selectItem(key: Key, event?: MenuSelectionEvent): boolean;
 }
 
+interface MenuItemCloseRegistryContextValue {
+  registerItem(key: Key, shouldCloseOnSelect: () => boolean | undefined): void;
+  unregisterItem(key: Key, shouldCloseOnSelect: () => boolean | undefined): void;
+  shouldCloseOnSelect(key: Key | null): boolean | undefined;
+}
+
 export const MenuContext = createContext<MenuContextValue<unknown> | null>(null);
 export const MenuStateContext = createContext<MenuState<unknown> | null>(null);
 export const MenuTriggerContext = createContext<MenuTriggerContextValue | null>(null);
@@ -292,6 +313,7 @@ const StaticMenuCollectionContext = createContext<StaticMenuCollectionContextVal
 const MenuSectionSelectionContext = createContext<MenuSectionSelectionContextValue | null>(null);
 const MenuSectionSelectionRegistryContext =
   createContext<MenuSectionSelectionRegistryContextValue | null>(null);
+const MenuItemCloseRegistryContext = createContext<MenuItemCloseRegistryContextValue | null>(null);
 
 type RefLike<T> = ((el: T) => void) | { current?: T | null } | undefined;
 
@@ -323,6 +345,22 @@ export function MenuTrigger(props: MenuTriggerProps): JSX.Element {
     },
   });
 
+  const [isMousePressed, setMousePressed] = createSignal(false);
+  const onPressStart = (e: { pointerType?: string }) => {
+    if (e.pointerType !== "mouse" || typeof document === "undefined") {
+      return;
+    }
+
+    setMousePressed(true);
+    document.addEventListener(
+      "pointerup",
+      () => {
+        setMousePressed(false);
+      },
+      { once: true, capture: true },
+    );
+  };
+
   const menuTrigger = createMenuTrigger(
     {
       get isDisabled() {
@@ -343,6 +381,8 @@ export function MenuTrigger(props: MenuTriggerProps): JSX.Element {
           get menuProps() {
             return menuTrigger.menuProps;
           },
+          isPressed: isMousePressed,
+          onPressStart,
         }}
       >
         {props.children}
@@ -369,7 +409,7 @@ export function SubmenuTrigger(props: SubmenuTriggerProps): JSX.Element {
     },
   });
 
-  let triggerRef: HTMLLIElement | null = null;
+  let triggerRef: HTMLElement | null = null;
   const triggerId = createUniqueId();
   const menuId = createUniqueId();
   let hoverTimeout: number | undefined;
@@ -448,7 +488,7 @@ export function SubmenuTrigger(props: SubmenuTriggerProps): JSX.Element {
     },
     triggerRef: () => triggerRef,
     setTriggerRef: (el: HTMLElement | null) => {
-      triggerRef = el as HTMLLIElement | null;
+      triggerRef = el;
     },
     triggerId,
     trigger: "SubmenuTrigger",
@@ -550,6 +590,9 @@ export function MenuButton(props: MenuButtonProps): JSX.Element {
     get isDisabled() {
       return local.isDisabled;
     },
+    onPressStart(e) {
+      context.onPressStart?.(e);
+    },
     onPress() {
       state.toggle();
     },
@@ -567,14 +610,16 @@ export function MenuButton(props: MenuButtonProps): JSX.Element {
     isOpen: state.isOpen(),
     isFocused: isFocused(),
     isFocusVisible: isFocusVisible(),
-    isPressed: buttonAria.isPressed(),
+    isPressed: context.isPressed?.() || buttonAria.isPressed(),
     isHovered: isHovered(),
     isDisabled: !!local.isDisabled,
   }));
 
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      get children() {
+        return props.children;
+      },
       class: local.class,
       style: local.style,
       defaultClassName: "solidaria-MenuButton",
@@ -624,7 +669,7 @@ export function MenuButton(props: MenuButtonProps): JSX.Element {
       data-open={state.isOpen() || undefined}
       data-focused={isFocused() || undefined}
       data-focus-visible={isFocusVisible() || undefined}
-      data-pressed={buttonAria.isPressed() || undefined}
+      data-pressed={context.isPressed?.() || buttonAria.isPressed() || undefined}
       data-hovered={isHovered() || undefined}
       data-disabled={local.isDisabled || undefined}
     >
@@ -639,23 +684,14 @@ export function MenuButton(props: MenuButtonProps): JSX.Element {
 export function Menu<T>(props: MenuProps<T>): JSX.Element {
   const [local, stateProps, ariaProps] = splitProps(
     props,
-    [
-      "children",
-      "class",
-      "style",
-      "render",
-      "slot",
-      "renderEmptyState",
-      "shouldCloseOnSelect",
-      "ref",
-      "staticChildren",
-    ],
+    ["children", "class", "style", "render", "slot", "renderEmptyState", "ref", "staticChildren"],
     [
       "items",
       "getKey",
       "getTextValue",
       "getDisabled",
       "disabledKeys",
+      "disabledBehavior",
       "selectionMode",
       "selectionBehavior",
       "disallowEmptySelection",
@@ -665,16 +701,18 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       "allowDuplicateSelectionEvents",
       "onAction",
       "onClose",
+      "shouldCloseOnSelect",
       "dragAndDropHooks",
     ],
   );
 
   const triggerContext = useContext(MenuTriggerContext);
 
-  const [menuRef, setMenuRef] = createSignal<HTMLUListElement | null>(null);
+  const [menuRef, setMenuRef] = createSignal<HTMLDivElement | null>(null);
   const [staticItems, setStaticItems] = createSignal<StaticMenuCollectionItem[]>([]);
   const staticItemMap = new Map<Key, StaticMenuCollectionItem>();
   const sectionSelectionMap = new Map<Key, MenuSectionSelectionContextValue>();
+  const itemCloseMap = new Map<Key, () => boolean | undefined>();
   const usesStaticChildren = () => local.staticChildren != null || stateProps.items == null;
 
   const syncStaticItems = () => {
@@ -720,9 +758,27 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       return true;
     },
   };
-  const handleAction = (key: Key) => {
+  const itemCloseRegistry: MenuItemCloseRegistryContextValue = {
+    registerItem(key, shouldCloseOnSelect) {
+      itemCloseMap.set(key, shouldCloseOnSelect);
+    },
+    unregisterItem(key, shouldCloseOnSelect) {
+      if (itemCloseMap.get(key) === shouldCloseOnSelect) {
+        itemCloseMap.delete(key);
+      }
+    },
+    shouldCloseOnSelect(key) {
+      return key == null ? undefined : itemCloseMap.get(key)?.();
+    },
+  };
+  const handleAction = (key: Key, value?: T) => {
     sectionSelectionRegistry.selectItem(key);
-    stateProps.onAction?.(key);
+    // Forward the activated item's value, which `createMenuState` sets from the
+    // collection node. For dynamic collections this is the user's data item.
+    // Static children are modeled with an internal item descriptor that upstream
+    // RAC does not expose as `value` (MenuItem only carries `value` for dynamic
+    // collections), so it is suppressed there to match.
+    stateProps.onAction?.(key, (usesStaticChildren() ? undefined : value) as T);
   };
 
   const flatItems = createMemo<T[]>(() => {
@@ -757,6 +813,9 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
     get disabledKeys() {
       return stateProps.disabledKeys;
     },
+    get disabledBehavior() {
+      return stateProps.disabledBehavior;
+    },
     get selectionMode() {
       return stateProps.selectionMode;
     },
@@ -808,6 +867,12 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       get onClose() {
         return stateProps.onClose ?? (() => triggerContext?.state.close());
       },
+      get shouldCloseOnSelect() {
+        return (
+          itemCloseRegistry.shouldCloseOnSelect(state.focusedKey()) ??
+          stateProps.shouldCloseOnSelect
+        );
+      },
       get "aria-label"() {
         return ariaProps["aria-label"];
       },
@@ -821,6 +886,15 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
     state,
   );
 
+  // Reveal the activedescendant-focused item on keyboard navigation. The menu
+  // keeps real DOM focus on itself, so the browser won't natively scroll an
+  // off-screen focused item into view the way roving tabindex would.
+  createScrollIntoViewOnFocus({
+    focusedKey: () => state.focusedKey(),
+    isActive: () => state.isFocused(),
+    ref: () => menuRef(),
+  });
+
   const { isFocused, focusProps } = createFocusRing();
 
   createInteractOutside({
@@ -870,7 +944,7 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
     const { ref: _ref4, ...rest } = labelProps as Record<string, unknown>;
     return rest;
   };
-  const setResolvedMenuRef = (el: HTMLUListElement): void => {
+  const setResolvedMenuRef = (el: HTMLDivElement): void => {
     setMenuRef(el);
     assignRef(local.ref, el);
   };
@@ -1067,31 +1141,31 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       parentCollectionRenderer?.renderDropIndicator?.(index, position),
   }));
   const menuItemContextValue = createMemo<MenuItemContextValue>(() =>
-    local.shouldCloseOnSelect !== undefined
-      ? { closeOnSelect: local.shouldCloseOnSelect }
+    stateProps.shouldCloseOnSelect !== undefined
+      ? { closeOnSelect: stateProps.shouldCloseOnSelect }
       : {},
   );
   const menuListChildren = () => (
     <SharedElementTransition>
       {state.collection().size === 0 && !usesStaticChildren() && local.renderEmptyState ? (
-        <li role="presentation" data-empty-state>
+        <div role="presentation" data-empty-state>
           <div role="menuitem" style={{ display: "contents" }}>
             {local.renderEmptyState()}
           </div>
-        </li>
+        </div>
       ) : usesStaticChildren() ? (
         renderStaticChildren()
       ) : hasSections() ? (
         <For each={sectionedRenderEntries()}>
           {(entry) =>
             entry.type === "section" ? (
-              <li role="presentation" data-section-wrapper>
+              <div role="presentation" data-section-wrapper>
                 <Section class="solidaria-Menu-section">
                   {entry.section.title != null && (
                     <Header class="solidaria-Menu-sectionHeader">{entry.section.title}</Header>
                   )}
                   <Group class="solidaria-Menu-sectionGroup">
-                    <ul role="group" aria-label={entry.section["aria-label"]}>
+                    <div role="group" aria-label={entry.section["aria-label"]}>
                       <For each={entry.items}>
                         {(indexedItem) => (
                           <>
@@ -1105,10 +1179,10 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
                           </>
                         )}
                       </For>
-                    </ul>
+                    </div>
                   </Group>
                 </Section>
-              </li>
+              </div>
             ) : (
               <>
                 {collectionRenderer().renderDropIndicator?.(entry.item.index, "before")}
@@ -1122,7 +1196,7 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       ) : (
         <>
           {virtualRange()?.offsetTop ? (
-            <li
+            <div
               role="presentation"
               aria-hidden="true"
               style={{ height: `${virtualRange()!.offsetTop}px` }}
@@ -1149,7 +1223,7 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
             }}
           </For>
           {virtualRange()?.offsetBottom ? (
-            <li
+            <div
               role="presentation"
               aria-hidden="true"
               style={{ height: `${virtualRange()!.offsetBottom}px` }}
@@ -1178,7 +1252,7 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
       "data-empty": state.collection().size === 0 || undefined,
       "data-drop-target": isRootDropTarget() || undefined,
       children: menuListChildren(),
-    }) as JSX.HTMLAttributes<HTMLUListElement>;
+    }) as JSX.HTMLAttributes<HTMLDivElement>;
 
   // Only use FocusScope when inside a MenuTrigger (for popover behavior)
   // Standalone menus don't need focus restoration
@@ -1196,44 +1270,46 @@ export function Menu<T>(props: MenuProps<T>): JSX.Element {
     >
       <MenuStateContext.Provider value={state}>
         <MenuSectionSelectionRegistryContext.Provider value={sectionSelectionRegistry}>
-          <StaticMenuCollectionContext.Provider
-            value={usesStaticChildren() ? staticCollectionContext : null}
-          >
-            <MenuItemContext.Provider value={menuItemContextValue()}>
-              <CollectionRendererContext.Provider value={collectionRenderer()}>
-                <>
-                  <Show when={ariaProps.label}>
-                    <span {...cleanLabelProps()}>{ariaProps.label as JSX.Element}</span>
-                  </Show>
-                  {local.render ? (
-                    local.render(menuListProps(), renderValues())
-                  ) : (
-                    <ul
-                      ref={setResolvedMenuRef}
-                      {...mergeProps(
-                        domProps(),
-                        cleanMenuProps(),
-                        cleanTriggerMenuProps(),
-                        cleanFocusProps(),
-                        (droppableCollection()?.collectionProps as
-                          | Record<string, unknown>
-                          | undefined) ?? {},
-                      )}
-                      class={renderProps.class()}
-                      style={renderProps.style()}
-                      slot={local.slot}
-                      data-focused={state.isFocused() || undefined}
-                      data-disabled={resolveDisabled() || undefined}
-                      data-empty={state.collection().size === 0 || undefined}
-                      data-drop-target={isRootDropTarget() || undefined}
-                    >
-                      {menuListChildren()}
-                    </ul>
-                  )}
-                </>
-              </CollectionRendererContext.Provider>
-            </MenuItemContext.Provider>
-          </StaticMenuCollectionContext.Provider>
+          <MenuItemCloseRegistryContext.Provider value={itemCloseRegistry}>
+            <StaticMenuCollectionContext.Provider
+              value={usesStaticChildren() ? staticCollectionContext : null}
+            >
+              <MenuItemContext.Provider value={menuItemContextValue()}>
+                <CollectionRendererContext.Provider value={collectionRenderer()}>
+                  <>
+                    <Show when={ariaProps.label}>
+                      <span {...cleanLabelProps()}>{ariaProps.label as JSX.Element}</span>
+                    </Show>
+                    {local.render ? (
+                      local.render(menuListProps(), renderValues())
+                    ) : (
+                      <div
+                        ref={setResolvedMenuRef}
+                        {...mergeProps(
+                          domProps(),
+                          cleanMenuProps(),
+                          cleanTriggerMenuProps(),
+                          cleanFocusProps(),
+                          (droppableCollection()?.collectionProps as
+                            | Record<string, unknown>
+                            | undefined) ?? {},
+                        )}
+                        class={renderProps.class()}
+                        style={renderProps.style()}
+                        slot={local.slot}
+                        data-focused={state.isFocused() || undefined}
+                        data-disabled={resolveDisabled() || undefined}
+                        data-empty={state.collection().size === 0 || undefined}
+                        data-drop-target={isRootDropTarget() || undefined}
+                      >
+                        {menuListChildren()}
+                      </div>
+                    )}
+                  </>
+                </CollectionRendererContext.Provider>
+              </MenuItemContext.Provider>
+            </StaticMenuCollectionContext.Provider>
+          </MenuItemCloseRegistryContext.Provider>
         </MenuSectionSelectionRegistryContext.Provider>
       </MenuStateContext.Provider>
     </MenuContext.Provider>
@@ -1283,17 +1359,26 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
   const staticCollection = useContext(StaticMenuCollectionContext);
   const sectionSelection = useContext(MenuSectionSelectionContext);
   const sectionSelectionRegistry = useContext(MenuSectionSelectionRegistryContext);
-  const [ref, setRef] = createSignal<HTMLLIElement | null>(null);
+  const itemCloseRegistry = useContext(MenuItemCloseRegistryContext);
+  // Tracks the focusable menuitem element (the <div>, or the <a> for link
+  // items) so roving focus can be moved onto it imperatively.
+  const [ref, setRef] = createSignal<HTMLElement | null>(null);
   const contextProps = () => itemContext?.props?.() ?? {};
   const combinedOnAction = () => {
     local.onAction?.();
     itemContext?.onAction?.();
   };
+  const itemCloseOnSelect = () =>
+    ariaProps.closeOnSelect ??
+    sectionSelection?.shouldCloseOnSelect() ??
+    itemContext?.closeOnSelect;
   const activeSectionSelection = () =>
     sectionSelection && sectionSelection.selectionMode() !== "none" ? sectionSelection : null;
   let registeredStaticKey: Key | null = null;
   let registeredSectionSelectionKey: Key | null = null;
   let registeredSectionSelection: MenuSectionSelectionContextValue | null = null;
+  let registeredCloseKey: Key | null = null;
+  let registeredCloseAccessor: (() => boolean | undefined) | null = null;
 
   const unregisterSectionSelection = () => {
     if (registeredSectionSelectionKey != null && registeredSectionSelection) {
@@ -1347,9 +1432,38 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
 
   onCleanup(unregisterSectionSelection);
 
+  const unregisterItemClose = () => {
+    if (registeredCloseKey != null && registeredCloseAccessor) {
+      itemCloseRegistry?.unregisterItem(registeredCloseKey, registeredCloseAccessor);
+      registeredCloseKey = null;
+      registeredCloseAccessor = null;
+    }
+  };
+
+  createEffect(() => {
+    if (!itemCloseRegistry) {
+      unregisterItemClose();
+      return;
+    }
+
+    if (registeredCloseKey === local.id && registeredCloseAccessor === itemCloseOnSelect) {
+      return;
+    }
+
+    unregisterItemClose();
+    registeredCloseKey = local.id;
+    registeredCloseAccessor = itemCloseOnSelect;
+    itemCloseRegistry.registerItem(local.id, itemCloseOnSelect);
+  });
+
+  onCleanup(unregisterItemClose);
+
   const itemAria = createMenuItem<T>(
     {
       key: local.id,
+      get id() {
+        return contextProps().id as string | undefined;
+      },
       get isDisabled() {
         return Boolean(
           ariaProps.isDisabled ||
@@ -1360,15 +1474,20 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
       get "aria-label"() {
         return ariaProps["aria-label"] ?? local.textValue;
       },
+      get "aria-controls"() {
+        return contextProps()["aria-controls"] as string | undefined;
+      },
+      get "aria-haspopup"() {
+        return contextProps()["aria-haspopup"] as string | boolean | undefined;
+      },
+      get "aria-expanded"() {
+        return contextProps()["aria-expanded"] as boolean | "true" | "false" | undefined;
+      },
       get onAction() {
         return combinedOnAction;
       },
       get closeOnSelect() {
-        return (
-          ariaProps.closeOnSelect ??
-          sectionSelection?.shouldCloseOnSelect() ??
-          itemContext?.closeOnSelect
-        );
+        return itemCloseOnSelect();
       },
       get href() {
         return local.href;
@@ -1384,6 +1503,7 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
       },
     },
     state,
+    () => ref(),
   );
 
   const { isHovered, hoverProps } = createHover({
@@ -1407,12 +1527,16 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
       isDisabled: itemAria.isDisabled(),
       hasSubmenu: Boolean(contextProps()["aria-haspopup"]),
       isOpen: contextProps()["aria-expanded"] === true,
+      descriptionProps: itemAria.descriptionProps,
+      keyboardShortcutProps: itemAria.keyboardShortcutProps,
     };
   });
 
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      get children() {
+        return props.children;
+      },
       class: local.class,
       style: local.style,
       defaultClassName: "solidaria-Menu-item",
@@ -1424,11 +1548,13 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
   };
 
   const cleanItemProps = () => {
-    const {
-      ref: _ref1,
-      "aria-describedby": _ariaDescribedby,
-      ...rest
-    } = itemAria.menuItemProps as Record<string, unknown>;
+    // Keep `aria-describedby`: the headless emits it (via `createSlotId`) only
+    // when a description/keyboard element is actually rendered, so it points at
+    // the styled `Text slot="description"` + `Keyboard` ids threaded through
+    // `renderValues` below — restoring upstream's two-context description
+    // delegation. `createSlotId` clears it to `undefined` on description-less
+    // items, so nothing dangles.
+    const { ref: _ref1, ...rest } = itemAria.menuItemProps as Record<string, unknown>;
     if (!hasPrimitiveLabel() && rest["aria-label"] == null) {
       delete rest["aria-labelledby"];
     }
@@ -1519,7 +1645,7 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
     ) : (
       renderProps.renderChildren()
     );
-  const setResolvedItemRef = (el: HTMLLIElement | null) => {
+  const setResolvedItemRef = (el: HTMLElement | null) => {
     setRef(el);
     itemContext?.setItemRef?.(el);
     if (el) assignRef(local.ref, el);
@@ -1539,7 +1665,7 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
       style: renderProps.style(),
       ...dataAttrs(),
       children: childContent(),
-    }) as JSX.HTMLAttributes<HTMLLIElement>;
+    }) as JSX.HTMLAttributes<HTMLElement>;
   const linkMenuItemProps = () =>
     ({
       ...mergeProps(
@@ -1555,7 +1681,7 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
       style: renderProps.style(),
       ...dataAttrs(),
       children: childContent(),
-    }) as JSX.HTMLAttributes<HTMLLIElement>;
+    }) as JSX.HTMLAttributes<HTMLElement>;
 
   if (local.render && !isLink()) {
     return local.render(menuItemProps(), renderValues());
@@ -1565,7 +1691,7 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
     <Show
       when={isLink()}
       fallback={
-        <li
+        <div
           ref={(el) => {
             setRef(el);
             itemContext?.setItemRef?.(el);
@@ -1584,38 +1710,36 @@ export function MenuItem<T>(props: MenuItemProps<T>): JSX.Element {
           {...dataAttrs()}
         >
           {childContent()}
-        </li>
+        </div>
       }
     >
-      <li
-        ref={(el) => {
-          setRef(el);
-          itemContext?.setItemRef?.(el);
-          assignRef(local.ref, el);
-        }}
-        role="presentation"
-      >
-        {local.render ? (
-          local.render(linkMenuItemProps(), renderValues())
-        ) : (
-          <a
-            {...mergeProps(
-              cleanItemPropsForLink(),
-              contextProps() as Record<string, unknown>,
-              domProps(),
-              cleanHoverProps(),
-              linkDomProps(),
-              (draggableItem()?.dragProps as Record<string, unknown> | undefined) ?? {},
-              (droppableItem()?.dropProps as Record<string, unknown> | undefined) ?? {},
-            )}
-            class={renderProps.class()}
-            style={renderProps.style()}
-            {...dataAttrs()}
-          >
-            {childContent()}
-          </a>
-        )}
-      </li>
+      {local.render ? (
+        local.render(linkMenuItemProps(), renderValues())
+      ) : (
+        // Upstream renders the link menuitem as a bare <a role="menuitem"> (no
+        // presentation wrapper); the <div> root makes the wrapper unnecessary.
+        <a
+          ref={(el) => {
+            setRef(el);
+            itemContext?.setItemRef?.(el);
+            assignRef(local.ref, el);
+          }}
+          {...mergeProps(
+            cleanItemPropsForLink(),
+            contextProps() as Record<string, unknown>,
+            domProps(),
+            cleanHoverProps(),
+            linkDomProps(),
+            (draggableItem()?.dragProps as Record<string, unknown> | undefined) ?? {},
+            (droppableItem()?.dropProps as Record<string, unknown> | undefined) ?? {},
+          )}
+          class={renderProps.class()}
+          style={renderProps.style()}
+          {...dataAttrs()}
+        >
+          {childContent()}
+        </a>
+      )}
     </Show>
   );
 }