[menu] Allow onKeyDown handlers to be called at Group level

Author: atomiks

packages/react/src/floating-ui-react/hooks/useTypeahead.ts

@@ -2,11 +2,22 @@ import * as React from 'react';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useTimeout } from '@base-ui/utils/useTimeout';
-import { contains, stopEvent } from '../utils';
+import { contains } from '../utils';
 
 import type { ElementProps, FloatingContext, FloatingRootContext } from '../types';
 import { EMPTY_ARRAY } from '../../utils/constants';
 
+// Track handled native events without mutating them so ancestors can skip typeahead.
+const handledTypeaheadEvents = new WeakSet<Event>();
+
+function isTypeaheadEventHandled(event: React.KeyboardEvent) {
+  return handledTypeaheadEvents.has(event.nativeEvent);
+}
+
+function markTypeaheadEventHandled(event: React.KeyboardEvent) {
+  handledTypeaheadEvents.add(event.nativeEvent);
+}
+
 export interface UseTypeaheadProps {
   /**
    * A ref which contains an array of strings whose indices match the HTML
@@ -45,6 +56,11 @@ export interface UseTypeaheadProps {
    * @default 750
    */
   resetMs?: number | undefined;
+  /**
+   * Whether to stop event propagation after typeahead handles the key.
+   * @default true
+   */
+  stopPropagation?: boolean | undefined;
   /**
    * An array of keys to ignore when typing.
    * @default []
@@ -77,6 +93,7 @@ export function useTypeahead(
     enabled = true,
     findMatch = null,
     resetMs = 750,
+    stopPropagation = true,
     ignoreKeys = EMPTY_ARRAY,
     selectedIndex = null,
   } = props;
@@ -118,7 +135,24 @@ export function useTypeahead(
     }
   });
 
+  function handleTypeaheadEvent(event: React.KeyboardEvent) {
+    markTypeaheadEventHandled(event);
+    event.preventDefault();
+
+    if (stopPropagation) {
+      event.stopPropagation();
+    }
+  }
+
   const onKeyDown = useStableCallback((event: React.KeyboardEvent) => {
+    // Allow bubbling for group handlers, but avoid parent typeahead re-running.
+    if (isTypeaheadEventHandled(event)) {
+      if (stopPropagation) {
+        event.stopPropagation();
+      }
+      return;
+    }
+
     function getMatchingIndex(
       list: Array<string | null>,
       orderedList: Array<string | null>,
@@ -139,7 +173,7 @@ export function useTypeahead(
       if (getMatchingIndex(listContent, listContent, stringRef.current) === -1) {
         setTypingChange(false);
       } else if (event.key === ' ') {
-        stopEvent(event);
+        handleTypeaheadEvent(event);
       }
     }
 
@@ -157,7 +191,7 @@ export function useTypeahead(
     }
 
     if (open && event.key !== ' ') {
-      stopEvent(event);
+      handleTypeaheadEvent(event);
       setTypingChange(true);
     }
 

packages/react/src/menu/group/MenuGroup.test.tsx

@@ -1,5 +1,5 @@
-import { screen } from '@mui/internal-test-utils';
-import { expect } from 'chai';
+import { flushMicrotasks, screen } from '@mui/internal-test-utils';
+import { expect, vi } from 'vitest';
 import { Menu } from '@base-ui/react/menu';
 import { createRenderer, describeConformance } from '#test-utils';
 
@@ -15,4 +15,45 @@ describe('<Menu.Group />', () => {
     await render(<Menu.Group />);
     expect(screen.getByRole('group')).toBeVisible();
   });
+
+  it('calls the group keydown handler without triggering parent typeahead in an open submenu', async () => {
+    const handleKeyDown = vi.fn();
+
+    const { user } = await render(
+      <Menu.Root open>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              <Menu.Group onKeyDown={handleKeyDown}>
+                <Menu.Item>Apple</Menu.Item>
+                <Menu.Item>Banana</Menu.Item>
+                <Menu.SubmenuRoot open>
+                  <Menu.SubmenuTrigger>More</Menu.SubmenuTrigger>
+                  <Menu.Portal>
+                    <Menu.Positioner>
+                      <Menu.Popup>
+                        <Menu.Item closeOnClick={false}>Sub item</Menu.Item>
+                      </Menu.Popup>
+                    </Menu.Positioner>
+                  </Menu.Portal>
+                </Menu.SubmenuRoot>
+              </Menu.Group>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>,
+    );
+
+    await flushMicrotasks();
+
+    const parentMatchItem = screen.getByRole('menuitem', { name: 'Banana' });
+    const subItem = screen.getByRole('menuitem', { name: 'Sub item' });
+    expect(parentMatchItem).not.toHaveAttribute('data-highlighted');
+
+    await user.click(subItem);
+    await user.keyboard('b');
+
+    expect(handleKeyDown).toHaveBeenCalled();
+    expect(parentMatchItem).not.toHaveAttribute('data-highlighted');
+  });
 });

packages/react/src/menu/root/MenuRoot.tsx

@@ -470,6 +470,9 @@ export const MenuRoot = fastComponent(function MenuRoot<Payload>(props: MenuRoot
     listRef: store.context.itemLabels,
     activeIndex,
     resetMs: TYPEAHEAD_RESET_MS,
+    // Let keydown bubble in nested menus so group handlers can run, but still mark the
+    // event so parent menus skip typeahead.
+    stopPropagation: parent.type !== 'menu' && parent.type !== 'nested-context-menu',
     onMatch: (index) => {
       if (open && index !== activeIndex) {
         store.set('activeIndex', index);