@spaced-out/ui-design-system 0.6.36 → 0.6.37

package/lib/components/Dropdown/Dropdown.js

@@ -14,6 +14,8 @@ var _mergeRefs = require("../../utils/merge-refs");
 var _qa = require("../../utils/qa");
 var _Input = require("../Input");
 var _Menu = require("../Menu");
+var _MenuFocusScope = require("../Menu/MenuFocusScope");
+var _useMenuTrigger = require("../Menu/useMenuTrigger");
 var _Tooltip = require("../Tooltip");
 var _DropdownModule = _interopRequireDefault(require("./Dropdown.module.css"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -32,10 +34,13 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
     dropdownInputText = '',
     clickAwayRef,
     elevation = 'modal',
+    enableA11y = false,
     testId,
     ...inputProps
   } = _ref;
   const menuRef = React.useRef(null);
+  const clickAwayFnRef = React.useRef(null);
+  const [isMenuOpen, setIsMenuOpen] = React.useState(false);
   const {
     x,
     y,
@@ -50,19 +55,75 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
     middleware: [(0, _react2.flip)(), (0, _react2.offset)(parseInt(_space.spaceXXSmall))]
   });
   const dropdownWidth = (0, _hooks.useReferenceElementWidth)(refs.reference?.current);
+  const focusTriggerInput = () => {
+    refs.reference?.current?.querySelector('input')?.focus();
+  };
+  const handleOptionSelect = (option, e) => {
+    onChange?.(option, e ?? null);
+    if (
+    // keepMenuOpenOnOptionSelect lets the menu persist on select in the normal variant
+    !option.keepMenuOpenOnOptionSelect && (!menu?.optionsVariant || menu.optionsVariant === 'normal')) {
+      clickAwayFnRef.current?.();
+      focusTriggerInput();
+    }
+  };
+
+  // The combobox half of the trigger wiring: the role and its ARIA, the
+  // active-option state behind `aria-activedescendant`, keyboard navigation
+  // against the real option list, and the props that tie the two together.
+  const comboboxTrigger = (0, _useMenuTrigger.useComboboxMenuTrigger)({
+    enabled: enableA11y,
+    menu,
+    menuRef,
+    isOpen: isMenuOpen,
+    onSelectOption: option => handleOptionSelect(option, null),
+    onClose: () => clickAwayFnRef.current?.(),
+    focusTrigger: focusTriggerInput,
+    triggerAriaLabelledBy: inputProps['aria-labelledby'],
+    triggerAriaLabel: inputProps['aria-label']
+  });
   const onMenuToggle = isOpen => {
+    setIsMenuOpen(isOpen);
     if (isOpen) {
       onMenuOpen?.();
     } else {
       onMenuClose?.();
     }
-    if (scrollMenuToBottom && menuRef.current && isOpen) {
+    if (!enableA11y && scrollMenuToBottom && menuRef.current && isOpen) {
+      // Kept as it was, deliberately. This runs before the portal holding
+      // the menu has mounted, so `menuRef` is empty and it does nothing —
+      // the effect below is the working version, and it is part of the
+      // opt-in because the element it scrolls only exists there. Restoring
+      // the scroll for consumers who have not opted in would be a visible
+      // change to menus that have never scrolled to the bottom.
       menuRef.current.scrollTop = isOpen ? menuRef.current.scrollHeight : 0;
     }
   };
+
+  // `scrollMenuToBottom` cannot be honoured from ClickAway's open callback:
+  // the menu lives in a portal that has not mounted yet at that point, so
+  // `menuRef` is still empty and the scroll silently does nothing. Wait for
+  // the open render to commit, then scroll the element that actually
+  // scrolls — the listbox itself, or react-window's box when virtualized,
+  // whichever Menu marked. rAF rather than a layout effect because the
+  // portal fills in a commit later still, and Menu's own open-time scroll
+  // (to a seeded active option) must not be undone by this one.
+  React.useEffect(() => {
+    if (!enableA11y || !scrollMenuToBottom || !isMenuOpen) {
+      return;
+    }
+    const frame = requestAnimationFrame(() => {
+      const scroller = menuRef.current?.querySelector('[data-menu-scroll-container]') ?? menuRef.current;
+      if (scroller) {
+        scroller.scrollTop = scroller.scrollHeight;
+      }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [enableA11y, scrollMenuToBottom, isMenuOpen]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_clickAway.ClickAway, {
     onChange: onMenuToggle,
     clickAwayRef: clickAwayRef,
+    restoreFocusOnClose: enableA11y,
     children: _ref2 => {
       let {
         isOpen,
@@ -71,6 +132,9 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
         boundaryRef,
         triggerRef
       } = _ref2;
+      // Capture the latest close handler so keyboard selection (which is
+      // wired at the component top level) can close the menu.
+      clickAwayFnRef.current = clickAway;
       return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
         className: (0, _classify.classify)(_DropdownModule.default.dropdownContainer, classNames?.wrapper),
         "data-testid": (0, _qa.generateTestId)({
@@ -79,22 +143,34 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
         }),
         children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.Input, {
           ...inputProps,
-          onKeyDown: e => {
-            if (e.keyCode === 32) {
-              e.preventDefault();
-              if (isOpen) {
-                clickAway();
-              } else {
-                onOpen();
+          ...(enableA11y ? comboboxTrigger.getTriggerProps({
+            isOpen,
+            onOpen,
+            // Chained rather than replaced: `onKeyDown` is a public
+            // prop of Dropdown (via InputProps) and of Combobox,
+            // which forwards it as `onDropdownKeyDown`. The hook
+            // stands down for any key the consumer's handler claims.
+            onKeyDown: inputProps.onKeyDown
+          }) : {
+            onKeyDown: e => {
+              if (e.keyCode === 32) {
+                e.preventDefault();
+                if (isOpen) {
+                  clickAway();
+                } else {
+                  onOpen();
+                }
               }
             }
-          },
+          }),
           boxRef: (0, _mergeRefs.mergeRefs)([refs.setReference, triggerRef]),
           size: size,
           placeholder: placeholder,
           value: dropdownInputText,
           classNames: {
-            box: (0, _classify.classify)(_DropdownModule.default.inputBox, classNames?.box),
+            box: (0, _classify.classify)(_DropdownModule.default.inputBox, {
+              [_DropdownModule.default.inputBoxOpen]: enableA11y && isOpen
+            }, classNames?.box),
             iconRight: classNames?.iconRight
           },
           iconRightName: isOpen ? 'angle-up' : 'angle-down',
@@ -109,8 +185,8 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
             slot: 'input'
           })
         }), isOpen && menu && /*#__PURE__*/(0, _jsxRuntime.jsx)(_react2.FloatingPortal, {
-          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_react2.FloatingFocusManager, {
-            modal: false,
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuFocusScope.MenuFocusScope, {
+            enabled: !enableA11y,
             context: context,
             initialFocus: refs.reference,
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
@@ -136,24 +212,16 @@ const Dropdown = exports.Dropdown = /*#__PURE__*/React.forwardRef((_ref, ref) =>
               },
               children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Menu.Menu, {
                 ...menu,
+                ...comboboxTrigger.menuProps,
                 testId: (0, _qa.generateTestId)({
                   base: testId,
                   slot: 'menu'
                 }),
-                onSelect: (option, e) => {
-                  onChange?.(option, e);
-                  if (
-                  // option.keepMenuOpenOnOptionSelect - to allow the menu persist its open stat upon option selection in normal variant
-                  !option.keepMenuOpenOnOptionSelect && (!menu.optionsVariant || menu.optionsVariant === 'normal')) {
-                    clickAway();
-                    if (refs.reference?.current) {
-                      refs.reference.current?.querySelector('input')?.focus();
-                    }
-                  }
-                },
+                onSelect: handleOptionSelect,
                 size: menu.size || size,
                 onTabOut: clickAway,
-                ref: menuRef
+                ref: menuRef,
+                enableA11y: enableA11y
               })
             })
           })

package/lib/components/Dropdown/Dropdown.module.css

@@ -2,6 +2,10 @@
   sizeFluid
 ) from '../../styles/variables/_size.css';
 
+@value (
+  borderWidthTertiary
+) from '../../styles/variables/_border.css';
+
 .dropdownContainer {
   display: flex;
   position: relative;
@@ -13,6 +17,26 @@
   cursor: pointer;
 }
 
+/*
+ * Keeping the trigger visually active while its menu is open (DOM focus has
+ * moved into the listbox) is done in Input.module.css, keyed off the trigger's
+ * own `aria-expanded`. It has to live there: the rules it must beat are scoped
+ * to Input's `.wrapper` / `.box` / `.withError` class names, which this module
+ * cannot name and therefore cannot reliably out-specify.
+ */
+
+/*
+ * forced-colors mode drops the box-shadow open-emphasis ring; the base box
+ * border survives, but add a system-color outline so the open state stays
+ * perceivable in Windows High Contrast.
+ */
+@media (forced-colors: active) {
+  .inputBox.inputBoxOpen {
+    outline: borderWidthTertiary solid Highlight;
+    outline-offset: borderWidthTertiary;
+  }
+}
+
 .menuWrapper {
   width: var(--dropdown-width);
   z-index: var(--menu-elevation);

package/lib/components/InlineDropdown/InlineDropdown.d.ts

@@ -18,6 +18,16 @@ export interface InlineDropdownProps extends Omit<UnstyledButtonProps, 'classNam
     onMenuClose?: () => unknown;
     size?: 'medium' | 'small' | 'extraSmall';
     elevation?: ElevationType;
+    /**
+     * Opt in to the accessibility behavior: `aria-haspopup` / `aria-expanded` /
+     * `aria-controls` on the trigger, the arrow key that opens the popup, focus
+     * moving into the menu and back to the trigger, and the roving tab stop
+     * inside it. Forwarded to the `Menu` this opens.
+     *
+     * Off by default, and off is this component exactly as it behaved before any
+     * of it existed.
+     */
+    enableA11y?: boolean;
     clickAwayRef?: React.RefObject<ClickAwayRefType | null>;
     testId?: string;
 }

package/lib/components/InlineDropdown/InlineDropdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"InlineDropdown.d.ts","sourceRoot":"","sources":["../../../src/components/InlineDropdown/InlineDropdown.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,4BAA4B,CAAC;AAKrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAK3D,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,+BAA+B,CAAC;AAE9D,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAC;AAO1D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,mBACf,SAAQ,IAAI,CACV,mBAAmB,EACjB,YAAY,GACZ,MAAM,GACN,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,WAAW,GACX,cAAc,CACjB;IACD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,KACxD,OAAO,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IACzC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,cAAc,EAAE,IAAI,CAAC,iBAAiB,CACjD,mBAAmB,EACnB,cAAc,CA0If,CAAC"}
+{"version":3,"file":"InlineDropdown.d.ts","sourceRoot":"","sources":["../../../src/components/InlineDropdown/InlineDropdown.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAU/B,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,4BAA4B,CAAC;AAKrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAK3D,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,+BAA+B,CAAC;AAE9D,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAI/D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAC;AAO1D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,mBACf,SAAQ,IAAI,CACV,mBAAmB,EACjB,YAAY,GACZ,MAAM,GACN,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,aAAa,GACb,MAAM,GACN,WAAW,GACX,cAAc,CACjB;IACD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,KACxD,OAAO,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IACzC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,cAAc,EAAE,IAAI,CAAC,iBAAiB,CACjD,mBAAmB,EACnB,cAAc,CAiKf,CAAC"}

package/lib/components/InlineDropdown/InlineDropdown.js

@@ -15,6 +15,8 @@ var _qa = require("../../utils/qa");
 var _Button = require("../Button");
 var _Icon = require("../Icon");
 var _Menu = require("../Menu");
+var _MenuFocusScope = require("../Menu/MenuFocusScope");
+var _useMenuTrigger = require("../Menu/useMenuTrigger");
 var _Tooltip = require("../Tooltip");
 var _Truncate = require("../Truncate");
 var _InlineDropdownModule = _interopRequireDefault(require("./InlineDropdown.module.css"));
@@ -34,9 +36,18 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
     children,
     clickAwayRef,
     elevation = 'modal',
+    enableA11y = false,
     testId,
     ...restButtonProps
   } = _ref;
+  const menuTrigger = (0, _useMenuTrigger.useMenuTrigger)({
+    enabled: enableA11y,
+    // The consumer's own id and menu naming are kept — see ButtonDropdown.
+    id: restButtonProps.id,
+    menuId: menu?.menuId,
+    ariaLabel: menu?.ariaLabel,
+    ariaLabelledBy: menu?.ariaLabelledBy
+  });
   const {
     x,
     y,
@@ -61,6 +72,7 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_clickAway.ClickAway, {
     onChange: onMenuToggle,
     clickAwayRef: clickAwayRef,
+    restoreFocusOnClose: enableA11y,
     children: _ref2 => {
       let {
         isOpen,
@@ -79,6 +91,12 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
         children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_Button.UnstyledButton, {
           ...restButtonProps,
           disabled: disabled,
+          ...menuTrigger.getTriggerProps({
+            // With no `menu` there is no popup to advertise or to open.
+            isOpen: isOpen && Boolean(menu),
+            onOpen,
+            onKeyDown: restButtonProps.onKeyDown
+          }),
           ref: (0, _mergeRefs.mergeRefs)([refs.setReference, triggerRef]),
           onClick: e => {
             e.stopPropagation();
@@ -110,10 +128,10 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
             })
           })]
         }), isOpen && menu && /*#__PURE__*/(0, _jsxRuntime.jsx)(_react2.FloatingPortal, {
-          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_react2.FloatingFocusManager, {
-            modal: false,
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuFocusScope.MenuFocusScope, {
+            enabled: !enableA11y,
             context: context,
-            initialFocus: triggerRef,
+            initialFocus: refs.reference,
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
               className: _InlineDropdownModule.default.menuWrapper,
               ref: (0, _mergeRefs.mergeRefs)([refs.setFloating, boundaryRef]),
@@ -138,6 +156,7 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
               },
               children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Menu.Menu, {
                 ...menu,
+                ...menuTrigger.menuProps,
                 onSelect: (option, e) => {
                   onOptionSelect?.(option, e);
                   if (
@@ -148,6 +167,7 @@ const InlineDropdown = exports.InlineDropdown = /*#__PURE__*/React.forwardRef((_
                 },
                 size: menu.size || 'medium',
                 onTabOut: clickAway,
+                enableA11y: enableA11y,
                 testId: (0, _qa.generateTestId)({
                   base: testId,
                   slot: 'menu'

package/lib/components/Input/Input.module.css

@@ -111,6 +111,44 @@
     borderWidthTertiary colorFocusPrimary;
 }
 
+/*
+ * The field is a popup trigger whose popup is open, so DOM focus has moved into a
+ * portal and `:focus-within` above no longer matches. Keep the emphasis anyway,
+ * including while hovered — otherwise the hover rule repaints the border grey and
+ * leaves the popup's halo behind it, a two-tone broken state.
+ *
+ * These live here rather than in Dropdown/Typeahead's own module because the
+ * rules being overridden are scoped to THIS module's `.wrapper` / `.box` /
+ * `.withError` class names, which a consumer stylesheet cannot name and so cannot
+ * reliably out-specify.
+ *
+ * Both the popup attribute AND the expanded state are required so this only ever
+ * hits a TRIGGER. On `aria-expanded` alone it also matches any other expanded
+ * input inside the field — such as a filter field rendered in the popup — and
+ * paints a focus ring on something that never has focus. `:not(.locked)` matches
+ * the adjacent hover rules: keying off ARIA loses the protection `:focus-within`
+ * had for free, since a locked field's input is natively disabled and so could
+ * never have been focused.
+ */
+.wrapper:not(.withError)
+  .box:not(.inputDisabled):not(.locked):has(
+    input[aria-haspopup][aria-expanded='true']
+  ) {
+  border-color: colorFillPrimary;
+  box-shadow: borderWidthNone borderWidthNone borderWidthNone
+    borderWidthTertiary colorFocusPrimary;
+}
+
+/* An errored trigger keeps the danger colors when its popup is open. */
+.wrapper.withError
+  .box:not(.inputDisabled):not(.locked):has(
+    input[aria-haspopup][aria-expanded='true']
+  ) {
+  border-color: colorTextDanger;
+  box-shadow: borderWidthNone borderWidthNone borderWidthNone
+    borderWidthTertiary colorFocusDanger;
+}
+
 .inputDisabled {
   color: colorTextDisabled;
   border-color: colorBorderPrimary;

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

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import type { Flow } from 'flow-to-typescript-codemod';
+import { FixedSizeList, VariableSizeList } from 'react-window';
 import type { MenuClassNames, MenuLabelTooltip } from '../../types/menu';
 import type { IconType } from '../../components/Icon/Icon';
 type ClassNames = MenuClassNames;
@@ -24,6 +25,11 @@ export type Virtualization = Readonly<{
     /** Max height of the whole card in px, search/header/footer included; never below the first row. */
     menuHeight?: number;
 }>;
+/**
+ * Either react-window list Menu may render. Both expose the `scrollToItem`
+ * used to keep the keyboard's active option mounted.
+ */
+type VirtualList = FixedSizeList | VariableSizeList;
 export interface MenuOption {
     key: string;
     classNames?: OptionClassNames;
@@ -51,7 +57,32 @@ export interface BaseMenuProps {
     width?: string;
     menuDisabled?: boolean;
     isFluid?: boolean;
+    /**
+     * Opt in to the accessibility behavior: keyboard navigation, the
+     * `listbox` / `option` roles and their states, focus management on open and
+     * close, and the scroll container moving onto the listbox.
+     *
+     * Off by default, and off is not a degraded mode — it is this component
+     * exactly as it behaved before any of it existed: no roles, no ARIA, no key
+     * handling, no focus moved, the card scrolling as it always did. Every prop
+     * below that exists to serve the accessible behavior (`onTabOut`,
+     * `onReturnFocusToInput`, `menuId`, `ariaLabelledBy`, `ariaLabel`,
+     * `initialFocusRef`, `activeOptionKey`, `externalKeyboardNav`,
+     * `onActiveOptionKeyChange`) is inert while this is unset.
+     *
+     * It is opt-in per call site so a surface can turn it on, verify it, and
+     * leave the rest of the app untouched — the behavior changes focus and DOM
+     * structure, and those are the things an app is most likely to have built
+     * around.
+     */
+    enableA11y?: boolean;
     onTabOut?: () => unknown;
+    /**
+     * Combobox consumers only: return focus to the trigger input (menu stays open)
+     * when Tab/Shift+Tab moves off a header/footer control back toward the input.
+     * The input lives outside the menu DOM, so it is the centre of the tab order.
+     */
+    onReturnFocusToInput?: () => void;
     allowSearch?: boolean;
     resolveLabel?: (option: MenuOption) => string | React.ReactNode;
     resolveSecondaryLabel?: (option: MenuOption) => string | React.ReactNode;
@@ -63,9 +94,56 @@ export interface BaseMenuProps {
         RESULT?: string;
         RESULTS?: string;
         SEARCH_PLACEHOLDER?: string;
+        /**
+         * Announced by a `Typeahead`'s live region while it is loading, and when a
+         * search returns nothing. Here rather than on `Typeahead` so every string a
+         * menu can speak is overridden in one place.
+         */
+        LOADING_RESULTS?: string;
+        NO_RESULTS?: string;
     };
     showLabelTooltip?: MenuLabelTooltip;
     allowWrap?: boolean;
+    /**
+     * id applied to the option `listbox` — the element a trigger's `aria-controls`
+     * should reference — and the prefix for the per-option ids that
+     * `aria-activedescendant` points at. Falls back to a generated id. It is not
+     * on the outer card.
+     */
+    menuId?: string;
+    /**
+     * Accessible name for the popup, linked to the trigger that opens it.
+     */
+    ariaLabelledBy?: string;
+    /**
+     * Literal accessible name for the listbox, used only when `ariaLabelledBy` is
+     * not supplied. Defaults to `'Options'` so the listbox is never unnamed — pass
+     * something specific to the content wherever you can.
+     */
+    ariaLabel?: string;
+    /**
+     * Marks the Menu as a popup that should auto-focus on open. When provided,
+     * Menu moves focus to the search input (or the active option) once it mounts
+     * and writes that element into the ref. Omit it for inline Menus (and for
+     * combobox triggers using `externalKeyboardNav`) so focus is never stolen.
+     */
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Controlled active option, honoured only with `externalKeyboardNav`: the
+     * trigger outside the menu owns the highlight and reports it here. Without
+     * `externalKeyboardNav` Menu manages its own active option (the roving tab
+     * stop, or the search field's active descendant) and this prop is ignored.
+     */
+    activeOptionKey?: string | null;
+    /**
+     * When true the Menu is driven by an external combobox input (e.g. Dropdown /
+     * Typeahead): focus stays on that input, the Menu does not run its own
+     * keyboard navigation or move focus into itself, and `activeOptionKey` is a
+     * controlled prop reflecting the input's aria-activedescendant.
+     */
+    externalKeyboardNav?: boolean;
+    /** Report active-option changes when `externalKeyboardNav` is set. */
+    onActiveOptionKeyChange?: (key: string | null) => void;
     testId?: string;
 }
 export interface MenuOptionTypes {
@@ -84,7 +162,28 @@ export interface MenuProps extends BaseMenuProps, MenuOptionTypes {
 }
 export interface RenderOptionProps extends Omit<MenuProps, 'searchText'> {
     searchText?: string;
+    /** Pointer-activation handler threaded down to each MenuOptionButton. */
+    onPointerActivate?: (key: string, el: HTMLElement, clientX: number, clientY: number) => void;
+    /** Handle on the virtual list, so Menu can scroll the active option into view. */
+    listRef?: React.RefCallback<VirtualList>;
+    /** Key the pointer most recently highlighted — keeps the focus ring off it. */
+    pointerActiveKey?: string | null;
+    /** Withhold the opening highlight until the user drives the menu themselves. */
+    suppressInitialHighlight?: boolean;
+    /** Whether focus is inside the menu — a roving highlight is only drawn then. */
+    menuHasFocus?: boolean;
 }
+/**
+ * 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`.
+ */
+export declare const getFlatOptions: (props: MenuProps) => MenuOption[];
+/**
+ * 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.
+ */
+export declare const getInitialActiveOptionKey: (props: MenuProps) => string | null;
 export declare const Menu: Flow.AbstractComponent<MenuProps, HTMLDivElement>;
 export {};
 //# sourceMappingURL=Menu.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Menu.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/Menu.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Menu.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/Menu.tsx"],"names":[],"mappings":"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"}