@spaced-out/ui-design-system 0.6.34 → 0.6.35-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.
+ */
+.menuCardTopPaddingZero,
+.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;
 }
@@ -165,25 +198,58 @@
   color: colorTextTertiary;
 }
 
+/*
+ * Background for the highlighted option (the "cursor"). There is only ever one —
+ * the Menu keeps it in sync across pointer and keyboard. `.active` covers the
+ * combobox active-descendant case (focus stays on the input); :hover covers a
+ * plain mouse-over.
+ */
 .option:hover,
-.option:active {
-  background: colorBackgroundSecondary;
+.option:active,
+.option.active {
+  outline: none;
   color: colorTextPrimary;
+  background: colorBackgroundSecondary;
 }
 
-.option:hover .optionTextSecondaryLabel {
-  color: colorTextSecondary;
-}
-
-.option:active .optionTextSecondaryLabel {
+.option:hover .optionTextSecondaryLabel,
+.option:active .optionTextSecondaryLabel,
+.option.active .optionTextSecondaryLabel,
+.option:focus .optionTextSecondaryLabel {
   color: colorTextSecondary;
 }
 
-.option:focus {
+/*
+ * 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.activeRing,
 .option:focus-visible {
   outline: none;
   color: colorTextPrimary;
@@ -191,20 +257,34 @@
     borderWidthTertiary colorFocusSecondary;
 }
 
-.option:focus-within {
-  outline: none;
-  color: colorTextPrimary;
-  /* box-shadow: none; */
-}
-
-.option.selected {
-  background: colorFillSecondary;
-  outline: none;
-  color: colorTextPrimary;
-}
-
-.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) {
+  .option:hover,
+  .option.active {
+    outline: borderWidthTertiary solid Highlight;
+    outline-offset: calc(-1 * borderWidthTertiary);
+  }
+
+  .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.
+   */
+  .option.activeRing,
+  .option:focus-visible {
+    outline: borderWidthTertiary dashed Highlight;
+    outline-offset: calc(-1 * borderWidthTertiary);
+  }
 }
 
 .disabled {
@@ -244,6 +324,41 @@
   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;
+}
+
+/*
+ * 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,11 +375,16 @@
   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;
+  position: relative;
+  flex: 0 0 auto;
   background-color: colorBackgroundTertiary;
   padding: spaceXSmall spaceNone;
-  top: spaceNone;
   margin-bottom: spaceXSmall;
   z-index: calc(elevationCard/4);
   min-height: size50;
@@ -280,11 +400,12 @@
   border-bottom: borderWidthPrimary solid colorBorderPrimary;
 }
 
+/* As `.menuHeader`, pinned by sitting outside the options scroll container. */
 .menuFooter {
-  position: sticky;
+  position: relative;
+  flex: 0 0 auto;
   background-color: colorBackgroundTertiary;
   padding: spaceXSmall spaceNone;
-  bottom: spaceNone;
   margin-top: spaceXSmall;
   min-height: size50;
   max-height: size50;

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

@@ -1,10 +1,31 @@
 import * as React from 'react';
 import type { CSSProperties } from 'react';
 import type { BaseMenuProps, MenuOption } from '../../components/Menu/Menu';
-export interface MenuOptionProps extends Omit<BaseMenuProps, 'option' | 'isLastItem' | 'style'> {
+export interface MenuOptionProps extends Omit<BaseMenuProps, 'option' | 'style'> {
     option: MenuOption;
-    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;
     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,OAAO,CAAC;IAC/C,MAAM,EAAE,UAAU,CAAC;IACnB,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,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,GAAI,OAAO,eAAe,sBAkQtD,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");
@@ -18,7 +19,6 @@ 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); }
 const MenuOptionButton = props => {
-  const lastMenuItemRef = React.useRef(null);
   const {
     option,
     size = 'medium',
@@ -28,13 +28,20 @@ const MenuOptionButton = props => {
     classNames,
     optionsVariant = 'normal',
     selectedKeys,
-    isLastItem,
-    onTabOut,
     resolveLabel,
     resolveSecondaryLabel,
     style,
     showLabelTooltip,
     allowWrap = false,
+    allowSearch = false,
+    menuId,
+    activeOptionKey,
+    externalKeyboardNav = false,
+    setSize,
+    posInSet,
+    onPointerActivate,
+    pointerActiveKey,
+    suppressInitialHighlight = false,
     testId
   } = props;
   const {
@@ -62,24 +69,45 @@ 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 showHighlight = isActive && !suppressInitialHighlight;
+  // 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 isVirtualFocusMode = allowSearch || externalKeyboardNav;
+  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]);
-  React.useEffect(() => {
-    const handleKeyDown = event => {
-      if (event.key === 'Tab' && !event.shiftKey) {
-        // Tab pressed without shift key, calling tab out callback
-        onTabOut?.();
-      }
-    };
-    lastMenuItemRef.current?.addEventListener('keydown', handleKeyDown);
-    return () => {
-      lastMenuItemRef.current?.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [isLastItem]);
   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]: showHighlight,
+      // Focus ring, keyboard-driven highlights only.
+      [_MenuModule.default.activeRing]: showActiveRing,
       [_MenuModule.default.optionSmall]: buttonSize === 'small',
       [_MenuModule.default.optionMedium]: buttonSize === 'medium',
       [_MenuModule.default.disabled]: menuDisabled || disabled,
@@ -87,36 +115,57 @@ const MenuOptionButton = props => {
       [_MenuModule.default.withIconRight]: !!iconRight
     }, classNames?.option, optionClassNames?.wrapper),
     style: style,
-    disabled: menuDisabled || disabled,
+    disabled: isOptionDisabled,
+    role: "option",
+    "aria-selected": isOptionSelected,
+    "aria-disabled": isOptionDisabled || undefined,
+    "aria-setsize": setSize,
+    "aria-posinset": posInSet,
+    tabIndex: optionTabIndex,
+    id: optionId,
+    "data-menu-option-key": key,
     onClick: e => onSelect && onSelect(option, e),
-    autoFocus: 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 (isOptionDisabled || isActive) {
+        return;
+      }
+      onPointerActivate?.(key, e.currentTarget, e.clientX, e.clientY);
+    },
     testId: (0, _qa.generateTestId)({
       base: optionTestId || testId,
       slot: 'option-button',
       index: key
     }),
-    ...(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__*/(0, _jsxRuntime.jsx)("span", {
+      "aria-hidden": "true",
+      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)("span", {
+      "aria-hidden": "true",
+      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,

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];
+    }
+  });
 });

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

@@ -0,0 +1,12 @@
+/**
+ * The DOM id of an option row — the one thing the row itself, the listbox's
+ * `aria-activedescendant`, and a combobox trigger's `aria-activedescendant`
+ * must all agree on, so it is built in exactly one place.
+ *
+ * Option keys are consumer data and may contain whitespace ("New York"), which
+ * an id can hold but an IDREF cannot: `aria-activedescendant="m-option-New
+ * York"` is a list of two references, neither of which resolves. Encoding the
+ * key keeps the id a single token.
+ */
+export declare const menuOptionId: (menuId: string, key: string) => string;
+//# sourceMappingURL=menuOptionId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"menuOptionId.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/menuOptionId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,KAAK,MAAM,KAAG,MACZ,CAAC"}

package/lib/components/Menu/menuOptionId.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.menuOptionId = void 0;
+/**
+ * The DOM id of an option row — the one thing the row itself, the listbox's
+ * `aria-activedescendant`, and a combobox trigger's `aria-activedescendant`
+ * must all agree on, so it is built in exactly one place.
+ *
+ * Option keys are consumer data and may contain whitespace ("New York"), which
+ * an id can hold but an IDREF cannot: `aria-activedescendant="m-option-New
+ * York"` is a list of two references, neither of which resolves. Encoding the
+ * key keeps the id a single token.
+ */
+const menuOptionId = (menuId, key) => `${menuId}-option-${encodeURIComponent(key)}`;
+exports.menuOptionId = menuOptionId;

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

@@ -0,0 +1,93 @@
+import * as React from 'react';
+/**
+ * Keyboard navigation for the Menu option list. Three interaction models,
+ * selected via `mode`:
+ *
+ * 1. `'roving'` — ROVING FOCUS (default; menu-button popups). Options are native
+ *    <button>s, so ArrowUp/ArrowDown move real DOM focus between the enabled
+ *    options and Space/Enter activate the focused option natively. Home/End jump
+ *    to the first/last option, PageUp/PageDown move by a page, and typing a
+ *    printable character jumps to the next matching label (type-ahead).
+ *
+ * 2. `'activedescendant'` — SELECT-ONLY COMBOBOX. DOM focus stays on the
+ *    combobox input; the "active" option is a virtual highlight reported via
+ *    `setActiveOptionKey` (surfaced as the input's aria-activedescendant) and
+ *    NEVER takes real focus. Arrows/Home/End/PageUp/PageDown move the highlight,
+ *    printable characters type-ahead, and Enter selects the active option.
+ *
+ * 3. `'search'` — EDITABLE COMBOBOX. Like `'activedescendant'`, but the input is
+ *    a free-text field: printable keys, Left/Right and Home/End are left to the
+ *    input for text editing (no type-ahead). Arrows/PageUp/PageDown move the
+ *    highlight and Enter selects.
+ *
+ * Navigation wraps around at the ends. Options are discovered from the DOM
+ * (`[data-menu-option-key]`) so it always matches what is rendered after search
+ * filtering / grouping.
+ *
+ * Tab / Shift+Tab keep focus moving through the menu's own focus zones in DOM
+ * order — header → search → options → footer — and only close the menu (via
+ * `onTabOut`) when focus would leave the menu entirely (Tab past the last
+ * focusable, Shift+Tab before the first). This keeps focus from silently
+ * dropping to <body> when the popup renders in a portal with nothing after it.
+ */
+export type MenuNavigationMode = 'roving' | 'activedescendant' | 'search';
+/** One navigable option, for menus whose option DOM is windowed. */
+export interface MenuNavigationOption {
+    key: string;
+    label: string;
+}
+interface UseMenuKeyboardNavigationArgs {
+    /** Ref to the element that contains the option buttons (the Menu listbox). */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Disable all handling (e.g. when the menu is disabled or closed). */
+    enabled?: boolean;
+    /** Interaction model — see the file header. Defaults to `'roving'`. */
+    mode?: MenuNavigationMode;
+    /** Key of the option currently highlighted (needed for the non-roving modes). */
+    activeOptionKey?: string | null;
+    /** Select the option with the given key (used for Enter in the combobox modes). */
+    onSelectKey?: (key: string) => void;
+    /** Report the option key that owns the roving tab stop / active descendant. */
+    setActiveOptionKey: (key: string | null) => void;
+    /** Close the menu when Tab / Shift+Tab would move focus out of it. */
+    onTabOut?: () => void;
+    /**
+     * Combobox menus only: return focus to the trigger input (keeping the menu
+     * open) when Tab / Shift+Tab moves off a header/footer control back toward the
+     * input — which sits OUTSIDE the menu DOM, so the input is the logical centre
+     * of the tab order (header ← input → footer), not an edge. When omitted (the
+     * roving menus) the input lives inside the menu, so the simple boundary close
+     * applies instead.
+     */
+    onReturnFocusToInput?: () => void;
+    /**
+     * Enabled options in render order. Supply this when the option DOM is WINDOWED
+     * (react-window virtualization): only a slice of the rows exists at any moment,
+     * so DOM discovery would confine Home/End, PageUp/PageDown, wrap-around and
+     * type-ahead to that slice — e.g. End on a 100-page Pagination would stop at
+     * page 10. When supplied, all index maths resolve against this list and the
+     * consumer is responsible for scrolling the active option into view (Menu does
+     * this from `activeOptionKey`). Omit it for plain menus: the DOM is then the
+     * source of truth, which keeps grouped/compose layouts and `resolveLabel`
+     * type-ahead working off the text actually rendered.
+     */
+    options?: MenuNavigationOption[];
+}
+/**
+ * Focusable controls inside the menu's sticky header / footer region, in DOM
+ * order. Used by combobox triggers (Dropdown / Typeahead) so Tab / Shift+Tab can
+ * move focus into the footer / header instead of closing the menu when one
+ * holds focusable controls (e.g. Cancel / Save buttons).
+ */
+export declare const getMenuRegionFocusables: (menu: HTMLElement | null, region: "header" | "footer") => HTMLElement[];
+/**
+ * Move focus into the menu's footer (Tab) or header (Shift+Tab) edge if that
+ * region has focusable controls. Returns true when it moved focus, so a combobox
+ * trigger can close the menu only when there was no chrome to land on.
+ */
+export declare const moveFocusToMenuChrome: (menu: HTMLElement | null, shiftKey: boolean) => boolean;
+export declare const useMenuKeyboardNavigation: ({ containerRef, enabled, mode, activeOptionKey, onSelectKey, setActiveOptionKey, onTabOut, onReturnFocusToInput, options, }: UseMenuKeyboardNavigationArgs) => {
+    onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
+};
+export {};
+//# sourceMappingURL=useMenuKeyboardNavigation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMenuKeyboardNavigation.d.ts","sourceRoot":"","sources":["../../../src/components/Menu/useMenuKeyboardNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAE1E,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAaD,UAAU,6BAA6B;IACrC,8EAA8E;IAC9E,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAClD,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mFAAmF;IACnF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+EAA+E;IAC/E,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACjD,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAkDD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,WAAW,GAAG,IAAI,EACxB,QAAQ,QAAQ,GAAG,QAAQ,KAC1B,WAAW,EAUb,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,WAAW,GAAG,IAAI,EACxB,UAAU,OAAO,KAChB,OAYF,CAAC;AASF,eAAO,MAAM,yBAAyB,GAAI,6HAUvC,6BAA6B,KAAG;IACjC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CAiY9D,CAAC"}