doc(material/button): improve button docs & examples (angular#26170)

* docs(material/button): improve button docs & examples - Remove stale README that describes the component as experimental - Add docs describing the extended fab variant - Add aria-labels to button examples that don't have text - Remove "basic" color fabs from example, since fab doesn't support an un-colored style (It probably should as its shown in the spec, but that's outside the scope of this docs fix). - Add extended fab row to example * fixup! docs(material/button): improve button docs & examples
wagnermaciel · Dec 9, 2022 · c240946 · c240946
1 parent 769ea45
commit c240946
Show file tree

Hide file tree

Showing 6 changed files with 85 additions and 101 deletions.
diff --git a/src/components-examples/material/button/BUILD.bazel b/src/components-examples/material/button/BUILD.bazel
@@ -19,6 +19,7 @@ ng_module(
         "//src/material/button/testing",
         "//src/material/divider",
         "//src/material/icon",
+        "//src/material/tooltip",
         "@npm//@angular/platform-browser",
         "@npm//@angular/platform-browser-dynamic",
         "@npm//@types/jasmine",

diff --git a/src/components-examples/material/button/button-types/button-types-example.css b/src/components-examples/material/button/button-types/button-types-example.css
@@ -2,3 +2,7 @@
 .example-button-row a {
   margin-right: 8px;
 }
+
+.example-disabled {
+  display: inline-block;
+}
diff --git a/src/components-examples/material/button/button-types/button-types-example.html b/src/components-examples/material/button/button-types/button-types-example.html
@@ -40,45 +40,90 @@ <h3>Flat Buttons</h3>
 
 <h3>Icon Buttons</h3>
 <div class="example-button-row">
-  <button mat-icon-button aria-label="Example icon-button with a heart icon">
+  <button mat-icon-button matTooltip="Basic" aria-label="Example icon-button with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <button mat-icon-button color="primary" aria-label="Example icon-button with a heart icon">
+  <button mat-icon-button matTooltip="Primary" color="primary" aria-label="Example icon-button with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <button mat-icon-button color="accent" aria-label="Example icon-button with a heart icon">
+  <button mat-icon-button matTooltip="Accent" color="accent" aria-label="Example icon-button with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <button mat-icon-button color="warn" aria-label="Example icon-button with a heart icon">
+  <button mat-icon-button matTooltip="Warn" color="warn" aria-label="Example icon-button with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <button mat-icon-button disabled aria-label="Example icon-button with a heart icon">
+  <div matTooltip="Disabled" class="example-disabled">
+    <button mat-icon-button disabled aria-label="Example icon-button with a heart icon">
+      <mat-icon>favorite</mat-icon>
+    </button>
+  </div>
+  <a mat-icon-button matTooltip="Lik" routerLink="." aria-label="Example icon-button with a heart icon">
     <mat-icon>favorite</mat-icon>
-  </button>
+  </a>
 </div>
 
 <h3>Fab Buttons</h3>
 <div class="example-button-row">
-  <button mat-fab>Basic</button>
-  <button mat-fab color="primary">Primary</button>
-  <button mat-fab color="accent">Accent</button>
-  <button mat-fab color="warn">Warn</button>
-  <button mat-fab disabled>Disabled</button>
-  <button mat-fab aria-label="Example icon-button with a heart icon">
+  <button mat-fab matTooltip="Primary" color="primary" aria-label="Example fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </button>
+  <button mat-fab matTooltip="Accent" color="accent" aria-label="Example fab with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <a mat-fab routerLink=".">Link</a>
+  <button mat-fab matTooltip="Warn" color="warn" aria-label="Example fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </button>
+  <div matTooltip="Disabled" class="example-disabled">
+    <button mat-fab disabled aria-label="Example fab with a heart icon">
+      <mat-icon>favorite</mat-icon>
+    </button>
+  </div>
+  <a mat-fab matTooltip="Link" routerLink="." aria-label="Example fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </a>
 </div>
 
 <h3>Mini Fab Buttons</h3>
 <div class="example-button-row">
-  <button mat-mini-fab>Basic</button>
-  <button mat-mini-fab color="primary">Primary</button>
-  <button mat-mini-fab color="accent">Accent</button>
-  <button mat-mini-fab color="warn">Warn</button>
-  <button mat-mini-fab disabled>Disabled</button>
-  <button mat-mini-fab aria-label="Example icon-button with a heart icon">
+  <button mat-mini-fab matTooltip="Primary" color="primary" aria-label="Example mini fab with a heart icon">
     <mat-icon>favorite</mat-icon>
   </button>
-  <a mat-mini-fab routerLink=".">Link</a>
+  <button mat-mini-fab matTooltip="Accent" color="accent" aria-label="Example mini fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </button>
+  <button mat-mini-fab matTooltip="Warn" color="warn" aria-label="Example mini fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </button>
+  <div matTooltip="Disabled" class="example-disabled">
+    <button mat-mini-fab disabled aria-label="Example mini fab with a heart icon">
+      <mat-icon>favorite</mat-icon>
+    </button>
+  </div>
+  <a mat-mini-fab matTooltip="Link" routerLink="." aria-label="Example mini fab with a heart icon">
+    <mat-icon>favorite</mat-icon>
+  </a>
+</div>
+
+<h3>Extended Fab</h3>
+<div class="example-button-row">
+  <button mat-fab extended color="primary">
+    <mat-icon>favorite</mat-icon>
+    Primary
+  </button>
+  <button mat-fab extended color="accent">
+    <mat-icon>favorite</mat-icon>
+    Accent
+  </button>
+  <button mat-fab extended color="warn">
+    <mat-icon>favorite</mat-icon>
+    Warn
+  </button>
+  <button mat-fab extended disabled>
+    <mat-icon>favorite</mat-icon>
+    Disabled
+  </button>
+  <a mat-fab extended routerLink=".">
+    <mat-icon>favorite</mat-icon>
+    Link
+  </a>
 </div>
diff --git a/src/components-examples/material/button/index.ts b/src/components-examples/material/button/index.ts
@@ -2,6 +2,7 @@ import {NgModule} from '@angular/core';
 import {MatButtonModule} from '@angular/material/button';
 import {MatDividerModule} from '@angular/material/divider';
 import {MatIconModule} from '@angular/material/icon';
+import {MatTooltipModule} from '@angular/material/tooltip';
 import {ButtonOverviewExample} from './button-overview/button-overview-example';
 import {ButtonTypesExample} from './button-types/button-types-example';
 import {ButtonHarnessExample} from './button-harness/button-harness-example';
@@ -11,7 +12,7 @@ export {ButtonOverviewExample, ButtonTypesExample, ButtonHarnessExample};
 const EXAMPLES = [ButtonOverviewExample, ButtonTypesExample, ButtonHarnessExample];
 
 @NgModule({
-  imports: [MatButtonModule, MatDividerModule, MatIconModule],
+  imports: [MatButtonModule, MatDividerModule, MatIconModule, MatTooltipModule],
   declarations: EXAMPLES,
   exports: EXAMPLES,
 })

diff --git a/src/material/button/README.md b/src/material/button/README.md
diff --git a/src/material/button/button.md b/src/material/button/button.md
@@ -32,6 +32,19 @@ certain locales. It is also worth noting that using ALL CAPS in the text itself
 screen-readers, which will read the text character-by-character. We leave the decision of how to
 approach this to the consuming app.
 
+### Extended fab buttons
+Traditional fab buttons are circular and only have space for a single icon. However, you can add the
+`extended` attribute to allow the fab to expand into a rounded rectangle shape with space for a text
+label in addition to the icon. Only full sized fabs support the `extended` attribute, mini fabs do
+not.
+
+```html
+<button mat-fab extended>
+  <mat-icon>home</mat-icon>
+  Home
+</button>
+```
+
 ### Accessibility
 Angular Material uses native `<button>` and `<a>` elements to ensure an accessible experience by
 default. A `<button>` element should be used for any interaction that _performs an action on the