@atlaskit/modal-dialog 16.3.2 → 16.3.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @atlaskit/modal-dialog
 
+## 16.3.4
+
+### Patch Changes
+
+- Updated dependencies
+
+## 16.3.3
+
+### Patch Changes
+
+- [`ccb9237bc10d9`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ccb9237bc10d9) -
+  Add the `dismissedBy` API to control Dialog dismissal consistently across browsers. Align Dialog
+  with Popover by notifying `onClose` after native dismissal, ensure both primitives unmount after
+  native dismissal, and simplify Modal close handling behind `platform-dst-top-layer`.
+- Updated dependencies
+
 ## 16.3.2
 
 ### Patch Changes

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

@@ -13,6 +13,7 @@ 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 _analyticsNext = require("@atlaskit/analytics-next");
@@ -91,7 +92,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "16.3.1"
+    packageVersion: "16.3.3"
   });
 }
 function getScrollMode(_ref) {
@@ -149,6 +150,17 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
+function getDialogDismissedBy(_ref2) {
+  var shouldCloseOnEscapePress = _ref2.shouldCloseOnEscapePress,
+    shouldCloseOnOverlayClick = _ref2.shouldCloseOnOverlayClick;
+  if (shouldCloseOnEscapePress && shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
+  if (shouldCloseOnEscapePress) {
+    return 'escape';
+  }
+  return 'none';
+}
 
 /**
  * Top-layer rendering path (platform-dst-top-layer).
@@ -158,8 +170,7 @@ function getTopLayerSurfaceHeight(input) {
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: onDialogClose only forwards allowed reasons
- *   (see notes/guides/dialog-close-flow.md).
+ * - Close gating: Dialog only forwards allowed reasons.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -226,21 +237,38 @@ function ModalWrapperTopLayer(props) {
     };
   }, [defaultTestId, titleId, onCloseHandler, providedOnClose, isFullScreen]);
 
-  // Only forward close when the reason is allowed by props.
-  // Passes a synthetic event to satisfy the KeyboardOrMouseEvent contract.
-  var onDialogClose = (0, _react.useCallback)(function (_ref2) {
-    var reason = _ref2.reason;
-    if (reason === 'escape' && shouldCloseOnEscapePress) {
-      onCloseHandler((0, _dialog.createCloseEvent)({
-        reason: reason
-      }));
-    }
-    if (reason === 'overlay-click' && shouldCloseOnOverlayClick) {
-      onCloseHandler((0, _dialog.createCloseEvent)({
-        reason: reason
-      }));
+  // Dialog has already applied the close behavior configured by `dismissedBy`.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+  var onDialogClose = (0, _react.useCallback)(function (_ref3) {
+    var reason = _ref3.reason;
+    onCloseHandler((0, _dialog.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) {
+      return;
     }
-  }, [onCloseHandler, shouldCloseOnEscapePress, shouldCloseOnOverlayClick]);
+    return (0, _bindEventListener.bind)(dialog, {
+      type: 'click',
+      listener: function listener(event) {
+        if (event.target === event.currentTarget) {
+          onDialogClose({
+            reason: 'overlay-click'
+          });
+        }
+      }
+    });
+  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -293,6 +321,7 @@ function ModalWrapperTopLayer(props) {
   return /*#__PURE__*/React.createElement(_dialog.Dialog, (0, _extends2.default)({
     ref: dialogRef,
     onClose: onDialogClose,
+    dismissedBy: dismissedBy,
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

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

@@ -4,6 +4,7 @@ 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';
@@ -81,7 +82,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "16.3.1"
+    packageVersion: "16.3.3"
   });
 }
 function getScrollMode({
@@ -140,6 +141,18 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
+function getDialogDismissedBy({
+  shouldCloseOnEscapePress,
+  shouldCloseOnOverlayClick
+}) {
+  if (shouldCloseOnEscapePress && shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
+  if (shouldCloseOnEscapePress) {
+    return 'escape';
+  }
+  return 'none';
+}
 
 /**
  * Top-layer rendering path (platform-dst-top-layer).
@@ -149,8 +162,7 @@ function getTopLayerSurfaceHeight(input) {
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: onDialogClose only forwards allowed reasons
- *   (see notes/guides/dialog-close-flow.md).
+ * - Close gating: Dialog only forwards allowed reasons.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -211,22 +223,39 @@ function ModalWrapperTopLayer(props) {
     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.
+  // Dialog has already applied the close behavior configured by `dismissedBy`.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
   const onDialogClose = useCallback(({
     reason
   }) => {
-    if (reason === 'escape' && shouldCloseOnEscapePress) {
-      onCloseHandler(createCloseEvent({
-        reason
-      }));
-    }
-    if (reason === 'overlay-click' && shouldCloseOnOverlayClick) {
-      onCloseHandler(createCloseEvent({
-        reason
-      }));
+    onCloseHandler(createCloseEvent({
+      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) {
+      return;
     }
-  }, [onCloseHandler, shouldCloseOnEscapePress, shouldCloseOnOverlayClick]);
+    return bind(dialog, {
+      type: 'click',
+      listener(event) {
+        if (event.target === event.currentTarget) {
+          onDialogClose({
+            reason: 'overlay-click'
+          });
+        }
+      }
+    });
+  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -279,6 +308,7 @@ function ModalWrapperTopLayer(props) {
   return /*#__PURE__*/React.createElement(Dialog, _extends({
     ref: dialogRef,
     onClose: onDialogClose,
+    dismissedBy: dismissedBy,
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

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

@@ -5,6 +5,7 @@ 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';
@@ -82,7 +83,7 @@ function useModalCloseHandler(providedOnClose) {
     action: 'closed',
     componentName: 'modalDialog',
     packageName: "@atlaskit/modal-dialog",
-    packageVersion: "16.3.1"
+    packageVersion: "16.3.3"
   });
 }
 function getScrollMode(_ref) {
@@ -140,6 +141,17 @@ function getTopLayerSurfaceHeight(input) {
   }
   return input;
 }
+function getDialogDismissedBy(_ref2) {
+  var shouldCloseOnEscapePress = _ref2.shouldCloseOnEscapePress,
+    shouldCloseOnOverlayClick = _ref2.shouldCloseOnOverlayClick;
+  if (shouldCloseOnEscapePress && shouldCloseOnOverlayClick) {
+    return 'escape-and-outside-click';
+  }
+  if (shouldCloseOnEscapePress) {
+    return 'escape';
+  }
+  return 'none';
+}
 
 /**
  * Top-layer rendering path (platform-dst-top-layer).
@@ -149,8 +161,7 @@ function getTopLayerSurfaceHeight(input) {
  *
  * Key decisions:
  * - Animation: CSS transitions via @starting-style / allow-discrete.
- * - Close gating: onDialogClose only forwards allowed reasons
- *   (see notes/guides/dialog-close-flow.md).
+ * - Close gating: Dialog only forwards allowed reasons.
  * - onClose event param: undefined - consumers should use close reason.
  * - Focus restoration: native <dialog> behavior replaces react-focus-lock's
  *   returnFocus (see accessibility-criteria.md).
@@ -217,21 +228,38 @@ function ModalWrapperTopLayer(props) {
     };
   }, [defaultTestId, titleId, onCloseHandler, providedOnClose, isFullScreen]);
 
-  // Only forward close when the reason is allowed by props.
-  // Passes a synthetic event to satisfy the KeyboardOrMouseEvent contract.
-  var onDialogClose = useCallback(function (_ref2) {
-    var reason = _ref2.reason;
-    if (reason === 'escape' && shouldCloseOnEscapePress) {
-      onCloseHandler(createCloseEvent({
-        reason: reason
-      }));
-    }
-    if (reason === 'overlay-click' && shouldCloseOnOverlayClick) {
-      onCloseHandler(createCloseEvent({
-        reason: reason
-      }));
+  // Dialog has already applied the close behavior configured by `dismissedBy`.
+  // Pass a synthetic event to satisfy the KeyboardOrMouseEvent contract.
+  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) {
+      return;
     }
-  }, [onCloseHandler, shouldCloseOnEscapePress, shouldCloseOnOverlayClick]);
+    return bind(dialog, {
+      type: 'click',
+      listener: function listener(event) {
+        if (event.target === event.currentTarget) {
+          onDialogClose({
+            reason: 'overlay-click'
+          });
+        }
+      }
+    });
+  }, [onDialogClose, shouldShimCloseOnOverlayClick]);
 
   // ExitingPersistence: isExiting → isOpen={false} → Dialog exit animation →
   // onExitFinish → onCloseComplete + unmount.
@@ -284,6 +312,7 @@ function ModalWrapperTopLayer(props) {
   return /*#__PURE__*/React.createElement(Dialog, _extends({
     ref: dialogRef,
     onClose: onDialogClose,
+    dismissedBy: dismissedBy,
     onExitFinish: handleDialogExitFinish,
     shouldAnimate: !isFullScreen,
     isOpen: !isExiting,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/modal-dialog",
-	"version": "16.3.2",
+	"version": "16.3.4",
 	"description": "A modal dialog displays content that requires user interaction, in a layer above the page.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -41,15 +41,15 @@
 		"@atlaskit/ds-lib": "^8.0.0",
 		"@atlaskit/icon": "^37.3.0",
 		"@atlaskit/layering": "^5.0.0",
-		"@atlaskit/motion": "^8.0.0",
+		"@atlaskit/motion": "^8.1.0",
 		"@atlaskit/platform-feature-flags": "^2.1.0",
 		"@atlaskit/portal": "^6.2.0",
-		"@atlaskit/pragmatic-drag-and-drop": "^2.0.0",
+		"@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
 		"@atlaskit/primitives": "^22.2.0",
 		"@atlaskit/react-compiler-gating": "^0.2.0",
 		"@atlaskit/theme": "^28.0.0",
 		"@atlaskit/tokens": "^16.7.0",
-		"@atlaskit/top-layer": "^4.0.0",
+		"@atlaskit/top-layer": "^4.2.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^1.0.2",
 		"bind-event-listener": "^3.0.0",

package/modal-dialog.docs.tsx

@@ -1,231 +0,0 @@
-import path from 'path';
-
-import type { StructuredContentSource } from '@atlassian/structured-docs-types/types';
-
-const documentation: StructuredContentSource = {
-	components: [
-		{
-			name: 'Modal',
-			description: 'A modal dialog component for important content.',
-			status: 'general-availability',
-			designSource: {
-				figmaUrl: 'https://go.atlassian.com/figma-library-ads-82128-80670',
-			},
-			import: {
-				name: 'Modal',
-				package: '@atlaskit/modal-dialog',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use for immediate task or critical/warning requiring a response; blocking until closed',
-				'Use sparingly—modals are invasive',
-				'One task per modal; limit interactions; no nested modals (inaccessible)',
-				'Anatomy: header (h1 title), close button, body, footer with primary + cancel/close',
-				'Footer: primary button on the right of secondary; multiple dismissal methods (close button, Esc, blanket click, Cancel/Close)',
-				'Use Popup for smaller info + controls; Spotlight for onboarding; Inline message for alert/action',
-			],
-			contentGuidelines: [
-				'Use clear, descriptive titles',
-				'Primary button label should reflect the modal title',
-				'Use action verbs in button labels',
-				'Keep content focused on a single task or message',
-				'Use sentence case for all text',
-			],
-			accessibilityGuidelines: [
-				'Modal must have a title: use title component, or titleId from useModal, or label (avoid if no visual title)',
-				'Close button is required (except rare cases—consult a11y team)',
-				'Do not rely on color alone for severity; provide accessible label for icons',
-				'Focus order: 1) close (or title or container), 2) first focusable, 3) secondary button, 4) primary, 5) return focus to trigger on close',
-				'Dismiss via: close button, Esc, click blanket, Cancel/Close in footer',
-				'Ensure modal content is announced by screen readers',
-				'Ensure keyboard navigation and escape key support',
-				'Maintain focus within modal when open',
-			],
-			examples: [
-				{
-					name: 'Default',
-					description: 'The default form of a modal dialog.',
-					source: path.resolve(__dirname, './examples/constellation/modal-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'dialog', 'popup', 'overlay', 'focused', 'interaction', 'layer'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'ModalHeader',
-			description:
-				'The header section of a modal dialog, typically containing the title and optional close button.',
-			status: 'general-availability',
-			import: {
-				name: 'ModalHeader',
-				package: '@atlaskit/modal-dialog/modal-header',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use as the first child of Modal',
-				'Use hasCloseButton prop for standard close affordance',
-				'Ensure header contains ModalTitle or equivalent for accessibility',
-				'For custom headers, use CloseButton as first element in DOM',
-			],
-			contentGuidelines: ['Use clear, descriptive titles', 'Keep header content focused'],
-			examples: [
-				{
-					name: 'Modal Header',
-					description: 'ModalHeader example',
-					source: path.resolve(__dirname, './examples/constellation/modal-header-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'header', 'title', 'close'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'ModalTitle',
-			description: 'The title element for a modal dialog. Renders as h1 for accessibility.',
-			status: 'general-availability',
-			import: {
-				name: 'ModalTitle',
-				package: '@atlaskit/modal-dialog/modal-title',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use inside ModalHeader for the modal title',
-				'Modal must have a title for accessibility',
-				'Supports any valid React element as children',
-			],
-			contentGuidelines: ['Use clear, descriptive titles', 'Use sentence case'],
-			examples: [
-				{
-					name: 'Modal Title',
-					description: 'ModalTitle example',
-					source: path.resolve(__dirname, './examples/constellation/modal-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'title', 'heading'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'ModalBody',
-			description: 'The main content area of a modal dialog.',
-			status: 'general-availability',
-			import: {
-				name: 'ModalBody',
-				package: '@atlaskit/modal-dialog/modal-body',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use for the primary content between header and footer',
-				'Accepts any valid React element as children',
-				'Handles overflow and scrolling when content exceeds viewport',
-			],
-			contentGuidelines: ['Keep content focused on a single task', 'Use clear, readable content'],
-			examples: [
-				{
-					name: 'Modal Body',
-					description: 'ModalBody example',
-					source: path.resolve(__dirname, './examples/constellation/modal-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'body', 'content'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'ModalFooter',
-			description: 'The footer section of a modal dialog, typically containing action buttons.',
-			status: 'general-availability',
-			import: {
-				name: 'ModalFooter',
-				package: '@atlaskit/modal-dialog/modal-footer',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use for primary and secondary actions',
-				'Primary button on the right of secondary',
-				'Include Cancel/Close for dismissal',
-				'Accepts any valid React element for custom layouts',
-			],
-			contentGuidelines: [
-				'Primary button label should reflect the modal title',
-				'Use action verbs in button labels',
-			],
-			examples: [
-				{
-					name: 'Modal Footer',
-					description: 'ModalFooter example',
-					source: path.resolve(__dirname, './examples/constellation/modal-footer-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'footer', 'actions', 'buttons'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'ModalTransition',
-			description: 'A wrapper that provides enter/exit transitions for modal content.',
-			status: 'general-availability',
-			import: {
-				name: 'ModalTransition',
-				package: '@atlaskit/modal-dialog/modal-transition',
-				type: 'default',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Wrap Modal with ModalTransition for animated open/close',
-				'Use when modal visibility is controlled by state',
-				'Children mount when visible and unmount when closed',
-			],
-			examples: [
-				{
-					name: 'Modal Transition',
-					description: 'ModalTransition example',
-					source: path.resolve(__dirname, './examples/constellation/modal-default.tsx'),
-				},
-			],
-			keywords: ['modal', 'transition', 'animation'],
-			categories: ['overlay'],
-		},
-		{
-			name: 'CloseButton',
-			description:
-				'An accessible close button for use in custom modal headers. Ensures users have an obvious way to close the modal.',
-			status: 'general-availability',
-			import: {
-				name: 'CloseButton',
-				package: '@atlaskit/modal-dialog/close-button',
-				type: 'named',
-				packagePath: path.resolve(__dirname),
-				packageJson: require('./package.json'),
-			},
-			usageGuidelines: [
-				'Use when customizing ModalHeader without hasCloseButton',
-				'Render CloseButton first in DOM for proper focus order',
-				'Use Flex with row-reverse if close should appear on the right',
-				'Provide label prop for custom accessible name',
-			],
-			accessibilityGuidelines: [
-				'Close button is required for modals (consult a11y team for rare exceptions)',
-				'Ensure close button is keyboard accessible',
-			],
-			examples: [
-				{
-					name: 'Close Button',
-					description: 'CloseButton example',
-					source: path.resolve(__dirname, './examples/constellation/modal-header-custom.tsx'),
-				},
-			],
-			keywords: ['modal', 'close', 'button', 'dismiss'],
-			categories: ['overlay'],
-		},
-	],
-};
-
-export default documentation;