feat(modals): adds subcomponent mapping to Modal (#1750)

geotrev · web-flow · commit 77b4fd9e2715 · 2024-03-14T13:06:03.000-05:00
diff --git a/docs/migration.md b/docs/migration.md
@@ -119,6 +119,8 @@ consider additional positioning prop support on a case-by-case basis.
 - `DrawerModal`: renamed to `Drawer`
 - `TooltipModal`: removed `popperModifiers` prop (see [note](#breaking-changes))
 - Removed `GARDEN_PLACEMENT` type export. Use `ITooltipModalProps['placement']` instead.
+- Subcomponent exports for `Modal` have been deprecated and will be removed in a future major version.
+  Update to subcomponent properties (e.g., `Modal.Body`).
 
 #### @zendeskgarden/react-notification
 
diff --git a/packages/modals/README.md b/packages/modals/README.md
@@ -18,25 +18,25 @@ npm install react react-dom styled-components @zendeskgarden/react-theming
 
 ```jsx
 import { ThemeProvider } from '@zendeskgarden/react-theming';
-import { Modal, Header, Body, Footer, FooterItem, Close } from '@zendeskgarden/react-modals';
+import { Modal } from '@zendeskgarden/react-modals';
 import { Button } from '@zendeskgarden/react-buttons';
 
 /**
  * Place a `ThemeProvider` at the root of your React application
  */
 <ThemeProvider>
   <Modal onClose={() => alert('modal closing')}>
-    <Header>Example Header</Header>
-    <Body>Some content</Body>
-    <Footer>
-      <FooterItem>
+    <Modal.Header>Example Header</Modal.Header>
+    <Modal.Body>Some content</Modal.Body>
+    <Modal.Footer>
+      <Modal.FooterItem>
         <Button isBasic>Cancel</Button>
-      </FooterItem>
-      <FooterItem>
+      </Modal.FooterItem>
+      <Modal.FooterItem>
         <Button isPrimary>Confirm</Button>
-      </FooterItem>
-    </Footer>
-    <Close aria-label="Close modal" />
+      </Modal.FooterItem>
+    </Modal.Footer>
+    <Modal.Close aria-label="Close modal" />
   </Modal>
 </ThemeProvider>;
 ```
diff --git a/packages/modals/demo/modal.stories.mdx b/packages/modals/demo/modal.stories.mdx
@@ -1,14 +1,20 @@
 import { Meta, ArgsTable, Canvas, Story, Markdown } from '@storybook/addon-docs';
 import { useArgs } from '@storybook/client-api';
-import { Modal, Body, Close, Footer, FooterItem, Header } from '@zendeskgarden/react-modals';
+import { Modal } from '@zendeskgarden/react-modals';
 import { ModalStory } from './stories/ModalStory';
 import { MODAL_BODY as BODY, MODAL_FOOTER_ITEMS as FOOTER_ITEMS } from './stories/data';
 import README from '../README.md';
 
 <Meta
   title="Packages/Modals/Modal"
   component={Modal}
-  subcomponents={{ Body, Close, Footer, FooterItem, Header }}
+  subcomponents={{
+    'Modal.Body': Modal.Body,
+    'Modal.Close': Modal.Close,
+    'Modal.Footer': Modal.Footer,
+    'Modal.FooterItem': Modal.FooterItem,
+    'Modal.Header': Modal.Header
+  }}
 />
 
 # API
@@ -37,16 +43,16 @@ import README from '../README.md';
     argTypes={{
       appendToNode: { control: false },
       isVisible: { table: { category: 'Story' } },
-      hasBody: { name: 'Body', table: { category: 'Story' } },
-      hasClose: { name: 'Close', table: { category: 'Story' } },
-      hasFooter: { name: 'Footer', table: { category: 'Story' } },
-      hasHeader: { name: 'Header', table: { category: 'Story' } },
-      footerItems: { name: 'FooterItem[]', table: { category: 'Story' } },
-      body: { name: 'children', table: { category: 'Body' } },
-      isDanger: { control: 'boolean', table: { category: 'Header' } },
-      tag: { control: 'text', table: { category: 'Header' } },
-      header: { name: 'children', table: { category: 'Header' } },
-      closeAriaLabel: { name: 'aria-label', table: { category: 'Close' } },
+      hasBody: { name: 'Modal.Body', table: { category: 'Story' } },
+      hasClose: { name: 'Modal.Close', table: { category: 'Story' } },
+      hasFooter: { name: 'Modal.Footer', table: { category: 'Story' } },
+      hasHeader: { name: 'Modal.Header', table: { category: 'Story' } },
+      footerItems: { name: 'Modal.FooterItem[]', table: { category: 'Story' } },
+      body: { name: 'children', table: { category: 'Modal.Body' } },
+      isDanger: { control: 'boolean', table: { category: 'Modal.Header' } },
+      tag: { control: 'text', table: { category: 'Modal.Header' } },
+      header: { name: 'children', table: { category: 'Modal.Header' } },
+      closeAriaLabel: { name: 'aria-label', table: { category: 'Modal.Close' } },
       dialogAriaLabel: { name: 'aria-label' }
     }}
     parameters={{
diff --git a/packages/modals/demo/stories/ModalStory.tsx b/packages/modals/demo/stories/ModalStory.tsx
@@ -8,15 +8,7 @@
 import React, { MouseEventHandler } from 'react';
 import { Story } from '@storybook/react';
 import Icon from '@zendeskgarden/svg-icons/src/16/lightning-bolt-stroke.svg';
-import {
-  Body,
-  Close,
-  Footer,
-  FooterItem,
-  Header,
-  IModalProps,
-  Modal
-} from '@zendeskgarden/react-modals';
+import { IModalProps, Modal } from '@zendeskgarden/react-modals';
 import { Button } from '@zendeskgarden/react-buttons';
 import { IFooterItem } from './types';
 
@@ -72,15 +64,15 @@ export const ModalStory: Story<IArgs> = ({
       {isVisible && (
         <Modal {...args} onClose={onClose} {...ariaProp}>
           {hasHeader && (
-            <Header isDanger={isDanger} tag={tag}>
+            <Modal.Header isDanger={isDanger} tag={tag}>
               {header}
-            </Header>
+            </Modal.Header>
           )}
-          {hasBody ? <Body>{body}</Body> : body}
+          {hasBody ? <Modal.Body>{body}</Modal.Body> : body}
           {hasFooter && (
-            <Footer>
+            <Modal.Footer>
               {footerItems.map(({ text, type }, index) => (
-                <FooterItem key={index}>
+                <Modal.FooterItem key={index}>
                   <Button
                     isBasic={type === 'basic'}
                     isPrimary={type === 'primary'}
@@ -89,11 +81,11 @@ export const ModalStory: Story<IArgs> = ({
                   >
                     {text}
                   </Button>
-                </FooterItem>
+                </Modal.FooterItem>
               ))}
-            </Footer>
+            </Modal.Footer>
           )}
-          {hasClose && <Close aria-label={closeAriaLabel} />}
+          {hasClose && <Modal.Close aria-label={closeAriaLabel} />}
         </Modal>
       )}
     </>
diff --git a/packages/modals/src/elements/Body.tsx b/packages/modals/src/elements/Body.tsx
@@ -10,6 +10,8 @@ import { StyledBody } from '../styled';
 import { useModalContext } from '../utils/useModalContext';
 
 /**
+ * @deprecated use `Modal.Body` instead
+ *
  * @extends HTMLAttributes<HTMLDivElement>
  */
 export const Body = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>((props, ref) => {
diff --git a/packages/modals/src/elements/Close.tsx b/packages/modals/src/elements/Close.tsx
@@ -12,6 +12,8 @@ import { useModalContext } from '../utils/useModalContext';
 import XStrokeIcon from '@zendeskgarden/svg-icons/src/16/x-stroke.svg';
 
 /**
+ * @deprecated use `Modal.Close` instead
+ *
  * @extends ButtonHTMLAttributes<HTMLButtonElement>
  */
 export const Close = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
diff --git a/packages/modals/src/elements/Footer.tsx b/packages/modals/src/elements/Footer.tsx
@@ -10,6 +10,8 @@ import { StyledFooter } from '../styled';
 import { useModalContext } from '../utils/useModalContext';
 
 /**
+ * @deprecated use `Modal.Footer` instead
+ *
  * @extends HTMLAttributes<HTMLDivElement>
  */
 export const Footer = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
diff --git a/packages/modals/src/elements/FooterItem.tsx b/packages/modals/src/elements/FooterItem.tsx
@@ -9,6 +9,8 @@ import React from 'react';
 import { StyledFooterItem } from '../styled';
 
 /**
+ * @deprecated use `Modal.FooterItem` instead
+ *
  * @extends HTMLAttributes<HTMLSpanElement>
  */
 export const FooterItem = React.forwardRef<HTMLSpanElement, React.HTMLAttributes<HTMLSpanElement>>(
diff --git a/packages/modals/src/elements/Header.tsx b/packages/modals/src/elements/Header.tsx
@@ -12,6 +12,8 @@ import { StyledDangerIcon, StyledHeader } from '../styled';
 import { IHeaderProps } from '../types';
 
 /**
+ * @deprecated use `Modal.Header` instead
+ *
  * @extends HTMLAttributes<HTMLDivElement>
  */
 export const Header = forwardRef<HTMLDivElement, IHeaderProps>(
diff --git a/packages/modals/src/elements/Modal.spec.tsx b/packages/modals/src/elements/Modal.spec.tsx
@@ -9,10 +9,6 @@ import React from 'react';
 import userEvent from '@testing-library/user-event';
 import { render } from 'garden-test-utils';
 import { Modal } from './Modal';
-import { Body } from './Body';
-import { Footer } from './Footer';
-import { Header } from './Header';
-import { Close } from './Close';
 import { IModalProps } from '../types';
 
 describe('Modal', () => {
@@ -33,12 +29,12 @@ describe('Modal', () => {
       data-test-id="modal"
       backdropProps={{ 'data-test-id': 'backdrop' } as any}
     >
-      {!noHeader && <Header data-test-id="header">Example Header</Header>}
-      <Body data-test-id="body">Body content</Body>
-      <Footer data-test-id="footer">
+      {!noHeader && <Modal.Header data-test-id="header">Example Header</Modal.Header>}
+      <Modal.Body data-test-id="body">Body content</Modal.Body>
+      <Modal.Footer data-test-id="footer">
         <button onClick={() => onClose}>Confirm</button>
-      </Footer>
-      <Close data-test-id="close" />
+      </Modal.Footer>
+      <Modal.Close data-test-id="close" />
     </Modal>
   );
 
@@ -120,19 +116,19 @@ describe('Modal', () => {
     expect(getByTestId('modal')).toHaveAttribute('aria-modal', 'true');
   });
 
-  it('applies title props to Header element', () => {
+  it('applies title props to Modal.Header element', () => {
     const { getByTestId } = render(<BasicExample />);
 
     expect(getByTestId('header')).toHaveAttribute('id', `${MODAL_ID}__title`);
   });
 
-  it('applies content props to Body element', () => {
+  it('applies content props to Modal.Body element', () => {
     const { getByTestId } = render(<BasicExample />);
 
     expect(getByTestId('body')).toHaveAttribute('id', `${MODAL_ID}__content`);
   });
 
-  it('applies close props to Close element', () => {
+  it('applies close props to Modal.Close element', () => {
     const { getByTestId } = render(<BasicExample />);
 
     expect(getByTestId('close')).toHaveAttribute('aria-label', 'Close modal');
@@ -146,7 +142,7 @@ describe('Modal', () => {
       expect(onCloseSpy).toHaveBeenCalled();
     });
 
-    it('is triggered by Close element click', async () => {
+    it('is triggered by Modal.Close element click', async () => {
       const { getByTestId } = render(<BasicExample onClose={onCloseSpy} />);
 
       await user.click(getByTestId('close'));
diff --git a/packages/modals/src/elements/Modal.tsx b/packages/modals/src/elements/Modal.tsx
@@ -29,6 +29,11 @@ import getScrollbarSize from 'dom-helpers/scrollbarSize';
 import { StyledModal, StyledBackdrop } from '../styled';
 import { IModalProps } from '../types';
 import { ModalsContext } from '../utils/useModalContext';
+import { Body } from './Body';
+import { Close } from './Close';
+import { Footer } from './Footer';
+import { FooterItem } from './FooterItem';
+import { Header } from './Header';
 
 const isOverflowing = (element: Element) => {
   const doc = ownerDocument(element);
@@ -48,10 +53,7 @@ const isOverflowing = (element: Element) => {
   return marginLeft + doc.body.clientWidth + marginRight < win.innerWidth;
 };
 
-/**
- * @extends HTMLAttributes<HTMLDivElement>
- */
-export const Modal = forwardRef<HTMLDivElement, IModalProps>(
+export const ModalComponent = forwardRef<HTMLDivElement, IModalProps>(
   (
     {
       backdropProps,
@@ -161,7 +163,7 @@ export const Modal = forwardRef<HTMLDivElement, IModalProps>(
       : modalProps['aria-label'];
 
     const ariaProps = {
-      [attribute]: useText(Modal, { [attribute]: labelValue }, attribute, defaultValue!)
+      [attribute]: useText(ModalComponent, { [attribute]: labelValue }, attribute, defaultValue!)
     };
 
     if (!rootNode) {
@@ -193,9 +195,9 @@ export const Modal = forwardRef<HTMLDivElement, IModalProps>(
   }
 );
 
-Modal.displayName = 'Modal';
+ModalComponent.displayName = 'Modal';
 
-Modal.propTypes = {
+ModalComponent.propTypes = {
   backdropProps: PropTypes.object,
   isLarge: PropTypes.bool,
   isAnimated: PropTypes.bool,
@@ -206,7 +208,24 @@ Modal.propTypes = {
   appendToNode: PropTypes.any
 };
 
-Modal.defaultProps = {
+ModalComponent.defaultProps = {
   isAnimated: true,
   isCentered: true
 };
+
+/**
+ * @extends HTMLAttributes<HTMLDivElement>
+ */
+export const Modal = ModalComponent as typeof ModalComponent & {
+  Body: typeof Body;
+  Close: typeof Close;
+  Footer: typeof Footer;
+  FooterItem: typeof FooterItem;
+  Header: typeof Header;
+};
+
+Modal.Body = Body;
+Modal.Close = Close;
+Modal.Footer = Footer;
+Modal.FooterItem = FooterItem;
+Modal.Header = Header;
diff --git a/packages/modals/src/index.ts b/packages/modals/src/index.ts
@@ -6,12 +6,12 @@
  */
 
 export { Modal } from './elements/Modal';
-
 export { Body } from './elements/Body';
 export { Close } from './elements/Close';
 export { Footer } from './elements/Footer';
 export { FooterItem } from './elements/FooterItem';
 export { Header } from './elements/Header';
+
 export { TooltipModal } from './elements/TooltipModal/TooltipModal';
 export { Drawer } from './elements/Drawer/Drawer';
 
