@atlaskit/top-layer 0.15.0 → 0.17.0

package/dist/es2019/internal/use-focus-wrap.js

@@ -4,7 +4,6 @@ import { getFirstFocusable } from '../focus/get-first-focusable';
 import { getLastFocusable } from '../focus/get-last-focusable';
 import { getNextFocusable } from '../focus/get-next-focusable';
 import { isNestedLayerFocused } from '../focus/is-nested-layer-focused';
-
 /**
  * Roles that require focus wrapping per WAI-ARIA APG.
  *
@@ -45,11 +44,13 @@ function roleRequiresFocusWrap(role) {
  */
 export function useFocusWrap({
   elementRef,
-  role
+  role,
+  phase
 }) {
+  const isVisible = phase !== 'closed';
   useEffect(() => {
     const element = elementRef.current;
-    if (!element || !roleRequiresFocusWrap(role)) {
+    if (!element || !roleRequiresFocusWrap(role) || !isVisible) {
       return;
     }
     const unbind = bind(element, {
@@ -100,5 +101,5 @@ export function useFocusWrap({
       }
     });
     return unbind;
-  }, [elementRef, role]);
+  }, [elementRef, role, isVisible]);
 }

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

@@ -1,6 +1,5 @@
 import { useEffect, useRef } from 'react';
 import { getFirstFocusable } from '../focus/get-first-focusable';
-
 /**
  * Determines the correct element to receive initial focus within a popover,
  * based on its ARIA role.
@@ -17,7 +16,102 @@ import { getFirstFocusable } from '../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/
  */
+// `<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.
+const TEXT_LIKE_INPUT_TYPES = new Set(['text', 'search', 'email', 'url', 'tel', 'password']);
+function isTextboxLikeElement(element) {
+  const 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.
+  const tag = element.tagName.toLowerCase();
+  if (tag === 'textarea') {
+    return true;
+  }
+  if (element.isContentEditable) {
+    return true;
+  }
+  if (tag === 'input') {
+    var _element$getAttribute;
+    const 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({
+  container
+}) {
+  var _active$getAttribute;
+  const ownerDocument = container.ownerDocument;
+  const 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.
+  const 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).
+  const referencedIds = idRefs.split(/\s+/).filter(id => id !== '');
+  return referencedIds.some(id => {
+    const referenced = ownerDocument.getElementById(id);
+    if (!referenced) {
+      return false;
+    }
+    return referenced === container || referenced.contains(container) || container.contains(referenced);
+  });
+}
 function getInitialFocusTarget({
   container,
   role
@@ -34,6 +128,13 @@ function getInitialFocusTarget({
     });
   }
   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
+    })) {
+      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
@@ -45,11 +146,31 @@ function getInitialFocusTarget({
     });
   }
   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
+    })) {
+      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.
     const selectedOption = container.querySelector('[role="option"][aria-selected="true"]');
     if (selectedOption) {
       return selectedOption;
     }
+    const 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 getFirstFocusable({
       container
     });
@@ -72,59 +193,82 @@ function getInitialFocusTarget({
  * 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.
  */
 export function useInitialFocus({
   elementRef,
-  isOpen,
+  phase,
   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.
-  const pendingRafRef = useRef(null);
+  // 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.
+  const prevPhaseRef = useRef('closed');
   useEffect(() => {
-    if (!isOpen) {
+    var _getInitialFocusTarge;
+    const 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;
     }
     const 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.
-    const rafId = requestAnimationFrame(() => {
-      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
-      })) === null || _getInitialFocusTarge === void 0 ? void 0 : _getInitialFocusTarge.focus();
-    });
-    pendingRafRef.current = rafId;
-    return () => {
-      cancelAnimationFrame(rafId);
-      if (pendingRafRef.current === rafId) {
-        pendingRafRef.current = null;
-      }
-    };
-  }, [elementRef, isOpen, role]);
+    (_getInitialFocusTarge = getInitialFocusTarget({
+      container: el,
+      role
+    })) === null || _getInitialFocusTarge === void 0 ? void 0 : _getInitialFocusTarge.focus();
+  }, [elementRef, phase, role]);
 }

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

@@ -17,7 +17,8 @@ import { setStyle } from './set-style';
 export function useWidthFromAnchor({
   mode,
   popoverRef,
-  anchorRef
+  anchorRef,
+  isOpen
 }) {
   useLayoutEffect(() => {
     const node = popoverRef.current;
@@ -44,7 +45,7 @@ export function useWidthFromAnchor({
       }
 
       // JS fallback: one-off read of the anchor's width.
-      const anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      const anchor = anchorRef.current;
       if (anchor) {
         return setStyle({
           el: node,
@@ -76,7 +77,7 @@ export function useWidthFromAnchor({
           }]
         });
       }
-      const anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      const anchor = anchorRef.current;
       if (anchor) {
         return setStyle({
           el: node,
@@ -99,5 +100,5 @@ export function useWidthFromAnchor({
       el: node,
       styles: [minInlineSizeStyle]
     });
-  }, [mode, popoverRef, anchorRef]);
+  }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/es2019/popover/popover.js

@@ -2,7 +2,7 @@
 import _extends from "@babel/runtime/helpers/extends";
 import "./popover.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 { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import once from '@atlaskit/ds-lib/once';
@@ -70,7 +70,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // dropped (React 19.2 uses underscores).
   const popoverId = idProp !== null && idProp !== void 0 ? idProp : `popover-${autoId.replace(/:/g, '')}`;
   const {
-    showChildren,
+    phase,
     preset
   } = useAnimatedVisibility({
     isOpen,
@@ -80,17 +80,29 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     onExitFinish
   });
 
-  // 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.
+  const 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'`.
   useFocusWrap({
     elementRef: ownRef,
-    role
+    role,
+    phase
   });
   useInitialFocus({
     elementRef: ownRef,
-    isOpen,
+    phase,
     role
   });
 
@@ -187,7 +199,23 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       });
     }
   }, [onClose, onOpenChange, role]);
-  useEffect(() => {
+
+  // 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.
+  useLayoutEffect(() => {
     const element = ownRef.current;
     if (!element) {
       return;
@@ -219,10 +247,13 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       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).
   useLayoutEffect(() => {
     const el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -234,7 +265,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     Object.entries(props).forEach(([key, value]) => {
       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
@@ -246,6 +277,13 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     }
     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 {}
@@ -261,6 +299,17 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       el.hidePopover();
     } catch {}
   }, [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.createElement("div", _extends({
     ref: combinedRef,
     id: popoverId
@@ -277,5 +326,5 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   } : undefined, {
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop -- xcss prop passes compiled atomic class names
     className: ax([styles.root, xcssFromProps])
-  }), showChildren ? children : null);
+  }), children);
 });

package/dist/esm/animations/presets.js

@@ -1,17 +1,71 @@
 import { getPlacement } from '../internal/resolve-placement';
+// ══════════════════════════════════════════════════════════════════════════════
+// Popover presets
+// ══════════════════════════════════════════════════════════════════════════════
 
-// slideAndFade
+// ── popupMotion ──
 
-function getSlideAndFadeProperties(_ref) {
-  var placement = _ref.placement,
-    distance = _ref.distance;
-  var pos = "".concat(distance, "px");
-  var neg = "-".concat(distance, "px");
+var POPUP_MOTION_CSS = "\n  [data-ds-popover-popup-motion] {\n    animation: var(--ds-popover-motion-exit);\n    animation-fill-mode: forwards;\n    transition:\n      overlay 150ms allow-discrete,\n      display 150ms allow-discrete;\n  }\n\n  [data-ds-popover-popup-motion]:popover-open {\n    animation: var(--ds-popover-motion-enter);\n    animation-fill-mode: backwards;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    [data-ds-popover-popup-motion],\n    [data-ds-popover-popup-motion]:popover-open {\n      animation: none;\n      transition-duration: 0s;\n    }\n  }\n";
+function getPopupMotionProperties(_ref) {
+  var placement = _ref.placement;
   var _getPlacement = getPlacement({
       placement: placement
     }),
     axis = _getPlacement.axis,
     edge = _getPlacement.edge;
+  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: function getProperties(_ref2) {
+      var placement = _ref2.placement;
+      return getPopupMotionProperties({
+        placement: placement
+      });
+    }
+  };
+}
+
+// ── slideAndFade ──
+
+function getSlideAndFadeProperties(_ref3) {
+  var placement = _ref3.placement,
+    distance = _ref3.distance;
+  var pos = "".concat(distance, "px");
+  var neg = "-".concat(distance, "px");
+  var _getPlacement2 = getPlacement({
+      placement: placement
+    }),
+    axis = _getPlacement2.axis,
+    edge = _getPlacement2.edge;
   if (axis === 'block' && edge === 'start') {
     return {
       '--ds-popover-tx': '0',
@@ -64,14 +118,15 @@ var SLIDE_AND_FADE_CSS = "\n[data-ds-popover-slide-and-fade] {\n  opacity: 0;\n
  * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function slideAndFade(options) {
   var _options$distance;
   var distance = (_options$distance = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance !== void 0 ? _options$distance : 4;
   return {
     name: 'slide-and-fade',
     css: SLIDE_AND_FADE_CSS,
-    getProperties: function getProperties(_ref2) {
-      var placement = _ref2.placement;
+    getProperties: function getProperties(_ref4) {
+      var placement = _ref4.placement;
       return getSlideAndFadeProperties({
         placement: placement,
         distance: distance
@@ -138,7 +193,36 @@ export function scaleAndFade() {
 // Dialog presets
 // ══════════════════════════════════════════════════════════════════════════════
 
-// dialogSlideUpAndFade
+// ── dialogMotion ──
+
+var DIALOG_MOTION_CSS = "\n  [data-ds-dialog-motion] {\n    animation: ".concat("var(--ds-modal-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) ScaleOut100to95)", ";\n    animation-fill-mode: forwards;\n    transition:\n      overlay 200ms allow-discrete,\n      display 200ms allow-discrete;\n  }\n\n  [data-ds-dialog-motion][open] {\n    animation: ", "var(--ds-modal-enter, 250ms cubic-bezier(0.4, 0, 0, 1) ScaleIn95to100)", ";\n    animation-fill-mode: backwards;\n  }\n\n  [data-ds-dialog-motion]::backdrop {\n    animation: ", "var(--ds-blanket-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)", ";\n    animation-fill-mode: forwards;\n    background-color: var(--ds-blanket, #050C1F75);\n    transition:\n      overlay 200ms allow-discrete,\n      display 200ms allow-discrete;\n  }\n\n  [data-ds-dialog-motion][open]::backdrop {\n    animation: ", "var(--ds-blanket-enter, 250ms cubic-bezier(0.4, 0, 0, 1) FadeIn0to100)", ";\n    animation-fill-mode: backwards;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    [data-ds-dialog-motion],\n    [data-ds-dialog-motion][open],\n    [data-ds-dialog-motion]::backdrop,\n    [data-ds-dialog-motion][open]::backdrop {\n      animation: none;\n      transition-duration: 0s;\n    }\n  }\n");
+
+/**
+ * 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 ──
 
 var DIALOG_SLIDE_UP_AND_FADE_CSS = "\n[data-ds-dialog-slide-up-and-fade] {\n  opacity: 0;\n  transform: translateY(calc(-1 * var(--ds-dialog-ty, 12px)));\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open] {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open] {\n    opacity: 0;\n    transform: translateY(var(--ds-dialog-ty, 12px));\n  }\n}\n\n[data-ds-dialog-slide-up-and-fade]::backdrop {\n  background-color: transparent;\n  transition:\n    background-color 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-dialog-slide-up-and-fade],\n  [data-ds-dialog-slide-up-and-fade][open],\n  [data-ds-dialog-slide-up-and-fade]::backdrop,\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n";