@primer/components 0.0.0-2021111171525 → 0.0.0-20211111716

package/lib-esm/hooks/index.d.ts

@@ -0,0 +1,11 @@
+export { useOnOutsideClick } from './useOnOutsideClick';
+export type { UseOnOutsideClickSettings, TouchOrMouseEvent } from './useOnOutsideClick';
+export { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+export { useOnEscapePress } from './useOnEscapePress';
+export { useOpenAndCloseFocus } from './useOpenAndCloseFocus';
+export type { UseOpenAndCloseFocusSettings } from './useOpenAndCloseFocus';
+export type { AnchoredPositionHookSettings } from './useAnchoredPosition';
+export { useAnchoredPosition } from './useAnchoredPosition';
+export { useOverlay } from './useOverlay';
+export type { UseOverlaySettings } from './useOverlay';
+export { useRenderForcingRef } from './useRenderForcingRef';

package/lib-esm/hooks/index.js

@@ -0,0 +1,7 @@
+export { useOnOutsideClick } from './useOnOutsideClick';
+export { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+export { useOnEscapePress } from './useOnEscapePress';
+export { useOpenAndCloseFocus } from './useOpenAndCloseFocus';
+export { useAnchoredPosition } from './useAnchoredPosition';
+export { useOverlay } from './useOverlay';
+export { useRenderForcingRef } from './useRenderForcingRef';

package/lib-esm/hooks/useAnchoredPosition.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import { PositionSettings, AnchorPosition } from '../behaviors/anchoredPosition';
+export interface AnchoredPositionHookSettings extends Partial<PositionSettings> {
+    floatingElementRef?: React.RefObject<Element>;
+    anchorElementRef?: React.RefObject<Element>;
+}
+/**
+ * Calculates the top and left values for an absolutely-positioned floating element
+ * to be anchored to some anchor element. Returns refs for the floating element
+ * and the anchor element, along with the position.
+ * @param settings Settings for calculating the anchored position.
+ * @param dependencies Dependencies to determine when to re-calculate the position.
+ * @returns An object of {top: number, left: number} to absolutely-position the
+ * floating element.
+ */
+export declare function useAnchoredPosition(settings?: AnchoredPositionHookSettings, dependencies?: React.DependencyList): {
+    floatingElementRef: React.RefObject<Element>;
+    anchorElementRef: React.RefObject<Element>;
+    position: AnchorPosition | undefined;
+};

package/lib-esm/hooks/useAnchoredPosition.js

@@ -0,0 +1,35 @@
+import React from 'react';
+import { getAnchoredPosition } from '../behaviors/anchoredPosition';
+import { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+import { useResizeObserver } from './useResizeObserver';
+import useLayoutEffect from '../utils/useIsomorphicLayoutEffect';
+
+/**
+ * Calculates the top and left values for an absolutely-positioned floating element
+ * to be anchored to some anchor element. Returns refs for the floating element
+ * and the anchor element, along with the position.
+ * @param settings Settings for calculating the anchored position.
+ * @param dependencies Dependencies to determine when to re-calculate the position.
+ * @returns An object of {top: number, left: number} to absolutely-position the
+ * floating element.
+ */
+export function useAnchoredPosition(settings, dependencies = []) {
+  const floatingElementRef = useProvidedRefOrCreate(settings === null || settings === void 0 ? void 0 : settings.floatingElementRef);
+  const anchorElementRef = useProvidedRefOrCreate(settings === null || settings === void 0 ? void 0 : settings.anchorElementRef);
+  const [position, setPosition] = React.useState(undefined);
+  const updatePosition = React.useCallback(() => {
+    if (floatingElementRef.current instanceof Element && anchorElementRef.current instanceof Element) {
+      setPosition(getAnchoredPosition(floatingElementRef.current, anchorElementRef.current, settings));
+    } else {
+      setPosition(undefined);
+    }
+  }, // eslint-disable-next-line react-hooks/exhaustive-deps
+  [floatingElementRef, anchorElementRef, ...dependencies]);
+  useLayoutEffect(updatePosition, [updatePosition]);
+  useResizeObserver(updatePosition);
+  return {
+    floatingElementRef,
+    anchorElementRef,
+    position
+  };
+}

package/lib-esm/hooks/useCombinedRefs.d.ts

@@ -0,0 +1,10 @@
+import { ForwardedRef } from 'react';
+/**
+ * Creates a ref by combining multiple constituent refs. The ref returned by this hook
+ * should be passed as the ref for the element that needs to be shared. This is
+ * particularly useful when you are using `React.forwardRef` in your component but you
+ * also want to be able to access the local element. This is a small anti-pattern,
+ * though, as it breaks encapsulation.
+ * @param refs
+ */
+export declare function useCombinedRefs<T>(...refs: (ForwardedRef<T> | null | undefined)[]): import("react").MutableRefObject<T | null>;

package/lib-esm/hooks/useCombinedRefs.js

@@ -0,0 +1,37 @@
+import { useRef } from 'react';
+import useLayoutEffect from '../utils/useIsomorphicLayoutEffect';
+/**
+ * Creates a ref by combining multiple constituent refs. The ref returned by this hook
+ * should be passed as the ref for the element that needs to be shared. This is
+ * particularly useful when you are using `React.forwardRef` in your component but you
+ * also want to be able to access the local element. This is a small anti-pattern,
+ * though, as it breaks encapsulation.
+ * @param refs
+ */
+
+export function useCombinedRefs(...refs) {
+  const combinedRef = useRef(null);
+  useLayoutEffect(() => {
+    function setRefs(current = null) {
+      for (const ref of refs) {
+        if (!ref) {
+          return;
+        }
+
+        if (typeof ref === 'function') {
+          ref(current);
+        } else {
+          ref.current = current;
+        }
+      }
+    }
+
+    setRefs(combinedRef.current);
+    return () => {
+      // ensure the refs get updated on unmount
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      setRefs(combinedRef.current);
+    }; // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...refs, combinedRef.current]);
+  return combinedRef;
+}

package/lib-esm/hooks/useDetails.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="react" />
+declare type UseDetailsParameters = {
+    ref?: React.RefObject<HTMLElement>;
+    closeOnOutsideClick?: boolean;
+    defaultOpen?: boolean;
+    onClickOutside?: (event: MouseEvent) => void;
+};
+declare function useDetails({ ref, closeOnOutsideClick, defaultOpen, onClickOutside }: UseDetailsParameters): {
+    open: boolean | undefined;
+    setOpen: import("react").Dispatch<import("react").SetStateAction<boolean | undefined>>;
+    getDetailsProps: () => {
+        onToggle: (e: React.SyntheticEvent<HTMLElement, Event>) => void;
+        open: boolean | undefined;
+        ref: import("react").RefObject<HTMLElement>;
+    };
+};
+export default useDetails;

package/lib-esm/hooks/useDialog.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="react" />
+declare type UseDialogParameters = {
+    modalRef: React.RefObject<HTMLElement>;
+    overlayRef: React.RefObject<HTMLElement>;
+    isOpen?: boolean;
+    onDismiss?: () => void;
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    closeButtonRef?: React.RefObject<HTMLElement>;
+    returnFocusRef?: React.RefObject<HTMLElement>;
+};
+declare function useDialog({ modalRef, overlayRef, isOpen, onDismiss, initialFocusRef, closeButtonRef }: UseDialogParameters): {
+    getDialogProps: () => {
+        onKeyDown: (event: any) => void;
+    };
+};
+export default useDialog;

package/lib-esm/hooks/useDialog.js

@@ -1,21 +1,24 @@
 import { useCallback, useEffect } from 'react';
 
+const noop = () => null;
+
 function visible(el) {
   return !el.hidden && (!el.type || el.type !== 'hidden') && (el.offsetWidth > 0 || el.offsetHeight > 0);
 }
 
 function focusable(el) {
-  return el.tabIndex >= 0 && !el.disabled && visible(el);
+  const inputEl = el;
+  return inputEl.tabIndex >= 0 && !inputEl.disabled && visible(inputEl);
 }
 
 function useDialog({
   modalRef,
   overlayRef,
   isOpen,
-  onDismiss,
+  onDismiss = noop,
   initialFocusRef,
   closeButtonRef
-} = {}) {
+}) {
   const onClickOutside = useCallback(e => {
     if (modalRef.current && overlayRef.current && !modalRef.current.contains(e.target) && overlayRef.current.contains(e.target)) {
       onDismiss();
@@ -39,20 +42,32 @@ function useDialog({
     }
   }, [isOpen, initialFocusRef, closeButtonRef]);
   const getFocusableItem = useCallback((e, movement) => {
-    if (modalRef && modalRef.current) {
+    if (modalRef.current) {
       const items = Array.from(modalRef.current.querySelectorAll('*')).filter(focusable);
       if (items.length === 0) return;
       e.preventDefault();
       const focusedElement = document.activeElement;
+
+      if (!focusedElement) {
+        return;
+      }
+
       const index = items.indexOf(focusedElement);
       const offsetIndex = index + movement;
       const fallbackIndex = movement === 1 ? 0 : items.length - 1;
-      return items[offsetIndex] || items[fallbackIndex];
+      const focusableItem = items[offsetIndex] || items[fallbackIndex];
+      return focusableItem;
     }
   }, [modalRef]);
   const handleTab = useCallback(e => {
     const movement = e.shiftKey ? -1 : 1;
-    getFocusableItem(e, movement).focus();
+    const focusableItem = getFocusableItem(e, movement);
+
+    if (!focusableItem) {
+      return;
+    }
+
+    focusableItem.focus();
   }, [getFocusableItem]);
   const onKeyDown = useCallback(event => {
     switch (event.key) {

package/lib-esm/hooks/useFocusTrap.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export interface FocusTrapHookSettings {
+    /**
+     * Ref that will be used for the trapping container. If not provided, one will
+     * be created by this hook and returned.
+     */
+    containerRef?: React.RefObject<HTMLElement>;
+    /**
+     * Ref for the element that should receive focus when the focus trap is first enabled. If
+     * not provided, one will be created by this hook and returned. Its use is optional.
+     */
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    /**
+     * Set to true to disable the focus trap and clean up listeners. Can be re-enabled at
+     * any time.
+     */
+    disabled?: boolean;
+    /**
+     * If true, when this focus trap is cleaned up, restore focus to the element that had
+     * focus immediately before the focus trap was enabled. (Default: false)
+     */
+    restoreFocusOnCleanUp?: boolean;
+}
+/**
+ * Hook used to trap focus inside a container. Returns a ref that can be added to the container
+ * that should trap focus.
+ * @param settings {FocusTrapHookSettings}
+ */
+export declare function useFocusTrap(settings?: FocusTrapHookSettings, dependencies?: React.DependencyList): {
+    containerRef: React.RefObject<HTMLElement>;
+    initialFocusRef: React.RefObject<HTMLElement>;
+};

package/lib-esm/hooks/useFocusTrap.js

@@ -0,0 +1,54 @@
+import React from 'react';
+import { focusTrap } from '../behaviors/focusTrap';
+import { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+
+/**
+ * Hook used to trap focus inside a container. Returns a ref that can be added to the container
+ * that should trap focus.
+ * @param settings {FocusTrapHookSettings}
+ */
+export function useFocusTrap(settings, dependencies = []) {
+  const containerRef = useProvidedRefOrCreate(settings === null || settings === void 0 ? void 0 : settings.containerRef);
+  const initialFocusRef = useProvidedRefOrCreate(settings === null || settings === void 0 ? void 0 : settings.initialFocusRef);
+  const disabled = settings === null || settings === void 0 ? void 0 : settings.disabled;
+  const abortController = React.useRef();
+  const previousFocusedElement = React.useRef(null); // If we are enabling a focus trap and haven't already stored the previously focused element
+  // go ahead an do that so we can restore later when the trap is disabled.
+
+  if (!previousFocusedElement.current && !(settings !== null && settings !== void 0 && settings.disabled)) {
+    previousFocusedElement.current = document.activeElement;
+  } // This function removes the event listeners that enable the focus trap and restores focus
+  // to the previously-focused element (if necessary).
+
+
+  function disableTrap() {
+    var _abortController$curr;
+
+    (_abortController$curr = abortController.current) === null || _abortController$curr === void 0 ? void 0 : _abortController$curr.abort();
+
+    if (settings !== null && settings !== void 0 && settings.restoreFocusOnCleanUp && previousFocusedElement.current instanceof HTMLElement) {
+      previousFocusedElement.current.focus();
+      previousFocusedElement.current = null;
+    }
+  }
+
+  React.useEffect(() => {
+    if (containerRef.current instanceof HTMLElement) {
+      if (!disabled) {
+        var _initialFocusRef$curr;
+
+        abortController.current = focusTrap(containerRef.current, (_initialFocusRef$curr = initialFocusRef.current) !== null && _initialFocusRef$curr !== void 0 ? _initialFocusRef$curr : undefined);
+        return () => {
+          disableTrap();
+        };
+      } else {
+        disableTrap();
+      }
+    }
+  }, // eslint-disable-next-line react-hooks/exhaustive-deps
+  [containerRef, initialFocusRef, disabled, ...dependencies]);
+  return {
+    containerRef,
+    initialFocusRef
+  };
+}

package/lib-esm/hooks/useFocusZone.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { FocusZoneSettings } from '../behaviors/focusZone';
+export interface FocusZoneHookSettings extends Omit<FocusZoneSettings, 'activeDescendantControl'> {
+    /**
+     * Optional ref for the container that holds all elements participating in arrow key focus.
+     * If one is not passed, we will create one for you and return it from the hook.
+     */
+    containerRef?: React.RefObject<HTMLElement>;
+    /**
+     * If using the "active descendant" focus pattern, pass `true` or a ref to the controlling
+     * element. If a ref object is not passed, we will create one for you.
+     */
+    activeDescendantFocus?: boolean | React.RefObject<HTMLElement>;
+    /**
+     * Set to true to disable the focus zone and clean up listeners. Can be re-enabled at
+     * any time.
+     */
+    disabled?: boolean;
+}
+export declare function useFocusZone(settings?: FocusZoneHookSettings, dependencies?: React.DependencyList): {
+    containerRef: React.RefObject<HTMLElement>;
+    activeDescendantControlRef: React.RefObject<HTMLElement>;
+};

package/lib-esm/hooks/useFocusZone.js

@@ -0,0 +1,37 @@
+import React, { useEffect } from 'react';
+import { focusZone } from '../behaviors/focusZone';
+import { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+export function useFocusZone(settings = {}, dependencies = []) {
+  const containerRef = useProvidedRefOrCreate(settings.containerRef);
+  const useActiveDescendant = !!settings.activeDescendantFocus;
+  const passedActiveDescendantRef = typeof settings.activeDescendantFocus === 'boolean' || !settings.activeDescendantFocus ? undefined : settings.activeDescendantFocus;
+  const activeDescendantControlRef = useProvidedRefOrCreate(passedActiveDescendantRef);
+  const disabled = settings.disabled;
+  const abortController = React.useRef();
+  useEffect(() => {
+    if (containerRef.current instanceof HTMLElement && (!useActiveDescendant || activeDescendantControlRef.current instanceof HTMLElement)) {
+      if (!disabled) {
+        var _activeDescendantCont;
+
+        const vanillaSettings = { ...settings,
+          activeDescendantControl: (_activeDescendantCont = activeDescendantControlRef.current) !== null && _activeDescendantCont !== void 0 ? _activeDescendantCont : undefined
+        };
+        abortController.current = focusZone(containerRef.current, vanillaSettings);
+        return () => {
+          var _abortController$curr;
+
+          (_abortController$curr = abortController.current) === null || _abortController$curr === void 0 ? void 0 : _abortController$curr.abort();
+        };
+      } else {
+        var _abortController$curr2;
+
+        (_abortController$curr2 = abortController.current) === null || _abortController$curr2 === void 0 ? void 0 : _abortController$curr2.abort();
+      }
+    }
+  }, // eslint-disable-next-line react-hooks/exhaustive-deps
+  [disabled, ...dependencies]);
+  return {
+    containerRef,
+    activeDescendantControlRef
+  };
+}

package/lib-esm/hooks/useOnEscapePress.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="react" />
+/**
+ * Sets up a `keydown` listener on `window.document`. If
+ * 1) The pressed key is "Escape", and
+ * 2) The event has not had `.preventDefault()` called
+ * The given callback will be executed.
+ *
+ * Note: If multiple `useOnEscapePress` hooks are active simultaneously, the
+ * callbacks will occur in reverse order. In other words, if a parent component
+ * and a child component both call `useOnEscapePress`, when the user presses
+ * Escape, the child component's callback will execute, followed by the parent's
+ * callback. Each callback has the chance to call `.preventDefault()` on the
+ * event to prevent further callbacks.
+ *
+ * @param callback {(e: KeyboardEvent) => void} The callback that gets executed
+ * when the Escape key is pressed. The KeyboardEvent generated by the Escape
+ * keypress is passed as the only argument.
+ *
+ * @param callbackDependencies {React.DependencyList} The dependencies of the given
+ * `onEscape` callback for memoization. Omit this param if the callback is already
+ * memoized. See `React.useCallback` for more info on memoization.
+ */
+export declare const useOnEscapePress: (onEscape: (e: KeyboardEvent) => void, callbackDependencies?: import("react").DependencyList) => void;

package/lib-esm/hooks/useOnEscapePress.js

@@ -0,0 +1,59 @@
+import { useEffect, useCallback } from 'react';
+const handlers = [];
+/**
+ * Calls all handlers in reverse order
+ * @param event The KeyboardEvent generated by the Escape keydown.
+ */
+
+function handleEscape(event) {
+  if (event.key === 'Escape' && !event.defaultPrevented) {
+    for (let i = handlers.length - 1; i >= 0; --i) {
+      handlers[i](event); // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+
+      if (event.defaultPrevented) {
+        break;
+      }
+    }
+  }
+}
+/**
+ * Sets up a `keydown` listener on `window.document`. If
+ * 1) The pressed key is "Escape", and
+ * 2) The event has not had `.preventDefault()` called
+ * The given callback will be executed.
+ *
+ * Note: If multiple `useOnEscapePress` hooks are active simultaneously, the
+ * callbacks will occur in reverse order. In other words, if a parent component
+ * and a child component both call `useOnEscapePress`, when the user presses
+ * Escape, the child component's callback will execute, followed by the parent's
+ * callback. Each callback has the chance to call `.preventDefault()` on the
+ * event to prevent further callbacks.
+ *
+ * @param callback {(e: KeyboardEvent) => void} The callback that gets executed
+ * when the Escape key is pressed. The KeyboardEvent generated by the Escape
+ * keypress is passed as the only argument.
+ *
+ * @param callbackDependencies {React.DependencyList} The dependencies of the given
+ * `onEscape` callback for memoization. Omit this param if the callback is already
+ * memoized. See `React.useCallback` for more info on memoization.
+ */
+
+
+export const useOnEscapePress = (onEscape, callbackDependencies = [onEscape]) => {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const escapeCallback = useCallback(onEscape, callbackDependencies);
+  useEffect(() => {
+    if (handlers.length === 0) {
+      document.addEventListener('keydown', handleEscape);
+    }
+
+    handlers.push(escapeCallback);
+    return () => {
+      handlers.splice(handlers.findIndex(h => h === escapeCallback), 1);
+
+      if (handlers.length === 0) {
+        document.removeEventListener('keydown', handleEscape);
+      }
+    };
+  }, [escapeCallback]);
+};

package/lib-esm/hooks/useOnOutsideClick.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export declare type TouchOrMouseEvent = MouseEvent | TouchEvent;
+export declare type UseOnOutsideClickSettings = {
+    containerRef: React.RefObject<HTMLDivElement>;
+    ignoreClickRefs?: React.RefObject<HTMLElement>[];
+    onClickOutside: (e: TouchOrMouseEvent) => void;
+};
+export declare const useOnOutsideClick: ({ containerRef, ignoreClickRefs, onClickOutside }: UseOnOutsideClickSettings) => void;

package/lib-esm/hooks/useOnOutsideClick.js

@@ -0,0 +1,79 @@
+import { useEffect, useCallback, useMemo } from 'react';
+// Because events are handled at the document level, we provide a mechanism for early return.
+const stopPropagation = true;
+/**
+ * Calls all handlers in reverse order
+ * @param event The MouseEvent generated by the click event.
+ */
+
+function handleClick(event) {
+  if (!event.defaultPrevented) {
+    for (const handler of Object.values(registry).reverse()) {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (handler(event) === stopPropagation || event.defaultPrevented) {
+        break;
+      }
+    }
+  }
+}
+
+const registry = {};
+
+function register(id, handler) {
+  registry[id] = handler;
+}
+
+function deregister(id) {
+  delete registry[id];
+} // For auto-incrementing unique identifiers for registered handlers.
+
+
+let handlerId = 0;
+export const useOnOutsideClick = ({
+  containerRef,
+  ignoreClickRefs,
+  onClickOutside
+}) => {
+  const id = useMemo(() => handlerId++, []);
+  const handler = useCallback(event => {
+    var _containerRef$current;
+
+    // don't call click handler if the mouse event was triggered by an auxiliary button (right click/wheel button/etc)
+    if (event instanceof MouseEvent && event.button > 0) {
+      return stopPropagation;
+    } // don't call handler if the click happened inside of the container
+
+
+    if ((_containerRef$current = containerRef.current) !== null && _containerRef$current !== void 0 && _containerRef$current.contains(event.target)) {
+      return stopPropagation;
+    } // don't call handler if click happened on an ignored ref
+
+
+    if (ignoreClickRefs && ignoreClickRefs.some(({
+      current
+    }) => current === null || current === void 0 ? void 0 : current.contains(event.target))) {
+      return stopPropagation;
+    }
+
+    onClickOutside(event);
+  }, [containerRef, ignoreClickRefs, onClickOutside]);
+  useEffect(() => {
+    if (Object.keys(registry).length === 0) {
+      // use capture to ensure we get all events
+      document.addEventListener('mousedown', handleClick, {
+        capture: true
+      });
+    }
+
+    register(id, handler);
+    return () => {
+      deregister(id);
+
+      if (Object.keys(registry).length === 0) {
+        document.removeEventListener('mousedown', handleClick, {
+          capture: true
+        });
+      }
+    };
+  }, [id, handler]);
+};

package/lib-esm/hooks/useOpenAndCloseFocus.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+export declare type UseOpenAndCloseFocusSettings = {
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    containerRef: React.RefObject<HTMLElement>;
+    returnFocusRef: React.RefObject<HTMLElement>;
+    preventFocusOnOpen?: boolean;
+};
+export declare function useOpenAndCloseFocus({ initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen }: UseOpenAndCloseFocusSettings): void;

package/lib-esm/hooks/useOpenAndCloseFocus.js

@@ -0,0 +1,27 @@
+import { useEffect } from 'react';
+import { iterateFocusableElements } from '../utils/iterateFocusableElements';
+export function useOpenAndCloseFocus({
+  initialFocusRef,
+  returnFocusRef,
+  containerRef,
+  preventFocusOnOpen
+}) {
+  useEffect(() => {
+    if (preventFocusOnOpen) {
+      return;
+    }
+
+    const returnRef = returnFocusRef.current;
+
+    if (initialFocusRef && initialFocusRef.current) {
+      initialFocusRef.current.focus();
+    } else if (containerRef.current) {
+      const firstItem = iterateFocusableElements(containerRef.current).next().value;
+      firstItem === null || firstItem === void 0 ? void 0 : firstItem.focus();
+    }
+
+    return function () {
+      returnRef === null || returnRef === void 0 ? void 0 : returnRef.focus();
+    };
+  }, [initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen]);
+}

package/lib-esm/hooks/useOverlay.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="react" />
+import { TouchOrMouseEvent } from './useOnOutsideClick';
+export declare type UseOverlaySettings = {
+    ignoreClickRefs?: React.RefObject<HTMLElement>[];
+    initialFocusRef?: React.RefObject<HTMLElement>;
+    returnFocusRef: React.RefObject<HTMLElement>;
+    onEscape: (e: KeyboardEvent) => void;
+    onClickOutside: (e: TouchOrMouseEvent) => void;
+    overlayRef?: React.RefObject<HTMLDivElement>;
+    preventFocusOnOpen?: boolean;
+};
+export declare type OverlayReturnProps = {
+    ref: React.RefObject<HTMLDivElement>;
+};
+export declare const useOverlay: ({ overlayRef: _overlayRef, returnFocusRef, initialFocusRef, onEscape, ignoreClickRefs, onClickOutside, preventFocusOnOpen }: UseOverlaySettings) => OverlayReturnProps;

package/lib-esm/hooks/useOverlay.js

@@ -0,0 +1,30 @@
+import { useOnOutsideClick } from './useOnOutsideClick';
+import { useOpenAndCloseFocus } from './useOpenAndCloseFocus';
+import { useOnEscapePress } from './useOnEscapePress';
+import { useProvidedRefOrCreate } from './useProvidedRefOrCreate';
+export const useOverlay = ({
+  overlayRef: _overlayRef,
+  returnFocusRef,
+  initialFocusRef,
+  onEscape,
+  ignoreClickRefs,
+  onClickOutside,
+  preventFocusOnOpen
+}) => {
+  const overlayRef = useProvidedRefOrCreate(_overlayRef);
+  useOpenAndCloseFocus({
+    containerRef: overlayRef,
+    returnFocusRef,
+    initialFocusRef,
+    preventFocusOnOpen
+  });
+  useOnOutsideClick({
+    containerRef: overlayRef,
+    ignoreClickRefs,
+    onClickOutside
+  });
+  useOnEscapePress(onEscape);
+  return {
+    ref: overlayRef
+  };
+};

package/lib-esm/hooks/useProvidedRefOrCreate.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+/**
+ * There are some situations where we only want to create a new ref if one is not provided to a component
+ * or hook as a prop. However, due to the `rules-of-hooks`, we cannot conditionally make a call to `React.useRef`
+ * only in the situations where the ref is not provided as a prop.
+ * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
+ * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
+ * @type TRef The type of the RefObject which should be created.
+ */
+export declare function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef>): React.RefObject<TRef>;