Deprecate breadcrumbs and allow singular backAction prop on Page and Breadcrumbs

.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 />);