chore(ModalWrapper): deprecate for ComposedModal (#12263)

* fix: add deprecated section to storybook * chore: add deprecation warning * chore: add migration doc * Update packages/react/src/components/ModalWrapper/ModalWrapper.js Co-authored-by: Taylor Jones <tay1orjones@users.noreply.github.com> Co-authored-by: Taylor Jones <tay1orjones@users.noreply.github.com> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
carbon-design-system · Oct 11, 2022 · 450ef8c · 450ef8c
1 parent 607e05b
commit 450ef8c
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 1 deletion.
diff --git a/packages/react/src/components/ModalWrapper/ ModalWrapper.stories.js b/packages/react/src/components/ModalWrapper/ ModalWrapper.stories.js
@@ -9,7 +9,7 @@ import React from 'react';
 import ModalWrapper from './ModalWrapper';
 
 export default {
-  title: 'Components/ModalWrapper',
+  title: 'Deprecated/ModalWrapper',
   component: ModalWrapper,
   argTypes: {
     triggerButtonKind: {

diff --git a/packages/react/src/components/ModalWrapper/ModalWrapper.js b/packages/react/src/components/ModalWrapper/ModalWrapper.js
@@ -10,8 +10,19 @@ import React from 'react';
 import Modal from '../Modal';
 import Button from '../Button';
 import { ButtonKinds } from '../../prop-types/types';
+import { warning } from '../../internal/warning';
+
+let didWarnAboutDeprecation = false;
 
 export default class ModalWrapper extends React.Component {
+  if(__DEV__) {
+    warning(
+      didWarnAboutDeprecation,
+      '`<ModalWrapper>` has been deprecated in favor of `<ComposedModal/>` and will be removed in the next major version, `@carbon/react@v2.x`'
+    );
+    didWarnAboutDeprecation = true;
+  }
+
   static propTypes = {
     buttonTriggerClassName: PropTypes.string,
     buttonTriggerText: PropTypes.node,

diff --git a/packages/react/src/components/ModalWrapper/migration.mdx b/packages/react/src/components/ModalWrapper/migration.mdx
@@ -0,0 +1,47 @@
+# ModalWrapper deprecation
+
+## Timeline
+
+The `<ModalWrapper/>` component has been deprecated in v11 and will be removed
+in v12.
+
+## Migration Strategy
+
+The `<ComposedModal/>` component will be used in favor of the `<ModalWrapper/>`
+going forward. The `<ComposedModal/>` is used along with any of these 3 children
+components: `<ModalHeader/>`, `<ModalBody/>` and `<ModalFooter/>`. This makes
+the `<ComposedModal/>` more customizable as you can choose what to include in
+it. A notable difference is that the modal trigger has to be custom implemented
+now.
+
+| ModalWrapper props            | ComposedModal component migration | ComposedModal prop equivalent |
+| ----------------------------- | --------------------------------- | ----------------------------- |
+| buttonTriggerClassName        | n/a                               | n/a                           |
+| buttonTriggerText             | n/a                               | n/a                           |
+| children                      | ComposedModal                     | children                      |
+| disabled                      | n/a                               | n/a                           |
+| handleOpen                    | n/a                               | n/a                           |
+| handleSubmit                  | ModalFooter                       | onRequestSubmit               |
+| id                            | n/a                               | n/a                           |
+| modalBeforeContent            | n/a                               | n/a                           |
+| modalHeading                  | ModalHeader                       | title                         |
+| modalLabel                    | ModalHeader                       | label                         |
+| modalText                     | ModalBody                         | children                      |
+| onKeyDown                     | ComposedModal                     | onKeyDown                     |
+| passiveModal                  | n/a                               | n/a                           |
+| preventCloseOnClickOutside    | ComposedModal                     | preventCloseOnClickOutside    |
+| primaryButtonText             | ModalFooter                       | primaryButtonText             |
+| renderTriggerButtonIcon       | n/a                               | n/a                           |
+| secondaryButtonText           | ModalFooter                       | secondaryButtonText           |
+| selectorPrimaryFocus          | ComposedModal                     | selectorPrimaryFocus          |
+| shouldCloseAfterSubmit (bool) | ModalFooter                       | onRequestSubmit (func)        |
+| status                        | n/a                               | n/a                           |
+| triggerButtonIconDescription  | n/a                               | n/a                           |
+| triggerButtonKind             | n/a                               | n/a                           |
+| withHeader                    | n/a                               | n/a                           |
+
+## Resources
+
+- [ComposedModal source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/ComposedModal)
+- [ComposedModal with state example](https://react.carbondesignsystem.com/?path=/story/components-composedmodal--with-state-manager)
+- [ComposedModal docs](https://github.com/carbon-design-system/carbon/blob/main/packages/react/src/components/ComposedModal/ComposedModal.mdx)