carbon-react 123.9.1 → 123.10.1

package/esm/__internal__/checkable-input/hidden-checkable-input.component.js

@@ -62,6 +62,7 @@ const HiddenCheckableInput = /*#__PURE__*/React.forwardRef(({
     "aria-describedby": combinedDescription,
     "aria-labelledby": ariaLabelledBy,
     autoFocus: autoFocus,
+    "data-has-autofocus": autoFocus ? true : undefined,
     "aria-checked": checked,
     checked: checked,
     name: name,

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

@@ -90,7 +90,8 @@ const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWra
   const isTop = position === "top";
   const currentIndex = trapWrappers.indexOf(guardWrapperRef);
   let index = currentIndex;
-  let nextWrapper, allFocusableElementsInNextWrapper;
+  let nextWrapper;
+  let allFocusableElementsInNextWrapper;
   do {
     index += isTop ? -1 : 1;
     if (index < 0) {
@@ -100,7 +101,7 @@ const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWra
       index -= trapWrappers.length;
     }
     nextWrapper = trapWrappers[index];
-    allFocusableElementsInNextWrapper = nextWrapper?.current?.querySelectorAll(focusableSelectors || defaultFocusableSelectors);
+    allFocusableElementsInNextWrapper = Array.from(nextWrapper?.current?.querySelectorAll(focusableSelectors || defaultFocusableSelectors) || /* istanbul ignore next */[]).filter(el => Number(el.tabIndex) !== -1);
   } while (index !== currentIndex && !allFocusableElementsInNextWrapper?.length);
   const toFocus = allFocusableElementsInNextWrapper?.[isTop ? allFocusableElementsInNextWrapper.length - 1 : 0];
   if (isRadio(toFocus)) {

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

@@ -74,16 +74,6 @@ const FocusTrap = ({
   }, [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;
-      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 => {
@@ -94,6 +84,17 @@ const FocusTrap = ({
     });
     return elements;
   }, [trapWrappers]);
+  useEffect(() => {
+    if (shouldSetFocus && !prevShouldSetFocus) {
+      const candidateFirstElement = focusFirstElement && "current" in focusFirstElement ? focusFirstElement.current : focusFirstElement;
+      const autoFocusedElement = getFocusableElements(defaultFocusableSelectors).find(el => el.getAttribute("data-has-autofocus") === "true");
+      const elementToFocus = candidateFirstElement || autoFocusedElement || wrapperRef.current;
+      // istanbul ignore else
+      if (elementToFocus) {
+        setElementFocus(elementToFocus);
+      }
+    }
+  }, [shouldSetFocus, prevShouldSetFocus, getFocusableElements, focusFirstElement, wrapperRef]);
   useEffect(() => {
     const trapFn = ev => {
       // block focus trap from working if it's not the topmost trap, or is currently closed

package/esm/__internal__/input/input.component.js

@@ -131,6 +131,7 @@ const Input = /*#__PURE__*/React.forwardRef(({
   }
   const combinedDescription = descriptionList.length ? descriptionList.filter(Boolean).join(" ") : undefined;
   return /*#__PURE__*/React.createElement(StyledInput, _extends({}, rest, {
+    "data-has-autofocus": autoFocus ? true : undefined,
     "aria-describedby": combinedDescription,
     "aria-labelledby": ariaLabelledBy,
     align: align,

package/esm/components/alert/alert.component.d.ts

@@ -1,4 +1,4 @@
 import React from "react";
 import { DialogProps } from "../dialog";
-export declare const Alert: ({ children, size, ...rest }: DialogProps) => React.JSX.Element;
+export declare const Alert: ({ children, size, topModalOverride, ...rest }: DialogProps) => React.JSX.Element;
 export default Alert;

package/esm/components/alert/alert.component.js

@@ -5,10 +5,12 @@ import Dialog from "../dialog";
 export const Alert = ({
   children,
   size = "extra-small",
+  topModalOverride,
   ...rest
 }) => /*#__PURE__*/React.createElement(Dialog, _extends({
   "data-component": "alert",
   role: "alertdialog",
-  size: size
+  size: size,
+  topModalOverride: topModalOverride
 }, rest), children);
 export default Alert;

package/esm/components/confirm/confirm.component.d.ts

@@ -38,5 +38,5 @@ export interface ConfirmProps extends Omit<DialogProps, "className" | "disableFo
     /** A custom event handler when a confirmation takes place */
     onConfirm: (ev: React.MouseEvent<HTMLButtonElement>) => void;
 }
-export declare const Confirm: ({ "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, open, children, cancelButtonDestructive, confirmButtonDestructive, cancelButtonType, confirmButtonType, cancelButtonIconType, cancelButtonIconPosition, confirmButtonIconType, confirmButtonIconPosition, cancelButtonDataProps, confirmButtonDataProps, cancelLabel, onCancel, disableCancel, onConfirm, isLoadingConfirm, disableConfirm, confirmLabel, iconType, subtitle, title, size, showCloseIcon, ...rest }: ConfirmProps) => React.JSX.Element;
+export declare const Confirm: ({ "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, open, children, cancelButtonDestructive, confirmButtonDestructive, cancelButtonType, confirmButtonType, cancelButtonIconType, cancelButtonIconPosition, confirmButtonIconType, confirmButtonIconPosition, cancelButtonDataProps, confirmButtonDataProps, cancelLabel, onCancel, disableCancel, onConfirm, isLoadingConfirm, disableConfirm, confirmLabel, iconType, subtitle, title, size, showCloseIcon, topModalOverride, ...rest }: ConfirmProps) => React.JSX.Element;
 export default Confirm;

package/esm/components/confirm/confirm.component.js

@@ -38,6 +38,7 @@ export const Confirm = ({
   title,
   size = "extra-small",
   showCloseIcon = false,
+  topModalOverride,
   ...rest
 }) => {
   const l = useLocale();
@@ -114,7 +115,8 @@ export const Confirm = ({
     "data-component": "confirm",
     role: "alertdialog",
     size: size,
-    showCloseIcon: showCloseIcon
+    showCloseIcon: showCloseIcon,
+    topModalOverride: topModalOverride
   }, ariaProps, rest), children, /*#__PURE__*/React.createElement(StyledConfirmButtons, null, renderCancelButton(), renderConfirmButton()));
 };
 export default Confirm;

package/esm/components/dialog/dialog.component.js

@@ -34,6 +34,7 @@ const Dialog = /*#__PURE__*/forwardRef(({
   role = "dialog",
   contentPadding = {},
   focusableContainers,
+  topModalOverride,
   ...rest
 }, ref) => {
   const locale = useLocale();
@@ -154,7 +155,8 @@ const Dialog = /*#__PURE__*/forwardRef(({
     onCancel: onCancel,
     disableEscKey: disableEscKey,
     disableClose: disableClose,
-    className: className ? `${className} carbon-dialog` : "carbon-dialog"
+    className: className ? `${className} carbon-dialog` : "carbon-dialog",
+    topModalOverride: topModalOverride
   }, componentTags), /*#__PURE__*/React.createElement(FocusTrap, {
     autoFocus: !disableAutoFocus,
     focusFirstElement: focusFirstElement,
@@ -234,7 +236,8 @@ Dialog.propTypes = {
   "size": PropTypes.oneOf(["auto", "extra-large", "extra-small", "large", "medium-large", "medium-small", "medium", "small"]),
   "subtitle": PropTypes.string,
   "timeout": PropTypes.number,
-  "title": PropTypes.node
+  "title": PropTypes.node,
+  "topModalOverride": PropTypes.bool
 };
 export { Dialog };
 export default Dialog;

package/esm/components/dialog-full-screen/dialog-full-screen.component.d.ts

@@ -52,5 +52,5 @@ export interface DialogFullScreenProps extends ModalProps {
     /** A custom close event handler */
     onCancel?: (ev: React.KeyboardEvent<HTMLElement> | React.MouseEvent<HTMLButtonElement>) => void;
 }
-export declare const DialogFullScreen: ({ "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disableAutoFocus, focusFirstElement, bespokeFocusTrap, open, children, title, subtitle, pagesStyling, headerChildren, showCloseIcon, disableContentPadding, disableEscKey, onCancel, contentRef, help, role, focusableContainers, focusableSelectors, ...rest }: DialogFullScreenProps) => React.JSX.Element;
+export declare const DialogFullScreen: ({ "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disableAutoFocus, focusFirstElement, bespokeFocusTrap, open, children, title, subtitle, pagesStyling, headerChildren, showCloseIcon, disableContentPadding, disableEscKey, onCancel, contentRef, help, role, focusableContainers, focusableSelectors, topModalOverride, ...rest }: DialogFullScreenProps) => React.JSX.Element;
 export default DialogFullScreen;

package/esm/components/dialog-full-screen/dialog-full-screen.component.js

@@ -35,6 +35,7 @@ export const DialogFullScreen = ({
   role = "dialog",
   focusableContainers,
   focusableSelectors,
+  topModalOverride,
   ...rest
 }) => {
   const locale = useLocale();
@@ -83,7 +84,8 @@ export const DialogFullScreen = ({
   return /*#__PURE__*/React.createElement(Modal, _extends({
     open: open,
     onCancel: onCancel,
-    disableEscKey: disableEscKey
+    disableEscKey: disableEscKey,
+    topModalOverride: topModalOverride
   }, componentTags), /*#__PURE__*/React.createElement(FocusTrap, {
     autoFocus: !disableAutoFocus,
     focusFirstElement: focusFirstElement,

package/esm/components/modal/__internal__/modal-manager.d.ts

@@ -2,12 +2,13 @@ declare type SetTriggerRefocusFlag = (boolean: boolean) => void;
 export declare type ModalList = {
     modal: HTMLElement;
     setTriggerRefocusFlag?: SetTriggerRefocusFlag;
+    topModalOverride?: boolean;
 }[];
 declare class ModalManagerInstance {
     private modalList;
     constructor();
     private getTopModal;
-    addModal: (modal: HTMLElement | null, setTriggerRefocusFlag?: SetTriggerRefocusFlag) => void;
+    addModal: (modal: HTMLElement | null, setTriggerRefocusFlag?: SetTriggerRefocusFlag, topModalOverride?: boolean) => void;
     isTopmost(modal: HTMLElement | null): boolean;
     removeModal(modal: HTMLElement | null, triggerRefocusOnClose?: boolean): void;
     clearList(): void;

package/esm/components/modal/__internal__/modal-manager.js

@@ -8,20 +8,22 @@ let ModalManagerInstance = /*#__PURE__*/function () {
   function ModalManagerInstance() {
     _classCallCheck(this, ModalManagerInstance);
     _defineProperty(this, "modalList", void 0);
-    _defineProperty(this, "addModal", (modal, setTriggerRefocusFlag) => {
+    _defineProperty(this, "addModal", (modal, setTriggerRefocusFlag, topModalOverride) => {
       if (!modal) {
         return;
       }
       const {
         modal: topModal,
-        setTriggerRefocusFlag: setTrapFlag
+        setTriggerRefocusFlag: setTrapFlag,
+        topModalOverride: topOverridden
       } = this.getTopModal();
-      if (topModal && setTrapFlag) {
+      if (!topOverridden && topModal && setTrapFlag) {
         setTrapFlag(false);
       }
       this.modalList.push({
         modal,
-        setTriggerRefocusFlag
+        setTriggerRefocusFlag,
+        topModalOverride
       });
       this.callTopModalSetters();
     });
@@ -38,7 +40,8 @@ let ModalManagerInstance = /*#__PURE__*/function () {
       if (!this.modalList.length) {
         return {};
       }
-      return this.modalList[this.modalList.length - 1];
+      const topModalOverride = this.modalList.slice().reverse().find(modal => modal.topModalOverride);
+      return topModalOverride || this.modalList[this.modalList.length - 1];
     }
   }, {
     key: "isTopmost",

package/esm/components/modal/modal.component.d.ts

@@ -25,6 +25,8 @@ export interface ModalProps extends TagProps {
     open: boolean;
     /** Transition time */
     timeout?: number;
+    /** Manually override the internal modal stacking order to set this as top */
+    topModalOverride?: boolean;
 }
-declare const Modal: ({ children, open, onCancel, disableEscKey, disableClose, enableBackgroundUI, timeout, ...rest }: ModalProps) => React.JSX.Element;
+declare const Modal: ({ children, open, onCancel, disableEscKey, disableClose, enableBackgroundUI, timeout, topModalOverride, ...rest }: ModalProps) => React.JSX.Element;
 export default Modal;

package/esm/components/modal/modal.component.js

@@ -16,6 +16,7 @@ const Modal = ({
   disableClose,
   enableBackgroundUI = false,
   timeout = 300,
+  topModalOverride,
   ...rest
 }) => {
   const ref = useRef(null);
@@ -54,7 +55,8 @@ const Modal = ({
     open,
     closeModal,
     modalRef: ref,
-    setTriggerRefocusFlag
+    setTriggerRefocusFlag,
+    topModalOverride
   });
   let background;
   let content;
@@ -71,6 +73,7 @@ const Modal = ({
     "data-state": open ? "open" : "closed",
     transitionName: "modal",
     transitionTime: timeout,
+    topModalOverride: topModalOverride,
     ref: ref
   }, rest), /*#__PURE__*/React.createElement(TransitionGroup, null, background && /*#__PURE__*/React.createElement(CSSTransition, {
     nodeRef: backgroundNodeRef,

package/esm/components/modal/modal.style.d.ts

@@ -3,5 +3,7 @@ declare type TransitionProps = {
     transitionTime: number;
 };
 declare const StyledModalBackground: import("styled-components").StyledComponent<"div", any, TransitionProps, never>;
-declare const StyledModal: import("styled-components").StyledComponent<"div", any, TransitionProps, never>;
+declare const StyledModal: import("styled-components").StyledComponent<"div", any, TransitionProps & {
+    topModalOverride?: boolean | undefined;
+}, never>;
 export { StyledModal, StyledModalBackground };

package/esm/components/modal/modal.style.js

@@ -37,8 +37,9 @@ const StyledModalBackground = styled.div`
 const StyledModal = styled.div`
   position: absolute;
   z-index: ${({
-  theme
-}) => theme.zIndex.modal};
+  theme,
+  topModalOverride
+}) => `${topModalOverride ? theme.zIndex.notification : theme.zIndex.modal}`};
 
   ${({
   transitionName,

package/esm/components/select/filterable-select/filterable-select.component.js

@@ -77,6 +77,7 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = useRef(null);
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
     Logger.deprecate("The `inputRef` prop in `Filterable Select` component is deprecated and will soon be removed. Please use `ref` instead.");
@@ -306,18 +307,26 @@ const FilterableSelect = /*#__PURE__*/React.forwardRef(({
   function handleTextboxFocus(event) {
     const triggerFocus = () => onFocus?.(event);
     if (openOnFocus) {
-      setOpen(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpen(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onFocus && !isInputFocused.current) {
+            triggerFocus();
+            isInputFocused.current = true;
+          }
+          if (isMouseDownReported.current && !isMouseDownOnInput.current) {
+            return false;
+          }
           return true;
-        }
-        if (onFocus && !isInputFocused.current) {
-          triggerFocus();
-          isInputFocused.current = true;
-        }
-        if (isMouseDownReported.current && !isMouseDownOnInput.current) {
-          return false;
-        }
-        return true;
+        });
       });
     } else if (onFocus && !isInputFocused.current) {
       triggerFocus();

package/esm/components/select/multi-select/multi-select.component.js

@@ -82,6 +82,7 @@ const MultiSelect = /*#__PURE__*/React.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = useRef(null);
   const actualValue = isControlled.current ? value : selectedValue;
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
@@ -312,21 +313,29 @@ const MultiSelect = /*#__PURE__*/React.forwardRef(({
   function handleTextboxFocus(event) {
     const triggerFocus = () => onFocus?.(event);
     if (openOnFocus) {
-      setOpenState(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpenState(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onOpen) {
+            onOpen();
+          }
+          if (onFocus && !isInputFocused.current) {
+            triggerFocus();
+            isInputFocused.current = true;
+          }
+          if (isMouseDownReported.current && !isMouseDownOnInput.current) {
+            return false;
+          }
           return true;
-        }
-        if (onOpen) {
-          onOpen();
-        }
-        if (onFocus && !isInputFocused.current) {
-          triggerFocus();
-          isInputFocused.current = true;
-        }
-        if (isMouseDownReported.current && !isMouseDownOnInput.current) {
-          return false;
-        }
-        return true;
+        });
       });
     } else if (onFocus && !isInputFocused.current) {
       triggerFocus();

package/esm/components/select/simple-select/simple-select.component.js

@@ -72,6 +72,7 @@ const SimpleSelect = /*#__PURE__*/React.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = useRef(null);
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
     Logger.deprecate("The `inputRef` prop in `Simple Select` component is deprecated and will soon be removed. Please use `ref` instead.");
@@ -235,14 +236,22 @@ const SimpleSelect = /*#__PURE__*/React.forwardRef(({
       return;
     }
     if (openOnFocus) {
-      setOpenState(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpenState(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onOpen) {
+            onOpen();
+          }
           return true;
-        }
-        if (onOpen) {
-          onOpen();
-        }
-        return true;
+        });
       });
     }
   }

package/esm/components/sidebar/sidebar.component.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import { PaddingProps, WidthProps } from "styled-system";
+import { ModalProps } from "../modal";
 import { TagProps } from "../../__internal__/utils/helpers/tags/tags";
 declare type CustomRefObject<T> = {
     current?: T | null;
@@ -8,7 +9,7 @@ export interface SidebarContextProps {
     isInSidebar?: boolean;
 }
 export declare const SidebarContext: React.Context<SidebarContextProps>;
-export interface SidebarProps extends PaddingProps, TagProps, WidthProps {
+export interface SidebarProps extends PaddingProps, TagProps, WidthProps, Pick<ModalProps, "topModalOverride"> {
     /** Prop to specify the aria-describedby property of the component */
     "aria-describedby"?: string;
     /**

package/esm/components/sidebar/sidebar.component.js

@@ -37,6 +37,7 @@ const Sidebar = /*#__PURE__*/React.forwardRef(({
   focusableSelectors,
   width,
   headerPadding = {},
+  topModalOverride,
   ...rest
 }, ref) => {
   const locale = useLocale();
@@ -102,7 +103,8 @@ const Sidebar = /*#__PURE__*/React.forwardRef(({
     open: open,
     onCancel: onCancel,
     disableEscKey: disableEscKey,
-    enableBackgroundUI: enableBackgroundUI
+    enableBackgroundUI: enableBackgroundUI,
+    topModalOverride: topModalOverride
   }, componentTags), enableBackgroundUI ? sidebar : /*#__PURE__*/React.createElement(FocusTrap, {
     wrapperRef: sidebarRef,
     isOpen: open,
@@ -460,6 +462,7 @@ Sidebar.propTypes = {
   }), PropTypes.string]),
   "role": PropTypes.string,
   "size": PropTypes.oneOf(["extra-large", "extra-small", "large", "medium-large", "medium-small", "medium", "small"]),
+  "topModalOverride": PropTypes.bool,
   "width": PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.oneOf([null]), PropTypes.number, PropTypes.shape({
     "__@iterator": PropTypes.func.isRequired,
     "anchor": PropTypes.func.isRequired,

package/esm/components/toast/toast.component.js

@@ -53,7 +53,8 @@ const Toast = /*#__PURE__*/React.forwardRef(({
   useModalManager({
     open,
     closeModal: dismissToast,
-    modalRef: refToPass
+    modalRef: refToPass,
+    topModalOverride: true
   });
   useEffect(() => {
     /* istanbul ignore next */

package/esm/hooks/__internal__/useModalManager/useModalManager.d.ts

@@ -5,6 +5,7 @@ declare type UseModalManagerArgs = {
     modalRef: React.RefObject<HTMLElement>;
     setTriggerRefocusFlag?: (flag: boolean) => void;
     triggerRefocusOnClose?: boolean;
+    topModalOverride?: boolean;
 };
-declare const useModalManager: ({ open, closeModal, modalRef, setTriggerRefocusFlag, triggerRefocusOnClose, }: UseModalManagerArgs) => void;
+declare const useModalManager: ({ open, closeModal, modalRef, setTriggerRefocusFlag, triggerRefocusOnClose, topModalOverride, }: UseModalManagerArgs) => void;
 export default useModalManager;

package/esm/hooks/__internal__/useModalManager/useModalManager.js

@@ -5,7 +5,8 @@ const useModalManager = ({
   closeModal,
   modalRef,
   setTriggerRefocusFlag,
-  triggerRefocusOnClose = true
+  triggerRefocusOnClose = true,
+  topModalOverride = false
 }) => {
   const listenerAdded = useRef(false);
   const modalRegistered = useRef(false);
@@ -43,10 +44,10 @@ const useModalManager = ({
   const registerModal = useCallback(ref => {
     /* istanbul ignore else */
     if (!modalRegistered.current) {
-      ModalManager.addModal(ref, setTriggerRefocusFlag);
+      ModalManager.addModal(ref, setTriggerRefocusFlag, topModalOverride);
       modalRegistered.current = true;
     }
-  }, [setTriggerRefocusFlag]);
+  }, [setTriggerRefocusFlag, topModalOverride]);
   const unregisterModal = useCallback(ref => {
     if (modalRegistered.current) {
       ModalManager.removeModal(ref, triggerRefocusOnClose);

package/lib/__internal__/checkable-input/hidden-checkable-input.component.js

@@ -71,6 +71,7 @@ const HiddenCheckableInput = /*#__PURE__*/_react.default.forwardRef(({
     "aria-describedby": combinedDescription,
     "aria-labelledby": ariaLabelledBy,
     autoFocus: autoFocus,
+    "data-has-autofocus": autoFocus ? true : undefined,
     "aria-checked": checked,
     checked: checked,
     name: name,

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

@@ -99,7 +99,8 @@ const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWra
   const isTop = position === "top";
   const currentIndex = trapWrappers.indexOf(guardWrapperRef);
   let index = currentIndex;
-  let nextWrapper, allFocusableElementsInNextWrapper;
+  let nextWrapper;
+  let allFocusableElementsInNextWrapper;
   do {
     index += isTop ? -1 : 1;
     if (index < 0) {
@@ -109,7 +110,7 @@ const onTabGuardFocus = (trapWrappers, focusableSelectors, position) => guardWra
       index -= trapWrappers.length;
     }
     nextWrapper = trapWrappers[index];
-    allFocusableElementsInNextWrapper = nextWrapper?.current?.querySelectorAll(focusableSelectors || defaultFocusableSelectors);
+    allFocusableElementsInNextWrapper = Array.from(nextWrapper?.current?.querySelectorAll(focusableSelectors || defaultFocusableSelectors) || /* istanbul ignore next */[]).filter(el => Number(el.tabIndex) !== -1);
   } while (index !== currentIndex && !allFocusableElementsInNextWrapper?.length);
   const toFocus = allFocusableElementsInNextWrapper?.[isTop ? allFocusableElementsInNextWrapper.length - 1 : 0];
   if (isRadio(toFocus)) {

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

@@ -84,16 +84,6 @@ const FocusTrap = ({
   }, [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;
-      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 => {
@@ -104,6 +94,17 @@ const FocusTrap = ({
     });
     return elements;
   }, [trapWrappers]);
+  (0, _react.useEffect)(() => {
+    if (shouldSetFocus && !prevShouldSetFocus) {
+      const candidateFirstElement = focusFirstElement && "current" in focusFirstElement ? focusFirstElement.current : focusFirstElement;
+      const autoFocusedElement = getFocusableElements(_focusTrapUtils.defaultFocusableSelectors).find(el => el.getAttribute("data-has-autofocus") === "true");
+      const elementToFocus = candidateFirstElement || autoFocusedElement || wrapperRef.current;
+      // istanbul ignore else
+      if (elementToFocus) {
+        (0, _focusTrapUtils.setElementFocus)(elementToFocus);
+      }
+    }
+  }, [shouldSetFocus, prevShouldSetFocus, getFocusableElements, focusFirstElement, wrapperRef]);
   (0, _react.useEffect)(() => {
     const trapFn = ev => {
       // block focus trap from working if it's not the topmost trap, or is currently closed

package/lib/__internal__/input/input.component.js

@@ -140,6 +140,7 @@ const Input = /*#__PURE__*/_react.default.forwardRef(({
   }
   const combinedDescription = descriptionList.length ? descriptionList.filter(Boolean).join(" ") : undefined;
   return /*#__PURE__*/_react.default.createElement(_input.default, _extends({}, rest, {
+    "data-has-autofocus": autoFocus ? true : undefined,
     "aria-describedby": combinedDescription,
     "aria-labelledby": ariaLabelledBy,
     align: align,

package/lib/components/alert/alert.component.d.ts

@@ -1,4 +1,4 @@
 import React from "react";
 import { DialogProps } from "../dialog";
-export declare const Alert: ({ children, size, ...rest }: DialogProps) => React.JSX.Element;
+export declare const Alert: ({ children, size, topModalOverride, ...rest }: DialogProps) => React.JSX.Element;
 export default Alert;

package/lib/components/alert/alert.component.js

@@ -12,11 +12,13 @@ function _extends() { _extends = Object.assign ? Object.assign.bind() : function
 const Alert = ({
   children,
   size = "extra-small",
+  topModalOverride,
   ...rest
 }) => /*#__PURE__*/_react.default.createElement(_dialog.default, _extends({
   "data-component": "alert",
   role: "alertdialog",
-  size: size
+  size: size,
+  topModalOverride: topModalOverride
 }, rest), children);
 exports.Alert = Alert;
 var _default = Alert;

package/lib/components/confirm/confirm.component.d.ts

@@ -38,5 +38,5 @@ export interface ConfirmProps extends Omit<DialogProps, "className" | "disableFo
     /** A custom event handler when a confirmation takes place */
     onConfirm: (ev: React.MouseEvent<HTMLButtonElement>) => void;
 }
-export declare const Confirm: ({ "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, open, children, cancelButtonDestructive, confirmButtonDestructive, cancelButtonType, confirmButtonType, cancelButtonIconType, cancelButtonIconPosition, confirmButtonIconType, confirmButtonIconPosition, cancelButtonDataProps, confirmButtonDataProps, cancelLabel, onCancel, disableCancel, onConfirm, isLoadingConfirm, disableConfirm, confirmLabel, iconType, subtitle, title, size, showCloseIcon, ...rest }: ConfirmProps) => React.JSX.Element;
+export declare const Confirm: ({ "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, open, children, cancelButtonDestructive, confirmButtonDestructive, cancelButtonType, confirmButtonType, cancelButtonIconType, cancelButtonIconPosition, confirmButtonIconType, confirmButtonIconPosition, cancelButtonDataProps, confirmButtonDataProps, cancelLabel, onCancel, disableCancel, onConfirm, isLoadingConfirm, disableConfirm, confirmLabel, iconType, subtitle, title, size, showCloseIcon, topModalOverride, ...rest }: ConfirmProps) => React.JSX.Element;
 export default Confirm;

package/lib/components/confirm/confirm.component.js

@@ -47,6 +47,7 @@ const Confirm = ({
   title,
   size = "extra-small",
   showCloseIcon = false,
+  topModalOverride,
   ...rest
 }) => {
   const l = (0, _useLocale.default)();
@@ -123,7 +124,8 @@ const Confirm = ({
     "data-component": "confirm",
     role: "alertdialog",
     size: size,
-    showCloseIcon: showCloseIcon
+    showCloseIcon: showCloseIcon,
+    topModalOverride: topModalOverride
   }, ariaProps, rest), children, /*#__PURE__*/_react.default.createElement(_confirm.StyledConfirmButtons, null, renderCancelButton(), renderConfirmButton()));
 };
 exports.Confirm = Confirm;

package/lib/components/dialog/dialog.component.js

@@ -43,6 +43,7 @@ const Dialog = /*#__PURE__*/(0, _react.forwardRef)(({
   role = "dialog",
   contentPadding = {},
   focusableContainers,
+  topModalOverride,
   ...rest
 }, ref) => {
   const locale = (0, _useLocale.default)();
@@ -163,7 +164,8 @@ const Dialog = /*#__PURE__*/(0, _react.forwardRef)(({
     onCancel: onCancel,
     disableEscKey: disableEscKey,
     disableClose: disableClose,
-    className: className ? `${className} carbon-dialog` : "carbon-dialog"
+    className: className ? `${className} carbon-dialog` : "carbon-dialog",
+    topModalOverride: topModalOverride
   }, componentTags), /*#__PURE__*/_react.default.createElement(_focusTrap.default, {
     autoFocus: !disableAutoFocus,
     focusFirstElement: focusFirstElement,
@@ -244,7 +246,8 @@ Dialog.propTypes = {
   "size": _propTypes.default.oneOf(["auto", "extra-large", "extra-small", "large", "medium-large", "medium-small", "medium", "small"]),
   "subtitle": _propTypes.default.string,
   "timeout": _propTypes.default.number,
-  "title": _propTypes.default.node
+  "title": _propTypes.default.node,
+  "topModalOverride": _propTypes.default.bool
 };
 var _default = Dialog;
 exports.default = _default;

package/lib/components/dialog-full-screen/dialog-full-screen.component.d.ts

@@ -52,5 +52,5 @@ export interface DialogFullScreenProps extends ModalProps {
     /** A custom close event handler */
     onCancel?: (ev: React.KeyboardEvent<HTMLElement> | React.MouseEvent<HTMLButtonElement>) => void;
 }
-export declare const DialogFullScreen: ({ "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disableAutoFocus, focusFirstElement, bespokeFocusTrap, open, children, title, subtitle, pagesStyling, headerChildren, showCloseIcon, disableContentPadding, disableEscKey, onCancel, contentRef, help, role, focusableContainers, focusableSelectors, ...rest }: DialogFullScreenProps) => React.JSX.Element;
+export declare const DialogFullScreen: ({ "aria-describedby": ariaDescribedBy, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disableAutoFocus, focusFirstElement, bespokeFocusTrap, open, children, title, subtitle, pagesStyling, headerChildren, showCloseIcon, disableContentPadding, disableEscKey, onCancel, contentRef, help, role, focusableContainers, focusableSelectors, topModalOverride, ...rest }: DialogFullScreenProps) => React.JSX.Element;
 export default DialogFullScreen;

package/lib/components/dialog-full-screen/dialog-full-screen.component.js

@@ -44,6 +44,7 @@ const DialogFullScreen = ({
   role = "dialog",
   focusableContainers,
   focusableSelectors,
+  topModalOverride,
   ...rest
 }) => {
   const locale = (0, _useLocale.default)();
@@ -92,7 +93,8 @@ const DialogFullScreen = ({
   return /*#__PURE__*/_react.default.createElement(_modal.default, _extends({
     open: open,
     onCancel: onCancel,
-    disableEscKey: disableEscKey
+    disableEscKey: disableEscKey,
+    topModalOverride: topModalOverride
   }, componentTags), /*#__PURE__*/_react.default.createElement(_focusTrap.default, {
     autoFocus: !disableAutoFocus,
     focusFirstElement: focusFirstElement,

package/lib/components/modal/__internal__/modal-manager.d.ts

@@ -2,12 +2,13 @@ declare type SetTriggerRefocusFlag = (boolean: boolean) => void;
 export declare type ModalList = {
     modal: HTMLElement;
     setTriggerRefocusFlag?: SetTriggerRefocusFlag;
+    topModalOverride?: boolean;
 }[];
 declare class ModalManagerInstance {
     private modalList;
     constructor();
     private getTopModal;
-    addModal: (modal: HTMLElement | null, setTriggerRefocusFlag?: SetTriggerRefocusFlag) => void;
+    addModal: (modal: HTMLElement | null, setTriggerRefocusFlag?: SetTriggerRefocusFlag, topModalOverride?: boolean) => void;
     isTopmost(modal: HTMLElement | null): boolean;
     removeModal(modal: HTMLElement | null, triggerRefocusOnClose?: boolean): void;
     clearList(): void;

package/lib/components/modal/__internal__/modal-manager.js

@@ -14,20 +14,22 @@ let ModalManagerInstance = /*#__PURE__*/function () {
   function ModalManagerInstance() {
     _classCallCheck(this, ModalManagerInstance);
     _defineProperty(this, "modalList", void 0);
-    _defineProperty(this, "addModal", (modal, setTriggerRefocusFlag) => {
+    _defineProperty(this, "addModal", (modal, setTriggerRefocusFlag, topModalOverride) => {
       if (!modal) {
         return;
       }
       const {
         modal: topModal,
-        setTriggerRefocusFlag: setTrapFlag
+        setTriggerRefocusFlag: setTrapFlag,
+        topModalOverride: topOverridden
       } = this.getTopModal();
-      if (topModal && setTrapFlag) {
+      if (!topOverridden && topModal && setTrapFlag) {
         setTrapFlag(false);
       }
       this.modalList.push({
         modal,
-        setTriggerRefocusFlag
+        setTriggerRefocusFlag,
+        topModalOverride
       });
       this.callTopModalSetters();
     });
@@ -44,7 +46,8 @@ let ModalManagerInstance = /*#__PURE__*/function () {
       if (!this.modalList.length) {
         return {};
       }
-      return this.modalList[this.modalList.length - 1];
+      const topModalOverride = this.modalList.slice().reverse().find(modal => modal.topModalOverride);
+      return topModalOverride || this.modalList[this.modalList.length - 1];
     }
   }, {
     key: "isTopmost",

package/lib/components/modal/modal.component.d.ts

@@ -25,6 +25,8 @@ export interface ModalProps extends TagProps {
     open: boolean;
     /** Transition time */
     timeout?: number;
+    /** Manually override the internal modal stacking order to set this as top */
+    topModalOverride?: boolean;
 }
-declare const Modal: ({ children, open, onCancel, disableEscKey, disableClose, enableBackgroundUI, timeout, ...rest }: ModalProps) => React.JSX.Element;
+declare const Modal: ({ children, open, onCancel, disableEscKey, disableClose, enableBackgroundUI, timeout, topModalOverride, ...rest }: ModalProps) => React.JSX.Element;
 export default Modal;

package/lib/components/modal/modal.component.js

@@ -26,6 +26,7 @@ const Modal = ({
   disableClose,
   enableBackgroundUI = false,
   timeout = 300,
+  topModalOverride,
   ...rest
 }) => {
   const ref = (0, _react.useRef)(null);
@@ -64,7 +65,8 @@ const Modal = ({
     open,
     closeModal,
     modalRef: ref,
-    setTriggerRefocusFlag
+    setTriggerRefocusFlag,
+    topModalOverride
   });
   let background;
   let content;
@@ -81,6 +83,7 @@ const Modal = ({
     "data-state": open ? "open" : "closed",
     transitionName: "modal",
     transitionTime: timeout,
+    topModalOverride: topModalOverride,
     ref: ref
   }, rest), /*#__PURE__*/_react.default.createElement(_reactTransitionGroup.TransitionGroup, null, background && /*#__PURE__*/_react.default.createElement(_reactTransitionGroup.CSSTransition, {
     nodeRef: backgroundNodeRef,

package/lib/components/modal/modal.style.d.ts

@@ -3,5 +3,7 @@ declare type TransitionProps = {
     transitionTime: number;
 };
 declare const StyledModalBackground: import("styled-components").StyledComponent<"div", any, TransitionProps, never>;
-declare const StyledModal: import("styled-components").StyledComponent<"div", any, TransitionProps, never>;
+declare const StyledModal: import("styled-components").StyledComponent<"div", any, TransitionProps & {
+    topModalOverride?: boolean | undefined;
+}, never>;
 export { StyledModal, StyledModalBackground };

package/lib/components/modal/modal.style.js

@@ -47,8 +47,9 @@ exports.StyledModalBackground = StyledModalBackground;
 const StyledModal = _styledComponents.default.div`
   position: absolute;
   z-index: ${({
-  theme
-}) => theme.zIndex.modal};
+  theme,
+  topModalOverride
+}) => `${topModalOverride ? theme.zIndex.notification : theme.zIndex.modal}`};
 
   ${({
   transitionName,

package/lib/components/select/filterable-select/filterable-select.component.js

@@ -86,6 +86,7 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = (0, _react.useRef)(null);
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
     _logger.default.deprecate("The `inputRef` prop in `Filterable Select` component is deprecated and will soon be removed. Please use `ref` instead.");
@@ -315,18 +316,26 @@ const FilterableSelect = /*#__PURE__*/_react.default.forwardRef(({
   function handleTextboxFocus(event) {
     const triggerFocus = () => onFocus?.(event);
     if (openOnFocus) {
-      setOpen(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpen(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onFocus && !isInputFocused.current) {
+            triggerFocus();
+            isInputFocused.current = true;
+          }
+          if (isMouseDownReported.current && !isMouseDownOnInput.current) {
+            return false;
+          }
           return true;
-        }
-        if (onFocus && !isInputFocused.current) {
-          triggerFocus();
-          isInputFocused.current = true;
-        }
-        if (isMouseDownReported.current && !isMouseDownOnInput.current) {
-          return false;
-        }
-        return true;
+        });
       });
     } else if (onFocus && !isInputFocused.current) {
       triggerFocus();

package/lib/components/select/multi-select/multi-select.component.js

@@ -91,6 +91,7 @@ const MultiSelect = /*#__PURE__*/_react.default.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = (0, _react.useRef)(null);
   const actualValue = isControlled.current ? value : selectedValue;
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
@@ -321,21 +322,29 @@ const MultiSelect = /*#__PURE__*/_react.default.forwardRef(({
   function handleTextboxFocus(event) {
     const triggerFocus = () => onFocus?.(event);
     if (openOnFocus) {
-      setOpenState(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpenState(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onOpen) {
+            onOpen();
+          }
+          if (onFocus && !isInputFocused.current) {
+            triggerFocus();
+            isInputFocused.current = true;
+          }
+          if (isMouseDownReported.current && !isMouseDownOnInput.current) {
+            return false;
+          }
           return true;
-        }
-        if (onOpen) {
-          onOpen();
-        }
-        if (onFocus && !isInputFocused.current) {
-          triggerFocus();
-          isInputFocused.current = true;
-        }
-        if (isMouseDownReported.current && !isMouseDownOnInput.current) {
-          return false;
-        }
-        return true;
+        });
       });
     } else if (onFocus && !isInputFocused.current) {
       triggerFocus();

package/lib/components/select/simple-select/simple-select.component.js

@@ -81,6 +81,7 @@ const SimpleSelect = /*#__PURE__*/_react.default.forwardRef(({
     id: inputId.current,
     label
   });
+  const focusTimer = (0, _react.useRef)(null);
   if (!deprecateInputRefWarnTriggered && inputRef) {
     deprecateInputRefWarnTriggered = true;
     _logger.default.deprecate("The `inputRef` prop in `Simple Select` component is deprecated and will soon be removed. Please use `ref` instead.");
@@ -244,14 +245,22 @@ const SimpleSelect = /*#__PURE__*/_react.default.forwardRef(({
       return;
     }
     if (openOnFocus) {
-      setOpenState(isAlreadyOpen => {
-        if (isAlreadyOpen) {
+      if (focusTimer.current) {
+        clearTimeout(focusTimer.current);
+      }
+
+      // we need to use a timeout here as there is a race condition when rendered in a modal
+      // whereby the select list isn't visible when the select is auto focused straight away
+      focusTimer.current = setTimeout(() => {
+        setOpenState(isAlreadyOpen => {
+          if (isAlreadyOpen) {
+            return true;
+          }
+          if (onOpen) {
+            onOpen();
+          }
           return true;
-        }
-        if (onOpen) {
-          onOpen();
-        }
-        return true;
+        });
       });
     }
   }

package/lib/components/sidebar/sidebar.component.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import { PaddingProps, WidthProps } from "styled-system";
+import { ModalProps } from "../modal";
 import { TagProps } from "../../__internal__/utils/helpers/tags/tags";
 declare type CustomRefObject<T> = {
     current?: T | null;
@@ -8,7 +9,7 @@ export interface SidebarContextProps {
     isInSidebar?: boolean;
 }
 export declare const SidebarContext: React.Context<SidebarContextProps>;
-export interface SidebarProps extends PaddingProps, TagProps, WidthProps {
+export interface SidebarProps extends PaddingProps, TagProps, WidthProps, Pick<ModalProps, "topModalOverride"> {
     /** Prop to specify the aria-describedby property of the component */
     "aria-describedby"?: string;
     /**

package/lib/components/sidebar/sidebar.component.js

@@ -46,6 +46,7 @@ const Sidebar = /*#__PURE__*/_react.default.forwardRef(({
   focusableSelectors,
   width,
   headerPadding = {},
+  topModalOverride,
   ...rest
 }, ref) => {
   const locale = (0, _useLocale.default)();
@@ -111,7 +112,8 @@ const Sidebar = /*#__PURE__*/_react.default.forwardRef(({
     open: open,
     onCancel: onCancel,
     disableEscKey: disableEscKey,
-    enableBackgroundUI: enableBackgroundUI
+    enableBackgroundUI: enableBackgroundUI,
+    topModalOverride: topModalOverride
   }, componentTags), enableBackgroundUI ? sidebar : /*#__PURE__*/_react.default.createElement(_focusTrap.default, {
     wrapperRef: sidebarRef,
     isOpen: open,
@@ -470,6 +472,7 @@ Sidebar.propTypes = {
   }), _propTypes.default.string]),
   "role": _propTypes.default.string,
   "size": _propTypes.default.oneOf(["extra-large", "extra-small", "large", "medium-large", "medium-small", "medium", "small"]),
+  "topModalOverride": _propTypes.default.bool,
   "width": _propTypes.default.oneOfType([_propTypes.default.arrayOf(_propTypes.default.oneOfType([_propTypes.default.oneOf([null]), _propTypes.default.number, _propTypes.default.shape({
     "__@iterator": _propTypes.default.func.isRequired,
     "anchor": _propTypes.default.func.isRequired,

package/lib/components/toast/toast.component.js

@@ -62,7 +62,8 @@ const Toast = /*#__PURE__*/_react.default.forwardRef(({
   (0, _useModalManager.default)({
     open,
     closeModal: dismissToast,
-    modalRef: refToPass
+    modalRef: refToPass,
+    topModalOverride: true
   });
   (0, _react.useEffect)(() => {
     /* istanbul ignore next */

package/lib/hooks/__internal__/useModalManager/useModalManager.d.ts

@@ -5,6 +5,7 @@ declare type UseModalManagerArgs = {
     modalRef: React.RefObject<HTMLElement>;
     setTriggerRefocusFlag?: (flag: boolean) => void;
     triggerRefocusOnClose?: boolean;
+    topModalOverride?: boolean;
 };
-declare const useModalManager: ({ open, closeModal, modalRef, setTriggerRefocusFlag, triggerRefocusOnClose, }: UseModalManagerArgs) => void;
+declare const useModalManager: ({ open, closeModal, modalRef, setTriggerRefocusFlag, triggerRefocusOnClose, topModalOverride, }: UseModalManagerArgs) => void;
 export default useModalManager;

package/lib/hooks/__internal__/useModalManager/useModalManager.js

@@ -12,7 +12,8 @@ const useModalManager = ({
   closeModal,
   modalRef,
   setTriggerRefocusFlag,
-  triggerRefocusOnClose = true
+  triggerRefocusOnClose = true,
+  topModalOverride = false
 }) => {
   const listenerAdded = (0, _react.useRef)(false);
   const modalRegistered = (0, _react.useRef)(false);
@@ -50,10 +51,10 @@ const useModalManager = ({
   const registerModal = (0, _react.useCallback)(ref => {
     /* istanbul ignore else */
     if (!modalRegistered.current) {
-      _modalManager.default.addModal(ref, setTriggerRefocusFlag);
+      _modalManager.default.addModal(ref, setTriggerRefocusFlag, topModalOverride);
       modalRegistered.current = true;
     }
-  }, [setTriggerRefocusFlag]);
+  }, [setTriggerRefocusFlag, topModalOverride]);
   const unregisterModal = (0, _react.useCallback)(ref => {
     if (modalRegistered.current) {
       _modalManager.default.removeModal(ref, triggerRefocusOnClose);

package/package.json

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