feat(modal): refactor to use native dialog element (#18553)

* refactor(modal): add dialog feature flag

* refactor(modal): begin dialog exploration

* feat(modal): unify conditional exports under wrapper component

* revert(modal): changes from initial dialog refactor

* refactor(modal): remove unecessary close button dom location condition

* fix(modal): add dialog refactor scss feature flag

* fix: named export

* feat(dialog): break children elements out into composable components

* feat(dialog): improve stories, documentation, and Modal refactor

* feat(modal): document dialog feature flag

* fix(composedmodal): refactor to use dialog

* refactor(modal): remove conditional export, move enableDialogElement into existing Modal source file

* Update packages/react/src/components/Dialog/Dialog.stories.js

Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

* Update packages/react/scss/components/dialog/_index.scss

Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

* Update packages/react/scss/components/dialog/_dialog.scss

Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

* fix(dialog): incorporate feedback

---------

Co-authored-by: “heloiselui” <helolui27@gmail.com>
Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

Author: tay1orjones

packages/feature-flags/feature-flags.yml

@@ -45,6 +45,10 @@ feature-flags:
     description: >
       Enable the new focus wrap behavior that doesn't use sentinel nodes
     enabled: false
+  - name: enable-dialog-element
+    description: >
+      Enable components to utilize the native dialog element
+    enabled: false
   - name: enable-v12-dynamic-floating-styles
     description: >
       Enable dynamic setting of floating styles for components like Popover,

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -9933,6 +9933,9 @@ Map {
       "children": Object {
         "type": "node",
       },
+      "enableDialogElement": Object {
+        "type": "bool",
+      },
       "enableExperimentalFocusWrapWithoutSentinels": Object {
         "type": "bool",
       },

packages/react/scss/components/dialog/_dialog.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2025
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@forward '@carbon/styles/scss/components/dialog/dialog';

packages/react/scss/components/dialog/_index.scss

@@ -0,0 +1,9 @@
+// Code generated by @carbon/react. DO NOT EDIT.
+//
+// Copyright IBM Corp. 2018, 2025
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@forward '@carbon/styles/scss/components/dialog';

packages/react/src/components/ComposedModal/ComposedModal.featureflag.mdx

@@ -10,22 +10,26 @@ import { Meta } from '@storybook/blocks';
  | 
 [Accessibility](https://www.carbondesignsystem.com/components/modal/accessibility)
 
-## Experimental focus wrap without sentinels
+## `enable-dialog-element`
 
-`ComposedModal` supports the `enable-experimental-focus-wrap-without-sentinels`
-feature flag. This enables a new approach to the focus wrap behavior that
-modifies the DOM to no longer include hidden "sentinel nodes" used to mark the
-beginning and end of the wrapped focus. The new behavior looks at all
-interactive child nodes and wraps focus based on tabbable order of those nodes.
-The focus direction is determined whether `tab` is being pressed (forward) or
-`shift`+`tab` is being pressed (backwards). In javascript you can enable this
-feature flag to use the new focus wrap behavior.
+`ComposedModal` supports the `enable-dialog-element` feature flag. This enables
+a new approach internal to the ComposedModal that uses the native `<dialog>`
+element. With this, the browser natively controls the focus wrap behavior. This
+means that the DOM no longer includes the "sentinel nodes" previously needed for
+the ComposedModal to manage focus wrap.
+
+`ComposedModal` also supports the
+`enable-experimental-focus-wrap-without-sentinels` feature flag that was
+implemented previous to the dialog element refactor. In ComposedModal, this flag
+is an alias for the `enable-dialog-element` flag. They do the same thing and you
+only need to use one, preferably `enable-dialog-element`.
+
+## Enabling the flag
+
+To enable the flag, use the `FeatureFlags` component and set the prop:
 
 ```js
-<FeatureFlags
-  flags={{
-    'enable-experimental-focus-wrap-without-sentinels': true,
-  }}>
-  <ComposedModal />
+<FeatureFlags enableDialogElement>
+  <ComposedModal ... />
 </FeatureFlags>
 ```

packages/react/src/components/ComposedModal/ComposedModal.featureflag.stories.js

@@ -45,7 +45,7 @@ export default {
   ],
 };
 
-export const FocusWrapWithoutSentinels = (args) => {
+export const EnableDialogElement = (args) => {
   const [open, setOpen] = useState(true);
   return (
     <>
@@ -84,7 +84,7 @@ export const FocusWrapWithoutSentinels = (args) => {
   );
 };
 
-FocusWrapWithoutSentinels.argTypes = {
+EnableDialogElement.argTypes = {
   children: {
     table: {
       disable: true,

packages/react/src/components/ComposedModal/ComposedModal.tsx

@@ -25,13 +25,13 @@ import toggleClass from '../../tools/toggleClass';
 import requiredIfGivenPropIsTruthy from '../../prop-types/requiredIfGivenPropIsTruthy';
 import wrapFocus, {
   elementOrParentIsFloatingMenu,
-  wrapFocusWithoutSentinels,
 } from '../../internal/wrapFocus';
 import { usePrefix } from '../../internal/usePrefix';
 import { keys, match } from '../../internal/keyboard';
 import { useFeatureFlag } from '../FeatureFlags';
 import { composeEventHandlers } from '../../tools/events';
 import deprecate from '../../prop-types/deprecate';
+import { unstable__Dialog as Dialog } from '../Dialog/index';
 
 export interface ModalBodyProps extends HTMLAttributes<HTMLDivElement> {
   /** Specify the content to be placed in the ModalBody. */
@@ -260,43 +260,34 @@ const ComposedModal = React.forwardRef<HTMLDivElement, ComposedModalProps>(
     const endSentinel = useRef<HTMLButtonElement>(null);
     const onMouseDownTarget: MutableRefObject<Node | null> =
       useRef<Node | null>(null);
-    const focusTrapWithoutSentinels = useFeatureFlag(
-      'enable-experimental-focus-wrap-without-sentinels'
-    );
+    const enableDialogElement =
+      // useFeatureFlag('enable-experimental-focus-wrap-without-sentinels') ||
+      useFeatureFlag('enable-dialog-element');
 
     // Keep track of modal open/close state
     // and propagate it to the document.body
     useEffect(() => {
-      if (open !== wasOpen) {
+      if (!enableDialogElement && open !== wasOpen) {
         setIsOpen(!!open);
         setWasOpen(!!open);
         toggleClass(document.body, `${prefix}--body--with-modal-open`, !!open);
       }
     }, [open, wasOpen, prefix]);
     // Remove the document.body className on unmount
     useEffect(() => {
-      return () => {
-        toggleClass(document.body, `${prefix}--body--with-modal-open`, false);
-      };
+      if (!enableDialogElement) {
+        return () => {
+          toggleClass(document.body, `${prefix}--body--with-modal-open`, false);
+        };
+      }
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
     function handleKeyDown(event) {
-      event.stopPropagation();
-      if (match(event, keys.Escape)) {
-        closeModal(event);
-      }
-
-      if (
-        focusTrapWithoutSentinels &&
-        open &&
-        match(event, keys.Tab) &&
-        innerModal.current
-      ) {
-        wrapFocusWithoutSentinels({
-          containerNode: innerModal.current,
-          currentActiveNode: event.target,
-          event: event,
-        });
+      if (!enableDialogElement) {
+        event.stopPropagation();
+        if (match(event, keys.Escape)) {
+          closeModal(event);
+        }
       }
 
       onKeyDown?.(event);
@@ -400,45 +391,47 @@ const ComposedModal = React.forwardRef<HTMLDivElement, ComposedModalProps>(
     });
 
     useEffect(() => {
-      if (!open && launcherButtonRef) {
+      if (!enableDialogElement && !open && launcherButtonRef) {
         setTimeout(() => {
           launcherButtonRef?.current?.focus();
         });
       }
     }, [open, launcherButtonRef]);
 
     useEffect(() => {
-      const initialFocus = (focusContainerElement) => {
-        const containerElement = focusContainerElement || innerModal.current;
-        const primaryFocusElement = containerElement
-          ? containerElement.querySelector(
-              danger ? `.${prefix}--btn--secondary` : selectorPrimaryFocus
-            )
-          : null;
-
-        if (primaryFocusElement) {
-          return primaryFocusElement;
-        }
-
-        return button && button.current;
-      };
-
-      const focusButton = (focusContainerElement) => {
-        const target = initialFocus(focusContainerElement);
+      if (!enableDialogElement) {
+        const initialFocus = (focusContainerElement) => {
+          const containerElement = focusContainerElement || innerModal.current;
+          const primaryFocusElement = containerElement
+            ? containerElement.querySelector(
+                danger ? `.${prefix}--btn--secondary` : selectorPrimaryFocus
+              )
+            : null;
+
+          if (primaryFocusElement) {
+            return primaryFocusElement;
+          }
+
+          return button && button.current;
+        };
+
+        const focusButton = (focusContainerElement) => {
+          const target = initialFocus(focusContainerElement);
+
+          const closeButton = focusContainerElement.querySelector(
+            `.${prefix}--modal-close`
+          );
 
-        const closeButton = focusContainerElement.querySelector(
-          `.${prefix}--modal-close`
-        );
+          if (target) {
+            target.focus();
+          } else if (!target && closeButton) {
+            closeButton?.focus();
+          }
+        };
 
-        if (target) {
-          target.focus();
-        } else if (!target && closeButton) {
-          closeButton?.focus();
+        if (open && isOpen) {
+          focusButton(innerModal.current);
         }
-      };
-
-      if (open && isOpen) {
-        focusButton(innerModal.current);
       }
     }, [open, selectorPrimaryFocus, isOpen]);
 
@@ -458,58 +451,78 @@ const ComposedModal = React.forwardRef<HTMLDivElement, ComposedModalProps>(
       );
     }
 
+    const modalBody = enableDialogElement ? (
+      <Dialog
+        open={open}
+        modal
+        className={containerClass}
+        aria-label={ariaLabel ? ariaLabel : generatedAriaLabel}
+        aria-labelledby={ariaLabelledBy}>
+        <div ref={innerModal} className={`${prefix}--modal-container-body`}>
+          {slug ? (
+            normalizedDecorator
+          ) : decorator ? (
+            <div className={`${prefix}--modal--inner__decorator`}>
+              {normalizedDecorator}
+            </div>
+          ) : (
+            ''
+          )}
+          {childrenWithProps}
+        </div>
+      </Dialog>
+    ) : (
+      <div
+        className={containerClass}
+        role="dialog"
+        aria-modal="true"
+        aria-label={ariaLabel ? ariaLabel : generatedAriaLabel}
+        aria-labelledby={ariaLabelledBy}>
+        {/* Non-translatable: Focus-wrap code makes this `<button>` not actually read by screen readers */}
+        <button
+          type="button"
+          ref={startSentinel}
+          className={`${prefix}--visually-hidden`}>
+          Focus sentinel
+        </button>
+        <div ref={innerModal} className={`${prefix}--modal-container-body`}>
+          {slug ? (
+            normalizedDecorator
+          ) : decorator ? (
+            <div className={`${prefix}--modal--inner__decorator`}>
+              {normalizedDecorator}
+            </div>
+          ) : (
+            ''
+          )}
+          {childrenWithProps}
+        </div>
+        {/* Non-translatable: Focus-wrap code makes this `<button>` not actually read by screen readers */}
+        <button
+          type="button"
+          ref={endSentinel}
+          className={`${prefix}--visually-hidden`}>
+          Focus sentinel
+        </button>
+      </div>
+    );
+
     return (
       <Layer
         {...rest}
         level={0}
         role="presentation"
         ref={ref}
         aria-hidden={!open}
-        onBlur={!focusTrapWithoutSentinels ? handleBlur : () => {}}
+        onBlur={!enableDialogElement ? handleBlur : () => {}}
         onClick={composeEventHandlers([rest?.onClick, handleOnClick])}
         onMouseDown={composeEventHandlers([
           rest?.onMouseDown,
           handleOnMouseDown,
         ])}
         onKeyDown={handleKeyDown}
         className={modalClass}>
-        <div
-          className={containerClass}
-          role="dialog"
-          aria-modal="true"
-          aria-label={ariaLabel ? ariaLabel : generatedAriaLabel}
-          aria-labelledby={ariaLabelledBy}>
-          {/* Non-translatable: Focus-wrap code makes this `<button>` not actually read by screen readers */}
-          {!focusTrapWithoutSentinels && (
-            <button
-              type="button"
-              ref={startSentinel}
-              className={`${prefix}--visually-hidden`}>
-              Focus sentinel
-            </button>
-          )}
-          <div ref={innerModal} className={`${prefix}--modal-container-body`}>
-            {slug ? (
-              normalizedDecorator
-            ) : decorator ? (
-              <div className={`${prefix}--modal--inner__decorator`}>
-                {normalizedDecorator}
-              </div>
-            ) : (
-              ''
-            )}
-            {childrenWithProps}
-          </div>
-          {/* Non-translatable: Focus-wrap code makes this `<button>` not actually read by screen readers */}
-          {!focusTrapWithoutSentinels && (
-            <button
-              type="button"
-              ref={endSentinel}
-              className={`${prefix}--visually-hidden`}>
-              Focus sentinel
-            </button>
-          )}
-        </div>
+        {modalBody}
       </Layer>
     );
   }