@atlaskit/top-layer 0.15.0 → 0.17.0

package/dist/cjs/internal/use-initial-focus.js

@@ -22,10 +22,106 @@ var _getFirstFocusable = require("../focus/get-first-focusable");
  * has no effect on hidden popover content. Consumers must set the native
  * attribute via a ref callback (e.g. `node.setAttribute('autofocus', '')`).
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
+ *
+ * Combobox pattern exception: if the popup is controlled by a focused
+ * combobox-like trigger (its `aria-controls` references this popup),
+ * focus stays on the textbox regardless of role. See
+ * `isComboboxControllingPopup`.
+ */
+
+/**
+ * WAI-ARIA APG Combobox Pattern: when a combobox controls a popup (listbox,
+ * grid, tree, or menu), DOM focus must remain on the textbox. Subsequent
+ * navigation through popup items uses `aria-activedescendant` (or proxied
+ * keyboard events), never DOM focus movement.
+ *
+ * Detects both variants in a single pass:
+ * - In-popup combobox: the textbox lives inside the popup `container`
+ *   (the popup is rendered as a child of the combobox wrapper).
+ * - External combobox: the textbox is rendered OUTSIDE the popup
+ *   (`react-select` pattern, where the listbox is portalled separately
+ *   from the textbox).
+ *
+ * Acceptance criteria for the active element:
+ * - Role / element-type filter: `role="combobox"`, `role="textbox"`,
+ *   `TEXTAREA`, `contentEditable`, or `INPUT` of text-like type
+ *   (`text`, `search`, `email`, `url`, `tel`, `password`, or
+ *   unspecified). Non-text input types (`button`, `checkbox`, etc.)
+ *   are rejected.
+ * - Reference filter: `aria-controls` (or legacy `aria-owns`) IDREFS
+ *   must resolve to an element that IS or CONTAINS the popup container.
+ *
+ * See: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
  */
-function getInitialFocusTarget(_ref) {
-  var container = _ref.container,
-    role = _ref.role;
+// `<input>` types treated as text-like for combobox detection.
+// Non-text input types (`button`, `checkbox`, `submit`, etc.) are rejected.
+// A missing `type` attribute defaults to `text` per the HTML spec, so we
+// normalize that case before lookup rather than including an empty string here.
+var TEXT_LIKE_INPUT_TYPES = new Set(['text', 'search', 'email', 'url', 'tel', 'password']);
+function isTextboxLikeElement(element) {
+  var role = element.getAttribute('role');
+  if (role === 'combobox' || role === 'textbox') {
+    return true;
+  }
+  // `tagName` is uppercase for HTML elements but can be mixed-case for
+  // XML/SVG. Normalize once so downstream comparisons stay lowercase.
+  var tag = element.tagName.toLowerCase();
+  if (tag === 'textarea') {
+    return true;
+  }
+  if (element.isContentEditable) {
+    return true;
+  }
+  if (tag === 'input') {
+    var _element$getAttribute;
+    var type = ((_element$getAttribute = element.getAttribute('type')) !== null && _element$getAttribute !== void 0 ? _element$getAttribute : 'text').toLowerCase();
+    return TEXT_LIKE_INPUT_TYPES.has(type);
+  }
+  return false;
+}
+function isComboboxControllingPopup(_ref) {
+  var _active$getAttribute;
+  var container = _ref.container;
+  var ownerDocument = container.ownerDocument;
+  var active = ownerDocument.activeElement;
+  if (!(active instanceof HTMLElement)) {
+    return false;
+  }
+  if (!isTextboxLikeElement(active)) {
+    return false;
+  }
+
+  // Accept legacy `aria-owns` in addition to `aria-controls`.
+  // `aria-controls` / `aria-owns` are IDREFS (space-separated list of IDs)
+  // per the WAI-ARIA spec, so we must split and check membership rather
+  // than comparing with strict equality. A combobox that controls both
+  // this popup and another element (e.g. a results status region) must
+  // still be recognised as controlling this popup.
+  var idRefs = (_active$getAttribute = active.getAttribute('aria-controls')) !== null && _active$getAttribute !== void 0 ? _active$getAttribute : active.getAttribute('aria-owns');
+  if (!idRefs) {
+    return false;
+  }
+
+  // Match if any referenced element IS, CONTAINS, or IS CONTAINED BY the
+  // popup container. The "contained by" case covers wrapper-style adopters
+  // like react-select, where the combobox input's `aria-controls` points at
+  // a listbox element that is a descendant of the Popover host (the
+  // listbox role lives on a child the wrapped library owns, not on the
+  // host we render).
+  var referencedIds = idRefs.split(/\s+/).filter(function (id) {
+    return id !== '';
+  });
+  return referencedIds.some(function (id) {
+    var referenced = ownerDocument.getElementById(id);
+    if (!referenced) {
+      return false;
+    }
+    return referenced === container || referenced.contains(container) || container.contains(referenced);
+  });
+}
+function getInitialFocusTarget(_ref2) {
+  var container = _ref2.container,
+    role = _ref2.role;
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     var autofocusEl = container.querySelector('[autofocus]');
@@ -38,6 +134,13 @@ function getInitialFocusTarget(_ref) {
     });
   }
   if (role === 'menu') {
+    // ARIA Combobox Pattern: if the popup is owned by a focused combobox,
+    // leave focus on the textbox. Navigation is proxied via the combobox.
+    if (isComboboxControllingPopup({
+      container: container
+    })) {
+      return null;
+    }
     // Initial focus placement is the extent of what top-layer provides
     // for menus. All subsequent keyboard navigation (arrow keys, Home/End,
     // type-ahead, Enter/Space, submenu coordination) is the responsibility
@@ -49,11 +152,31 @@ function getInitialFocusTarget(_ref) {
     });
   }
   if (role === 'listbox') {
-    // Prefer selected option, fall back to first focusable
+    // ARIA Combobox Pattern: if the popup is owned by a focused
+    // combobox-like textbox (in-popup or external e.g. react-select),
+    // leave focus on the textbox. Navigation is proxied via the combobox.
+    if (isComboboxControllingPopup({
+      container: container
+    })) {
+      return null;
+    }
+    // Prefer the selected option, then fall back to the first option.
+    // We intentionally match by `[role="option"]` rather than by
+    // `getFirstFocusable`. The standard WAI-ARIA APG listbox pattern
+    // renders options with `tabindex="-1"` (managed via roving
+    // tabindex); `getFirstFocusable` excludes `tabindex="-1"` elements
+    // and would silently lose initial focus for spec-conformant
+    // listboxes. Options remain programmatically focusable.
     var selectedOption = container.querySelector('[role="option"][aria-selected="true"]');
     if (selectedOption) {
       return selectedOption;
     }
+    var firstOption = container.querySelector('[role="option"]');
+    if (firstOption) {
+      return firstOption;
+    }
+    // Last resort for non-standard listboxes that render no options
+    // but do contain a focusable element (e.g. an empty-state action).
     return (0, _getFirstFocusable.getFirstFocusable)({
       container: container
     });
@@ -76,58 +199,81 @@ function getInitialFocusTarget(_ref) {
  * Role is taken from the typed `role` prop - this is the consumer's contract
  * and is not subject to drift from a directly-mutated DOM attribute.
  *
- * Always call this hook unconditionally. Focus is only moved when `isOpen`
- * transitions to `true` and the role requires it.
+ * Always call this hook unconditionally. Focus is moved on each transition
+ * into a visible phase, the moment the host element first becomes visible
+ * for that open intent:
+ *
+ * - Animated path: on `closed → entering`. The host has just been mounted
+ *   and the layout effect that calls `showPopover()` / `showModal()` has
+ *   already run, so the element is in the top layer. We focus before the
+ *   entry transition settles to match the WAI-ARIA APG expectation that
+ *   focus lands on the new menu / dialog the instant it opens, not after
+ *   the CSS finishes animating.
+ * - Non-animated path: on `closed → open` (the entering phase is skipped).
+ * - Reopen mid-exit: on `exiting → entering`. When a user dismisses the
+ *   popup (Escape, close button, light dismiss) the browser natively
+ *   restores focus to the trigger as part of `hidePopover()` /
+ *   `<dialog>.close()`. If the consumer reopens before the exit transition
+ *   has settled, the phase machine jumps `exiting → entering` without
+ *   passing through `closed`, so without this branch the popup would be
+ *   visible again with focus stranded on the trigger — a keyboard usability
+ *   gap for menu/dialog/listbox roles.
+ *
+ * Note: there is a rare programmatic path where a consumer flips `isOpen`
+ * false → true without any user-initiated close gesture and had moved focus
+ * to a non-default target inside the popup. In that scenario this hook
+ * re-focuses the role-appropriate default (e.g. first menu item) rather
+ * than preserving the consumer-chosen target. This matches the documented
+ * `closed → entering` behavior and is considered acceptable given how
+ * abstract the scenario is. See `notes/architecture/focus.md`.
+ *
+ * Pure `entering → exiting → entering` stutters where the popup never
+ * reaches `closed` and the consumer toggles in the same frame are still
+ * collapsed: the `prevPhase` ref guard rejects any transition whose
+ * previous phase was not `closed` or `exiting`.
+ *
+ * Tradeoff vs the previous `requestAnimationFrame` based approach: we no
+ * longer wait one paint before focusing. The element is already attached
+ * and in the top layer when this effect runs (the show / hide layout
+ * effect runs first), so screen-reader announcement and visible focus
+ * land together. If a regression appears that needs the extra paint
+ * (e.g. browsers that require a layout pass before `focus()` works on a
+ * freshly promoted top-layer element), wrap the `focus()` call in a
+ * single `requestAnimationFrame` here and re-add a same-element ref
+ * check inside the RAF callback.
  */
-function useInitialFocus(_ref2) {
-  var elementRef = _ref2.elementRef,
-    isOpen = _ref2.isOpen,
-    role = _ref2.role;
-  // Track the most recently scheduled RAF so a rapid `isOpen → false → true`
-  // transition can cancel the previous frame before its closure runs against
-  // a stale popover element. Without this, the RAF queued during the first
-  // open could fire after the second open had begun and focus the wrong
-  // instance.
-  var pendingRafRef = (0, _react.useRef)(null);
+function useInitialFocus(_ref3) {
+  var elementRef = _ref3.elementRef,
+    phase = _ref3.phase,
+    role = _ref3.role;
+  // Track the previous phase so we only focus on transitions into a
+  // visible phase from either `'closed'` (fresh mount) or `'exiting'`
+  // (mid-exit reopen where the browser has already restored focus to
+  // the trigger). Pure `entering → exiting → entering` stutters where
+  // the consumer toggles in the same frame are still collapsed.
+  var prevPhaseRef = (0, _react.useRef)('closed');
   (0, _react.useEffect)(function () {
-    if (!isOpen) {
+    var _getInitialFocusTarge;
+    var prevPhase = prevPhaseRef.current;
+    prevPhaseRef.current = phase;
+
+    // Skip the `phase === 'closed'` transitions (host is going away,
+    // nothing to focus) and any transition whose previous phase was
+    // neither `'closed'` (fresh open) nor `'exiting'` (mid-exit
+    // reopen, focus already on the trigger).
+    if (phase === 'closed') {
+      return;
+    }
+    if (prevPhase !== 'closed' && prevPhase !== 'exiting') {
       return;
     }
     var el = elementRef.current;
     if (!el) {
       return;
     }
-
-    // Cancel any RAF queued by the previous open cycle.
-    if (pendingRafRef.current !== null) {
-      cancelAnimationFrame(pendingRafRef.current);
-    }
-
-    // Use requestAnimationFrame to ensure the popover is fully rendered
-    // and visible in the top layer before attempting to move focus.
-    // showPopover() is called in useLayoutEffect (which runs before this
-    // useEffect), so by the time the RAF fires after the next paint the
-    // element is guaranteed to be in the top layer.
-    var rafId = requestAnimationFrame(function () {
-      var _getInitialFocusTarge;
-      pendingRafRef.current = null;
-      // Verify the element we captured is still the live popover. In
-      // rapid-toggle scenarios the ref may already point to a different
-      // instance - skip rather than focus the wrong popover.
-      if (elementRef.current !== el) {
-        return;
-      }
-      (_getInitialFocusTarge = getInitialFocusTarget({
-        container: el,
-        role: role
-      })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
-    });
-    pendingRafRef.current = rafId;
-    return function () {
-      cancelAnimationFrame(rafId);
-      if (pendingRafRef.current === rafId) {
-        pendingRafRef.current = null;
-      }
-    };
-  }, [elementRef, isOpen, role]);
+    (_getInitialFocusTarge = getInitialFocusTarget({
+      container: el,
+      role: role
+    })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
+  }, [elementRef, phase, role]);
 }

package/dist/cjs/internal/use-width-from-anchor.js

@@ -22,7 +22,8 @@ var _setStyle = require("./set-style");
 function useWidthFromAnchor(_ref) {
   var mode = _ref.mode,
     popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef;
+    anchorRef = _ref.anchorRef,
+    isOpen = _ref.isOpen;
   (0, _react.useLayoutEffect)(function () {
     var node = popoverRef.current;
     if (!node) {
@@ -48,7 +49,7 @@ function useWidthFromAnchor(_ref) {
       }
 
       // JS fallback: one-off read of the anchor's width.
-      var anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      var anchor = anchorRef.current;
       if (anchor) {
         return (0, _setStyle.setStyle)({
           el: node,
@@ -80,7 +81,7 @@ function useWidthFromAnchor(_ref) {
           }]
         });
       }
-      var _anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      var _anchor = anchorRef.current;
       if (_anchor) {
         return (0, _setStyle.setStyle)({
           el: node,
@@ -103,5 +104,5 @@ function useWidthFromAnchor(_ref) {
       el: node,
       styles: [minInlineSizeStyle]
     });
-  }, [mode, popoverRef, anchorRef]);
+  }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/cjs/popover/popover.js

@@ -86,20 +86,32 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
-    showChildren = _useAnimatedVisibilit.showChildren,
+    phase = _useAnimatedVisibilit.phase,
     preset = _useAnimatedVisibilit.preset;
 
-  // Focus management: initial focus on open (role-dependent), Tab cycling
+  // Pre-computed phase predicate. `isVisible` mirrors "host element is
+  // mounted and on screen" (any phase except `closed`); used as a dep
+  // signal for listener-re-bind effects so they re-attach to the fresh
+  // host element after a close → reopen unmount/remount cycle.
+  var isVisible = phase !== 'closed';
+
+  // Focus management: initial focus on entry (role-dependent), Tab cycling
   // for dialog roles. Restoration is native for outermost popovers; nested
   // focus-capturing roles are handled below via `beforetoggle` snapshot.
   // See: notes/architecture/focus-restoration.md
+  //
+  // Both hooks take `phase` directly: `useFocusWrap` keeps its listener
+  // attached while `phase !== 'closed'` (so focus stays trapped through
+  // the animated-exit window — WCAG 2.4.3 regression guard);
+  // `useInitialFocus` moves focus on the transition into `'open'`.
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
-    role: role
+    role: role,
+    phase: phase
   });
   (0, _useInitialFocus.useInitialFocus)({
     elementRef: ownRef,
-    isOpen: isOpen,
+    phase: phase,
     role: role
   });
 
@@ -196,7 +208,23 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       });
     }
   }, [onClose, onOpenChange, role]);
-  (0, _react.useEffect)(function () {
+
+  // Bind toggle/beforetoggle/keydown listeners via `useLayoutEffect` so
+  // they are attached BEFORE the show/hide layout effect calls
+  // `el.showPopover()`. `showPopover()` dispatches `beforetoggle`
+  // synchronously; binding the listener in a regular `useEffect`
+  // (which runs after layout effects) misses that first dispatch and
+  // the `previouslyFocusedElementRef` snapshot never gets taken — which
+  // breaks nested-popover focus restoration on close.
+  //
+  // `isVisible` is in deps so the listeners re-bind to the new host
+  // element after a host unmount/remount cycle. The cleanup detaches
+  // the old listeners.
+  //
+  // This layout effect MUST appear in the file before the show/hide
+  // layout effect — React runs layout effects in source order on the
+  // same commit, and we need listeners attached first.
+  (0, _react.useLayoutEffect)(function () {
     var element = ownRef.current;
     if (!element) {
       return;
@@ -228,10 +256,13 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       unbindToggle();
       unbindBeforeToggle();
     };
-  }, [handleToggle, handleBeforeToggle]);
+  }, [handleToggle, handleBeforeToggle, isVisible]);
 
   // Placement-dependent animation CSS vars. Kept separate from show/hide
-  // so preset reference changes do not re-trigger visibility.
+  // so preset reference changes do not re-trigger visibility. `isVisible`
+  // is in deps so the CSS vars are re-applied to the new host element after
+  // a remount cycle (otherwise the freshly mounted element would have no
+  // transform / placement vars set).
   (0, _react.useLayoutEffect)(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -246,7 +277,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
         value = _ref3[1];
       el.style.setProperty(key, String(value));
     });
-  }, [preset, placement]);
+  }, [preset, placement, isVisible]);
 
   // Show/hide based on isOpen. `showPopover`/`hidePopover` are no-ops when
   // already in the target state. Try/catch guards `InvalidStateError` on
@@ -258,6 +289,13 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     }
     if (isOpen) {
       programmaticCloseRef.current = false;
+      // Reset the close-reason snapshot at the start of every open
+      // cycle. The ref outlives the host element (lives on the
+      // component, not the DOM), so a stale 'escape' from a prior
+      // cycle would otherwise leak into the next close — especially
+      // in the no-animation path where the host unmounts before
+      // `handleToggle` has a chance to reset the ref itself.
+      closeReasonRef.current = 'light-dismiss';
       try {
         el.showPopover();
       } catch (_unused) {}
@@ -273,6 +311,17 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       el.hidePopover();
     } catch (_unused3) {}
   }, [isOpen]);
+
+  // The host element is only rendered while the popover is open or its exit
+  // animation is playing. Once the phase returns to `closed`, we unmount
+  // the host entirely so it does not leave an empty `role="..."` /
+  // `popover` element in the accessibility tree. The element re-mounts on
+  // the next `isOpen=true` commit; refs and event listeners re-bind via
+  // the existing layout effect and `useEffect`. The popover `id` is stable
+  // across opens (derived from `useId()` or the consumer-supplied `idProp`).
+  if (!isVisible) {
+    return null;
+  }
   return /*#__PURE__*/_react.default.createElement("div", (0, _extends2.default)({
     ref: combinedRef,
     id: popoverId
@@ -287,5 +336,5 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   }, preset ? (0, _defineProperty2.default)({}, "data-ds-popover-".concat(preset.name), '') : undefined, {
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop -- xcss prop passes compiled atomic class names
     className: (0, _runtime.ax)([styles.root, xcssFromProps])
-  }), showChildren ? children : null);
+  }), children);
 });

package/dist/es2019/animations/presets.js

@@ -1,6 +1,82 @@
 import { getPlacement } from '../internal/resolve-placement';
+// ══════════════════════════════════════════════════════════════════════════════
+// Popover presets
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── popupMotion ──
+
+const POPUP_MOTION_CSS = `
+  [data-ds-popover-popup-motion] {
+    animation: var(--ds-popover-motion-exit);
+    animation-fill-mode: forwards;
+    transition:
+      overlay 150ms allow-discrete,
+      display 150ms allow-discrete;
+  }
+
+  [data-ds-popover-popup-motion]:popover-open {
+    animation: var(--ds-popover-motion-enter);
+    animation-fill-mode: backwards;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-ds-popover-popup-motion],
+    [data-ds-popover-popup-motion]:popover-open {
+      animation: none;
+      transition-duration: 0s;
+    }
+  }
+`;
+function getPopupMotionProperties({
+  placement
+}) {
+  const {
+    axis,
+    edge
+  } = getPlacement({
+    placement
+  });
+  if (axis === 'block' && edge === 'start') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-top, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInTop8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-top, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutTop8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-left, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInLeft8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-left, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutLeft8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-right, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInRight8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-right, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutRight8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  // Default: block/end (popover below trigger)
+  return {
+    '--ds-popover-motion-enter': "var(--ds-popup-enter-bottom, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInBottom8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+    '--ds-popover-motion-exit': "var(--ds-popup-exit-bottom, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutBottom8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+  };
+}
+
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function popupMotion() {
+  return {
+    name: 'popup-motion',
+    css: POPUP_MOTION_CSS,
+    enterDurationMs: 150,
+    exitDurationMs: 100,
+    getProperties: ({
+      placement
+    }) => getPopupMotionProperties({
+      placement
+    })
+  };
+}
 
-// slideAndFade
+// ── slideAndFade ──
 
 function getSlideAndFadeProperties({
   placement,
@@ -106,6 +182,7 @@ const SLIDE_AND_FADE_CSS = `
  * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function slideAndFade(options) {
   var _options$distance;
   const distance = (_options$distance = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance !== void 0 ? _options$distance : 4;
@@ -235,7 +312,73 @@ export function scaleAndFade() {
 // Dialog presets
 // ══════════════════════════════════════════════════════════════════════════════
 
-// dialogSlideUpAndFade
+// ── dialogMotion ──
+
+const DIALOG_MOTION_CSS = `
+  [data-ds-dialog-motion] {
+    animation: ${"var(--ds-modal-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) ScaleOut100to95)"};
+    animation-fill-mode: forwards;
+    transition:
+      overlay 200ms allow-discrete,
+      display 200ms allow-discrete;
+  }
+
+  [data-ds-dialog-motion][open] {
+    animation: ${"var(--ds-modal-enter, 250ms cubic-bezier(0.4, 0, 0, 1) ScaleIn95to100)"};
+    animation-fill-mode: backwards;
+  }
+
+  [data-ds-dialog-motion]::backdrop {
+    animation: ${"var(--ds-blanket-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"};
+    animation-fill-mode: forwards;
+    background-color: var(--ds-blanket, #050C1F75);
+    transition:
+      overlay 200ms allow-discrete,
+      display 200ms allow-discrete;
+  }
+
+  [data-ds-dialog-motion][open]::backdrop {
+    animation: ${"var(--ds-blanket-enter, 250ms cubic-bezier(0.4, 0, 0, 1) FadeIn0to100)"};
+    animation-fill-mode: backwards;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-ds-dialog-motion],
+    [data-ds-dialog-motion][open],
+    [data-ds-dialog-motion]::backdrop,
+    [data-ds-dialog-motion][open]::backdrop {
+      animation: none;
+      transition-duration: 0s;
+    }
+  }
+`;
+
+/**
+ * Dialog motion animation.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogMotion } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogMotion()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function dialogMotion() {
+  // Bare preset name; `Dialog` prefixes it via `data-ds-dialog-{name}`.
+  return {
+    name: 'motion',
+    css: DIALOG_MOTION_CSS,
+    enterDurationMs: 250,
+    exitDurationMs: 200
+  };
+}
+
+// ── dialogSlideUpAndFade ──
 
 const DIALOG_SLIDE_UP_AND_FADE_CSS = `
 [data-ds-dialog-slide-up-and-fade] {