@atlaskit/top-layer 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atlaskit/top-layer
 
+## 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.js

@@ -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.js

@@ -97,11 +97,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 +144,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 +218,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 +230,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 +248,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.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';
@@ -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;
   }

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

@@ -1,5 +1,5 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { bind, bindAll } from 'bind-event-listener';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { bind } from 'bind-event-listener';
 import { prefersReducedMotion } from './reduced-motion';
 /**
  * Using the recommended motion timings for safety net.
@@ -110,7 +110,7 @@ function runOnTransitionEndOrTimeout({
  * `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):
  *
  * ```
@@ -130,6 +130,7 @@ export function useAnimatedVisibility({
   onExitFinish
 }) {
   const willAnimate = shouldAnimate && !prefersReducedMotion();
+  const isNativeClosedRef = useRef(false);
 
   // Promote `closed → entering`/`closed → open` synchronously during
   // render so the host element mounts in the same commit as the open
@@ -140,16 +141,23 @@ export function useAnimatedVisibility({
     }
     return willAnimate ? 'entering' : 'open';
   });
-  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
@@ -234,47 +242,37 @@ export function useAnimatedVisibility({
     });
   }, [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.
   useLayoutEffect(() => {
-    if (phase !== 'exiting' || willAnimate) {
-      return;
+    if (phase === 'exiting' && !willAnimate && isNativeClosedRef.current) {
+      setPhase('closed');
     }
-    const element = elementRef.current;
-    if (!element) {
+  }, [phase, willAnimate]);
+  const onToggle = useCallback(event => {
+    if (event.newState === 'open') {
+      isNativeClosedRef.current = false;
       return;
     }
-    function unmount() {
-      setPhase(current => current === 'exiting' ? 'closed' : current);
+    if (event.newState !== 'closed') {
+      return;
     }
-    return bindAll(element, [{
-      type: 'toggle',
-      listener: event => {
-        if (event.newState === 'closed') {
-          unmount();
-        }
+    isNativeClosedRef.current = true;
+    setPhase(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).
   const prevPhaseForExitRef = useRef('closed');
   useEffect(() => {
     const prevPhase = prevPhaseForExitRef.current;
@@ -289,6 +287,7 @@ export function useAnimatedVisibility({
     }
   }, [phase, willAnimate]);
   return {
-    phase
+    phase,
+    onToggle
   };
 }

package/dist/es2019/popover/popover.js

@@ -88,11 +88,7 @@ const 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>
@@ -132,7 +128,8 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // `useId()` colons are invalid in CSS selectors and popover target attributes.
   const popoverId = idProp !== null && idProp !== void 0 ? idProp : `popover-${autoId.replace(/:/g, '')}`;
   const {
-    phase
+    phase,
+    onToggle
   } = useAnimatedVisibility({
     isOpen,
     animationKind: 'popover',
@@ -214,6 +211,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   const handleToggle = useCallback(event => {
     const element = ownRef.current;
     if (event.newState === 'open') {
+      onToggle(event);
       return;
     }
     if (event.newState === 'closed') {
@@ -243,18 +241,18 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
         // 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).
+        const reason = closeReasonRef.current;
+        closeReasonRef.current = 'light-dismiss';
+        // Optional: `manual` mode has no `onClose` in the forwarded type.
+        onClose === null || onClose === void 0 ? void 0 : onClose({
+          reason
+        });
       }
-
-      // Browser dismiss (Escape/click-outside).
-      const reason = closeReasonRef.current;
-      closeReasonRef.current = 'light-dismiss';
-      // Optional: `manual` mode has no `onClose` in the forwarded type.
-      onClose === null || onClose === void 0 ? void 0 : onClose({
-        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/esm/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';
@@ -45,8 +45,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
@@ -56,6 +56,8 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
   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,
@@ -73,6 +75,7 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
   var dialogId = providedId !== null && providedId !== void 0 ? providedId : generatedId;
   var ownRef = useRef(null);
   var combinedRef = mergeRefs([ownRef, ref]);
+  var closeReasonRef = useRef(null);
   var _useAnimatedVisibilit = useAnimatedVisibility({
       isOpen: isOpen,
       animationKind: 'dialog',
@@ -81,7 +84,8 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
       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.
@@ -112,6 +116,7 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
       return;
     }
     if (isOpen) {
+      closeReasonRef.current = null;
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -144,45 +149,67 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
     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.
-  useEffect(function () {
+  useLayoutEffect(function () {
     var dialog = ownRef.current;
     if (!dialog) {
       return;
     }
-    return bind(dialog, {
+    return 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/esm/internal/use-animated-visibility.js

@@ -1,6 +1,6 @@
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { bind, bindAll } from 'bind-event-listener';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { bind } from 'bind-event-listener';
 import { prefersReducedMotion } from './reduced-motion';
 /**
  * Using the recommended motion timings for safety net.
@@ -110,7 +110,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):
  *
  * ```
@@ -129,6 +129,7 @@ export function useAnimatedVisibility(_ref2) {
     onEnterFinish = _ref2.onEnterFinish,
     onExitFinish = _ref2.onExitFinish;
   var willAnimate = shouldAnimate && !prefersReducedMotion();
+  var isNativeClosedRef = useRef(false);
 
   // Promote `closed → entering`/`closed → open` synchronously during
   // render so the host element mounts in the same commit as the open
@@ -142,16 +143,23 @@ export function useAnimatedVisibility(_ref2) {
     _useState2 = _slicedToArray(_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
@@ -240,49 +248,37 @@ export 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.
   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 = 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 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 = useRef('closed');
   useEffect(function () {
     var prevPhase = prevPhaseForExitRef.current;
@@ -297,6 +293,7 @@ export function useAnimatedVisibility(_ref2) {
     }
   }, [phase, willAnimate]);
   return {
-    phase: phase
+    phase: phase,
+    onToggle: onToggle
   };
 }

package/dist/esm/popover/popover.js

@@ -88,11 +88,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>
@@ -139,7 +135,8 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       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.
@@ -212,6 +209,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   var handleToggle = useCallback(function (event) {
     var element = ownRef.current;
     if (event.newState === 'open') {
+      onToggle(event);
       return;
     }
     if (event.newState === 'closed') {
@@ -223,11 +221,11 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
         // 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 && shouldFocusIntoPopover({
           role: role
-        }) && (_reason === 'escape' || isProgrammatic);
+        }) && (reason === 'escape' || isProgrammatic);
         if (shouldRestore && previouslyFocused) {
           previouslyFocused.focus({
             preventScroll: true
@@ -241,18 +239,18 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
         // 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/types/dialog/dialog-content.d.ts

@@ -14,8 +14,8 @@ import { type TDialogProps } from './types';
  *
  * 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

package/dist/types/dialog/index.d.ts

@@ -1,3 +1,3 @@
 export { createCloseEvent } from './create-close-event';
 export { Dialog } from './dialog-content';
-export type { TDialogCloseReason, TDialogProps } from './types';
+export type { TDialogCloseReason, TDialogDismissedBy, TDialogProps } from './types';

package/dist/types/dialog/types.d.ts

@@ -11,6 +11,10 @@ import type { StrictXCSSProp } from '@atlaskit/css';
  * produces. The consumer simply sets `isOpen={false}`.
  */
 export type TDialogCloseReason = 'escape' | 'overlay-click';
+/**
+ * User interactions that are allowed to dismiss the dialog.
+ */
+export type TDialogDismissedBy = 'none' | 'escape' | 'escape-and-outside-click';
 /**
  * Props shared across `TDialogProps` variants.
  *
@@ -40,14 +44,24 @@ type TDialogBaseProps = {
      */
     isOpen: boolean;
     /**
-     * Called when the user triggers close via Escape or backdrop click.
+     * Called after the dialog closes through an allowed Escape or backdrop interaction.
      *
-     * The dialog does **not** close itself. The consumer decides whether to
-     * set `isOpen={false}` (e.g. gate by reason).
+     * User dismissal cannot be rejected from this callback. The consumer must set
+     * `isOpen={false}` in response to synchronize controlled state with the native dialog.
      */
     onClose: (args: {
         reason: TDialogCloseReason;
     }) => void;
+    /**
+     * Controls which user actions can dismiss the dialog.
+     *
+     * - `'escape-and-outside-click'`: Escape and outside click.
+     * - `'escape'`: Escape only.
+     * - `'none'`: no user action.
+     *
+     * Defaults to `'escape-and-outside-click'`.
+     */
+    dismissedBy?: TDialogDismissedBy;
     /**
      * Whether the dialog should animate in and out.
      *

package/dist/types/entry-points/dialog.d.ts

@@ -1,2 +1,2 @@
 export { createCloseEvent, Dialog } from '../dialog';
-export type { TDialogCloseReason, TDialogProps } from '../dialog';
+export type { TDialogCloseReason, TDialogDismissedBy, TDialogProps } from '../dialog';

package/dist/types/internal/use-animated-visibility.d.ts

@@ -42,6 +42,12 @@ type TUseAnimatedVisibilityResult = {
      * trapping, listeners that must outlive the exit).
      */
     phase: TPhase;
+    /**
+     * Notifies the visibility lifecycle after the primitive has finished its
+     * own native toggle handling. Closing toggles make native dismissal
+     * authoritative while preserving primitive-specific handler ordering.
+     */
+    onToggle: (event: ToggleEvent) => void;
 };
 /**
  * Visibility lifecycle phase shared between `useAnimatedVisibility`,
@@ -93,7 +99,7 @@ export type TPhase = 'closed' | 'entering' | 'open' | 'exiting';
  * `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):
  *
  * ```

package/dist/types/popover/popover.d.ts

@@ -16,11 +16,7 @@ import { type TPopoverForwardedProps } from './types';
  * ### 📜 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>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "4.0.0",
+	"version": "4.1.0",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",