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

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

@@ -0,0 +1,207 @@
+import * as React from 'react';
+import type { MenuOption, MenuProps } from '../../components/Menu/Menu';
+/**
+ * Wires a trigger to the Menu it opens.
+ *
+ * Three things have to live on the trigger rather than in Menu, because they
+ * exist while the menu does NOT: `aria-haspopup`, `aria-expanded="false"`, and
+ * the ArrowDown/ArrowUp that opens the popup in the first place. That is the
+ * floor — no Menu prop can supply them — so these hooks hand them over as props
+ * to spread instead, and own everything else: the ids, the tie between the
+ * trigger's name and the listbox, and the ref Menu focuses into on open.
+ *
+ * `useMenuTrigger` is for triggers whose popup options own focus — a button, a
+ * tab overflow chevron, an inline label — so arrows move real DOM focus.
+ * `useComboboxMenuTrigger` is for triggers that are text inputs, where focus
+ * stays put and the highlight is virtual (`aria-activedescendant`).
+ *
+ * `getTriggerProps` is a getter rather than a static object because open state
+ * belongs to the consumer's `ClickAway`, which exposes it through a render
+ * callback — where a hook cannot be called.
+ *
+ *     const menuTrigger = useMenuTrigger({id: props.id, ariaLabel: menu?.ariaLabel});
+ *     <ClickAway restoreFocusOnClose>
+ *       {({isOpen, onOpen, clickAway}) => (
+ *         <>
+ *           <Button {...props} {...menuTrigger.getTriggerProps({isOpen, onOpen})} />
+ *           {isOpen && (
+ *             <Menu
+ *               {...menu}
+ *               {...menuTrigger.menuProps}
+ *               enableA11y
+ *               onTabOut={clickAway}
+ *             />
+ *           )}
+ *         </>
+ *       )}
+ *     </ClickAway>
+ *
+ * `restoreFocusOnClose` is what returns focus to the trigger when the menu
+ * closes. Menu moves focus INTO the popup on open, so without it Escape, a
+ * selection or Tab leaves focus on `document.body` — the components in this
+ * package pass it alongside their own `enableA11y`.
+ */
+export interface UseMenuTriggerArgs {
+    /**
+     * Produce the wiring at all. False returns empty props and an inert handler,
+     * so a consumer can call the hook unconditionally (hooks cannot be
+     * conditional) while its own accessibility opt-in is off.
+     */
+    enabled?: boolean;
+    /**
+     * The trigger's own `id`, when the consumer supplied one. It is kept — the
+     * hook only mints an id when there is none, since the listbox is named after
+     * the trigger through it.
+     */
+    id?: string;
+    /** The listbox id, when the consumer set `menu.menuId`. Minted otherwise. */
+    menuId?: string;
+    /** Literal name for the listbox. Wins over naming it after the trigger. */
+    ariaLabel?: string;
+    /** Id of the element naming the listbox. Defaults to the trigger itself. */
+    ariaLabelledBy?: string;
+}
+/**
+ * Generic in the trigger element so the returned handler matches whatever it is
+ * spread onto — inferred from the trigger's own `onKeyDown` where it has one.
+ */
+export interface GetTriggerPropsArgs<T extends HTMLElement = HTMLElement> {
+    /** The consumer's popup state — what ClickAway reports. */
+    isOpen: boolean;
+    onOpen: () => void;
+    /** The trigger's own key handler, if it has one. Runs first. */
+    onKeyDown?: React.KeyboardEventHandler<T>;
+}
+export interface MenuTriggerProps<T extends HTMLElement = HTMLElement> {
+    id: string;
+    'aria-haspopup': 'listbox';
+    'aria-expanded': boolean;
+    'aria-controls': string | undefined;
+    onKeyDown: React.KeyboardEventHandler<T>;
+}
+export interface MenuTriggerMenuProps {
+    menuId: string;
+    ariaLabelledBy?: string;
+    ariaLabel?: string;
+    initialFocusRef: React.RefObject<HTMLElement | null>;
+}
+export declare const useMenuTrigger: ({ enabled, id, menuId: consumerMenuId, ariaLabel, ariaLabelledBy, }?: UseMenuTriggerArgs) => {
+    getTriggerProps: <T extends HTMLElement = HTMLElement>(args: GetTriggerPropsArgs<T>) => MenuTriggerProps<T>;
+    menuProps: MenuTriggerMenuProps;
+};
+/**
+ * Which of ARIA's two combobox patterns the trigger implements.
+ *
+ * - `select` — a read-only field standing in for a `<select>`. An option is
+ *   highlighted as soon as the list opens, Space selects it (the field has no
+ *   typing role), and Enter or Space opens the list in the first place.
+ * - `autocomplete` — an editable field that filters the list as you type.
+ *   Nothing is highlighted until the user arrows to it (APG calls this manual
+ *   selection: auto-highlighting would let Enter select something they never
+ *   chose), Space types a space, and only the arrow keys open the list.
+ */
+export type ComboboxPattern = 'select' | 'autocomplete';
+export interface UseComboboxMenuTriggerArgs {
+    /**
+     * Produce the wiring at all. False returns empty props and an inert handler,
+     * so a consumer can call the hook unconditionally while its own accessibility
+     * opt-in is off.
+     */
+    enabled?: boolean;
+    /** Which pattern this trigger implements. Defaults to `select`. */
+    pattern?: ComboboxPattern;
+    /**
+     * The menu this trigger opens. Read for the option source (unless `options`
+     * is given), the selection, `virtualization`, `menuDisabled`, `resolveLabel`,
+     * `allowSearch` and the consumer's own `menuId` / `ariaLabel` /
+     * `ariaLabelledBy`, all of which win over what the hook would derive.
+     */
+    menu?: MenuProps;
+    /**
+     * Option source, when it is not `menu` — a consumer that owns filtering and
+     * hands the already-filtered options to Menu supplies them here instead. Every
+     * derivation (navigation list, highlight seed, selection lookup) uses it.
+     */
+    options?: Array<MenuOption>;
+    /**
+     * Refuse to open, e.g. until enough has been typed. Consulted only for the
+     * keys that would otherwise open the list.
+     */
+    canOpen?: () => boolean;
+    /** Ref on the rendered Menu, for reaching its header/footer controls. */
+    menuRef: React.RefObject<HTMLElement | null>;
+    /**
+     * The consumer's popup state — what ClickAway reports. Drives which keys the
+     * trigger handles (open-state navigation vs. closed-state opening) and the
+     * highlight's lifecycle. If the listbox can be WITHHELD while the popup is
+     * open (still loading, no matches), keep passing the open state here and hand
+     * `isExpanded` to `getTriggerProps` for the ARIA — routing keys off the
+     * rendered state instead would make an arrow key call `onOpen` on an
+     * already-open popup, and `onOpen` toggles.
+     */
+    isOpen: boolean;
+    /** Apply a selection. Called with the option the keyboard acted on. */
+    onSelectOption: (option: MenuOption) => void;
+    /** Close the popup — used when Tab leaves a menu with no chrome to land on. */
+    onClose: () => void;
+    /** Put focus back on the trigger input, keeping the menu open. */
+    focusTrigger: () => void;
+    /** What already labels the trigger, used to name the listbox after it. */
+    triggerAriaLabelledBy?: string;
+    triggerAriaLabel?: string;
+    /**
+     * Literal name for the listbox when nothing else supplies one. Defaults to
+     * `'Options'`; a suggestion list wants something truer to what it holds.
+     */
+    defaultAriaLabel?: string;
+}
+export interface GetComboboxTriggerPropsArgs<T extends HTMLElement = HTMLElement> extends GetTriggerPropsArgs<T> {
+    /**
+     * Whether the listbox is actually rendered right now, when that can differ
+     * from `isOpen` (a popup withheld while loading or with no matches). Drives
+     * `aria-expanded`, `aria-controls` and `aria-activedescendant`, so the trigger
+     * never claims an expanded listbox that is not in the DOM. Defaults to
+     * `isOpen`.
+     */
+    isExpanded?: boolean;
+}
+export interface ComboboxTriggerProps<T extends HTMLElement = HTMLElement> {
+    role: 'combobox';
+    'aria-haspopup': 'listbox';
+    'aria-expanded': boolean;
+    'aria-controls': string | undefined;
+    'aria-autocomplete': 'none' | 'list';
+    'aria-activedescendant': string | undefined;
+    onKeyDown: React.KeyboardEventHandler<T>;
+}
+export interface ComboboxMenuProps {
+    menuId: string;
+    ariaLabelledBy?: string;
+    ariaLabel?: string;
+    externalKeyboardNav: boolean;
+    activeOptionKey?: string | null;
+    onActiveOptionKeyChange?: (key: string | null) => void;
+    onReturnFocusToInput?: () => void;
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+}
+/**
+ * Wires a COMBOBOX trigger — a text input — to the Menu it opens. Focus stays
+ * on the input and the highlight is virtual, reported through
+ * `aria-activedescendant`, because the input has to keep receiving the keys it
+ * filters with.
+ *
+ * Driving the highlight from outside Menu means owning the active option as
+ * state, and owning it means deriving the same option list, initial highlight
+ * and navigation list that Menu derives internally. Both combobox consumers had
+ * grown their own copies of all three; they come from Menu itself now.
+ *
+ * A menu that carries its own filter field (`menu.allowSearch`) inverts the
+ * model: navigation lives inside Menu, so the trigger stops driving it and
+ * hands over an `initialFocusRef` instead. Both shapes come out of this hook.
+ */
+export declare const useComboboxMenuTrigger: ({ enabled, pattern, menu, options, canOpen, menuRef, isOpen, onSelectOption, onClose, focusTrigger, triggerAriaLabelledBy, triggerAriaLabel, defaultAriaLabel, }: UseComboboxMenuTriggerArgs) => {
+    getTriggerProps: <T extends HTMLElement = HTMLElement>(args: GetComboboxTriggerPropsArgs<T>) => ComboboxTriggerProps<T>;
+    menuProps: ComboboxMenuProps;
+    activeOptionKey: string | null;
+};
+//# sourceMappingURL=useMenuTrigger.d.ts.map

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

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

package/lib/components/Menu/useMenuTrigger.js

@@ -0,0 +1,389 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMenuTrigger = exports.useComboboxMenuTrigger = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _hooks = require("../../hooks");
+var _Menu = require("./Menu");
+var _menuOptionId = require("./menuOptionId");
+var _useMenuKeyboardNavigation = require("./useMenuKeyboardNavigation");
+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); }
+/**
+ * Drop undefined-valued keys. The props these hooks return are spread AFTER the
+ * consumer's own `menu` props, and an own property holding `undefined` would
+ * erase a value the consumer set — `{...menu, ...{ariaLabel: undefined}}` has no
+ * label at all.
+ */
+const compact = obj => Object.fromEntries(Object.entries(obj).filter(_ref => {
+  let [, value] = _ref;
+  return value !== undefined;
+}));
+
+/**
+ * Wires a trigger to the Menu it opens.
+ *
+ * Three things have to live on the trigger rather than in Menu, because they
+ * exist while the menu does NOT: `aria-haspopup`, `aria-expanded="false"`, and
+ * the ArrowDown/ArrowUp that opens the popup in the first place. That is the
+ * floor — no Menu prop can supply them — so these hooks hand them over as props
+ * to spread instead, and own everything else: the ids, the tie between the
+ * trigger's name and the listbox, and the ref Menu focuses into on open.
+ *
+ * `useMenuTrigger` is for triggers whose popup options own focus — a button, a
+ * tab overflow chevron, an inline label — so arrows move real DOM focus.
+ * `useComboboxMenuTrigger` is for triggers that are text inputs, where focus
+ * stays put and the highlight is virtual (`aria-activedescendant`).
+ *
+ * `getTriggerProps` is a getter rather than a static object because open state
+ * belongs to the consumer's `ClickAway`, which exposes it through a render
+ * callback — where a hook cannot be called.
+ *
+ *     const menuTrigger = useMenuTrigger({id: props.id, ariaLabel: menu?.ariaLabel});
+ *     <ClickAway restoreFocusOnClose>
+ *       {({isOpen, onOpen, clickAway}) => (
+ *         <>
+ *           <Button {...props} {...menuTrigger.getTriggerProps({isOpen, onOpen})} />
+ *           {isOpen && (
+ *             <Menu
+ *               {...menu}
+ *               {...menuTrigger.menuProps}
+ *               enableA11y
+ *               onTabOut={clickAway}
+ *             />
+ *           )}
+ *         </>
+ *       )}
+ *     </ClickAway>
+ *
+ * `restoreFocusOnClose` is what returns focus to the trigger when the menu
+ * closes. Menu moves focus INTO the popup on open, so without it Escape, a
+ * selection or Tab leaves focus on `document.body` — the components in this
+ * package pass it alongside their own `enableA11y`.
+ */
+
+/**
+ * Generic in the trigger element so the returned handler matches whatever it is
+ * spread onto — inferred from the trigger's own `onKeyDown` where it has one.
+ */
+
+const useMenuTrigger = function () {
+  let {
+    enabled = true,
+    id,
+    menuId: consumerMenuId,
+    ariaLabel,
+    ariaLabelledBy
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const generatedMenuId = React.useId();
+  const generatedTriggerId = React.useId();
+  const menuId = consumerMenuId ?? generatedMenuId;
+  const triggerId = id ?? generatedTriggerId;
+  const initialFocusRef = React.useRef(null);
+  // The trigger exists before the popup does, which is the only point early
+  // enough to observe the keypress that opens it.
+  React.useEffect(() => {
+    if (enabled) {
+      (0, _hooks.startInteractionModalityTracking)();
+    }
+  }, [enabled]);
+  const getTriggerProps = _ref2 => {
+    let {
+      isOpen,
+      onOpen,
+      onKeyDown
+    } = _ref2;
+    return !enabled ?
+    // Nothing but the consumer's own handler, so spreading this changes
+    // nothing about the trigger. Compacted because these props are spread
+    // AFTER the consumer's: a key holding `undefined` would erase theirs.
+    compact({
+      onKeyDown
+    }) : {
+      id: triggerId,
+      'aria-haspopup': 'listbox',
+      'aria-expanded': isOpen,
+      // Only while the listbox is actually rendered: an IDREF that resolves to
+      // nothing is an invalid value, not an empty one.
+      'aria-controls': isOpen ? menuId : undefined,
+      onKeyDown: event => {
+        onKeyDown?.(event);
+        // Opening on an arrow key is the trigger's job precisely because the menu
+        // does not exist yet to handle it. Leave the key alone if the trigger's
+        // own handler already claimed it.
+        if (event.defaultPrevented || isOpen) {
+          return;
+        }
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+          event.preventDefault();
+          onOpen();
+        }
+      }
+    };
+  };
+  return {
+    getTriggerProps,
+    menuProps: !enabled ? {} : compact({
+      menuId,
+      // An explicit label suppresses the idref, so the two never compete.
+      ariaLabelledBy: ariaLabel ? undefined : ariaLabelledBy ?? triggerId,
+      ariaLabel,
+      initialFocusRef
+    })
+  };
+};
+
+/**
+ * Which of ARIA's two combobox patterns the trigger implements.
+ *
+ * - `select` — a read-only field standing in for a `<select>`. An option is
+ *   highlighted as soon as the list opens, Space selects it (the field has no
+ *   typing role), and Enter or Space opens the list in the first place.
+ * - `autocomplete` — an editable field that filters the list as you type.
+ *   Nothing is highlighted until the user arrows to it (APG calls this manual
+ *   selection: auto-highlighting would let Enter select something they never
+ *   chose), Space types a space, and only the arrow keys open the list.
+ */
+exports.useMenuTrigger = useMenuTrigger;
+/**
+ * Wires a COMBOBOX trigger — a text input — to the Menu it opens. Focus stays
+ * on the input and the highlight is virtual, reported through
+ * `aria-activedescendant`, because the input has to keep receiving the keys it
+ * filters with.
+ *
+ * Driving the highlight from outside Menu means owning the active option as
+ * state, and owning it means deriving the same option list, initial highlight
+ * and navigation list that Menu derives internally. Both combobox consumers had
+ * grown their own copies of all three; they come from Menu itself now.
+ *
+ * A menu that carries its own filter field (`menu.allowSearch`) inverts the
+ * model: navigation lives inside Menu, so the trigger stops driving it and
+ * hands over an `initialFocusRef` instead. Both shapes come out of this hook.
+ */
+const useComboboxMenuTrigger = _ref3 => {
+  let {
+    enabled = true,
+    pattern = 'select',
+    menu,
+    options,
+    canOpen,
+    menuRef,
+    isOpen,
+    onSelectOption,
+    onClose,
+    focusTrigger,
+    triggerAriaLabelledBy,
+    triggerAriaLabel,
+    defaultAriaLabel = 'Options'
+  } = _ref3;
+  const generatedMenuId = React.useId();
+  // The consumer's own id wins: it is what their `aria-controls` elsewhere, or
+  // their tests, already point at.
+  const menuId = menu?.menuId ?? generatedMenuId;
+  // See the note in useMenuTrigger.
+  React.useEffect(() => {
+    if (enabled) {
+      (0, _hooks.startInteractionModalityTracking)();
+    }
+  }, [enabled]);
+  const initialFocusRef = React.useRef(null);
+  const [activeOptionKey, setActiveOptionKey] = React.useState(null);
+  const isAutocomplete = pattern === 'autocomplete';
+
+  // A searchable menu drives navigation internally from its own filter field; a
+  // select-only menu is driven by this trigger instead, with focus never
+  // entering the listbox. An autocomplete trigger IS the filter field, so it
+  // always drives navigation itself.
+  const usesExternalNav = isAutocomplete || !menu?.allowSearch;
+
+  /** The options the keyboard navigates, whatever supplied them. */
+  const optionSource = React.useMemo(() => options ?? (menu ? (0, _Menu.getFlatOptions)(menu) : []), [options, menu]);
+
+  /*
+   * `listbox` is an accessible-name-required role, so the popup must be named.
+   * Best name first:
+   *   1. what the consumer said (`menu.ariaLabelledBy` / `menu.ariaLabel`),
+   *   2. whatever already labels the trigger — a field label is the most useful
+   *      name there is,
+   *   3. a literal fallback. Deliberately NOT the placeholder: echoing
+   *      "Select..." names the list after an instruction, not its contents.
+   * An explicit label suppresses the idref, since a listbox drops `aria-label`
+   * whenever `aria-labelledby` is present.
+   */
+  const menuAriaLabelledBy = menu?.ariaLabelledBy ?? (menu?.ariaLabel ? undefined : triggerAriaLabelledBy);
+  const menuAriaLabel = menu?.ariaLabel ?? (menuAriaLabelledBy ? undefined : triggerAriaLabel ?? defaultAriaLabel);
+  const selectByKey = key => {
+    const option = optionSource.find(opt => opt.key === key);
+    if (option) {
+      onSelectOption(option);
+    }
+  };
+
+  /*
+   * A virtualized menu keeps only a window of rows in the DOM, so the keyboard
+   * hook would otherwise clamp End / PageDown / wrap-around / type-ahead to that
+   * window. Hand it the real option list in that case — whichever source it came
+   * from, and flat or grouped alike, since Menu handles both — and Menu
+   * scrolls the active row into view. Plain menus stay on the DOM-driven path,
+   * which keeps grouped layouts and `resolveLabel` type-ahead working off the
+   * rendered text.
+   */
+  const resolveLabel = menu?.resolveLabel;
+  const navigationOptions = React.useMemo(() => {
+    // A wholly disabled menu has no navigable options at all.
+    if (!menu?.virtualization?.enable || menu.menuDisabled) {
+      return undefined;
+    }
+    return optionSource.filter(option => !option.disabled).map(option => {
+      // Type-ahead must match the text the user can actually read.
+      const resolved = resolveLabel?.(option);
+      return {
+        key: option.key,
+        label: typeof resolved === 'string' ? resolved : option.label ?? ''
+      };
+    });
+  }, [menu?.virtualization?.enable, menu?.menuDisabled, resolveLabel, optionSource]);
+  const {
+    onKeyDown: onComboboxKeyDown
+  } = (0, _useMenuKeyboardNavigation.useMenuKeyboardNavigation)({
+    containerRef: menuRef,
+    enabled: enabled && isOpen && usesExternalNav && !menu?.menuDisabled,
+    // An editable trigger keeps printable keys for filtering; a read-only one
+    // spends them on type-ahead.
+    mode: isAutocomplete ? 'search' : 'activedescendant',
+    activeOptionKey,
+    onSelectKey: selectByKey,
+    setActiveOptionKey,
+    options: navigationOptions
+  });
+
+  /*
+   * Seed the highlight when the menu opens, drop it when it closes, and keep it
+   * valid while the option set changes underneath it (async or cascading
+   * options). Menu skips its own re-validation under `externalKeyboardNav`, so
+   * the trigger owns it — without this, `aria-activedescendant` could point at
+   * the id of an option that no longer exists. A layout effect, so the id is in
+   * place before the browser paints the open menu.
+   */
+  const selectedKeys = menu?.selectedKeys;
+  const selectedOption = menu?.selectedOption;
+  React.useLayoutEffect(() => {
+    // A closed list has no active option, whichever pattern this is.
+    if (!isOpen) {
+      setActiveOptionKey(null);
+      return;
+    }
+    const enabledKeys = optionSource.filter(option => !option.disabled).map(option => option.key);
+    const surviving = prev => prev && enabledKeys.includes(prev) ? prev : null;
+    if (isAutocomplete) {
+      // Manual selection: never highlight anything on the user's behalf, only
+      // drop a highlight that the filtering has removed under them.
+      setActiveOptionKey(surviving);
+      return;
+    }
+    if (!usesExternalNav) {
+      setActiveOptionKey(null);
+      return;
+    }
+    setActiveOptionKey(prev => surviving(prev) ?? (0, _Menu.getInitialActiveOptionKey)({
+      options: optionSource,
+      selectedKeys,
+      selectedOption
+    }));
+  }, [isAutocomplete, isOpen, usesExternalNav, optionSource, selectedKeys, selectedOption]);
+  const getTriggerProps = _ref4 => {
+    let {
+      isOpen: triggerIsOpen,
+      isExpanded,
+      onOpen,
+      onKeyDown
+    } = _ref4;
+    const expanded = isExpanded ?? triggerIsOpen;
+    if (!enabled) {
+      // Only the consumer's own handler, so spreading this is a no-op — and
+      // compacted, since a key holding `undefined` spread after the consumer's
+      // props would erase theirs.
+      return compact({
+        onKeyDown
+      });
+    }
+    return {
+      // The one combobox for both shapes: the menu's own filter field is a
+      // `searchbox`, so nothing competes for the listbox. Keeping the role
+      // unconditional also keeps `aria-expanded` valid — it is not an allowed
+      // attribute on a plain textbox.
+      role: 'combobox',
+      'aria-haspopup': 'listbox',
+      'aria-expanded': expanded,
+      // Only reference the listbox while it is actually rendered. The hook always
+      // hands `menuId` to Menu, so the element exists whenever `expanded` says so,
+      // whichever option source was supplied.
+      'aria-controls': expanded ? menuId : undefined,
+      // 'list' whenever typing narrows the list: the autocomplete pattern, or a
+      // menu carrying its own filter field.
+      'aria-autocomplete': isAutocomplete || !usesExternalNav ? 'list' : 'none',
+      'aria-activedescendant': expanded && usesExternalNav && activeOptionKey ? (0, _menuOptionId.menuOptionId)(menuId, activeOptionKey) : undefined,
+      onKeyDown: event => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) {
+          return;
+        }
+        if (!triggerIsOpen) {
+          // Closed: the arrow keys open the list, and a read-only trigger takes
+          // Enter and Space for it too — a typed space belongs to an editable
+          // one. This is the part no Menu prop can supply: the menu does not
+          // exist yet.
+          const opensList = event.key === 'ArrowDown' || event.key === 'ArrowUp' || !isAutocomplete && (event.key === 'Enter' || event.key === ' ');
+          if (opensList && (canOpen?.() ?? true)) {
+            event.preventDefault();
+            onOpen();
+          }
+          return;
+        }
+        // Open + searchable: focus is in the menu's own filter field, which owns
+        // navigation — nothing to do here.
+        if (!usesExternalNav) {
+          return;
+        }
+        // Tab moves into the menu's footer, Shift+Tab into its header, when that
+        // region has focusable controls. With none there, the listbox closes
+        // (APG: the popup closes when the combobox loses focus) and focus moves
+        // on.
+        if (event.key === 'Tab') {
+          if ((0, _useMenuKeyboardNavigation.moveFocusToMenuChrome)(menuRef.current, event.shiftKey)) {
+            event.preventDefault();
+          } else {
+            onClose();
+          }
+          return;
+        }
+        // Space selects the active option — only where it has no typing role.
+        if (!isAutocomplete && event.key === ' ') {
+          event.preventDefault();
+          if (activeOptionKey) {
+            selectByKey(activeOptionKey);
+          }
+          return;
+        }
+        // Arrows / Home / End / Enter / type-ahead.
+        onComboboxKeyDown(event);
+      }
+    };
+  };
+  return {
+    getTriggerProps,
+    menuProps: !enabled ? {} : compact({
+      menuId,
+      ariaLabelledBy: menuAriaLabelledBy,
+      ariaLabel: menuAriaLabel,
+      externalKeyboardNav: usesExternalNav,
+      activeOptionKey: usesExternalNav ? activeOptionKey : undefined,
+      onActiveOptionKeyChange: usesExternalNav ? setActiveOptionKey : undefined,
+      onReturnFocusToInput: usesExternalNav ? focusTrigger : undefined,
+      initialFocusRef: usesExternalNav ? undefined : initialFocusRef
+    }),
+    activeOptionKey
+  };
+};
+exports.useComboboxMenuTrigger = useComboboxMenuTrigger;

package/lib/components/OptionButton/OptionButton.d.ts

@@ -27,6 +27,22 @@ export interface OptionButtonProps extends Omit<ButtonProps, 'menu' | 'anchorPos
     tooltip?: OptionButtonTooltipProps;
     classNames?: ClassNames;
     clickAwayRef?: React.RefObject<ClickAwayRefType | null>;
+    /**
+     * Opt in to the accessibility behavior. Forwarded to the `ButtonDropdown`
+     * this renders, which owns the trigger and the menu.
+     *
+     * Off by default, and off is this component exactly as it behaved before any
+     * of it existed.
+     */
+    enableA11y?: boolean;
+    /**
+     * Accessible name for the options button — the icon-only half of the split
+     * button, which has no text of its own. It also names the listbox that button
+     * opens, so without it the listbox ends up unnamed. Override it for another
+     * language, as `TabList` does with `overflowTabLabel`. A consumer's own
+     * `ariaLabel` still wins.
+     */
+    optionsLabel?: string;
     testId?: string;
 }
 export declare const OptionButton: Flow.AbstractComponent<OptionButtonProps, HTMLDivElement>;

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

@@ -1 +1 @@
-{"version":3,"file":"OptionButton.d.ts","sourceRoot":"","sources":["../../../src/components/OptionButton/OptionButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,4BAA4B,CAAC;AAGrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAG3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,+BAA+B,CAAC;AAG9D,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAM7D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED,MAAM,WAAW,iBACf,SAAQ,IAAI,CACV,WAAW,EACT,MAAM,GACN,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,aAAa,GACb,SAAS,GACT,YAAY,GACZ,cAAc,CACjB;IACD,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,aAAa,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IAC3D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,iBAAiB,CAC/C,iBAAiB,EACjB,cAAc,CA6Gf,CAAC"}
+{"version":3,"file":"OptionButton.d.ts","sourceRoot":"","sources":["../../../src/components/OptionButton/OptionButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,4BAA4B,CAAC;AAGrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAG3D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,+BAA+B,CAAC;AAG9D,OAAO,KAAK,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAM7D,KAAK,UAAU,GAAG,QAAQ,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED,MAAM,WAAW,iBACf,SAAQ,IAAI,CACV,WAAW,EACT,MAAM,GACN,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,aAAa,GACb,SAAS,GACT,YAAY,GACZ,cAAc,CACjB;IACD,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,aAAa,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IAC3D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,iBAAiB,CAC/C,iBAAiB,EACjB,cAAc,CAgHf,CAAC"}

package/lib/components/OptionButton/OptionButton.js

@@ -36,6 +36,8 @@ const OptionButton = exports.OptionButton = /*#__PURE__*/React.forwardRef((_ref,
     tooltip,
     classNames,
     clickAwayRef,
+    enableA11y = false,
+    optionsLabel = 'More options',
     testId
   } = _ref;
   const [iconName, setIconName] = React.useState('chevron-down');
@@ -83,7 +85,7 @@ const OptionButton = exports.OptionButton = /*#__PURE__*/React.forwardRef((_ref,
       })
     }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_ButtonDropdown.ButtonDropdown, {
       anchorPosition: anchorPosition,
-      ariaLabel: ariaLabel,
+      ariaLabel: ariaLabel ?? (enableA11y ? optionsLabel : undefined),
       iconLeftName: iconName,
       tooltip: tooltip?.optionsButton,
       classNames: {
@@ -107,6 +109,7 @@ const OptionButton = exports.OptionButton = /*#__PURE__*/React.forwardRef((_ref,
       onOptionSelect: onOptionSelect,
       size: size,
       clickAwayRef: clickAwayRef,
+      enableA11y: enableA11y,
       testId: (0, _qa.generateTestId)({
         base: testId,
         slot: 'dropdown'