feat(material/button): add expanded option for extended FAB

Adds the `expanded` input to the extended FAB component, allowing developers to collapse the extended FAB down to a regular circular shape while hiding the text label via animations. By default, `expanded` is `true`.

Author: jexjws

MODULE.bazel.lock

@@ -67,14 +67,17 @@ export type MatFabAnchor = MatFabButton;
 // @public
 export class MatFabButton extends MatButtonBase {
     constructor(...args: unknown[]);
+    expanded: boolean;
     // (undocumented)
     extended: boolean;
     // (undocumented)
     _isFab: boolean;
     // (undocumented)
+    static ngAcceptInputType_expanded: unknown;
+    // (undocumented)
     static ngAcceptInputType_extended: unknown;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatFabButton, "button[mat-fab], a[mat-fab], button[matFab], a[matFab]", ["matButton", "matAnchor"], { "extended": { "alias": "extended"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]", "[progressIndicator]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatFabButton, "button[mat-fab], a[mat-fab], button[matFab], a[matFab]", ["matButton", "matAnchor"], { "extended": { "alias": "extended"; "required": false; }; "expanded": { "alias": "expanded"; "required": false; }; }, {}, never, [".material-icons:not([iconPositionEnd]), mat-icon:not([iconPositionEnd]), [matButtonIcon]:not([iconPositionEnd])", "*", ".material-icons[iconPositionEnd], mat-icon[iconPositionEnd], [matButtonIcon][iconPositionEnd]", "[progressIndicator]"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatFabButton, never>;
 }

goldens/material/button/index.api.md

@@ -16,6 +16,10 @@ <h4 class="demo-section-header">Buttons</h4>
       Search
       <mat-icon iconPositionEnd>check</mat-icon>
     </button>
+    <button matFab extended [expanded]="false">
+      <mat-icon>search</mat-icon>
+      Collapsed
+    </button>
   </section>
   <section>
     @for (appearance of appearances; track $index) {
@@ -135,6 +139,10 @@ <h4 class="demo-section-header">Anchors</h4>
       Search
       <mat-icon iconPositionEnd>check</mat-icon>
     </a>
+    <a href="//www.google.com" matFab extended [expanded]="false">
+      <mat-icon>search</mat-icon>
+      Collapsed
+    </a>
   </section>
   <section>
     <a
@@ -340,6 +348,21 @@ <h4 class="demo-section-header">FABs</h4>
     </button>
   </section>
 
+  <h4 class="demo-section-header">Extended FABs</h4>
+  <section>
+       <p>
+        <mat-checkbox [(ngModel)]="extendFABExpanded">Expanded</mat-checkbox>
+      </p>
+    <button matFab extended [expanded]="extendFABExpanded">
+      <mat-icon>edit</mat-icon>
+      Compose
+    </button>
+    <button matFab extended [expanded]="extendFABExpanded" color="primary">
+      <mat-icon>edit</mat-icon>
+      long long long text
+    </button>
+  </section>
+
   <h4 class="demo-section-header">Mini FABs</h4>
   <section>
     <button matMiniFab>

src/dev-app/button/button-demo.html

@@ -50,6 +50,7 @@ export class ButtonDemo {
   showProgress = false;
   clickCounter = 0;
   toggleDisable = false;
+  extendFABExpanded = true;
   tooltipText = 'This is a button tooltip!';
   disabledInteractive = false;
   appearances: MatButtonAppearance[] = ['text', 'elevated', 'outlined', 'filled', 'tonal'];

src/dev-app/button/button-demo.ts

@@ -43,6 +43,15 @@ the `extended` attribute, mini FABs do not.
 </button>
 ```
 
+You can dynamically expand or collapse the extended FAB using the `expanded` input. When `expanded` is set to `false`, the text label is hidden and the extended FAB transitions visually to a circular shape, maintaining the current component structure but occupying less screen estate. By default, `expanded` is unconditionally `true` for all extended FABs.
+
+```html
+<button matFab extended [expanded]="isFabExpanded">
+  <mat-icon>edit</mat-icon>
+  Compose
+</button>
+```
+
 ### Icon positioning
 
 Buttons can contain icons alongside text. By default, icons (`mat-icon`, `.material-icons`, or

src/material/button/button.md

@@ -197,6 +197,41 @@ describe('MatButton', () => {
       fixture.detectChanges();
       expect(extendedFabButtonDebugEl.nativeElement.classList).toContain('mat-mdc-extended-fab');
     });
+
+    it('should default expanded to true', () => {
+      const fixture = TestBed.createComponent(TestApp);
+      fixture.detectChanges();
+      const extendedFabButtonDebugEl = fixture.debugElement.query(By.css('.extended-fab-test'))!;
+
+      fixture.componentInstance.extended = true;
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+
+      expect(extendedFabButtonDebugEl.nativeElement.classList).toContain(
+        'mat-mdc-extended-fab-expanded',
+      );
+      expect(extendedFabButtonDebugEl.nativeElement.classList).not.toContain(
+        'mat-mdc-extended-fab-collapsed',
+      );
+    });
+
+    it('should add mat-mdc-extended-fab-collapsed class when expanded is false', () => {
+      const fixture = TestBed.createComponent(TestApp);
+      fixture.detectChanges();
+      const extendedFabButtonDebugEl = fixture.debugElement.query(By.css('.extended-fab-test'))!;
+
+      fixture.componentInstance.extended = true;
+      fixture.componentInstance.expanded = false;
+      fixture.changeDetectorRef.markForCheck();
+      fixture.detectChanges();
+
+      expect(extendedFabButtonDebugEl.nativeElement.classList).toContain(
+        'mat-mdc-extended-fab-collapsed',
+      );
+      expect(extendedFabButtonDebugEl.nativeElement.classList).not.toContain(
+        'mat-mdc-extended-fab-expanded',
+      );
+    });
   });
 
   // Regular button tests
@@ -533,7 +568,7 @@ describe('MatFabDefaultOptions', () => {
       Fab Button
       <span progressIndicator>Progress...</span>
     </button>
-    <button mat-fab [extended]="extended" class="extended-fab-test">Extended</button>
+    <button mat-fab [extended]="extended" [expanded]="expanded" class="extended-fab-test">Extended</button>
     <button mat-mini-fab [showProgress]="showProgress">
       Mini Fab Button
       <span progressIndicator>Progress...</span>
@@ -551,6 +586,7 @@ class TestApp {
   buttonColor!: ThemePalette;
   tabIndex!: number;
   extended = false;
+  expanded = true;
   disabledInteractive = false;
   appearance: MatButtonAppearance = 'text';
   showProgress = false;

src/material/button/button.spec.ts

@@ -1,10 +1,23 @@
+@use 'sass:map';
 @use './button-base';
 @use '../core/tokens/token-utils';
 @use '../core/style/private' as style-private;
 @use '../core/style/vendor-prefixes';
 @use '../core/focus-indicators/private' as focus-indicators-private;
+@use '../core/tokens/m3/md-sys-motion' as m3-motion;
 @use './m3-fab';
 
+$m3-motion-tokens: m3-motion.md-sys-motion-values();
+$easing-emphasized: map.get($m3-motion-tokens, easing-emphasized);
+$easing-emphasized-decelerate: map.get($m3-motion-tokens, easing-emphasized-decelerate);
+$easing-emphasized-accelerate: map.get($m3-motion-tokens, easing-emphasized-accelerate);
+$easing-standard: map.get($m3-motion-tokens, easing-standard);
+$easing-standard-decelerate: map.get($m3-motion-tokens, easing-standard-decelerate);
+$easing-standard-accelerate: map.get($m3-motion-tokens, easing-standard-accelerate);
+$easing-legacy: map.get($m3-motion-tokens, easing-legacy);
+$easing-legacy-decelerate: map.get($m3-motion-tokens, easing-legacy-decelerate);
+$easing-legacy-accelerate: map.get($m3-motion-tokens, easing-legacy-accelerate);
+
 $fallbacks: m3-fab.get-tokens();
 
 .mat-mdc-fab-base {
@@ -24,8 +37,8 @@ $fallbacks: m3-fab.get-tokens();
   -moz-appearance: none;
   -webkit-appearance: none;
   overflow: visible;
-  transition: box-shadow 280ms cubic-bezier(0.4, 0, 0.2, 1), opacity 15ms linear 30ms,
-    transform 270ms 0ms cubic-bezier(0, 0, 0.2, 1);
+  transition: box-shadow 280ms $easing-legacy, opacity 15ms linear 30ms,
+    transform 270ms 0ms $easing-legacy-decelerate;
   flex-shrink: 0; // Prevent the button from shrinking since it's always supposed to be a circle.
 
   // Due to the shape of the FAB, inheriting the shape looks off. Disable it explicitly.
@@ -75,7 +88,7 @@ $fallbacks: m3-fab.get-tokens();
   // mixin will style the icons appropriately.
   // stylelint-disable-next-line selector-class-pattern
   .mat-icon, .material-icons {
-    transition: transform 180ms 90ms cubic-bezier(0, 0, 0.2, 1);
+    transition: transform 180ms 90ms $easing-legacy-decelerate;
     fill: currentColor;
     will-change: transform;
   }
@@ -167,11 +180,8 @@ $fallbacks: m3-fab.get-tokens();
   // tokens it doesn't. We add it since it can cause tiny differences in
   // screenshot tests and it generally looks better.
   @include vendor-prefixes.smooth-font();
-  padding-left: 20px;
-  padding-right: 20px;
+
   width: auto;
-  max-width: 100%;
-  line-height: normal;
   box-shadow: token-utils.slot(fab-extended-container-elevation-shadow, $fallbacks);
   height: token-utils.slot(fab-extended-container-height, $fallbacks);
   border-radius: token-utils.slot(fab-extended-container-shape, $fallbacks);
@@ -180,6 +190,20 @@ $fallbacks: m3-fab.get-tokens();
   font-weight: token-utils.slot(fab-extended-label-text-weight, $fallbacks);
   letter-spacing: token-utils.slot(fab-extended-label-text-tracking, $fallbacks);
 
+    // Outer container padding: expanded state (asymmetrical layout)
+    // LTR: 16px at start (close to icon), 20px at end (close to text)
+    padding-left: 16px;
+    padding-right: 20px;
+    transition: padding 270ms $easing-standard,
+                margin 270ms $easing-standard,
+                border-radius 270ms $easing-standard;
+
+    // RTL: start moves to right (16px), end moves to left (20px)
+  [dir='rtl'] & {
+    padding-left: 20px;
+    padding-right: 16px;
+  }
+
   @media (hover: hover) {
     &:hover {
       box-shadow: token-utils.slot(fab-extended-hover-container-elevation-shadow, $fallbacks);
@@ -203,22 +227,74 @@ $fallbacks: m3-fab.get-tokens();
 
   // stylelint-disable selector-class-pattern
   // For Extended FAB with text label followed by icon.
-  // We are checking for the a button class because white this is a FAB it
+  // We are checking for the a button class because while this is a FAB it
   // uses the same template as button.
-  [dir='rtl'] & .mdc-button__label + .mat-icon,
-  [dir='rtl'] & .mdc-button__label + .material-icons,
-  > .mat-icon,
-  > .material-icons {
-    margin-left: -8px;
+  .mdc-button__label {
+    white-space: nowrap;
+    opacity: 1;
+    display: inline-grid;
+    // Explicitly break the auto constraint, allowing tracks to be squeezed to 0
+    // to achieve "label width" set to 0.
+    grid-template-columns: minmax(0, 1fr);
+    overflow: hidden;
+
+    transition: opacity 150ms 100ms linear,
+          grid-template-columns 270ms $easing-standard;
+    }
+
+    // Icon visually positioned on the LEFT (first icon in LTR, or last icon in RTL)
+    // No margin on the left, rely on parent container padding to create space.
+    // Use 12px margin on the right to push text.
+    [dir='rtl'] & .mdc-button__label + .mat-icon,
+    [dir='rtl'] & .mdc-button__label + .material-icons,
+    > .mat-icon,
+    > .material-icons {
+    margin-left: 0;
     margin-right: 12px;
-  }
+    transition: margin 270ms $easing-standard;
+    }
 
-  .mdc-button__label + .mat-icon,
-  .mdc-button__label + .material-icons,
-  [dir='rtl'] & > .mat-icon,
-  [dir='rtl'] & > .material-icons {
+    // Icon visually positioned on the RIGHT (last icon in LTR, or first icon in RTL)
+    // 12px margin on the left to push text; no margin on the right,
+    // rely on parent container padding.
+    .mdc-button__label + .mat-icon,
+    .mdc-button__label + .material-icons,
+    [dir='rtl'] & > .mat-icon,
+    [dir='rtl'] & > .material-icons {
     margin-left: 12px;
-    margin-right: -8px;
+    margin-right: 0;
+    transition: margin 270ms $easing-standard;
+    }
+
+    &.mat-mdc-extended-fab-collapsed {
+    // Force symmetric 16px padding.
+    // 16px (spacing) + 24px (icon) + 16px (spacing) = 56px perfect circle.
+    padding-left: 16px;
+    padding-right: 16px;
+
+    [dir='rtl'] & {
+      padding-left: 16px;
+      padding-right: 16px;
+    }
+
+    // Collapse text and make it transparent when collapsed
+    .mdc-button__label {
+      grid-template-columns: minmax(0, 0fr);
+
+      opacity: 0;
+      transition: grid-template-columns 270ms $easing-standard,
+            opacity 100ms 0ms linear;
+    }
+
+    // When collapsed, remove all extra icon margins to allow flexbox to center it perfectly
+    > .mat-icon,
+    > .material-icons,
+    .mdc-button__label + .mat-icon,
+    .mdc-button__label + .material-icons {
+      margin-left: 0;
+      margin-right: 0;
+      transition: margin 270ms $easing-standard;
+    }
   }
   // stylelint-enable selector-class-pattern
 

src/material/button/fab.scss

@@ -61,6 +61,7 @@ const defaults: MatFabDefaultOptions = {
     'class': 'mdc-fab mat-mdc-fab-base mat-mdc-fab',
     '[class.mdc-fab--extended]': 'extended',
     '[class.mat-mdc-extended-fab]': 'extended',
+    '[class.mat-mdc-extended-fab-collapsed]': 'extended && !expanded',
   },
   exportAs: 'matButton, matAnchor',
   encapsulation: ViewEncapsulation.None,
@@ -73,6 +74,9 @@ export class MatFabButton extends MatButtonBase {
 
   @Input({transform: booleanAttribute}) extended: boolean = false;
 
+  /** Whether the extended-FAB is currently expanded. Has no effect on non-extended FABs. */
+  @Input({transform: booleanAttribute}) expanded: boolean = true;
+
   constructor(...args: unknown[]);
 
   constructor() {