[Page] Add ReactNode as an accepted primaryAction prop value

UNRELEASED.md

@@ -6,6 +6,10 @@
 
 ### Enhancements
 
+- Added `ReactNode` as an accepted prop type to `primaryAction` on the `Page` component ([#3002](https://github.com/Shopify/polaris-react/pull/3002))
+- Added a `fullWidth` prop to `EmptyState` to support full width layout within a content context ([#2992](https://github.com/Shopify/polaris-react/pull/2992))
+- Added an `emptyState` prop to `ResourceList` to support in context empty states in list views ([#2569](https://github.com/Shopify/polaris-react/pull/2569))
+
 ### Bug fixes
 
 ### Documentation

src/components/Page/Page.tsx

@@ -16,7 +16,7 @@ import {
   WithAppProviderProps,
 } from '../../utilities/with-app-provider';
 
-import {Header, HeaderProps} from './components';
+import {Header, HeaderProps, isPrimaryAction} from './components';
 import styles from './Page.scss';
 
 export interface PageProps extends HeaderProps {
@@ -166,7 +166,7 @@ class PageInner extends React.PureComponent<ComposedProps, never> {
     return {
       title,
       buttons: transformActions(appBridge, {
-        primaryAction,
+        ...(isPrimaryAction(primaryAction) && {primaryAction}),
         secondaryActions,
         actionGroups,
       }),

src/components/Page/README.md

@@ -248,6 +248,32 @@ Use for building any page on iOS.
 
 <!-- /content-for -->
 
+### Page with custom primary action
+
+<!-- example-for: web -->
+
+Use to create a custom primary action.
+
+```jsx
+<Page
+  breadcrumbs={[{content: 'Settings', url: '/settings'}]}
+  title="General"
+  primaryAction={
+    <Button
+      primary
+      connectedDisclosure={{
+        accessibilityLabel: 'Other save actions',
+        actions: [{content: 'Save as new'}],
+      }}
+    >
+      Save
+    </Button>
+  }
+>
+  <p>Page content</p>
+</Page>
+```
+
 ### Page without primary action in header
 
 <!-- example-for: web -->

src/components/Page/components/Header/Header.tsx

@@ -43,7 +43,7 @@ export interface HeaderProps extends TitleProps {
   /** Adds a border to the bottom of the page header (stand-alone app use only) */
   separator?: boolean;
   /** Primary page-level action */
-  primaryAction?: PrimaryAction;
+  primaryAction?: PrimaryAction | React.ReactNode;
   /** Page-level pagination (stand-alone app use only) */
   pagination?: PaginationDescriptor;
   /** Collection of breadcrumbs */
@@ -56,6 +56,12 @@ export interface HeaderProps extends TitleProps {
   additionalNavigation?: React.ReactNode;
 }
 
+export function isPrimaryAction(
+  x: PrimaryAction | React.ReactNode,
+): x is PrimaryAction {
+  return !React.isValidElement(x) && x !== undefined;
+}
+
 export function Header({
   title,
   subtitle,
@@ -116,28 +122,8 @@ export function Header({
     />
   );
 
-  const primary =
-    primaryAction &&
-    (primaryAction.primary === undefined ? true : primaryAction.primary);
-
   const primaryActionMarkup = primaryAction ? (
-    <ConditionalWrapper
-      condition={newDesignLanguage === false}
-      wrapper={(children) => (
-        <div className={styles.PrimaryActionWrapper}>{children}</div>
-      )}
-    >
-      {buttonsFrom(
-        shouldShowIconOnly(
-          newDesignLanguage,
-          isNavigationCollapsed,
-          primaryAction,
-        ),
-        {
-          primary,
-        },
-      )}
-    </ConditionalWrapper>
+    <PrimaryActionMarkup primaryAction={primaryAction} />
   ) : null;
 
   const actionMenuMarkup =
@@ -228,6 +214,42 @@ export function Header({
   );
 }
 
+function PrimaryActionMarkup({
+  primaryAction,
+}: {
+  primaryAction: PrimaryAction | React.ReactNode;
+}) {
+  const {isNavigationCollapsed} = useMediaQuery();
+  const {newDesignLanguage} = useFeatures();
+  let content = primaryAction;
+  if (isPrimaryAction(primaryAction)) {
+    const primary =
+      primaryAction.primary === undefined ? true : primaryAction.primary;
+
+    content = buttonsFrom(
+      shouldShowIconOnly(
+        newDesignLanguage,
+        isNavigationCollapsed,
+        primaryAction,
+      ),
+      {
+        primary,
+      },
+    );
+  }
+
+  return (
+    <ConditionalWrapper
+      condition={newDesignLanguage === false}
+      wrapper={(children) => (
+        <div className={styles.PrimaryActionWrapper}>{children}</div>
+      )}
+    >
+      {content}
+    </ConditionalWrapper>
+  );
+}
+
 function shouldShowIconOnly(
   newDesignLanguage: boolean,
   isMobile: boolean,

src/components/Page/components/Header/tests/Header.test.tsx

@@ -12,6 +12,7 @@ import {
 } from 'components';
 // eslint-disable-next-line no-restricted-imports
 import {mountWithAppProvider} from 'test-utilities/legacy';
+import {mountWithApp} from 'test-utilities';
 
 import type {LinkAction} from '../../../../../types';
 import {Header, HeaderProps} from '../Header';
@@ -98,6 +99,16 @@ describe('<Header />', () => {
       const expectedButton = buttonsFrom(primaryAction, {primary: false});
       expect(header.contains(expectedButton)).toBeTruthy();
     });
+
+    it('renders a `ReactNode`', () => {
+      const PrimaryAction = () => null;
+
+      const header = mountWithApp(
+        <Header {...mockProps} primaryAction={<PrimaryAction />} />,
+      );
+
+      expect(header).toContainReactComponent(PrimaryAction);
+    });
   });
 
   describe('pagination', () => {