npm - @spaced-out/ui-design-system - Versions diffs - 0.6.34 → 0.6.35-beta.0 - Mend

@spaced-out/ui-design-system 0.6.34 → 0.6.35-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/.cspell/custom-words.txt +9 -0
package/CHANGELOG.md +7 -0
package/lib/components/Menu/Menu.d.ts +71 -0
package/lib/components/Menu/Menu.d.ts.map +1 -1
package/lib/components/Menu/Menu.js +1028 -185
package/lib/components/Menu/Menu.module.css +148 -27
package/lib/components/Menu/MenuOptionButton.d.ts +23 -2
package/lib/components/Menu/MenuOptionButton.d.ts.map +1 -1
package/lib/components/Menu/MenuOptionButton.js +87 -38
package/lib/components/Menu/index.d.ts +2 -0
package/lib/components/Menu/index.d.ts.map +1 -1
package/lib/components/Menu/index.js +22 -0
package/lib/components/Menu/menuOptionId.d.ts +12 -0
package/lib/components/Menu/menuOptionId.d.ts.map +1 -0
package/lib/components/Menu/menuOptionId.js +18 -0
package/lib/components/Menu/useMenuKeyboardNavigation.d.ts +93 -0
package/lib/components/Menu/useMenuKeyboardNavigation.d.ts.map +1 -0
package/lib/components/Menu/useMenuKeyboardNavigation.js +471 -0
package/lib/components/Menu/useMenuTrigger.d.ts +183 -0
package/lib/components/Menu/useMenuTrigger.d.ts.map +1 -0
package/lib/components/Menu/useMenuTrigger.js +347 -0
package/lib/hooks/index.d.ts +1 -0
package/lib/hooks/index.d.ts.map +1 -1
package/lib/hooks/index.js +11 -0
package/lib/hooks/useInteractionModality/index.d.ts +2 -0
package/lib/hooks/useInteractionModality/index.d.ts.map +1 -0
package/lib/hooks/useInteractionModality/index.js +16 -0
package/lib/hooks/useInteractionModality/useInteractionModality.d.ts +15 -0
package/lib/hooks/useInteractionModality/useInteractionModality.d.ts.map +1 -0
package/lib/hooks/useInteractionModality/useInteractionModality.js +103 -0
package/lib/utils/click-away/click-away.d.ts +3 -0
package/lib/utils/click-away/click-away.d.ts.map +1 -1
package/lib/utils/click-away/click-away.js +49 -0
package/mcp/package.json +1 -1
package/package.json +1 -1

package/lib/components/Menu/useMenuKeyboardNavigation.js ADDED Viewed

@@ -0,0 +1,471 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMenuKeyboardNavigation = exports.moveFocusToMenuChrome = exports.getMenuRegionFocusables = void 0;
+var React = _interopRequireWildcard(require("react"));
+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); }
+/**
+ * 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.
+ */
+/** One navigable option, for menus whose option DOM is windowed. */
+const OPTION_SELECTOR = '[data-menu-option-key]';
+// Elements that can hold a tab stop inside the menu (header/footer controls,
+// the search input, and the single roving option whose tabIndex is 0).
+const TABBABLE_SELECTOR = 'a[href], button, input, select, textarea, [tabindex]';
+const PAGE_SIZE = 10;
+const TYPEAHEAD_RESET_MS = 600;
+// Frames to wait for a windowed list to mount the row we just moved to before
+// giving up on placing real focus on it.
+const MOUNT_RETRY_FRAMES = 3;
+const getEnabledOptionEls = container => {
+  if (!container) {
+    return [];
+  }
+  return Array.from(container.querySelectorAll(OPTION_SELECTOR)).filter(el => el.getAttribute('aria-disabled') !== 'true' && !el.disabled);
+};
+// Enabled + visible. Used for elements we focus PROGRAMMATICALLY (footer/header
+// controls via moveFocusToMenuChrome), so the natural tab order (tabIndex) is
+// irrelevant — el.focus() works regardless. This matters because a combobox
+// menu's footer/header controls are observed to sit at tabIndex -1 while the
+// input holds focus, which a tabIndex-based filter (isTabbable) would wrongly
+// skip.
+const isFocusableControl = el => {
+  if (el.disabled) {
+    return false;
+  }
+  if (el.getAttribute('aria-disabled') === 'true') {
+    return false;
+  }
+  // Skip hidden elements (no layout box).
+  return el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0;
+};
+// As above, but also in the natural tab order right now (tabIndex >= 0). Used
+// for the roving boundary check, where focus actually rests on the element.
+const isTabbable = el => el.tabIndex >= 0 && isFocusableControl(el);
+/**
+ * Focusable elements inside the menu, in DOM order. With roving tabindex only
+ * the active option is tabbable (tabIndex 0); the others and the menu container
+ * are tabIndex -1, so they are excluded — leaving header/footer controls, the
+ * search input and the single active option.
+ */
+const getTabbables = container => Array.from(container.querySelectorAll(TABBABLE_SELECTOR)).filter(isTabbable);
+/**
+ * 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).
+ */
+const getMenuRegionFocusables = (menu, region) => {
+  const regionEl = menu?.querySelector(`[data-menu-region="${region}"]`);
+  if (!regionEl) {
+    return [];
+  }
+  return Array.from(regionEl.querySelectorAll(TABBABLE_SELECTOR)).filter(isFocusableControl);
+};
+/**
+ * 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.
+ */
+exports.getMenuRegionFocusables = getMenuRegionFocusables;
+const moveFocusToMenuChrome = (menu, shiftKey) => {
+  const focusables = getMenuRegionFocusables(menu, shiftKey ? 'header' : 'footer');
+  if (!focusables.length) {
+    return false;
+  }
+  // Tab → first control in the footer; Shift+Tab → last control in the header.
+  const target = shiftKey ? focusables[focusables.length - 1] : focusables[0];
+  target.focus();
+  return true;
+};
+exports.moveFocusToMenuChrome = moveFocusToMenuChrome;
+const isPrintableCharacter = event => event.key.length === 1 && event.key !== ' ' && !event.altKey && !event.ctrlKey && !event.metaKey;
+const useMenuKeyboardNavigation = _ref => {
+  let {
+    containerRef,
+    enabled = true,
+    mode = 'roving',
+    activeOptionKey,
+    onSelectKey,
+    setActiveOptionKey,
+    onTabOut,
+    onReturnFocusToInput,
+    options
+  } = _ref;
+  const typeahead = React.useRef({
+    query: '',
+    at: 0
+  });
+  const keyOf = el => el?.getAttribute('data-menu-option-key') ?? null;
+  // Move the highlight without moving focus (combobox / active-descendant model).
+  const highlightAt = (els, index) => {
+    const el = els[index];
+    if (!el) {
+      return;
+    }
+    el.scrollIntoView({
+      block: 'nearest'
+    });
+    setActiveOptionKey(keyOf(el));
+  };
+  // Move real DOM focus (roving model).
+  const focusAt = (els, index) => {
+    const el = els[index];
+    if (!el) {
+      return;
+    }
+    el.focus();
+    el.scrollIntoView({
+      block: 'nearest'
+    });
+    setActiveOptionKey(keyOf(el));
+  };
+  /** Type-ahead: jump to the next option whose label matches the typed text. */
+  const typeaheadTo = _ref2 => {
+    let {
+      count,
+      labelAt,
+      currentIndex,
+      char,
+      move
+    } = _ref2;
+    const now = Date.now();
+    const state = typeahead.current;
+    if (now - state.at > TYPEAHEAD_RESET_MS) {
+      state.query = '';
+    }
+    state.at = now;
+    state.query += char.toLowerCase();
+    const isRepeat = state.query.length > 1 && state.query.split('').every(c => c === state.query[0]);
+    const query = isRepeat ? state.query[0] : state.query;
+    // First keystroke or a repeated character advances past the current option
+    // so repeats cycle; accumulating distinct characters refines in place.
+    const offset = state.query.length === 1 || isRepeat ? 1 : 0;
+    const base = currentIndex < 0 ? -offset : currentIndex;
+    for (let i = 0; i < count; i++) {
+      const idx = (base + offset + i + count) % count;
+      if (labelAt(idx).startsWith(query)) {
+        move(idx);
+        return;
+      }
+    }
+  };
+  /**
+   * Search mode only: a printable key pressed while focus is somewhere in the
+   * menu OTHER than the search input (in practice the menu container — the
+   * fallback target when every option is disabled) redirects focus to the input
+   * and forwards the character, so typing still lands in the search box.
+   * Header/footer controls never reach here: onKeyDown's `[data-menu-region]`
+   * guard returns before the printable branch when focus is in that chrome.
+   */
+  const redirectPrintableToInput = event => {
+    const container = containerRef.current;
+    // Scope to the Menu's OWN search field via the marker it renders, not to a
+    // role — a consumer header/footer could contain an unrelated search input,
+    // and matching that would replay the user's keystrokes into the wrong field.
+    const searchInput = container?.querySelector('input[data-menu-search]');
+    if (!searchInput || typeof document === 'undefined' || document.activeElement === searchInput) {
+      return false;
+    }
+    event.preventDefault();
+    searchInput.focus();
+    searchInput.scrollIntoView({
+      block: 'nearest'
+    });
+    if (typeof window !== 'undefined') {
+      const nativeSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set;
+      if (nativeSetter) {
+        nativeSetter.call(searchInput, searchInput.value + event.key);
+        searchInput.dispatchEvent(new Event('input', {
+          bubbles: true
+        }));
+      }
+    }
+    return true;
+  };
+  /**
+   * Keep Tab / Shift+Tab inside the menu's focus zones (header → search →
+   * options → footer) and close the menu when focus would leave it entirely,
+   * instead of letting it fall to <body> below the portal. Internal moves
+   * (e.g. option → footer button) fall through to the browser default.
+   *
+   * Combobox menus (when `onReturnFocusToInput` is set) treat the trigger input
+   * — which lives OUTSIDE the menu DOM — as the logical centre of the tab order
+   * (header ← input → footer). So Tabbing toward the input (Shift+Tab off the
+   * footer's first control, or Tab off the header's last control) returns focus
+   * to the input with the menu open, and only the OUTER edges (Tab past the last
+   * footer control, Shift+Tab before the first header control) close the menu.
+   */
+  const handleTab = event => {
+    const container = containerRef.current;
+    if (!container || !onTabOut) {
+      return;
+    }
+    const focused = typeof document !== 'undefined' ? document.activeElement : null;
+    if (onReturnFocusToInput) {
+      const footers = getMenuRegionFocusables(container, 'footer');
+      const headers = getMenuRegionFocusables(container, 'header');
+      // Moving off a region back toward the input (Shift+Tab off the footer's
+      // first control, or Tab off the header's last control) returns focus to
+      // the input with the menu open — the input is the centre of the tab order.
+      const returningToInput = event.shiftKey ? footers.length > 0 && focused === footers[0] : headers.length > 0 && focused === headers[headers.length - 1];
+      if (returningToInput) {
+        event.preventDefault();
+        onReturnFocusToInput();
+        return;
+      }
+      // Anything else (footer/header outer edge, or focus not on a region edge)
+      // falls through to the boundary close logic below, so leaving the menu's
+      // outer edge closes it and never drops focus to <body>.
+    }
+    const tabbables = getTabbables(container);
+    const index = focused ? tabbables.indexOf(focused) : -1;
+    // Focus is inside the menu but not on one of its tab stops — in practice the
+    // menu container itself, which is the documented fallback target when every
+    // option is disabled or the option list is still empty. Treat it as sitting
+    // BEFORE the first tab stop: Tab moves forward into the menu's own stops
+    // (header / footer controls) instead of closing and leaving them unreachable,
+    // while Shift+Tab keeps moving backwards and falls through to the close
+    // below — jumping forward to the last control would reverse the user's
+    // direction of travel.
+    if (!event.shiftKey && index === -1 && tabbables.length) {
+      event.preventDefault();
+      tabbables[0].focus();
+      return;
+    }
+    const leavingMenu = event.shiftKey ? index <= 0 : index === tabbables.length - 1;
+    if (leavingMenu) {
+      // Stop the browser moving focus out (to <body>); close instead so the
+      // consumer's ClickAway returns focus to the trigger.
+      event.preventDefault();
+      onTabOut();
+    }
+  };
+  const onKeyDown = event => {
+    // Tab management runs even when option navigation is disabled (external
+    // combobox menus) so that, once focus is inside the footer / header, Tabbing
+    // off the edge still closes the menu instead of dropping focus to <body>.
+    if (event.key === 'Tab') {
+      handleTab(event);
+      return;
+    }
+    if (!enabled) {
+      return;
+    }
+    // While focus sits in the header/footer chrome (e.g. after Tabbing to a
+    // footer button), the menu's key handler must stay out of the way: arrows
+    // must not move or steal the option highlight, and printable keys must not
+    // be redirected into the search input. Let the focused control own its keys.
+    const focused = typeof document !== 'undefined' ? document.activeElement : null;
+    if (focused?.closest('[data-menu-region]')) {
+      return;
+    }
+    const els = getEnabledOptionEls(containerRef.current);
+    // A windowed list only has a slice of its rows in the DOM, so the caller
+    // supplies the real option list and it wins over what we can see.
+    const windowed = Boolean(options?.length);
+    const count = windowed ? options.length : els.length;
+    if (!count) {
+      return;
+    }
+    const movesFocus = mode === 'roving';
+    const hasSearchField = mode === 'search';
+    // Home/End (and Cmd+Arrow) belong to the caret only while the caret HAS
+    // focus. A searchable menu's virtualized listbox is itself a tab stop; once
+    // focus is on the list, those keys move the highlight like any listbox.
+    const caretOwnsKeys = hasSearchField && focused instanceof HTMLInputElement && focused.getAttribute('data-menu-search') !== null;
+    const labelAt = index => windowed ? (options[index].label ?? '').trim().toLowerCase() : (els[index].textContent ?? '').trim().toLowerCase();
+    const moveWindowed = index => {
+      const key = options[index].key;
+      // Publishing the key is the whole move: the consumer keys its virtual list
+      // off `activeOptionKey`, so this both scrolls the row into view and makes
+      // aria-activedescendant resolve once that row mounts. Deliberately no
+      // scrollIntoView here — that would fight the consumer's own scrolling.
+      setActiveOptionKey(key);
+      if (!movesFocus) {
+        return;
+      }
+      // Roving mode needs REAL focus, and the row may not be mounted yet when the
+      // list is windowed. Retry for a few frames until the consumer's scroll has
+      // rendered it, rather than assuming a single frame is enough.
+      let attempts = 0;
+      const focusRow = () => {
+        const el = containerRef.current?.querySelector(`[data-menu-option-key="${CSS.escape(key)}"]`);
+        if (el) {
+          el.focus({
+            preventScroll: true
+          });
+          return;
+        }
+        if (attempts < MOUNT_RETRY_FRAMES) {
+          attempts += 1;
+          requestAnimationFrame(focusRow);
+        }
+      };
+      focusRow();
+    };
+    const move = windowed ? moveWindowed : movesFocus ? index => focusAt(els, index) : index => highlightAt(els, index);
+    const currentIndex = windowed ? activeOptionKey ? options.findIndex(option => option.key === activeOptionKey) : -1 : movesFocus ? els.findIndex(el => typeof document !== 'undefined' && el === document.activeElement) : activeOptionKey ? els.map(el => keyOf(el)).indexOf(activeOptionKey) : -1;
+    const fromIndex = currentIndex < 0 ? 0 : currentIndex;
+    // Mac keyboards have no End / Home key — those are Fn+Right / Fn+Left — so
+    // Cmd+Down / Cmd+Up stand in for them, which is the "jump to the end"
+    // gesture macOS uses everywhere else. Subject to the same search-input
+    // exemption as End / Home below, because in a text field the platform binds
+    // them to the caret. Option and Control leave the key to the browser
+    // instead of being silently treated as an unmodified arrow.
+    const jumpsToEdge = event.metaKey && !event.altKey && !event.ctrlKey;
+    if ((event.altKey || event.ctrlKey) && !event.metaKey) {
+      return;
+    }
+    switch (event.key) {
+      case 'ArrowDown':
+        {
+          if (jumpsToEdge) {
+            if (!caretOwnsKeys) {
+              event.preventDefault();
+              move(count - 1);
+            }
+            break;
+          }
+          // Wraps from the last option back to the first.
+          event.preventDefault();
+          move(currentIndex < 0 ? 0 : (currentIndex + 1) % count);
+          break;
+        }
+      case 'ArrowUp':
+        {
+          if (jumpsToEdge) {
+            if (!caretOwnsKeys) {
+              event.preventDefault();
+              move(0);
+            }
+            break;
+          }
+          // Wraps from the first option back to the last.
+          event.preventDefault();
+          move(currentIndex < 0 ? count - 1 : (currentIndex - 1 + count) % count);
+          break;
+        }
+      case 'PageDown':
+        {
+          event.preventDefault();
+          move(Math.min(fromIndex + PAGE_SIZE, count - 1));
+          break;
+        }
+      case 'PageUp':
+        {
+          event.preventDefault();
+          move(Math.max(fromIndex - PAGE_SIZE, 0));
+          break;
+        }
+      case 'Home':
+        {
+          // Editable (search) input keeps Home/End for text-cursor movement.
+          if (!caretOwnsKeys) {
+            event.preventDefault();
+            move(0);
+          }
+          break;
+        }
+      case 'End':
+        {
+          if (!caretOwnsKeys) {
+            event.preventDefault();
+            move(count - 1);
+          }
+          break;
+        }
+      case ' ':
+        {
+          // In the text field Space types; on a roving option the <button> handles
+          // it natively. With focus on the list itself (the focusable listbox of a
+          // searchable menu) Space selects the active option, as it does for Enter.
+          if (!movesFocus && !caretOwnsKeys && activeOptionKey && onSelectKey) {
+            event.preventDefault();
+            onSelectKey(activeOptionKey);
+          }
+          break;
+        }
+      case 'Enter':
+        {
+          // Roving mode lets the focused <button> handle Enter natively. The
+          // combobox modes keep focus on the input, so select explicitly.
+          if (!movesFocus && activeOptionKey && onSelectKey) {
+            event.preventDefault();
+            onSelectKey(activeOptionKey);
+          }
+          break;
+        }
+      default:
+        {
+          // Space/Enter in roving mode are handled natively by the focused option.
+          if (!isPrintableCharacter(event)) {
+            break;
+          }
+          if (hasSearchField) {
+            // Editable input: let the character type into the field (it filters).
+            // Only step in when focus is somewhere else in the menu.
+            redirectPrintableToInput(event);
+          } else {
+            // Roving / select-only combobox: printable jumps to a matching label.
+            event.preventDefault();
+            typeaheadTo({
+              count,
+              labelAt,
+              currentIndex,
+              char: event.key,
+              move
+            });
+          }
+          break;
+        }
+    }
+  };
+  return {
+    onKeyDown
+  };
+};
+exports.useMenuKeyboardNavigation = useMenuKeyboardNavigation;

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

@@ -0,0 +1,183 @@
+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>
+ *       {({isOpen, onOpen, clickAway}) => (
+ *         <>
+ *           <Button {...props} {...menuTrigger.getTriggerProps({isOpen, onOpen})} />
+ *           {isOpen && <Menu {...menu} {...menuTrigger.menuProps} onTabOut={clickAway} />}
+ *         </>
+ *       )}
+ *     </ClickAway>
+ */
+export interface UseMenuTriggerArgs {
+    /**
+     * 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: ({ 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 {
+    /** 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: ({ 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 ADDED Viewed

@@ -0,0 +1 @@

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