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

package/lib/components/Menu/Menu.module.css

@@ -9,6 +9,7 @@
 @value (
   colorBackgroundSecondary,
   colorFillSecondary,
+  colorFillPrimary,
   colorTextDisabled,
   colorTextPrimary,
   colorTextSecondary,
@@ -60,6 +61,17 @@
   z-index: elevationMenu;
 }
 
+/*
+ * The options carry their own scroll container, so the card must not scroll as
+ * well — otherwise both would show a scrollbar. `hidden` also keeps a pinned
+ * header / footer inside the border radius.
+ */
+.menuCardA11y.menuCardTopPaddingZero,
+.menuCardA11y.menuCardBottomPaddingZero,
+.menuCardNoScroll {
+  overflow: hidden;
+}
+
 .menuCardTopPaddingZero {
   padding-top: spaceNone;
 }
@@ -68,7 +80,28 @@
   padding-bottom: spaceNone;
 }
 
-.menuCard:empty {
+/*
+ * Scrolls the options only. A header / footer is a flex sibling of this element
+ * rather than something sticky inside it, so the scrollbar spans just the option
+ * list — it no longer runs the whole height of the card behind the bars — and no
+ * option can be clipped under them. `min-height: 0` is what lets a flex item
+ * actually shrink and scroll instead of growing to fit its content.
+ */
+.optionsScroll {
+  display: flex;
+  flex-flow: column;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/*
+ * Collapse a menu that renders nothing. `:empty` alone no longer suffices: the
+ * card always holds the (possibly empty) role="listbox" element so the trigger's
+ * aria-controls resolves, so Menu also sets `.menuCardEmpty` explicitly.
+ */
+.menuCard:empty,
+.menuCard.menuCardEmpty {
   padding: spaceNone;
   border: none;
 }
@@ -179,11 +212,56 @@
   color: colorTextSecondary;
 }
 
+/*
+ * These two suppress the browser's own focus ring, which a CLICK produces:
+ * clicking an option focuses it, and `:focus-visible` deliberately does not
+ * match pointer-driven focus, so without them a clicked option grows a native
+ * outline. Unscoped, because that is true whether or not a consumer opted in.
+ */
 .option:focus {
   outline: none;
   color: colorTextPrimary;
 }
 
+.option:focus-within {
+  outline: none;
+  color: colorTextPrimary;
+}
+
+.option:focus .optionTextSecondaryLabel {
+  color: colorTextSecondary;
+}
+
+/*
+ * Selected value (committed), shown as a stronger fill than the active highlight.
+ *
+ * Deliberately no left accent bar: a 2px inset box-shadow gets tapered by the
+ * option's 8px border-radius, so it renders as a small curved sliver at the edge
+ * that reads as a stray focus artefact rather than an intentional indicator. The
+ * checkbox / radio glyph carries the state in those variants, and forced-colors
+ * mode below re-expresses it as a full outline, which the radius follows cleanly.
+ */
+.option.selected {
+  background: colorFillSecondary;
+  outline: none;
+  color: colorTextPrimary;
+}
+
+/*
+ * Focus ring — KEYBOARD ONLY. A focus indicator has to mean "focus is here", so
+ * it must not appear under the mouse pointer:
+ *
+ * - `.activeRing` is set by Menu for the combobox modes (Dropdown / Typeahead),
+ *   where DOM focus stays on the input and the active option is virtual. Menu
+ *   withholds it when the highlight came from the pointer.
+ * - `:focus-visible` covers the roving menus, which move real DOM focus. It is
+ *   exactly the right selector here: arrow-key navigation calls .focus() after a
+ *   key press so the ring shows, while hover-driven .focus() follows a pointer
+ *   interaction so it does not.
+ *
+ * Declared after `.selected`, which sets no box-shadow of its own, so a selected
+ * option that also has focus shows the ring without anything to fight over.
+ */
 .option:focus-visible {
   outline: none;
   color: colorTextPrimary;
@@ -191,20 +269,57 @@
     borderWidthTertiary colorFocusSecondary;
 }
 
-.option:focus-within {
+/*
+ * The opt-in's own indicators, scoped to it so a consumer who has not opted in
+ * keeps exactly the option styling they had. `.active` is the highlight the
+ * keyboard moves; `.activeRing` is the focus ring for the combobox modes, where
+ * DOM focus stays on the input and `:focus-visible` can never match the option.
+ */
+.menuCardA11y .option.active {
   outline: none;
   color: colorTextPrimary;
-  /* box-shadow: none; */
+  background: colorBackgroundSecondary;
 }
 
-.option.selected {
-  background: colorFillSecondary;
+.menuCardA11y .option.active .optionTextSecondaryLabel {
+  color: colorTextSecondary;
+}
+
+.menuCardA11y .option.activeRing {
   outline: none;
   color: colorTextPrimary;
+  box-shadow: inset borderWidthNone borderWidthNone borderWidthNone
+    borderWidthTertiary colorFocusSecondary;
 }
 
-.option:focus .optionTextSecondaryLabel {
-  color: colorTextSecondary;
+/*
+ * Windows High Contrast / forced-colors mode drops box-shadow and flattens
+ * background, so the bar + tint indicators above vanish. Re-express the active
+ * highlight and selected state with system-color outlines (honored in HCM).
+ */
+@media (forced-colors: active) {
+  .menuCardA11y .option:hover,
+  .menuCardA11y .option.active {
+    outline: borderWidthTertiary solid Highlight;
+    outline-offset: calc(-1 * borderWidthTertiary);
+  }
+
+  .menuCardA11y .option.selected {
+    outline: borderWidthTertiary solid SelectedItem;
+    outline-offset: calc(-1 * borderWidthTertiary);
+  }
+
+  /*
+   * Keyboard focus must stay distinguishable from BOTH the hover highlight and
+   * the selected state, and Highlight / SelectedItem commonly resolve to the same
+   * system color — so change the outline STYLE rather than add a third color.
+   * Declared last so a selected option that also has focus still shows it.
+   */
+  .menuCardA11y .option.activeRing,
+  .menuCardA11y .option:focus-visible {
+    outline: borderWidthTertiary dashed Highlight;
+    outline-offset: calc(-1 * borderWidthTertiary);
+  }
 }
 
 .disabled {
@@ -244,6 +359,55 @@
   flex-flow: column;
 }
 
+/*
+ * Wraps only the option list so the listbox role contains option children
+ * exclusively (search/header/footer stay outside it). display:contents keeps
+ * the existing flex layout of .menuCard unchanged.
+ */
+.optionsListbox {
+  display: contents;
+}
+
+/*
+ * The listbox as the element that actually scrolls. Under virtualization
+ * react-window's own scroll box carries the role (see ListboxOuter); this is the
+ * same arrangement for a plain option list, and it matters beyond tidiness: the
+ * options are not focusable themselves whenever a combobox trigger drives the
+ * menu, so a
+ * scroll container that is NOT the combobox's popup reads as an unreachable
+ * scroll area (axe `scrollable-region-focusable`). Making the listbox the
+ * scroller means the region IS the popup, which that rule exempts.
+ */
+.optionsListboxScroll {
+  display: flex;
+  flex-flow: column;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/*
+ * The listbox takes a tab stop only where the menu owns its filter field, and in
+ * that shape it reports the cursor through `aria-activedescendant` — the ring is
+ * drawn on the active OPTION, which is what APG prescribes for that pattern.
+ * Leaving the browser's own ring on the container as well shows two focus
+ * indicators at once, the outer one around a box the user cannot move, which
+ * reads as a rendering fault rather than as focus. Applied to whichever element
+ * holds the role: this one, or react-window's scroll box when virtualized.
+ */
+.listboxFocusContainer:focus,
+.listboxFocusContainer:focus-visible {
+  outline: none;
+}
+
+/*
+ * role="group" wrapper around each titled option group. display:contents keeps
+ * the existing flex layout (title + options) unchanged.
+ */
+.optionGroup {
+  display: contents;
+}
+
 .groupTitleWrapper {
   composes: formLabelSmall from '../../styles/typography.module.css';
   display: flex;
@@ -260,6 +424,11 @@
   margin-left: spaceSmall;
 }
 
+/*
+ * Pinned by living OUTSIDE the options scroll container rather than by sticking
+ * inside it, so it never has the option list's scrollbar running behind it and
+ * never has an option tucked under it. `relative` positions the divider below.
+ */
 .menuHeader {
   position: sticky;
   background-color: colorBackgroundTertiary;
@@ -271,6 +440,20 @@
   max-height: size50;
 }
 
+/*
+ * With the opt-in the options carry their own scroll container, so the bars are
+ * pinned by living OUTSIDE it rather than by sticking inside it: the option
+ * list's scrollbar never runs behind them and no option is ever tucked under
+ * them. `relative` positions the divider below.
+ */
+.menuCardA11y .menuHeader,
+.menuCardA11y .menuFooter {
+  position: relative;
+  flex: 0 0 auto;
+  top: auto;
+  bottom: auto;
+}
+
 .menuHeader::after {
   content: '';
   position: absolute;
@@ -280,6 +463,7 @@
   border-bottom: borderWidthPrimary solid colorBorderPrimary;
 }
 
+/* As `.menuHeader`, pinned by sitting outside the options scroll container. */
 .menuFooter {
   position: sticky;
   background-color: colorBackgroundTertiary;

package/lib/components/Menu/MenuFocusScope.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { FloatingFocusManager } from '@floating-ui/react';
+/**
+ * floating-ui's `FloatingFocusManager`, or nothing at all.
+ *
+ * Mounting it is what manages focus, so there is no `disabled` prop to pass —
+ * the choice has to be whether the element exists. Every popup trigger in the
+ * dropdown family needs that choice: without `enableA11y` focus is managed by
+ * floating-ui exactly as it always was, and with it, `Menu` takes over, because
+ * the one thing `FloatingFocusManager` cannot express is returning focus to a
+ * trigger that lives OUTSIDE the popup.
+ */
+export declare const MenuFocusScope: ({ enabled, context, initialFocus, returnFocus, children, }: {
+    enabled: boolean;
+    context: React.ComponentProps<typeof FloatingFocusManager>["context"];
+    initialFocus: React.RefObject<HTMLElement | null>;
+    /** Passed through; `Typeahead` opts out, as it did before. */
+    returnFocus?: boolean;
+    children: React.ReactElement;
+}) => React.JSX.Element;
+//# sourceMappingURL=MenuFocusScope.d.ts.map

package/lib/components/Menu/MenuFocusScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MenuFocusScope.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/MenuFocusScope.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAC,oBAAoB,EAAC,MAAM,oBAAoB,CAAC;AAGxD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,4DAM5B;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,oBAAoB,CAAC,CAAC,SAAS,CAAC,CAAC;IACtE,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAClD,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC;CAC9B,sBAYE,CAAC"}

package/lib/components/Menu/MenuFocusScope.js

@@ -0,0 +1,37 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MenuFocusScope = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _react2 = require("@floating-ui/react");
+var _jsxRuntime = require("react/jsx-runtime");
+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); }
+/**
+ * floating-ui's `FloatingFocusManager`, or nothing at all.
+ *
+ * Mounting it is what manages focus, so there is no `disabled` prop to pass —
+ * the choice has to be whether the element exists. Every popup trigger in the
+ * dropdown family needs that choice: without `enableA11y` focus is managed by
+ * floating-ui exactly as it always was, and with it, `Menu` takes over, because
+ * the one thing `FloatingFocusManager` cannot express is returning focus to a
+ * trigger that lives OUTSIDE the popup.
+ */
+const MenuFocusScope = _ref => {
+  let {
+    enabled,
+    context,
+    initialFocus,
+    returnFocus,
+    children
+  } = _ref;
+  return enabled ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_react2.FloatingFocusManager, {
+    modal: false,
+    context: context,
+    returnFocus: returnFocus,
+    initialFocus: initialFocus,
+    children: children
+  }) : children;
+};
+exports.MenuFocusScope = MenuFocusScope;

package/lib/components/Menu/MenuOptionButton.d.ts

@@ -3,8 +3,44 @@ import type { CSSProperties } from 'react';
 import type { BaseMenuProps, MenuOption } from '../../components/Menu/Menu';
 export interface MenuOptionProps extends Omit<BaseMenuProps, 'option' | 'isLastItem' | 'style'> {
     option: MenuOption;
+    /**
+     * Last option in the list. Without `enableA11y` this is how the menu knows
+     * where Tab leaves it: the last option carries a keydown listener that calls
+     * `onTabOut`. With the opt-in, the keyboard hook owns Tab for the whole menu
+     * and this is ignored.
+     */
     isLastItem?: boolean;
     style?: CSSProperties | undefined;
+    /** Total option count — set for virtualized lists so AT announces "N of total". */
+    setSize?: number;
+    /** 1-based position — set for virtualized lists (windowed DOM hides the rest). */
+    posInSet?: number;
+    /**
+     * Make this option the active highlight when the pointer moves over it, so
+     * mouse and keyboard share one cursor (and roving focus follows the pointer).
+     * `clientX`/`clientY` let Menu drop no-op moves (scroll under a still cursor).
+     */
+    onPointerActivate?: (key: string, el: HTMLElement, clientX: number, clientY: number) => void;
+    /**
+     * Key of the option the POINTER most recently highlighted. Used to keep the
+     * focus ring off a highlight the mouse created, while the background tint still
+     * follows the pointer.
+     */
+    pointerActiveKey?: string | null;
+    /**
+     * Withhold the highlight the menu opened with. Set when the menu was opened by
+     * mouse, so it does not appear to have a cursor the user never placed; cleared
+     * as soon as they move the active option themselves.
+     */
+    suppressInitialHighlight?: boolean;
+    /**
+     * Whether focus is inside the menu. A roving menu's highlight IS its DOM
+     * focus, so it must not be drawn once focus has moved elsewhere on the page —
+     * the active option is still remembered, it is just no longer shown. The
+     * combobox modes ignore this: there the trigger input outside the menu holds
+     * focus by design and this highlight is the user's only cursor.
+     */
+    menuHasFocus?: boolean;
     testId?: string;
 }
 export declare const MenuOptionButton: (props: MenuOptionProps) => React.JSX.Element;

package/lib/components/Menu/MenuOptionButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MenuOptionButton.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/MenuOptionButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,OAAO,CAAC;AASzC,OAAO,KAAK,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAQxE,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IAC9D,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,sBA+MtD,CAAC"}
+{"version":3,"file":"MenuOptionButton.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/MenuOptionButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,OAAO,CAAC;AASzC,OAAO,KAAK,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC;AASxE,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IAC9D,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,IAAI,CAAC;IACV;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAcD,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,sBA+StD,CAAC"}

package/lib/components/Menu/MenuOptionButton.js

@@ -10,6 +10,7 @@ var _qa = require("../../utils/qa");
 var _Button = require("../Button");
 var _Checkbox = require("../Checkbox");
 var _Icon = require("../Icon");
+var _menuOptionId = require("./menuOptionId");
 var _RadioButton = require("../RadioButton");
 var _Truncate = require("../Truncate");
 var _TruncatedTextWithTooltip = require("../TruncatedTextWithTooltip");
@@ -17,6 +18,22 @@ 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); }
+/**
+ * Hides its child from assistive technology, adding no DOM node when it has
+ * nothing to hide — so the un-opted markup keeps exactly the shape it had.
+ */
+const Wrap = _ref => {
+  let {
+    hidden,
+    children
+  } = _ref;
+  return hidden ? /*#__PURE__*/(0, _jsxRuntime.jsx)("span", {
+    "aria-hidden": "true",
+    children: children
+  }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
+    children: children
+  });
+};
 const MenuOptionButton = props => {
   const lastMenuItemRef = React.useRef(null);
   const {
@@ -28,13 +45,24 @@ const MenuOptionButton = props => {
     classNames,
     optionsVariant = 'normal',
     selectedKeys,
-    isLastItem,
-    onTabOut,
     resolveLabel,
     resolveSecondaryLabel,
     style,
     showLabelTooltip,
     allowWrap = false,
+    enableA11y = false,
+    isLastItem,
+    onTabOut,
+    allowSearch = false,
+    menuId,
+    activeOptionKey,
+    externalKeyboardNav = false,
+    setSize,
+    posInSet,
+    onPointerActivate,
+    pointerActiveKey,
+    suppressInitialHighlight = false,
+    menuHasFocus = false,
     testId
   } = props;
   const {
@@ -62,24 +90,68 @@ const MenuOptionButton = props => {
     }
     return selectedKeys.includes(option.key);
   };
+  const isOptionSelected = isSelected() || key === selectedOption?.key;
+  const isOptionDisabled = Boolean(menuDisabled || disabled);
+  // Roving tabindex: Menu always passes activeOptionKey (string | null), so a
+  // single option owns the tab stop. The `undefined` fallback only matters if a
+  // MenuOptionButton is rendered outside Menu — there every option stays
+  // tabbable (default tabIndex), preserving the pre-roving behavior.
+  const isRoving = activeOptionKey !== undefined;
+  // `isActive` still drives the roving tab stop and aria-activedescendant — the
+  // menu always has an active option so the keyboard has somewhere to start.
+  // `showHighlight` is the visible half of it, withheld while the only reason an
+  // option is active is that the menu just opened under the mouse.
+  const isActive = isRoving && activeOptionKey === key;
+  const isVirtualFocusMode = allowSearch || externalKeyboardNav;
+  // Drawn only while the menu can actually be driven: under roving focus that
+  // means focus is inside it. `externalKeyboardNav` keeps it regardless, since
+  // the combobox input that owns focus lives outside this DOM.
+  const showHighlight = isActive && !suppressInitialHighlight && (externalKeyboardNav || menuHasFocus);
+  // Focus ring. Only the combobox modes need a CLASS for it: there, DOM focus
+  // stays on the trigger input and this ring is the only cursor the user has, so
+  // it is drawn from `activeOptionKey` — minus any highlight the pointer created,
+  // since a focus indicator must not follow the mouse.
+  //
+  // Roving menus move real DOM focus, so they are left to `:focus-visible` in CSS,
+  // which the browser only matches for keyboard-driven focus. That is why merely
+  // opening a roving menu with the mouse no longer paints a ring.
+  const showActiveRing = showHighlight && isVirtualFocusMode && pointerActiveKey !== key;
+  // The option is a real tab stop only under true roving focus. Under search or
+  // external combobox nav, focus stays on the input — every option is -1 and the
+  // active one is surfaced through the input's aria-activedescendant instead.
+  const optionTabIndex = externalKeyboardNav ? -1 : isRoving ? isActive && !allowSearch ? 0 : -1 : undefined;
+  const optionId = menuId ? (0, _menuOptionId.menuOptionId)(menuId, key) : undefined;
   React.useEffect(() => {
     setButtonSize(optionSize || size);
   }, [optionSize, size]);
+
+  // Tab out from the last option. Only without the opt-in: with it, Tab is
+  // handled for the whole menu by useMenuKeyboardNavigation, which knows about
+  // the header and footer this listener cannot see.
   React.useEffect(() => {
+    if (enableA11y) {
+      return;
+    }
     const handleKeyDown = event => {
       if (event.key === 'Tab' && !event.shiftKey) {
         // Tab pressed without shift key, calling tab out callback
         onTabOut?.();
       }
     };
-    lastMenuItemRef.current?.addEventListener('keydown', handleKeyDown);
+    const node = lastMenuItemRef.current;
+    node?.addEventListener('keydown', handleKeyDown);
     return () => {
-      lastMenuItemRef.current?.removeEventListener('keydown', handleKeyDown);
+      node?.removeEventListener('keydown', handleKeyDown);
     };
-  }, [isLastItem]);
+  }, [isLastItem, enableA11y]);
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_Button.UnstyledButton, {
     className: (0, _classify.classify)(_MenuModule.default.option, {
       [_MenuModule.default.selected]: isSelected() || key === selectedOption?.key,
+      // Background highlight for the single active option, from either input
+      // source, so pointer and keyboard never show two cursors.
+      [_MenuModule.default.active]: enableA11y && showHighlight,
+      // Focus ring, keyboard-driven highlights only.
+      [_MenuModule.default.activeRing]: enableA11y && showActiveRing,
       [_MenuModule.default.optionSmall]: buttonSize === 'small',
       [_MenuModule.default.optionMedium]: buttonSize === 'medium',
       [_MenuModule.default.disabled]: menuDisabled || disabled,
@@ -87,36 +159,72 @@ const MenuOptionButton = props => {
       [_MenuModule.default.withIconRight]: !!iconRight
     }, classNames?.option, optionClassNames?.wrapper),
     style: style,
-    disabled: menuDisabled || disabled,
-    onClick: e => onSelect && onSelect(option, e),
-    autoFocus: selectedOption?.key === key,
+    disabled: isOptionDisabled,
+    role: enableA11y ? 'option' : undefined,
+    "aria-selected": enableA11y ? isOptionSelected : undefined,
+    "aria-disabled": enableA11y && isOptionDisabled || undefined,
+    "aria-setsize": enableA11y ? setSize : undefined,
+    "aria-posinset": enableA11y ? posInSet : undefined,
+    tabIndex: enableA11y ? optionTabIndex : undefined,
+    id: enableA11y ? optionId : undefined,
+    "data-menu-option-key": enableA11y ? key : undefined,
+    onClick: e => onSelect && onSelect(option, e)
+    // Without the opt-in the selected option pulls focus to itself on mount,
+    // which is the only focus behavior this component had. The opt-in
+    // replaces it with Menu's own open-time focus, which can also decline to
+    // move focus at all (an inline menu must not steal it).
+    ,
+    autoFocus: !enableA11y && selectedOption?.key === key,
+    onMouseMove: e => {
+      // Pointer drives the same single active highlight as the keyboard.
+      // Guarded so it only fires when crossing into a different option. The
+      // cursor coordinates are forwarded so Menu can ignore moves with no real
+      // pointer delta (the list scrolling under a stationary cursor during
+      // keyboard nav), which would otherwise steal focus from the keyboard.
+      if (!enableA11y || isOptionDisabled || isActive) {
+        return;
+      }
+      onPointerActivate?.(key, e.currentTarget, e.clientX, e.clientY);
+    },
     testId: (0, _qa.generateTestId)({
       base: optionTestId || testId,
       slot: 'option-button',
       index: key
     }),
-    ...(isLastItem ? {
+    ...(!enableA11y && isLastItem ? {
       ref: lastMenuItemRef
     } : {}),
-    children: [optionVariant === 'checkbox' && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Checkbox.Checkbox, {
-      tabIndex: -1,
-      disabled: menuDisabled || disabled,
-      checked: isSelected(),
-      indeterminate: indeterminate,
-      testId: (0, _qa.generateTestId)({
-        base: optionTestId || testId,
-        slot: 'checkbox',
-        index: key
+    children: [optionVariant === 'checkbox' &&
+    /*#__PURE__*/
+    // The wrapper exists only to hide the control from AT: the option row
+    // already reports its own selected state, and a nested checkbox would
+    // be announced as a second, separate control. It is an extra DOM node,
+    // so it appears only with the opt-in.
+    (0, _jsxRuntime.jsx)(Wrap, {
+      hidden: enableA11y,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Checkbox.Checkbox, {
+        tabIndex: -1,
+        disabled: menuDisabled || disabled,
+        checked: isSelected(),
+        indeterminate: indeterminate,
+        testId: (0, _qa.generateTestId)({
+          base: optionTestId || testId,
+          slot: 'checkbox',
+          index: key
+        })
       })
-    }), optionVariant === 'radio' && /*#__PURE__*/(0, _jsxRuntime.jsx)(_RadioButton.RadioButton, {
-      disabled: menuDisabled || disabled,
-      value: option.key,
-      selectedValue: selectedKeys?.[0],
-      tabIndex: -1,
-      testId: (0, _qa.generateTestId)({
-        base: optionTestId || testId,
-        slot: 'radio-button',
-        index: key
+    }), optionVariant === 'radio' && /*#__PURE__*/(0, _jsxRuntime.jsx)(Wrap, {
+      hidden: enableA11y,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_RadioButton.RadioButton, {
+        disabled: menuDisabled || disabled,
+        value: option.key,
+        selectedValue: selectedKeys?.[0],
+        tabIndex: -1,
+        testId: (0, _qa.generateTestId)({
+          base: optionTestId || testId,
+          slot: 'radio-button',
+          index: key
+        })
       })
     }), !!iconLeft && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Icon.Icon, {
       name: iconLeft,
@@ -179,14 +287,14 @@ const MenuOptionButton = props => {
   });
 };
 exports.MenuOptionButton = MenuOptionButton;
-const renderLabel = _ref => {
+const renderLabel = _ref2 => {
   let {
     label,
     allowWrap,
     showLabelTooltip,
     testId,
     key
-  } = _ref;
+  } = _ref2;
   if (showLabelTooltip) {
     return /*#__PURE__*/(0, _jsxRuntime.jsx)(_TruncatedTextWithTooltip.TruncatedTextWithTooltip, {
       tooltip: {

package/lib/components/Menu/index.d.ts

@@ -1,3 +1,5 @@
 export * from '../../components/Menu/Menu';
 export * from '../../components/Menu/MenuOptionButton';
+export * from '../../components/Menu/useMenuTrigger';
+export * from '../../components/Menu/useMenuKeyboardNavigation';
 //# sourceMappingURL=index.d.ts.map

package/lib/components/Menu/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AAKrD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+CAA+C,CAAC"}

package/lib/components/Menu/index.js

@@ -24,4 +24,26 @@ Object.keys(_MenuOptionButton).forEach(function (key) {
       return _MenuOptionButton[key];
     }
   });
+});
+var _useMenuTrigger = require("./useMenuTrigger");
+Object.keys(_useMenuTrigger).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useMenuTrigger[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useMenuTrigger[key];
+    }
+  });
+});
+var _useMenuKeyboardNavigation = require("./useMenuKeyboardNavigation");
+Object.keys(_useMenuKeyboardNavigation).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useMenuKeyboardNavigation[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useMenuKeyboardNavigation[key];
+    }
+  });
 });