@spaced-out/ui-design-system 0.6.36 → 0.6.37-beta.0

package/lib/components/Menu/Menu.js

@@ -3,19 +3,28 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.Menu = void 0;
+exports.getInitialActiveOptionKey = exports.getFlatOptions = exports.Menu = void 0;
 var React = _interopRequireWildcard(require("react"));
 var _reactWindow = require("react-window");
+var _hooks = require("../../hooks");
 var _classify = require("../../utils/classify");
 var _menu = require("../../utils/menu");
+var _mergeRefs = require("../../utils/merge-refs");
 var _qa = require("../../utils/qa");
 var _MenuOptionButton = require("./MenuOptionButton");
+var _menuOptionId = require("./menuOptionId");
+var _useMenuKeyboardNavigation = require("./useMenuKeyboardNavigation");
 var _SearchInput = require("../SearchInput");
 var _Text = require("../Text");
 var _MenuModule = _interopRequireDefault(require("./Menu.module.css"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/**
+ * Either react-window list Menu may render. Both expose the `scrollToItem`
+ * used to keep the keyboard's active option mounted.
+ */
+
 // Render first available option set
 
 const menuSizeMedium = 276,
@@ -25,49 +34,369 @@ const buttonSizeMedium = 40,
 const searchInputSizeMedium = 42,
   searchInputSizeSmall = 34;
 const cardPadding = 8;
+// default group title row height when virtualizing groupTitleOptions
 const groupTitleSize = 32;
 const resultTextSize = 41;
 const headerFooterSize = 58;
-const getMenuChromeHeight = _ref => {
+/**
+ * Live region announcing the filtered result count. Rendered as a SIBLING of
+ * the listbox (not inside it) so the listbox owns only option children.
+ * `role="status"` already implies `aria-live="polite"`.
+ */
+const ResultStatus = _ref => {
+  let {
+    enableA11y,
+    text,
+    testId
+  } = _ref;
+  return enableA11y ? /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    role: "status",
+    className: _MenuModule.default.filterOptionsResultText,
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.FormLabelSmall, {
+      color: "tertiary",
+      testId: (0, _qa.generateTestId)({
+        base: testId,
+        slot: 'result-text'
+      }),
+      children: text
+    })
+  }) :
+  /*#__PURE__*/
+  // No live region without the opt-in: the count is the same label element it
+  // has always been, carrying the class itself rather than a wrapper.
+  (0, _jsxRuntime.jsx)(_Text.FormLabelSmall, {
+    className: _MenuModule.default.filterOptionsResultText,
+    color: "tertiary",
+    testId: (0, _qa.generateTestId)({
+      base: testId,
+      slot: 'result-text'
+    }),
+    children: text
+  });
+};
+/**
+ * role="listbox" around the option children, and — for every shape but a
+ * virtualized one — the element that scrolls them (`.optionsListboxScroll`).
+ * Under virtualization react-window owns the scroll box and carries the role
+ * instead (ListboxOuter), so this falls back to `display: contents` and leaves
+ * the card's flex layout untouched.
+ *
+ * Keeping the role on the element that scrolls is what lets it hold a tab stop
+ * when the menu drives its own filter field, and what earns the scroll area
+ * axe's combobox-popup exemption when a trigger drives it.
+ */
+const OptionsListbox = _ref2 => {
+  let {
+    enableA11y,
+    menuId,
+    ariaLabelledBy,
+    ariaLabel,
+    optionsVariant,
+    scrolls,
+    tabIndex,
+    activeDescendantId,
+    children
+  } = _ref2;
+  return !enableA11y ?
+  /*#__PURE__*/
+  // No opt-in: no element. The options sit directly in the card and the card
+  // scrolls them, exactly as before.
+  (0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
+    children: children
+  }) : /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    role: "listbox",
+    id: menuId,
+    tabIndex: tabIndex,
+    "aria-activedescendant": activeDescendantId
+    // The element that actually scrolls, for consumers that need to scroll the
+    // menu programmatically (Dropdown's `scrollMenuToBottom`).
+    ,
+    "data-menu-scroll-container": scrolls ? '' : undefined,
+    "aria-labelledby": ariaLabelledBy
+    // `listbox` is an accessible-name-required role, and Menu is used directly
+    // (not only behind a trigger that can name it), so default the name here
+    // rather than leaving every inline consumer with an unnamed listbox.
+    // Consumers should still pass something meaningful via `ariaLabelledBy` /
+    // `ariaLabel`; this only stops the unnamed case from existing at all.
+    ,
+    "aria-label": ariaLabelledBy ? undefined : ariaLabel ?? 'Options',
+    "aria-multiselectable": optionsVariant === 'checkbox' || undefined,
+    className: (0, _classify.classify)(scrolls ? _MenuModule.default.optionsListboxScroll : _MenuModule.default.optionsListbox, _MenuModule.default.listboxFocusContainer),
+    children: children
+  });
+};
+const ListboxAttrsContext = /*#__PURE__*/React.createContext({});
+
+/**
+ * Groups a title with its options so the listbox owns only `group` and `option`
+ * children and the group name is announced. Without the opt-in it adds no
+ * element: the title and the options are siblings in the card, as before.
+ */
+const OptionGroup = _ref3 => {
+  let {
+    enableA11y,
+    labelledBy,
+    children
+  } = _ref3;
+  return enableA11y ? /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    role: "group",
+    "aria-labelledby": labelledBy,
+    className: _MenuModule.default.optionGroup,
+    children: children
+  }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
+    children: children
+  });
+};
+
+/*
+ * Wrapper element type for react-window's inner scroll container. Marks it
+ * role="presentation" so it doesn't sit as a generic node between the
+ * role="listbox" and its role="option" children (valid listbox ownership).
+ */
+const PresentationDiv = /*#__PURE__*/React.forwardRef((props, ref) => {
+  // Reads the flag from context rather than taking it as a prop: react-window
+  // renders this as a component TYPE, so a wrapper closing over the flag would
+  // be a new type every render and remount every row.
+  const {
+    enableA11y
+  } = React.useContext(ListboxAttrsContext);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    ref: ref,
+    role: enableA11y ? 'presentation' : undefined,
+    ...props
+  });
+});
+PresentationDiv.displayName = 'PresentationDiv';
+
+/*
+ * react-window owns the element that scrolls, so the listbox has to BE that
+ * element rather than a wrapper around it. A listbox wrapped around the
+ * scroller leaves a scrollable region that holds no focusable content — the
+ * options are `tabindex="-1"` under `aria-activedescendant` — which reads as an
+ * unreachable scroll area (axe `scrollable-region-focusable`) even though the
+ * combobox driving it scrolls the list with the arrow keys. Sitting on the
+ * scroller, it is the combobox's own popup, which is what that rule exempts.
+ *
+ * The attributes arrive through context because react-window renders
+ * `outerElementType` as a component TYPE: an inline wrapper closing over them
+ * would be a new type on every render and remount every row (see the row
+ * renderers below).
+ */
+
+const ListboxOuter = /*#__PURE__*/React.forwardRef((props, ref) => {
+  const {
+    enableA11y,
+    menuId,
+    ariaLabelledBy,
+    ariaLabel,
+    optionsVariant,
+    tabIndex,
+    activeDescendantId
+  } = React.useContext(ListboxAttrsContext);
+  if (!enableA11y) {
+    // react-window still needs its scroll box; it just carries nothing extra.
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      ref: ref,
+      ...props
+    });
+  }
+  const {
+    className,
+    ...rest
+  } = props;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    ref: ref,
+    role: "listbox",
+    id: menuId
+    // The element that actually scrolls, for consumers that need to scroll
+    // the menu programmatically (Dropdown's `scrollMenuToBottom`).
+    ,
+    "data-menu-scroll-container": "",
+    "aria-labelledby": ariaLabelledBy
+    // `listbox` is an accessible-name-required role — see OptionsListbox.
+    ,
+    "aria-label": ariaLabelledBy ? undefined : ariaLabel ?? 'Options',
+    "aria-multiselectable": optionsVariant === 'checkbox' || undefined,
+    tabIndex: tabIndex,
+    "aria-activedescendant": activeDescendantId,
+    ...rest,
+    className: (0, _classify.classify)(className, _MenuModule.default.listboxFocusContainer)
+  });
+});
+ListboxOuter.displayName = 'ListboxOuter';
+const getMenuChromeHeight = _ref4 => {
   let {
     size,
     allowSearch,
     showResultText,
     hasHeader,
     hasFooter
-  } = _ref;
+  } = _ref4;
   return (hasHeader ? headerFooterSize : cardPadding) + (hasFooter ? headerFooterSize : cardPadding) + (allowSearch ? size === 'medium' ? searchInputSizeMedium : searchInputSizeSmall : 0) + (allowSearch && showResultText ? resultTextSize : 0);
 };
 const makeItemHeightResolver = (itemHeight, size) => (option, index) => typeof itemHeight === 'function' ? itemHeight(option, index) : itemHeight || (size === 'medium' ? buttonSizeMedium : buttonSizeSmall);
 const makeGroupTitleHeightResolver = groupTitleHeight => (groupTitle, groupIndex) => typeof groupTitleHeight === 'function' ? groupTitleHeight(groupTitle, groupIndex) : groupTitleHeight || groupTitleSize;
+/**
+ * Flatten groups into the single row list a virtualized grouped menu renders.
+ * Shared with Menu itself, which needs the same row order to translate an
+ * option key into the row index `scrollToItem` expects.
+ */
+const buildGroupVirtualRows = groups => {
+  const rows = [];
+  let flatOptionIndex = 0;
+  groups.forEach((optionsGroup, groupIndex) => {
+    if (optionsGroup.groupTitle) {
+      rows.push({
+        kind: 'title',
+        node: optionsGroup.groupTitle,
+        groupIndex
+      });
+    }
+    optionsGroup.options?.forEach((option, optionIndex) => {
+      rows.push({
+        kind: 'option',
+        option,
+        groupIndex,
+        optionIndex,
+        flatOptionIndex
+      });
+      flatOptionIndex += 1;
+    });
+  });
+  return rows;
+};
+
 // VariableSizeList caches row offsets, so the cache must be flushed whenever
 // the rows or their heights change. `heightSignature` encodes every row's
 // key and height; when it changes, resetAfterIndex invalidates the cache in
 // place without remounting the list (a remount would drop scroll position).
-const MenuVariableSizeList = _ref2 => {
+
+function MenuVariableSizeList(_ref5) {
   let {
     heightSignature,
     height,
     itemCount,
     itemSize,
     itemKey,
+    itemData,
+    listRef,
     children
-  } = _ref2;
-  const listRef = React.useRef(null);
+  } = _ref5;
+  const innerListRef = React.useRef(null);
   React.useEffect(() => {
-    listRef.current?.resetAfterIndex(0, true);
+    innerListRef.current?.resetAfterIndex(0, true);
   }, [heightSignature]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactWindow.VariableSizeList, {
-    ref: listRef,
+    ref: (0, _mergeRefs.mergeRefs)([innerListRef, listRef]),
     height: height,
     itemSize: itemSize,
     itemCount: itemCount,
     itemKey: itemKey,
+    itemData: itemData,
     width: "initial",
+    outerElementType: ListboxOuter,
+    innerElementType: PresentationDiv,
     children: children
   });
+}
+
+/*
+ * Row renderers for the virtualized lists, and the reason they live out here.
+ *
+ * react-window renders its `children` as a COMPONENT TYPE, so an inline arrow
+ * function is a new type on every render and React unmounts and remounts every
+ * row. Under roving focus that destroys the row the user is standing on — focus
+ * lands on <body>, the menu stops receiving keys, and arrows, Home/End and
+ * type-ahead all go dead. (In the combobox and search modes focus lives on the
+ * input, which is why the remount went unnoticed there.) Keeping the renderers
+ * stable and passing the per-render values through `itemData` keeps the rows
+ * mounted across re-renders.
+ */
+
+const FlatRow = _ref6 => {
+  let {
+    index,
+    style,
+    data
+  } = _ref6;
+  const {
+    options,
+    classNames,
+    testId,
+    optionProps
+  } = data;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
+    option: options[index],
+    classNames: classNames,
+    style: style,
+    ...optionProps,
+    isLastItem: index === options.length - 1,
+    setSize: options.length,
+    posInSet: index + 1,
+    testId: (0, _qa.generateTestId)({
+      base: testId,
+      slot: 'option',
+      index: index.toString()
+    })
+  });
 };
-const RenderOption = _ref3 => {
+const GroupRow = _ref7 => {
+  let {
+    index,
+    style,
+    data
+  } = _ref7;
+  const {
+    rows,
+    optionCount,
+    enableA11y,
+    menuId,
+    classNames,
+    testId,
+    optionProps
+  } = data;
+  const row = rows[index];
+  if (row.kind === 'title') {
+    // A flattened row cannot contain the options that follow it — react-window
+    // positions every row absolutely — so the title is its own `group` naming
+    // itself from its content, rather than a presentation row. That keeps the
+    // listbox owning only option and group children (a group title passed as a
+    // custom node would otherwise expose that node as generic content inside
+    // the listbox) and keeps the group NAME in the tree, which a presentation
+    // row dropped. It is a real limitation all the same: the options sit beside
+    // the group rather than inside it, so AT reads the group as a row of its own
+    // and does not announce it as context for the options that follow.
+    const titleId = `${menuId}-group-${row.groupIndex}`;
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      style: style,
+      id: enableA11y ? titleId : undefined,
+      role: enableA11y ? 'group' : undefined,
+      "aria-labelledby": enableA11y ? titleId : undefined,
+      className: (0, _classify.classify)(_MenuModule.default.groupTitleWrapper, classNames?.groupTitle),
+      "data-testid": (0, _qa.generateTestId)({
+        base: testId,
+        slot: 'group-title',
+        index: row.groupIndex.toString()
+      }),
+      children: row.node
+    });
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
+    option: row.option,
+    classNames: classNames,
+    style: style,
+    ...optionProps,
+    isLastItem: index === rows.length - 1,
+    setSize: optionCount,
+    posInSet: row.flatOptionIndex + 1,
+    testId: (0, _qa.generateTestId)({
+      base: testId,
+      slot: 'option',
+      index: `${row.groupIndex}-${row.optionIndex}`
+    })
+  });
+};
+const RenderOption = _ref8 => {
   let {
     options,
     composeOptions,
@@ -76,17 +405,25 @@ const RenderOption = _ref3 => {
     searchText = '',
     showResultText = true,
     testId,
+    listRef,
     staticLabels = {
       RESULT: 'result',
       RESULTS: 'results',
       SEARCH_PLACEHOLDER: 'Search...'
     },
     ...restProps
-  } = _ref3;
+  } = _ref8;
   const {
     allowSearch,
     size,
-    virtualization
+    enableA11y,
+    menuId,
+    ariaLabelledBy,
+    ariaLabel,
+    optionsVariant,
+    virtualization,
+    externalKeyboardNav,
+    activeOptionKey
   } = restProps;
   const {
     enable: isVirtualizationEnabled = false,
@@ -99,135 +436,151 @@ const RenderOption = _ref3 => {
   const listHeight = menuHeight || (size === 'medium' ? menuSizeMedium : menuSizeSmall);
   const resolveItemHeight = makeItemHeightResolver(itemHeight, size);
   const resolveGroupTitleHeight = makeGroupTitleHeightResolver(groupTitleHeight);
+
+  /*
+   * When the menu owns its filter field and the list is virtualized, the
+   * scrolling list is a standalone listbox, and APG makes that focusable with
+   * the active option reported through `aria-activedescendant` — the field and
+   * the list each carry it, so whichever holds focus reports the same option. It
+   * also stops the virtualized scroll area reading as unreachable: the options
+   * are `tabindex="-1"`, so without a tab stop of its own the region has no
+   * focusable content at all (axe `scrollable-region-focusable`).
+   *
+   * Only the virtualized scroller can take that tab stop; the non-virtualized
+   * listbox is a `display: contents` wrapper with no box at all, and such an
+   * element is skipped by sequential focus navigation (see OptionsListbox).
+   * Behind a
+   * combobox trigger none of this applies — the trigger is the single tab stop
+   * and owns `aria-activedescendant`, and axe exempts a combobox's own popup —
+   * and a roving menu needs no tab stop here either, since its options are real
+   * focusable buttons.
+   */
+  const listboxIsFocusable = Boolean(enableA11y && allowSearch && !externalKeyboardNav);
+  const listboxAttrs = {
+    enableA11y,
+    menuId,
+    ariaLabelledBy,
+    ariaLabel,
+    optionsVariant,
+    // Under virtualization react-window's outer box scrolls and carries the
+    // role; every other shape scrolls on the listbox itself.
+    scrolls: !isVirtualizationEnabled,
+    tabIndex: listboxIsFocusable ? 0 : undefined,
+    activeDescendantId: listboxIsFocusable && activeOptionKey && menuId ? (0, _menuOptionId.menuOptionId)(menuId, activeOptionKey) : undefined
+  };
   if (options && Array.isArray(options) && options.length) {
     const optionsFiltered = !allowSearch ? options : (0, _menu.getFilteredOptionsFromSearchText)(options, searchText);
     const finalResultText = !allowSearch ? '' : (0, _menu.getFilteredOptionsResultText)(optionsFiltered, staticLabels);
-    const renderFlatRow = _ref4 => {
-      let {
-        index: idx,
-        style
-      } = _ref4;
-      const buttonOption = optionsFiltered[idx];
-      return /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
-        option: buttonOption,
-        classNames: classNames,
-        style: style,
-        ...restProps,
-        isLastItem: idx === optionsFiltered.length - 1,
-        testId: (0, _qa.generateTestId)({
-          base: testId,
-          slot: 'option',
-          index: idx.toString()
-        })
-      });
+    const flatRowData = {
+      options: optionsFiltered,
+      classNames,
+      testId,
+      optionProps: restProps
     };
-    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-      children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.FormLabelSmall, {
-        className: _MenuModule.default.filterOptionsResultText,
-        color: "tertiary",
-        testId: (0, _qa.generateTestId)({
-          base: testId,
-          slot: 'result-text'
-        }),
-        children: finalResultText
-      }), virtualization && isVirtualizationEnabled ? typeof itemHeight === 'function' ? /*#__PURE__*/(0, _jsxRuntime.jsx)(MenuVariableSizeList, {
-        heightSignature: optionsFiltered.map((option, idx) => `${option.key}:${resolveItemHeight(option, idx)}`).join('|'),
-        height: listHeight,
-        itemSize: idx => resolveItemHeight(optionsFiltered[idx], idx),
-        itemCount: optionsFiltered.length,
-        itemKey: idx => optionsFiltered[idx].key,
-        children: renderFlatRow
-      }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactWindow.FixedSizeList, {
-        height: listHeight,
-        itemSize: itemHeight || (size === 'medium' ? buttonSizeMedium : buttonSizeSmall),
-        itemCount: optionsFiltered.length,
-        itemKey: idx => optionsFiltered[idx].key,
-        width: "initial",
-        children: renderFlatRow
-      }) : optionsFiltered.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
-        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
-          option: option,
-          classNames: classNames,
-          ...restProps,
-          isLastItem: idx === optionsFiltered.length - 1,
-          testId: (0, _qa.generateTestId)({
-            base: testId,
-            slot: 'option',
-            index: idx.toString()
+    if (isVirtualizationEnabled) {
+      return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+        children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(ResultStatus, {
+          enableA11y: enableA11y,
+          text: finalResultText,
+          testId: testId
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(ListboxAttrsContext.Provider, {
+          value: listboxAttrs,
+          children: typeof itemHeight === 'function' ? /*#__PURE__*/(0, _jsxRuntime.jsx)(MenuVariableSizeList, {
+            listRef: listRef,
+            heightSignature: optionsFiltered.map((option, idx) => `${option.key}:${resolveItemHeight(option, idx)}`).join('|'),
+            height: listHeight,
+            itemSize: idx => resolveItemHeight(optionsFiltered[idx], idx),
+            itemCount: optionsFiltered.length,
+            itemKey: idx => optionsFiltered[idx].key,
+            itemData: flatRowData,
+            children: FlatRow
+          }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactWindow.FixedSizeList, {
+            ref: listRef,
+            height: listHeight,
+            itemSize: itemHeight || (size === 'medium' ? buttonSizeMedium : buttonSizeSmall),
+            itemCount: optionsFiltered.length,
+            itemKey: idx => optionsFiltered[idx].key,
+            itemData: flatRowData,
+            width: "initial",
+            outerElementType: ListboxOuter,
+            innerElementType: PresentationDiv,
+            children: FlatRow
           })
-        })
-      }, option.key))]
-    });
-  }
-  if (composeOptions && Array.isArray(composeOptions) && composeOptions.length) {
-    const optionsFiltered = !allowSearch ? composeOptions : (0, _menu.getFilteredComposeOptionsFromSearchText)(composeOptions, searchText);
-    const finalResultText = !allowSearch ? '' : (0, _menu.getFilteredComposeOptionsResultText)(optionsFiltered, staticLabels);
+        })]
+      });
+    }
     return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-      children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.FormLabelSmall, {
-        className: _MenuModule.default.filterOptionsResultText,
-        color: "tertiary",
-        testId: (0, _qa.generateTestId)({
-          base: testId,
-          slot: 'result-text'
-        }),
-        children: finalResultText
-      }), optionsFiltered.map((composeMenuOptions, index) =>
-      /*#__PURE__*/
-      // eslint-disable-next-line react/no-array-index-key
-      (0, _jsxRuntime.jsx)("span", {
-        className: _MenuModule.default.menuDivider,
-        children: composeMenuOptions.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
+      children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(ResultStatus, {
+        enableA11y: enableA11y,
+        text: finalResultText,
+        testId: testId
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(OptionsListbox, {
+        ...listboxAttrs,
+        children: optionsFiltered.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
           children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
             option: option,
             classNames: classNames,
             ...restProps,
-            isLastItem: index === optionsFiltered.length - 1 && idx === composeMenuOptions.length - 1,
+            isLastItem: idx === optionsFiltered.length - 1,
             testId: (0, _qa.generateTestId)({
               base: testId,
               slot: 'option',
-              index: `${index}-${idx}`
+              index: idx.toString()
             })
           })
         }, option.key))
-      }, index))]
+      })]
+    });
+  }
+  if (composeOptions && Array.isArray(composeOptions) && composeOptions.length) {
+    const optionsFiltered = !allowSearch ? composeOptions : (0, _menu.getFilteredComposeOptionsFromSearchText)(composeOptions, searchText);
+    const finalResultText = !allowSearch ? '' : (0, _menu.getFilteredComposeOptionsResultText)(optionsFiltered, staticLabels);
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+      children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(ResultStatus, {
+        enableA11y: enableA11y,
+        text: finalResultText,
+        testId: testId
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(OptionsListbox, {
+        ...listboxAttrs,
+        children: optionsFiltered.map((composeMenuOptions, index) => /*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+          role: enableA11y ? 'presentation' : undefined,
+          className: _MenuModule.default.menuDivider,
+          children: composeMenuOptions.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
+            children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
+              option: option,
+              classNames: classNames,
+              ...restProps,
+              isLastItem: index === optionsFiltered.length - 1 && idx === composeMenuOptions.length - 1,
+              testId: (0, _qa.generateTestId)({
+                base: testId,
+                slot: 'option',
+                index: `${index}-${idx}`
+              })
+            })
+          }, option.key))
+        }, index))
+      })]
     });
   }
   if (groupTitleOptions && Array.isArray(groupTitleOptions) && groupTitleOptions.length) {
     const optionsFiltered = !allowSearch ? groupTitleOptions : (0, _menu.getFilteredGroupTitleOptionsFromSearchText)(groupTitleOptions, searchText);
     const finalResultText = !allowSearch ? '' : (0, _menu.getFilteredGroupTitleOptionsResultText)(optionsFiltered, staticLabels);
-    const resultText = allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.FormLabelSmall, {
-      className: _MenuModule.default.filterOptionsResultText,
-      color: "tertiary",
-      testId: (0, _qa.generateTestId)({
-        base: testId,
-        slot: 'result-text'
-      }),
-      children: finalResultText
-    });
     if (isVirtualizationEnabled) {
-      // Mixed row heights (group titles vs options) rule out FixedSizeList —
-      // flatten the groups into one row list and size each row individually.
-      const rows = [];
-      let flatOptionIndex = 0;
-      optionsFiltered.forEach((optionsGroup, groupIndex) => {
-        if (optionsGroup.groupTitle) {
-          rows.push({
-            kind: 'title',
-            node: optionsGroup.groupTitle,
-            groupIndex
-          });
-        }
-        optionsGroup.options?.forEach((option, optionIndex) => {
-          rows.push({
-            kind: 'option',
-            option,
-            groupIndex,
-            optionIndex,
-            flatOptionIndex
-          });
-          flatOptionIndex += 1;
-        });
-      });
+      // Group titles and options have different heights, which rules out
+      // FixedSizeList — flatten the groups into one row list and size each row
+      // individually.
+      //
+      // Flattening also costs the role="group" WRAPPERS the non-virtualized
+      // path renders: react-window positions every row absolutely, so a title
+      // cannot contain the options that follow it. Each title is instead its
+      // own `group` row naming itself (see GroupRow), so the listbox still owns
+      // only option/group children and the group name stays in the tree — but
+      // the options sit beside that group rather than inside it, so AT will not
+      // announce the group as context while arrowing through them. Every option
+      // carries aria-setsize / aria-posinset so its place in the whole list is
+      // still reported rather than its place in the mounted window.
+      const rows = buildGroupVirtualRows(optionsFiltered);
+      const optionCount = rows.filter(row => row.kind === 'option').length;
       const rowHeight = idx => {
         const row = rows[idx];
         return row.kind === 'title' ? resolveGroupTitleHeight(row.node, row.groupIndex) : resolveItemHeight(row.option, row.flatOptionIndex);
@@ -236,78 +589,129 @@ const RenderOption = _ref3 => {
         const row = rows[idx];
         return row.kind === 'title' ? `group-title-${row.groupIndex}` : row.option.key;
       };
+      const groupRowData = {
+        rows,
+        optionCount,
+        enableA11y,
+        menuId,
+        classNames,
+        testId,
+        optionProps: restProps
+      };
       return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-        children: [resultText, /*#__PURE__*/(0, _jsxRuntime.jsx)(MenuVariableSizeList, {
-          heightSignature: rows.map((_row, idx) => `${rowKey(idx)}:${rowHeight(idx)}`).join('|'),
-          height: listHeight,
-          itemSize: rowHeight,
-          itemCount: rows.length,
-          itemKey: rowKey,
-          children: _ref5 => {
-            let {
-              index: idx,
-              style
-            } = _ref5;
-            const row = rows[idx];
-            if (row.kind === 'title') {
-              return /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
-                style: style,
-                className: (0, _classify.classify)(_MenuModule.default.groupTitleWrapper, classNames?.groupTitle),
-                "data-testid": (0, _qa.generateTestId)({
-                  base: testId,
-                  slot: 'group-title',
-                  index: row.groupIndex.toString()
-                }),
-                children: row.node
-              });
-            }
-            return /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
-              option: row.option,
-              classNames: classNames,
-              style: style,
-              ...restProps,
-              isLastItem: idx === rows.length - 1,
-              testId: (0, _qa.generateTestId)({
-                base: testId,
-                slot: 'option',
-                index: `${row.groupIndex}-${row.optionIndex}`
-              })
-            });
-          }
+        children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(ResultStatus, {
+          enableA11y: enableA11y,
+          text: finalResultText,
+          testId: testId
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(ListboxAttrsContext.Provider, {
+          value: listboxAttrs,
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(MenuVariableSizeList, {
+            listRef: listRef,
+            heightSignature: rows.map((_row, idx) => `${rowKey(idx)}:${rowHeight(idx)}`).join('|'),
+            height: listHeight,
+            itemSize: rowHeight,
+            itemCount: rows.length,
+            itemKey: rowKey,
+            itemData: groupRowData,
+            children: GroupRow
+          })
         })]
       });
     }
     return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-      children: [resultText, optionsFiltered.map((optionsGroup, index) =>
-      /*#__PURE__*/
-      // eslint-disable-next-line react/no-array-index-key
-      (0, _jsxRuntime.jsxs)(React.Fragment, {
-        children: [!!optionsGroup.groupTitle && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
-          className: (0, _classify.classify)(_MenuModule.default.groupTitleWrapper, classNames?.groupTitle),
-          "data-testid": (0, _qa.generateTestId)({
-            base: testId,
-            slot: 'group-title',
-            index: index.toString()
-          }),
-          children: optionsGroup.groupTitle
-        }), optionsGroup.options?.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
-          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
-            option: option,
-            classNames: classNames,
-            ...restProps,
-            isLastItem: index === optionsFiltered.length - 1 && idx === (optionsGroup.options && optionsGroup.options.length - 1),
-            testId: (0, _qa.generateTestId)({
-              base: testId,
-              slot: 'option',
-              index: `${index}-${idx}`
-            })
-          })
-        }, option.key))]
-      }, index))]
+      children: [allowSearch && showResultText && /*#__PURE__*/(0, _jsxRuntime.jsx)(ResultStatus, {
+        enableA11y: enableA11y,
+        text: finalResultText,
+        testId: testId
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(OptionsListbox, {
+        ...listboxAttrs,
+        children: optionsFiltered.map((optionsGroup, index) => {
+          // Link each group's options to its visible title via role="group"
+          // so the listbox owns only group/option children and AT announces
+          // group boundaries + names.
+          const groupTitleId = optionsGroup.groupTitle ? `${menuId}-group-${index}` : undefined;
+          return /*#__PURE__*/(0, _jsxRuntime.jsxs)(OptionGroup
+          // eslint-disable-next-line react/no-array-index-key
+          , {
+            enableA11y: enableA11y,
+            labelledBy: groupTitleId,
+            children: [!!optionsGroup.groupTitle && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+              id: enableA11y ? groupTitleId : undefined,
+              className: (0, _classify.classify)(_MenuModule.default.groupTitleWrapper, classNames?.groupTitle),
+              "data-testid": (0, _qa.generateTestId)({
+                base: testId,
+                slot: 'group-title',
+                index: index.toString()
+              }),
+              children: optionsGroup.groupTitle
+            }), optionsGroup.options?.map((option, idx) => /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
+              children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuOptionButton.MenuOptionButton, {
+                option: option,
+                classNames: classNames,
+                ...restProps,
+                isLastItem: index === optionsFiltered.length - 1 && idx === (optionsGroup.options && optionsGroup.options.length - 1),
+                testId: (0, _qa.generateTestId)({
+                  base: testId,
+                  slot: 'option',
+                  index: `${index}-${idx}`
+                })
+              })
+            }, option.key))]
+          }, index);
+        })
+      })]
     });
   }
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {});
+  // No option source yet (e.g. async options still loading). Render the listbox
+  // element anyway: the trigger advertises aria-expanded + aria-controls={menuId}
+  // for as long as the menu is mounted, and an IDREF that resolves to nothing is
+  // an invalid-value violation. An empty listbox is honest and valid.
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(OptionsListbox, {
+    enableA11y: enableA11y,
+    menuId: menuId,
+    ariaLabelledBy: ariaLabelledBy,
+    ariaLabel: ariaLabel,
+    optionsVariant: optionsVariant
+  });
+};
+
+/**
+ * Flatten the active option source (options | compose | groups) into one list.
+ * Exported because a combobox trigger drives the highlight from outside Menu
+ * and needs the same list Menu itself navigates — see `useMenuTrigger`.
+ */
+const getFlatOptions = props => {
+  const {
+    options,
+    composeOptions,
+    groupTitleOptions
+  } = props;
+  if (options && options.length) {
+    return options;
+  }
+  if (composeOptions && composeOptions.length) {
+    return composeOptions.flat();
+  }
+  if (groupTitleOptions && groupTitleOptions.length) {
+    return groupTitleOptions.flatMap(group => group.options ?? []);
+  }
+  return [];
 };
+
+/**
+ * Key of the option that should own the roving tab stop when the menu opens:
+ * the selected option if present, otherwise the first enabled option.
+ */
+exports.getFlatOptions = getFlatOptions;
+const getInitialActiveOptionKey = props => {
+  const enabled = getFlatOptions(props).filter(option => !option.disabled);
+  if (!enabled.length) {
+    return null;
+  }
+  const selectedKey = enabled.find(option => props.selectedKeys?.includes(option.key) || option.key === props.selectedOption?.key)?.key;
+  return selectedKey ?? enabled[0].key;
+};
+exports.getInitialActiveOptionKey = getInitialActiveOptionKey;
 const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
   const {
     classNames,
@@ -325,6 +729,15 @@ const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
     header,
     footer,
     staticLabels,
+    menuId,
+    menuDisabled,
+    onSelect,
+    onTabOut,
+    onReturnFocusToInput,
+    initialFocusRef,
+    externalKeyboardNav = false,
+    onActiveOptionKeyChange,
+    activeOptionKey: controlledActiveOptionKey,
     testId
   } = props;
   const [searchText, setSearchText] = React.useState('');
@@ -333,8 +746,494 @@ const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
     itemHeight,
     groupTitleHeight
   } = virtualization;
+  // Everything the accessibility work added hangs off this. Unset, the
+  // component behaves exactly as it did before any of it existed.
+  const enableA11y = props.enableA11y === true;
+
+  // A virtualized list only mounts a window of rows, so the DOM cannot be the
+  // source of truth for keyboard navigation — Home/End and friends would stop
+  // at the edge of the window. Build the real option list and hand it to the
+  // hook. The plain `options` and the grouped `groupTitleOptions` branches
+  // both virtualize (see RenderOption); compose menus never do, so they keep
+  // the DOM-driven path.
+  const isVirtualized = Boolean(virtualization.enable && (props.options?.length || props.groupTitleOptions?.length));
+  const virtualListRef = React.useRef(null);
+  // A callback ref, because which of the two react-window list types is
+  // mounted depends on the virtualization mode.
+  const setVirtualList = React.useCallback(instance => {
+    virtualListRef.current = instance;
+  }, []);
+  // Last `key:rowIndex` the virtual list was scrolled to. Guards against
+  // re-scrolling on unrelated re-renders, and is pre-set by the pointer path so
+  // hovering a partially clipped row never scrolls the list under the cursor.
+  // The row index is part of the stamp because filtering can keep the active
+  // key while moving its row — a key-only guard would leave the highlight
+  // stranded off-screen with `aria-activedescendant` pointing at nothing.
+  const lastScrolledKeyRef = React.useRef(null);
+  // Which option the pointer last highlighted. State (not a ref) because the
+  // focus ring is rendered from it and has to repaint when it changes.
+  const [pointerActiveKey, setPointerActiveKey] = React.useState(null);
+  // Exactly the rows react-window renders, in its order. Disabled options ARE
+  // included, because they still occupy a row.
+  //
+  // `scrollToItem` counts ROWS, and a virtualized grouped menu interleaves
+  // title rows among the options, so an option's row index is not its index
+  // among the options. Keep both: `options` drives navigation, `rowIndexByKey`
+  // translates the active option into the index the list expects.
+  const virtualLayout = React.useMemo(() => {
+    if (!isVirtualized) {
+      return undefined;
+    }
+    const rowIndexByKey = new Map();
+    if (props.options?.length) {
+      const options = allowSearch ? (0, _menu.getFilteredOptionsFromSearchText)(props.options, searchText) : props.options;
+      options.forEach((option, index) => {
+        rowIndexByKey.set(option.key, index);
+      });
+      return {
+        options,
+        rowIndexByKey
+      };
+    }
+    if (props.groupTitleOptions?.length) {
+      const groups = allowSearch ? (0, _menu.getFilteredGroupTitleOptionsFromSearchText)(props.groupTitleOptions, searchText) : props.groupTitleOptions;
+      const options = [];
+      buildGroupVirtualRows(groups).forEach((row, index) => {
+        if (row.kind === 'option') {
+          rowIndexByKey.set(row.option.key, index);
+          options.push(row.option);
+        }
+      });
+      return {
+        options,
+        rowIndexByKey
+      };
+    }
+    return undefined;
+  }, [isVirtualized, props.options, props.groupTitleOptions, allowSearch, searchText]);
+  const virtualRows = virtualLayout?.options;
+  // The navigable subset (arrow keys skip disabled options). Kept separate from
+  // the row layout because mixing the two would make `scrollToItem` land on
+  // the wrong row whenever the list contains a disabled option or a title.
+  const navigationOptions = React.useMemo(() => virtualRows?.filter(option => !option.disabled && !menuDisabled).map(option => {
+    // Type-ahead must match what the user can read, so prefer the
+    // resolved label when the consumer supplies a string one.
+    const resolved = props.resolveLabel?.(option);
+    return {
+      key: option.key,
+      label: typeof resolved === 'string' ? resolved : option.label ?? ''
+    };
+  }), [virtualRows, menuDisabled, props.resolveLabel]);
+  const generatedMenuId = React.useId();
+  const resolvedMenuId = menuId ?? generatedMenuId;
+  const containerRef = React.useRef(null);
+  // Last pointer position seen by an option's mousemove — used to ignore
+  // scroll-under-stationary-cursor moves so hover doesn't fight the keyboard.
+  const lastPointerRef = React.useRef(null);
+  const [internalActiveKey, setInternalActiveKey] = React.useState(() => getInitialActiveOptionKey(props));
+
+  /*
+   * The menu opens with an option already active so the keyboard has somewhere
+   * to start, but painting that highlight after a MOUSE open makes the menu
+   * look like it has a cursor the user never asked for. Suppress it until the
+   * keyboard or the pointer actually picks an option.
+   *
+   * Read imperatively, not as reactive state: what matters is how the menu was
+   * OPENED. Re-rendering when the user later switches to the mouse would undo
+   * the highlight they just navigated to with the keyboard.
+   */
+  /*
+   * Whether focus is inside the menu right now.
+   *
+   * A roving menu's highlight IS its DOM focus, so showing it while focus has
+   * moved elsewhere on the page paints a cursor in a widget the keyboard is no
+   * longer driving. The active option is still remembered — arrowing back in
+   * resumes where it was — it just stops being drawn.
+   *
+   * The combobox modes are exempt: there the trigger input outside this DOM
+   * holds focus by design, and this highlight is the only cursor the user has.
+   */
+  const [menuHasFocus, setMenuHasFocus] = React.useState(false);
+  const [suppressInitialHighlight, setSuppressInitialHighlight] = React.useState(() => (0, _hooks.getInteractionModality)() !== 'keyboard');
+  // Primed by the trigger hooks before the popup exists; primed here too for a
+  // Menu opened by a trigger that does not use them.
+  React.useEffect(() => {
+    if (enableA11y) {
+      (0, _hooks.startInteractionModalityTracking)();
+    }
+  }, [enableA11y]);
+
+  // When an external combobox input drives navigation the active option is a
+  // controlled prop; otherwise the Menu owns it (roving / internal search).
+  const activeOptionKey = externalKeyboardNav ? controlledActiveOptionKey ?? null : internalActiveKey;
+  const setActiveOptionKey = externalKeyboardNav ? onActiveOptionKeyChange ?? (() => undefined) : setInternalActiveKey;
+
+  // Once the user reaches for the keyboard the highlight is wanted, wherever
+  // they pressed. This is what covers the combobox consumers, whose key
+  // handling lives on the trigger OUTSIDE this component and so never reaches
+  // the keydown handler below.
+  //
+  // Deliberately keyed off real interaction rather than off `activeOptionKey`
+  // changing: async options arriving after a mouse open also change that key,
+  // and treating it as intent would paint the very highlight this suppresses.
+  //
+  // Popups only. An inline Menu has no trigger outside itself, so the only
+  // keyboard that should reveal its highlight is the one pressed inside it
+  // (the card's own onKeyDown below) — not typing in some unrelated field on
+  // the same page, which also flips the session-wide modality.
+  const modality = (0, _hooks.useInteractionModality)(enableA11y);
+  const isPopup = Boolean(initialFocusRef || externalKeyboardNav);
+  React.useEffect(() => {
+    if (isPopup && modality === 'keyboard') {
+      setSuppressInitialHighlight(false);
+    }
+  }, [isPopup, modality]);
+
+  // Keep the roving tab stop valid as the rendered option set changes
+  // (search filtering, async options, etc.). Skipped under external nav —
+  // the parent owns the active option there.
+  React.useLayoutEffect(() => {
+    if (!enableA11y || externalKeyboardNav) {
+      return;
+    }
+    const container = containerRef.current;
+    // Under virtualization the DOM holds only a window of rows, so validating
+    // against it would discard a perfectly good active key the moment it
+    // scrolled out and snap the highlight back to the top of the window.
+    const keys = navigationOptions ? navigationOptions.map(option => option.key) : container ? Array.from(container.querySelectorAll('[data-menu-option-key]')).filter(el => el.getAttribute('aria-disabled') !== 'true' && !el.disabled).map(el => el.getAttribute('data-menu-option-key')).filter(key => key !== null) : [];
+    setInternalActiveKey(prev => {
+      if (!keys.length) {
+        return null;
+      }
+      if (prev && keys.includes(prev)) {
+        return prev;
+      }
+      const selectedKey = keys.find(key => props.selectedKeys?.includes(key) || key === props.selectedOption?.key);
+      return selectedKey ?? keys[0];
+    });
+  }, [enableA11y, searchText, props.options, props.composeOptions, props.groupTitleOptions, props.selectedKeys, props.selectedOption, navigationOptions]);
+
+  // Keep the active option MOUNTED in a virtualized list: the row the keyboard
+  // just moved to may be outside the render window, which would leave roving
+  // focus with no target and aria-activedescendant pointing at nothing.
+  React.useLayoutEffect(() => {
+    if (!enableA11y || !isVirtualized || !activeOptionKey || !virtualLayout) {
+      return;
+    }
+    // Only act on an actual CHANGE of active option. The row layout is memoized
+    // on the consumer's own array, so a parent that rebuilds it every render (e.g.
+    // Pagination's inline `menu={{options: allPages.map(...)}}`) would
+    // otherwise re-run this on every render and yank the list back to the
+    // active row, throwing away wherever the user had scrolled to.
+    // Index within the RENDERED rows — scrollToItem counts disabled options
+    // and group titles too. A key that is not in the layout yet (async options
+    // still arriving) is left unstamped, so it is scrolled to once it exists.
+    const index = virtualLayout.rowIndexByKey.get(activeOptionKey);
+    if (index === undefined) {
+      return;
+    }
+    const stamp = `${activeOptionKey}:${index}`;
+    if (lastScrolledKeyRef.current === stamp) {
+      return;
+    }
+    lastScrolledKeyRef.current = stamp;
+    // Whether the menu owns focus RIGHT NOW, captured before the scroll can
+    // unmount the row holding it. Focus is only ever reclaimed below when the
+    // answer is yes: on the very first run of this effect (the menu mounting
+    // with an option already seeded) focus is still wherever the user left it,
+    // and an inline Menu must not pull it out of the page.
+    const hadFocusInside = Boolean(typeof document !== 'undefined' && containerRef.current?.contains(document.activeElement));
+    virtualListRef.current?.scrollToItem(index, 'smart');
+    // react-window positions using the `height` it was handed, which under this
+    // flex layout can be taller than the scroll box actually ends up, leaving
+    // the last rows a few pixels clipped. Once the row has mounted, nudge it
+    // with the real box so the highlight is never cut off, and — for roving
+    // focus — put real focus on it, since the row the open-time effect wanted
+    // may not have existed until this scroll rendered it.
+    const frame = requestAnimationFrame(() => {
+      const row = containerRef.current?.querySelector(`[data-menu-option-key="${CSS.escape(activeOptionKey)}"]`);
+      if (!row) {
+        return;
+      }
+      row.scrollIntoView({
+        block: 'nearest'
+      });
+      // Reclaim focus only if the scroll actually cost us it (the previously
+      // focused row was unmounted, dropping focus to <body>). Never steal it
+      // from the search field, the chrome, a combobox trigger outside — or
+      // from whatever owned it before this menu existed.
+      if (hadFocusInside && !allowSearch && !externalKeyboardNav && typeof document !== 'undefined' && (document.activeElement === document.body || document.activeElement === null)) {
+        row.focus({
+          preventScroll: true
+        });
+      }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [enableA11y, activeOptionKey, isVirtualized, virtualLayout, allowSearch, externalKeyboardNav]);
+
+  // A virtualized row can be unmounted underneath the focus it holds: the user
+  // scrolls the options with the wheel, the scrollbar, or a key the browser
+  // scrolls with, and react-window drops the row they were standing on. Focus
+  // then falls to <body>, which takes the menu's key handling with it — and
+  // because the roving tab stop lives on the active row, that row is no longer
+  // rendered either, so there is nothing left to Tab back to. The options are
+  // unreachable by keyboard until the user clicks one.
+  //
+  // The removal cannot be caught on blur: React's onBlur needs the event to
+  // bubble up through this container, and the row is already detached by then.
+  // The scroll is the live signal. Park focus on the card — always mounted,
+  // and it carries the key handler — and the next arrow key puts real focus
+  // back on a row, resuming from `activeOptionKey`.
+  React.useLayoutEffect(() => {
+    const container = containerRef.current;
+    if (!enableA11y || !isVirtualized || allowSearch || externalKeyboardNav || !container) {
+      return;
+    }
+    let frame = 0;
+    // The row is not removed during the scroll event — the commit that drops it
+    // lands a frame or two later, and focus only falls to <body> then. So the
+    // check runs for a few frames after a scroll rather than once.
+    const CHECK_FRAMES = 4;
+    const check = remaining => {
+      frame = 0;
+      if (typeof document === 'undefined' || !container.isConnected) {
+        return;
+      }
+      if (document.activeElement === document.body || document.activeElement === null) {
+        container.focus({
+          preventScroll: true
+        });
+        return;
+      }
+      if (remaining > 0) {
+        frame = requestAnimationFrame(() => check(remaining - 1));
+      }
+    };
+    const onScroll = () => {
+      // Sample ownership NOW, while the doomed row is still mounted: only a
+      // scroll that starts with focus inside the menu can be the one that
+      // unmounts the focused row. Someone who clicked the page away from the
+      // menu and then scrolled it with the wheel is not asking for focus back.
+      if (typeof document === 'undefined' || !container.contains(document.activeElement)) {
+        return;
+      }
+      if (!frame) {
+        frame = requestAnimationFrame(() => check(CHECK_FRAMES));
+      }
+    };
+    // `scroll` does not bubble, so listen for it in the capture phase rather
+    // than reaching into react-window's own scroll container.
+    container.addEventListener('scroll', onScroll, true);
+    return () => {
+      container.removeEventListener('scroll', onScroll, true);
+      if (frame) {
+        cancelAnimationFrame(frame);
+      }
+    };
+  }, [enableA11y, isVirtualized, allowSearch, externalKeyboardNav]);
+
+  // Move focus into the menu when it opens — the search input (so typing
+  // works) or the active option (so arrow-key roving works) — never a
+  // focusable header that happens to come first in the DOM. This is what a
+  // trigger relies on instead of wrapping the menu in FloatingFocusManager.
+  // Gated on `initialFocusRef` so only popup consumers (the dropdown family)
+  // auto-focus on open; an inline Menu without that prop never steals focus.
+  React.useLayoutEffect(() => {
+    if (!enableA11y || !initialFocusRef || externalKeyboardNav) {
+      return;
+    }
+    const container = containerRef.current;
+    // A virtualized list mounts only a window of rows, so the active option may
+    // not exist yet on open. Focusing whatever IS mounted would be undone a
+    // moment later when the scroll effect renders the real row and unmounts the
+    // one we focused, dropping focus to <body> and leaving the popup with no
+    // keyboard owner. Scroll first and let the scroll effect place focus.
+    if (isVirtualized && !allowSearch && activeOptionKey && virtualLayout) {
+      const index = virtualLayout.rowIndexByKey.get(activeOptionKey);
+      if (index !== undefined) {
+        // Park focus on the card so it is inside the popup straight away (Tab
+        // and Escape behave, nothing falls to <body>), scroll the real row in,
+        // then hand focus over once it has mounted.
+        initialFocusRef.current = container;
+        container?.focus();
+        lastScrolledKeyRef.current = `${activeOptionKey}:${index}`;
+        virtualListRef.current?.scrollToItem(index, 'smart');
+        const openFrame = requestAnimationFrame(() => {
+          const row = containerRef.current?.querySelector(`[data-menu-option-key="${CSS.escape(activeOptionKey)}"]`);
+          if (!row) {
+            return;
+          }
+          initialFocusRef.current = row;
+          row.focus({
+            preventScroll: true
+          });
+          row.scrollIntoView({
+            block: 'nearest'
+          });
+        });
+        return () => cancelAnimationFrame(openFrame);
+      }
+    }
+    const target = container ? allowSearch ? container.querySelector('input[data-menu-search]') :
+    // The roving tab stop, unless `menuDisabled` has rendered it disabled —
+    // focusing a disabled <button> is a no-op that would leave focus on
+    // the trigger with the popup open and keyboard-dead.
+    container.querySelector('[data-menu-option-key][tabindex="0"]:not(:disabled):not([aria-disabled="true"])') ??
+    // Fallback must skip disabled options — focusing a disabled <button>
+    // is a no-op that would drop focus to <body> (all-disabled menus).
+    container.querySelector('[data-menu-option-key]:not([aria-disabled="true"]):not(:disabled)') : null;
+    // When no focusable option exists (every option disabled / menuDisabled),
+    // focus the menu container itself (it has tabIndex={-1}) so focus still
+    // enters the popup instead of falling to <body>.
+    const focusTarget = target ?? container;
+    initialFocusRef.current = focusTarget;
+    focusTarget?.focus();
+    // Only needs to resolve once when the menu mounts (opens).
+  }, []);
+  const selectByKey = key => {
+    const option = getFlatOptions(props).find(opt => opt.key === key);
+    if (option) {
+      onSelect?.(option, null);
+    }
+  };
+  const {
+    onKeyDown
+  } = (0, _useMenuKeyboardNavigation.useMenuKeyboardNavigation)({
+    containerRef,
+    enabled: enableA11y && !menuDisabled && !externalKeyboardNav,
+    mode: allowSearch ? 'search' : 'roving',
+    activeOptionKey,
+    onSelectKey: selectByKey,
+    setActiveOptionKey,
+    onTabOut,
+    onReturnFocusToInput,
+    options: navigationOptions
+  });
+  const activeDescendantId = allowSearch && activeOptionKey ? (0, _menuOptionId.menuOptionId)(resolvedMenuId, activeOptionKey) : undefined;
+
+  // Hovering an option makes it the single active highlight, so pointer and
+  // keyboard never diverge. In roving mode focus follows the pointer too, so
+  // arrow-key navigation resumes from wherever the mouse last was and the
+  // previously focused option's highlight clears. Search / external-combobox
+  // modes keep DOM focus on the input and only move the active descendant.
+  const handleOptionPointerActivate = (key, el, clientX, clientY) => {
+    // Ignore moves with no real pointer delta — e.g. the list scrolling under
+    // a stationary cursor during keyboard nav fires mousemove with unchanged
+    // viewport coordinates. Acting on those would steal focus from the
+    // keyboard / fight the arrow keys.
+    const last = lastPointerRef.current;
+    if (last && last.x === clientX && last.y === clientY) {
+      return;
+    }
+    lastPointerRef.current = {
+      x: clientX,
+      y: clientY
+    };
+    // The row is already under the cursor, so it must not be scrolled to.
+    // Claiming it here makes the virtual-scroll effect treat it as handled —
+    // otherwise hovering a partially clipped edge row would nudge the list
+    // under a stationary mouse and shift every row out from under it.
+    lastScrolledKeyRef.current = `${key}:${virtualLayout?.rowIndexByKey.get(key) ?? '?'}`;
+    setPointerActiveKey(key);
+    // Hovering an option IS the user picking it out, so show the highlight
+    // even though the menu was opened by mouse.
+    setSuppressInitialHighlight(false);
+    setActiveOptionKey(key);
+    // Roving mode only: move real focus so the keyboard cursor / tab stop
+    // follows the pointer. Search & external-combobox keep focus on the input.
+    // Gate on focus ALREADY being inside the menu so an inline menu (or a
+    // consumer like TokenListInput, where the user types in an external input
+    // and the menu is just a mouse target) is never robbed of its focus by a
+    // stray hover.
+    if (!allowSearch && !externalKeyboardNav) {
+      const container = containerRef.current;
+      if (container && typeof document !== 'undefined' && container.contains(document.activeElement)) {
+        el.focus({
+          preventScroll: true
+        });
+      }
+    }
+  };
+
+  // Close when focus leaves the menu entirely (e.g. Tab past the footer or
+  // Shift+Tab before the header). Internal moves between the search input,
+  // options, header and footer keep focus inside, so they don't close.
+  const handleMenuBlur = event => {
+    const next = event.relatedTarget;
+    if (next && event.currentTarget.contains(next)) {
+      return;
+    }
+    // Focus fell out of the menu without landing anywhere — a click on
+    // non-focusable page content, or a virtualized row being unmounted under
+    // it. The highlight stops being drawn either way; if it was the row
+    // churning, the reclaim below focuses the card again and brings it back.
+    if (!next) {
+      setMenuHasFocus(false);
+      return;
+    }
+    // Focus moving into ANOTHER floating-ui portal is a nested popup opening
+    // from this menu's own chrome (a Dropdown in the footer, say), not the user
+    // leaving — ClickAway tolerates the click for the same reason, so the blur
+    // has to as well or the parent closes under the child.
+    const ownPortal = event.currentTarget.closest('[data-floating-ui-portal]');
+    const nextPortal = next.closest?.('[data-floating-ui-portal]') ?? null;
+    if (nextPortal && nextPortal !== ownPortal) {
+      return;
+    }
+    // Focus has genuinely gone somewhere else on the page. Stop drawing the
+    // highlight before deciding whether this is a tab-out: moving to the
+    // trigger is not one, but it is still focus leaving the menu.
+    setMenuHasFocus(false);
+    // Focus landing on the trigger that controls this menu is never a tab-out.
+    // For combobox menus it is a deliberate return to the input (Shift+Tab off
+    // a footer control). For roving menus it is the user pressing the trigger
+    // to dismiss — and mousedown moves focus BEFORE the click, so closing here
+    // would let the trigger's own toggle re-open the menu a moment later.
+    // Leaving the menu by keyboard is handled explicitly in handleTab, and
+    // clicking elsewhere is handled by ClickAway, so neither needs this path.
+    if (next.getAttribute?.('aria-controls') === resolvedMenuId) {
+      return;
+    }
+    onTabOut?.();
+  };
+
+  // The card is tabIndex={-1} so it can take focus programmatically, but that
+  // also makes it CLICK-focusable. Without this, clicking its padding, a group
+  // title, the result-count row or its scrollbar pulls focus off the combobox
+  // input (or the roving option) onto the card, leaving the menu open but
+  // keyboard-dead: the trigger's key handler can't fire and Menu's own is off
+  // under externalKeyboardNav. Suppressing the default only for non-control
+  // targets keeps focus where it was; real controls still focus normally.
+  const handleMenuMouseDown = event => {
+    const target = event.target;
+    // A press on a scrollbar reports its scroll container as the target but
+    // lands OUTSIDE that element's client box; preventing the default there
+    // would cancel the drag. Test the target itself, not just the card — under
+    // virtualization the scroll container is react-window's own wrapper, so a
+    // card-only check would leave that scrollbar unguarded.
+    if (target) {
+      const scrolls = target.scrollHeight > target.clientHeight || target.scrollWidth > target.clientWidth;
+      const rect = target.getBoundingClientRect();
+      if (scrolls && (event.clientX > rect.left + target.clientWidth || event.clientY > rect.top + target.clientHeight)) {
+        return;
+      }
+    }
+    if (!target?.closest('a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])')) {
+      event.preventDefault();
+    }
+  };
   const hasHeader = header ? true : false;
   const hasFooter = footer ? true : false;
+
+  // The card used to collapse via `:empty` when it rendered nothing at all.
+  // It now always contains the (possibly empty) listbox element so the
+  // trigger's aria-controls resolves, which means `:empty` can never match —
+  // so decide emptiness here instead and keep the collapsed styling.
+  // Mirror RenderOption's own branch conditions rather than using the FLATTENED
+  // option count: `groupTitleOptions: [{groupTitle: 'Recent', options: []}]`
+  // still renders a visible group title, so collapsing the card there would
+  // strip its border and padding while leaving that title on screen.
+  const isCardEmpty = !hasHeader && !hasFooter && !allowSearch && !props.options?.length && !props.composeOptions?.length && !props.groupTitleOptions?.length;
   const firstOption = options?.[0] ?? composeOptions?.[0]?.[0] ?? groupTitleOptions?.[0]?.options?.[0];
   const firstRowHeight = (groupTitleOptions?.length ? makeGroupTitleHeightResolver(groupTitleHeight)(groupTitleOptions[0].groupTitle, 0) : 0) + (firstOption ? makeItemHeightResolver(itemHeight, size)(firstOption, 0) : 0);
   const minCardHeight = getMenuChromeHeight({
@@ -346,6 +1245,24 @@ const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
   }) + firstRowHeight;
   const cardMaxHeight = menuHeight ? Math.max(menuHeight, minCardHeight) : null;
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+    // -1 so it is never in the tab order but CAN receive programmatic focus
+    // as the open-time fallback when no option is focusable (all disabled).
+    tabIndex: enableA11y ? -1 : undefined,
+    onKeyDown: enableA11y ? event => {
+      // Any key press means the keyboard is driving again, so a stale
+      // pointer highlight must stop suppressing the focus ring —
+      // otherwise arrowing back onto the row the mouse last touched
+      // would show no focus.
+      setPointerActiveKey(null);
+      // A key press means the keyboard is driving, so the opening
+      // highlight is now wanted even if the key did not move the
+      // active option (Home on the first option, say).
+      setSuppressInitialHighlight(false);
+      onKeyDown(event);
+    } : undefined,
+    onMouseDown: enableA11y ? handleMenuMouseDown : undefined,
+    onFocus: enableA11y ? () => setMenuHasFocus(true) : undefined,
+    onBlur: enableA11y ? handleMenuBlur : undefined,
     className: (0, _classify.classify)(_MenuModule.default.menuCard, {
       [_MenuModule.default.fluid]: isFluid,
       [_MenuModule.default.medium]: size === 'medium',
@@ -356,26 +1273,46 @@ const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
       [_MenuModule.default.smallWithHeader]: size === 'small' && hasHeader && !hasFooter,
       [_MenuModule.default.smallWithFooter]: size === 'small' && !hasHeader && hasFooter,
       [_MenuModule.default.smallWithHeaderAndFooter]: size === 'small' && hasFooter && hasHeader,
+      // Scopes the CSS the opt-in changes — the pinned header/footer
+      // layout and the card's overflow — so nothing restyles a menu that
+      // has not opted in.
+      [_MenuModule.default.menuCardA11y]: enableA11y,
       [_MenuModule.default.menuCardTopPaddingZero]: header,
-      [_MenuModule.default.menuCardBottomPaddingZero]: footer
+      [_MenuModule.default.menuCardBottomPaddingZero]: footer,
+      // Whatever scrolls the options, the card must not scroll too —
+      // but only the opt-in moves the scroll onto the listbox, so without
+      // it the card stays the scroll box it has always been.
+      [_MenuModule.default.menuCardNoScroll]: enableA11y && !isVirtualized,
+      [_MenuModule.default.menuCardEmpty]: enableA11y && isCardEmpty
     }, classNames?.wrapper),
     style: {
       width,
       maxHeight: cardMaxHeight ? cardMaxHeight + 'px' : ''
     },
-    ref: ref,
+    ref: (0, _mergeRefs.mergeRefs)([ref, containerRef]),
     "data-testid": (0, _qa.generateTestId)({
       base: testId,
       slot: 'wrapper'
     }),
     children: [hasHeader && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
       className: (0, _classify.classify)(_MenuModule.default.menuHeader, classNames?.header),
+      "data-menu-region": enableA11y ? 'header' : undefined,
       "data-testid": (0, _qa.generateTestId)({
         base: testId,
         slot: 'header'
       }),
       children: header
-    }), allowSearch && /*#__PURE__*/(0, _jsxRuntime.jsx)(_SearchInput.SearchInput, {
+    }), allowSearch && /*#__PURE__*/(0, _jsxRuntime.jsx)(_SearchInput.SearchInput
+    // A filter field, NOT a combobox: an always-expanded combobox is
+    // meaningless, and a second combobox pointing aria-controls at the
+    // same listbox as the trigger that opened the popup has no defined
+    // mapping. `searchbox` describes what it actually is; the trigger
+    // outside the menu remains the single combobox owning the listbox.
+    , {
+      role: enableA11y ? 'searchbox' : undefined,
+      "data-menu-search": enableA11y ? 'true' : undefined,
+      "aria-controls": enableA11y ? resolvedMenuId : undefined,
+      "aria-activedescendant": enableA11y ? activeDescendantId : undefined,
       value: searchText,
       onChange: e => setSearchText(e.target.value),
       onClear: () => setSearchText(''),
@@ -385,12 +1322,40 @@ const Menu = exports.Menu = /*#__PURE__*/React.forwardRef((props, ref) => {
         base: testId,
         slot: 'search'
       })
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(RenderOption, {
+    }), enableA11y && (hasHeader || hasFooter) && isVirtualized ?
+    /*#__PURE__*/
+    // Only a virtualized list needs this wrapper: it is sized by
+    // `menuHeight` rather than by the flex box, so it needs something to
+    // sit between the pinned bars. A plain option list scrolls on the
+    // listbox itself.
+    (0, _jsxRuntime.jsx)("div", {
+      className: _MenuModule.default.optionsScroll,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(RenderOption, {
+        ...props,
+        searchText: searchText,
+        testId: testId,
+        menuId: resolvedMenuId,
+        activeOptionKey: activeOptionKey,
+        onPointerActivate: handleOptionPointerActivate,
+        pointerActiveKey: pointerActiveKey,
+        suppressInitialHighlight: suppressInitialHighlight,
+        menuHasFocus: menuHasFocus,
+        listRef: setVirtualList
+      })
+    }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(RenderOption, {
       ...props,
       searchText: searchText,
-      testId: testId
+      testId: testId,
+      menuId: resolvedMenuId,
+      activeOptionKey: activeOptionKey,
+      onPointerActivate: handleOptionPointerActivate,
+      pointerActiveKey: pointerActiveKey,
+      suppressInitialHighlight: suppressInitialHighlight,
+      menuHasFocus: menuHasFocus,
+      listRef: setVirtualList
     }), hasFooter && /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
       className: (0, _classify.classify)(_MenuModule.default.menuFooter, classNames?.footer),
+      "data-menu-region": enableA11y ? 'footer' : undefined,
       "data-testid": (0, _qa.generateTestId)({
         base: testId,
         slot: 'footer'