fix(button): support for wrapping text (#2248)

* fix(button): restore ability for button text to wrap

Remove the CSS that prevents the text in the button from wrapping.

The guidelines for the component say "When the button text is too long
for the horizontal space available, it wraps to form another line."

* docs(button): add wrapping text story

Add "Wrapping" story that demonstrates a button with long text that
wraps to the next line. Some template adjustments and additional args
added to allow for this.

* fix(button)!: icon alignment when text is wrapping

BREAKING CHANGE: changes vertical flex alignment to start.

Previously when the button had an icon and the text was wrapping, the
icon was vertically aligned center and the text was aligned center.

This fixes this to match with the design spec: for the version of the
button that uses a workflow icon, the icon should stay aligned to the
top, and the text should be aligned left (start). This uses the defined
token for the space between the top of the component and the workflow
icon (--spectrum-component-top-to-workflow-icon-*).

* docs(button): rename storybook control to layout

Rename Storybook control for stacking buttons to "layout" with specified
options, which is a more appropriate name. The control has also been
made visible.

* fix(button): support any existing use of ui icons

Support any existing use of ui icons with the updated wrapping behavior.
And add Chromatic only testing of them to the Wrapping story.

Workflow icons are intended, with the use of the
spectrum-component-top-to-workflow-icon tokens, but UI icons have not
yet been specifically excluded in guidelines and are currently in use
within SplitButton in this library. This keeps UI icons that are
smaller than the intended workflow icon, better vertically centered
with the text within the button.

* feat(button): mod property for icon margin top

Add a mod property to make it easy to modify the margin-block-start of
the icon, in case of alignment issues with icons that are not the
intended workflow sizes.

Author: jawinn

components/button/index.css

@@ -23,9 +23,9 @@ governing permissions and limitations under the License.
   --spectrum-button-focus-ring-border-radius: calc(var(--spectrum-button-border-radius) + var(--spectrum-button-focus-ring-gap));
   --spectrum-button-focus-ring-thickness: var(--spectrum-focus-indicator-thickness);
   --spectrum-button-focus-indicator-color: var(--spectrum-focus-indicator-color);
+  --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-50);
 }
 
-
 .spectrum-Button--sizeS {
   --spectrum-button-min-width: calc(var(--spectrum-component-height-75) * var(--spectrum-button-minimum-width-multiplier));
 
@@ -40,6 +40,8 @@ governing permissions and limitations under the License.
   --spectrum-button-padding-label-to-icon: var(--spectrum-text-to-visual-75);
   --spectrum-button-top-to-text: var(--spectrum-button-top-to-text-small);
   --spectrum-button-bottom-to-text: var(--spectrum-button-bottom-to-text-small);
+  --spectrum-button-top-to-icon: var(--spectrum-component-top-to-workflow-icon-75);
+  --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-75);
 }
 
 .spectrum-Button--sizeM {
@@ -56,6 +58,8 @@ governing permissions and limitations under the License.
   --spectrum-button-padding-label-to-icon: var(--spectrum-text-to-visual-100);
   --spectrum-button-top-to-text: var(--spectrum-button-top-to-text-medium);
   --spectrum-button-bottom-to-text: var(--spectrum-button-bottom-to-text-medium);
+  --spectrum-button-top-to-icon: var(--spectrum-component-top-to-workflow-icon-100);
+  --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-100);
 
   &[pending],
   &.is-pending {
@@ -77,7 +81,8 @@ governing permissions and limitations under the License.
   --spectrum-button-padding-label-to-icon: var(--spectrum-text-to-visual-200);
   --spectrum-button-top-to-text: var(--spectrum-button-top-to-text-large);
   --spectrum-button-bottom-to-text: var(--spectrum-button-bottom-to-text-large);
-
+  --spectrum-button-top-to-icon: var(--spectrum-component-top-to-workflow-icon-200);
+  --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-200);
 
   &[pending],
   &.is-pending {
@@ -99,6 +104,8 @@ governing permissions and limitations under the License.
   --spectrum-button-padding-label-to-icon: var(--spectrum-text-to-visual-300);
   --spectrum-button-top-to-text: var(--spectrum-button-top-to-text-extra-large);
   --spectrum-button-bottom-to-text: var(--spectrum-button-bottom-to-text-extra-large);
+  --spectrum-button-top-to-icon: var(--spectrum-component-top-to-workflow-icon-300);
+  --spectrum-button-intended-icon-size: var(--spectrum-workflow-icon-size-300);
 
   .spectrum--medium &[pending],
   .spectrum--medium &.is-pending {
@@ -141,11 +148,28 @@ governing permissions and limitations under the License.
   }
 
   .spectrum-Icon {
+    /* Any block-size difference between the intended workflow icon size and actual icon used.
+       Helps support any existing use of smaller UI icons instead of intended Workflow icons. */
+    --_icon-size-difference: max(0px,
+      var(--spectrum-button-intended-icon-size) - 
+      var(--spectrum-icon-block-size, var(--spectrum-button-intended-icon-size))
+    );
+
+    margin-block-start: var(--mod-button-icon-margin-block-start,
+      max(0px,
+        var(--mod-button-top-to-icon, var(--spectrum-button-top-to-icon)) - 
+        var(--mod-button-border-width, var(--spectrum-button-border-width)) +
+        (var(--_icon-size-difference, 0px) / 2)
+      )
+    );
+
     margin-inline-start: calc(
       var(--mod-button-edge-to-visual, var(--spectrum-button-edge-to-visual)) -
       var(--mod-button-edge-to-text, var(--spectrum-button-edge-to-text))
     );
     color: inherit;
+    flex-shrink: 0;
+    align-self: flex-start;
   }
 
   /* correct focus indicator radius for t-shirt sizing */
@@ -159,7 +183,9 @@ governing permissions and limitations under the License.
     border-radius: 50%;
 
     .spectrum-Icon {
+      align-self: center;
       margin-inline-start: 0;
+      margin-block-start: 0;
     }
 
     &::after {
@@ -176,9 +202,13 @@ a.spectrum-Button {
   @extend %spectrum-ButtonLabel;
   padding-block-start: calc(var(--mod-button-top-to-text, var(--spectrum-button-top-to-text)) - var(--mod-button-border-width, var(--spectrum-button-border-width)));
   padding-block-end: calc(var(--mod-button-bottom-to-text, var(--spectrum-button-bottom-to-text)) - var(--mod-button-border-width, var(--spectrum-button-border-width)));
-  white-space: nowrap;
   line-height: var(--mod-button-line-height, var(--spectrum-button-line-height));
   align-self: start;
+  text-align: var(--mod-button-text-align, center);
+}
+
+.spectrum-Button .spectrum-Icon + .spectrum-Button-label {
+  text-align: var(--mod-button-text-align-with-icon, start);
 }
 
 .spectrum-Button {
@@ -190,26 +220,22 @@ a.spectrum-Button {
   }
 }
 
-/* special cases for focus-ring */
+/* Special cases for focus indicator */
 .spectrum-Button {
   transition: border-color var(--mod-button-animation-duration, var(--spectrum-button-animation-duration)) ease-in-out;
 
   &::after {
     position: absolute;
     inset: 0;
-
     margin: calc((var(--mod-button-focus-ring-gap, var(--spectrum-button-focus-ring-gap)) + var(--mod-button-border-width, var(--spectrum-button-border-width))) * -1);
-
     border-radius: var(--mod-button-focus-ring-border-radius, var(--spectrum-button-focus-ring-border-radius));
-
     transition: box-shadow var(--mod-button-animation-duration, var(--spectrum-button-animation-duration)) ease-in-out;
-
     pointer-events: none;
     content: '';
   }
 
   &:focus-visible {
-    /* kill the default ring */
+    /* Remove the default focus outline */
     box-shadow: none;
     outline: none;
 
@@ -222,7 +248,6 @@ a.spectrum-Button {
 
 /* Core Token Theming */
 /* former skin.css, applied / copied from actionbutton/index.css  */
-
 .spectrum-Button {
   @extend %spectrum-BaseButton;
 
@@ -268,7 +293,16 @@ a.spectrum-Button {
   }
 }
 
-/* windows high contrast mode over-writes for accent variant */
+/* Static color variants */
+.spectrum-Button--staticWhite {
+  --spectrum-button-focus-indicator-color: var(--mod-static-black-focus-indicator-color, var(--spectrum-static-black-focus-indicator-color));
+}
+
+.spectrum-Button--staticBlack {
+  --spectrum-button-focus-indicator-color: var(--mod-static-black-focus-indicator-color, var(--spectrum-static-black-focus-indicator-color));
+}
+
+/* Windows High Contrast Mode */
 @media (forced-colors: active) {
   .spectrum-Button {
     --highcontrast-button-content-color-disabled: GrayText;
@@ -302,12 +336,3 @@ a.spectrum-Button {
     }
   }
 }
-
-/* static variants */
-.spectrum-Button--staticWhite {
-  --spectrum-button-focus-indicator-color: var(--mod-static-black-focus-indicator-color, var(--spectrum-static-black-focus-indicator-color));
-}
-
-.spectrum-Button--staticBlack {
-  --spectrum-button-focus-indicator-color: var(--mod-static-black-focus-indicator-color, var(--spectrum-static-black-focus-indicator-color));
-}

components/button/metadata/mods.md

@@ -32,13 +32,17 @@
 | `--mod-button-font-family`                 |
 | `--mod-button-font-size`                   |
 | `--mod-button-height`                      |
+| `--mod-button-icon-margin-block-start`     |
 | `--mod-button-line-height`                 |
 | `--mod-button-margin-block`                |
 | `--mod-button-margin-left`                 |
 | `--mod-button-margin-right`                |
 | `--mod-button-min-width`                   |
 | `--mod-button-padding-label-to-icon`       |
 | `--mod-button-static-content-color`        |
+| `--mod-button-text-align`                  |
+| `--mod-button-text-align-with-icon`        |
+| `--mod-button-top-to-icon`                 |
 | `--mod-button-top-to-text`                 |
 | `--mod-focus-indicator-gap`                |
 | `--mod-line-height-100`                    |

components/button/package.json

@@ -15,7 +15,7 @@
   },
   "main": "dist/index-vars.css",
   "peerDependencies": {
-    "@spectrum-css/icon": ">=4",
+    "@spectrum-css/icon": ">=6",
     "@spectrum-css/progresscircle": ">=2",
     "@spectrum-css/tokens": ">=13"
   },