@atlaskit/top-layer 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @atlaskit/top-layer
 
+## 4.2.0
+
+### Minor Changes
+
+- [`e825821c5493d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/e825821c5493d) -
+  Reset inherited `pointer-events` on Dialog and Popover top-layer surfaces so their content remains
+  interactive inside non-interactive overlay containers.
+
+## 4.1.0
+
+### Minor Changes
+
+- [`ccb9237bc10d9`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ccb9237bc10d9) -
+  Add the `dismissedBy` API to control Dialog dismissal consistently across browsers. Align Dialog
+  with Popover by notifying `onClose` after native dismissal, ensure both primitives unmount after
+  native dismissal, and simplify Modal close handling behind `platform-dst-top-layer`.
+
 ## 4.0.0
 
 ### Major Changes

package/dist/cjs/dialog/dialog-content.compiled.css

@@ -24,6 +24,7 @@
 ._bozgze3t{padding-inline-start:var(--ds-space-0,0)}
 ._c71lglyw{max-height:none}
 ._k8m011k7{transition-property:overlay,display}
+._lcxv1wug{pointer-events:auto}
 ._o5724jg8{white-space:normal}
 ._otyr1wug{margin-bottom:auto}
 ._p12fglyw{max-width:none}

package/dist/cjs/dialog/dialog-content.js

@@ -20,16 +20,16 @@ var _useFocusWrap = require("../internal/use-focus-wrap");
 var _useSafariEscapeFix2 = require("../internal/use-safari-escape-fix");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 // Surface reset — see the rationale on `surfaceResetStyles` in `popover/popover.tsx`.
-// Neutralises inherited text-layout properties (e.g. `white-space: nowrap`) that leak
-// into the top-layer surface. Excludes `color`/`font` (theming) and
-// `direction`/`unicode-bidi` (RTL must inherit). Pure layout reset with no box
-// side-effects, so it does not reintroduce the `margin: auto` centering problem that
-// kept `height: auto` off `Dialog`.
+// Neutralises inherited interaction and text-layout properties (e.g.
+// `pointer-events: none` and `white-space: nowrap`) that leak into the top-layer
+// surface. Excludes `color`/`font` (theming) and `direction`/`unicode-bidi` (RTL
+// must inherit). The reset has no box side-effects, so it does not reintroduce
+// the `margin: auto` centering problem that kept `height: auto` off `Dialog`.
 //
 // KEEP IN SYNC with the identical `surfaceResetStyles` in `popover/popover.tsx`
 // (ADS forbids sharing styles across files, so it is co-located and duplicated).
 var surfaceResetStyles = {
-  root: "_o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
+  root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
 var dialogStyles = {
   root: "_19itglyw _19pk1wug _2hwx1wug _otyr1wug _18u01wug _1q51ze3t _y4tize3t _85i5ze3t _bozgze3t _p12fglyw _c71lglyw _bfhk1j28",
@@ -54,8 +54,8 @@ var backdropStyles = {
  *
  * Handles native `cancel` event (Escape) and backdrop click detection.
  *
- * Close flow: we never call `dialog.close()` from event handlers. We always call
- * `onClose`; the consumer decides whether to set `isOpen={false}`.
+ * Close flow: allowed user dismissal closes the native dialog before `onClose`
+ * notifies the consumer. The consumer must synchronize `isOpen` in response.
  *
  * Accessibility: render at least one focusable element (typically a close
  * button) when `isOpen` becomes `true`. Tab is always trapped inside the
@@ -65,6 +65,8 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   var children = _ref.children,
     isOpen = _ref.isOpen,
     onClose = _ref.onClose,
+    _ref$dismissedBy = _ref.dismissedBy,
+    dismissedBy = _ref$dismissedBy === void 0 ? 'escape-and-outside-click' : _ref$dismissedBy,
     onEnterFinish = _ref.onEnterFinish,
     onExitFinish = _ref.onExitFinish,
     _ref$shouldAnimate = _ref.shouldAnimate,
@@ -82,6 +84,7 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   var dialogId = providedId !== null && providedId !== void 0 ? providedId : generatedId;
   var ownRef = (0, _react.useRef)(null);
   var combinedRef = (0, _mergeRefs.default)([ownRef, ref]);
+  var closeReasonRef = (0, _react.useRef)(null);
   var _useAnimatedVisibilit = (0, _useAnimatedVisibility.useAnimatedVisibility)({
       isOpen: isOpen,
       animationKind: 'dialog',
@@ -90,7 +93,8 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
       onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
-    phase = _useAnimatedVisibilit.phase;
+    phase = _useAnimatedVisibilit.phase,
+    onToggle = _useAnimatedVisibilit.onToggle;
 
   // True while the host element is mounted (any phase except `closed`).
   // Used as a dep so listener-rebind effects re-attach after a remount.
@@ -121,6 +125,7 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
       return;
     }
     if (isOpen) {
+      closeReasonRef.current = null;
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -153,45 +158,67 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
     if (event.target !== event.currentTarget) {
       return;
     }
-    event.preventDefault();
+
     // Spurious Safari `cancel`: the keydown snapshot saw an open child
     // popover, so this Escape belongs to that popover (light-dismissed
     // natively). Keep the dialog open instead of forwarding to `onClose`.
     if (shouldIgnoreEscape()) {
+      event.preventDefault();
       return;
     }
-    onClose({
-      reason: 'escape'
-    });
-  }, [onClose, shouldIgnoreEscape]);
 
-  // Handle backdrop click
+    // Without native `closedby`, cancel Escape only when dismissal is disabled.
+    // Allowed dismissal follows Popover behavior: the browser closes the element
+    // and `onClose` notifies the controlled owner of the reason.
+    if (dismissedBy === 'none') {
+      event.preventDefault();
+      return;
+    }
+    closeReasonRef.current = 'escape';
+  }, [dismissedBy, shouldIgnoreEscape]);
+
+  // Handle backdrop interaction
   // Attached via bind-event-listener rather than a React prop so we avoid
   // a11y lint suppressions on the <dialog> element.
-  // Keyboard dismiss is already handled natively (Escape → onCancel above).
+  // The click listener provides light dismiss consistently across browsers.
   // `isVisible` is in deps so the listener re-binds to the new <dialog>
   // element after a host unmount / remount cycle.
-  (0, _react.useEffect)(function () {
+  (0, _react.useLayoutEffect)(function () {
     var dialog = ownRef.current;
     if (!dialog) {
       return;
     }
-    return (0, _bindEventListener.bind)(dialog, {
+    return (0, _bindEventListener.bindAll)(dialog, [{
       type: 'click',
       listener: function listener(event) {
-        if (event.target === event.currentTarget) {
-          onClose({
-            reason: 'overlay-click'
-          });
+        if (event.target === event.currentTarget && dismissedBy === 'escape-and-outside-click') {
+          closeReasonRef.current = 'overlay-click';
+          // Calls native close because this is emulating the native light-dismiss behavior
+          dialog.close();
         }
       }
-    });
-  }, [onClose, isVisible]);
+    }, {
+      type: 'toggle',
+      listener: function listener(event) {
+        if (event.newState === 'closed') {
+          var reason = closeReasonRef.current;
+          closeReasonRef.current = null;
+          if (reason) {
+            onClose({
+              reason: reason
+            });
+          }
+        }
+
+        // Visibility cleanup runs after close-reason handling.
+        onToggle(event);
+      }
+    }]);
+  }, [dismissedBy, onClose, onToggle, isVisible]);
 
   // Unmount the `<dialog>` once exit completes so it does not leave an
   // empty `role="dialog"` element in the accessibility tree. On the next
-  // open the element remounts and the `[isOpen]` and `[onClose, isVisible]`
-  // effects re-run against the fresh element.
+  // open the element remounts and its effects run against the fresh element.
   if (!isVisible) {
     return null;
   }

package/dist/cjs/internal/use-animated-visibility.js

@@ -117,7 +117,7 @@ function runOnTransitionEndOrTimeout(_ref) {
  * `entering`, `open`, `exiting`). The host element is rendered while
  * `phase !== 'closed'`, so the `exiting` phase keeps the host mounted
  * while the CSS exit transition plays (or, with animation disabled,
- * while we wait for the browser `toggle` / `close` event to fire on the
+ * while we wait for the browser's closing `toggle` event to fire on the
  * still-attached element):
  *
  * ```
@@ -136,6 +136,7 @@ function useAnimatedVisibility(_ref2) {
     onEnterFinish = _ref2.onEnterFinish,
     onExitFinish = _ref2.onExitFinish;
   var willAnimate = shouldAnimate && !(0, _reducedMotion.prefersReducedMotion)();
+  var isNativeClosedRef = (0, _react.useRef)(false);
 
   // Promote `closed → entering`/`closed → open` synchronously during
   // render so the host element mounts in the same commit as the open
@@ -149,16 +150,23 @@ function useAnimatedVisibility(_ref2) {
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
     phase = _useState2[0],
     setPhase = _useState2[1];
-  if (isOpen && phase === 'closed') {
+
+  // Rearm only after controlled state and the native lifecycle have both
+  // reached closed. Resetting as soon as `isOpen` becomes false can erase a
+  // closing toggle that was handled in the same React batch.
+  if (!isOpen && phase === 'closed') {
+    isNativeClosedRef.current = false;
+  }
+  if (isOpen && phase === 'closed' && !isNativeClosedRef.current) {
     setPhase(willAnimate ? 'entering' : 'open');
   }
   if (!isOpen && (phase === 'open' || phase === 'entering')) {
     // Close intent. Move to `exiting` to gate the unmount on either
-    // the exit transition (animated) or the toggle/close event
+    // the exit transition (animated) or the closing toggle event
     // (non-animated). Includes interrupted entry (`entering → exiting`).
     setPhase('exiting');
   }
-  if (isOpen && phase === 'exiting') {
+  if (isOpen && phase === 'exiting' && !isNativeClosedRef.current) {
     // Reopen mid-exit. With animation, jump back to `entering` and let
     // the entry transition restart from current visual state. Without
     // animation, jump straight to `open` (the handshake we were waiting
@@ -247,49 +255,37 @@ function useAnimatedVisibility(_ref2) {
     });
   }, [phase, willAnimate, animationKind, elementRef]);
 
-  // Non-animated exit: wait for the browser's `toggle` (closed) or
-  // `close` event before unmounting, so the consumer's listener (close
-  // reason, nested focus restoration, `onClose`) and the browser's
-  // native focus restoration both run against the still-attached
-  // element. A naive `setTimeout(0)` occasionally beats the `toggle`
-  // task in Chromium and drops focus restoration.
-  //
-  // `useLayoutEffect` so the listener binds in the same commit as the
-  // show/hide layout effect that calls `hidePopover()` / `dialog.close()`.
-  // The toggle/close event is queued as a task and cannot run until the
-  // frame completes. SSR-safe: `phase` starts at `'closed'`.
-  //
-  // `onExitFinish` is fired separately (see effect below) so consumers
-  // observe it the moment `isOpen` flips to `false`.
+  // Native dismissal is authoritative. Its toggle can arrive while controlled
+  // state still says open, so remember that native state and do not
+  // reopen until `isOpen` has first moved to false.
   (0, _react.useLayoutEffect)(function () {
-    if (phase !== 'exiting' || willAnimate) {
-      return;
+    if (phase === 'exiting' && !willAnimate && isNativeClosedRef.current) {
+      setPhase('closed');
     }
-    var element = elementRef.current;
-    if (!element) {
+  }, [phase, willAnimate]);
+  var onToggle = (0, _react.useCallback)(function (event) {
+    if (event.newState === 'open') {
+      isNativeClosedRef.current = false;
       return;
     }
-    function unmount() {
-      setPhase(function (current) {
-        return current === 'exiting' ? 'closed' : current;
-      });
+    if (event.newState !== 'closed') {
+      return;
     }
-    return (0, _bindEventListener.bindAll)(element, [{
-      type: 'toggle',
-      listener: function listener(event) {
-        if (event.newState === 'closed') {
-          unmount();
-        }
+    isNativeClosedRef.current = true;
+    setPhase(function (current) {
+      if (current === 'open' || current === 'entering') {
+        return 'exiting';
       }
-    }, {
-      type: 'close',
-      listener: unmount
-    }]);
-  }, [phase, willAnimate, elementRef]);
+      if (current === 'exiting' && !willAnimate) {
+        return 'closed';
+      }
+      return current;
+    });
+  }, [willAnimate]);
 
   // Non-animated exit callback. No `transitionend` to wait for, so fire
   // `onExitFinish` on the transition into `exiting` (the unmount itself
-  // is gated by the toggle/close handshake above).
+  // is gated by the closing toggle handshake above).
   var prevPhaseForExitRef = (0, _react.useRef)('closed');
   (0, _react.useEffect)(function () {
     var prevPhase = prevPhaseForExitRef.current;
@@ -304,6 +300,7 @@ function useAnimatedVisibility(_ref2) {
     }
   }, [phase, willAnimate]);
   return {
-    phase: phase
+    phase: phase,
+    onToggle: onToggle
   };
 }

package/dist/cjs/popover/popover.compiled.css

@@ -18,6 +18,7 @@
 ._bfhk1j28{background-color:transparent}
 ._ca0qidpf{padding-top:0}
 ._k8m011k7{transition-property:overlay,display}
+._lcxv1wug{pointer-events:auto}
 ._n3tdidpf{padding-bottom:0}
 ._o5724jg8{white-space:normal}
 ._otyridpf{margin-bottom:0}

package/dist/cjs/popover/popover.js

@@ -34,7 +34,8 @@ var supportsPopoverHint = (0, _once.default)(function () {
   return element.popover === 'hint';
 });
 
-// Surface reset — neutralises inherited text-layout properties (e.g.
+// Surface reset — neutralises inherited interaction and text-layout properties
+// (e.g. `pointer-events: none` from an overlaid controls container and
 // `white-space: nowrap` from an `@atlaskit/select` option) that leak into a
 // top-layer element because, for CSS inheritance, it is still a DOM child of its
 // trigger (top-layer promotion is paint/stacking only; the legacy portal path
@@ -46,7 +47,7 @@ var supportsPopoverHint = (0, _once.default)(function () {
 // `no-imported-style-values` — Compiled styles are null at runtime), so the reset is
 // co-located and duplicated deliberately.
 var surfaceResetStyles = {
-  root: "_o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
+  root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
 var styles = {
   root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28 _4t3i1wug",
@@ -97,11 +98,7 @@ var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', '
  * ### 📜 Browser dismiss is non-cancellable
  *
  * Per the popover spec, `beforetoggle` is cancellable on open transitions
- * only, not on close. Consumers that need to ignore a specific dismiss
- * (e.g. a click on a logically-associated external trigger) must reconcile
- * inside their own `onClose` handler by calling `showPopover()` again.
- * `Popover` does not self-heal so consumers do not pay a reconcile cost
- * by default.
+ * only, not on close.
  *
  * - Spec: <https://html.spec.whatwg.org/multipage/popover.html#the-popover-attribute>
  * - <https://github.com/whatwg/html/issues/8973>
@@ -148,7 +145,8 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
-    phase = _useAnimatedVisibilit.phase;
+    phase = _useAnimatedVisibilit.phase,
+    onToggle = _useAnimatedVisibilit.onToggle;
 
   // True while the host element is mounted (any phase except `closed`).
   // Used as a dep so listener-rebind effects re-attach after a remount.
@@ -221,6 +219,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   var handleToggle = (0, _react.useCallback)(function (event) {
     var element = ownRef.current;
     if (event.newState === 'open') {
+      onToggle(event);
       return;
     }
     if (event.newState === 'closed') {
@@ -232,11 +231,11 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
         // click target keeps focus per HTML spec
         // (`focusPreviousElement=false`).
         var previouslyFocused = previouslyFocusedElementRef.current;
-        var _reason = closeReasonRef.current;
+        var reason = closeReasonRef.current;
         var isProgrammatic = programmaticCloseRef.current;
         var shouldRestore = previouslyFocused !== null && previouslyFocused.isConnected && (0, _shouldFocusIntoPopover.shouldFocusIntoPopover)({
           role: role
-        }) && (_reason === 'escape' || isProgrammatic);
+        }) && (reason === 'escape' || isProgrammatic);
         if (shouldRestore && previouslyFocused) {
           previouslyFocused.focus({
             preventScroll: true
@@ -250,18 +249,18 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
         // Reset reason so a stale 'escape' from a race with Escape keydown
         // does not corrupt the next browser-dismiss cycle.
         closeReasonRef.current = 'light-dismiss';
-        return;
+      } else {
+        // Browser dismiss (Escape/click-outside).
+        var _reason = closeReasonRef.current;
+        closeReasonRef.current = 'light-dismiss';
+        // Optional: `manual` mode has no `onClose` in the forwarded type.
+        onClose === null || onClose === void 0 || onClose({
+          reason: _reason
+        });
       }
-
-      // Browser dismiss (Escape/click-outside).
-      var reason = closeReasonRef.current;
-      closeReasonRef.current = 'light-dismiss';
-      // Optional: `manual` mode has no `onClose` in the forwarded type.
-      onClose === null || onClose === void 0 || onClose({
-        reason: reason
-      });
     }
-  }, [onClose, role]);
+    onToggle(event);
+  }, [onClose, onToggle, role]);
 
   // Bind via `useLayoutEffect`, and BEFORE the show/hide layout effect
   // below, so listeners are attached when `showPopover()` synchronously

package/dist/es2019/dialog/dialog-content.compiled.css

@@ -24,6 +24,7 @@
 ._bozgze3t{padding-inline-start:var(--ds-space-0,0)}
 ._c71lglyw{max-height:none}
 ._k8m011k7{transition-property:overlay,display}
+._lcxv1wug{pointer-events:auto}
 ._o5724jg8{white-space:normal}
 ._otyr1wug{margin-bottom:auto}
 ._p12fglyw{max-width:none}

package/dist/es2019/dialog/dialog-content.js

@@ -1,9 +1,9 @@
 /* dialog-content.tsx generated by @compiled/babel-plugin v2.0.0 */
 import "./dialog-content.compiled.css";
 import { ax, ix } from "@compiled/react/runtime";
-import React, { forwardRef, useCallback, useEffect, useId, useLayoutEffect, useRef } from 'react';
+import React, { forwardRef, useCallback, useId, useLayoutEffect, useRef } from 'react';
 import { cx } from '@compiled/react';
-import { bind } from 'bind-event-listener';
+import { bindAll } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import noop from '@atlaskit/ds-lib/noop';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/use-notify-open-layer-observer';
@@ -11,16 +11,16 @@ import { useAnimatedVisibility } from '../internal/use-animated-visibility';
 import { useFocusWrap } from '../internal/use-focus-wrap';
 import { useSafariEscapeFix } from '../internal/use-safari-escape-fix';
 // Surface reset — see the rationale on `surfaceResetStyles` in `popover/popover.tsx`.
-// Neutralises inherited text-layout properties (e.g. `white-space: nowrap`) that leak
-// into the top-layer surface. Excludes `color`/`font` (theming) and
-// `direction`/`unicode-bidi` (RTL must inherit). Pure layout reset with no box
-// side-effects, so it does not reintroduce the `margin: auto` centering problem that
-// kept `height: auto` off `Dialog`.
+// Neutralises inherited interaction and text-layout properties (e.g.
+// `pointer-events: none` and `white-space: nowrap`) that leak into the top-layer
+// surface. Excludes `color`/`font` (theming) and `direction`/`unicode-bidi` (RTL
+// must inherit). The reset has no box side-effects, so it does not reintroduce
+// the `margin: auto` centering problem that kept `height: auto` off `Dialog`.
 //
 // KEEP IN SYNC with the identical `surfaceResetStyles` in `popover/popover.tsx`
 // (ADS forbids sharing styles across files, so it is co-located and duplicated).
 const surfaceResetStyles = {
-  root: "_o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
+  root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
 const dialogStyles = {
   root: "_19itglyw _19pk1wug _2hwx1wug _otyr1wug _18u01wug _1q51ze3t _y4tize3t _85i5ze3t _bozgze3t _p12fglyw _c71lglyw _bfhk1j28",
@@ -45,8 +45,8 @@ const backdropStyles = {
  *
  * Handles native `cancel` event (Escape) and backdrop click detection.
  *
- * Close flow: we never call `dialog.close()` from event handlers. We always call
- * `onClose`; the consumer decides whether to set `isOpen={false}`.
+ * Close flow: allowed user dismissal closes the native dialog before `onClose`
+ * notifies the consumer. The consumer must synchronize `isOpen` in response.
  *
  * Accessibility: render at least one focusable element (typically a close
  * button) when `isOpen` becomes `true`. Tab is always trapped inside the
@@ -56,6 +56,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   children,
   isOpen,
   onClose,
+  dismissedBy = 'escape-and-outside-click',
   onEnterFinish,
   onExitFinish,
   shouldAnimate = false,
@@ -73,8 +74,10 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   const dialogId = providedId !== null && providedId !== void 0 ? providedId : generatedId;
   const ownRef = useRef(null);
   const combinedRef = mergeRefs([ownRef, ref]);
+  const closeReasonRef = useRef(null);
   const {
-    phase
+    phase,
+    onToggle
   } = useAnimatedVisibility({
     isOpen,
     animationKind: 'dialog',
@@ -113,6 +116,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
       return;
     }
     if (isOpen) {
+      closeReasonRef.current = null;
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -146,45 +150,67 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     if (event.target !== event.currentTarget) {
       return;
     }
-    event.preventDefault();
+
     // Spurious Safari `cancel`: the keydown snapshot saw an open child
     // popover, so this Escape belongs to that popover (light-dismissed
     // natively). Keep the dialog open instead of forwarding to `onClose`.
     if (shouldIgnoreEscape()) {
+      event.preventDefault();
+      return;
+    }
+
+    // Without native `closedby`, cancel Escape only when dismissal is disabled.
+    // Allowed dismissal follows Popover behavior: the browser closes the element
+    // and `onClose` notifies the controlled owner of the reason.
+    if (dismissedBy === 'none') {
+      event.preventDefault();
       return;
     }
-    onClose({
-      reason: 'escape'
-    });
-  }, [onClose, shouldIgnoreEscape]);
+    closeReasonRef.current = 'escape';
+  }, [dismissedBy, shouldIgnoreEscape]);
 
-  // Handle backdrop click
+  // Handle backdrop interaction
   // Attached via bind-event-listener rather than a React prop so we avoid
   // a11y lint suppressions on the <dialog> element.
-  // Keyboard dismiss is already handled natively (Escape → onCancel above).
+  // The click listener provides light dismiss consistently across browsers.
   // `isVisible` is in deps so the listener re-binds to the new <dialog>
   // element after a host unmount / remount cycle.
-  useEffect(() => {
+  useLayoutEffect(() => {
     const dialog = ownRef.current;
     if (!dialog) {
       return;
     }
-    return bind(dialog, {
+    return bindAll(dialog, [{
       type: 'click',
       listener(event) {
-        if (event.target === event.currentTarget) {
-          onClose({
-            reason: 'overlay-click'
-          });
+        if (event.target === event.currentTarget && dismissedBy === 'escape-and-outside-click') {
+          closeReasonRef.current = 'overlay-click';
+          // Calls native close because this is emulating the native light-dismiss behavior
+          dialog.close();
         }
       }
-    });
-  }, [onClose, isVisible]);
+    }, {
+      type: 'toggle',
+      listener(event) {
+        if (event.newState === 'closed') {
+          const reason = closeReasonRef.current;
+          closeReasonRef.current = null;
+          if (reason) {
+            onClose({
+              reason
+            });
+          }
+        }
+
+        // Visibility cleanup runs after close-reason handling.
+        onToggle(event);
+      }
+    }]);
+  }, [dismissedBy, onClose, onToggle, isVisible]);
 
   // Unmount the `<dialog>` once exit completes so it does not leave an
   // empty `role="dialog"` element in the accessibility tree. On the next
-  // open the element remounts and the `[isOpen]` and `[onClose, isVisible]`
-  // effects re-run against the fresh element.
+  // open the element remounts and its effects run against the fresh element.
   if (!isVisible) {
     return null;
   }