fix(material-angular-io): remove docs data from critical path

The docs site was loading the data of all the examples up-front through an eager import which was bringing in ~170kb of JavaScript which isn't necessary for the initial load. These changes refactor the various call sites so that they load the example data asynchronously.

Author: crisbeto

material.angular.io/.eslintrc.json

@@ -20,8 +20,10 @@
         "@angular-eslint/component-selector": "off",
         "@angular-eslint/directive-class-suffix": "off",
         "@angular-eslint/directive-selector": "off",
+        "@angular-eslint/no-host-metadata-property": "off",
         "@typescript-eslint/dot-notation": "off",
         "@typescript-eslint/member-delimiter-style": "off",
+        "@typescript-eslint/naming-convention": "off",
         "@typescript-eslint/explicit-member-accessibility": [
           "off",
           {

material.angular.io/src/app/pages/component-category-list/component-category-list.html

@@ -3,9 +3,9 @@
      focusOnNavigation>
   <div [innerHTML]="_categoryListSummary"></div>
 </div>
-@if ((params | async)?.section; as section) {
+@if (items.length > 0) {
   <div class="docs-component-category-list">
-    @for (component of docItems.getItems(section); track component) {
+    @for (component of items; track component) {
       <a class="docs-component-category-list-item"
          [routerLink]="'/' + section + '/' + component.id">
         <div class="docs-component-category-list-card" matRipple>

material.angular.io/src/app/pages/component-category-list/component-category-list.spec.ts

@@ -1,11 +1,14 @@
-import {AsyncPipe} from '@angular/common';
 import {Component, NgModule, OnDestroy, OnInit} from '@angular/core';
 import {MatCardModule} from '@angular/material/card';
-import {ActivatedRoute, Params, RouterModule, RouterLink} from '@angular/router';
+import {ActivatedRoute, RouterModule, RouterLink} from '@angular/router';
 import {MatRipple} from '@angular/material/core';
-import {combineLatest, Observable, Subscription} from 'rxjs';
+import {combineLatest, Subscription} from 'rxjs';
 
-import {DocumentationItems, SECTIONS} from '../../shared/documentation-items/documentation-items';
+import {
+  DocItem,
+  DocumentationItems,
+  SECTIONS,
+} from '../../shared/documentation-items/documentation-items';
 import {NavigationFocus} from '../../shared/navigation-focus/navigation-focus';
 
 import {ComponentPageTitle} from '../page-title/page-title';
@@ -15,32 +18,31 @@ import {ComponentPageTitle} from '../page-title/page-title';
   templateUrl: './component-category-list.html',
   styleUrls: ['./component-category-list.scss'],
   standalone: true,
-  imports: [NavigationFocus, RouterLink, AsyncPipe, MatRipple],
+  imports: [NavigationFocus, RouterLink, MatRipple],
 })
 export class ComponentCategoryList implements OnInit, OnDestroy {
-  params: Observable<Params> | undefined;
+  items: DocItem[] = [];
+  section = '';
   routeParamSubscription: Subscription = new Subscription();
   _categoryListSummary: string | undefined;
 
   constructor(
-    public docItems: DocumentationItems,
-    public _componentPageTitle: ComponentPageTitle,
+    readonly _docItems: DocumentationItems,
+    private _componentPageTitle: ComponentPageTitle,
     private _route: ActivatedRoute,
   ) {}
 
   ngOnInit() {
-    // Combine params from all of the path into a single object.
-    this.params = combineLatest(
+    this.routeParamSubscription = combineLatest(
       this._route.pathFromRoot.map(route => route.params),
       Object.assign,
-    );
-
-    // title on topbar navigation
-    this.routeParamSubscription = this.params.subscribe(params => {
+    ).subscribe(async params => {
       const sectionName = params['section'];
       const section = SECTIONS[sectionName];
       this._componentPageTitle.title = section.name;
       this._categoryListSummary = section.summary;
+      this.section = sectionName;
+      this.items = await this._docItems.getItems(sectionName);
     });
   }
 

material.angular.io/src/app/pages/component-category-list/component-category-list.ts

@@ -1,17 +1,19 @@
 <div class="docs-component-viewer-nav">
-  @if ((params() | async)?.section; as section) {
+  @let items = (this.items | async) || [];
+
+  @if (items.length > 0) {
     <div class="docs-component-viewer-nav-content">
-        <mat-nav-list>
-          @for (component of docItems.getItems(section); track component) {
-            <a mat-list-item #link="routerLinkActive"
-               [routerLink]="'/' + section+ '/' + component.id"
-               [activated]="link.isActive"
-               routerLinkActive="docs-component-viewer-sidenav-item-selected"
-               [attr.aria-current]="currentItemId === component.id ? 'page': 'false'">
-              {{component.name}}
-            </a>
-          }
-        </mat-nav-list>
+      <mat-nav-list>
+        @for (component of items; track component) {
+          <a mat-list-item #link="routerLinkActive"
+              [routerLink]="'/' + params()?.section + '/' + component.id"
+              [activated]="link.isActive"
+              routerLinkActive="docs-component-viewer-sidenav-item-selected"
+              [attr.aria-current]="link.isActive ? 'page': 'false'">
+            {{component.name}}
+          </a>
+        }
+      </mat-nav-list>
     </div>
   }
 </div>

material.angular.io/src/app/pages/component-sidenav/component-nav.html

@@ -6,7 +6,7 @@
                 [mode]="(isScreenSmall | async) ? 'over' : 'side'"
                 [fixedInViewport]="(isScreenSmall | async)"
                 [fixedTopGap]="(isExtraScreenSmall | async) ? 92 : 56">
-      <app-component-nav [params]="params"></app-component-nav>
+      <app-component-nav [params]="params | async"></app-component-nav>
     </mat-sidenav>
   }
   <div class="docs-component-sidenav-content">
@@ -15,7 +15,7 @@
       <main class="docs-component-sidenav-body-content">
         <!-- If on large screen, menu resides to left of content -->
         @if ((isScreenSmall | async) === false) {
-          <app-component-nav [params]="params"/>
+          <app-component-nav [params]="params | async"/>
         }
         <router-outlet></router-outlet>
       </main>

material.angular.io/src/app/pages/component-sidenav/component-sidenav.html

@@ -34,8 +34,9 @@ describe('ComponentSidenav', () => {
     });
   });
 
-  it('should show a link for each item in doc items categories', () => {
-    const totalItems = component.docItems.getItems('categories').length;
+  it('should show a link for each item in doc items categories', async () => {
+    const items = await component.docItems.getItems('categories');
+    const totalItems = items.length;
     const totalLinks = fixture.nativeElement.querySelectorAll(
       '.docs-component-viewer-sidenav li a',
     ).length;

material.angular.io/src/app/pages/component-sidenav/component-sidenav.spec.ts

@@ -1,14 +1,15 @@
 import {
   Component,
   NgModule,
-  NgZone,
   OnDestroy,
   OnInit,
   ViewEncapsulation,
   forwardRef,
+  inject,
   input,
   viewChild,
 } from '@angular/core';
+import {toObservable} from '@angular/core/rxjs-interop';
 import {CdkAccordionModule} from '@angular/cdk/accordion';
 import {BreakpointObserver} from '@angular/cdk/layout';
 import {AsyncPipe} from '@angular/common';
@@ -26,7 +27,7 @@ import {
   RouterLink,
 } from '@angular/router';
 import {combineLatest, Observable, Subscription} from 'rxjs';
-import {map} from 'rxjs/operators';
+import {map, switchMap} from 'rxjs/operators';
 
 import {DocViewerModule} from '../../shared/doc-viewer/doc-viewer-module';
 import {DocumentationItems} from '../../shared/documentation-items/documentation-items';
@@ -75,16 +76,15 @@ const SMALL_WIDTH_BREAKPOINT = 959;
 })
 export class ComponentSidenav implements OnInit, OnDestroy {
   readonly sidenav = viewChild(MatSidenav);
-  params: Observable<Params> | undefined;
+  params: Observable<Params>;
   isExtraScreenSmall: Observable<boolean>;
   isScreenSmall: Observable<boolean>;
-  private subscriptions = new Subscription();
+  private _subscriptions = new Subscription();
 
   constructor(
     public docItems: DocumentationItems,
     private _route: ActivatedRoute,
     private _navigationFocusService: NavigationFocusService,
-    zone: NgZone,
     breakpoints: BreakpointObserver,
   ) {
     this.isExtraScreenSmall = breakpoints
@@ -93,16 +93,15 @@ export class ComponentSidenav implements OnInit, OnDestroy {
     this.isScreenSmall = breakpoints
       .observe(`(max-width: ${SMALL_WIDTH_BREAKPOINT}px)`)
       .pipe(map(breakpoint => breakpoint.matches));
-  }
 
-  ngOnInit() {
-    // Combine params from all of the path into a single object.
     this.params = combineLatest(
       this._route.pathFromRoot.map(route => route.params),
       Object.assign,
     );
+  }
 
-    this.subscriptions.add(
+  ngOnInit() {
+    this._subscriptions.add(
       this._navigationFocusService.navigationEndEvents
         .pipe(map(() => this.isScreenSmall))
         .subscribe(shouldCloseSideNav => {
@@ -115,7 +114,7 @@ export class ComponentSidenav implements OnInit, OnDestroy {
   }
 
   ngOnDestroy() {
-    this.subscriptions.unsubscribe();
+    this._subscriptions.unsubscribe();
   }
 
   toggleSidenav(): void {
@@ -130,10 +129,14 @@ export class ComponentSidenav implements OnInit, OnDestroy {
   imports: [MatListModule, RouterLinkActive, RouterLink, AsyncPipe],
 })
 export class ComponentNav {
-  readonly params = input<Observable<Params>>();
-  currentItemId: string | undefined;
+  private _docItems = inject(DocumentationItems);
+  readonly params = input<Params | null>();
 
-  constructor(public docItems: DocumentationItems) {}
+  items = toObservable(this.params).pipe(
+    switchMap(params =>
+      params?.section ? this._docItems.getItems(params.section) : Promise.resolve(null),
+    ),
+  );
 }
 
 const routes: Routes = [

material.angular.io/src/app/pages/component-sidenav/component-sidenav.ts

@@ -14,15 +14,14 @@ import {
 import {MatTabsModule} from '@angular/material/tabs';
 import {
   ActivatedRoute,
-  Params,
   Router,
   RouterModule,
   RouterLinkActive,
   RouterLink,
   RouterOutlet,
 } from '@angular/router';
 import {combineLatest, Observable, ReplaySubject, Subject} from 'rxjs';
-import {map, skip, takeUntil} from 'rxjs/operators';
+import {map, skip, switchMap, takeUntil} from 'rxjs/operators';
 import {DocViewerModule} from '../../shared/doc-viewer/doc-viewer-module';
 import {DocItem, DocumentationItems} from '../../shared/documentation-items/documentation-items';
 import {TableOfContents} from '../../shared/table-of-contents/table-of-contents';
@@ -59,15 +58,13 @@ export class ComponentViewer implements OnDestroy {
     // parent route for the section (material/cdk).
     combineLatest(routeAndParentParams)
       .pipe(
-        map((params: Params[]) => {
+        switchMap(async params => {
           const id = params[0]['id'];
           const section = params[1]['section'];
-
-          return {
-            doc: docItems.getItemById(id, section),
-            section: section,
-          };
-        }, takeUntil(this._destroyed)),
+          const doc = await docItems.getItemById(id, section);
+          return {doc, section};
+        }),
+        takeUntil(this._destroyed),
       )
       .subscribe(({doc, section}) => {
         if (!doc) {