@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

package/src/CommandPalette/CommandPalette.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -36,6 +36,7 @@ import {CommandPaletteInput} from './CommandPaletteInput';
 import {CommandPaletteFooter} from './CommandPaletteFooter';
 import {CommandPaletteEmpty} from './CommandPaletteEmpty';
 import type {BaseProps} from '../BaseProps';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useTranslator} from '../i18n';
 
 export interface CommandPaletteProps<
@@ -268,6 +269,7 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   label: labelFromProps,
   width = 640,
   maxHeight = 480,
+  ...rest
 }: CommandPaletteProps<T>) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.commandPalette.label');
@@ -290,6 +292,13 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const isBusy = isPending;
   const searchVersionRef = useRef(0);
 
+  // Announce search status to screen readers through the shared polite live
+  // region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
+  // The busy spinner and the empty states are otherwise purely visual, so a
+  // screen-reader user typing a query would hear nothing when loading starts
+  // or results disappear.
+  const announce = useAnnounce();
+
   const value = controlledValue ?? internalValue;
 
   const setValue = useCallback(
@@ -317,8 +326,12 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       setInternalValue('');
     }
     searchSource.cancel?.();
+    // Clear any lingering result / loading announcement when the palette
+    // closes so stale status text does not linger in the a11y tree
+    // (matching Selector's onHide).
+    announce('');
     onOpenChange(false);
-  }, [onOpenChange, searchSource, controlledValue]);
+  }, [onOpenChange, searchSource, controlledValue, announce]);
 
   const selectItem = useCallback(
     (itemValue: string) => {
@@ -354,6 +367,14 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       startTransition(async () => {
         const isBootstrap = query === '';
 
+        // Loading started for a user query: tell screen-reader users the
+        // spinner appeared. The polite region coalesces rapid updates, so for
+        // fast sources the result-count announcement below simply replaces
+        // this instead of stacking one "Loading" per keystroke.
+        if (!isBootstrap) {
+          announce(t('@astryx.commandPalette.loading'));
+        }
+
         // Client-filter previous results for instant narrowing while fetch is in flight
         if (!isBootstrap && searchResults.length > 0) {
           const lower = query.toLowerCase().trim();
@@ -376,6 +397,23 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
           setOptimisticResults(items);
           setSearchResults(items);
 
+          // Announce the outcome from the search commit (not a reactive
+          // effect), matching Selector / BaseTypeahead: exactly one
+          // announcement per committed query, and the version check above
+          // already discards stale keystrokes. Bootstrap stays silent — the
+          // same role PowerSearch's mount guard plays — so opening the
+          // palette announces nothing; clearing the query only clears any
+          // lingering status text.
+          if (isBootstrap) {
+            announce('');
+          } else if (items.length === 0) {
+            announce(t('@astryx.commandPalette.noResultsFor', {query}));
+          } else {
+            announce(
+              t('@astryx.commandPalette.resultCount', {count: items.length}),
+            );
+          }
+
           // When opening with a preselected value, highlight it once
           // bootstrap results arrive. No value → highlight stays at -1
           // and ArrowDown naturally moves to the first item.
@@ -395,6 +433,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       value,
       combobox,
       setOptimisticResults,
+      announce,
+      t,
     ],
   );
 
@@ -527,7 +567,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       width={width}
       maxHeight={maxHeight}
       purpose="info"
-      aria-label={label}>
+      aria-label={label}
+      {...rest}>
       <CommandPaletteContext value={contextValue}>
         <Layout
           defaultHasDividers

package/src/CommandPalette/CommandPaletteGroup.test.tsx

@@ -9,6 +9,8 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {CommandPaletteGroup} from './CommandPaletteGroup';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 describe('CommandPaletteGroup', () => {
   it('renders heading', () => {
@@ -51,4 +53,73 @@ describe('CommandPaletteGroup', () => {
       'true',
     );
   });
+
+  // ===========================================================================
+  // Heading theme target
+  // ===========================================================================
+
+  describe('heading theme target', () => {
+    it('renders the astryx-command-palette-group-heading target on the heading', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const heading = screen.getByText('Suggestions');
+
+      // The root carries `astryx-command-palette-group`; this is the stable
+      // handle on the heading itself, so a theme can style just the heading
+      // without a fragile structural selector.
+      expect(heading).toHaveClass('astryx-command-palette-group-heading');
+    });
+
+    it('keeps the heading target distinct from the group root target', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const root = screen.getByRole('group');
+      const heading = screen.getByText('Suggestions');
+
+      expect(root).toHaveClass('astryx-command-palette-group');
+      expect(root).not.toHaveClass('astryx-command-palette-group-heading');
+      expect(heading).not.toHaveClass('astryx-command-palette-group');
+    });
+
+    it('leaves the heading decorative (additive target only)', () => {
+      // The target adds a class and nothing else — the heading stays
+      // aria-hidden so grouping remains announced via the root's aria-label.
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      expect(screen.getByText('Suggestions')).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it('exposes command-palette-group-heading as a themeable defineTheme target', () => {
+      // The generated CSS proves the target is reachable by a theme: jsdom
+      // cannot resolve the @layer cascade, so the DOM-class assertions above
+      // and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'command-palette-group-heading-test',
+        components: {
+          'command-palette-group-heading': {
+            base: {
+              paddingBlock: 'var(--spacing-2)',
+              fontWeight: 'var(--font-weight-bold)',
+            },
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-command-palette-group-heading {');
+      expect(css).toContain('padding-block: var(--spacing-2)');
+      expect(css).toContain('font-weight: var(--font-weight-bold)');
+    });
+  });
 });

package/src/CommandPalette/CommandPaletteGroup.tsx

@@ -90,7 +90,18 @@ export function CommandPaletteGroup({
         style,
       )}
       {...props}>
-      <div aria-hidden="true" {...stylex.props(styles.heading)}>
+      <div
+        aria-hidden="true"
+        {...mergeProps(
+          // Stable theme target for the group heading text. The root carries
+          // `astryx-command-palette-group`, but the heading itself had no
+          // handle, so a theme could only reach it through a fragile structural
+          // selector. This adds an `astryx-command-palette-group-heading` class
+          // so `defineTheme` can scope overrides (e.g. heading typography) to
+          // the heading alone.
+          themeProps('command-palette-group-heading'),
+          stylex.props(styles.heading),
+        )}>
         {heading}
       </div>
       {children}

package/src/CommandPalette/CommandPaletteInput.doc.mjs

@@ -7,7 +7,8 @@ export const docs = {
   subComponentOf: 'CommandPalette',
   displayName: 'Command Palette Input',
   isHiddenFromOverview: true,
-  description: 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
+  description:
+    'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
   props: [
     {
       name: 'placeholder',
@@ -15,16 +16,24 @@ export const docs = {
       description: 'Placeholder text for the input.',
       default: "'Search...'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible label for the combobox input, announced by screen readers. Falls back to the placeholder text when omitted.',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
-      description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
+      description:
+        'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
       default: 'true',
     },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+      description:
+        'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
       slotElements: [
         {
           __element: 'Icon',
@@ -44,17 +53,20 @@ export const docs = {
     {
       name: 'value',
       type: 'string',
-      description: 'Search value. When omitted inside CommandPalette, reads from context.',
+      description:
+        'Search value. When omitted inside CommandPalette, reads from context.',
     },
     {
       name: 'onValueChange',
       type: '(value: string) => void',
-      description: 'Called when search value changes. When omitted inside CommandPalette, writes to context.',
+      description:
+        'Called when search value changes. When omitted inside CommandPalette, writes to context.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
   playground: {
@@ -69,9 +81,11 @@ export const docsZh = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
+  description:
+    '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
   propDescriptions: {
     placeholder: '输入框的占位文本。',
+    label: '组合框输入的无障碍标签，供屏幕阅读器朗读。省略时回退到占位文本。',
     hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
     endContent: '渲染在输入框末尾的内容，位于加载指示器之后。',
     value: '搜索值。在 CommandPalette 内省略时从上下文读取。',
@@ -84,13 +98,16 @@ export const docsDense = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: 'search input; auto-focus on mount; wires to context inside CommandPalette',
+  description:
+    'search input; auto-focus on mount; wires to context inside CommandPalette',
   propDescriptions: {
     placeholder: 'input placeholder text',
+    label: 'accessible label for the combobox; falls back to placeholder',
     hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
     endContent: 'trailing content after spinner',
     value: 'search value; reads context when omitted inside palette',
-    onValueChange: 'called on change; writes context when omitted inside palette',
+    onValueChange:
+      'called on change; writes context when omitted inside palette',
     xstyle: 'StyleX layout styles; must be stylex.create() value',
   },
 };

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -32,6 +32,40 @@ describe('CommandPaletteInput', () => {
     expect(screen.getByRole('combobox')).toBeInTheDocument();
   });
 
+  it('has an accessible name by default', () => {
+    render(<CommandPaletteInput />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Search…',
+    );
+  });
+
+  it('uses the label prop as the accessible name', () => {
+    render(<CommandPaletteInput label="Search commands" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-label', 'Search commands');
+    // The label prop does not affect the visible placeholder
+    expect(input).toHaveAttribute('placeholder', 'Search…');
+  });
+
+  it('falls back to a custom placeholder for the accessible name', () => {
+    render(<CommandPaletteInput placeholder="Type a command..." />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Type a command...',
+    );
+  });
+
+  it('lets a consumer-passed aria-label override the default', () => {
+    render(
+      <CommandPaletteInput label="Search commands" aria-label="Custom name" />,
+    );
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Custom name',
+    );
+  });
+
   it('calls onValueChange when typing', () => {
     const handleChange = vi.fn();
     render(<CommandPaletteInput onValueChange={handleChange} />);

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -109,6 +109,13 @@ export interface CommandPaletteInputProps extends Omit<
    */
   placeholder?: string;
 
+  /**
+   * Accessible label for the combobox input, announced by screen readers.
+   * Falls back to the placeholder text (`'Search…'` by default), since a
+   * placeholder alone is not a reliable accessible name.
+   */
+  label?: string;
+
   /**
    * Whether to auto-focus the input when mounted.
    * @default true
@@ -149,6 +156,7 @@ export function CommandPaletteInput({
   value: controlledValue,
   onValueChange,
   placeholder: placeholderFromProps,
+  label,
   hasAutoFocus = true,
   endContent,
   onChange,
@@ -215,6 +223,9 @@ export function CommandPaletteInput({
             ? ctx.getItemId(ctx.highlightedIndex)
             : undefined
         }
+        // A placeholder alone is not a reliable accessible name; give the
+        // combobox an explicit one (consumer aria-label via rest props wins).
+        aria-label={label ?? placeholder}
         placeholder={placeholder}
         value={value}
         data-autofocus={effectiveAutoFocus || undefined}

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -43,7 +43,7 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left' as const,
+    textAlign: 'start' as const,
     outline: 'none',
     userSelect: 'none',
   },

package/src/ContextMenu/ContextMenu.test.tsx

@@ -611,3 +611,238 @@ describe('ContextMenu selectable items', () => {
     expect(onToggle).toHaveBeenCalledWith(true);
   });
 });
+
+describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)', () => {
+  it('arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused menuitemradio with Enter and a menuitemcheckbox with Space', () => {
+    const onSelect = vi.fn();
+    const onToggle = vi.fn();
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div
+              role="menuitemradio"
+              tabIndex={-1}
+              aria-checked="false"
+              onClick={onSelect}>
+              Newest
+            </div>
+            <div
+              role="menuitemcheckbox"
+              tabIndex={-1}
+              aria-checked="false"
+              onClick={onToggle}>
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'Enter'});
+    expect(onSelect).toHaveBeenCalledTimes(1);
+
+    screen
+      .getByRole('menuitemcheckbox', {name: 'Archived', hidden: true})
+      .focus();
+    fireEvent.keyDown(menu, {key: ' '});
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('typeahead matches a menuitemradio label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead matches a menuitemcheckbox label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'a'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead skips an aria-disabled item and matches the next enabled label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Nightly
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    // Anchor the search on 'Cut' so typeahead scans forward and meets the
+    // disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.
+    // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the
+    // menus never pass useTypeahead's `isDisabled` option, so that clause is
+    // the only thing keeping disabled rows out of the typeahead list. An
+    // arrow-key test cannot cover it — useListFocus re-filters disabled items
+    // independently, so arrow navigation is guarded twice over.
+    // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so
+    // the selector clause is the sole reason focus skips it.
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-disabled="true">
+              Archived
+            </div>
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Oldest
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('renders a submenu from a nested items array and keyboard-reaches an item after it', () => {
+    // Same inline-flyout scoping the DropdownMenu fix covers: the submenu's
+    // items must not pollute the ContextMenu's roving order, and an item after
+    // the submenu row must stay keyboard-reachable.
+    const onDelete = vi.fn();
+    render(
+      <ContextMenu
+        items={[
+          {label: 'Cut', onClick: () => {}},
+          {
+            label: 'Move to',
+            items: [
+              {label: 'Folder A', onClick: () => {}},
+              {label: 'Folder B', onClick: () => {}},
+            ],
+          },
+          {type: 'divider'},
+          {label: 'Delete', onClick: onDelete},
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    // Two role="menu" exist (the context menu + the inline submenu flyout);
+    // the context menu is the first in DOM order.
+    const menu = screen.getAllByRole('menu', {hidden: true})[0];
+    // The submenu trigger renders as a menuitem with aria-haspopup.
+    const submenuTrigger = screen.getByRole('menuitem', {
+      name: /Move to/,
+      hidden: true,
+    });
+    expect(submenuTrigger).toHaveAttribute('aria-haspopup', 'menu');
+    // Cut → Move to → Delete, one step per press (submenu items not swept in).
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(submenuTrigger).toHaveFocus();
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveFocus();
+  });
+});

package/src/ContextMenu/ContextMenu.tsx

@@ -49,6 +49,7 @@ import {
 import {
   MENU_ITEM_ROLES,
   MENU_ITEM_SELECTOR,
+  MENU_BOUNDARY_SELECTOR,
 } from '../DropdownMenu/menuItemRoles';
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
@@ -268,22 +269,18 @@ export function ContextMenu({
     handleKeyDown: listNavKeyDown,
     focusFirst,
     focusItem,
+    ownsEvent,
+    getItems: getMenuItems,
   } = useListFocus<HTMLDivElement>({
     itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
     wrap: false,
     onEscape: closeMenu,
   });
 
-  // First-character typeahead over the enabled menu items (menus-11).
-  const getMenuItems = useCallback(
-    (): HTMLElement[] =>
-      listRef.current
-        ? Array.from(
-            listRef.current.querySelectorAll<HTMLElement>(MENU_ITEM_SELECTOR),
-          )
-        : [],
-    [listRef],
-  );
+  // First-character typeahead over the enabled menu items (menus-11). Reuses
+  // the hook's scoped item collection so an inline submenu flyout's items
+  // aren't swept in.
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -340,6 +337,11 @@ export function ContextMenu({
 
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // A submenu flyout renders inline inside this menu; its key events bubble
+      // up here. Let that level own them — only handle events from this level.
+      if (!ownsEvent(e)) {
+        return;
+      }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();
         const focused = document.activeElement as HTMLElement | null;
@@ -357,7 +359,7 @@ export function ContextMenu({
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, typeahead],
+    [listNavKeyDown, typeahead, ownsEvent],
   );
 
   // Place the zero-size cursor anchor at a point in the trigger's local