feat(material/stepper): allow for content to be rendered lazily (#15817)

Adds the `matStepContent` directive that allows consumers to defer rendering
the content of a step until it is opened for the first time.

Fixes #12339.

Author: crisbeto

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

@@ -14,6 +14,7 @@ import {StepperOverviewExample} from './stepper-overview/stepper-overview-exampl
 import {StepperStatesExample} from './stepper-states/stepper-states-example';
 import {StepperVerticalExample} from './stepper-vertical/stepper-vertical-example';
 import {StepperHarnessExample} from './stepper-harness/stepper-harness-example';
+import {StepperLazyContentExample} from './stepper-lazy-content/stepper-lazy-content-example';
 
 export {
   StepperEditableExample,
@@ -24,6 +25,7 @@ export {
   StepperOverviewExample,
   StepperStatesExample,
   StepperVerticalExample,
+  StepperLazyContentExample,
 };
 
 const EXAMPLES = [
@@ -35,6 +37,7 @@ const EXAMPLES = [
   StepperOverviewExample,
   StepperStatesExample,
   StepperVerticalExample,
+  StepperLazyContentExample,
 ];
 
 @NgModule({

src/components-examples/material/stepper/stepper-lazy-content/stepper-lazy-content-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */

src/components-examples/material/stepper/stepper-lazy-content/stepper-lazy-content-example.html

@@ -0,0 +1,22 @@
+<mat-vertical-stepper>
+  <mat-step>
+    <ng-template matStepLabel>Step 1</ng-template>
+    <ng-template matStepContent>
+      <p>This content was rendered lazily</p>
+      <button mat-button matStepperNext>Next</button>
+    </ng-template>
+  </mat-step>
+  <mat-step>
+    <ng-template matStepLabel>Step 2</ng-template>
+    <ng-template matStepContent>
+      <p>This content was also rendered lazily</p>
+      <button mat-button matStepperPrevious>Back</button>
+      <button mat-button matStepperNext>Next</button>
+    </ng-template>
+  </mat-step>
+  <mat-step>
+    <ng-template matStepLabel>Step 3</ng-template>
+    <p>This content was rendered eagerly</p>
+    <button mat-button matStepperPrevious>Back</button>
+  </mat-step>
+</mat-vertical-stepper>

src/components-examples/material/stepper/stepper-lazy-content/stepper-lazy-content-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Stepper lazy content rendering
+ */
+@Component({
+  selector: 'stepper-lazy-content-example',
+  templateUrl: 'stepper-lazy-content-example.html',
+  styleUrls: ['stepper-lazy-content-example.css'],
+})
+export class StepperLazyContentExample {}

src/material/stepper/public-api.ts

@@ -14,3 +14,4 @@ export * from './step-header';
 export * from './stepper-intl';
 export * from './stepper-animations';
 export * from './stepper-icon';
+export * from './step-content';

src/material/stepper/step-content.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Directive, TemplateRef} from '@angular/core';
+
+/**
+ * Content for a `mat-step` that will be rendered lazily.
+ */
+@Directive({
+  selector: 'ng-template[matStepContent]'
+})
+export class MatStepContent {
+  constructor(public _template: TemplateRef<any>) {}
+}

src/material/stepper/step.html

@@ -1 +1,4 @@
-<ng-template><ng-content></ng-content></ng-template>
+<ng-template>
+  <ng-content></ng-content>
+  <ng-template [cdkPortalOutlet]="_portal"></ng-template>
+</ng-template>

src/material/stepper/stepper-module.ts

@@ -19,6 +19,7 @@ import {MatHorizontalStepper, MatStep, MatStepper, MatVerticalStepper} from './s
 import {MatStepperNext, MatStepperPrevious} from './stepper-button';
 import {MatStepperIcon} from './stepper-icon';
 import {MAT_STEPPER_INTL_PROVIDER} from './stepper-intl';
+import {MatStepContent} from './step-content';
 
 
 @NgModule({
@@ -42,6 +43,7 @@ import {MAT_STEPPER_INTL_PROVIDER} from './stepper-intl';
     MatStepperPrevious,
     MatStepHeader,
     MatStepperIcon,
+    MatStepContent,
   ],
   declarations: [
     MatHorizontalStepper,
@@ -53,6 +55,7 @@ import {MAT_STEPPER_INTL_PROVIDER} from './stepper-intl';
     MatStepperPrevious,
     MatStepHeader,
     MatStepperIcon,
+    MatStepContent,
   ],
   providers: [MAT_STEPPER_INTL_PROVIDER, ErrorStateMatcher],
 })

src/material/stepper/stepper.md

@@ -180,6 +180,13 @@ will not affect steppers marked as `linear`.
 
 <!-- example(stepper-errors) -->
 
+### Lazy rendering
+By default, the stepper will render all of it's content when it's initialized. If you have some
+content that you want to want to defer until the particular step is opened, you can put it inside
+an `ng-template` with the `matStepContent` attribute.
+
+<!-- example(stepper-lazy-content) -->
+
 ### Keyboard interaction
 - <kbd>LEFT_ARROW</kbd>: Focuses the previous step header
 - <kbd>RIGHT_ARROW</kbd>: Focuses the next step header

src/material/stepper/stepper.spec.ts

@@ -1302,6 +1302,44 @@ describe('MatStepper', () => {
       expect(stepper.selectedIndex).toBe(1);
       expect(stepper.selected).toBeTruthy();
     });
+
+  describe('stepper with lazy content', () => {
+    it('should render the content of the selected step on init', () => {
+      const fixture = createComponent(StepperWithLazyContent);
+      const element = fixture.nativeElement;
+      fixture.componentInstance.selectedIndex = 1;
+      fixture.detectChanges();
+
+      expect(element.textContent).not.toContain('Step 1 content');
+      expect(element.textContent).toContain('Step 2 content');
+      expect(element.textContent).not.toContain('Step 3 content');
+    });
+
+    it('should render the content of steps when the user navigates to them', () => {
+      const fixture = createComponent(StepperWithLazyContent);
+      const element = fixture.nativeElement;
+      fixture.componentInstance.selectedIndex = 0;
+      fixture.detectChanges();
+
+      expect(element.textContent).toContain('Step 1 content');
+      expect(element.textContent).not.toContain('Step 2 content');
+      expect(element.textContent).not.toContain('Step 3 content');
+
+      fixture.componentInstance.selectedIndex = 1;
+      fixture.detectChanges();
+
+      expect(element.textContent).toContain('Step 1 content');
+      expect(element.textContent).toContain('Step 2 content');
+      expect(element.textContent).not.toContain('Step 3 content');
+
+      fixture.componentInstance.selectedIndex = 2;
+      fixture.detectChanges();
+
+      expect(element.textContent).toContain('Step 1 content');
+      expect(element.textContent).toContain('Step 2 content');
+      expect(element.textContent).toContain('Step 3 content');
+    });
+  });
 });
 
 /** Asserts that keyboard interaction works correctly. */
@@ -1826,3 +1864,26 @@ class NestedSteppers {
 class StepperWithStaticOutOfBoundsIndex {
   @ViewChild(MatStepper) stepper: MatStepper;
 }
+
+
+@Component({
+  template: `
+    <mat-vertical-stepper [selectedIndex]="selectedIndex">
+      <mat-step>
+        <ng-template matStepLabel>Step 1</ng-template>
+        <ng-template matStepContent>Step 1 content</ng-template>
+      </mat-step>
+      <mat-step>
+        <ng-template matStepLabel>Step 2</ng-template>
+        <ng-template matStepContent>Step 2 content</ng-template>
+      </mat-step>
+      <mat-step>
+        <ng-template matStepLabel>Step 3</ng-template>
+        <ng-template matStepContent>Step 3 content</ng-template>
+      </mat-step>
+    </mat-vertical-stepper>
+  `
+})
+class StepperWithLazyContent {
+  selectedIndex = 0;
+}