@atlaskit/modal-dialog 17.0.3 → 17.1.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @atlaskit/modal-dialog
 
+## 17.1.1
+
+### Patch Changes
+
+- [`f026aadea067f`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f026aadea067f) -
+  On the top-layer path (`platform-dst-top-layer`), `onClose` now runs in the same cases as on the
+  legacy path while the modal is open, and the modal stays open until you unmount it. Unlike legacy,
+  Escape and backdrop clicks during the exit animation do not call `onClose` again.
+- Updated dependencies
+
+## 17.1.0
+
+### Minor Changes
+
+- [`62c3c0411e84b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/62c3c0411e84b) -
+  Cleanup `feature_gate` `platform_dst-a11y_accessible-error-modal`. The accessible modal error
+  experience is now permanent. `ModalTrigger` and `FullScreenModalTrigger` support localized
+  `title`, `errorText`, and `errorCloseText` strings for the default error fallback. `ModalTrigger`
+  also supports a per-trigger `errorFallback`. `ModalHeader` supports a localized close-button
+  label.
+
 ## 17.0.3
 
 ### Patch Changes

package/__tests__/playwright/top-layer-escape.spec.tsx

@@ -0,0 +1,286 @@
+/* eslint-disable @repo/internal/dom-events/no-unsafe-event-listeners -- `page.evaluate` code runs in the page and cannot import `bind-event-listener` */
+
+import { expect, type Page, test } from '@af/integration-testing';
+
+const featureFlag = 'platform-dst-top-layer';
+
+// Dialog takes the Escape `keydown`, so the browser makes no close request and never closes
+// the `<dialog>` itself, even after many refused Escapes (the close-watcher rule in Chrome and
+// Firefox 149+).
+test.describe('Modal dialog: top-layer Escape never closes the dialog natively', () => {
+	test('when onClose keeps the modal open', async ({ page }) => {
+		await openModal({ page, trigger: 'refusing-trigger' });
+		const focused = page.getByTestId('modal-body-button');
+		await focused.focus();
+		await recordDialogState({ page });
+
+		await mashEscape({ page, onSpacedPress: (i) => expectCloseCount({ page, count: i }) });
+
+		// A held key asks once: 5 + 20 + 1.
+		await expectCloseCount({ page, count: 26 });
+		await expectNeverClosed({ page, escapes: 45, focusedTestId: 'modal-body-button' });
+		await expect(focused).toBeFocused();
+	});
+
+	test('when shouldCloseOnEscapePress is false', async ({ page }) => {
+		await openModal({ page, trigger: 'escape-disabled-trigger' });
+		const focused = page.getByTestId('modal-body-button');
+		await focused.focus();
+		await recordDialogState({ page });
+
+		await mashEscape({ page, onSpacedPress: () => nextFrames({ page }) });
+
+		await expectNeverClosed({ page, escapes: 45, focusedTestId: 'modal-body-button' });
+		await expectCloseCount({ page, count: 0 });
+		await expect(focused).toBeFocused();
+	});
+
+	// A click on the title moves focus to the `<dialog>`, so the modal still takes the Escape.
+	test('after a click on the title', async ({ page }) => {
+		await openModal({ page, trigger: 'refusing-trigger' });
+		await page.getByText('Escape refused', { exact: true }).click();
+		await expect(page.getByTestId('modal')).toBeFocused();
+		await recordDialogState({ page });
+
+		await mashEscape({ page, onSpacedPress: (i) => expectCloseCount({ page, count: i }) });
+
+		await expectCloseCount({ page, count: 26 });
+		await expectNeverClosed({ page, escapes: 45, focusedTestId: 'modal' });
+	});
+
+	test('a child popup takes the first Escape, the modal is asked the rest', async ({ page }) => {
+		await openModal({ page, trigger: 'refusing-trigger' });
+		await page.getByTestId('child-popup-trigger').click();
+		await expect(page.getByTestId('child-popup-button')).toBeVisible();
+		await page.getByTestId('child-popup-button').focus();
+		await recordDialogState({ page });
+
+		await page.keyboard.press('Escape');
+		await expect(page.getByTestId('child-popup-button')).toBeHidden();
+		await expectCloseCount({ page, count: 0 });
+		// Not every engine restores focus to the trigger, so focus a button.
+		const focused = page.getByTestId('modal-body-button');
+		await focused.focus();
+
+		for (let i = 0; i < 20; i++) {
+			await page.keyboard.press('Escape');
+		}
+
+		await expectCloseCount({ page, count: 20 });
+		await expectNeverClosed({ page, escapes: 21, focusedTestId: 'modal-body-button', skip: 1 });
+		await expect(focused).toBeFocused();
+	});
+});
+
+// Focus on `<body>`: focus was last in the modal, so it takes the Escape and asks once per press,
+// as legacy does. No close request, so the close-watcher rule (Chrome, Firefox 149+) never forces
+// a close. Nothing runs between the Escapes: Playwright's `page.evaluate` and `expect` grant user
+// activation, which would hide a forced close.
+test('Modal dialog: top-layer Escape after the focused element is removed asks once per press', async ({
+	page,
+}) => {
+	await openModal({ page, trigger: 'refusing-trigger' });
+	await page.getByTestId('removable-button').focus();
+	await page.keyboard.press('Enter');
+	await expect(page.getByTestId('removable-button')).toHaveCount(0);
+	await recordDialogState({ page });
+
+	for (let i = 0; i < 20; i++) {
+		await page.keyboard.press('Escape');
+	}
+
+	await expectCloseCount({ page, count: 20 });
+	await expectNeverClosed({ page, escapes: 20 });
+	expect(await page.evaluate(() => document.activeElement === document.body)).toBe(true);
+});
+
+// As in Forge: the modal is inside an open popup. Escape closes only the modal.
+test('Modal dialog: top-layer Escape in a modal inside a popup closes only the modal', async ({
+	page,
+}) => {
+	await page.visitExample<typeof import('../../examples/104-testing-escape-refused.tsx')>(
+		'design-system',
+		'modal-dialog',
+		'testing-escape-refused',
+		{ featureFlag },
+	);
+	await page.getByTestId('host-popup-trigger').click();
+	await page.getByTestId('hosted-modal-trigger').click();
+	await expect(page.getByTestId('hosted-modal')).toBeVisible();
+	await page.getByTestId('hosted-modal-button').focus();
+
+	await page.keyboard.press('Escape');
+
+	await expect(page.getByTestId('hosted-modal')).toHaveCount(0);
+	await expect(page.getByTestId('host-popup-content')).toBeVisible();
+	await expect(page.getByTestId('host-popup-close-count')).toHaveText('0');
+});
+
+// Unlike legacy: an Escape during the exit, with focus back on the trigger, does not call onClose
+// again. The modal is already closing.
+test('Modal dialog: top-layer Escape during the exit does not call onClose again', async ({
+	page,
+}) => {
+	await openModal({ page, trigger: 'closing-trigger' });
+	await page.getByTestId('modal-body-button').focus();
+	// Hold the exit open, so the next Escape is during the exit.
+	await page.addStyleTag({
+		content: 'dialog, dialog::backdrop { animation-duration: 100s !important; }',
+	});
+
+	await page.keyboard.press('Escape');
+	await expect(page.getByTestId('closing-trigger')).toBeFocused();
+	await expect(page.getByTestId('modal')).toHaveCount(1);
+	await page.keyboard.press('Escape');
+
+	await expectCloseCount({ page, count: 1 });
+});
+
+// Unlike legacy: an Escape during a nested modal's exit, with focus back on its trigger in the
+// outer modal, asks the outer modal. The nested modal is not asked again.
+test('Modal dialog: top-layer Escape during a nested modal exit asks the outer modal', async ({
+	page,
+}) => {
+	await openModal({ page, trigger: 'refusing-trigger' });
+	await page.getByTestId('nested-modal-trigger').click();
+	await expect(page.getByTestId('nested-modal')).toBeVisible();
+	await page.getByTestId('nested-modal-button').focus();
+	// Hold the exit open, so the next Escape is during the exit.
+	await page.addStyleTag({
+		content: 'dialog, dialog::backdrop { animation-duration: 100s !important; }',
+	});
+
+	await page.keyboard.press('Escape');
+	await expect(page.getByTestId('nested-modal-trigger')).toBeFocused();
+	await expect(page.getByTestId('nested-modal')).toHaveCount(1);
+	await page.keyboard.press('Escape');
+
+	await expectCloseCount({ page, count: 1 });
+	await expect(page.getByTestId('nested-close-count')).toHaveText('1');
+	// The outer modal refuses, so it stays open.
+	await expect(page.getByTestId('modal')).toHaveAttribute('open', '');
+});
+
+async function openModal({ page, trigger }: { page: Page; trigger: string }) {
+	await page.visitExample<typeof import('../../examples/104-testing-escape-refused.tsx')>(
+		'design-system',
+		'modal-dialog',
+		'testing-escape-refused',
+		{ featureFlag },
+	);
+	await page.getByTestId(trigger).click();
+	await expect(page.getByTestId('modal')).toBeVisible();
+}
+
+async function expectCloseCount({ page, count }: { page: Page; count: number }) {
+	await expect(page.getByTestId('close-count')).toHaveText(String(count));
+}
+
+async function nextFrames({ page }: { page: Page }) {
+	await page.evaluate(
+		() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))),
+	);
+}
+
+// 5 spaced presses, then 20 back to back, then 20 held (repeated `keydown`, one `keyup`).
+async function mashEscape({
+	page,
+	onSpacedPress,
+}: {
+	page: Page;
+	onSpacedPress: (pressCount: number) => Promise<void>;
+}) {
+	for (let i = 1; i <= 5; i++) {
+		await page.keyboard.press('Escape');
+		await onSpacedPress(i);
+	}
+	for (let i = 0; i < 20; i++) {
+		await page.keyboard.press('Escape');
+	}
+	for (let i = 0; i < 20; i++) {
+		await page.keyboard.down('Escape');
+	}
+	await page.keyboard.up('Escape');
+}
+
+type TDialogLog = {
+	escapes: number;
+	// The Escape count when each `cancel` fired.
+	cancelsAtEscape: number[];
+	nativeCloses: number;
+	closedToggles: number;
+	closedSamples: number;
+	focusedTestIds: (string | null)[];
+};
+
+// Records native close events, and samples `dialog.open` on every Escape and every frame.
+async function recordDialogState({ page }: { page: Page }) {
+	await page.evaluate(() => {
+		const dialog = document.querySelector('dialog');
+		if (!dialog) {
+			throw new Error('No dialog');
+		}
+		const log: TDialogLog = {
+			escapes: 0,
+			cancelsAtEscape: [],
+			nativeCloses: 0,
+			closedToggles: 0,
+			closedSamples: 0,
+			focusedTestIds: [],
+		};
+		const sample = () => {
+			if (!dialog.open) {
+				log.closedSamples++;
+			}
+		};
+		dialog.addEventListener('cancel', () => log.cancelsAtEscape.push(log.escapes));
+		dialog.addEventListener('close', () => log.nativeCloses++);
+		dialog.addEventListener('toggle', (event) => {
+			if ((event as ToggleEvent).newState === 'closed') {
+				log.closedToggles++;
+			}
+		});
+		window.addEventListener(
+			'keydown',
+			(event) => {
+				if (event.key === 'Escape') {
+					log.escapes++;
+					log.focusedTestIds.push(document.activeElement?.getAttribute('data-testid') ?? null);
+					sample();
+				}
+			},
+			true,
+		);
+		window.addEventListener('keyup', sample);
+		const onFrame = () => {
+			sample();
+			requestAnimationFrame(onFrame);
+		};
+		requestAnimationFrame(onFrame);
+		(window as unknown as { dialogLog: TDialogLog }).dialogLog = log;
+	});
+}
+
+async function expectNeverClosed({
+	page,
+	escapes,
+	focusedTestId,
+	skip = 0,
+}: {
+	page: Page;
+	escapes: number;
+	focusedTestId?: string;
+	skip?: number;
+}) {
+	const log = await page.evaluate(() => (window as unknown as { dialogLog: TDialogLog }).dialogLog);
+	expect(log.escapes).toBe(escapes);
+	// No close request after `skip`: ModalDialog took every Escape.
+	expect(log.cancelsAtEscape.filter((escape) => escape > skip)).toEqual([]);
+	expect(log.nativeCloses).toBe(0);
+	expect(log.closedToggles).toBe(0);
+	expect(log.closedSamples).toBe(0);
+	if (focusedTestId) {
+		expect(log.focusedTestIds.slice(skip)).toEqual(Array(escapes - skip).fill(focusedTestId));
+	}
+	await expect(page.getByTestId('modal')).toHaveAttribute('open', '');
+}

package/__tests__/playwright/top-layer-focus.spec.tsx

@@ -107,6 +107,7 @@ test.describe('Modal dialog: top-layer focus contract', () => {
 			},
 		});
 	});
+
 	test('focus movement: Tab traverses each control before wrapping', async ({ page }) => {
 		await page.visitExample<typeof import('../../examples/98-testing-initial-focus-matrix.tsx')>(
 			'design-system',

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

@@ -13,7 +13,6 @@ 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 _bindEventListener = require("bind-event-listener");
 var _reactFocusLock = _interopRequireDefault(require("react-focus-lock"));
 var _reactScrolllock = _interopRequireWildcard(require("react-scrolllock"));
 var _usePlatformLeafEventHandler = require("@atlaskit/analytics-next/usePlatformLeafEventHandler");
@@ -95,7 +94,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "17.0.2"
+    packageVersion: "17.1.0"
   });
 }
 function getScrollMode(_ref) {
@@ -153,7 +152,7 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
-function getDialogDismissedBy(_ref2) {
+function getDismissedBy(_ref2) {
   var shouldCloseOnEscapePress = _ref2.shouldCloseOnEscapePress,
     shouldCloseOnOverlayClick = _ref2.shouldCloseOnOverlayClick;
   if (shouldCloseOnEscapePress && shouldCloseOnOverlayClick) {
@@ -162,6 +161,10 @@ function getDialogDismissedBy(_ref2) {
   if (shouldCloseOnEscapePress) {
     return 'escape';
   }
+  // Backdrop clicks only: `Dialog` asks on both, and `onDialogAsk` ignores Escape.
+  if (shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
   return 'none';
 }
 
@@ -173,7 +176,11 @@ function getDialogDismissedBy(_ref2) {
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: Dialog only forwards allowed reasons.
+ * - Close gating: matches legacy while open. Dialog asks on Escape and backdrop
+ *   clicks (the consumer may refuse any number of times). During the exit they
+ *   do not call `onClose` again.
+ * - A close that Dialog did not ask about (e.g. `<form method="dialog">`): not
+ *   supported. Dialog shows the modal again, and `onClose` does not run.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -241,38 +248,39 @@ function ModalWrapperTopLayer(props) {
     };
   }, [defaultTestId, titleId, onCloseHandler, hasProvidedOnClose, isFullScreen]);
 
-  // Dialog has already applied the close behavior configured by `dismissedBy`.
-  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract. Dialog calls this
+  // for an allowed Escape or backdrop click.
   var onDialogClose = (0, _react.useCallback)(function (_ref3) {
     var reason = _ref3.reason;
     onCloseHandler((0, _createCloseEvent.createCloseEvent)({
       reason: reason
     }));
   }, [onCloseHandler]);
-  var dismissedBy = getDialogDismissedBy({
-    shouldCloseOnEscapePress: shouldCloseOnEscapePress,
-    shouldCloseOnOverlayClick: shouldCloseOnOverlayClick
-  });
-  var shouldShimCloseOnOverlayClick = shouldCloseOnOverlayClick && !shouldCloseOnEscapePress;
 
-  // Required until we fully remove `shouldCloseOnEscapePress`.
-  // Dialog's `dismissedBy` options do not support outside click without Escape (because it is a bad pattern)
-  (0, _react.useEffect)(function () {
-    var dialog = dialogRef.current;
-    if (!dialog || !shouldShimCloseOnOverlayClick) {
+  /**
+   * Dialog asks on an allowed Escape or backdrop click. Ignoring an Escape ask refuses it:
+   * Dialog still cancels the Escape `keydown`, so nothing else closes.
+   */
+  var onDialogAsk = (0, _react.useCallback)(function (_ref4) {
+    var reason = _ref4.reason;
+    if (reason === 'escape' && !shouldCloseOnEscapePress) {
       return;
     }
-    return (0, _bindEventListener.bind)(dialog, {
-      type: 'click',
-      listener: function listener(event) {
-        if (event.target === event.currentTarget) {
-          onDialogClose({
-            reason: 'overlay-click'
-          });
-        }
-      }
+    onDialogClose({
+      reason: reason
     });
-  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
+  }, [onDialogClose, shouldCloseOnEscapePress]);
+
+  // Unlike legacy, Escape and backdrop clicks during the exit do not call `onClose` again.
+  // See `@atlaskit/top-layer` notes: `decisions/dialog-close-flow.md`.
+
+  // Dialog could not reopen after a close it did not ask about (its parent layer is closed), so
+  // the `<dialog>` is already gone. End the exit.
+  (0, _react.useEffect)(function () {
+    if (isExiting && !dialogRef.current) {
+      onExitFinish === null || onExitFinish === void 0 || onExitFinish();
+    }
+  }, [isExiting, onExitFinish]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -321,8 +329,11 @@ function ModalWrapperTopLayer(props) {
   });
   return /*#__PURE__*/React.createElement(_dialogContent.Dialog, (0, _extends2.default)({
     ref: dialogRef,
-    onClose: onDialogClose,
-    dismissedBy: dismissedBy,
+    onClose: onDialogAsk,
+    dismissedBy: getDismissedBy({
+      shouldCloseOnEscapePress: shouldCloseOnEscapePress,
+      shouldCloseOnOverlayClick: shouldCloseOnOverlayClick
+    }),
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

package/dist/cjs/modal-header.js

@@ -30,7 +30,8 @@ var ModalHeader = function ModalHeader(props) {
   var children = props.children,
     userDefinedTestId = props.testId,
     _props$hasCloseButton = props.hasCloseButton,
-    hasCloseButton = _props$hasCloseButton === void 0 ? false : _props$hasCloseButton;
+    hasCloseButton = _props$hasCloseButton === void 0 ? false : _props$hasCloseButton,
+    closeButtonLabel = props.closeButtonLabel;
   var _useModal = (0, _hooks.useModal)(),
     hasProvidedOnClose = _useModal.hasProvidedOnClose,
     onClose = _useModal.onClose,
@@ -49,6 +50,7 @@ var ModalHeader = function ModalHeader(props) {
   }, /*#__PURE__*/_react.default.createElement(_flex.Flex, {
     justifyContent: "end"
   }, /*#__PURE__*/_react.default.createElement(_closeButton.CloseButton, {
+    label: closeButtonLabel,
     onClick: onClose,
     testId: modalTestId
   })), /*#__PURE__*/_react.default.createElement(_flex.Flex, {

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

@@ -4,7 +4,6 @@ import "./modal-wrapper.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { forwardRef, useCallback, useEffect, useMemo, useRef } from 'react';
-import { bind } from 'bind-event-listener';
 import FocusLock from 'react-focus-lock';
 import ScrollLock, { TouchScrollable } from 'react-scrolllock';
 import { usePlatformLeafEventHandler } from '@atlaskit/analytics-next/usePlatformLeafEventHandler';
@@ -85,7 +84,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "17.0.2"
+    packageVersion: "17.1.0"
   });
 }
 function getScrollMode({
@@ -144,7 +143,7 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
-function getDialogDismissedBy({
+function getDismissedBy({
   shouldCloseOnEscapePress,
   shouldCloseOnOverlayClick
 }) {
@@ -154,6 +153,10 @@ function getDialogDismissedBy({
   if (shouldCloseOnEscapePress) {
     return 'escape';
   }
+  // Backdrop clicks only: `Dialog` asks on both, and `onDialogAsk` ignores Escape.
+  if (shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
   return 'none';
 }
 
@@ -165,7 +168,11 @@ function getDialogDismissedBy({
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: Dialog only forwards allowed reasons.
+ * - Close gating: matches legacy while open. Dialog asks on Escape and backdrop
+ *   clicks (the consumer may refuse any number of times). During the exit they
+ *   do not call `onClose` again.
+ * - A close that Dialog did not ask about (e.g. `<form method="dialog">`): not
+ *   supported. Dialog shows the modal again, and `onClose` does not run.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -227,8 +234,8 @@ function ModalWrapperTopLayer(props) {
     isFullScreen: isFullScreen !== null && isFullScreen !== void 0 ? isFullScreen : false
   }), [defaultTestId, titleId, onCloseHandler, hasProvidedOnClose, isFullScreen]);
 
-  // Dialog has already applied the close behavior configured by `dismissedBy`.
-  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract. Dialog calls this
+  // for an allowed Escape or backdrop click.
   const onDialogClose = useCallback(({
     reason
   }) => {
@@ -236,30 +243,32 @@ function ModalWrapperTopLayer(props) {
       reason
     }));
   }, [onCloseHandler]);
-  const dismissedBy = getDialogDismissedBy({
-    shouldCloseOnEscapePress,
-    shouldCloseOnOverlayClick
-  });
-  const shouldShimCloseOnOverlayClick = shouldCloseOnOverlayClick && !shouldCloseOnEscapePress;
 
-  // Required until we fully remove `shouldCloseOnEscapePress`.
-  // Dialog's `dismissedBy` options do not support outside click without Escape (because it is a bad pattern)
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog || !shouldShimCloseOnOverlayClick) {
+  /**
+   * Dialog asks on an allowed Escape or backdrop click. Ignoring an Escape ask refuses it:
+   * Dialog still cancels the Escape `keydown`, so nothing else closes.
+   */
+  const onDialogAsk = useCallback(({
+    reason
+  }) => {
+    if (reason === 'escape' && !shouldCloseOnEscapePress) {
       return;
     }
-    return bind(dialog, {
-      type: 'click',
-      listener(event) {
-        if (event.target === event.currentTarget) {
-          onDialogClose({
-            reason: 'overlay-click'
-          });
-        }
-      }
+    onDialogClose({
+      reason
     });
-  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
+  }, [onDialogClose, shouldCloseOnEscapePress]);
+
+  // Unlike legacy, Escape and backdrop clicks during the exit do not call `onClose` again.
+  // See `@atlaskit/top-layer` notes: `decisions/dialog-close-flow.md`.
+
+  // Dialog could not reopen after a close it did not ask about (its parent layer is closed), so
+  // the `<dialog>` is already gone. End the exit.
+  useEffect(() => {
+    if (isExiting && !dialogRef.current) {
+      onExitFinish === null || onExitFinish === void 0 ? void 0 : onExitFinish();
+    }
+  }, [isExiting, onExitFinish]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -308,8 +317,11 @@ function ModalWrapperTopLayer(props) {
   });
   return /*#__PURE__*/React.createElement(Dialog, _extends({
     ref: dialogRef,
-    onClose: onDialogClose,
-    dismissedBy: dismissedBy,
+    onClose: onDialogAsk,
+    dismissedBy: getDismissedBy({
+      shouldCloseOnEscapePress,
+      shouldCloseOnOverlayClick
+    }),
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

package/dist/es2019/modal-header.js

@@ -23,7 +23,8 @@ const ModalHeader = props => {
   const {
     children,
     testId: userDefinedTestId,
-    hasCloseButton = false
+    hasCloseButton = false,
+    closeButtonLabel
   } = props;
   const {
     hasProvidedOnClose,
@@ -44,6 +45,7 @@ const ModalHeader = props => {
   }, /*#__PURE__*/React.createElement(Flex, {
     justifyContent: "end"
   }, /*#__PURE__*/React.createElement(CloseButton, {
+    label: closeButtonLabel,
     onClick: onClose,
     testId: modalTestId
   })), /*#__PURE__*/React.createElement(Flex, {

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

@@ -5,7 +5,6 @@ import "./modal-wrapper.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { forwardRef, useCallback, useEffect, useMemo, useRef } from 'react';
-import { bind } from 'bind-event-listener';
 import FocusLock from 'react-focus-lock';
 import ScrollLock, { TouchScrollable } from 'react-scrolllock';
 import { usePlatformLeafEventHandler } from '@atlaskit/analytics-next/usePlatformLeafEventHandler';
@@ -86,7 +85,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "17.0.2"
+    packageVersion: "17.1.0"
   });
 }
 function getScrollMode(_ref) {
@@ -144,7 +143,7 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
-function getDialogDismissedBy(_ref2) {
+function getDismissedBy(_ref2) {
   var shouldCloseOnEscapePress = _ref2.shouldCloseOnEscapePress,
     shouldCloseOnOverlayClick = _ref2.shouldCloseOnOverlayClick;
   if (shouldCloseOnEscapePress && shouldCloseOnOverlayClick) {
@@ -153,6 +152,10 @@ function getDialogDismissedBy(_ref2) {
   if (shouldCloseOnEscapePress) {
     return 'escape';
   }
+  // Backdrop clicks only: `Dialog` asks on both, and `onDialogAsk` ignores Escape.
+  if (shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
   return 'none';
 }
 
@@ -164,7 +167,11 @@ function getDialogDismissedBy(_ref2) {
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: Dialog only forwards allowed reasons.
+ * - Close gating: matches legacy while open. Dialog asks on Escape and backdrop
+ *   clicks (the consumer may refuse any number of times). During the exit they
+ *   do not call `onClose` again.
+ * - A close that Dialog did not ask about (e.g. `<form method="dialog">`): not
+ *   supported. Dialog shows the modal again, and `onClose` does not run.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -232,38 +239,39 @@ function ModalWrapperTopLayer(props) {
     };
   }, [defaultTestId, titleId, onCloseHandler, hasProvidedOnClose, isFullScreen]);
 
-  // Dialog has already applied the close behavior configured by `dismissedBy`.
-  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract. Dialog calls this
+  // for an allowed Escape or backdrop click.
   var onDialogClose = useCallback(function (_ref3) {
     var reason = _ref3.reason;
     onCloseHandler(createCloseEvent({
       reason: reason
     }));
   }, [onCloseHandler]);
-  var dismissedBy = getDialogDismissedBy({
-    shouldCloseOnEscapePress: shouldCloseOnEscapePress,
-    shouldCloseOnOverlayClick: shouldCloseOnOverlayClick
-  });
-  var shouldShimCloseOnOverlayClick = shouldCloseOnOverlayClick && !shouldCloseOnEscapePress;
 
-  // Required until we fully remove `shouldCloseOnEscapePress`.
-  // Dialog's `dismissedBy` options do not support outside click without Escape (because it is a bad pattern)
-  useEffect(function () {
-    var dialog = dialogRef.current;
-    if (!dialog || !shouldShimCloseOnOverlayClick) {
+  /**
+   * Dialog asks on an allowed Escape or backdrop click. Ignoring an Escape ask refuses it:
+   * Dialog still cancels the Escape `keydown`, so nothing else closes.
+   */
+  var onDialogAsk = useCallback(function (_ref4) {
+    var reason = _ref4.reason;
+    if (reason === 'escape' && !shouldCloseOnEscapePress) {
       return;
     }
-    return bind(dialog, {
-      type: 'click',
-      listener: function listener(event) {
-        if (event.target === event.currentTarget) {
-          onDialogClose({
-            reason: 'overlay-click'
-          });
-        }
-      }
+    onDialogClose({
+      reason: reason
     });
-  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
+  }, [onDialogClose, shouldCloseOnEscapePress]);
+
+  // Unlike legacy, Escape and backdrop clicks during the exit do not call `onClose` again.
+  // See `@atlaskit/top-layer` notes: `decisions/dialog-close-flow.md`.
+
+  // Dialog could not reopen after a close it did not ask about (its parent layer is closed), so
+  // the `<dialog>` is already gone. End the exit.
+  useEffect(function () {
+    if (isExiting && !dialogRef.current) {
+      onExitFinish === null || onExitFinish === void 0 || onExitFinish();
+    }
+  }, [isExiting, onExitFinish]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -312,8 +320,11 @@ function ModalWrapperTopLayer(props) {
   });
   return /*#__PURE__*/React.createElement(Dialog, _extends({
     ref: dialogRef,
-    onClose: onDialogClose,
-    dismissedBy: dismissedBy,
+    onClose: onDialogAsk,
+    dismissedBy: getDismissedBy({
+      shouldCloseOnEscapePress: shouldCloseOnEscapePress,
+      shouldCloseOnOverlayClick: shouldCloseOnOverlayClick
+    }),
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

package/dist/esm/modal-header.js

@@ -23,7 +23,8 @@ var ModalHeader = function ModalHeader(props) {
   var children = props.children,
     userDefinedTestId = props.testId,
     _props$hasCloseButton = props.hasCloseButton,
-    hasCloseButton = _props$hasCloseButton === void 0 ? false : _props$hasCloseButton;
+    hasCloseButton = _props$hasCloseButton === void 0 ? false : _props$hasCloseButton,
+    closeButtonLabel = props.closeButtonLabel;
   var _useModal = useModal(),
     hasProvidedOnClose = _useModal.hasProvidedOnClose,
     onClose = _useModal.onClose,
@@ -42,6 +43,7 @@ var ModalHeader = function ModalHeader(props) {
   }, /*#__PURE__*/React.createElement(Flex, {
     justifyContent: "end"
   }, /*#__PURE__*/React.createElement(CloseButton, {
+    label: closeButtonLabel,
     onClick: onClose,
     testId: modalTestId
   })), /*#__PURE__*/React.createElement(Flex, {

package/dist/types/modal-header.d.ts

@@ -13,6 +13,10 @@ export interface ModalHeaderProps {
      * @default false
      */
     hasCloseButton?: boolean;
+    /**
+     * The accessible name for the close button when `hasCloseButton` is true.
+     */
+    closeButtonLabel?: string;
     /**
      * A `testId` prop is provided for specified elements,
      * which is a unique string that appears as a data attribute `data-testid` in the rendered code,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/modal-dialog",
-	"version": "17.0.3",
+	"version": "17.1.1",
 	"description": "A modal dialog displays content that requires user interaction, in a layer above the page.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -39,7 +39,7 @@
 	"dependencies": {
 		"@atlaskit/analytics-next": "^12.6.0",
 		"@atlaskit/blanket": "^16.4.0",
-		"@atlaskit/button": "^25.4.0",
+		"@atlaskit/button": "^25.5.0",
 		"@atlaskit/css": "^1.1.0",
 		"@atlaskit/ds-lib": "^8.0.0",
 		"@atlaskit/icon": "^38.0.0",
@@ -48,11 +48,11 @@
 		"@atlaskit/platform-feature-flags": "^2.2.0",
 		"@atlaskit/portal": "^7.0.0",
 		"@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
-		"@atlaskit/primitives": "^22.5.0",
+		"@atlaskit/primitives": "^22.6.0",
 		"@atlaskit/react-compiler-gating": "^0.2.0",
 		"@atlaskit/theme": "^28.2.0",
-		"@atlaskit/tokens": "^20.4.0",
-		"@atlaskit/top-layer": "^6.2.0",
+		"@atlaskit/tokens": "^20.6.0",
+		"@atlaskit/top-layer": "^6.4.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^1.0.2",
 		"bind-event-listener": "^3.0.0",
@@ -80,7 +80,7 @@
 		"@atlaskit/form": "^18.2.0",
 		"@atlaskit/heading": "^8.0.0",
 		"@atlaskit/link": "^5.1.0",
-		"@atlaskit/popup": "^9.0.0",
+		"@atlaskit/popup": "^10.0.0",
 		"@atlaskit/radio": "^10.2.0",
 		"@atlaskit/section-message": "^10.2.0",
 		"@atlaskit/select": "^23.1.0",
@@ -90,7 +90,7 @@
 		"@atlassian/feature-flags-test-utils": "^1.3.0",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@atlassian/structured-docs-types": "workspace:^",
-		"@atlassian/testing-library": "^0.11.0",
+		"@atlassian/testing-library": "^0.12.0",
 		"@atlassian/workbench": "workspace:*",
 		"@testing-library/dom": "^10.1.0",
 		"@types/raf-schd": "^4.0.1",