Add tooltip to Page primary & secondary actions

Author: aminpaks

.changeset/famous-emus-learn.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Support tooltip for Page component's primary & secondary actions

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

@@ -2,11 +2,13 @@ import React, {useEffect, useRef} from 'react';
 
 import {classNames} from '../../../../utilities/css';
 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 {
+interface SecondaryAction extends ButtonProps, ActionWithTooltip {
   onAction?(): void;
   getOffsetWidth?(width: number): void;
 }
@@ -16,6 +18,7 @@ export function SecondaryAction({
   destructive,
   onAction,
   getOffsetWidth,
+  tooltip,
   ...rest
 }: SecondaryAction) {
   const secondaryActionsRef = useRef<HTMLSpanElement>(null);
@@ -26,6 +29,16 @@ export function SecondaryAction({
     getOffsetWidth(secondaryActionsRef.current?.offsetWidth);
   }, [getOffsetWidth]);
 
+  let button = (
+    <Button onClick={onAction} {...rest}>
+      {children}
+    </Button>
+  );
+
+  if (tooltip != null) {
+    button = tooltipFrom(tooltip, button);
+  }
+
   return (
     <span
       className={classNames(
@@ -34,9 +47,7 @@ export function SecondaryAction({
       )}
       ref={secondaryActionsRef}
     >
-      <Button onClick={onAction} {...rest}>
-        {children}
-      </Button>
+      {button}
     </span>
   );
 }

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

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

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

@@ -427,6 +427,31 @@ 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

@@ -10,12 +10,13 @@ import {
   ConditionalWrapper,
 } from '../../../../utilities/components';
 import type {
-  MenuGroupDescriptor,
-  MenuActionDescriptor,
+  ActionWithTooltip,
   DestructableAction,
   DisableableAction,
-  LoadableAction,
   IconableAction,
+  LoadableAction,
+  MenuActionDescriptor,
+  MenuGroupDescriptor,
 } from '../../../../types';
 import {Breadcrumbs, BreadcrumbsProps} from '../../../Breadcrumbs';
 import {Pagination, PaginationProps} from '../../../Pagination';
@@ -32,7 +33,8 @@ interface PrimaryAction
   extends DestructableAction,
     DisableableAction,
     LoadableAction,
-    IconableAction {
+    IconableAction,
+    ActionWithTooltip {
   /** Provides extra visual weight and identifies the primary action in a set of buttons */
   primary?: boolean;
 }

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

@@ -3,8 +3,10 @@ import {animationFrame} from '@shopify/jest-dom-mocks';
 import {mountWithApp} from 'tests/utilities';
 
 import type {ActionMenuProps} from '../../ActionMenu';
+import type {ActionTooltip} from '../../../types';
 import {Badge} from '../../Badge';
 import {Card} from '../../Card';
+import {Tooltip} from '../../Tooltip';
 import {Page, PageProps} from '../Page';
 import {Header} from '../components';
 
@@ -290,6 +292,39 @@ describe('<Page />', () => {
       expect(page).not.toContainReactComponent(Header);
     });
   });
+
+  describe('<Tooltip />', () => {
+    const saveTooltip: ActionTooltip = {
+      content: 'Save tooltip',
+      dismissOnMouseOut: true,
+    };
+
+    it('is rendered when available for primary action', () => {
+      const page = mountWithApp(
+        <Page
+          {...mockProps}
+          primaryAction={{content: 'Save', tooltip: saveTooltip}}
+        />,
+      );
+      expect(page).not.toContainReactComponent(
+        Tooltip,
+        expect.objectContaining(saveTooltip),
+      );
+    });
+
+    it('is rendered when available for secondary actions', () => {
+      const page = mountWithApp(
+        <Page
+          {...mockProps}
+          secondaryActions={[{content: 'Save', tooltip: saveTooltip.content}]}
+        />,
+      );
+      expect(page).not.toContainReactComponent(
+        Tooltip,
+        expect.objectContaining(saveTooltip),
+      );
+    });
+  });
 });
 
 function noop() {}

polaris-react/src/components/Tooltip/index.ts

@@ -1 +1,2 @@
+export * from './utils';
 export * from './Tooltip';

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

@@ -0,0 +1,22 @@
+import React from 'react';
+import type {ReactNode} from 'react';
+
+import type {ActionTooltip} from '../../types';
+import {isInterface} from '../../utilities/is-interface';
+
+import {Tooltip, TooltipProps} from './Tooltip';
+
+export function tooltipFrom(
+  tooltip: NonNullable<ReactNode> | ActionTooltip,
+  button: ReactNode,
+) {
+  const tooltipType = typeof tooltip;
+  const tooltipProps: TooltipProps =
+    tooltipType !== 'string' &&
+    tooltipType !== 'function' &&
+    isInterface(tooltip)
+      ? tooltip
+      : {content: tooltip};
+
+  return <Tooltip {...tooltipProps}>{button}</Tooltip>;
+}

polaris-react/src/types.ts

@@ -4,6 +4,8 @@ import type {AvatarProps} from './components/Avatar';
 import type {IconProps} from './components/Icon';
 // eslint-disable-next-line @shopify/strict-component-boundaries
 import type {ThumbnailProps} from './components/Thumbnail';
+// eslint-disable-next-line @shopify/strict-component-boundaries
+import type {TooltipProps} from './components/Tooltip';
 
 export interface OptionDescriptor {
   /** Value of the option */
@@ -155,6 +157,12 @@ export interface IconableAction extends Action {
   icon?: IconSource;
 }
 
+export type ActionTooltip = Omit<TooltipProps, 'children' | 'active'>;
+
+export interface ActionWithTooltip extends Action {
+  tooltip?: React.ReactNode | ActionTooltip;
+}
+
 export interface LoadableAction extends Action {
   /** Should a spinner be displayed */
   loading?: boolean;
@@ -212,6 +220,7 @@ export interface ComplexAction
     IconableAction,
     OutlineableAction,
     LoadableAction,
+    ActionWithTooltip,
     PlainAction {}
 
 export interface MenuActionDescriptor extends ComplexAction {