carbon-react 116.1.0 → 116.1.1

package/esm/__internal__/focus-trap/focus-trap-utils.d.ts

@@ -1,4 +1,9 @@
+declare type CustomRefObject<T> = {
+    current?: T | null;
+};
 declare const defaultFocusableSelectors = "button:not([disabled]), [href], input:not([type=\"hidden\"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]";
 declare const setElementFocus: (element: HTMLElement) => void;
 declare const getNextElement: (element: HTMLElement, focusableElements: HTMLElement[], shiftKey: boolean) => HTMLElement | undefined;
-export { defaultFocusableSelectors, getNextElement, setElementFocus };
+declare const onTabGuardFocus: (trapWrappers: CustomRefObject<HTMLElement>[], focusableSelectors: string | undefined, position: "top" | "bottom") => (guardWrapperRef: CustomRefObject<HTMLElement>) => () => void;
+declare const trapFunction: (ev: KeyboardEvent, defaultFocusableElements: HTMLElement[], isWrapperFocused: boolean, focusableSelectors?: string | undefined, bespokeTrap?: ((event: KeyboardEvent, firstElement?: HTMLElement | undefined, lastElement?: HTMLElement | undefined) => void) | undefined) => void;
+export { defaultFocusableSelectors, getNextElement, setElementFocus, onTabGuardFocus, trapFunction, };

package/esm/__internal__/focus-trap/focus-trap-utils.js

@@ -45,12 +45,6 @@ const getNextElement = (element, focusableElements, shiftKey) => {
   if (currentIndex === -1) {
     // we're not currently on a focusable element - most likely because the focusableElements come from a different focus trap!
     // So we need to leave focus where it is.
-    // The exception is when the focus is on the document body - perhaps because the previously-focused element was dynamically removed.
-    // In that case focus the first element.
-    if (element === document.body) {
-      return focusableElements[0];
-    }
-
     return undefined;
   }
 
@@ -110,4 +104,80 @@ const getNextElement = (element, focusableElements, shiftKey) => {
   return foundElement;
 };
 
-export { defaultFocusableSelectors, getNextElement, setElementFocus };
+const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWrapperRef => () => {
+  var _allFocusableElements2;
+
+  const isTop = position === "top";
+  const currentIndex = trapWrappers.indexOf(guardWrapperRef);
+  let index = currentIndex;
+  let nextWrapper, allFocusableElementsInNextWrapper;
+
+  do {
+    var _allFocusableElements, _nextWrapper, _nextWrapper$current;
+
+    index += isTop ? -1 : 1;
+
+    if (index < 0) {
+      index += trapWrappers.length;
+    }
+
+    if (index >= trapWrappers.length) {
+      index -= trapWrappers.length;
+    }
+
+    nextWrapper = trapWrappers[index];
+    allFocusableElementsInNextWrapper = (_nextWrapper = nextWrapper) === null || _nextWrapper === void 0 ? void 0 : (_nextWrapper$current = _nextWrapper.current) === null || _nextWrapper$current === void 0 ? void 0 : _nextWrapper$current.querySelectorAll(focusableSelectors || defaultFocusableSelectors);
+  } while (index !== currentIndex && !((_allFocusableElements = allFocusableElementsInNextWrapper) !== null && _allFocusableElements !== void 0 && _allFocusableElements.length));
+
+  const toFocus = (_allFocusableElements2 = allFocusableElementsInNextWrapper) === null || _allFocusableElements2 === void 0 ? void 0 : _allFocusableElements2[isTop ? allFocusableElementsInNextWrapper.length - 1 : 0];
+
+  if (isRadio(toFocus)) {
+    const radioToFocus = getRadioElementToFocus(toFocus.getAttribute("name"), isTop);
+    setElementFocus(radioToFocus);
+  } else {
+    setElementFocus(toFocus);
+  }
+};
+
+const trapFunction = (ev, defaultFocusableElements, isWrapperFocused, focusableSelectors, bespokeTrap) => {
+  const customFocusableElements = focusableSelectors ? defaultFocusableElements.filter(element => element.matches(focusableSelectors)) : defaultFocusableElements;
+  const firstElement = customFocusableElements[0];
+  const lastElement = customFocusableElements[customFocusableElements.length - 1];
+
+  if (bespokeTrap) {
+    bespokeTrap(ev, firstElement, lastElement);
+    return;
+  }
+
+  if (ev.key !== "Tab") return;
+
+  if (!(customFocusableElements !== null && customFocusableElements !== void 0 && customFocusableElements.length)) {
+    /* Block the trap */
+    ev.preventDefault();
+    return;
+  }
+
+  const activeElement = document.activeElement; // special case if focus is on document body
+
+  if (activeElement === document.body) {
+    ev.preventDefault();
+    setElementFocus(firstElement);
+    return;
+  }
+
+  if (!focusableSelectors) {
+    return;
+  }
+
+  const elementWhenWrapperFocused = ev.shiftKey ? firstElement : lastElement;
+  const elementToFocus = getNextElement(isWrapperFocused ? elementWhenWrapperFocused : activeElement, customFocusableElements, ev.shiftKey);
+  const defaultNextElement = getNextElement(isWrapperFocused ? elementWhenWrapperFocused : activeElement, defaultFocusableElements, ev.shiftKey);
+
+  if (elementToFocus && elementToFocus !== defaultNextElement) {
+    // if next element would match the custom selector anyway, then no need to prevent default
+    setElementFocus(elementToFocus);
+    ev.preventDefault();
+  }
+};
+
+export { defaultFocusableSelectors, getNextElement, setElementFocus, onTabGuardFocus, trapFunction };

package/esm/__internal__/focus-trap/focus-trap.component.d.ts

@@ -12,7 +12,7 @@ export interface FocusTrapProps {
     /** optional selector to identify the focusable elements, if not provided a default selector is used */
     focusableSelectors?: string;
     /** a ref to the container wrapping the focusable elements */
-    wrapperRef?: CustomRefObject<HTMLElement>;
+    wrapperRef: CustomRefObject<HTMLElement>;
     isOpen?: boolean;
     /** an optional array of refs to containers whose content should also be reachable from the FocusTrap */
     additionalWrapperRefs?: CustomRefObject<HTMLElement>[];

package/esm/__internal__/focus-trap/focus-trap.component.js

@@ -1,8 +1,11 @@
-import React, { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import React, { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import PropTypes from "prop-types";
-import { defaultFocusableSelectors, getNextElement, setElementFocus } from "./focus-trap-utils";
+import { defaultFocusableSelectors, setElementFocus, onTabGuardFocus, trapFunction } from "./focus-trap-utils";
 import { ModalContext } from "../../components/modal/modal.component";
-import usePrevious from "../../hooks/__internal__/usePrevious"; // TODO investigate why React.RefObject<T> produces a failed prop type when current = null
+import usePrevious from "../../hooks/__internal__/usePrevious";
+import TopModalContext from "../../components/carbon-provider/top-modal-context";
+const TAB_GUARD_TOP = "tab-guard-top";
+const TAB_GUARD_BOTTOM = "tab-guard-bottom"; // TODO investigate why React.RefObject<T> produces a failed prop type when current = null
 
 const FocusTrap = ({
   children,
@@ -15,113 +18,129 @@ const FocusTrap = ({
   additionalWrapperRefs
 }) => {
   const trapRef = useRef(null);
-  const [focusableElements, setFocusableElements] = useState();
-  const [firstElement, setFirstElement] = useState();
-  const [lastElement, setLastElement] = useState();
   const [currentFocusedElement, setCurrentFocusedElement] = useState();
   const {
     isAnimationComplete = true,
     triggerRefocusFlag
   } = useContext(ModalContext);
-  const hasNewInputs = useCallback(candidate => {
-    if (!focusableElements || candidate.length !== focusableElements.length) {
-      return true;
-    }
+  const {
+    topModal
+  } = useContext(TopModalContext); // we ensure that isTopModal is true if there is no TopModalContext, so that consumers who have not
+  // wrapped their app in CarbonProvider do not have all FocusTrap behaviour broken
 
-    return Array.from(candidate).some((el, i) => el !== focusableElements[i]);
-  }, [focusableElements]);
+  const isTopModal = !topModal || wrapperRef.current && topModal.contains(wrapperRef.current);
   const trapWrappers = useMemo(() => additionalWrapperRefs !== null && additionalWrapperRefs !== void 0 && additionalWrapperRefs.length ? [wrapperRef, ...additionalWrapperRefs] : [wrapperRef], [additionalWrapperRefs, wrapperRef]);
-  const allRefs = trapWrappers.map(ref => ref === null || ref === void 0 ? void 0 : ref.current);
-  const updateFocusableElements = useCallback(() => {
-    const elements = [];
-    allRefs.forEach(ref => {
-      if (ref) {
-        elements.push(...Array.from(ref.querySelectorAll(focusableSelectors || defaultFocusableSelectors)).filter(el => Number(el.tabIndex) !== -1));
-      }
-    });
-
-    if (hasNewInputs(elements)) {
-      setFocusableElements(Array.from(elements));
-      setFirstElement(elements[0]);
-      setLastElement(elements[elements.length - 1]);
-    }
-  }, [hasNewInputs, allRefs, focusableSelectors]);
+  const onTabGuardTopFocus = useMemo(() => onTabGuardFocus(trapWrappers, focusableSelectors, "top"), [focusableSelectors, trapWrappers]);
+  const onTabGuardBottomFocus = useMemo(() => onTabGuardFocus(trapWrappers, focusableSelectors, "bottom"), [focusableSelectors, trapWrappers]);
   useEffect(() => {
-    const observer = new MutationObserver(updateFocusableElements);
-    trapWrappers.forEach(wrapper => {
-      if (wrapper !== null && wrapper !== void 0 && wrapper.current) {
-        observer.observe(wrapper === null || wrapper === void 0 ? void 0 : wrapper.current, {
-          subtree: true,
-          childList: true,
-          attributes: true,
-          characterData: true
-        });
+    additionalWrapperRefs === null || additionalWrapperRefs === void 0 ? void 0 : additionalWrapperRefs.forEach(ref => {
+      const {
+        current: containerElement
+      } = ref; // istanbul ignore else
+
+      if (containerElement) {
+        var _containerElement$pre, _containerElement$nex;
+
+        // istanbul ignore else
+        if (!((_containerElement$pre = containerElement.previousElementSibling) !== null && _containerElement$pre !== void 0 && _containerElement$pre.matches(`[data-element=${TAB_GUARD_TOP}]`))) {
+          const topTabGuard = document.createElement("div");
+          topTabGuard.tabIndex = 0;
+          topTabGuard.dataset.element = TAB_GUARD_TOP;
+          containerElement.insertAdjacentElement("beforebegin", topTabGuard);
+          topTabGuard.addEventListener("focus", onTabGuardTopFocus(ref));
+        } // istanbul ignore else
+
+
+        if (!((_containerElement$nex = containerElement.nextElementSibling) !== null && _containerElement$nex !== void 0 && _containerElement$nex.matches(`[data-element=${TAB_GUARD_BOTTOM}]`))) {
+          const bottomTabGuard = document.createElement("div");
+          bottomTabGuard.tabIndex = 0;
+          bottomTabGuard.dataset.element = TAB_GUARD_BOTTOM;
+          containerElement.insertAdjacentElement("afterend", bottomTabGuard);
+          bottomTabGuard.addEventListener("focus", onTabGuardBottomFocus(ref));
+        }
       }
     });
-    return () => observer.disconnect();
-  }, [updateFocusableElements, trapWrappers]);
-  useLayoutEffect(() => {
-    updateFocusableElements();
-  }, [children, updateFocusableElements]);
-  const shouldSetFocus = autoFocus && isOpen && isAnimationComplete && (focusFirstElement || (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current));
+    return () => {
+      additionalWrapperRefs === null || additionalWrapperRefs === void 0 ? void 0 : additionalWrapperRefs.forEach(ref => {
+        var _ref$current, _ref$current2;
+
+        const previousElement = (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.previousElementSibling;
+
+        if (previousElement !== null && previousElement !== void 0 && previousElement.matches(`[data-element=${TAB_GUARD_TOP}]`)) {
+          previousElement.remove();
+        }
+
+        const nextElement = (_ref$current2 = ref.current) === null || _ref$current2 === void 0 ? void 0 : _ref$current2.nextElementSibling;
+
+        if (nextElement !== null && nextElement !== void 0 && nextElement.matches(`[data-element=${TAB_GUARD_BOTTOM}]`)) {
+          nextElement.remove();
+        }
+      });
+    };
+  }, [additionalWrapperRefs, onTabGuardTopFocus, onTabGuardBottomFocus]);
+  const shouldSetFocus = autoFocus && isOpen && isAnimationComplete;
   const prevShouldSetFocus = usePrevious(shouldSetFocus);
   useEffect(() => {
     if (shouldSetFocus && !prevShouldSetFocus) {
       const candidateFirstElement = focusFirstElement && "current" in focusFirstElement ? focusFirstElement.current : focusFirstElement;
-      setElementFocus(candidateFirstElement || (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current));
+      const elementToFocus = candidateFirstElement || wrapperRef.current; // istanbul ignore else
+
+      if (elementToFocus) {
+        setElementFocus(elementToFocus);
+      }
     }
   }, [shouldSetFocus, prevShouldSetFocus, focusFirstElement, wrapperRef]);
+  const getFocusableElements = useCallback(selector => {
+    const elements = [];
+    trapWrappers.forEach(ref => {
+      // istanbul ignore else
+      if (ref.current) {
+        elements.push(...Array.from(ref.current.querySelectorAll(selector)).filter(el => Number(el.tabIndex) !== -1));
+      }
+    });
+    return elements;
+  }, [trapWrappers]);
   useEffect(() => {
     const trapFn = ev => {
-      if (bespokeTrap) {
-        bespokeTrap(ev, firstElement, lastElement);
-        return;
-      }
-
-      if (ev.key !== "Tab") return;
-
-      if (!(focusableElements !== null && focusableElements !== void 0 && focusableElements.length)) {
-        /* Block the trap */
-        ev.preventDefault();
+      // block focus trap from working if it's not the topmost trap
+      if (!isTopModal) {
         return;
       }
 
-      const activeElement = document.activeElement;
-      const isWrapperFocused = activeElement === (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current);
-      const elementWhenWrapperFocused = ev.shiftKey ? firstElement : lastElement;
-      const elementToFocus = getNextElement(isWrapperFocused ? elementWhenWrapperFocused : activeElement, focusableElements, ev.shiftKey);
-
-      if (elementToFocus) {
-        setElementFocus(elementToFocus);
-        ev.preventDefault();
-      }
+      const focusableElements = getFocusableElements(defaultFocusableSelectors);
+      trapFunction(ev, focusableElements, document.activeElement === wrapperRef.current, focusableSelectors, bespokeTrap);
     };
 
     document.addEventListener("keydown", trapFn, true);
     return function cleanup() {
       document.removeEventListener("keydown", trapFn, true);
     };
-  }, [firstElement, lastElement, focusableElements, bespokeTrap, wrapperRef]);
+  }, [bespokeTrap, wrapperRef, focusableSelectors, getFocusableElements, isTopModal]);
   const updateCurrentFocusedElement = useCallback(() => {
+    const focusableElements = getFocusableElements(focusableSelectors || defaultFocusableSelectors);
     const element = focusableElements === null || focusableElements === void 0 ? void 0 : focusableElements.find(el => el === document.activeElement);
 
     if (element) {
       setCurrentFocusedElement(element);
     }
-  }, [focusableElements]);
+  }, [getFocusableElements, focusableSelectors]);
   const refocusTrap = useCallback(() => {
     var _wrapperRef$current;
 
-    /* istanbul ignore else */
     if (currentFocusedElement && !currentFocusedElement.hasAttribute("disabled")) {
       // the trap breaks if it tries to refocus a disabled element
       setElementFocus(currentFocusedElement);
-    } else if (wrapperRef !== null && wrapperRef !== void 0 && (_wrapperRef$current = wrapperRef.current) !== null && _wrapperRef$current !== void 0 && _wrapperRef$current.hasAttribute("tabindex")) {
+    } else if ((_wrapperRef$current = wrapperRef.current) !== null && _wrapperRef$current !== void 0 && _wrapperRef$current.hasAttribute("tabindex")) {
       setElementFocus(wrapperRef.current);
-    } else if (firstElement) {
-      setElementFocus(firstElement);
+    } else {
+      const focusableElements = getFocusableElements(focusableSelectors || defaultFocusableSelectors);
+      /* istanbul ignore else */
+
+      if (focusableElements.length) {
+        setElementFocus(focusableElements[0]);
+      }
     }
-  }, [currentFocusedElement, firstElement, wrapperRef]);
+  }, [currentFocusedElement, wrapperRef, focusableSelectors, getFocusableElements]);
   useEffect(() => {
     if (triggerRefocusFlag) {
       refocusTrap();
@@ -159,15 +178,15 @@ const FocusTrap = ({
   return /*#__PURE__*/React.createElement("div", {
     ref: trapRef
   }, /*#__PURE__*/React.createElement("div", {
-    "data-element": "tab-guard-top" // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+    "data-element": TAB_GUARD_TOP // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
     ,
     tabIndex: 0,
-    onFocus: () => setElementFocus(lastElement)
+    onFocus: onTabGuardTopFocus(wrapperRef)
   }), clonedChildren, /*#__PURE__*/React.createElement("div", {
-    "data-element": "tab-guard-bottom" // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+    "data-element": TAB_GUARD_BOTTOM // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
     ,
     tabIndex: 0,
-    onFocus: () => setElementFocus(firstElement)
+    onFocus: onTabGuardBottomFocus(wrapperRef)
   }));
 };
 
@@ -209,6 +228,6 @@ FocusTrap.propTypes = {
         return new Error("Expected prop '" + propName + "' to be of type Element");
       }
     }
-  })
+  }).isRequired
 };
 export default FocusTrap;

package/lib/__internal__/focus-trap/focus-trap-utils.d.ts

@@ -1,4 +1,9 @@
+declare type CustomRefObject<T> = {
+    current?: T | null;
+};
 declare const defaultFocusableSelectors = "button:not([disabled]), [href], input:not([type=\"hidden\"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]";
 declare const setElementFocus: (element: HTMLElement) => void;
 declare const getNextElement: (element: HTMLElement, focusableElements: HTMLElement[], shiftKey: boolean) => HTMLElement | undefined;
-export { defaultFocusableSelectors, getNextElement, setElementFocus };
+declare const onTabGuardFocus: (trapWrappers: CustomRefObject<HTMLElement>[], focusableSelectors: string | undefined, position: "top" | "bottom") => (guardWrapperRef: CustomRefObject<HTMLElement>) => () => void;
+declare const trapFunction: (ev: KeyboardEvent, defaultFocusableElements: HTMLElement[], isWrapperFocused: boolean, focusableSelectors?: string | undefined, bespokeTrap?: ((event: KeyboardEvent, firstElement?: HTMLElement | undefined, lastElement?: HTMLElement | undefined) => void) | undefined) => void;
+export { defaultFocusableSelectors, getNextElement, setElementFocus, onTabGuardFocus, trapFunction, };

package/lib/__internal__/focus-trap/focus-trap-utils.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.setElementFocus = exports.getNextElement = exports.defaultFocusableSelectors = void 0;
+exports.trapFunction = exports.onTabGuardFocus = exports.setElementFocus = exports.getNextElement = exports.defaultFocusableSelectors = void 0;
 const defaultFocusableSelectors = 'button:not([disabled]), [href], input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]';
 exports.defaultFocusableSelectors = defaultFocusableSelectors;
 const INTERVAL = 10;
@@ -54,12 +54,6 @@ const getNextElement = (element, focusableElements, shiftKey) => {
   if (currentIndex === -1) {
     // we're not currently on a focusable element - most likely because the focusableElements come from a different focus trap!
     // So we need to leave focus where it is.
-    // The exception is when the focus is on the document body - perhaps because the previously-focused element was dynamically removed.
-    // In that case focus the first element.
-    if (element === document.body) {
-      return focusableElements[0];
-    }
-
     return undefined;
   }
 
@@ -119,4 +113,84 @@ const getNextElement = (element, focusableElements, shiftKey) => {
   return foundElement;
 };
 
-exports.getNextElement = getNextElement;
+exports.getNextElement = getNextElement;
+
+const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWrapperRef => () => {
+  var _allFocusableElements2;
+
+  const isTop = position === "top";
+  const currentIndex = trapWrappers.indexOf(guardWrapperRef);
+  let index = currentIndex;
+  let nextWrapper, allFocusableElementsInNextWrapper;
+
+  do {
+    var _allFocusableElements, _nextWrapper, _nextWrapper$current;
+
+    index += isTop ? -1 : 1;
+
+    if (index < 0) {
+      index += trapWrappers.length;
+    }
+
+    if (index >= trapWrappers.length) {
+      index -= trapWrappers.length;
+    }
+
+    nextWrapper = trapWrappers[index];
+    allFocusableElementsInNextWrapper = (_nextWrapper = nextWrapper) === null || _nextWrapper === void 0 ? void 0 : (_nextWrapper$current = _nextWrapper.current) === null || _nextWrapper$current === void 0 ? void 0 : _nextWrapper$current.querySelectorAll(focusableSelectors || defaultFocusableSelectors);
+  } while (index !== currentIndex && !((_allFocusableElements = allFocusableElementsInNextWrapper) !== null && _allFocusableElements !== void 0 && _allFocusableElements.length));
+
+  const toFocus = (_allFocusableElements2 = allFocusableElementsInNextWrapper) === null || _allFocusableElements2 === void 0 ? void 0 : _allFocusableElements2[isTop ? allFocusableElementsInNextWrapper.length - 1 : 0];
+
+  if (isRadio(toFocus)) {
+    const radioToFocus = getRadioElementToFocus(toFocus.getAttribute("name"), isTop);
+    setElementFocus(radioToFocus);
+  } else {
+    setElementFocus(toFocus);
+  }
+};
+
+exports.onTabGuardFocus = onTabGuardFocus;
+
+const trapFunction = (ev, defaultFocusableElements, isWrapperFocused, focusableSelectors, bespokeTrap) => {
+  const customFocusableElements = focusableSelectors ? defaultFocusableElements.filter(element => element.matches(focusableSelectors)) : defaultFocusableElements;
+  const firstElement = customFocusableElements[0];
+  const lastElement = customFocusableElements[customFocusableElements.length - 1];
+
+  if (bespokeTrap) {
+    bespokeTrap(ev, firstElement, lastElement);
+    return;
+  }
+
+  if (ev.key !== "Tab") return;
+
+  if (!(customFocusableElements !== null && customFocusableElements !== void 0 && customFocusableElements.length)) {
+    /* Block the trap */
+    ev.preventDefault();
+    return;
+  }
+
+  const activeElement = document.activeElement; // special case if focus is on document body
+
+  if (activeElement === document.body) {
+    ev.preventDefault();
+    setElementFocus(firstElement);
+    return;
+  }
+
+  if (!focusableSelectors) {
+    return;
+  }
+
+  const elementWhenWrapperFocused = ev.shiftKey ? firstElement : lastElement;
+  const elementToFocus = getNextElement(isWrapperFocused ? elementWhenWrapperFocused : activeElement, customFocusableElements, ev.shiftKey);
+  const defaultNextElement = getNextElement(isWrapperFocused ? elementWhenWrapperFocused : activeElement, defaultFocusableElements, ev.shiftKey);
+
+  if (elementToFocus && elementToFocus !== defaultNextElement) {
+    // if next element would match the custom selector anyway, then no need to prevent default
+    setElementFocus(elementToFocus);
+    ev.preventDefault();
+  }
+};
+
+exports.trapFunction = trapFunction;

package/lib/__internal__/focus-trap/focus-trap.component.d.ts

@@ -12,7 +12,7 @@ export interface FocusTrapProps {
     /** optional selector to identify the focusable elements, if not provided a default selector is used */
     focusableSelectors?: string;
     /** a ref to the container wrapping the focusable elements */
-    wrapperRef?: CustomRefObject<HTMLElement>;
+    wrapperRef: CustomRefObject<HTMLElement>;
     isOpen?: boolean;
     /** an optional array of refs to containers whose content should also be reachable from the FocusTrap */
     additionalWrapperRefs?: CustomRefObject<HTMLElement>[];

package/lib/__internal__/focus-trap/focus-trap.component.js

@@ -15,12 +15,17 @@ var _modal = require("../../components/modal/modal.component");
 
 var _usePrevious = _interopRequireDefault(require("../../hooks/__internal__/usePrevious"));
 
+var _topModalContext = _interopRequireDefault(require("../../components/carbon-provider/top-modal-context"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 function _getRequireWildcardCache() { if (typeof WeakMap !== "function") return null; var cache = new WeakMap(); _getRequireWildcardCache = function () { return cache; }; return cache; }
 
 function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
 
+const TAB_GUARD_TOP = "tab-guard-top";
+const TAB_GUARD_BOTTOM = "tab-guard-bottom"; // TODO investigate why React.RefObject<T> produces a failed prop type when current = null
+
 const FocusTrap = ({
   children,
   autoFocus = true,
@@ -32,113 +37,129 @@ const FocusTrap = ({
   additionalWrapperRefs
 }) => {
   const trapRef = (0, _react.useRef)(null);
-  const [focusableElements, setFocusableElements] = (0, _react.useState)();
-  const [firstElement, setFirstElement] = (0, _react.useState)();
-  const [lastElement, setLastElement] = (0, _react.useState)();
   const [currentFocusedElement, setCurrentFocusedElement] = (0, _react.useState)();
   const {
     isAnimationComplete = true,
     triggerRefocusFlag
   } = (0, _react.useContext)(_modal.ModalContext);
-  const hasNewInputs = (0, _react.useCallback)(candidate => {
-    if (!focusableElements || candidate.length !== focusableElements.length) {
-      return true;
-    }
+  const {
+    topModal
+  } = (0, _react.useContext)(_topModalContext.default); // we ensure that isTopModal is true if there is no TopModalContext, so that consumers who have not
+  // wrapped their app in CarbonProvider do not have all FocusTrap behaviour broken
 
-    return Array.from(candidate).some((el, i) => el !== focusableElements[i]);
-  }, [focusableElements]);
+  const isTopModal = !topModal || wrapperRef.current && topModal.contains(wrapperRef.current);
   const trapWrappers = (0, _react.useMemo)(() => additionalWrapperRefs !== null && additionalWrapperRefs !== void 0 && additionalWrapperRefs.length ? [wrapperRef, ...additionalWrapperRefs] : [wrapperRef], [additionalWrapperRefs, wrapperRef]);
-  const allRefs = trapWrappers.map(ref => ref === null || ref === void 0 ? void 0 : ref.current);
-  const updateFocusableElements = (0, _react.useCallback)(() => {
-    const elements = [];
-    allRefs.forEach(ref => {
-      if (ref) {
-        elements.push(...Array.from(ref.querySelectorAll(focusableSelectors || _focusTrapUtils.defaultFocusableSelectors)).filter(el => Number(el.tabIndex) !== -1));
-      }
-    });
-
-    if (hasNewInputs(elements)) {
-      setFocusableElements(Array.from(elements));
-      setFirstElement(elements[0]);
-      setLastElement(elements[elements.length - 1]);
-    }
-  }, [hasNewInputs, allRefs, focusableSelectors]);
+  const onTabGuardTopFocus = (0, _react.useMemo)(() => (0, _focusTrapUtils.onTabGuardFocus)(trapWrappers, focusableSelectors, "top"), [focusableSelectors, trapWrappers]);
+  const onTabGuardBottomFocus = (0, _react.useMemo)(() => (0, _focusTrapUtils.onTabGuardFocus)(trapWrappers, focusableSelectors, "bottom"), [focusableSelectors, trapWrappers]);
   (0, _react.useEffect)(() => {
-    const observer = new MutationObserver(updateFocusableElements);
-    trapWrappers.forEach(wrapper => {
-      if (wrapper !== null && wrapper !== void 0 && wrapper.current) {
-        observer.observe(wrapper === null || wrapper === void 0 ? void 0 : wrapper.current, {
-          subtree: true,
-          childList: true,
-          attributes: true,
-          characterData: true
-        });
+    additionalWrapperRefs === null || additionalWrapperRefs === void 0 ? void 0 : additionalWrapperRefs.forEach(ref => {
+      const {
+        current: containerElement
+      } = ref; // istanbul ignore else
+
+      if (containerElement) {
+        var _containerElement$pre, _containerElement$nex;
+
+        // istanbul ignore else
+        if (!((_containerElement$pre = containerElement.previousElementSibling) !== null && _containerElement$pre !== void 0 && _containerElement$pre.matches(`[data-element=${TAB_GUARD_TOP}]`))) {
+          const topTabGuard = document.createElement("div");
+          topTabGuard.tabIndex = 0;
+          topTabGuard.dataset.element = TAB_GUARD_TOP;
+          containerElement.insertAdjacentElement("beforebegin", topTabGuard);
+          topTabGuard.addEventListener("focus", onTabGuardTopFocus(ref));
+        } // istanbul ignore else
+
+
+        if (!((_containerElement$nex = containerElement.nextElementSibling) !== null && _containerElement$nex !== void 0 && _containerElement$nex.matches(`[data-element=${TAB_GUARD_BOTTOM}]`))) {
+          const bottomTabGuard = document.createElement("div");
+          bottomTabGuard.tabIndex = 0;
+          bottomTabGuard.dataset.element = TAB_GUARD_BOTTOM;
+          containerElement.insertAdjacentElement("afterend", bottomTabGuard);
+          bottomTabGuard.addEventListener("focus", onTabGuardBottomFocus(ref));
+        }
       }
     });
-    return () => observer.disconnect();
-  }, [updateFocusableElements, trapWrappers]);
-  (0, _react.useLayoutEffect)(() => {
-    updateFocusableElements();
-  }, [children, updateFocusableElements]);
-  const shouldSetFocus = autoFocus && isOpen && isAnimationComplete && (focusFirstElement || (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current));
+    return () => {
+      additionalWrapperRefs === null || additionalWrapperRefs === void 0 ? void 0 : additionalWrapperRefs.forEach(ref => {
+        var _ref$current, _ref$current2;
+
+        const previousElement = (_ref$current = ref.current) === null || _ref$current === void 0 ? void 0 : _ref$current.previousElementSibling;
+
+        if (previousElement !== null && previousElement !== void 0 && previousElement.matches(`[data-element=${TAB_GUARD_TOP}]`)) {
+          previousElement.remove();
+        }
+
+        const nextElement = (_ref$current2 = ref.current) === null || _ref$current2 === void 0 ? void 0 : _ref$current2.nextElementSibling;
+
+        if (nextElement !== null && nextElement !== void 0 && nextElement.matches(`[data-element=${TAB_GUARD_BOTTOM}]`)) {
+          nextElement.remove();
+        }
+      });
+    };
+  }, [additionalWrapperRefs, onTabGuardTopFocus, onTabGuardBottomFocus]);
+  const shouldSetFocus = autoFocus && isOpen && isAnimationComplete;
   const prevShouldSetFocus = (0, _usePrevious.default)(shouldSetFocus);
   (0, _react.useEffect)(() => {
     if (shouldSetFocus && !prevShouldSetFocus) {
       const candidateFirstElement = focusFirstElement && "current" in focusFirstElement ? focusFirstElement.current : focusFirstElement;
-      (0, _focusTrapUtils.setElementFocus)(candidateFirstElement || (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current));
+      const elementToFocus = candidateFirstElement || wrapperRef.current; // istanbul ignore else
+
+      if (elementToFocus) {
+        (0, _focusTrapUtils.setElementFocus)(elementToFocus);
+      }
     }
   }, [shouldSetFocus, prevShouldSetFocus, focusFirstElement, wrapperRef]);
+  const getFocusableElements = (0, _react.useCallback)(selector => {
+    const elements = [];
+    trapWrappers.forEach(ref => {
+      // istanbul ignore else
+      if (ref.current) {
+        elements.push(...Array.from(ref.current.querySelectorAll(selector)).filter(el => Number(el.tabIndex) !== -1));
+      }
+    });
+    return elements;
+  }, [trapWrappers]);
   (0, _react.useEffect)(() => {
     const trapFn = ev => {
-      if (bespokeTrap) {
-        bespokeTrap(ev, firstElement, lastElement);
-        return;
-      }
-
-      if (ev.key !== "Tab") return;
-
-      if (!(focusableElements !== null && focusableElements !== void 0 && focusableElements.length)) {
-        /* Block the trap */
-        ev.preventDefault();
+      // block focus trap from working if it's not the topmost trap
+      if (!isTopModal) {
         return;
       }
 
-      const activeElement = document.activeElement;
-      const isWrapperFocused = activeElement === (wrapperRef === null || wrapperRef === void 0 ? void 0 : wrapperRef.current);
-      const elementWhenWrapperFocused = ev.shiftKey ? firstElement : lastElement;
-      const elementToFocus = (0, _focusTrapUtils.getNextElement)(isWrapperFocused ? elementWhenWrapperFocused : activeElement, focusableElements, ev.shiftKey);
-
-      if (elementToFocus) {
-        (0, _focusTrapUtils.setElementFocus)(elementToFocus);
-        ev.preventDefault();
-      }
+      const focusableElements = getFocusableElements(_focusTrapUtils.defaultFocusableSelectors);
+      (0, _focusTrapUtils.trapFunction)(ev, focusableElements, document.activeElement === wrapperRef.current, focusableSelectors, bespokeTrap);
     };
 
     document.addEventListener("keydown", trapFn, true);
     return function cleanup() {
       document.removeEventListener("keydown", trapFn, true);
     };
-  }, [firstElement, lastElement, focusableElements, bespokeTrap, wrapperRef]);
+  }, [bespokeTrap, wrapperRef, focusableSelectors, getFocusableElements, isTopModal]);
   const updateCurrentFocusedElement = (0, _react.useCallback)(() => {
+    const focusableElements = getFocusableElements(focusableSelectors || _focusTrapUtils.defaultFocusableSelectors);
     const element = focusableElements === null || focusableElements === void 0 ? void 0 : focusableElements.find(el => el === document.activeElement);
 
     if (element) {
       setCurrentFocusedElement(element);
     }
-  }, [focusableElements]);
+  }, [getFocusableElements, focusableSelectors]);
   const refocusTrap = (0, _react.useCallback)(() => {
     var _wrapperRef$current;
 
-    /* istanbul ignore else */
     if (currentFocusedElement && !currentFocusedElement.hasAttribute("disabled")) {
       // the trap breaks if it tries to refocus a disabled element
       (0, _focusTrapUtils.setElementFocus)(currentFocusedElement);
-    } else if (wrapperRef !== null && wrapperRef !== void 0 && (_wrapperRef$current = wrapperRef.current) !== null && _wrapperRef$current !== void 0 && _wrapperRef$current.hasAttribute("tabindex")) {
+    } else if ((_wrapperRef$current = wrapperRef.current) !== null && _wrapperRef$current !== void 0 && _wrapperRef$current.hasAttribute("tabindex")) {
       (0, _focusTrapUtils.setElementFocus)(wrapperRef.current);
-    } else if (firstElement) {
-      (0, _focusTrapUtils.setElementFocus)(firstElement);
+    } else {
+      const focusableElements = getFocusableElements(focusableSelectors || _focusTrapUtils.defaultFocusableSelectors);
+      /* istanbul ignore else */
+
+      if (focusableElements.length) {
+        (0, _focusTrapUtils.setElementFocus)(focusableElements[0]);
+      }
     }
-  }, [currentFocusedElement, firstElement, wrapperRef]);
+  }, [currentFocusedElement, wrapperRef, focusableSelectors, getFocusableElements]);
   (0, _react.useEffect)(() => {
     if (triggerRefocusFlag) {
       refocusTrap();
@@ -177,15 +198,15 @@ const FocusTrap = ({
   return /*#__PURE__*/_react.default.createElement("div", {
     ref: trapRef
   }, /*#__PURE__*/_react.default.createElement("div", {
-    "data-element": "tab-guard-top" // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+    "data-element": TAB_GUARD_TOP // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
     ,
     tabIndex: 0,
-    onFocus: () => (0, _focusTrapUtils.setElementFocus)(lastElement)
+    onFocus: onTabGuardTopFocus(wrapperRef)
   }), clonedChildren, /*#__PURE__*/_react.default.createElement("div", {
-    "data-element": "tab-guard-bottom" // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
+    "data-element": TAB_GUARD_BOTTOM // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
     ,
     tabIndex: 0,
-    onFocus: () => (0, _focusTrapUtils.setElementFocus)(firstElement)
+    onFocus: onTabGuardBottomFocus(wrapperRef)
   }));
 };
 
@@ -227,7 +248,7 @@ FocusTrap.propTypes = {
         return new Error("Expected prop '" + propName + "' to be of type Element");
       }
     }
-  })
+  }).isRequired
 };
 var _default = FocusTrap;
 exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carbon-react",
-  "version": "116.1.0",
+  "version": "116.1.1",
   "description": "A library of reusable React components for easily building user interfaces.",
   "files": [
     "lib",