feat(demo): add change detection content

Author: tomastrajan

projects/elements-demo/src/app/core/layout/navigation/navigation.component.ts

@@ -21,6 +21,10 @@ const NAVIGATION = [
         label: 'Use cases',
         url: 'docs/use-cases'
       },
+      {
+        label: 'Change detection',
+        url: 'docs/change-detection'
+      },
       {
         label: 'API',
         url: 'docs/api'

projects/elements-demo/src/app/features/docs/change-detection/change-detection-routing.module.ts

@@ -0,0 +1,12 @@
+import { NgModule } from '@angular/core';
+import { Routes, RouterModule } from '@angular/router';
+
+import { ChangeDetectionComponent } from './change-detection.component';
+
+const routes: Routes = [{ path: '', component: ChangeDetectionComponent }];
+
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule]
+})
+export class ChangeDetectionRoutingModule {}

projects/elements-demo/src/app/features/docs/change-detection/change-detection.component.html

@@ -0,0 +1,50 @@
+<div class="wrapper">
+  <h1>Change detection</h1>
+  <p>
+    In this section we're going to curate and discuss various change detection
+    related issues and lessons learned when using Angular Elements.
+  </p>
+
+  <h2>
+    RxJs stream runs in a wrong (parent / outer) zone.js [Angular Elements]
+  </h2>
+  <h3>Description</h3>
+  <p>
+    This issue happens when using <code>@angular/element</code> inside of a
+    parent Angular application. The parent application and element will NOT run
+    in the same zone. This will lead to problems with change detection inside of
+    the element when the <code>rxjs</code> stream was triggered by the change of
+    the <code>@Input() prop</code> originating in the parent application.
+  </p>
+  <p>
+    The stream will run in parent zone (instead of element zone) so any async
+    operation (like backend request or using
+    <code>debounceTime()</code> operator) will not trigger change detection of
+    the element so the stream data will not be rendered...
+  </p>
+  <h3>Solution</h3>
+  <ol>
+    <li>
+      Do NOT use <code>zone.js</code> in your Angular element and trigger change
+      detection manually
+    </li>
+    <li>
+      Use single (parent) <code>NgZone</code> also for both the application and
+      the element.
+      <pre [highlight]="codeExampleShareNgZone"></pre>
+    </li>
+    <li>
+      Use <code>import 'zone.js/dist/zone-patch-rxjs';</code> in your Angular
+      element. This will fix it BUT if the parent application (or ANY other lib
+      used by the parent application) already has this import then the one in
+      the element will be ignored and hence not solving the problem.
+    </li>
+  </ol>
+  <p>
+    Check out detailed description of the
+    <a href="https://github.com/angular/angular/issues/31870" target="_blank"
+      >issue</a
+    >
+    and some of the proposed solutions...
+  </p>
+</div>

projects/elements-demo/src/app/features/docs/change-detection/change-detection.component.scss

@@ -0,0 +1,19 @@
+h2 {
+  margin: 40px 0 10px 0;
+  font-weight: bold;
+}
+
+h3 {
+  margin: 20px 0 5px 0;
+  font-weight: bold;
+}
+
+ol {
+  margin: 0 0 20px 0;
+}
+
+:host-context(.responsive-large) {
+  .wrapper {
+    width: 70%;
+  }
+}

projects/elements-demo/src/app/features/docs/change-detection/change-detection.component.spec.ts

@@ -0,0 +1,34 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+import { HighlightModule } from 'ngx-highlightjs';
+import typescript from 'highlight.js/lib/languages/typescript';
+
+import { SharedModule } from '../../../shared/shared.module';
+
+import { ChangeDetectionComponent } from './change-detection.component';
+
+describe('ChangeDetectionComponent', () => {
+  let component: ChangeDetectionComponent;
+  let fixture: ComponentFixture<ChangeDetectionComponent>;
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        HighlightModule.forRoot({
+          languages: () => [{ name: 'typescript', func: typescript }]
+        }),
+        SharedModule
+      ],
+      declarations: [ChangeDetectionComponent]
+    }).compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ChangeDetectionComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

projects/elements-demo/src/app/features/docs/change-detection/change-detection.component.ts

@@ -0,0 +1,26 @@
+import { Component, OnInit } from '@angular/core';
+
+@Component({
+  selector: 'demo-change-detection',
+  templateUrl: './change-detection.component.html',
+  styleUrls: ['./change-detection.component.scss']
+})
+export class ChangeDetectionComponent implements OnInit {
+  codeExampleShareNgZone = CODE_EXAMPLE_SHARE_NG_ZONE;
+
+  constructor() {}
+
+  ngOnInit() {}
+}
+
+export const CODE_EXAMPLE_SHARE_NG_ZONE = `// in parent app (app.module.ts)
+export class AppModule {
+  constructor(private ngZone: NgZone) {
+    (window as any).ngZone = this.ngZone // store ngZone reference on the window object
+  }
+}
+
+// in element (main.ts)
+platformBrowserDynamic()
+  .bootstrapModule(AppModule, { ngZone: (window as any).ngZone }) // use parent ngZone
+`;

projects/elements-demo/src/app/features/docs/change-detection/change-detection.module.ts

@@ -0,0 +1,13 @@
+import { NgModule } from '@angular/core';
+import { HighlightModule } from 'ngx-highlightjs';
+
+import { SharedModule } from '../../../shared/shared.module';
+
+import { ChangeDetectionRoutingModule } from './change-detection-routing.module';
+import { ChangeDetectionComponent } from './change-detection.component';
+
+@NgModule({
+  declarations: [ChangeDetectionComponent],
+  imports: [HighlightModule, SharedModule, ChangeDetectionRoutingModule]
+})
+export class ChangeDetectionModule {}

projects/elements-demo/src/app/features/docs/docs-routing.module.ts

@@ -39,6 +39,13 @@ const routes: Routes = [
       {
         path: 'faq',
         loadChildren: () => import('./faq/faq.module').then(m => m.FaqModule)
+      },
+      {
+        path: 'change-detection',
+        loadChildren: () =>
+          import('./change-detection/change-detection.module').then(
+            m => m.ChangeDetectionModule
+          )
       }
     ]
   }