From f1db36b8f12a36dc9886c5e460979ca712610d07 Mon Sep 17 00:00:00 2001
From: Simon Cousineau <simon.cousineau99@gmail.com>
Date: Tue, 18 Dec 2018 09:50:30 -0500
Subject: [PATCH 1/4] Added helpText to ActionList items

---
 .../ActionList/components/Item/Item.tsx       | 13 +++++++++++-
 .../components/Item/tests/Item.test.tsx       |  6 ++++++
 .../ActionList/components/Section/Section.tsx |  3 ++-
 .../components/Section/tests/Section.test.tsx | 21 +++++++++++++++++++
 src/types.ts                                  |  2 ++
 5 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/components/ActionList/components/Item/Item.tsx b/src/components/ActionList/components/Item/Item.tsx
index 16740195916..93317bc986e 100644
--- a/src/components/ActionList/components/Item/Item.tsx
+++ b/src/components/ActionList/components/Item/Item.tsx
@@ -6,6 +6,7 @@ import Scrollable from '../../../Scrollable';
 import Icon from '../../../Icon';
 import UnstyledLink from '../../../UnstyledLink';
 import Badge from '../../../Badge';
+import TextStyle from '../../../TextStyle';
 
 import * as styles from '../../ActionList.scss';
 
@@ -15,6 +16,7 @@ export default function Item({
   id,
   badge,
   content,
+  helpText,
   url,
   onAction,
   icon,
@@ -51,7 +53,16 @@ export default function Item({
     );
   }
 
-  const contentMarkup = ellipsis && content ? `${content}…` : content;
+  const contentText = ellipsis && content ? `${content}…` : content;
+
+  const contentMarkup = helpText ? (
+    <div>
+      <div>{contentText}</div>
+      <TextStyle variation="subdued">{helpText}</TextStyle>
+    </div>
+  ) : (
+    contentText
+  );
 
   const badgeMarkup = badge && (
     <span className={styles.BadgeWrapper}>
diff --git a/src/components/ActionList/components/Item/tests/Item.test.tsx b/src/components/ActionList/components/Item/tests/Item.test.tsx
index ee331c6f097..843cf598786 100644
--- a/src/components/ActionList/components/Item/tests/Item.test.tsx
+++ b/src/components/ActionList/components/Item/tests/Item.test.tsx
@@ -2,6 +2,7 @@ import * as React from 'react';
 import {mountWithAppProvider} from 'test-utilities';
 import {UnstyledLink} from 'components';
 import Item from '../Item';
+import TextStyle from '../../../../TextStyle';
 
 describe('<Item />', () => {
   it('adds a style property when the image prop is present', () => {
@@ -36,4 +37,9 @@ describe('<Item />', () => {
     const item = mountWithAppProvider(<Item ellipsis />);
     expect(item.text()).toBe('');
   });
+
+  it('renders helpText when the helpText prop is defined', () => {
+    const item = mountWithAppProvider(<Item helpText="Foo" />);
+    expect(item.find(TextStyle).text()).toBe('Foo');
+  });
 });
diff --git a/src/components/ActionList/components/Section/Section.tsx b/src/components/ActionList/components/Section/Section.tsx
index f0e0e583354..754cc9e9ae4 100644
--- a/src/components/ActionList/components/Section/Section.tsx
+++ b/src/components/ActionList/components/Section/Section.tsx
@@ -32,11 +32,12 @@ export default function Section({
     };
   };
   const actionMarkup = section.items.map(
-    ({content, onAction, ...item}, index) => {
+    ({content, helpText, onAction, ...item}, index) => {
       return (
         <Item
           key={`${content}-${index}`}
           content={content}
+          helpText={helpText}
           role={actionRole}
           onAction={handleAction(onAction)}
           {...item}
diff --git a/src/components/ActionList/components/Section/tests/Section.test.tsx b/src/components/ActionList/components/Section/tests/Section.test.tsx
index 3f1e5765763..0fbad297010 100644
--- a/src/components/ActionList/components/Section/tests/Section.test.tsx
+++ b/src/components/ActionList/components/Section/tests/Section.test.tsx
@@ -76,6 +76,27 @@ describe('<Section />', () => {
     ).toBe('Import file');
   });
 
+  it('passes helpText to Item', () => {
+    const section = mountWithAppProvider(
+      <Section
+        hasMultipleSections
+        section={{
+          items: [
+            {content: 'Import file', helpText: 'Foo', onAction: noop},
+            {content: 'Export file', helpText: 'Bar', onAction: noop},
+          ],
+        }}
+      />,
+    );
+
+    expect(
+      section
+        .find(Item)
+        .first()
+        .prop('helpText'),
+    ).toBe('Foo');
+  });
+
   it('passes the onActionAnyItem callback to Item', () => {
     const spy = jest.fn();
     const section = mountWithAppProvider(
diff --git a/src/types.ts b/src/types.ts
index 562bf931293..cf8b92b3274 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -106,6 +106,8 @@ export interface ActionListItemDescriptor
     BadgeAction,
     DestructableAction,
     AppBridgeAction {
+  /** Help text */
+  helpText?: string;
   /** Image source */
   image?: string;
   /**  Add an ellipsis suffix to action content */

From e1f6c3d613cdb0bed95d280db8f11b89f48d818c Mon Sep 17 00:00:00 2001
From: Simon Cousineau <simon.cousineau99@gmail.com>
Date: Tue, 18 Dec 2018 10:03:15 -0500
Subject: [PATCH 2/4] Added UNRELEASED entry

---
 UNRELEASED.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/UNRELEASED.md b/UNRELEASED.md
index 3db95c0af31..960b025b5f2 100644
--- a/UNRELEASED.md
+++ b/UNRELEASED.md
@@ -7,6 +7,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 ### Enhancements
 
 - Moved icons to a separate npm package ([#686](https://github.com/Shopify/polaris-react/pull/686))
+- Added helpText prop to ActionList items ([#777](https://github.com/Shopify/polaris-react/pull/777))
 
 ### Bug fixes
 

From a6725f1014ebd91f75655fbad03e5caa6b6911b3 Mon Sep 17 00:00:00 2001
From: Simon Cousineau <simon.cousineau99@gmail.com>
Date: Tue, 18 Dec 2018 10:34:16 -0500
Subject: [PATCH 3/4] Changes according to PR feedback #777

---
 src/components/ActionList/README.md | 51 +++++++++++++++++++++++++++++
 src/types.ts                        |  2 +-
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/src/components/ActionList/README.md b/src/components/ActionList/README.md
index 90920b060fc..43382545850 100644
--- a/src/components/ActionList/README.md
+++ b/src/components/ActionList/README.md
@@ -269,6 +269,57 @@ class ActionListExample extends React.Component {
 }
 ```
 
+### Action list with help text
+
+Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant.
+
+```jsx
+class ActionListExample extends React.Component {
+  state = {
+    active: true,
+  };
+
+  togglePopover = () => {
+    this.setState(({active}) => {
+      return {active: !active};
+    });
+  };
+
+  render() {
+    const activator = (
+      <Button onClick={this.togglePopover}>More actions</Button>
+    );
+
+    return (
+      <div style={{height: '250px'}}>
+        <Popover
+          active={this.state.active}
+          activator={activator}
+          onClose={this.togglePopover}
+        >
+          <ActionList
+            sections={[
+              {
+                items: [
+                  {
+                    content: 'Blog posts',
+                    helpText: 'Manage your blog articles',
+                  },
+                  {
+                    content: 'Blogs',
+                    helpText: 'Manage blogs published to your Online Store',
+                  },
+                ],
+              },
+            ]}
+          />
+        </Popover>
+      </div>
+    );
+  }
+}
+```
+
 ---
 
 ## Related components
diff --git a/src/types.ts b/src/types.ts
index cf8b92b3274..01555928621 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -106,7 +106,7 @@ export interface ActionListItemDescriptor
     BadgeAction,
     DestructableAction,
     AppBridgeAction {
-  /** Help text */
+  /** Additional hint text to display with item */
   helpText?: string;
   /** Image source */
   image?: string;

From fc2f878789b437e29fb28b46777cfc95ad9350fe Mon Sep 17 00:00:00 2001
From: Tim Layton <tmlayton@users.noreply.github.com>
Date: Tue, 18 Dec 2018 13:12:59 -0500
Subject: [PATCH 4/4] Update UNRELEASED.md

Co-Authored-By: BlazingBBQ <simon.cousineau99@gmail.com>
---
 UNRELEASED.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/UNRELEASED.md b/UNRELEASED.md
index bdcf012b6bf..7a894b3042f 100644
--- a/UNRELEASED.md
+++ b/UNRELEASED.md
@@ -8,7 +8,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 
 - Moved icons to a separate npm package ([#686](https://github.com/Shopify/polaris-react/pull/686))
 - Added `oneHalf` and `oneThird` props to `Layout` component ([#724](https://github.com/Shopify/polaris-react/pull/724))
-- Added helpText prop to ActionList items ([#777](https://github.com/Shopify/polaris-react/pull/777))
+- Added `helpText` prop to ActionList items ([#777](https://github.com/Shopify/polaris-react/pull/777))
 
 ### Bug fixes