feat(material/tabs): add the ability to keep content inside the DOM while off-screen

Adds the `preserveContent` input which allows consumers to opt into keeping the
content of off-screen tabs inside the DOM. This is useful primarily for edge cases like
iframes and videos where removing the element from the DOM will cause it to reload.

One gotcha here is that we have to set `visibility: hidden` on the off-screen content so
that users can't tab into it.

Fixes #19480.

Author: crisbeto

src/components-examples/material/tabs/index.ts

@@ -19,6 +19,9 @@ import {TabGroupHarnessExample} from './tab-group-harness/tab-group-harness-exam
 import {TabGroupDynamicExample} from './tab-group-dynamic/tab-group-dynamic-example';
 import {TabGroupHeaderBelowExample} from './tab-group-header-below/tab-group-header-below-example';
 import {TabGroupLazyLoadedExample} from './tab-group-lazy-loaded/tab-group-lazy-loaded-example';
+import {
+  TabGroupPreserveContentExample
+} from './tab-group-preserve-content/tab-group-preserve-content-example';
 import {TabGroupStretchedExample} from './tab-group-stretched/tab-group-stretched-example';
 import {TabGroupThemeExample} from './tab-group-theme/tab-group-theme-example';
 import {TabNavBarBasicExample} from './tab-nav-bar-basic/tab-nav-bar-basic-example';
@@ -37,6 +40,7 @@ export {
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
+  TabGroupPreserveContentExample,
 };
 
 const EXAMPLES = [
@@ -53,6 +57,7 @@ const EXAMPLES = [
   TabGroupStretchedExample,
   TabGroupThemeExample,
   TabNavBarBasicExample,
+  TabGroupPreserveContentExample,
 ];
 
 @NgModule({

src/components-examples/material/tabs/tab-group-preserve-content/tab-group-preserve-content-example.html

@@ -0,0 +1,14 @@
+<p>Start the video in the first tab and navigate to the second one to see how it keeps playing.</p>
+
+<mat-tab-group [preserveContent]="true">
+  <mat-tab label="First">
+    <iframe
+      width="560"
+      height="315"
+      src="https://www.youtube.com/embed/B-lipaiZII8"
+      frameborder="0"
+      allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+      allowfullscreen></iframe>
+  </mat-tab>
+  <mat-tab label="Second">Note how the video from the previous tab is still playing.</mat-tab>
+</mat-tab-group>

src/components-examples/material/tabs/tab-group-preserve-content/tab-group-preserve-content-example.ts

@@ -0,0 +1,10 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Tab group that keeps its content inside the DOM when it's off-screen.
+ */
+@Component({
+  selector: 'tab-group-preserve-content-example',
+  templateUrl: 'tab-group-preserve-content-example.html',
+})
+export class TabGroupPreserveContentExample {}

src/material-experimental/mdc-tabs/tab-group.html

@@ -60,6 +60,7 @@
                [position]="tab.position!"
                [origin]="tab.origin"
                [animationDuration]="animationDuration"
+               [preserveContent]="preserveContent"
                (_onCentered)="_removeTabBodyWrapperHeight()"
                (_onCentering)="_setTabBodyWrapperHeight($event)">
   </mat-tab-body>

src/material-experimental/mdc-tabs/tab-group.spec.ts

@@ -627,6 +627,44 @@ describe('MDC-based MatTabGroup', () => {
 
       expect(tabGroupNode.classList).toContain('mat-mdc-tab-group-inverted-header');
     });
+
+    it('should be able to opt into keeping the inactive tab content in the DOM', fakeAsync(() => {
+      fixture.componentInstance.preserveContent = true;
+      fixture.detectChanges();
+
+      expect(fixture.nativeElement.textContent).toContain('Pizza, fries');
+      expect(fixture.nativeElement.textContent).not.toContain('Peanuts');
+
+      tabGroup.selectedIndex = 3;
+      fixture.detectChanges();
+      tick();
+
+      expect(fixture.nativeElement.textContent).toContain('Pizza, fries');
+      expect(fixture.nativeElement.textContent).toContain('Peanuts');
+    }));
+
+    it('should visibly hide the content of inactive tabs', fakeAsync(() => {
+      const contentElements: HTMLElement[] =
+          Array.from(fixture.nativeElement.querySelectorAll('.mat-mdc-tab-body-content'));
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['visible', 'hidden', 'hidden', 'hidden']);
+
+      tabGroup.selectedIndex = 2;
+      fixture.detectChanges();
+      tick();
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['hidden', 'hidden', 'visible', 'hidden']);
+
+      tabGroup.selectedIndex = 1;
+      fixture.detectChanges();
+      tick();
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['hidden', 'visible', 'hidden', 'hidden']);
+    }));
+
   });
 
   describe('lazy loaded tabs', () => {
@@ -973,7 +1011,7 @@ class AsyncTabsTestApp implements OnInit {
 
 @Component({
   template: `
-  <mat-tab-group>
+  <mat-tab-group [preserveContent]="preserveContent">
     <mat-tab label="Junk food"> Pizza, fries </mat-tab>
     <mat-tab label="Vegetables"> Broccoli, spinach </mat-tab>
     <mat-tab [label]="otherLabel"> {{otherContent}} </mat-tab>
@@ -982,6 +1020,7 @@ class AsyncTabsTestApp implements OnInit {
   `
 })
 class TabGroupWithSimpleApi {
+  preserveContent = false;
   otherLabel = 'Fruit';
   otherContent = 'Apples, grapes';
   @ViewChild('legumes') legumes: any;

src/material/tabs/tab-body.ts

@@ -88,7 +88,9 @@ export class MatTabBodyPortal extends CdkPortalOutlet implements OnInit, OnDestr
       });
 
     this._leavingSub = this._host._afterLeavingCenter.subscribe(() => {
-      this.detach();
+      if (!this._host.preserveContent) {
+        this.detach();
+      }
     });
   }
 
@@ -144,6 +146,9 @@ export abstract class _MatTabBodyBase implements OnInit, OnDestroy {
   /** Duration for the tab's animation. */
   @Input() animationDuration: string = '500ms';
 
+  /** Whether the tab's content should be kept in the DOM while it's off-screen. */
+  @Input() preserveContent: boolean = false;
+
   /** The shifted index position of the tab body, where zero represents the active center tab. */
   @Input()
   set position(position: number) {

src/material/tabs/tab-config.ts

@@ -26,6 +26,13 @@ export interface MatTabsConfig {
 
   /** Whether the tab group should grow to the size of the active tab. */
   dynamicHeight?: boolean;
+
+  /**
+   * By default tabs remove their content from the DOM while it's off-screen.
+   * Setting this to `true` will keep it in the DOM which will prevent elements
+   * like iframes and videos from reloading next time it comes back into the view.
+   */
+  preserveContent?: boolean;
 }
 
 /** Injection token that can be used to provide the default options the tabs module. */

src/material/tabs/tab-group.html

@@ -46,6 +46,7 @@
                [position]="tab.position!"
                [origin]="tab.origin"
                [animationDuration]="animationDuration"
+               [preserveContent]="preserveContent"
                (_onCentered)="_removeTabBodyWrapperHeight()"
                (_onCentering)="_setTabBodyWrapperHeight($event)">
   </mat-tab-body>

src/material/tabs/tab-group.spec.ts

@@ -626,6 +626,44 @@ describe('MatTabGroup', () => {
 
       expect(tabGroupNode.classList).toContain('mat-tab-group-inverted-header');
     });
+
+    it('should be able to opt into keeping the inactive tab content in the DOM', fakeAsync(() => {
+      fixture.componentInstance.preserveContent = true;
+      fixture.detectChanges();
+
+      expect(fixture.nativeElement.textContent).toContain('Pizza, fries');
+      expect(fixture.nativeElement.textContent).not.toContain('Peanuts');
+
+      tabGroup.selectedIndex = 3;
+      fixture.detectChanges();
+      tick();
+
+      expect(fixture.nativeElement.textContent).toContain('Pizza, fries');
+      expect(fixture.nativeElement.textContent).toContain('Peanuts');
+    }));
+
+    it('should visibly hide the content of inactive tabs', fakeAsync(() => {
+      const contentElements: HTMLElement[] =
+          Array.from(fixture.nativeElement.querySelectorAll('.mat-tab-body-content'));
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['visible', 'hidden', 'hidden', 'hidden']);
+
+      tabGroup.selectedIndex = 2;
+      fixture.detectChanges();
+      tick();
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['hidden', 'hidden', 'visible', 'hidden']);
+
+      tabGroup.selectedIndex = 1;
+      fixture.detectChanges();
+      tick();
+
+      expect(contentElements.map(element => element.style.visibility))
+          .toEqual(['hidden', 'visible', 'hidden', 'hidden']);
+    }));
+
   });
 
   describe('lazy loaded tabs', () => {
@@ -917,7 +955,7 @@ class AsyncTabsTestApp implements OnInit {
 
 @Component({
   template: `
-  <mat-tab-group>
+  <mat-tab-group [preserveContent]="preserveContent">
     <mat-tab label="Junk food"> Pizza, fries </mat-tab>
     <mat-tab label="Vegetables"> Broccoli, spinach </mat-tab>
     <mat-tab [label]="otherLabel"> {{otherContent}} </mat-tab>
@@ -926,6 +964,7 @@ class AsyncTabsTestApp implements OnInit {
   `
 })
 class TabGroupWithSimpleApi {
+  preserveContent = false;
   otherLabel = 'Fruit';
   otherContent = 'Apples, grapes';
   @ViewChild('legumes') legumes: any;

src/material/tabs/tab-group.ts

@@ -138,6 +138,14 @@ export abstract class _MatTabGroupBase extends _MatTabGroupMixinBase implements
   @Input()
   disablePagination: boolean;
 
+  /**
+   * By default tabs remove their content from the DOM while it's off-screen.
+   * Setting this to `true` will keep it in the DOM which will prevent elements
+   * like iframes and videos from reloading next time it comes back into the view.
+   */
+  @Input()
+  preserveContent: boolean;
+
   /** Background color of the tab group. */
   @Input()
   get backgroundColor(): ThemePalette { return this._backgroundColor; }
@@ -182,6 +190,7 @@ export abstract class _MatTabGroupBase extends _MatTabGroupMixinBase implements
         defaultConfig.disablePagination : false;
     this.dynamicHeight = defaultConfig && defaultConfig.dynamicHeight != null ?
         defaultConfig.dynamicHeight : false;
+    this.preserveContent = !!defaultConfig?.preserveContent;
   }
 
   /**

src/material/tabs/tabs-animations.ts

@@ -23,24 +23,39 @@ export const matTabsAnimations: {
 } = {
   /** Animation translates a tab along the X axis. */
   translateTab: trigger('translateTab', [
-    // Note: transitions to `none` instead of 0, because some browsers might blur the content.
-    state('center, void, left-origin-center, right-origin-center', style({transform: 'none'})),
+    state('center, void, left-origin-center, right-origin-center', style({
+      // Transitions to `none` instead of 0, because some browsers might blur the content.
+      transform: 'none',
+      // Ensures that the `visibility: hidden` from below is cleared.
+      visibility: 'visible'
+    })),
 
     // If the tab is either on the left or right, we additionally add a `min-height` of 1px
     // in order to ensure that the element has a height before its state changes. This is
     // necessary because Chrome does seem to skip the transition in RTL mode if the element does
     // not have a static height and is not rendered. See related issue: #9465
-    state('left', style({transform: 'translate3d(-100%, 0, 0)', minHeight: '1px'})),
-    state('right', style({transform: 'translate3d(100%, 0, 0)', minHeight: '1px'})),
+    state('left', style({
+      transform: 'translate3d(-100%, 0, 0)',
+      minHeight: '1px',
+
+      // Normally this is redundant since we detach the content from the DOM, but if the user
+      // opted into keeping the content in the DOM, we have to hide it so it isn't focusable.
+      visibility: 'hidden'
+    })),
+    state('right', style({
+      transform: 'translate3d(100%, 0, 0)',
+      minHeight: '1px',
+      visibility: 'hidden'
+    })),
 
     transition('* => left, * => right, left => center, right => center',
         animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')),
     transition('void => left-origin-center', [
-      style({transform: 'translate3d(-100%, 0, 0)'}),
+      style({transform: 'translate3d(-100%, 0, 0)', visibility: 'hidden'}),
       animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')
     ]),
     transition('void => right-origin-center', [
-      style({transform: 'translate3d(100%, 0, 0)'}),
+      style({transform: 'translate3d(100%, 0, 0)', visibility: 'hidden'}),
       animate('{{animationDuration}} cubic-bezier(0.35, 0, 0.25, 1)')
     ])
   ])

src/material/tabs/tabs.md

@@ -84,6 +84,15 @@ duration can be configured globally using the `MAT_TABS_CONFIG` injection token.
                "file": "tab-group-animations-example.html",
                "region": "slow-animation-duration"}) -->
 
+### Keeping the tab content inside the DOM while it's off-screen
+By default the `<mat-tab-group>` will remove the content of off-screen tabs from the DOM until they
+come into the view. This is optimal for most cases since it keeps the DOM size smaller, but it
+isn't great for others like when a tab has an `<audio>` or `<video>` element, because the content
+will be re-initialized whenever the user navigates to the tab. If you want to keep the content of
+off-screen tabs in the DOM, you can set the `preserveContent` input to `true`.
+
+<!-- example(tab-group-preserve-content) -->
+
 ### Accessibility
 `<mat-tab-group>` and `<mat-nav-tab-bar>` use different interaction patterns. The
 `<mat-tab-group>` component combines `tablist`, `tab`, and `tabpanel` into a single component with

tools/public_api_guard/material/tabs.d.ts

@@ -19,13 +19,14 @@ export declare abstract class _MatTabBodyBase implements OnInit, OnDestroy {
     animationDuration: string;
     origin: number | null;
     set position(position: number);
+    preserveContent: boolean;
     constructor(_elementRef: ElementRef<HTMLElement>, _dir: Directionality, changeDetectorRef: ChangeDetectorRef);
     _getLayoutDirection(): Direction;
     _isCenterPosition(position: MatTabBodyPositionState | string): boolean;
     _onTranslateTabStarted(event: AnimationEvent): void;
     ngOnDestroy(): void;
     ngOnInit(): void;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<_MatTabBodyBase, never, never, { "_content": "content"; "origin": "origin"; "animationDuration": "animationDuration"; "position": "position"; }, { "_onCentering": "_onCentering"; "_beforeCentering": "_beforeCentering"; "_afterLeavingCenter": "_afterLeavingCenter"; "_onCentered": "_onCentered"; }, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<_MatTabBodyBase, never, never, { "_content": "content"; "origin": "origin"; "animationDuration": "animationDuration"; "preserveContent": "preserveContent"; "position": "position"; }, { "_onCentering": "_onCentering"; "_beforeCentering": "_beforeCentering"; "_afterLeavingCenter": "_afterLeavingCenter"; "_onCentered": "_onCentered"; }, never>;
     static ɵfac: i0.ɵɵFactoryDeclaration<_MatTabBodyBase, [null, { optional: true; }, null]>;
 }
 
@@ -46,6 +47,7 @@ export declare abstract class _MatTabGroupBase extends _MatTabGroupMixinBase imp
     set dynamicHeight(value: boolean);
     readonly focusChange: EventEmitter<MatTabChangeEvent>;
     headerPosition: MatTabHeaderPosition;
+    preserveContent: boolean;
     get selectedIndex(): number | null;
     set selectedIndex(value: number | null);
     readonly selectedIndexChange: EventEmitter<number>;
@@ -68,7 +70,7 @@ export declare abstract class _MatTabGroupBase extends _MatTabGroupMixinBase imp
     static ngAcceptInputType_disableRipple: BooleanInput;
     static ngAcceptInputType_dynamicHeight: BooleanInput;
     static ngAcceptInputType_selectedIndex: NumberInput;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<_MatTabGroupBase, never, never, { "dynamicHeight": "dynamicHeight"; "selectedIndex": "selectedIndex"; "headerPosition": "headerPosition"; "animationDuration": "animationDuration"; "disablePagination": "disablePagination"; "backgroundColor": "backgroundColor"; }, { "selectedIndexChange": "selectedIndexChange"; "focusChange": "focusChange"; "animationDone": "animationDone"; "selectedTabChange": "selectedTabChange"; }, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<_MatTabGroupBase, never, never, { "dynamicHeight": "dynamicHeight"; "selectedIndex": "selectedIndex"; "headerPosition": "headerPosition"; "animationDuration": "animationDuration"; "disablePagination": "disablePagination"; "preserveContent": "preserveContent"; "backgroundColor": "backgroundColor"; }, { "selectedIndexChange": "selectedIndexChange"; "focusChange": "focusChange"; "animationDone": "animationDone"; "selectedTabChange": "selectedTabChange"; }, never>;
     static ɵfac: i0.ɵɵFactoryDeclaration<_MatTabGroupBase, [null, null, { optional: true; }, { optional: true; }]>;
 }
 
@@ -254,6 +256,7 @@ export interface MatTabsConfig {
     disablePagination?: boolean;
     dynamicHeight?: boolean;
     fitInkBarToContent?: boolean;
+    preserveContent?: boolean;
 }
 
 export declare class MatTabsModule {