[Typography foundations] Text component beta release (#7068)

### WHY are these changes introduced?

Resolves #6537, resolves #7647.

Deprecates our existing typography components with mapping to the new
`Text` component.
Updates the `Text` component page in the style guide to use the `beta`
flag instead of `alpha`.

### WHAT is this pull request doing?

Deprecates `Caption`, `DisplayText`, `Heading`, `Subheading`,
`TextStyle`, and `VisuallyHidden` on the style guide and in
`polaris-react`.

Adds logic in the style guide to hide the prop table if the component is
deprecated and hide the component examples if none exist.
    <details>
      <summary>Deprecated Caption component page</summary>
<img
src="https://user-images.githubusercontent.com/26749317/198280661-5b29b45c-9cc9-4bff-aee3-86caf08d65c0.png"
alt="Deprecated Caption component page">
    </details>

<!-- ℹ️ Delete the following for small / trivial changes -->

### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#local-development)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [x] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [x] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Co-authored-by: Chaz Dean <59836805+chazdean@users.noreply.github.com>

Author: laurkim

.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}