docs: snippet-based examples not showing after clicking away and coming back (#31415)

Fixes that examples based on snippets (e.g. first example for autocomplete) weren't showing up if the user lands on the page, clicks to another tab and then comes back.

The problem was that the timing is different on the second run, because we hit the cached rather than fetching the content. These changes resolve it by switching the component's internal state to signals.

Author: crisbeto

docs/src/app/shared/doc-viewer/doc-viewer.spec.ts

@@ -95,11 +95,12 @@ describe('DocViewer', () => {
 
     http.expectOne(testUrl).flush(FAKE_DOCS[testUrl]);
 
-    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer));
-    expect(exampleViewer.componentInstance.file).toBe('some-example.html');
-    expect(exampleViewer.componentInstance.showCompactToggle).toBeTrue();
-    expect(exampleViewer.componentInstance.region).toBe('some-region');
-    expect(exampleViewer.componentInstance.view).toBe('snippet');
+    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer))
+      .componentInstance as ExampleViewer;
+    expect(exampleViewer.file()).toBe('some-example.html');
+    expect(exampleViewer.showCompactToggle()).toBeTrue();
+    expect(exampleViewer.region()).toBe('some-region');
+    expect(exampleViewer.view()).toBe('snippet');
   });
 
   it('should instantiate example viewer in demo view', () => {
@@ -111,10 +112,11 @@ describe('DocViewer', () => {
 
     http.expectOne(testUrl).flush(FAKE_DOCS[testUrl]);
 
-    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer));
-    expect(exampleViewer.componentInstance.file).toBeUndefined();
-    expect(exampleViewer.componentInstance.showCompactToggle).toBeFalse();
-    expect(exampleViewer.componentInstance.view).toBe('demo');
+    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer))
+      .componentInstance as ExampleViewer;
+    expect(exampleViewer.file()).toBeUndefined();
+    expect(exampleViewer.showCompactToggle()).toBeFalse();
+    expect(exampleViewer.view()).toBe('demo');
   });
 
   it('should instantiate example viewer in snippet view with whole snippet', () => {
@@ -126,10 +128,11 @@ describe('DocViewer', () => {
 
     http.expectOne(testUrl).flush(FAKE_DOCS[testUrl]);
 
-    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer));
-    expect(exampleViewer.componentInstance.file).toBe('whole-snippet-example.ts');
-    expect(exampleViewer.componentInstance.showCompactToggle).toBeTrue();
-    expect(exampleViewer.componentInstance.view).toBe('snippet');
+    const exampleViewer = fixture.debugElement.query(By.directive(ExampleViewer))
+      .componentInstance as ExampleViewer;
+    expect(exampleViewer.file()).toBe('whole-snippet-example.ts');
+    expect(exampleViewer.showCompactToggle()).toBeTrue();
+    expect(exampleViewer.view()).toBe('snippet');
   });
 
   it('should show error message when doc not found', () => {

docs/src/app/shared/doc-viewer/doc-viewer.ts

@@ -30,6 +30,7 @@ import {
   ViewContainerRef,
   input,
   inject,
+  Type,
 } from '@angular/core';
 import {Observable, Subscription} from 'rxjs';
 import {shareReplay, take, tap} from 'rxjs/operators';
@@ -113,17 +114,17 @@ export class DocViewer implements OnDestroy {
     if (file) {
       // if the html div has field `file` then it should be in compact view to show the code
       // snippet
-      exampleViewerComponent.view = 'snippet';
-      exampleViewerComponent.showCompactToggle = true;
-      exampleViewerComponent.file = file;
+      exampleViewerComponent.view.set('snippet');
+      exampleViewerComponent.showCompactToggle.set(true);
+      exampleViewerComponent.file.set(file);
       if (region) {
         // `region` should only exist when `file` exists but not vice versa
         // It is valid for embedded example snippets to show the whole file (esp short files)
-        exampleViewerComponent.region = region;
+        exampleViewerComponent.region.set(region);
       }
     } else {
       // otherwise it is an embedded demo
-      exampleViewerComponent.view = 'demo';
+      exampleViewerComponent.view.set('demo');
     }
   }
 
@@ -175,7 +176,7 @@ export class DocViewer implements OnDestroy {
   }
 
   /** Instantiate a ExampleViewer for each example. */
-  private _loadComponents(componentName: string, componentClass: any) {
+  private _loadComponents(componentName: string, componentClass: Type<ExampleViewer | HeaderLink>) {
     const exampleElements = this._elementRef.nativeElement.querySelectorAll(`[${componentName}]`);
 
     [...exampleElements].forEach((element: Element) => {
@@ -185,9 +186,14 @@ export class DocViewer implements OnDestroy {
       const portalHost = new DomPortalOutlet(element, this._appRef, this._injector);
       const examplePortal = new ComponentPortal(componentClass, this._viewContainerRef);
       const exampleViewer = portalHost.attach(examplePortal);
-      const exampleViewerComponent = exampleViewer.instance as ExampleViewer;
-      if (example !== null) {
-        DocViewer._initExampleViewer(exampleViewerComponent, example, file, region);
+      const exampleViewerComponent = exampleViewer.instance;
+      if (example !== null && componentClass === ExampleViewer) {
+        DocViewer._initExampleViewer(
+          exampleViewerComponent as ExampleViewer,
+          example,
+          file,
+          region,
+        );
       }
       this._portalHosts.push(portalHost);
     });

docs/src/app/shared/example-viewer/example-viewer.html

@@ -1,5 +1,8 @@
+@let exampleData = this.exampleData();
+@let fileUrl = this.fileUrl();
+
 <div class="docs-example-viewer-wrapper">
-  @if (view === 'snippet') {
+  @if (view() === 'snippet') {
     <div class="docs-example-viewer-source-compact">
       <div class="docs-button-bar">
         <button mat-icon-button type="button" (click)="copySource(snippet())"
@@ -37,7 +40,7 @@
         <mat-icon>link</mat-icon>
       </button>
 
-      @if (showCompactToggle) {
+      @if (showCompactToggle()) {
         <button mat-icon-button
                 (click)="toggleCompactView()"
                 matTooltip="View snippet only"
@@ -52,37 +55,39 @@
       }
 
       <button mat-icon-button type="button" (click)="toggleSourceView()"
-              [matTooltip]="view === 'demo' ? 'View code' : 'Hide code'" aria-label="View source">
+              [matTooltip]="view() === 'demo' ? 'View code' : 'Hide code'" aria-label="View source">
         <mat-icon>code</mat-icon>
       </button>
 
       <stackblitz-button [example]="example"></stackblitz-button>
     </div>
 
-    @if (view === 'full') {
+    @if (view() === 'full') {
       <div class="docs-example-viewer-source">
         <mat-tab-group animationDuration="0ms" [(selectedIndex)]="selectedTab" mat-stretch-tabs="false">
-          @for (tabName of _getExampleTabNames(); track tabName) {
+          @for (tabName of _exampleTabNames(); track tabName) {
             <mat-tab [label]="tabName">
               <div class="docs-button-bar">
-                <button mat-icon-button type="button" (click)="copySource(snippet(), selectedTab)"
+                <button mat-icon-button type="button" (click)="copySource(snippet(), selectedTab())"
                         class="docs-example-source-copy docs-example-button" matTooltip="Copy example source"
                         title="Copy example source" aria-label="Copy example source to clipboard">
                   <mat-icon>content_copy</mat-icon>
                 </button>
               </div>
-              <code-snippet [source]="exampleTabs[tabName]"></code-snippet>
+              <code-snippet [source]="exampleTabs()[tabName]"></code-snippet>
             </mat-tab>
           }
         </mat-tab-group>
       </div>
     }
   }
 
-  @if (view !== 'snippet') {
+  @if (view() !== 'snippet') {
     <div class="docs-example-viewer-body">
-      @if (_exampleComponentType && !example?.includes('harness')) {
-        <ng-template [ngComponentOutlet]="_exampleComponentType"/>
+      @let componentType = _exampleComponentType();
+
+      @if (componentType && !example?.includes('harness')) {
+        <ng-template [ngComponentOutlet]="componentType"/>
       } @else {
         <div>This example contains tests. Open in Stackblitz to run the tests.</div>
       }