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

package/lib/components/Menu/useMenuTrigger.js

@@ -0,0 +1,347 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useMenuTrigger = exports.useComboboxMenuTrigger = void 0;
+var React = _interopRequireWildcard(require("react"));
+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>
+ *       {({isOpen, onOpen, clickAway}) => (
+ *         <>
+ *           <Button {...props} {...menuTrigger.getTriggerProps({isOpen, onOpen})} />
+ *           {isOpen && <Menu {...menu} {...menuTrigger.menuProps} onTabOut={clickAway} />}
+ *         </>
+ *       )}
+ *     </ClickAway>
+ */
+
+/**
+ * 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 {
+    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);
+  const getTriggerProps = _ref2 => {
+    let {
+      isOpen,
+      onOpen,
+      onKeyDown
+    } = _ref2;
+    return {
+      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: 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 {
+    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;
+  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: 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;
+    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: 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/hooks/index.d.ts

@@ -4,6 +4,7 @@ export * from '../hooks/useDebounce';
 export * from '../hooks/useFileUpload';
 export * from '../hooks/useFilteredOptions';
 export * from '../hooks/useInfiniteScroll';
+export * from '../hooks/useInteractionModality';
 export * from '../hooks/useInputState';
 export * from '../hooks/useLockedBody';
 export * from '../hooks/useModal';

package/lib/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC;AACrD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC;AACrD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC"}

package/lib/hooks/index.js

@@ -69,6 +69,17 @@ Object.keys(_useInfiniteScroll).forEach(function (key) {
     }
   });
 });
+var _useInteractionModality = require("./useInteractionModality");
+Object.keys(_useInteractionModality).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useInteractionModality[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useInteractionModality[key];
+    }
+  });
+});
 var _useInputState = require("./useInputState");
 Object.keys(_useInputState).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/lib/hooks/useInteractionModality/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../../hooks/useInteractionModality/useInteractionModality';
+//# sourceMappingURL=index.d.ts.map

package/lib/hooks/useInteractionModality/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/useInteractionModality/index.ts"],"names":[],"mappings":"AAAA,cAAc,yDAAyD,CAAC"}

package/lib/hooks/useInteractionModality/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _useInteractionModality = require("./useInteractionModality");
+Object.keys(_useInteractionModality).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useInteractionModality[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useInteractionModality[key];
+    }
+  });
+});

package/lib/hooks/useInteractionModality/useInteractionModality.d.ts

@@ -0,0 +1,15 @@
+export type InteractionModality = 'keyboard' | 'pointer';
+/**
+ * How the user last interacted with the page, read imperatively.
+ *
+ * Use this when the answer is needed during render or in an effect rather than
+ * as reactive state — for example a popup deciding on mount whether it was opened
+ * by keyboard, where re-rendering on later modality changes would be wrong.
+ */
+export declare const getInteractionModality: () => InteractionModality;
+/**
+ * How the user last interacted with the page, as reactive state. Re-renders the
+ * caller when the user switches between keyboard and pointer.
+ */
+export declare const useInteractionModality: () => InteractionModality;
+//# sourceMappingURL=useInteractionModality.d.ts.map

package/lib/hooks/useInteractionModality/useInteractionModality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInteractionModality.d.ts","sourceRoot":"","sources":["../../../src/hooks/useInteractionModality/useInteractionModality.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAC;AA6FzD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAO,mBAGzC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,QAAO,mBAMzC,CAAC"}

package/lib/hooks/useInteractionModality/useInteractionModality.js

@@ -0,0 +1,103 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useInteractionModality = exports.getInteractionModality = void 0;
+var _react = require("react");
+/*
+ * Input modality is a property of the SESSION, not of any one component, so it
+ * lives in module scope rather than in state that each consumer would have to
+ * thread around. This is the same shape the platform itself uses: `:focus-visible`
+ * is implemented by the engine tracking the last interaction globally.
+ *
+ * Reach for this only when CSS cannot answer the question — `:focus-visible` is
+ * the right tool whenever the element you need to style is the one that was
+ * interacted with. This exists for the case where it is NOT: a popup deciding
+ * whether to show a keyboard cursor has to know how its TRIGGER was operated,
+ * and the trigger's own `:focus-visible` cannot be trusted for that, because
+ * browsers always match it on text inputs (typing is expected there) — so an
+ * input-triggered popup would always look keyboard-opened.
+ */
+let currentModality = 'pointer';
+let listening = false;
+const subscribers = new Set();
+
+// Keys that navigate even when chorded with a modifier — Cmd+Down is "jump to
+// the end" on macOS and the menus honour it as such.
+const NAVIGATION_KEYS = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown', 'Tab', 'Enter', ' ']);
+const MODIFIER_KEYS = new Set(['Shift', 'Meta', 'Alt', 'Control']);
+const set = modality => {
+  if (currentModality === modality) {
+    return;
+  }
+  currentModality = modality;
+  subscribers.forEach(notify => notify(modality));
+};
+const handleKeyDown = event => {
+  // A modifier pressed on its own — Shift held for a click, say — is not an
+  // interaction, and a chorded shortcut (Cmd+C, Ctrl+S) is a command rather than
+  // navigation. Neither should make the session look keyboard-driven. A chorded
+  // NAVIGATION key (Cmd+Down) does count: it moves the highlight.
+  if (MODIFIER_KEYS.has(event.key)) {
+    return;
+  }
+  if ((event.metaKey || event.altKey || event.ctrlKey) && !NAVIGATION_KEYS.has(event.key)) {
+    return;
+  }
+  set('keyboard');
+};
+const handlePointerDown = () => set('pointer');
+
+/*
+ * Capture phase, so the modality is recorded before any component handler reacts
+ * to the same event.
+ *
+ * Listening starts when this module is imported, NOT lazily on first read. It has
+ * to: the interesting question is usually "how was the thing that just mounted
+ * opened?", and the keypress that opened it happened before it existed. Attaching
+ * on first read would miss exactly that event and report the default instead.
+ */
+const subscribe = notify => {
+  // Session-scoped by design: the listeners live for the life of the page, so
+  // there is nothing to tear down.
+  if (typeof document !== 'undefined' && !listening) {
+    listening = true;
+    document.addEventListener('keydown', handleKeyDown, true);
+    document.addEventListener('pointerdown', handlePointerDown, true);
+  }
+  if (!notify) {
+    return () => undefined;
+  }
+  subscribers.add(notify);
+  return () => {
+    subscribers.delete(notify);
+  };
+};
+
+// Start listening at import time — see the note on `subscribe`.
+subscribe();
+
+/**
+ * How the user last interacted with the page, read imperatively.
+ *
+ * Use this when the answer is needed during render or in an effect rather than
+ * as reactive state — for example a popup deciding on mount whether it was opened
+ * by keyboard, where re-rendering on later modality changes would be wrong.
+ */
+const getInteractionModality = () => {
+  subscribe();
+  return currentModality;
+};
+
+/**
+ * How the user last interacted with the page, as reactive state. Re-renders the
+ * caller when the user switches between keyboard and pointer.
+ */
+exports.getInteractionModality = getInteractionModality;
+const useInteractionModality = () => {
+  const [modality, setModality] = (0, _react.useState)(() => getInteractionModality());
+  (0, _react.useEffect)(() => subscribe(setModality), []);
+  return modality;
+};
+exports.useInteractionModality = useInteractionModality;

package/lib/utils/click-away/click-away.d.ts

@@ -56,11 +56,14 @@ export declare class ClickAway<TTrigger extends HTMLElement = HTMLButtonElement,
     el: HTMLElement | null | undefined;
     boundaryRef: BoundaryRefType<TBoundary>;
     triggerRef: TriggerRefType<TTrigger>;
+    previouslyFocused: HTMLElement | null;
+    closedByOutsideClick: boolean;
     componentDidMount(): void;
     componentDidUpdate(_prevProps: Readonly<ClickAwayProps<TTrigger, TBoundary>>, prevState: Readonly<ClickAwayState>): void;
     componentWillUnmount(): void;
     render(): React.ReactNode;
     handleOpenClick: () => void;
+    restoreFocus: () => void;
     handleCloseClick: (evt: MouseEvent) => void;
     handleCloseOnEscapeKeypress: (evt?: KeyboardEvent) => void;
     forceClose: () => void;

package/lib/utils/click-away/click-away.d.ts.map

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

package/lib/utils/click-away/click-away.js

@@ -24,6 +24,17 @@ class ClickAway extends React.Component {
   el = null;
   boundaryRef = /*#__PURE__*/React.createRef();
   triggerRef = /*#__PURE__*/React.createRef();
+  // Element that had focus right before the popup opened. Restored on close so
+  // keyboard focus returns to the trigger (Escape, a selection, Tab past the
+  // popup's edge) — the job FloatingFocusManager's returnFocus does for the
+  // dropdown family until they move onto this.
+  previouslyFocused = null;
+  // Set by handleCloseClick for the close that follows. A click on the page is
+  // the user moving on: focus belongs wherever they clicked (or on <body>), and
+  // pulling it back onto the trigger would re-run the trigger's own focus
+  // handling — a Typeahead opens its menu on focus, so it would reopen the very
+  // popup the click dismissed.
+  closedByOutsideClick = false;
   componentDidMount() {
     if (this.el) {
       this.setState({
@@ -49,6 +60,12 @@ class ClickAway extends React.Component {
           capture: true
         });
         window.document.removeEventListener('keyup', this.handleCloseOnEscapeKeypress);
+        if (this.closedByOutsideClick) {
+          this.previouslyFocused = null;
+        } else {
+          this.restoreFocus();
+        }
+        this.closedByOutsideClick = false;
       }
     }
   }
@@ -92,11 +109,42 @@ class ClickAway extends React.Component {
     if (this.el) {
       pageBottom = this.pageBottom();
     }
+
+    // Capture the focused element before opening (still the trigger at this
+    // point, before the popup mounts and moves focus into itself) so it can be
+    // restored on close.
+    if (!this.state.isOpen && typeof window.document !== 'undefined') {
+      this.previouslyFocused = window.document.activeElement;
+    }
     this.setState({
       isOpen: !this.state.isOpen,
       pageBottom
     }, this.handleOnChange);
   };
+
+  // Return focus to the trigger when the popup closes — but only if focus was
+  // lost to the document body (the focused popup element was unmounted). If the
+  // user moved focus elsewhere (e.g. clicked another control), leave it there.
+  restoreFocus = () => {
+    const previous = this.previouslyFocused;
+    this.previouslyFocused = null;
+    if (typeof window.document === 'undefined') {
+      return;
+    }
+    const active = window.document.activeElement;
+    const focusLost = !active || active === window.document.body;
+    if (!focusLost) {
+      return;
+    }
+    // `previouslyFocused` is <body> whenever the opening click did not land on a
+    // natively focusable element — notably Safari and Firefox on macOS, which do
+    // not focus a <button> on click. Restoring it would be a no-op that strands
+    // focus at the top of the document, so fall back to the trigger itself.
+    const target = previous && previous !== window.document.body ? previous : this.triggerRef.current;
+    if (target && window.document.contains(target)) {
+      target.focus();
+    }
+  };
   handleCloseClick = evt => {
     if (evt.target instanceof Node && this.props.containsNestedFloatingPortals && this.boundaryRef.current?.parentElement && (this.boundaryRef.current.parentElement === evt.target || this.boundaryRef.current.parentElement.contains(evt.target))) {
       return;
@@ -107,6 +155,7 @@ class ClickAway extends React.Component {
     if (evt.target instanceof Node && this.triggerRef && (this.triggerRef.current === evt.target || this.triggerRef.current?.contains(evt.target))) {
       return;
     }
+    this.closedByOutsideClick = true;
     this.setState({
       isOpen: false
     }, this.handleOnChange);

package/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/genesis-mcp",
-  "version": "1.0.46",
+  "version": "1.0.47",
   "description": "MCP server for Genesis UI Design System - provides AI assistants with access to components, hooks, and design tokens",
   "type": "module",
   "main": "index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaced-out/ui-design-system",
-  "version": "0.6.34",
+  "version": "0.6.35-beta.0",
   "description": "Sense UI components library",
   "author": {
     "name": "Spaced Out"