feat(notifications): adds subcomponent mapping (#1748)

geotrev · web-flow · commit 875b15368b8e · 2024-03-13T09:45:52.000-05:00
diff --git a/docs/migration.md b/docs/migration.md
@@ -125,6 +125,11 @@ consider additional positioning prop support on a case-by-case basis.
 - The following types have changed:
   - removed `ToastPlacement`. Use `IToastOptions['placement']` instead.
   - removed `ToastContent`. Use `IToast['content']` instead.
+- Subcomponent exports have been deprecated and will be removed in a future major version. Update
+  to subcomponent properties:
+  - `Close` -> `Alert.Close`, `Notification.Close`
+  - `Paragraph` -> `Alert.Paragraph`, `Notification.Paragraph`, `Well.Paragraph`
+  - `Title` -> `Alert.Title`, `Notification.Title`, `Well.Title`
 
 #### @zendeskgarden/react-pagination
 
diff --git a/packages/notifications/README.md b/packages/notifications/README.md
@@ -14,16 +14,18 @@ npm install react react-dom styled-components @zendeskgarden/react-theming
 
 ## Usage
 
+## Notifications
+
 ```jsx
 import { ThemeProvider } from '@zendeskgarden/react-theming';
-import { Notification, Title } from '@zendeskgarden/react-notifications';
+import { Notification } from '@zendeskgarden/react-notifications';
 
 /**
  * Place a `ThemeProvider` at the root of your React application
  */
 <ThemeProvider>
   <Notification>
-    <Title>Example Title</Title>
+    <Notification.Title>Example Title</Notification.Title>
     Lorem ipsum dolor sit amet, consectetur adipiscing elit...
   </Notification>
 </ThemeProvider>;
@@ -34,7 +36,7 @@ import { Notification, Title } from '@zendeskgarden/react-notifications';
 ```jsx
 import { ThemeProvider } from '@zendeskgarden/react-theming';
 import { Button } from '@zendeskgarden/react-buttons';
-import { Notification, Close, ToastProvider, useToast } from '@zendeskgarden/react-notifications';
+import { Notification, ToastProvider, useToast } from '@zendeskgarden/react-notifications';
 
 const ToastExample = () => {
   const { addToast } = useToast();
@@ -45,7 +47,7 @@ const ToastExample = () => {
         addToast(({ close }) => (
           <Notification>
             Example notification
-            <Close onClick={close} aria-label="Close" />
+            <Notification.Close onClick={close} aria-label="Close" />
           </Notification>
         ))
       }
diff --git a/packages/notifications/demo/alert.stories.mdx b/packages/notifications/demo/alert.stories.mdx
@@ -1,12 +1,16 @@
 import { Meta, ArgsTable, Canvas, Story, Markdown } from '@storybook/addon-docs';
-import { Alert, Close, Paragraph, Title } from '@zendeskgarden/react-notifications';
+import { Alert } from '@zendeskgarden/react-notifications';
 import { AlertStory } from './stories/AlertStory';
 import README from '../README.md';
 
 <Meta
   title="Packages/Notifications/Alert"
   component={Alert}
-  subcomponents={{ Close, Paragraph, Title }}
+  subcomponents={{
+    'Alert.Close': Alert.Close,
+    'Alert.Paragraph': Alert.Paragraph,
+    'Alert.Title': Alert.Title
+  }}
 />
 
 # API
@@ -27,11 +31,11 @@ import README from '../README.md';
       'aria-label': 'Close'
     }}
     argTypes={{
-      title: { name: 'children', table: { category: 'Title' } },
-      isRegular: { control: { type: 'boolean' }, table: { category: 'Title' } },
-      hasClose: { name: 'Close', table: { category: 'Story' } },
-      hasParagraph: { name: 'Paragraph', table: { category: 'Story' } },
-      'aria-label': { table: { category: 'Close' } }
+      title: { name: 'children', table: { category: 'Alert.Title' } },
+      isRegular: { control: { type: 'boolean' }, table: { category: 'Alert.Title' } },
+      hasClose: { name: 'Alert.Close', table: { category: 'Story' } },
+      hasParagraph: { name: 'Alert.Paragraph', table: { category: 'Story' } },
+      'aria-label': { table: { category: 'Alert.Close' } }
     }}
     parameters={{
       design: {
diff --git a/packages/notifications/demo/notification.stories.mdx b/packages/notifications/demo/notification.stories.mdx
@@ -1,12 +1,16 @@
 import { Meta, ArgsTable, Canvas, Story, Markdown } from '@storybook/addon-docs';
-import { Notification, Close, Paragraph, Title } from '@zendeskgarden/react-notifications';
+import { Notification } from '@zendeskgarden/react-notifications';
 import { NotificationStory } from './stories/NotificationStory';
 import README from '../README.md';
 
 <Meta
   title="Packages/Notifications/Notification"
   component={Notification}
-  subcomponents={{ Close, Paragraph, Title }}
+  subcomponents={{
+    'Notification.Close': Notification.Close,
+    'Notification.Paragraph': Notification.Paragraph,
+    'Notification.Title': Notification.Title
+  }}
 />
 
 # API
@@ -26,11 +30,11 @@ import README from '../README.md';
       'aria-label': 'Close'
     }}
     argTypes={{
-      title: { name: 'children', table: { category: 'Title' } },
-      isRegular: { control: { type: 'boolean' }, table: { category: 'Title' } },
-      hasClose: { name: 'Close', table: { category: 'Story' } },
-      hasParagraph: { name: 'Paragraph', table: { category: 'Story' } },
-      'aria-label': { table: { category: 'Close' } }
+      title: { name: 'children', table: { category: 'Notification.Title' } },
+      isRegular: { control: { type: 'boolean' }, table: { category: 'Notification.Title' } },
+      hasClose: { name: 'Notification.Close', table: { category: 'Story' } },
+      hasParagraph: { name: 'Notification.Paragraph', table: { category: 'Story' } },
+      'aria-label': { table: { category: 'Notification.Close' } }
     }}
     parameters={{
       design: {
diff --git a/packages/notifications/demo/stories/AlertStory.tsx b/packages/notifications/demo/stories/AlertStory.tsx
@@ -7,7 +7,7 @@
 
 import React from 'react';
 import { Story } from '@storybook/react';
-import { Alert, Close, IAlertProps, Paragraph, Title } from '@zendeskgarden/react-notifications';
+import { Alert, IAlertProps } from '@zendeskgarden/react-notifications';
 
 interface IArgs extends IAlertProps {
   title?: string;
@@ -26,8 +26,8 @@ export const AlertStory: Story<IArgs> = ({
   ...args
 }) => (
   <Alert {...args}>
-    {title && <Title isRegular={isRegular}>{title}</Title>}
-    {hasParagraph ? <Paragraph>{children}</Paragraph> : children}
-    {hasClose && <Close aria-label={ariaLabel} />}
+    {title && <Alert.Title isRegular={isRegular}>{title}</Alert.Title>}
+    {hasParagraph ? <Alert.Paragraph>{children}</Alert.Paragraph> : children}
+    {hasClose && <Alert.Close aria-label={ariaLabel} />}
   </Alert>
 );
diff --git a/packages/notifications/demo/stories/NotificationStory.tsx b/packages/notifications/demo/stories/NotificationStory.tsx
@@ -7,13 +7,7 @@
 
 import React from 'react';
 import { Story } from '@storybook/react';
-import {
-  Notification,
-  Close,
-  INotificationProps,
-  Title,
-  Paragraph
-} from '@zendeskgarden/react-notifications';
+import { Notification, INotificationProps } from '@zendeskgarden/react-notifications';
 
 interface IArgs extends INotificationProps {
   title?: string;
@@ -32,8 +26,8 @@ export const NotificationStory: Story<IArgs> = ({
   ...args
 }) => (
   <Notification {...args}>
-    {title && <Title isRegular={isRegular}>{title}</Title>}
-    {hasParagraph ? <Paragraph>{children}</Paragraph> : children}
-    {hasClose && <Close aria-label={ariaLabel} />}
+    {title && <Notification.Title isRegular={isRegular}>{title}</Notification.Title>}
+    {hasParagraph ? <Notification.Paragraph>{children}</Notification.Paragraph> : children}
+    {hasClose && <Notification.Close aria-label={ariaLabel} />}
   </Notification>
 );
diff --git a/packages/notifications/demo/stories/WellStory.tsx b/packages/notifications/demo/stories/WellStory.tsx
@@ -7,7 +7,7 @@
 
 import React from 'react';
 import { Story } from '@storybook/react';
-import { Well, IWellProps, Paragraph, Title } from '@zendeskgarden/react-notifications';
+import { Well, IWellProps } from '@zendeskgarden/react-notifications';
 
 interface IArgs extends IWellProps {
   title?: string;
@@ -17,7 +17,7 @@ interface IArgs extends IWellProps {
 
 export const WellStory: Story<IArgs> = ({ children, title, hasParagraph, isRegular, ...args }) => (
   <Well {...args}>
-    {title && <Title isRegular={isRegular}>{title}</Title>}
-    {hasParagraph ? <Paragraph>{children}</Paragraph> : children}
+    {title && <Well.Title isRegular={isRegular}>{title}</Well.Title>}
+    {hasParagraph ? <Well.Paragraph>{children}</Well.Paragraph> : children}
   </Well>
 );
diff --git a/packages/notifications/demo/well.stories.mdx b/packages/notifications/demo/well.stories.mdx
@@ -1,9 +1,16 @@
 import { Meta, ArgsTable, Canvas, Story, Markdown } from '@storybook/addon-docs';
-import { Well, Close, Paragraph, Title } from '@zendeskgarden/react-notifications';
+import { Well } from '@zendeskgarden/react-notifications';
 import { WellStory } from './stories/WellStory';
 import README from '../README.md';
 
-<Meta title="Packages/Notifications/Well" component={Well} subcomponents={{ Paragraph, Title }} />
+<Meta
+  title="Packages/Notifications/Well"
+  component={Well}
+  subcomponents={{
+    'Well.Paragraph': Well.Paragraph,
+    'Well.Title': Well.Title
+  }}
+/>
 
 # API
 
@@ -16,9 +23,9 @@ import README from '../README.md';
     name="Well"
     args={{ children: 'Text', title: 'Title', hasParagraph: false }}
     argTypes={{
-      title: { name: 'children', table: { category: 'Title' } },
-      isRegular: { control: { type: 'boolean' }, table: { category: 'Title' } },
-      hasParagraph: { name: 'Paragraph', table: { category: 'Story' } }
+      title: { name: 'children', table: { category: 'Well.Title' } },
+      isRegular: { control: { type: 'boolean' }, table: { category: 'Well.Title' } },
+      hasParagraph: { name: 'Well.Paragraph', table: { category: 'Story' } }
     }}
     parameters={{
       design: {
diff --git a/packages/notifications/src/elements/Alert.tsx b/packages/notifications/src/elements/Alert.tsx
@@ -11,28 +11,43 @@ import { IAlertProps, TYPE } from '../types';
 import { StyledAlert, StyledIcon } from '../styled';
 import { validationIcons, validationHues } from '../utils/icons';
 import { Hue, NotificationsContext } from '../utils/useNotificationsContext';
+import { Title } from './content/Title';
+import { Paragraph } from './content/Paragraph';
+import { Close } from './content/Close';
 
-/**
- * @extends HTMLAttributes<HTMLDivElement>
- */
-export const Alert = React.forwardRef<HTMLDivElement, IAlertProps>(({ role, ...props }, ref) => {
-  const hue = validationHues[props.type];
-  const Icon = validationIcons[props.type] as any;
+export const AlertComponent = React.forwardRef<HTMLDivElement, IAlertProps>(
+  ({ role, ...props }, ref) => {
+    const hue = validationHues[props.type];
+    const Icon = validationIcons[props.type] as any;
 
-  return (
-    <NotificationsContext.Provider value={hue as Hue}>
-      <StyledAlert ref={ref} hue={hue} role={role === undefined ? 'alert' : role} {...props}>
-        <StyledIcon hue={hue}>
-          <Icon />
-        </StyledIcon>
-        {props.children}
-      </StyledAlert>
-    </NotificationsContext.Provider>
-  );
-});
+    return (
+      <NotificationsContext.Provider value={hue as Hue}>
+        <StyledAlert ref={ref} hue={hue} role={role === undefined ? 'alert' : role} {...props}>
+          <StyledIcon hue={hue}>
+            <Icon />
+          </StyledIcon>
+          {props.children}
+        </StyledAlert>
+      </NotificationsContext.Provider>
+    );
+  }
+);
 
-Alert.displayName = 'Alert';
+AlertComponent.displayName = 'Alert';
 
-Alert.propTypes = {
+AlertComponent.propTypes = {
   type: PropTypes.oneOf(TYPE).isRequired
 };
+
+/**
+ * @extends HTMLAttributes<HTMLDivElement>
+ */
+export const Alert = AlertComponent as typeof AlertComponent & {
+  Close: typeof Close;
+  Paragraph: typeof Paragraph;
+  Title: typeof Title;
+};
+
+Alert.Close = Close;
+Alert.Paragraph = Paragraph;
+Alert.Title = Title;
diff --git a/packages/notifications/src/elements/Notification.tsx b/packages/notifications/src/elements/Notification.tsx
@@ -11,11 +11,11 @@ import InfoStrokeIcon from '@zendeskgarden/svg-icons/src/16/info-stroke.svg';
 import { INotificationProps, TYPE } from '../types';
 import { StyledNotification, StyledIcon } from '../styled';
 import { validationIcons, validationHues } from '../utils/icons';
+import { Title } from './content/Title';
+import { Paragraph } from './content/Paragraph';
+import { Close } from './content/Close';
 
-/**
- * @extends HTMLAttributes<HTMLDivElement>
- */
-export const Notification = forwardRef<HTMLDivElement, INotificationProps>(
+export const NotificationComponent = forwardRef<HTMLDivElement, INotificationProps>(
   ({ role, ...props }, ref) => {
     const Icon = props.type ? validationIcons[props.type] : InfoStrokeIcon;
     const hue = props.type && validationHues[props.type];
@@ -40,8 +40,21 @@ export const Notification = forwardRef<HTMLDivElement, INotificationProps>(
   }
 );
 
-Notification.displayName = 'Notification';
+NotificationComponent.displayName = 'Notification';
 
-Notification.propTypes = {
+NotificationComponent.propTypes = {
   type: PropTypes.oneOf(TYPE)
 };
+
+/**
+ * @extends HTMLAttributes<HTMLDivElement>
+ */
+export const Notification = NotificationComponent as typeof NotificationComponent & {
+  Close: typeof Close;
+  Paragraph: typeof Paragraph;
+  Title: typeof Title;
+};
+
+Notification.Close = Close;
+Notification.Paragraph = Paragraph;
+Notification.Title = Title;
diff --git a/packages/notifications/src/elements/Well.tsx b/packages/notifications/src/elements/Well.tsx
@@ -9,17 +9,27 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import { IWellProps } from '../types';
 import { StyledWell } from '../styled';
+import { Title } from './content/Title';
+import { Paragraph } from './content/Paragraph';
 
-/**
- * @extends HTMLAttributes<HTMLDivElement>
- */
-export const Well = React.forwardRef<HTMLDivElement, IWellProps>((props, ref) => (
+export const WellComponent = React.forwardRef<HTMLDivElement, IWellProps>((props, ref) => (
   <StyledWell ref={ref} {...props} />
 ));
 
-Well.displayName = 'Well';
+WellComponent.displayName = 'Well';
 
-Well.propTypes = {
+WellComponent.propTypes = {
   isRecessed: PropTypes.bool,
   isFloating: PropTypes.bool
 };
+
+/**
+ * @extends HTMLAttributes<HTMLDivElement>
+ */
+export const Well = WellComponent as typeof WellComponent & {
+  Paragraph: typeof Paragraph;
+  Title: typeof Title;
+};
+
+Well.Paragraph = Paragraph;
+Well.Title = Title;
diff --git a/packages/notifications/src/elements/content/Close.tsx b/packages/notifications/src/elements/content/Close.tsx
@@ -12,6 +12,8 @@ import { useText } from '@zendeskgarden/react-theming';
 import XStrokeIcon from '@zendeskgarden/svg-icons/src/12/x-stroke.svg';
 
 /**
+ * @deprecated use `Alert.Close` or `Notification.Close` instead
+ *
  * @extends ButtonHTMLAttributes<HTMLButtonElement>
  */
 export const Close = React.forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
diff --git a/packages/notifications/src/elements/content/Paragraph.tsx b/packages/notifications/src/elements/content/Paragraph.tsx
@@ -9,6 +9,8 @@ import React, { HTMLAttributes } from 'react';
 import { StyledParagraph } from '../../styled';
 
 /**
+ * @deprecated use `Alert.Paragraph`, `Notification.Paragraph`, or `Well.Paragraph` instead
+ *
  * @extends HTMLAttributes<HTMLParagraphElement>
  */
 export const Paragraph = React.forwardRef<
diff --git a/packages/notifications/src/elements/content/Title.tsx b/packages/notifications/src/elements/content/Title.tsx
@@ -10,6 +10,8 @@ import { ITitleProps } from '../../types';
 import { StyledTitle } from '../../styled';
 
 /**
+ * @deprecated use `Alert.Title`, `Notification.Title`, or `Well.Title` instead
+ *
  * @extends HTMLAttributes<HTMLDivElement>
  */
 export const Title = React.forwardRef<HTMLDivElement, ITitleProps>((props, ref) => (
