[Typography foundations] Text component beta release

.changeset/grumpy-cycles-explode.md

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

.changeset/grumpy-donuts-agree.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': minor
+---
+
+Deprecated `DisplayText`, `Heading`, `Subheading`, `Caption`, `TextStyle`, and `VisuallyHidden` pages and removed examples

polaris-react/playground/DetailsPage.tsx

@@ -19,7 +19,6 @@ import {
 import {
   ActionList,
   Badge,
-  Caption,
   Card,
   ContextualSaveBar,
   DropZone,
@@ -36,12 +35,12 @@ import {
   SkeletonDisplayText,
   SkeletonPage,
   Stack,
+  Text,
   TextContainer,
   TextField,
   Thumbnail,
   Toast,
   TopBar,
-  VisuallyHidden,
 } from '../src';
 
 import styles from './DetailsPage.scss';
@@ -451,7 +450,7 @@ export function DetailsPage() {
   const loadingMarkup = isLoading ? <Loading /> : null;
 
   const skipToContentTarget = (
-    <VisuallyHidden>
+    <Text as="span" variant="bodySm" visuallyHidden>
       <a
         href="#SkipToContent"
         id="SkipToContentTarget"
@@ -460,7 +459,7 @@ export function DetailsPage() {
       >
         Page content
       </a>
-    </VisuallyHidden>
+    </Text>
   );
 
   const [title, setTitle] = useState(
@@ -534,7 +533,10 @@ export function DetailsPage() {
             }
           />
           <div>
-            {file.name} <Caption>{file.size} bytes</Caption>
+            {file.name}{' '}
+            <Text as="p" variant="bodySm">
+              {file.size} bytes
+            </Text>
           </div>
         </Stack>
       ))}

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/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/Heading/Heading.tsx

@@ -16,7 +16,21 @@ export interface HeadingProps {
   id?: string;
 }
 
+/**
+ * @deprecated The Heading 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 Heading({element: Element = 'h2', children, id}: HeadingProps) {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `Heading` 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={styles.Heading} id={id}>
       {children}

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

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

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

@@ -13,12 +13,26 @@ export interface SubheadingProps {
   /** Text to display in subheading */
   children?: React.ReactNode;
 }
-
+/**
+ * @deprecated The Subheading 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 Subheading({
   element: Element = 'h3',
   children,
 }: SubheadingProps) {
   const ariaLabel = typeof children === 'string' ? children : undefined;
+
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `Subheading` 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 aria-label={ariaLabel} className={styles.Subheading}>
       {children}

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

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

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

@@ -7,7 +7,6 @@ import React, {
 } from 'react';
 import {CircleCancelMinor} from '@shopify/polaris-icons';
 
-import {Text} from '../Text';
 import {classNames, variationName} from '../../utilities/css';
 import {useI18n} from '../../utilities/i18n';
 import {useUniqueId} from '../../utilities/unique-id';
@@ -16,6 +15,7 @@ import {Labelled, LabelledProps, helpTextID, labelID} from '../Labelled';
 import {Connected} from '../Connected';
 import {Error, Key} from '../../types';
 import {Icon} from '../Icon';
+import {Text} from '../Text';
 
 import {Resizer, Spinner, SpinnerProps} from './components';
 import styles from './TextField.scss';

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

@@ -28,11 +28,26 @@ export interface TextStyleProps {
   children?: React.ReactNode;
 }
 
+/**
+ * @deprecated The TextStyle 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 TextStyle({variation, children}: TextStyleProps) {
   const className = classNames(
     variation && styles[variationName('variation', variation)],
     variation === VariationValue.Code && styles.code,
   );
+
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `TextStyle` 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',
+    );
+  }
+
   const Element = variationElement(variation);
 
   return <Element className={className}>{children}</Element>;

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

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

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

@@ -7,6 +7,20 @@ export interface VisuallyHiddenProps {
   children?: React.ReactNode;
 }
 
+/**
+ * @deprecated The VisuallyHidden 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 VisuallyHidden({children}: VisuallyHiddenProps) {
+  if (process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The  VisuallyHidden` 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 <span className={styles.VisuallyHidden}>{children}</span>;
 }

polaris.shopify.com/content/components/caption.md

@@ -15,10 +15,18 @@ keywords:
   - time text
   - compact text
   - small text
-examples:
-  - fileName: caption-default.tsx
-    title: Default
-    description: Use to provide details in situations where content is compact and space is tight.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Caption>Received April 21, 2017</Caption>
++ <Text variant="bodySm" as="p">Received April 21, 2017</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/display-text.md

@@ -23,19 +23,41 @@ keywords:
   - visual story telling
   - visual storytelling
   - visual statements
-examples:
-  - fileName: display-text-extra-large.tsx
-    title: Extra large
-    description: Use this size sparingly and never multiple times on the same page.
-  - fileName: display-text-large.tsx
-    title: Large
-    description: Use for display text that’s more important than the medium size, but less important than extra large.
-  - fileName: display-text-medium.tsx
-    title: Medium
-    description: Use for display text that’s more important than the small size, but less important than large.
-  - fileName: display-text-small.tsx
-    title: Small
-    description: Use for text that would otherwise use body text, but that needs to scale with other display text.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+### Small
+
+```diff
+- <DisplayText size="small">Sales this year</DisplayText>
++ <Text variant="headingLg" as="p">Sales this year</Text>
+```
+
+### Medium
+
+```diff
+- <DisplayText size="medium">Sales this year</DisplayText>
++ <Text variant="headingXl" as="p">Sales this year</Text>
+```
+
+### Large
+
+```diff
+- <DisplayText size="large">Sales this year</DisplayText>
++ <Text variant="heading2xl" as="p">Sales this year</Text>
+```
+
+### Extra large
+
+```diff
+- <DisplayText size="extraLarge">Sales this year</DisplayText>
++ <Text variant="heading4xl" as="p">Sales this year</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/heading.md

@@ -14,10 +14,18 @@ keywords:
   - section headings
   - heading text
   - heading font
-examples:
-  - fileName: heading-default.tsx
-    title: Default
-    description: Use for the title of each top-level page section.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Heading>Online store dashboard</Heading>
++ <Text variant="headingMd" as="h2">Online store dashboard</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/subheading.md

@@ -10,10 +10,18 @@ keywords:
   - titles of sub-sections
   - subsection titles
   - titles of subsections
-examples:
-  - fileName: subheading-default.tsx
-    title: Default
-    description: Used for the title of any sub-sections in top-level page sections.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Subheading>Accounts</Subheading>
++ <Text variant="headingXs" as="h3">Accounts</Text>
+```
+
 ---
 
 ## Best practices