Deprecate breadcrumbs and allow singular backAction prop on Page and Breadcrumbs (#8135)

### WHY are these changes introduced?

As a followup to #8016 in
preparation for v11 where breadcrumb becomes singular
(#7990).

I should have originally done this and deprecated breadcrumbs but at the
time we had a different upgrade path in mind. After collaborating with a
number of folks we determined deprecating breadcrumbs officially and
moving to a singular breadcrumb in a `backAction` prop for v11 was the
best path.

### WHAT is this pull request doing?

<!--
  Summary of the changes committed.

Before / after screenshots are appreciated for UI changes. Make sure to
include alt text that describes the screenshot.

If you include an animated gif showing your change, wrapping it in a
details tag is recommended. Gifs usually autoplay, which can cause
accessibility issues for people reviewing your PR:

    <details>
      <summary>Summary of your gif(s)</summary>
      <img src="..." alt="Description of what the gif shows">
    </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)

<!--
  Give as much information as needed to experiment with the component
  in the playground.
-->

<details>
<summary>Copy-paste this code in
<code>playground/Playground.tsx</code>:</summary>

```jsx
import React from 'react';
import {Page} from '../src';

export function Playground() {
  return (
    <Page title="Playground">
      {/* Add the code you want to test in here */}
    </Page>
  );
}
```

</details>

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] 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
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

---------

Co-authored-by: Chloe Rice <chloerice@users.noreply.github.com>

Author: itwasmattgregg

.changeset/metal-cows-poke.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Deprecated the `Page` `breadcrumbs` prop in favor of the new `backAction` prop.

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

@@ -10,15 +10,25 @@ import {Text} from '../Text';
 import styles from './Breadcrumbs.scss';
 
 export interface BreadcrumbsProps {
-  /** Collection of breadcrumbs */
-  breadcrumbs: (CallbackAction | LinkAction) | (CallbackAction | LinkAction)[];
+  /** @deprecated Collection of breadcrumbs */
+  breadcrumbs?: (CallbackAction | LinkAction) | (CallbackAction | LinkAction)[];
+  /** Back action link */
+  backAction?: CallbackAction | LinkAction;
 }
 
-export function Breadcrumbs({breadcrumbs}: BreadcrumbsProps) {
-  const breadcrumb = Array.isArray(breadcrumbs)
-    ? breadcrumbs[breadcrumbs.length - 1]
-    : breadcrumbs;
+export function Breadcrumbs({breadcrumbs, backAction}: BreadcrumbsProps) {
+  const breadcrumb =
+    backAction ??
+    (Array.isArray(breadcrumbs)
+      ? breadcrumbs[breadcrumbs.length - 1]
+      : breadcrumbs);
   if (breadcrumb == null) {
+    if (process.env.NODE_ENV === 'development') {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'Please provide a value to backAction, it will become required in the next major release.',
+      );
+    }
     return null;
   }
 

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

@@ -43,7 +43,8 @@ export function Page({
     (rest.breadcrumbs != null &&
       Array.isArray(rest.breadcrumbs) &&
       rest.breadcrumbs.length > 0) ||
-    rest.breadcrumbs != null;
+    rest.breadcrumbs != null ||
+    rest.backAction != null;
 
   const contentClassName = classNames(
     !hasHeaderContent && styles.Content,

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

@@ -49,8 +49,10 @@ export interface HeaderProps extends TitleProps {
   primaryAction?: PrimaryAction | React.ReactNode;
   /** Page-level pagination */
   pagination?: PaginationProps;
-  /** Collection of breadcrumbs */
+  /** @deprecated Collection of breadcrumbs */
   breadcrumbs?: BreadcrumbsProps['breadcrumbs'];
+  /** A back action link */
+  backAction?: BreadcrumbsProps['backAction'];
   /** Collection of secondary page-level actions */
   secondaryActions?: MenuActionDescriptor[] | React.ReactNode;
   /** Collection of page-level groups of secondary actions */
@@ -77,6 +79,7 @@ export function Header({
   pagination,
   additionalNavigation,
   breadcrumbs,
+  backAction,
   secondaryActions = [],
   actionGroups = [],
   compactTitle = false,
@@ -91,6 +94,12 @@ export function Header({
       'Deprecation: The `additionalNavigation` on Page is deprecated and will be removed in the next major version.',
     );
   }
+  if (breadcrumbs && process.env.NODE_ENV === 'development') {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Deprecation: The `breadcrumbs` prop on Page is deprecated and will be removed in the next major version. Please replace with a single `backAction`.',
+    );
+  }
 
   const isSingleRow =
     !primaryAction &&
@@ -99,15 +108,27 @@ export function Header({
       isReactElement(secondaryActions)) &&
     !actionGroups.length;
 
-  const breadcrumbMarkup =
+  let breadcrumbMarkup = null;
+  if (backAction) {
+    breadcrumbMarkup = (
+      <div className={styles.BreadcrumbWrapper}>
+        <Box maxWidth="100%" paddingInlineEnd="4" printHidden>
+          <Breadcrumbs backAction={backAction} />
+        </Box>
+      </div>
+    );
+  } else if (
     (Array.isArray(breadcrumbs) && breadcrumbs.length > 0) ||
-    (!Array.isArray(breadcrumbs) && breadcrumbs) ? (
+    (!Array.isArray(breadcrumbs) && breadcrumbs)
+  ) {
+    breadcrumbMarkup = (
       <div className={styles.BreadcrumbWrapper}>
         <Box maxWidth="100%" paddingInlineEnd="4" printHidden>
           <Breadcrumbs breadcrumbs={breadcrumbs} />
         </Box>
       </div>
-    ) : null;
+    );
+  }
 
   const paginationMarkup =
     pagination && !isNavigationCollapsed ? (

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

@@ -269,6 +269,29 @@ describe('<Page />', () => {
     });
   });
 
+  describe('backAction', () => {
+    const backAction = {
+      content: 'Products',
+      onAction: noop,
+    };
+
+    it('renders a <Header /> when defined', () => {
+      const page = mountWithApp(
+        <Page {...mockProps} backAction={backAction} />,
+      );
+      expect(page).toContainReactComponent(Header);
+    });
+
+    it('gets passed into the <Header />', () => {
+      const page = mountWithApp(
+        <Page {...mockProps} backAction={backAction} />,
+      );
+      expect(page).toContainReactComponent(Header, {
+        backAction,
+      });
+    });
+  });
+
   describe('divider', () => {
     it('renders border when divider is true and header props exist', () => {
       const wrapper = mountWithApp(<Page {...mockProps} divider />);