build(docs-infra): show a dist-tag when installing the CLI on non-stable versions (#41991)

It is important to use the correct major version of the Angular CLI when
following the examples in the tutorials. This commit provides a custom
element that renders an appropriate dist-tag in the setup step of
the tutorial when the docs are not in "stable" mode.

Fixes #39821

PR Close #41991

aio/content/guide/setup-local.md

@@ -59,7 +59,7 @@ You use the Angular CLI to create projects, generate application and library cod
 To install the Angular CLI, open a terminal window and run the following command:
 
 <code-example language="sh">
-  npm install -g @angular/cli
+  npm install -g @angular/cli<aio-angular-dist-tag class="pln"></aio-angular-dist-tag>
 </code-example>
 
 {@a create-proj}

aio/src/app/custom-elements/dist-tag/dist-tag.component.spec.ts

@@ -0,0 +1,47 @@
+import { VERSION } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { environment } from 'environments/environment';
+import { DistTagComponent } from './dist-tag.component';
+
+describe('DistTagComponent', () => {
+  let actualMode: string;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({ declarations: [DistTagComponent] });
+    actualMode = environment.mode;
+  });
+
+  afterEach(() => {
+    (environment.mode as any) = actualMode;
+  });
+
+  describe('rendering', () => {
+    it('should display nothing (for stable versions)', () => {
+      environment.mode = 'stable';
+      const fixture = TestBed.createComponent(DistTagComponent);
+      fixture.detectChanges();
+      expect(fixture.nativeElement.innerHTML).toEqual('');
+    });
+
+    it('should display the current major version (for archive versions)', () => {
+      environment.mode = 'archive';
+      const fixture = TestBed.createComponent(DistTagComponent);
+      fixture.detectChanges();
+      expect(fixture.nativeElement.innerHTML).toEqual('@' + VERSION.major);
+    });
+
+    it('should display "@next" (for rc versions)', () => {
+      environment.mode = 'rc';
+      const fixture = TestBed.createComponent(DistTagComponent);
+      fixture.detectChanges();
+      expect(fixture.nativeElement.innerHTML).toEqual('@next');
+    });
+
+    it('should display "@next" (for next versions)', () => {
+      environment.mode = 'next';
+      const fixture = TestBed.createComponent(DistTagComponent);
+      fixture.detectChanges();
+      expect(fixture.nativeElement.innerHTML).toEqual('@next');
+    });
+  });
+});

aio/src/app/custom-elements/dist-tag/dist-tag.component.ts

@@ -0,0 +1,27 @@
+import { Component, VERSION } from '@angular/core';
+import { environment } from 'environments/environment';
+
+/**
+ * Display the dist-tag of Angular for installing from npm at the point these docs are generated.
+ */
+@Component({
+  selector: 'aio-angular-dist-tag',
+  template: '{{tag}}',
+})
+export class DistTagComponent {
+  tag: string;
+
+  constructor() {
+    switch (environment.mode) {
+      case 'stable':
+        this.tag = '';
+        break;
+      case 'next':
+      case 'rc':
+        this.tag = '@next';
+        break;
+      default:
+        this.tag = `@${VERSION.major}`;
+    }
+  }
+}

aio/src/app/custom-elements/dist-tag/dist-tag.module.ts

@@ -0,0 +1,12 @@
+import { NgModule, Type } from '@angular/core';
+import { WithCustomElementComponent } from '../element-registry';
+
+import { DistTagComponent } from './dist-tag.component';
+
+@NgModule({
+  declarations: [ DistTagComponent ],
+  entryComponents: [ DistTagComponent ],
+})
+export class DistTagModule implements WithCustomElementComponent {
+  customElementComponent: Type<any> = DistTagComponent;
+}

aio/src/app/custom-elements/element-registry.ts

@@ -21,6 +21,10 @@ export const ELEMENT_MODULE_LOAD_CALLBACKS_AS_ROUTES = [
     selector: 'aio-file-not-found-search',
     loadChildren: () => import('./search/file-not-found-search.module').then(m => m.FileNotFoundSearchModule)
   },
+  {
+    selector: 'aio-angular-dist-tag',
+    loadChildren: () => import('./dist-tag/dist-tag.module').then(m => m.DistTagModule)
+  },
   {
     selector: 'aio-resource-list',
     loadChildren: () => import('./resource/resource-list.module').then(m => m.ResourceListModule)

goldens/size-tracking/aio-payloads.json

@@ -2,18 +2,18 @@
   "aio": {
     "master": {
       "uncompressed": {
-        "runtime-es2015": 4444,
+        "runtime-es2015": 4538,
-        "main-es2015": 451200,
+        "main-es2015": 451314,
-        "polyfills-es2015": 55283
+        "polyfills-es2015": 55210
       }
     }
   },
   "aio-local": {
     "master": {
       "uncompressed": {
-        "runtime-es2015": 4444,
+        "runtime-es2015": 4538,
-        "main-es2015": 451200,
+        "main-es2015": 451493,
-        "polyfills-es2015": 55283
+        "polyfills-es2015": 55291
       }
     }
   }