feat(button): Add trailing icon support via label element (#4159)

BREAKING CHANGE: We recommend placing each button's text label within a mdc-button__label element. This does not immediately break existing MDC Button usage, but updating is recommended to future-proof against potential upcoming changes.
material-components · Dec 12, 2018 · fa41579 · fa41579
1 parent 2d35220
commit fa41579
Show file tree

Hide file tree

Showing 44 changed files with 1,111 additions and 253 deletions.
diff --git a/packages/mdc-button/README.md b/packages/mdc-button/README.md
@@ -41,7 +41,7 @@ npm install @material/button
 
 ```html
 <button class="mdc-button">
-  Button
+  <span class="mdc-button__label">Button</span>
 </button>
 ```
 
@@ -92,7 +92,7 @@ To add an icon, add an element with the `mdc-button__icon` class inside the butt
 ```html
 <button class="mdc-button">
   <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
-  Button
+  <span class="mdc-button__label">Button</span>
 </button>
 ```
 
@@ -103,18 +103,32 @@ It's also possible to use an SVG icon:
   <svg class="mdc-button__icon" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="...">
   ...
   </svg>
-  Button
+  <span class="mdc-button__label">Button</span>
 </button>
 ```
 
+#### Trailing Icon
+
+Certain icons make more sense to appear after the button's text label rather than before. This can be accomplished by
+putting the icon markup _after_ the `mdc-button__label` element.
+
+```html
+<button class="mdc-button">
+  <span class="mdc-button__label">Button</span>
+  <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
+</button>
+```
+
+> _NOTE_: The `mdc-button__label` element is _required_ in order for the trailing icon to be styled appropriately.
+
 ### Disabled
 
 To disable a button, add the `disabled` attribute directly to the `<button>`, or set the `disabled` attribute on the `<fieldset>` containing the button.
 Disabled buttons cannot be interacted with and have no visual interaction effect.
 
 ```html
 <button class="mdc-button" disabled>
-  Button
+  <span class="mdc-button__label">Button</span>
 </button>
 ```
 
@@ -129,7 +143,14 @@ CSS Class | Description
 `mdc-button--unelevated` | Optional. Styles a contained button that is flush with the surface.
 `mdc-button--outlined` | Optional. Styles an outlined button that is flush with the surface.
 `mdc-button--dense` | Optional. Makes the button text and container slightly smaller.
-`mdc-button__icon` | Optional. Indicates an icon element.
+`mdc-button__label` | Recommended.\* Indicates the element containing the button's text label.
+`mdc-button__icon` | Optional. Indicates the element containing the button's icon.
+
+> \*_NOTE_: The `mdc-button__label` element is required for buttons with a trailing icon, but it is currently optional for
+> buttons with no icon or a leading icon. In the latter cases, it is acceptable for the text label to simply exist
+> directly within the `mdc-button` element.
+> However, the `mdc-button__label` class may become mandatory for all cases in the future, so it is recommended to
+> always include it to be future-proof.
 
 ### Sass Mixins
 

diff --git a/packages/mdc-button/_mixins.scss b/packages/mdc-button/_mixins.scss
@@ -147,6 +147,10 @@
   vertical-align: top;
 }
 
+@mixin mdc-button__icon-trailing_ {
+  @include mdc-rtl-reflexive-box(margin, left, 8px);
+}
+
 @mixin mdc-button__icon-svg_ {
   fill: currentColor;
 }
@@ -155,6 +159,10 @@
   @include mdc-rtl-reflexive-property(margin, -4px, 8px);
 }
 
+@mixin mdc-button__icon-contained-trailing_ {
+  @include mdc-rtl-reflexive-property(margin, 8px, -4px);
+}
+
 @mixin mdc-button--outlined_() {
   border-style: solid;
 

diff --git a/packages/mdc-button/mdc-button.scss b/packages/mdc-button/mdc-button.scss
@@ -40,11 +40,15 @@
   .mdc-button__icon {
     @include mdc-button__icon_;
   }
+}
 
-  // stylelint-disable-next-line selector-no-qualifying-type
-  svg.mdc-button__icon {
-    @include mdc-button__icon-svg_;
-  }
+.mdc-button__label + .mdc-button__icon {
+  @include mdc-button__icon-trailing_;
+}
+
+// stylelint-disable-next-line selector-no-qualifying-type
+svg.mdc-button__icon {
+  @include mdc-button__icon-svg_;
 }
 
 .mdc-button--raised,
@@ -54,6 +58,10 @@
     // Icons inside contained buttons have different styles due to increased button padding
     @include mdc-button__icon-contained_;
   }
+
+  .mdc-button__label + .mdc-button__icon {
+    @include mdc-button__icon-contained-trailing_;
+  }
 }
 
 .mdc-button--raised,

diff --git a/packages/mdc-card/README.md b/packages/mdc-card/README.md
@@ -57,8 +57,12 @@ Fully-featured:
   <!-- ... content ... -->
   <div class="mdc-card__actions">
     <div class="mdc-card__action-buttons">
-      <button class="mdc-button mdc-card__action mdc-card__action--button">Action 1</button>
-      <button class="mdc-button mdc-card__action mdc-card__action--button">Action 2</button>
+      <button class="mdc-button mdc-card__action mdc-card__action--button">
+        <span class="mdc-button__label">Action 1</span>
+      </button>
+      <button class="mdc-button mdc-card__action mdc-card__action--button">
+        <span class="mdc-button__label">Action 2</span>
+      </button>
     </div>
     <div class="mdc-card__action-icons">
       <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="Share">share</button>
@@ -123,8 +127,12 @@ and the [optional modifier classes](#css-classes).
 
 ```html
 <div class="mdc-card__actions">
-  <button class="mdc-button mdc-card__action mdc-card__action--button">Action 1</button>
-  <button class="mdc-button mdc-card__action mdc-card__action--button">Action 2</button>
+  <button class="mdc-button mdc-card__action mdc-card__action--button">
+    <span class="mdc-button__label">Action 1</span>
+  </button>
+  <button class="mdc-button mdc-card__action mdc-card__action--button">
+    <span class="mdc-button__label">Action 2</span>
+  </button>
 </div>
 ```
 
@@ -153,7 +161,7 @@ To have a single action button take up the entire width of the action row, use t
 ```html
 <div class="mdc-card__actions mdc-card__actions--full-bleed">
   <a class="mdc-button mdc-card__action mdc-card__action--button" href="#">
-    All Business Headlines
+    <span class="mdc-button__label">All Business Headlines</span>
     <i class="material-icons" aria-hidden="true">arrow_forward</i>
   </a>
 </div>
@@ -165,8 +173,12 @@ elements:
 ```html
 <div class="mdc-card__actions">
   <div class="mdc-card__action-buttons">
-    <button class="mdc-button mdc-card__action mdc-card__action--button">Read</button>
-    <button class="mdc-button mdc-card__action mdc-card__action--button">Bookmark</button>
+    <button class="mdc-button mdc-card__action mdc-card__action--button">
+      <span class="mdc-button__label">Read</span>
+    </button>
+    <button class="mdc-button mdc-card__action mdc-card__action--button">
+      <span class="mdc-button__label">Bookmark</span>
+    </button>
   </div>
   <div class="mdc-card__action-icons">
    <button class="material-icons mdc-icon-button mdc-card__action mdc-card__action--icon" title="Share">share</button>

diff --git a/packages/mdc-dialog/README.md b/packages/mdc-dialog/README.md
@@ -55,8 +55,12 @@ npm install @material/dialog
         Dialog body text goes here.
       </div>
       <footer class="mdc-dialog__actions">
-        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="no">No</button>
-        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="yes">Yes</button>
+        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="no">
+          <span class="mdc-button__label">No</span>
+        </button>
+        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="yes">
+          <span class="mdc-button__label">Yes</span>
+        </button>
       </footer>
     </div>
   </div>
@@ -177,8 +181,12 @@ radio buttons (indicating single selection) or checkboxes (indicating multiple s
         </ul>
       </div>
       <footer class="mdc-dialog__actions">
-        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="close">Cancel</button>
-        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="accept">OK</button>
+        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="close">
+          <span class="mdc-button__label">Cancel</span>
+        </button>
+        <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="accept">
+          <span class="mdc-button__label">OK</span>
+        </button>
       </footer>
     </div>
   </div>
@@ -245,8 +253,12 @@ For example:
 ```html
 ...
 <footer class="mdc-dialog__actions">
-  <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="close">Cancel</button>
-  <button type="button" class="mdc-button mdc-dialog__button mdc-dialog__button--default" data-mdc-dialog-action="accept">OK</button>
+  <button type="button" class="mdc-button mdc-dialog__button" data-mdc-dialog-action="close">
+    <span class="mdc-button__label">Cancel</span>
+  </button>
+  <button type="button" class="mdc-button mdc-dialog__button mdc-dialog__button--default" data-mdc-dialog-action="accept">
+    <span class="mdc-button__label">OK</span>
+  </button>
 </footer>
 ...
 ```