[Button] Improve the disclosure API for button, allowing user to specify the direction the disclosure icon faces

UNRELEASED.md

@@ -12,7 +12,8 @@
 - Prevented scrolling to `Popover` content in development ([#2403](https://github.com/Shopify/polaris-react/pull/2403))
 - Fixed an issue which caused HSL colors to not display in Edge ([#2418](https://github.com/Shopify/polaris-react/pull/2418))
 - Fixed an issue where the dropzone component jumped from an extra-large layout to a layout based on the width of its container ([#2412](https://github.com/Shopify/polaris-react/pull/2412))
-- Fixed an issue which caused HSL colors to not display in Edge ((#2418)[https://github.com/Shopify/polaris-react/pull/2418])
+- Fixed an issue which caused HSL colors to not display in Edge ([#2418](https://github.com/Shopify/polaris-react/pull/2418))
+- Changed Button's `disclosure` prop to be `boolean | "up" | "down"`, allowing greater control over the direction the disclosure caret faces ([#2431](https://github.com/Shopify/polaris-react/pull/2431))
 - Fixed an issue where the dropzone component jumped from an extra-large layout to a layout based on the width of it's container ([#2412](https://github.com/Shopify/polaris-react/pull/2412))
 - Fixed a race condition in DatePicker ([#2373](https://github.com/Shopify/polaris-react/pull/2373))
 

src/components/Button/Button.scss

@@ -592,3 +592,13 @@ $partial-button-filled-pressed-box-shadow: inset 0 0 0 0 transparent,
   }
 }
 // stylelint-enable selector-max-specificity
+
+.DisclosureIcon {
+  transition-property: transform;
+  transition-duration: duration(slow);
+  transition-timing-function: easing(out);
+}
+
+.DisclosureIconFacingUp {
+  transform: rotate(-180deg);
+}

src/components/Button/Button.tsx

@@ -44,8 +44,8 @@ export interface ButtonProps {
   pressed?: boolean;
   /** Allows the button to grow to the width of its container */
   fullWidth?: boolean;
-  /** Displays the button with a disclosure icon */
-  disclosure?: boolean;
+  /** Displays the button with a disclosure icon. Defaults to `down` when set to true */
+  disclosure?: 'down' | 'up' | boolean;
   /** Allows the button to submit a form */
   submit?: boolean;
   /** Renders a button that looks like a link */
@@ -154,9 +154,20 @@ export function Button({
     icon && children == null && styles.iconOnly,
   );
 
+  const disclosureIcon = (
+    <Icon source={loading ? 'placeholder' : CaretDownMinor} />
+  );
+
   const disclosureIconMarkup = disclosure ? (
     <IconWrapper>
-      <Icon source={loading ? 'placeholder' : CaretDownMinor} />
+      <div
+        className={classNames(
+          styles.DisclosureIcon,
+          disclosure === 'up' && styles.DisclosureIconFacingUp,
+        )}
+      >
+        {disclosureIcon}
+      </div>
     </IconWrapper>
   ) : null;
 

src/components/Button/README.md

@@ -290,6 +290,30 @@ function PressedButton() {
 }
 ```
 
+### Button with disclosure
+
+<!-- example-for: web -->
+
+Use to denote something that can be progressively disclosed to the user on click.
+
+```jsx
+function DisclosureButtion() {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <Button
+      plain
+      disclosure={expanded ? 'up' : 'down'}
+      onClick={() => {
+        setExpanded(!expanded);
+      }}
+    >
+      {expanded ? 'Show less' : 'Show more'}
+    </Button>
+  );
+}
+```
+
 ### Disabled state
 
 Use for actions that aren’t currently available. The surrounding interface should make it clear why the button is disabled and what needs to be done to enable it.

src/components/Button/tests/Button.test.tsx

@@ -370,6 +370,26 @@ describe('<Button />', () => {
     });
   });
 
+  describe('disclosure', () => {
+    it('assumes "down" if set to true', () => {
+      const button = mountWithAppProvider(<Button disclosure />);
+      const disclosureIcon = button.find('.DisclosureIcon');
+      expect(disclosureIcon!.hasClass('DisclosureIconFacingUp')).toBe(false);
+    });
+
+    it('is facing down if set to "down"', () => {
+      const button = mountWithAppProvider(<Button disclosure="down" />);
+      const disclosureIcon = button.find('.DisclosureIcon');
+      expect(disclosureIcon!.hasClass('DisclosureIconFacingUp')).toBe(false);
+    });
+
+    it('is facing up if set to "up"', () => {
+      const button = mountWithAppProvider(<Button disclosure="up" />);
+      const disclosureIcon = button.find('.DisclosureIcon');
+      expect(disclosureIcon!.hasClass('DisclosureIconFacingUp')).toBe(true);
+    });
+  });
+
   describe('deprecations', () => {
     it('warns the ariaPressed prop has been replaced', () => {
       const warningSpy = jest