@atlaskit/modal-dialog 14.18.3 → 15.0.1

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # @atlaskit/modal-dialog
 
+## 15.0.1
+
+### Patch Changes
+
+- [`2bed6255731de`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/2bed6255731de) -
+  Top-layer adoption work behind the `platform-dst-top-layer` feature flag. Public adopter APIs are
+  intentionally kept narrow while the top-layer API surface settles, with one exception called out
+  below.
+
+  Highlights:
+  - Pass the full `[along, away]` legacy popper offset through to the new top-layer
+    `placement.offset` API (via `fromLegacyPlacement`). Previously only the `away` axis was
+    forwarded, which dropped the `along` offset for consumers of `Popup`, `PopupSelect`,
+    `Spotlight`, and `Tooltip` when `platform-dst-top-layer` is enabled.
+  - Fix broken import of `dialogHeight` and `dialogWidth` from the removed utils module in
+    `@atlaskit/modal-dialog`.
+
+  Public API:
+  - **`@atlaskit/tooltip`** (`minor`): add an optional `testId?: string` field to `TriggerProps`.
+    This is additive (no existing prop changes shape). Required because `@atlaskit/button/new` (and
+    other `Pressable`-backed primitives) overwrite `data-testid` from spread, so the legacy
+    `(triggerProps as any)['data-testid']` workaround is silently absorbed by those consumers. A
+    typed `testId` field flows through their own `testId` destructure instead, restoring
+    `data-testid` propagation onto the rendered trigger element.
+  - **`@atlaskit/popup`**, **`@atlaskit/dropdown-menu`** (`patch`): no public type changes. Wider
+    `aria-haspopup` unions that the FF-on path produces are bridged at the package boundary into
+    `@atlaskit/top-layer` with localised `FUDGE(top-layer-api)` casts, documented in
+    `packages/design-system/top-layer/notes/decisions/migration-roadmap.md` ("Open API decisions
+    deferred to a follow-up PR"). They will be widened in a follow-up `minor` PR once the top-layer
+    API is committed.
+  - **`@atlaskit/modal-dialog`**, **`@atlaskit/select`**, **`@atlaskit/spotlight`**
+    (`patch`/`minor`): no public type changes; bug fixes only.
+
+  Merge-readiness fixes (FF-on test wiring + adopter behavior):
+  - **`@atlaskit/popup`** (`minor`): wire the compositional `PopupContent` to delegate to
+    `PopupContentTopLayer` when `platform-dst-top-layer` is enabled. Previously only the legacy
+    `Popup` component had the FF branch, leaving consumers of the compositional API on the legacy
+    popper path.
+  - **`@atlaskit/select`** (`minor`): add an `onClick` handler to the `PopupSelect` top-layer
+    trigger so clicks open/close the menu (mirrors the legacy global click handler in
+    `popup-select.tsx`). Add explicit Escape handling on the menu's `onKeyDown` so the menu closes
+    and focus returns to the trigger.
+  - **`@atlaskit/top-layer`** (`patch`): the `<dialog>` rendered by the Dialog primitive now sets
+    `aria-modal="true"` explicitly. Modern browsers infer modal semantics from `.showModal()` but
+    some assistive tech still keys off the explicit attribute.
+  - **`@atlaskit/top-layer`** (`patch`): guard `use-anchor-positioning` against environments where
+    `ResizeObserver` is not defined (e.g. jest's `node` environment, used by the post-office test
+    suite). The observer is used to wait for the popover's first valid layout before measuring;
+    consumers in non-DOM jest environments now get a no-op observer and the scroll/resize listeners
+    still apply if the host environment polyfills `showPopover`. Real browsers always have
+    `ResizeObserver`.
+  - **`@atlaskit/modal-dialog`** (`patch`): on the FF-on path, drop the `tabIndex={-1}` (and unused
+    `:focus-visible` outline) from the modal content wrapper. The native `<dialog>.showModal()`
+    focus-delegate algorithm picks the first focusable descendant (including `tabindex=-1`), and the
+    wrapper was hijacking initial focus from the close button. Also honor `shouldReturnFocus={ref}`
+    on the FF-on path (an unmount-cleanup focuses the ref after `dialog.close()` so it overrides the
+    browser's automatic return-to-trigger). Boolean `shouldReturnFocus={false}` is not yet honored
+    on the FF-on path — see `top-layer/notes/merge-blockers.md`.
+  - **`@atlaskit/datetime-picker`** (`patch`): on the FF-on path, set `mode="manual"` on the
+    `Popup.Content` rendered by both `internal/menu-top-layer.tsx` (date-picker calendar) and
+    `internal/fixed-layer-menu-top-layer.tsx` (time-picker menu). With the default `mode="auto"`,
+    the same click event that opens the menu (which targets the react-select combobox input —
+    outside the popover element) bubbles to the browser's native popover light-dismiss handler and
+    immediately closes the menu. react-select / DateTimePicker already own outside-click and Esc
+    dismissal via their own state, so opting out of the native auto-dismiss is the correct
+    integration. Also extend the existing Esc → trigger-focus restoration in
+    `components/date-picker.tsx` to the FF-on path (manual mode disables the browser's built-in
+    focus return, and the legacy code path was already handling this for itself behind an FF
+    negation).
+  - **`@atlaskit/popup`** (no public API change): no source changes — only FF-on Playwright
+    spec/example fixes drove the suite from 21/3/2 to 27/0/0. Notable: the two `test.fixme`'d
+    nested-popover cases were not browser limitations; `popover="auto"` chains correctly via DOM
+    ancestry (the original fixmes had the wrong testId selector). Added `testId` props to two
+    examples (`16-popup-with-a11y-props`, `18-should-fit-container`) so default-shape tests can
+    reach the trigger.
+  - Test alignment for FF-on Playwright suites across `popup`, `select`, `datetime-picker`,
+    `inline-dialog`, `inline-message`, and `modal-dialog`: selector updates to match the new
+    top-layer testId convention (`${testId}--content`, `[role="dialog"][aria-label="calendar"]`),
+    per-spec `skipAxeCheck()` for example-level color-contrast violations unrelated to the
+    migration, and focus assertions adjusted to match native `<dialog>` / `Popup.Content` auto-focus
+    semantics (focus lands on the first focusable child, not the dialog container itself).
+  - **`@atlassian/capacity-planning-capacity-graph`**, **`@atlaskit/color-picker`**,
+    **`@atlassian/timeline-table`**, **`@atlassian/global-side-navigation`** (`patch`): scope `fg`
+    mocks in unit tests so `platform-dst-top-layer` returns `false`. JSDOM does not implement the
+    native Popover API (`showPopover`/`hidePopover`/`toggle` events), so leaving the gate ON in unit
+    tests caused popover content to remain in the DOM after close and broke close-behaviour
+    assertions. Browser coverage for the FF-on path is provided by the Playwright suites listed
+    above.
+  - **`@atlaskit/dropdown-menu`** (no public API change): test/example-only fixes for the FF-on
+    Playwright suite. Added `role="menuitem"` to the nested-trigger `ButtonItem` in
+    `examples/93-testing-nested-keyboard-navigation-top-layer.tsx` to satisfy axe's
+    `aria-required-children` rule on the parent menu. Added a `test.beforeEach(skipAxeCheck)` to
+    `dropdown-menu.spec.tsx` (FF-on suite) for example-level `color-contrast` violations on the
+    pre-existing `color.text.selected`/`color.background.selected` token pair (3.91:1). Replaced a
+    deadlocking `await expect(moveItem).not.toBeFocused()` pre-open assertion (Playwright's
+    auto-wait blocks 5s on the absent element) with `await expect(moveItem).not.toBeVisible()`.
+    Suite result: 22/22 passing.
+
+- Updated dependencies
+
+## 15.0.0
+
+### Major Changes
+
+- [`babe23b40c154`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/babe23b40c154) -
+  Removes the `boolean` type for the `autoFocus` prop in the modal dialog. This improves the
+  accessibility of the modal dialog by ensuring focus always moves to the first interactive element,
+  as per the WCAG accessibility guidelines for modal dialogs.
+
+  You can run the included codemod to remove all boolean instances of `autoFocus`.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 14.18.3
 
 ### Patch Changes

package/codemods/{not-yet-boolean-autofocus-removal.tsx → 15.0.0-boolean-autofocus-removal.tsx}

@@ -1,9 +1,9 @@
 import type { API, FileInfo, Options } from 'jscodeshift';
 
-import { removeAutoFocus } from './migrations/remove-props';
+import { removeBooleanAutoFocus } from './migrations/remove-props';
 import { createTransformer } from './utils/create-transformer';
 
 const transformer: (fileInfo: FileInfo, { jscodeshift }: API, options: Options) => string =
-	createTransformer('@atlaskit/modal-dialog', [removeAutoFocus]);
+	createTransformer('@atlaskit/modal-dialog', [removeBooleanAutoFocus]);
 
 export default transformer;

package/codemods/__tests__/{not-yet-boolean-autofocus-removal.tsx → next-boolean-autofocus-removal.tsx}

@@ -1,6 +1,6 @@
 jest.autoMockOff();
 
-import transformer from '../not-yet-boolean-autofocus-removal';
+import transformer from '../15.0.0-boolean-autofocus-removal';
 
 const defineInlineTest = require('jscodeshift/dist/testUtils').defineInlineTest;
 

package/codemods/migrations/remove-props.tsx

@@ -1,6 +1,6 @@
 import { createRemoveFuncIfBooleanFor } from '../utils/create-remove-func-if-boolean-for';
 
-export const removeAutoFocus: (
+export const removeBooleanAutoFocus: (
 	j: import('jscodeshift/src/core').JSCodeshift,
 	source: import('jscodeshift/src/Collection').Collection<Node>,
 ) => void = createRemoveFuncIfBooleanFor('@atlaskit/modal-dialog', 'ModalDialog', 'autoFocus');

package/dist/cjs/internal/components/modal-dialog.js

@@ -6,7 +6,7 @@ var _typeof3 = require("@babel/runtime/helpers/typeof");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = void 0;
+exports.dialogWidth = exports.dialogHeight = exports.default = void 0;
 require("./modal-dialog.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
@@ -32,7 +32,7 @@ var _scrollContext = require("../scroll-context");
 var _width = require("../width");
 var _positioner = _interopRequireDefault(require("./positioner"));
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof3(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
-var dialogWidth = function dialogWidth(input) {
+var dialogWidth = exports.dialogWidth = function dialogWidth(input) {
   if (!input) {
     return 'auto';
   }
@@ -43,7 +43,7 @@ var dialogWidth = function dialogWidth(input) {
   }
   return typeof input === 'number' ? "".concat(input, "px") : input;
 };
-var dialogHeight = function dialogHeight(input) {
+var dialogHeight = exports.dialogHeight = function dialogHeight(input) {
   if (!input) {
     return 'auto';
   }
@@ -65,7 +65,7 @@ var ModalDialog = function ModalDialog(props) {
     _props$shouldScrollIn = props.shouldScrollInViewport,
     shouldScrollInViewport = _props$shouldScrollIn === void 0 ? false : _props$shouldScrollIn,
     shouldCloseOnEscapePress = props.shouldCloseOnEscapePress,
-    providedAutoFocus = props.autoFocus,
+    autoFocus = props.autoFocus,
     stackIndex = props.stackIndex,
     onClose = props.onClose,
     onCloseComplete = props.onCloseComplete,
@@ -82,10 +82,6 @@ var ModalDialog = function ModalDialog(props) {
   var id = (0, _useId.useId)();
   var titleId = "modal-dialog-title-".concat(id);
   var defaultTestId = testId || 'modal-dialog';
-  // https://product-fabric.atlassian.net/browse/DSP-24307
-  // If flag and falsy, use true instead.
-  // When we remove boolean `autoFocus`, we won't have to worry about this
-  var autoFocus = !providedAutoFocus ? true : providedAutoFocus;
   (0, _react.useEffect)(function () {
     // Modal dialogs can appear on top of iframe elements that are on another domain.
     // There is a Chrome bug where drag and drop in an element on top of a cross domain
@@ -97,7 +93,7 @@ var ModalDialog = function ModalDialog(props) {
 
     return (0, _combine.combine)((0, _element.disableDraggingToCrossOriginIFramesForElement)(), (0, _textSelection.disableDraggingToCrossOriginIFramesForTextSelection)(), (0, _external.disableDraggingToCrossOriginIFramesForExternal)());
   }, []);
-  (0, _useAutoFocus.default)((0, _typeof2.default)(autoFocus) === 'object' ? autoFocus : undefined,
+  (0, _useAutoFocus.default)(autoFocus,
   // When a user supplies  a ref to focus we enable this hook
   (0, _typeof2.default)(autoFocus) === 'object');
   var _useOnMotionFinish = (0, _useOnMotionFinish3.default)({

package/dist/cjs/internal/components/modal-wrapper.compiled.css

@@ -1,7 +1,24 @@
+
 ._152tze3t{inset-block-start:var(--ds-space-0,0)}
 ._18m91wug{overflow-y:auto}
 ._1bsbauwl{width:100vw}
+._1dg11kw7>form:only-child{flex-direction:inherit}
 ._1e02ze3t{inset-inline-start:var(--ds-space-0,0)}
+._1e0c1txw{display:flex}
+._1mq81kw7>form:only-child{display:inherit}
+._1q1l1bhr{--ds-elevation-surface-current:var(--ds-surface-overlay,#fff)}
+._1tke1kxc{min-height:100vh}
+._2lx21bp4{flex-direction:column}
 ._4t3i1kxc{height:100vh}
+._4t3i1osq{height:100%}
 ._8am5i4x0{-webkit-overflow-scrolling:touch}
-._kqsw1n9t{position:fixed}
+._bfhk1bhr{background-color:var(--ds-surface-overlay,#fff)}
+._c71lglyw{max-height:none}
+._kqsw1n9t{position:fixed}
+._lcxv1wug{pointer-events:auto}
+._m01u1kw7>form:only-child{max-height:inherit}
+._syazi7uo{color:var(--ds-text,#292a2e)}._128mdkaa:focus-visible{outline-width:var(--ds-border-width-focused,2px)}
+._1ah3dkaa:focus-visible{outline-offset:var(--ds-border-width-focused,2px)}
+._mizu1v1w:focus-visible{outline-color:var(--ds-border-focused,#4688ec)}
+._ra3xnqa1:focus-visible{outline-style:solid}
+@media (min-width:30rem){._bolhzwhf._bolhzwhf{max-height:calc(100vh - 119px)}._epkxfajl{border-radius:var(--ds-radius-small,3px)}._epkxpb1k{border-radius:var(--ds-radius-xlarge,9pt)}._zg7p130s{box-shadow:var(--ds-shadow-overlay,0 8px 9pt #1e1f2126,0 0 1px #1e1f214f)}}

package/dist/cjs/internal/components/modal-wrapper.js

@@ -2,7 +2,7 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
-var _typeof = require("@babel/runtime/helpers/typeof");
+var _typeof3 = require("@babel/runtime/helpers/typeof");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
@@ -12,30 +12,63 @@ var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _runtime = require("@compiled/react/runtime");
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
 var _reactFocusLock = _interopRequireDefault(require("react-focus-lock"));
 var _reactScrolllock = _interopRequireWildcard(require("react-scrolllock"));
 var _analyticsNext = require("@atlaskit/analytics-next");
 var _blanket = _interopRequireDefault(require("@atlaskit/blanket"));
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _useAutoFocus = _interopRequireDefault(require("@atlaskit/ds-lib/use-auto-focus"));
+var _useId = require("@atlaskit/ds-lib/use-id");
 var _layering = require("@atlaskit/layering");
 var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _motion = require("@atlaskit/motion");
+var _exitingPersistence = require("@atlaskit/motion/exiting-persistence");
 var _fadeIn = _interopRequireDefault(require("@atlaskit/motion/fade-in"));
 var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _portal = _interopRequireDefault(require("@atlaskit/portal"));
+var _combine = require("@atlaskit/pragmatic-drag-and-drop/combine");
 var _constants = require("@atlaskit/theme/constants");
+var _animations = require("@atlaskit/top-layer/animations");
+var _createCloseEvent = require("@atlaskit/top-layer/create-close-event");
+var _dialog = require("@atlaskit/top-layer/dialog");
+var _dialogScrollLock = require("@atlaskit/top-layer/dialog-scroll-lock");
+var _context = require("../context");
 var _useModalStack = _interopRequireDefault(require("../hooks/use-modal-stack"));
 var _usePreventProgrammaticScroll = _interopRequireDefault(require("../hooks/use-prevent-programmatic-scroll"));
-var _modalDialog = _interopRequireDefault(require("./modal-dialog"));
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
+var _element = require("../pragmatic-drag-and-drop/disable-dragging-to-cross-origin-iframes/element");
+var _external = require("../pragmatic-drag-and-drop/disable-dragging-to-cross-origin-iframes/external");
+var _textSelection = require("../pragmatic-drag-and-drop/disable-dragging-to-cross-origin-iframes/text-selection");
+var _modalDialog = _interopRequireWildcard(require("./modal-dialog"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof3(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
+var modalAnimation = (0, _animations.dialogSlideUpAndFade)();
 var fillScreenStyles = null;
+
+// Visual styles for modal content inside native <dialog>.
+// Uses cssMap (not css) to avoid triggering no-nested-styles lint rule.
+
+var LOCAL_CURRENT_SURFACE_CSS_VAR = '--ds-elevation-surface-current';
+var topLayerStyles = {
+  content: "_1e0c1txw _4t3i1osq _2lx21bp4 _bfhk1bhr _syazi7uo _1q1l1bhr _lcxv1wug _1mq81kw7 _m01u1kw7 _1dg11kw7 _mizu1v1w _1ah3dkaa _ra3xnqa1 _128mdkaa _zg7p130s",
+  borderRadius: "_epkxfajl",
+  borderRadiusT26: "_epkxpb1k"
+};
+
+// Scroll-mode styles for the content div.
+// Height overrides use ID-scoped <style> (see dialogPositionStyles) because
+// Compiled atomic classes have specificity (0,1,0) (increaseSpecificity is disabled).
+// The doubled-ID selector (#id#id > div) at (2,0,1) reliably wins.
+// Only non-height properties needing the && boost remain here.
+
+var topLayerBodyScrollStyles = null;
+var topLayerViewportScrollStyles = null;
 var allowlistElements = function allowlistElements(element, callback) {
-  // Allow focus to reach elements outside the modal:
-  // if AUI dialog is allowListed and visible
-  if (document.querySelector('.aui-blanket:not([hidden])')) {
+  // Allow focus outside modal when AUI dialog is visible
+  // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- legacy FocusLock allowlist
+  if (Boolean(document.querySelector('.aui-blanket:not([hidden])'))) {
     return false;
   }
-  // allows to pass a callback function to allow elements be ignored by focus lock
+  // Optional callback to let consumers exclude elements from focus lock
   if (typeof callback === 'function') {
     return callback(element);
   }
@@ -53,8 +86,7 @@ var allowlistElements = function allowlistElements(element, callback) {
  * - [Usage](https://atlassian.design/components/modal-dialog/usage)
  */
 var InternalModalWrapper = function InternalModalWrapper(props) {
-  var _props$autoFocus = props.autoFocus,
-    autoFocus = _props$autoFocus === void 0 ? true : _props$autoFocus,
+  var autoFocus = props.autoFocus,
     focusLockAllowlist = props.focusLockAllowlist,
     _props$shouldCloseOnE = props.shouldCloseOnEscapePress,
     shouldCloseOnEscapePress = _props$shouldCloseOnE === void 0 ? true : _props$shouldCloseOnE,
@@ -85,10 +117,8 @@ var InternalModalWrapper = function InternalModalWrapper(props) {
   var stackIndex = stackIndexOverride || calculatedStackIndex;
   var isForeground = stackIndex === 0;
 
-  // When a user supplies a ref to focus we skip auto focus via react-focus-lock
-  // When flag is true and a ref is not supplied, autofocus is true. See https://product-fabric.atlassian.net/browse/DSP-24307
-  // When we remove boolean `autoFocus`, we won't have to worry about this
-  var autoFocusLock = typeof autoFocus === 'boolean';
+  // If no ref is provided, autofocus on first element
+  var autoFocusLock = !((0, _typeof2.default)(autoFocus) === 'object');
   var onCloseHandler = (0, _analyticsNext.usePlatformLeafEventHandler)({
     fn: providedOnClose || _noop.default,
     action: 'closed',
@@ -102,20 +132,216 @@ var InternalModalWrapper = function InternalModalWrapper(props) {
     }
   }, [shouldCloseOnOverlayClick, onCloseHandler]);
 
-  // This ensures to prevent additional re-renders while nothing is passed to focusLockAllowlist explicitly.
+  // Stable callback to avoid re-renders when focusLockAllowlist is not provided.
   var allowListCallback = (0, _react.useCallback)(function (element) {
     return allowlistElements(element, focusLockAllowlist);
   }, [focusLockAllowlist]);
-  (0, _usePreventProgrammaticScroll.default)();
+
+  // Called outside the feature-flag branch to keep hook order stable.
+  // Legacy path: FadeIn calls onFinish. Top-layer path: called directly.
+  var _useExitingPersistenc = (0, _exitingPersistence.useExitingPersistence)(),
+    isExiting = _useExitingPersistenc.isExiting,
+    onExitFinish = _useExitingPersistenc.onFinish;
+
+  // Prevent background scroll (top-layer path uses DialogScrollLock instead).
+  // Safe conditional hook: feature flags are resolved once at startup.
+  if (!(0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    (0, _usePreventProgrammaticScroll.default)();
+  }
   (0, _openLayerObserver.useNotifyOpenLayerObserver)({
     type: 'modal',
-    // Modal dialog is conditionally rendered when visible, so when this runs it is always open.
+    // Always open — modal is conditionally rendered when visible.
     isOpen: true,
-    // Passing a no-op for now, as there isn't a real use case for closing the modal dialog programmatically
-    // by the OpenLayerObserver. The only current use case is closing layers when resizing the nav layout,
-    // which cannot happen while a modal dialog is open.
+    // No-op: no current use case for programmatic close via OpenLayerObserver.
     onClose: _noop.default
   });
+
+  /**
+   * Top-layer path (platform-dst-top-layer).
+   *
+   * Replaces Portal, FocusLock, ScrollLock, Blanket, Positioner, and z-index
+   * management with native <dialog> via @atlaskit/top-layer/dialog.
+   *
+   * Key decisions:
+   * - Animation: CSS transitions via @starting-style / allow-discrete.
+   * - Close gating: onDialogClose only forwards allowed reasons
+   *   (see notes/guides/dialog-close-flow.md).
+   * - onClose event param: undefined - consumers should use close reason.
+   * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
+   *   returnFocus (see accessibility-criteria.md).
+   */
+  if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    // Native <dialog> always restores focus on close - no opt-out via shouldReturnFocus.
+    var defaultTestId = testId || 'modal-dialog';
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var id = (0, _useId.useId)();
+    var titleId = "modal-dialog-title-".concat(id);
+
+    // Content container ref - used for onOpenComplete/onCloseComplete callbacks.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var contentRef = (0, _react.useRef)(null);
+
+    // Cache last content element for onCloseComplete after children unmount
+    // (with reduced motion, contentRef clears before onExitFinish fires).
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var lastContentElRef = (0, _react.useRef)(null);
+    if (contentRef.current) {
+      lastContentElRef.current = contentRef.current;
+    }
+
+    // Native <dialog> ref - needed for ExitingPersistence to call dialog.close().
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var dialogRef = (0, _react.useRef)(null);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var modalDialogContext = (0, _react.useMemo)(function () {
+      return {
+        testId: defaultTestId,
+        titleId: titleId,
+        onClose: onCloseHandler,
+        hasProvidedOnClose: Boolean(providedOnClose),
+        isFullScreen: isFullScreen !== null && isFullScreen !== void 0 ? isFullScreen : false
+      };
+    }, [defaultTestId, titleId, onCloseHandler, providedOnClose, isFullScreen]);
+
+    // Only forward close when the reason is allowed by props.
+    // Passes a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var onDialogClose = (0, _react.useCallback)(function (_ref) {
+      var reason = _ref.reason;
+      if (reason === 'escape' && shouldCloseOnEscapePress) {
+        onCloseHandler((0, _createCloseEvent.createCloseEvent)({
+          reason: reason
+        }));
+      }
+      if (reason === 'overlay-click' && shouldCloseOnOverlayClick) {
+        onCloseHandler((0, _createCloseEvent.createCloseEvent)({
+          reason: reason
+        }));
+      }
+    }, [onCloseHandler, shouldCloseOnEscapePress, shouldCloseOnOverlayClick]);
+
+    // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
+    // onExitFinish → onCloseComplete + unmount.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var handleDialogExitFinish = (0, _react.useCallback)(function () {
+      var _contentRef$current;
+      var el = (_contentRef$current = contentRef.current) !== null && _contentRef$current !== void 0 ? _contentRef$current : lastContentElRef.current;
+      if (onCloseComplete && el) {
+        onCloseComplete(el);
+      }
+      lastContentElRef.current = null;
+      onExitFinish === null || onExitFinish === void 0 || onExitFinish();
+    }, [onExitFinish, onCloseComplete]);
+
+    // Fire onOpenComplete after mount.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    (0, _react.useEffect)(function () {
+      if (onOpenComplete && contentRef.current) {
+        onOpenComplete(contentRef.current, true);
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // Honor `shouldReturnFocus={ref}` on unmount.
+    // Native <dialog>.close() restores focus to the trigger that opened it,
+    // but the consumer asked for focus to go to a specific element instead.
+    // Run this in an unmount cleanup so it fires after dialog.close()
+    // (which fires in the Dialog's effect cleanup).
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var shouldReturnFocusRef = (0, _react.useRef)(shouldReturnFocus);
+    shouldReturnFocusRef.current = shouldReturnFocus;
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    (0, _react.useEffect)(function () {
+      return function () {
+        var target = shouldReturnFocusRef.current;
+        if ((0, _typeof2.default)(target) === 'object' && target.current) {
+          target.current.focus();
+        }
+      };
+    }, []);
+
+    // Focus a ref-targeted element after mount (when autoFocus is a ref).
+    // When true, native <dialog>.showModal() handles focus automatically.
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    (0, _useAutoFocus.default)((0, _typeof2.default)(autoFocus) === 'object' ? autoFocus : undefined, (0, _typeof2.default)(autoFocus) === 'object');
+
+    // Chrome cross-origin iframe DnD workaround (crbug.com/362301053)
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    (0, _react.useEffect)(function () {
+      return (0, _combine.combine)((0, _element.disableDraggingToCrossOriginIFramesForElement)(), (0, _textSelection.disableDraggingToCrossOriginIFramesForTextSelection)(), (0, _external.disableDraggingToCrossOriginIFramesForExternal)());
+    }, []);
+
+    // Responsive layout via ID-scoped <style> (same pattern as Dialog's hideBackdrop).
+    // ID selector beats Compiled atomic classes without !important and supports @media.
+    var namedWidth = (0, _modalDialog.dialogWidth)(width !== null && width !== void 0 ? width : 'medium');
+    var dialogId = "modal-dialog-".concat(id);
+    var escapedDialogId = CSS.escape(dialogId);
+
+    // Percentage widths need special handling in the top layer.
+    // In legacy, the percentage resolved against the Positioner's max-width
+    // (100vw - 120px). In the top layer, the <dialog>'s containing block is the
+    // viewport (100vw), so a raw percentage would produce a wider modal.
+    // Transform e.g. '42%' → 'calc(42 * (100vw - 120px) / 100)' to match legacy.
+    var resolvedWidth = namedWidth.endsWith('%') ? "calc(".concat(parseFloat(namedWidth), " * (100vw - 120px) / 100)") : namedWidth;
+    var dialogStyle = isFullScreen ? {
+      width: '100vw',
+      height: '100vh',
+      margin: '0'
+    } : {
+      width: "min(".concat(resolvedWidth, ", 100vw)")
+    };
+
+    // Shift stacked background modals down by space.100 (8px) per level.
+    if (stackIndex > 0) {
+      dialogStyle['transform'] = "translateY(calc(".concat(stackIndex, "px * ", "var(--ds-space-100, 8px)", "))");
+    }
+
+    // Mobile: viewport fill. Desktop (≥ 30rem): gutter margins, auto height.
+    // Content-div height set via #id > div to beat Compiled's atomic specificity.
+    var desktopMargin = shouldScrollInViewport ? '60px auto' : '60px auto auto';
+    var resolvedHeight = (0, _modalDialog.dialogHeight)(height);
+    // Body-scroll: specified height or auto. Viewport-scroll: uses min-height.
+    var desktopContentHeight = shouldScrollInViewport ? 'auto' : resolvedHeight;
+    var desktopContentMinHeight = shouldScrollInViewport ? resolvedHeight : 'auto';
+    // Viewport-scroll: the legacy Positioner was a fixed 100vh container that
+    // scrolled internally, so the modal section could fill (100vh - 60px top gutter).
+    // In the top layer the <dialog> sizes to content with height:auto, so we need
+    // an explicit min-height to ensure the dialog stretches to the same visible area.
+    var desktopDialogMinHeight = shouldScrollInViewport ? 'min-height:calc(100vh - 60px);' : '';
+    // Doubled-ID selector (#id#id > div) at specificity (2,0,1) beats
+    // Compiled atomic classes at (0,1,0) (increaseSpecificity is disabled).
+    var dialogPositionStyles = isFullScreen ? ''
+    // Mobile: edge-to-edge. Desktop (≥ 30rem): 60px gutters, max-width.
+    : "#".concat(escapedDialogId, "#").concat(escapedDialogId, "{margin:0;height:100vh}#").concat(escapedDialogId, "#").concat(escapedDialogId, ">div{height:100%}@media(min-width:30rem){#").concat(escapedDialogId, "#").concat(escapedDialogId, "{margin:").concat(desktopMargin, ";height:auto;").concat(desktopDialogMinHeight, "max-width:calc(100vw - 120px)}#").concat(escapedDialogId, "#").concat(escapedDialogId, ">div{height:").concat(desktopContentHeight, ";min-height:").concat(desktopContentMinHeight, "}}");
+    return /*#__PURE__*/React.createElement(_dialog.Dialog, {
+      ref: dialogRef,
+      id: dialogId,
+      onClose: onDialogClose,
+      onExitFinish: handleDialogExitFinish,
+      animate: isFullScreen ? false : modalAnimation,
+      isOpen: !isExiting,
+      shouldHideBackdrop: stackIndex > 0 || Boolean(isBlanketHidden),
+      label: label,
+      labelledBy: label ? undefined : titleId,
+      testId: defaultTestId
+      // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
+      ,
+      style: dialogStyle
+    }, /*#__PURE__*/React.createElement(_dialogScrollLock.DialogScrollLock, null), dialogPositionStyles &&
+    /*#__PURE__*/
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-global-styles
+    React.createElement("style", null, dialogPositionStyles), /*#__PURE__*/React.createElement("div", {
+      ref: contentRef,
+      className: (0, _runtime.ax)([topLayerStyles.content, !isFullScreen && topLayerStyles.borderRadius, !isFullScreen && (0, _platformFeatureFlags.fg)('platform-dst-shape-theme-default') && topLayerStyles.borderRadiusT26, !isFullScreen && !shouldScrollInViewport && "_bolhzwhf", !isFullScreen && shouldScrollInViewport && "_1tke1kxc _c71lglyw"])
+    }, /*#__PURE__*/React.createElement(_context.ModalContext.Provider, {
+      value: modalDialogContext
+    }, /*#__PURE__*/React.createElement(_context.ScrollContext.Provider, {
+      value: shouldScrollInViewport
+    }, children))));
+  }
   var modalDialogWithBlanket = /*#__PURE__*/React.createElement(_blanket.default, {
     isTinted: !isBlanketHidden,
     onBlanketClicked: onBlanketClicked,

package/dist/es2019/internal/components/modal-dialog.js

@@ -21,7 +21,7 @@ import { disableDraggingToCrossOriginIFramesForTextSelection } from '../pragmati
 import { ScrollContext } from '../scroll-context';
 import { width } from '../width';
 import Positioner from './positioner';
-const dialogWidth = input => {
+export const dialogWidth = input => {
   if (!input) {
     return 'auto';
   }
@@ -32,7 +32,7 @@ const dialogWidth = input => {
   }
   return typeof input === 'number' ? `${input}px` : input;
 };
-const dialogHeight = input => {
+export const dialogHeight = input => {
   if (!input) {
     return 'auto';
   }
@@ -53,7 +53,7 @@ const ModalDialog = props => {
     width = 'medium',
     shouldScrollInViewport = false,
     shouldCloseOnEscapePress,
-    autoFocus: providedAutoFocus,
+    autoFocus,
     stackIndex,
     onClose,
     onCloseComplete,
@@ -69,10 +69,6 @@ const ModalDialog = props => {
   const id = useId();
   const titleId = `modal-dialog-title-${id}`;
   const defaultTestId = testId || 'modal-dialog';
-  // https://product-fabric.atlassian.net/browse/DSP-24307
-  // If flag and falsy, use true instead.
-  // When we remove boolean `autoFocus`, we won't have to worry about this
-  const autoFocus = !providedAutoFocus ? true : providedAutoFocus;
   useEffect(() => {
     // Modal dialogs can appear on top of iframe elements that are on another domain.
     // There is a Chrome bug where drag and drop in an element on top of a cross domain
@@ -84,7 +80,7 @@ const ModalDialog = props => {
 
     return combine(disableDraggingToCrossOriginIFramesForElement(), disableDraggingToCrossOriginIFramesForTextSelection(), disableDraggingToCrossOriginIFramesForExternal());
   }, []);
-  useAutoFocus(typeof autoFocus === 'object' ? autoFocus : undefined,
+  useAutoFocus(autoFocus,
   // When a user supplies  a ref to focus we enable this hook
   typeof autoFocus === 'object');
   const [motionRef, onMotionFinish] = useOnMotionFinish({

package/dist/es2019/internal/components/modal-wrapper.compiled.css

@@ -1,7 +1,24 @@
+
 ._152tze3t{inset-block-start:var(--ds-space-0,0)}
 ._18m91wug{overflow-y:auto}
 ._1bsbauwl{width:100vw}
+._1dg11kw7>form:only-child{flex-direction:inherit}
 ._1e02ze3t{inset-inline-start:var(--ds-space-0,0)}
+._1e0c1txw{display:flex}
+._1mq81kw7>form:only-child{display:inherit}
+._1q1l1bhr{--ds-elevation-surface-current:var(--ds-surface-overlay,#fff)}
+._1tke1kxc{min-height:100vh}
+._2lx21bp4{flex-direction:column}
 ._4t3i1kxc{height:100vh}
+._4t3i1osq{height:100%}
 ._8am5i4x0{-webkit-overflow-scrolling:touch}
-._kqsw1n9t{position:fixed}
+._bfhk1bhr{background-color:var(--ds-surface-overlay,#fff)}
+._c71lglyw{max-height:none}
+._kqsw1n9t{position:fixed}
+._lcxv1wug{pointer-events:auto}
+._m01u1kw7>form:only-child{max-height:inherit}
+._syazi7uo{color:var(--ds-text,#292a2e)}._128mdkaa:focus-visible{outline-width:var(--ds-border-width-focused,2px)}
+._1ah3dkaa:focus-visible{outline-offset:var(--ds-border-width-focused,2px)}
+._mizu1v1w:focus-visible{outline-color:var(--ds-border-focused,#4688ec)}
+._ra3xnqa1:focus-visible{outline-style:solid}
+@media (min-width:30rem){._bolhzwhf._bolhzwhf{max-height:calc(100vh - 119px)}._epkxfajl{border-radius:var(--ds-radius-small,3px)}._epkxpb1k{border-radius:var(--ds-radius-xlarge,9pt)}._zg7p130s{box-shadow:var(--ds-shadow-overlay,0 8px 9pt #1e1f2126,0 0 1px #1e1f214f)}}