[Page] Add support for tooltips on primaryAction and secondaryActions

Author: chloerice

.changeset/famous-emus-learn.md

@@ -2,4 +2,4 @@
 '@shopify/polaris': minor
 ---
 
-Support tooltip for Page component's primary & secondary actions
+Added `Tooltip` support for `Page` `primaryAction` and `secondaryActions`

polaris-react/README.md

@@ -33,7 +33,7 @@ Otherwise include the CSS in your HTML. We suggest copying the styles file into
 ```html
 <link
   rel="stylesheet"
-  href="https://unpkg.com/@shopify/[email protected].0/build/esm/styles.css"
+  href="https://unpkg.com/@shopify/[email protected].1/build/esm/styles.css"
 />
 ```
 
@@ -70,7 +70,7 @@ If React doesn’t make sense for your application, you can use a CSS-only versi
 ```html
 <link
   rel="stylesheet"
-  href="https://unpkg.com/@shopify/[email protected].0/build/esm/styles.css"
+  href="https://unpkg.com/@shopify/[email protected].1/build/esm/styles.css"
 />
 ```
 

polaris-react/src/components/ActionMenu/components/Actions/tests/Actions.test.tsx

@@ -3,6 +3,7 @@ import {mountWithApp} from 'tests/utilities';
 
 import {ActionMenuProps, ActionMenu} from '../../..';
 import {Actions, MenuGroup, RollupActions, SecondaryAction} from '../..';
+import {Tooltip} from '../../../../Tooltip';
 
 describe('<Actions />', () => {
   const mockProps: ActionMenuProps = {
@@ -40,6 +41,21 @@ describe('<Actions />', () => {
       expect(wrapper.findAll(SecondaryAction)).toHaveLength(3);
     });
 
+    it('renders a <Tooltip /> when helpText is set on an action', () => {
+      const toolTipAction = {
+        content: 'Refund',
+        helpText:
+          'You need permission from your store administrator to issue refunds.',
+      };
+
+      const wrapper = mountWithApp(<ActionMenu actions={[toolTipAction]} />);
+      const action = wrapper.find(SecondaryAction);
+
+      expect(action).toContainReactComponent(Tooltip, {
+        content: toolTipAction.helpText,
+      });
+    });
+
     it('renders a MenuGroup', () => {
       const wrapper = mountWithApp(
         <ActionMenu groups={[{title: 'group', actions: []}]} />,

polaris-react/src/components/ActionMenu/components/SecondaryAction/SecondaryAction.tsx

@@ -1,24 +1,24 @@
 import React, {useEffect, useRef} from 'react';
 
 import {classNames} from '../../../../utilities/css';
+import {Tooltip} from '../../../Tooltip';
 import {Button} from '../../../Button';
-import {tooltipFrom} from '../../../Tooltip';
 import type {ButtonProps} from '../../../Button';
-import type {ActionWithTooltip} from '../../../../types';
 
 import styles from './SecondaryAction.scss';
 
-interface SecondaryAction extends ButtonProps, ActionWithTooltip {
+interface SecondaryAction extends ButtonProps {
+  helpText?: React.ReactNode;
   onAction?(): void;
   getOffsetWidth?(width: number): void;
 }
 
 export function SecondaryAction({
   children,
   destructive,
+  helpText,
   onAction,
   getOffsetWidth,
-  tooltip,
   ...rest
 }: SecondaryAction) {
   const secondaryActionsRef = useRef<HTMLSpanElement>(null);
@@ -29,15 +29,17 @@ export function SecondaryAction({
     getOffsetWidth(secondaryActionsRef.current?.offsetWidth);
   }, [getOffsetWidth]);
 
-  let button = (
+  const buttonMarkup = (
     <Button onClick={onAction} {...rest}>
       {children}
     </Button>
   );
 
-  if (tooltip != null) {
-    button = tooltipFrom(tooltip, button);
-  }
+  const actionMarkup = helpText ? (
+    <Tooltip content={helpText}>{buttonMarkup}</Tooltip>
+  ) : (
+    buttonMarkup
+  );
 
   return (
     <span
@@ -47,7 +49,7 @@ export function SecondaryAction({
       )}
       ref={secondaryActionsRef}
     >
-      {button}
+      {actionMarkup}
     </span>
   );
 }

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

@@ -179,41 +179,43 @@ describe('<ActionMenu />', () => {
     });
   });
 
-  it('uses Button and ButtonGroup as subcomponents', () => {
-    const wrapper = mountWithApp(
-      <ActionMenu {...mockProps} actions={mockActions} />,
-    );
+  describe('<Actions />', () => {
+    it('uses Button and ButtonGroup as subcomponents', () => {
+      const wrapper = mountWithApp(
+        <ActionMenu {...mockProps} actions={mockActions} />,
+      );
 
-    expect(wrapper.findAll(Button)).toHaveLength(2);
-    expect(wrapper.findAll(ButtonGroup)).toHaveLength(1);
-  });
+      expect(wrapper.findAll(Button)).toHaveLength(2);
+      expect(wrapper.findAll(ButtonGroup)).toHaveLength(1);
+    });
+
+    it('passes action callbacks through to Button', () => {
+      const spy = jest.fn();
+      const wrapper = mountWithApp(
+        <ActionMenu
+          {...mockProps}
+          actions={[{content: 'mock', onAction: spy}]}
+        />,
+      );
 
-  it('action callbacks are passed through to Button', () => {
-    const spy = jest.fn();
-    const wrapper = mountWithApp(
-      <ActionMenu
-        {...mockProps}
-        actions={[{content: 'mock', onAction: spy}]}
-      />,
-    );
+      wrapper.find(Button)!.trigger('onClick');
 
-    wrapper.find(Button)!.trigger('onClick');
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
 
-    expect(spy).toHaveBeenCalledTimes(1);
-  });
+    it('passes `onActionRollup` if set', () => {
+      const onActionRollup = jest.fn();
+      const wrapper = mountWithApp(
+        <ActionMenu
+          {...mockProps}
+          actions={[{content: 'mock'}]}
+          onActionRollup={onActionRollup}
+        />,
+      );
 
-  it('renders <Actions /> passing `onActionRollup` as prop if it exists', () => {
-    const onActionRollup = jest.fn();
-    const wrapper = mountWithApp(
-      <ActionMenu
-        {...mockProps}
-        actions={[{content: 'mock'}]}
-        onActionRollup={onActionRollup}
-      />,
-    );
-
-    expect(wrapper).toContainReactComponent(Actions, {
-      onActionRollup,
+      expect(wrapper).toContainReactComponent(Actions, {
+        onActionRollup,
+      });
     });
   });
 });

polaris-react/src/components/Button/utils.tsx

@@ -1,7 +1,6 @@
 import React from 'react';
 
 import type {ComplexAction} from '../../types';
-import {tooltipFrom} from '../Tooltip';
 
 import {Button, ButtonProps} from './Button';
 
@@ -26,15 +25,13 @@ export function buttonsFrom(
 }
 
 export function buttonFrom(
-  {content, onAction, tooltip, ...action}: ComplexAction,
+  {content, onAction, ...action}: ComplexAction,
   overrides?: Partial<ButtonProps>,
   key?: any,
 ) {
-  const button = (
+  return (
     <Button key={key} onClick={onAction} {...action} {...overrides}>
       {content}
     </Button>
   );
-
-  return tooltip ? tooltipFrom(tooltip, button) : button;
 }

polaris-react/src/components/Page/README.md

@@ -254,6 +254,30 @@ Use to create a custom secondary action.
 </Page>
 ```
 
+### With tooltip action
+
+Use when merchants or their staff will benefit from context on why a page action is disabled.
+
+````jsx
+<Page
+  title="Product"
+  primaryAction={{
+    content: 'Save',
+  }}
+  secondaryActions={[
+    {
+      content: 'Import',
+      disabled: true,
+      helpText: 'You need permission to import products.',
+    },
+  ]}
+>
+  <Card title="Product X" sectioned>
+    <p>Product X information</p>
+  </Card>
+</Page>
+```
+
 ### With subtitle
 
 Use when the page title benefits from secondary content.
@@ -269,7 +293,7 @@ Use when the page title benefits from secondary content.
     <p>Credit card information</p>
   </Card>
 </Page>
-```
+````
 
 ### With external link
 
@@ -427,31 +451,6 @@ Use when the page needs visual separation between the page header and the conten
 </Page>
 ```
 
-### Page actions with tooltip
-
-Use actions with tooltip to give more context or if the action button is disabled to indicate the reason as to why it's disabled.
-
-```jsx
-<Page
-  title="Product"
-  primaryAction={{
-    content: 'Save',
-    tooltip: <span>Save is an <strong>async</strong> operation</span>,
-  }}
-  secondaryActions={[
-    {
-      content: 'Import',
-      disabled: true,
-      tooltip: 'You need permission to import products',
-    },
-  ]}
->
-  <Card title="Product X" sectioned>
-    <p>Product X information</p>
-  </Card>
-</Page>
-```
-
 ---
 
 ## Related components

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

@@ -1,22 +1,23 @@
 import React from 'react';
 
 import {classNames} from '../../../../utilities/css';
-import {buttonsFrom} from '../../../Button';
+import {buttonFrom} from '../../../Button';
 import {TextStyle} from '../../../TextStyle';
+import {Tooltip} from '../../../Tooltip';
 import {useMediaQuery} from '../../../../utilities/media-query';
 import {useI18n} from '../../../../utilities/i18n';
 import {
   ConditionalRender,
   ConditionalWrapper,
 } from '../../../../utilities/components';
 import type {
-  ActionWithTooltip,
   DestructableAction,
   DisableableAction,
   IconableAction,
   LoadableAction,
   MenuActionDescriptor,
   MenuGroupDescriptor,
+  TooltipAction,
 } from '../../../../types';
 import {Breadcrumbs, BreadcrumbsProps} from '../../../Breadcrumbs';
 import {Pagination, PaginationProps} from '../../../Pagination';
@@ -34,7 +35,7 @@ interface PrimaryAction
     DisableableAction,
     LoadableAction,
     IconableAction,
-    ActionWithTooltip {
+    TooltipAction {
   /** Provides extra visual weight and identifies the primary action in a set of buttons */
   primary?: boolean;
 }
@@ -231,20 +232,26 @@ function PrimaryActionMarkup({
   primaryAction: PrimaryAction | React.ReactNode;
 }) {
   const {isNavigationCollapsed} = useMediaQuery();
-  let content = primaryAction;
-  if (isInterface(primaryAction)) {
-    const primary =
-      primaryAction.primary === undefined ? true : primaryAction.primary;
 
-    content = buttonsFrom(
+  let actionMarkup = primaryAction;
+  if (isInterface(primaryAction)) {
+    const {primary: isPrimary, helpText} = primaryAction;
+    const primary = isPrimary === undefined ? true : isPrimary;
+    const content = buttonFrom(
       shouldShowIconOnly(isNavigationCollapsed, primaryAction),
       {
         primary,
       },
     );
+
+    actionMarkup = helpText ? (
+      <Tooltip content={helpText}>{content}</Tooltip>
+    ) : (
+      content
+    );
   }
 
-  return <div className={styles.PrimaryActionWrapper}>{content}</div>;
+  return <div className={styles.PrimaryActionWrapper}>{actionMarkup}</div>;
 }
 
 function shouldShowIconOnly(

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

@@ -8,6 +8,7 @@ import {Breadcrumbs} from '../../../../Breadcrumbs';
 import {Button} from '../../../../Button';
 import {ButtonGroup} from '../../../../ButtonGroup';
 import {Pagination} from '../../../../Pagination';
+import {Tooltip} from '../../../../Tooltip';
 import type {LinkAction, MenuActionDescriptor} from '../../../../../types';
 import {Header, HeaderProps} from '../Header';
 
@@ -106,6 +107,19 @@ describe('<Header />', () => {
 
       expect(header).toContainReactComponent(PrimaryAction);
     });
+
+    it('renders a <Tooltip /> when helpText is provided', () => {
+      const primaryAction = {
+        content: 'Save',
+        helpText: 'Helpful text',
+      };
+      const header = mountWithApp(
+        <Header {...mockProps} primaryAction={primaryAction} />,
+      );
+      expect(header).toContainReactComponent(Tooltip, {
+        content: primaryAction.helpText,
+      });
+    });
   });
 
   describe('pagination', () => {