@carbon/react 1.107.1 → 1.108.0

package/es/components/Button/Button.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { type ReactNode } from 'react';
+import React from 'react';
 import { IconButtonKind } from '../IconButton';
 import { PolymorphicComponentPropWithRef } from '../../internal/PolymorphicProps';
 export declare const ButtonKinds: readonly ["primary", "secondary", "danger", "ghost", "danger--primary", "danger--ghost", "danger--tertiary", "tertiary"];
@@ -82,6 +82,6 @@ export interface ButtonBaseProps extends React.ButtonHTMLAttributes<HTMLButtonEl
     tooltipPosition?: ButtonTooltipPosition;
 }
 export type ButtonProps<T extends React.ElementType> = PolymorphicComponentPropWithRef<T, ButtonBaseProps>;
-export type ButtonComponent = <T extends React.ElementType = 'button'>(props: ButtonProps<T>) => ReactNode;
+export type ButtonComponent = <T extends React.ElementType = 'button'>(props: ButtonProps<T>, context?: any) => React.ReactElement | any;
 declare const _default: ButtonComponent;
 export default _default;

package/es/components/Button/ButtonBase.js

@@ -17,7 +17,7 @@ import { jsx } from "react/jsx-runtime";
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
-const ButtonBase = React.forwardRef(function ButtonBase({ as, children, className, dangerDescription = "danger", disabled = false, hasIconOnly = false, href, iconDescription, isExpressive = false, isSelected, kind = "primary", onBlur, onClick, onFocus, onMouseEnter, onMouseLeave, renderIcon: ButtonImageElement, size, tabIndex, type = "button", ...rest }, ref) {
+const ButtonBase = React.forwardRef(function ButtonBase({ as, children, className, dangerDescription = "", disabled = false, hasIconOnly = false, href, iconDescription, isExpressive = false, isSelected, kind = "primary", onBlur, onClick, onFocus, onMouseEnter, onMouseLeave, renderIcon: ButtonImageElement, size, tabIndex, type = "button", ...rest }, ref) {
 	const prefix = usePrefix();
 	const commonProps = {
 		tabIndex,
@@ -43,23 +43,23 @@ const ButtonBase = React.forwardRef(function ButtonBase({ as, children, classNam
 		className: `${prefix}--btn__icon`,
 		"aria-hidden": "true"
 	});
-	const dangerButtonVariants = [
+	const hasDangerDescription = [
 		"danger",
 		"danger--tertiary",
 		"danger--ghost"
-	];
+	].includes(kind) && Boolean(dangerDescription);
 	let component = "button";
 	const assistiveId = useId("danger-description");
 	const { "aria-pressed": ariaPressed, "aria-describedby": ariaDescribedBy } = rest;
 	let otherProps = {
 		disabled,
 		type,
-		"aria-describedby": dangerButtonVariants.includes(kind) ? assistiveId : ariaDescribedBy || void 0,
+		"aria-describedby": hasDangerDescription ? assistiveId : ariaDescribedBy || void 0,
 		"aria-pressed": ariaPressed ?? (hasIconOnly && kind === "ghost" ? isSelected : void 0)
 	};
 	const anchorProps = { href };
 	let assistiveText = null;
-	if (dangerButtonVariants.includes(kind)) assistiveText = /* @__PURE__ */ jsx("span", {
+	if (hasDangerDescription) assistiveText = /* @__PURE__ */ jsx("span", {
 		id: assistiveId,
 		className: `${prefix}--visually-hidden`,
 		children: dangerDescription

package/es/components/ChatButton/ChatButton.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2024, 2025
+ * Copyright IBM Corp. 2024, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.

package/es/components/ChatButton/ChatButton.js

@@ -13,7 +13,7 @@ import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/ChatButton/ChatButton.tsx
 /**
-* Copyright IBM Corp. 2024, 2025
+* Copyright IBM Corp. 2024, 2026
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.

package/es/components/ComposedModal/ComposedModal.js

@@ -26,6 +26,7 @@ import { elementOrParentIsFloatingMenu, wrapFocus, wrapFocusWithoutSentinels } f
 import { Dialog } from "../Dialog/Dialog.js";
 import { useComposedModalState } from "./useComposedModalState.js";
 import { ComposedModalPresence, ComposedModalPresenceContext, useExclusiveComposedModalPresenceContext } from "./ComposedModalPresence.js";
+import { isTopmostVisibleModal } from "../Modal/isTopmostVisibleModal.js";
 import classNames from "classnames";
 import React, { Children, cloneElement, useContext, useEffect, useRef } from "react";
 import PropTypes from "prop-types";
@@ -98,9 +99,14 @@ const ComposedModalDialog = React.forwardRef(function ComposedModalDialog({ ["ar
 	const button = useRef(null);
 	const startSentinel = useRef(null);
 	const endSentinel = useRef(null);
+	const modalRef = useRef(null);
 	const onMouseDownTarget = useRef(null);
 	const presenceContext = useContext(ComposedModalPresenceContext);
-	const mergedRefs = useMergeRefs([ref, presenceContext?.presenceRef]);
+	const mergedRefs = useMergeRefs([
+		modalRef,
+		ref,
+		presenceContext?.presenceRef
+	]);
 	const enablePresence = useFeatureFlag("enable-presence") || presenceContext?.autoEnablePresence;
 	const open = externalOpen || enablePresence;
 	const modalState = useComposedModalState(open);
@@ -184,15 +190,14 @@ const ComposedModalDialog = React.forwardRef(function ComposedModalDialog({ ["ar
 	useEffect(() => {
 		if (!open) return;
 		const handleEscapeKey = (event) => {
-			if (match(event, Escape)) {
+			if (match(event, Escape) && isTopmostVisibleModal(modalRef.current, prefix)) {
 				event.preventDefault();
-				event.stopPropagation();
 				closeModal(event);
 			}
 		};
-		document.addEventListener("keydown", handleEscapeKey, true);
+		document.addEventListener("keydown", handleEscapeKey);
 		return () => {
-			document.removeEventListener("keydown", handleEscapeKey, true);
+			document.removeEventListener("keydown", handleEscapeKey);
 		};
 	}, [open]);
 	useEffect(() => {

package/es/components/ComposedModal/ModalFooter.d.ts

@@ -36,6 +36,11 @@ export interface ModalFooterProps {
      * Note that this prop is not applied if you render primary/danger button by yourself
      */
     danger?: boolean;
+    /**
+     * Specify the message read by screen readers for the danger primary button.
+     * Defaults to an empty string; provide localized text to opt in.
+     */
+    dangerDescription?: string;
     /**
      * The `ref` callback for the primary button.
      */

package/es/components/ComposedModal/ModalFooter.js

@@ -61,7 +61,7 @@ SecondaryButtonSet.propTypes = {
 	},
 	secondaryClassName: PropTypes.string
 };
-const ModalFooter = React.forwardRef(function ModalFooter({ children, className: customClassName, closeModal = noopFn, danger, inputref, onRequestClose = noopFn, onRequestSubmit = noopFn, primaryButtonDisabled, primaryButtonText, primaryClassName, secondaryButtonText, secondaryButtons, secondaryClassName, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, ...rest }, ref) {
+const ModalFooter = React.forwardRef(function ModalFooter({ children, className: customClassName, closeModal = noopFn, danger, dangerDescription = "", inputref, onRequestClose = noopFn, onRequestSubmit = noopFn, primaryButtonDisabled, primaryButtonText, primaryClassName, secondaryButtonText, secondaryButtons, secondaryClassName, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, ...rest }, ref) {
 	const prefix = usePrefix();
 	const footerClass = classNames(`${prefix}--modal-footer`, customClassName, Array.isArray(secondaryButtons) && secondaryButtons.length === 2 ? `${prefix}--modal-footer--three-button` : null);
 	const primaryButtonClass = classNames(primaryClassName, loadingStatus !== "inactive" ? `${prefix}--btn--loading` : null);
@@ -85,6 +85,7 @@ const ModalFooter = React.forwardRef(function ModalFooter({ children, className:
 				onClick: onRequestSubmit,
 				className: primaryButtonClass,
 				disabled: loadingActive || primaryButtonDisabled,
+				dangerDescription,
 				kind: danger ? "danger" : "primary",
 				ref: inputref,
 				children: loadingStatus === "inactive" ? primaryButtonText : /* @__PURE__ */ jsx(InlineLoading_default, {
@@ -104,6 +105,7 @@ ModalFooter.propTypes = {
 	className: PropTypes.string,
 	closeModal: PropTypes.func,
 	danger: PropTypes.bool,
+	dangerDescription: PropTypes.string,
 	inputref: PropTypes.oneOfType([PropTypes.func, PropTypes.shape({ current: PropTypes.any })]),
 	loadingDescription: PropTypes.string,
 	loadingIconDescription: PropTypes.string,

package/es/components/Dialog/Dialog.d.ts

@@ -232,6 +232,11 @@ interface DialogFooterProps extends HTMLAttributes<HTMLDivElement> {
      * Specify whether the Dialog is for dangerous actions
      */
     danger?: boolean;
+    /**
+     * Specify the message read by screen readers for the danger primary button.
+     * Defaults to an empty string; provide localized text to opt in.
+     */
+    dangerDescription?: string;
     /**
      * Specify loading status
      */

package/es/components/Dialog/Dialog.js

@@ -248,7 +248,7 @@ DialogBody.propTypes = {
 	className: PropTypes.string,
 	hasScrollingContent: PropTypes.bool
 };
-const DialogFooter = React.forwardRef(({ children, className, onRequestClose = noopFn, onSecondarySubmit, onRequestSubmit = noopFn, primaryButtonText = "Save", primaryButtonDisabled = false, secondaryButtonText = "Cancel", secondaryButtons, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, danger = false, ...rest }, ref) => {
+const DialogFooter = React.forwardRef(({ children, className, onRequestClose = noopFn, onSecondarySubmit, onRequestSubmit = noopFn, primaryButtonText = "Save", primaryButtonDisabled = false, secondaryButtonText = "Cancel", secondaryButtons, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, danger = false, dangerDescription = "", ...rest }, ref) => {
 	const prefix = usePrefix();
 	const button = useRef(null);
 	const { isOpen } = useContext(DialogContext);
@@ -296,6 +296,7 @@ const DialogFooter = React.forwardRef(({ children, className, onRequestClose = n
 		}), /* @__PURE__ */ jsx(Button_default, {
 			className: primaryButtonClass,
 			kind: danger ? "danger" : "primary",
+			dangerDescription,
 			disabled: loadingActive || primaryButtonDisabled,
 			onClick: onRequestSubmit,
 			ref: button,
@@ -333,6 +334,7 @@ DialogFooter.propTypes = {
 		return null;
 	},
 	danger: PropTypes.bool,
+	dangerDescription: PropTypes.string,
 	loadingStatus: PropTypes.oneOf([
 		"inactive",
 		"active",

package/es/components/ErrorBoundary/ErrorBoundaryContext.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.

package/es/components/ErrorBoundary/ErrorBoundaryContext.js

@@ -8,7 +8,7 @@
 import { createContext } from "react";
 //#region src/components/ErrorBoundary/ErrorBoundaryContext.ts
 /**
-* Copyright IBM Corp. 2016, 2023
+* Copyright IBM Corp. 2016, 2026
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.

package/es/components/FileUploader/FileUploader.d.ts

@@ -11,6 +11,7 @@ interface FileItem {
     file: File & {
         invalidFileType?: boolean;
     };
+    disabled?: boolean;
 }
 export interface FileChangeData {
     addedFiles: FileItem[];
@@ -113,6 +114,10 @@ export interface FileUploaderHandle {
      * Get current files (only available when 'enable-enhanced-file-uploader' feature flag is enabled)
      */
     getCurrentFiles?: () => FileItem[];
+    /**
+     * Set current files (only available when 'enable-enhanced-file-uploader' feature flag is enabled)
+     */
+    setCurrentFiles?: (files: FileItem[]) => void;
 }
 declare const FileUploader: {
     (props: FileUploaderProps): React.ReactElement;

package/es/components/FileUploader/FileUploader.js

@@ -154,9 +154,14 @@ const FileUploader = forwardRef(({ accept, buttonKind, buttonLabel, className, d
 				});
 			} else setLegacyFileNames([]);
 		},
-		...enhancedFileUploaderEnabled && { getCurrentFiles() {
-			return [...fileItems];
-		} }
+		...enhancedFileUploaderEnabled && {
+			getCurrentFiles() {
+				return [...fileItems];
+			},
+			setCurrentFiles: (files) => {
+				setFileItems(files);
+			}
+		}
 	}), [
 		enhancedFileUploaderEnabled,
 		fileItems,
@@ -167,12 +172,14 @@ const FileUploader = forwardRef(({ accept, buttonKind, buttonLabel, className, d
 		[className]: className
 	});
 	const getHelperLabelClasses = (baseClass) => classNames(baseClass, { [`${prefix}--label-description--disabled`]: disabled });
-	const selectedFileClasses = classNames(`${prefix}--file__selected-file`, {
+	const getSelectedFileClasses = (file) => classNames(`${prefix}--file__selected-file`, {
 		[`${prefix}--file__selected-file--md`]: size === "field" || size === "md",
-		[`${prefix}--file__selected-file--sm`]: size === "small" || size === "sm"
+		[`${prefix}--file__selected-file--sm`]: size === "small" || size === "sm",
+		[`${prefix}--file__selected-file--disabled`]: file.disabled
 	});
 	const displayFiles = enhancedFileUploaderEnabled ? fileItems.map((item, index) => ({
 		name: item.name,
+		disabled: item.disabled,
 		key: item.uuid,
 		index
 	})) : legacyFileNames.map((name, index) => ({
@@ -211,7 +218,7 @@ const FileUploader = forwardRef(({ accept, buttonKind, buttonLabel, className, d
 			/* @__PURE__ */ jsx("div", {
 				className: `${prefix}--file-container`,
 				children: displayFiles.length === 0 ? null : displayFiles.map((file) => /* @__PURE__ */ jsxs("span", {
-					className: selectedFileClasses,
+					className: getSelectedFileClasses(file),
 					ref: (node) => {
 						nodes[file.index] = node;
 					},
@@ -225,6 +232,7 @@ const FileUploader = forwardRef(({ accept, buttonKind, buttonLabel, className, d
 						className: `${prefix}--file__state-container`,
 						children: /* @__PURE__ */ jsx(Filename, {
 							name: file.name,
+							disabled: file.disabled,
 							iconDescription,
 							status: filenameStatus,
 							onKeyDown: (evt) => {

package/es/components/FileUploader/FileUploaderItem.d.ts

@@ -7,6 +7,10 @@
 import PropTypes from 'prop-types';
 import React, { type HTMLAttributes } from 'react';
 export interface FileUploaderItemProps extends HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Specify whether file uploader item is disabled
+     */
+    disabled?: boolean;
     /**
      * Error message body for an invalid file upload
      */
@@ -52,7 +56,7 @@ export interface FileUploaderItemProps extends HTMLAttributes<HTMLSpanElement> {
      */
     uuid?: string;
 }
-declare function FileUploaderItem({ uuid, name, status, iconDescription, onDelete, invalid, errorSubject, errorBody, size, className, ...other }: FileUploaderItemProps): import("react/jsx-runtime").JSX.Element;
+declare function FileUploaderItem({ uuid, name, status, iconDescription, onDelete, invalid, errorSubject, errorBody, size, className, disabled, ...other }: FileUploaderItemProps): import("react/jsx-runtime").JSX.Element;
 declare namespace FileUploaderItem {
     var propTypes: {
         /**

package/es/components/FileUploader/FileUploaderItem.js

@@ -25,7 +25,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
-function FileUploaderItem({ uuid, name, status = "uploading", iconDescription, onDelete = noopFn, invalid, errorSubject, errorBody, size, className, ...other }) {
+function FileUploaderItem({ uuid, name, status = "uploading", iconDescription, onDelete = noopFn, invalid, errorSubject, errorBody, size, className, disabled, ...other }) {
 	const textRef = useRef(null);
 	const [isEllipsisApplied, setIsEllipsisApplied] = useState(false);
 	const prefix = usePrefix();
@@ -34,7 +34,8 @@ function FileUploaderItem({ uuid, name, status = "uploading", iconDescription, o
 	const classes = classNames(`${prefix}--file__selected-file`, className, {
 		[`${prefix}--file__selected-file--invalid`]: invalid,
 		[`${prefix}--file__selected-file--md`]: size === "md",
-		[`${prefix}--file__selected-file--sm`]: size === "sm"
+		[`${prefix}--file__selected-file--sm`]: size === "sm",
+		[`${prefix}--file__selected-file--disabled`]: disabled
 	});
 	const isInvalid = invalid ? `${prefix}--file-filename-container-wrap-invalid` : `${prefix}--file-filename-container-wrap`;
 	const filterSpaceName = (name) => {
@@ -89,6 +90,7 @@ function FileUploaderItem({ uuid, name, status = "uploading", iconDescription, o
 					className: `${prefix}--file__state-container`,
 					children: /* @__PURE__ */ jsx(Filename, {
 						name,
+						disabled,
 						iconDescription,
 						status,
 						invalid,

package/es/components/FileUploader/Filename.d.ts

@@ -17,6 +17,10 @@ export interface FilenameProps extends Omit<HTMLAttributes<HTMLElement> & SVGAtt
      * Provide a description of the SVG icon to denote file upload status
      */
     iconDescription?: string;
+    /**
+     * Specify whether the file uploader item is disabled
+     */
+    disabled?: boolean;
     /**
      * Specify if the file is invalid
      */
@@ -34,7 +38,7 @@ export interface FilenameProps extends Omit<HTMLAttributes<HTMLElement> & SVGAtt
      */
     tabIndex?: number;
 }
-declare function Filename({ iconDescription, status, invalid, name, tabIndex, ['aria-describedby']: ariaDescribedBy, ...rest }: FilenameProps): import("react/jsx-runtime").JSX.Element | null;
+declare function Filename({ iconDescription, status, invalid, disabled, name, tabIndex, ['aria-describedby']: ariaDescribedBy, ...rest }: FilenameProps): import("react/jsx-runtime").JSX.Element | null;
 declare namespace Filename {
     var propTypes: {
         /**

package/es/components/FileUploader/Filename.js

@@ -18,7 +18,7 @@ import { CheckmarkFilled, Close, WarningFilled } from "@carbon/icons-react";
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
-function Filename({ iconDescription = "Uploading file", status = "uploading", invalid, name, tabIndex = 0, ["aria-describedby"]: ariaDescribedBy, ...rest }) {
+function Filename({ iconDescription = "Uploading file", status = "uploading", invalid, disabled, name, tabIndex = 0, ["aria-describedby"]: ariaDescribedBy, ...rest }) {
 	const prefix = usePrefix();
 	switch (status) {
 		case "uploading": return /* @__PURE__ */ jsx(Loading_default, {
@@ -28,6 +28,7 @@ function Filename({ iconDescription = "Uploading file", status = "uploading", in
 			className: `${prefix}--file-loading`
 		});
 		case "edit": return /* @__PURE__ */ jsxs(Fragment, { children: [invalid && /* @__PURE__ */ jsx(WarningFilled, { className: `${prefix}--file-invalid` }), /* @__PURE__ */ jsx("button", {
+			disabled,
 			"aria-label": `${iconDescription} - ${name}`,
 			className: `${prefix}--file-close`,
 			type: "button",

package/es/components/Menu/MenuItem.js

@@ -21,7 +21,7 @@ import React, { forwardRef, useContext, useEffect, useRef, useState } from "reac
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { CaretLeft, CaretRight, Checkmark } from "@carbon/icons-react";
-import { FloatingFocusManager, autoUpdate, offset, safePolygon, useFloating, useHover, useInteractions } from "@floating-ui/react";
+import { FloatingFocusManager, autoUpdate, flip, offset, safePolygon, useFloating, useHover, useInteractions } from "@floating-ui/react";
 //#region src/components/Menu/MenuItem.tsx
 /**
 * Copyright IBM Corp. 2023, 2026
@@ -29,18 +29,26 @@ import { FloatingFocusManager, autoUpdate, offset, safePolygon, useFloating, use
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */
-const MenuItem = forwardRef(function MenuItem({ children, className, dangerDescription = "danger", disabled, kind = "default", label, onClick, renderIcon: IconElement, shortcut, ...rest }, forwardRef) {
+const MenuItem = forwardRef(function MenuItem({ children, className, dangerDescription = "", disabled, kind = "default", label, onClick, renderIcon: IconElement, shortcut, ...rest }, forwardRef) {
 	const [submenuOpen, setSubmenuOpen] = useState(false);
 	const [rtl, setRtl] = useState(false);
 	const { refs, floatingStyles, context: floatingContext } = useFloating({
 		open: submenuOpen,
-		onOpenChange: setSubmenuOpen,
+		onOpenChange: (open, event) => {
+			if (open) setSubmenuOpen(true);
+			else {
+				const relatedTarget = event && "relatedTarget" in event ? event.relatedTarget : null;
+				if (relatedTarget instanceof Node && menuItem.current?.contains(relatedTarget)) return;
+				setSubmenuOpen(false);
+				if (!(relatedTarget instanceof HTMLElement && relatedTarget.closest("[role=\"menuitem\"]")?.querySelector("[role=\"menu\"]"))) menuItem.current?.focus();
+			}
+		},
 		placement: rtl ? "left-start" : "right-start",
 		whileElementsMounted: autoUpdate,
-		middleware: [offset({
-			mainAxis: -6,
+		middleware: [flip(), offset(({ placement }) => ({
+			mainAxis: placement.startsWith("left") ? 10 : -6,
 			crossAxis: -6
-		})],
+		}))],
 		strategy: "fixed"
 	});
 	const { getReferenceProps, getFloatingProps } = useInteractions([useHover(floatingContext, {
@@ -59,6 +67,7 @@ const MenuItem = forwardRef(function MenuItem({ children, className, dangerDescr
 	const hasChildren = React.Children.toArray(children).length > 0;
 	const isDisabled = disabled && !hasChildren;
 	const isDanger = kind === "danger" && !hasChildren;
+	const hasDangerDescription = isDanger && Boolean(dangerDescription);
 	function registerItem() {
 		context.dispatch({
 			type: "registerItem",
@@ -161,7 +170,7 @@ const MenuItem = forwardRef(function MenuItem({ children, className, dangerDescr
 					className: `${prefix}--menu-item__label`,
 					children: label
 				}),
-				isDanger && /* @__PURE__ */ jsx("span", {
+				hasDangerDescription && /* @__PURE__ */ jsx("span", {
 					id: assistiveId,
 					className: `${prefix}--visually-hidden`,
 					children: dangerDescription

package/es/components/Modal/Modal.d.ts

@@ -38,6 +38,11 @@ export interface ModalProps extends HTMLAttributes<HTMLDivElement> {
      * Specify whether the Modal is for dangerous actions
      */
     danger?: boolean;
+    /**
+     * Specify the message read by screen readers for the danger primary button.
+     * Defaults to an empty string; provide localized text to opt in.
+     */
+    dangerDescription?: string;
     /**
      * **Experimental**: Provide a decorator component to be rendered inside the `Modal` component
      */

package/es/components/Modal/Modal.js

@@ -29,6 +29,7 @@ import { toggleClass } from "../../tools/toggleClass.js";
 import { requiredIfGivenPropIsTruthy } from "../../prop-types/requiredIfGivenPropIsTruthy.js";
 import { elementOrParentIsFloatingMenu, wrapFocus, wrapFocusWithoutSentinels } from "../../internal/wrapFocus.js";
 import { Dialog } from "../Dialog/Dialog.js";
+import { isTopmostVisibleModal } from "./isTopmostVisibleModal.js";
 import { usePreviousValue } from "../../internal/usePreviousValue.js";
 import { ModalPresence, ModalPresenceContext, useExclusiveModalPresenceContext } from "./ModalPresence.js";
 import classNames from "classnames";
@@ -72,12 +73,13 @@ const Modal = React.forwardRef(function Modal({ open, ...props }, ref) {
 		...props
 	});
 });
-const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLabelProp, children, className, decorator, modalHeading = "", modalLabel = "", modalAriaLabel, passiveModal = false, secondaryButtonText, primaryButtonText, open: externalOpen, onRequestClose = noopFn, onRequestSubmit = noopFn, onSecondarySubmit, primaryButtonDisabled = false, danger, alert, secondaryButtons, selectorPrimaryFocus = "[data-modal-primary-focus]", selectorsFloatingMenus, shouldSubmitOnEnter, size, hasScrollingContent = false, closeButtonLabel = "Close", preventCloseOnClickOutside, isFullWidth, launcherButtonRef, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, slug, ...rest }, ref) {
+const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLabelProp, children, className, decorator, modalHeading = "", modalLabel = "", modalAriaLabel, passiveModal = false, secondaryButtonText, primaryButtonText, open: externalOpen, onRequestClose = noopFn, onRequestSubmit = noopFn, onSecondarySubmit, primaryButtonDisabled = false, danger, dangerDescription = "", alert, secondaryButtons, selectorPrimaryFocus = "[data-modal-primary-focus]", selectorsFloatingMenus, shouldSubmitOnEnter, size, hasScrollingContent = false, closeButtonLabel = "Close", preventCloseOnClickOutside, isFullWidth, launcherButtonRef, loadingStatus = "inactive", loadingDescription, loadingIconDescription, onLoadingSuccess = noopFn, slug, ...rest }, ref) {
 	const prefix = usePrefix();
 	const button = useRef(null);
 	const secondaryButton = useRef(null);
 	const contentRef = useRef(null);
 	const innerModal = useRef(null);
+	const modalRef = useRef(null);
 	const startTrap = useRef(null);
 	const endTrap = useRef(null);
 	const wrapFocusTimeout = useRef(null);
@@ -89,7 +91,11 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 	const primaryButtonClass = classNames({ [`${prefix}--btn--loading`]: loadingStatus !== "inactive" });
 	const loadingActive = loadingStatus !== "inactive";
 	const presenceContext = useContext(ModalPresenceContext);
-	const mergedRefs = useMergedRefs([ref, presenceContext?.presenceRef]);
+	const mergedRefs = useMergedRefs([
+		modalRef,
+		ref,
+		presenceContext?.presenceRef
+	]);
 	const enablePresence = useFeatureFlag("enable-presence") || presenceContext?.autoEnablePresence;
 	const open = externalOpen || enablePresence;
 	const prevOpen = usePreviousValue(open);
@@ -103,14 +109,19 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 	}
 	function handleKeyDown(evt) {
 		const { target } = evt;
-		evt.stopPropagation();
 		if (open && target instanceof HTMLElement) {
-			if (match(evt, Enter) && shouldSubmitOnEnter && !isCloseButton(target) && document.activeElement !== button.current) onRequestSubmit(evt);
-			if (focusTrapWithoutSentinels && !enableDialogElement && match(evt, Tab) && innerModal.current) wrapFocusWithoutSentinels({
-				containerNode: innerModal.current,
-				currentActiveNode: target,
-				event: evt
-			});
+			if (match(evt, Enter) && shouldSubmitOnEnter && !isCloseButton(target) && document.activeElement !== button.current) {
+				evt.stopPropagation();
+				onRequestSubmit(evt);
+			}
+			if (focusTrapWithoutSentinels && !enableDialogElement && match(evt, Tab) && innerModal.current) {
+				evt.stopPropagation();
+				wrapFocusWithoutSentinels({
+					containerNode: innerModal.current,
+					currentActiveNode: target,
+					event: evt
+				});
+			}
 		}
 	}
 	function handleOnClick(evt) {
@@ -187,15 +198,14 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 	useEffect(() => {
 		if (!open) return;
 		const handleEscapeKey = (event) => {
-			if (match(event, Escape)) {
+			if (match(event, Escape) && isTopmostVisibleModal(modalRef.current, prefix)) {
 				event.preventDefault();
-				event.stopPropagation();
 				onRequestClose(event);
 			}
 		};
-		document.addEventListener("keydown", handleEscapeKey, true);
+		document.addEventListener("keydown", handleEscapeKey);
 		return () => {
-			document.removeEventListener("keydown", handleEscapeKey, true);
+			document.removeEventListener("keydown", handleEscapeKey);
 		};
 	}, [open]);
 	useEffect(() => {
@@ -352,6 +362,7 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 				}), /* @__PURE__ */ jsx(Button_default, {
 					className: primaryButtonClass,
 					kind: danger ? "danger" : "primary",
+					dangerDescription,
 					disabled: loadingActive || primaryButtonDisabled,
 					onClick: onRequestSubmit,
 					ref: button,
@@ -428,6 +439,7 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 					}), /* @__PURE__ */ jsx(Button_default, {
 						className: primaryButtonClass,
 						kind: danger ? "danger" : "primary",
+						dangerDescription,
 						disabled: loadingActive || primaryButtonDisabled,
 						onClick: onRequestSubmit,
 						ref: button,
@@ -470,6 +482,7 @@ Modal.propTypes = {
 	className: PropTypes.string,
 	closeButtonLabel: PropTypes.string,
 	danger: PropTypes.bool,
+	dangerDescription: PropTypes.string,
 	decorator: PropTypes.node,
 	hasScrollingContent: PropTypes.bool,
 	id: PropTypes.string,

package/es/components/Modal/isTopmostVisibleModal.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright IBM Corp. 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export declare const isTopmostVisibleModal: (node: HTMLElement | null, prefix: string) => boolean;

package/es/components/Modal/isTopmostVisibleModal.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright IBM Corp. 2016, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+//#region src/components/Modal/isTopmostVisibleModal.ts
+/**
+* Copyright IBM Corp. 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+const isTopmostVisibleModal = (node, prefix) => {
+	if (!node) return false;
+	const visibleModals = document.querySelectorAll(`.${prefix}--modal.is-visible`);
+	return visibleModals.item(visibleModals.length - 1) === node;
+};
+//#endregion
+export { isTopmostVisibleModal };