@atlaskit/top-layer 4.0.0 → 4.2.0

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.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/es2019/popover/popover.js

@@ -25,7 +25,8 @@ const supportsPopoverHint = once(() => {
   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
@@ -37,7 +38,7 @@ const supportsPopoverHint = once(() => {
 // `no-imported-style-values` — Compiled styles are null at runtime), so the reset is
 // co-located and duplicated deliberately.
 const surfaceResetStyles = {
-  root: "_o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
+  root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
 const styles = {
   root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28 _4t3i1wug",
@@ -88,11 +89,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 +129,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 +212,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 +242,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.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/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';
@@ -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).
 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",
@@ -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.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/esm/popover/popover.js

@@ -25,7 +25,8 @@ var supportsPopoverHint = once(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
@@ -37,7 +38,7 @@ var supportsPopoverHint = once(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",
@@ -88,11 +89,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 +136,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 +210,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 +222,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 +240,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';