[Typography foundations] Add deprecation warnings for existing Text components

.changeset/grumpy-cycles-explode.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Deprecated `DisplayText`, `Heading`, `Subheading`, `Caption`, `TextStyle`, and `VisuallyHidden` components

polaris-react/playground/DetailsPage.tsx

@@ -19,6 +19,7 @@ import {
 import {
   ActionList,
   Badge,
+  // eslint-disable-next-line import/no-deprecated
   Caption,
   Card,
   ContextualSaveBar,
@@ -41,6 +42,7 @@ import {
   Thumbnail,
   Toast,
   TopBar,
+  // eslint-disable-next-line import/no-deprecated
   VisuallyHidden,
 } from '../src';
 

polaris-react/src/components/AccountConnection/AccountConnection.tsx

@@ -5,6 +5,7 @@ import {Avatar} from '../Avatar';
 import {buttonFrom} from '../Button';
 import {Card} from '../Card';
 import {Stack} from '../Stack';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../TextStyle';
 import {SettingAction} from '../SettingAction';
 

polaris-react/src/components/ActionList/components/Item/Item.tsx

@@ -6,6 +6,7 @@ import {Scrollable} from '../../../Scrollable';
 import {Icon} from '../../../Icon';
 import {UnstyledLink} from '../../../UnstyledLink';
 import {Badge} from '../../../Badge';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../../../TextStyle';
 import styles from '../../ActionList.scss';
 import {handleMouseUpByBlurring} from '../../../../utilities/focus';

polaris-react/src/components/ActionList/components/Item/tests/Item.test.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
 import {Item} from '../Item';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../../../../TextStyle';
 import {UnstyledLink} from '../../../../UnstyledLink';
 
@@ -54,6 +55,7 @@ describe('<Item />', () => {
   it('renders helpText when the helpText prop is defined', () => {
     const helpText = 'Foo';
     const item = mountWithApp(<Item helpText={helpText} />);
+    // eslint-disable-next-line import/no-deprecated
     expect(item.find(TextStyle)).toContainReactText(helpText);
   });
 

polaris-react/src/components/Autocomplete/components/MappedAction/MappedAction.tsx

@@ -6,6 +6,7 @@ import {classNames} from '../../../../utilities/css';
 import {MappedActionContext} from '../../../../utilities/autocomplete';
 import {Listbox} from '../../../Listbox';
 import {Icon} from '../../../Icon';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../../../TextStyle';
 import {useI18n} from '../../../../utilities/i18n';
 

polaris-react/src/components/Badge/Badge.tsx

@@ -3,6 +3,7 @@ import React, {useContext} from 'react';
 import {classNames, variationName} from '../../utilities/css';
 import {useI18n} from '../../utilities/i18n';
 import {WithinFilterContext} from '../../utilities/within-filter-context';
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../VisuallyHidden';
 import {Icon} from '../Icon';
 import type {IconSource} from '../../types';

polaris-react/src/components/Badge/components/Pip/Pip.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 
 import {classNames, variationName} from '../../../../utilities/css';
 import type {Progress, Status} from '../../types';
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../../../VisuallyHidden';
 import {useI18n} from '../../../../utilities/i18n';
 import {getDefaultAccessibilityLabel} from '../../utils';

polaris-react/src/components/Badge/tests/Badge.test.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 import {GlobeMinor} from '@shopify/polaris-icons';
 
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../../VisuallyHidden';
 import {Icon} from '../../Icon';
 import {Badge} from '../Badge';
@@ -14,11 +15,13 @@ describe('<Badge />', () => {
 
   it('accepts a status prop and renders a visually hidden label', () => {
     const badge = mountWithApp(<Badge status="success" />);
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden);
   });
 
   it('accepts a progress prop and renders a visually hidden label', () => {
     const badge = mountWithApp(<Badge progress="incomplete" />);
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden);
   });
 
@@ -27,6 +30,7 @@ describe('<Badge />', () => {
       <Badge progress="incomplete" status="attention" />,
     );
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponentTimes(VisuallyHidden, 1, {
       children: 'Attention Incomplete',
     });
@@ -87,6 +91,7 @@ describe('<Badge />', () => {
       />,
     );
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: mockAccessibilityLabel,
     });
@@ -102,6 +107,7 @@ describe('<Badge />', () => {
       />,
     );
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).not.toContainReactComponent(VisuallyHidden, {
       children: 'Attention Incomplete',
     });
@@ -112,24 +118,28 @@ describe('<Badge />', () => {
       <Badge status="attention" progress="incomplete" />,
     );
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Attention Incomplete',
     });
 
     badge = mountWithApp(<Badge progress="incomplete" />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Incomplete',
     });
 
     badge = mountWithApp(<Badge status="attention" />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Attention',
     });
 
     badge = mountWithApp(<Badge />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).not.toContainReactComponent(VisuallyHidden);
   });
 });
@@ -140,24 +150,28 @@ describe('<Badge.Pip />', () => {
       <Badge.Pip status="attention" progress="incomplete" />,
     );
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Attention Incomplete',
     });
 
     badge = mountWithApp(<Badge.Pip progress="partiallyComplete" />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Partially complete',
     });
 
     badge = mountWithApp(<Badge.Pip status="attention" />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Attention Complete',
     });
 
     badge = mountWithApp(<Badge.Pip />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(badge).toContainReactComponent(VisuallyHidden, {
       children: 'Complete',
     });

polaris-react/src/components/Banner/Banner.tsx

@@ -19,6 +19,7 @@ import {useUniqueId} from '../../utilities/unique-id';
 import {useI18n} from '../../utilities/i18n';
 import type {Action, DisableableAction, LoadableAction} from '../../types';
 import {Button} from '../Button';
+// eslint-disable-next-line import/no-deprecated
 import {Heading} from '../Heading';
 import {ButtonGroup} from '../ButtonGroup';
 import {UnstyledButton, unstyledButtonFrom} from '../UnstyledButton';

polaris-react/src/components/Banner/tests/Banner.test.tsx

@@ -9,6 +9,7 @@ import {
 import {mountWithApp} from 'tests/utilities';
 
 import {Button} from '../../Button';
+// eslint-disable-next-line import/no-deprecated
 import {Heading} from '../../Heading';
 import {Icon} from '../../Icon';
 import {Spinner} from '../../Spinner';
@@ -21,11 +22,13 @@ import {Banner, BannerHandles} from '../Banner';
 describe('<Banner />', () => {
   it('renders a title', () => {
     const banner = mountWithApp(<Banner title="Banner title" />);
+    // eslint-disable-next-line import/no-deprecated
     expect(banner.find(Heading)).toContainReactText('Banner title');
   });
 
   it('passes a p element to Heading', () => {
     const banner = mountWithApp(<Banner title="Banner title" />);
+    // eslint-disable-next-line import/no-deprecated
     expect(banner).toContainReactComponent(Heading, {element: 'p'});
   });
 

polaris-react/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -5,6 +5,7 @@ import {Icon} from '../Icon';
 import {UnstyledLink} from '../UnstyledLink';
 import type {CallbackAction, LinkAction} from '../../types';
 import {handleMouseUpByBlurring} from '../../utilities/focus';
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../VisuallyHidden';
 
 import styles from './Breadcrumbs.scss';

polaris-react/src/components/Breadcrumbs/tests/Breadcrumbs.test.tsx

@@ -3,6 +3,7 @@ import {mountWithApp} from 'tests/utilities';
 
 import type {CallbackAction, LinkAction} from '../../../types';
 import {Breadcrumbs} from '../Breadcrumbs';
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../../VisuallyHidden';
 
 describe('<Breadcrumbs />', () => {
@@ -103,6 +104,7 @@ describe('<Breadcrumbs />', () => {
   it('renders breadcrumb content as a visually hidden label when the new design language is enabled', () => {
     const wrapper = mountWithApp(<Breadcrumbs breadcrumbs={linkBreadcrumbs} />);
 
+    // eslint-disable-next-line import/no-deprecated
     expect(wrapper).toContainReactComponent(VisuallyHidden, {
       children: 'Products',
     });

polaris-react/src/components/CalloutCard/CalloutCard.tsx

@@ -7,6 +7,7 @@ import {Card} from '../Card';
 import {TextContainer} from '../TextContainer';
 import {ButtonGroup} from '../ButtonGroup';
 import {Button, buttonFrom} from '../Button';
+// eslint-disable-next-line import/no-deprecated
 import {Heading} from '../Heading';
 import {Image} from '../Image';
 

polaris-react/src/components/Caption/Caption.tsx

@@ -7,6 +7,20 @@ export interface CaptionProps {
   children?: React.ReactNode;
 }
 
+/**
+ * @deprecated The Caption component will be removed in the next
+ * major version. Use the Text component instead. See the
+ * Polaris component guide on how to use Text.
+ *
+ * https://polaris.shopify.com/components/text
+ */
 export function Caption({children}: CaptionProps) {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `Caption` component has been deprecated. Use the `Text` component instead. See the Polaris component guide on how to use `Text`. https://polaris.shopify.com/components/text',
+    );
+  }
+
   return <p className={styles.Caption}>{children}</p>;
 }

polaris-react/src/components/Caption/tests/Caption.test.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
+// eslint-disable-next-line import/no-deprecated
 import {Caption} from '../Caption';
 
 describe('<Caption />', () => {

polaris-react/src/components/Card/components/Header/Header.tsx

@@ -4,6 +4,7 @@ import type {DisableableAction} from '../../../../types';
 import {buttonsFrom} from '../../../Button';
 import {ButtonGroup} from '../../../ButtonGroup';
 import {Stack} from '../../../Stack';
+// eslint-disable-next-line import/no-deprecated
 import {Heading} from '../../../Heading';
 import styles from '../../Card.scss';
 

polaris-react/src/components/Card/components/Header/tests/Header.test.tsx

@@ -3,6 +3,7 @@ import {mountWithApp} from 'tests/utilities';
 
 import {buttonsFrom} from '../../../../Button';
 import {ButtonGroup} from '../../../../ButtonGroup';
+// eslint-disable-next-line import/no-deprecated
 import {Heading} from '../../../../Heading';
 import {Header} from '../Header';
 
@@ -17,12 +18,14 @@ describe('<Header />', () => {
   describe('title', () => {
     it('renders a heading when defined', () => {
       const header = mountWithApp(<Header title="Staff accounts" />);
+      // eslint-disable-next-line import/no-deprecated
       expect(header).toContainReactComponent(Heading);
     });
 
     it('renders the title directly if its a valid React element', () => {
       const title = <div>Staff accounts</div>;
       const header = mountWithApp(<Header title={title} />);
+      // eslint-disable-next-line import/no-deprecated
       expect(header).not.toContainReactComponent(Heading);
       expect(header).toContainReactComponent('div', {
         children: 'Staff accounts',
@@ -32,6 +35,7 @@ describe('<Header />', () => {
     it('is used as the content for the heading', () => {
       const title = 'Staff accounts';
       const header = mountWithApp(<Header title={title} />);
+      // eslint-disable-next-line import/no-deprecated
       expect(header.find(Heading)).toContainReactText(title);
     });
   });

polaris-react/src/components/Card/components/Section/Section.tsx

@@ -5,6 +5,7 @@ import type {ComplexAction} from '../../../../types';
 import {buttonsFrom} from '../../../Button';
 import {Stack} from '../../../Stack';
 import {ButtonGroup} from '../../../ButtonGroup';
+// eslint-disable-next-line import/no-deprecated
 import {Subheading} from '../../../Subheading';
 import styles from '../../Card.scss';
 

polaris-react/src/components/Card/components/Section/tests/Section.test.tsx

@@ -4,6 +4,7 @@ import {mountWithApp} from 'tests/utilities';
 import {Badge} from '../../../../Badge';
 import {Button} from '../../../../Button';
 import {ButtonGroup} from '../../../../ButtonGroup';
+// eslint-disable-next-line import/no-deprecated
 import {Subheading} from '../../../../Subheading';
 import {Section} from '../Section';
 
@@ -28,6 +29,7 @@ describe('<Card.Section />', () => {
   it('wraps plain string titles in a <Subheading />', () => {
     const titleString = 'Online store';
     const card = mountWithApp(<Section title={titleString} />);
+    // eslint-disable-next-line import/no-deprecated
     expect(card.find(Subheading)).toContainReactText(titleString);
   });
 

polaris-react/src/components/DisplayText/DisplayText.tsx

@@ -22,6 +22,13 @@ export interface DisplayTextProps {
   children?: React.ReactNode;
 }
 
+/**
+ * @deprecated The DisplayText component will be removed in the next
+ * major version. Use the Text component instead. See the
+ * Polaris component guide on how to use Text.
+ *
+ * https://polaris.shopify.com/components/text
+ */
 export function DisplayText({
   element: Element = 'p',
   children,
@@ -32,5 +39,12 @@ export function DisplayText({
     size && styles[variationName('size', size)],
   );
 
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `DisplayText` component has been deprecated. Use the `Text` component instead. See the Polaris component guide on how to use `Text`. https://polaris.shopify.com/components/text',
+    );
+  }
+
   return <Element className={className}>{children}</Element>;
 }

polaris-react/src/components/DisplayText/tests/DisplayText.test.tsx

@@ -1,6 +1,7 @@
 import React from 'react';
 import {mountWithApp} from 'tests/utilities';
 
+// eslint-disable-next-line import/no-deprecated
 import {DisplayText} from '../DisplayText';
 
 describe('<DisplayText />', () => {

polaris-react/src/components/DropZone/DropZone.tsx

@@ -15,8 +15,11 @@ import {classNames, variationName} from '../../utilities/css';
 import {capitalize} from '../../utilities/capitalize';
 import {Icon} from '../Icon';
 import {Stack} from '../Stack';
+// eslint-disable-next-line import/no-deprecated
 import {Caption} from '../Caption';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../TextStyle';
+// eslint-disable-next-line import/no-deprecated
 import {VisuallyHidden} from '../VisuallyHidden';
 import {Labelled, LabelledProps} from '../Labelled';
 import {useI18n} from '../../utilities/i18n';

polaris-react/src/components/DropZone/components/FileUpload/FileUpload.tsx

@@ -3,7 +3,9 @@ import React, {useContext} from 'react';
 import {classNames} from '../../../../utilities/css';
 import {capitalize} from '../../../../utilities/capitalize';
 import {Stack} from '../../../Stack';
+// eslint-disable-next-line import/no-deprecated
 import {Caption} from '../../../Caption';
+// eslint-disable-next-line import/no-deprecated
 import {TextStyle} from '../../../TextStyle';
 import {uploadArrow} from '../../images';
 import {DropZoneContext} from '../../context';