feat: update origin to Angular v18.0.1

Author: ricardochl

adev-es/src/app/sub-navigation-data.ts

@@ -8,6 +8,7 @@
 
 import {NavigationItem} from '@angular/docs';
 
+// These 2 imports are expected to be red because they are generated a build time
 import FIRST_APP_TUTORIAL_NAV_DATA from '../../src/assets/tutorials/first-app/routes.json';
 import LEARN_ANGULAR_TUTORIAL_NAV_DATA from '../../src/assets/tutorials/learn-angular/routes.json';
 
@@ -639,6 +640,12 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
           },
         ],
       },
+      {
+        label: 'Experimental features',
+        children: [
+          {label: 'Zoneless', path: 'guide/experimental/zoneless', contentPath: 'guide/zoneless'},
+        ],
+      },
     ],
   },
   {
@@ -678,9 +685,9 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [
             contentPath: 'tools/cli/end-to-end',
           },
           {
-            label: 'ESBuild',
-            path: 'tools/cli/esbuild',
-            contentPath: 'tools/cli/esbuild',
+            label: 'Migrating to new build system',
+            path: 'tools/cli/build-system-migration',
+            contentPath: 'tools/cli/build-system-migration',
           },
           {
             label: 'Build environments',
@@ -931,19 +938,70 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
       },
       {
         label: 'ng analytics',
-        path: 'cli/analytics',
+        children: [
+          {
+            label: 'Overview',
+            path: 'cli/analytics',
+          },
+          {
+            label: 'disable',
+            path: 'cli/analytics/disable',
+          },
+          {
+            label: 'enable',
+            path: 'cli/analytics/enable',
+          },
+          {
+            label: 'info',
+            path: 'cli/analytics/info',
+          },
+          {
+            label: 'prompt',
+            path: 'cli/analytics/prompt',
+          },
+        ],
       },
       {
         label: 'ng build',
         path: 'cli/build',
       },
       {
         label: 'ng cache',
-        path: 'cli/cache',
+        children: [
+          {
+            label: 'Overview',
+            path: 'cli/cache',
+          },
+          {
+            label: 'clear',
+            path: 'cli/cache/clean',
+          },
+          {
+            label: 'disable',
+            path: 'cli/cache/disable',
+          },
+          {
+            label: 'enable',
+            path: 'cli/cache/enable',
+          },
+          {
+            label: 'info',
+            path: 'cli/cache/info',
+          },
+        ],
       },
       {
         label: 'ng completion',
-        path: 'cli/completion',
+        children: [
+          {
+            label: 'Overview',
+            path: 'cli/completion',
+          },
+          {
+            label: 'script',
+            path: 'cli/completion/script',
+          },
+        ],
       },
       {
         label: 'ng config',
@@ -953,10 +1011,6 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
         label: 'ng deploy',
         path: 'cli/deploy',
       },
-      {
-        label: 'ng doc',
-        path: 'cli/doc',
-      },
       {
         label: 'ng e2e',
         path: 'cli/e2e',
@@ -967,7 +1021,80 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
       },
       {
         label: 'ng generate',
-        path: 'cli/generate',
+        children: [
+          {
+            label: 'Overview',
+            path: 'cli/generate',
+          },
+          {
+            label: 'app-shell',
+            path: 'cli/generate/app-shell',
+          },
+          {
+            label: 'application',
+            path: 'cli/generate/application',
+          },
+          {
+            label: 'class',
+            path: 'cli/generate/class',
+          },
+          {
+            label: 'component',
+            path: 'cli/generate/component',
+          },
+          {
+            label: 'config',
+            path: 'cli/generate/config',
+          },
+          {
+            label: 'enum',
+            path: 'cli/generate/enum',
+          },
+          {
+            label: 'environments',
+            path: 'cli/generate/environments',
+          },
+          {
+            label: 'guard',
+            path: 'cli/generate/guard',
+          },
+          {
+            label: 'interceptor',
+            path: 'cli/generate/interceptor',
+          },
+          {
+            label: 'interface',
+            path: 'cli/generate/interface',
+          },
+          {
+            label: 'library',
+            path: 'cli/generate/library',
+          },
+          {
+            label: 'module',
+            path: 'cli/generate/module',
+          },
+          {
+            label: 'pipe',
+            path: 'cli/generate/pipe',
+          },
+          {
+            label: 'resolver',
+            path: 'cli/generate/resolver',
+          },
+          {
+            label: 'service-worker',
+            path: 'cli/generate/service-worker',
+          },
+          {
+            label: 'service',
+            path: 'cli/generate/service',
+          },
+          {
+            label: 'web-worker',
+            path: 'cli/generate/web-worker',
+          },
+        ],
       },
       {
         label: 'ng lint',
@@ -1112,6 +1239,11 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
         path: 'errors/NG0507',
         contentPath: 'reference/errors/NG0507',
       },
+      {
+        label: 'NG0602: HTML content was altered after server-side rendering',
+        path: 'errors/NG0602',
+        contentPath: 'reference/errors/NG0602',
+      },
       {
         label: 'NG05104: Root element was not found',
         path: 'errors/NG05104',
@@ -1127,6 +1259,26 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
         path: 'errors/NG0912',
         contentPath: 'reference/errors/NG0912',
       },
+      {
+        label: 'NG0950: Required input is accessed before a value is set.',
+        path: 'errors/NG0950',
+        contentPath: 'reference/errors/NG0950',
+      },
+      {
+        label: 'NG0951: Child query result is required but no value is available.',
+        path: 'errors/NG0951',
+        contentPath: 'reference/errors/NG0951',
+      },
+      {
+        label: 'NG0955: Track expression resulted in duplicated keys for a given collection',
+        path: 'errors/NG0955',
+        contentPath: 'reference/errors/NG0955',
+      },
+      {
+        label: 'NG0956: Tracking expression caused re-creation of the DOM structure',
+        path: 'errors/NG0956',
+        contentPath: 'reference/errors/NG0956',
+      },
       {
         label: 'NG1001: Argument Not Literal',
         path: 'errors/NG1001',
@@ -1148,9 +1300,9 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
         contentPath: 'reference/errors/NG3003',
       },
       {
-        label: 'NG5000: Hydration with unsupported Zone.js instance.',
-        path: 'errors/NG5000',
-        contentPath: 'reference/errors/NG5000',
+        label: 'NG05000: Hydration with unsupported Zone.js instance.',
+        path: 'errors/NG05000',
+        contentPath: 'reference/errors/NG05000',
       },
       {
         label: 'NG6100: NgModule.id Set to module.id anti-pattern',
@@ -1239,6 +1391,10 @@ const REFERENCE_SUB_NAVIGATION_DATA: NavigationItem[] = [
     path: 'reference/versions',
     contentPath: 'reference/versions',
   },
+  {
+    label: 'Update guide',
+    path: 'update-guide',
+  },
   {
     label: 'Configurations',
     children: [

adev-es/src/content/best-practices/a11y.md

@@ -76,15 +76,15 @@ The following example shows how to make a progress bar accessible by using host
     The ARIA attribute `aria-valuenow` is bound to the user's input.
 * In the template, the `aria-label` attribute ensures that the control is accessible to screen readers.
 
-<docs-code-multifile
-  path="adev/src/content/examples/accessibility/src/app/app.component.ts"
-  preview>
+<docs-code-multifile>
   <docs-code
     path="adev/src/content/examples/accessibility/src/app/progress-bar.component.ts"
+    language="ts"
     linenums
     highlight="[12, 20]"/>
   <docs-code
     path="adev/src/content/examples/accessibility/src/app/app.component.html"
+    language="html"
     linenums
     highlight="[8, 9]"/>
 </docs-code-multifile>

adev-es/src/content/best-practices/runtime-performance/skipping-subtrees.md

@@ -59,8 +59,6 @@ If Angular handles an event within a component with OnPush strategy, the framewo
 
 As an example, if Angular handles an event within `MainComponent`, the framework will run change detection in the entire component tree. Angular will ignore the subtree with root `LoginComponent` because it has `OnPush` and the event happened outside of its scope.
 
-<img alt="Change detection propagation from OnPush component" src="assets/images/best-practices/runtime-performance/on-push-trigger.svg">
-
 ```mermaid
 graph TD;
     app[AppComponent] --- header[HeaderComponent];

adev-es/src/content/best-practices/runtime-performance/slow-computations.md

@@ -19,7 +19,7 @@ For example, in the preceding screenshot, the second recorded change detection c
 Here are several techniques to remove slow computations:
 
 * **Optimizing the underlying algorithm**. This is the recommended approach. If you can speed up the algorithm that is causing the problem, you can speed up the entire change detection mechanism.
-* **Caching using pure pipes**. You can move the heavy computation to a pure [pipe](/guide/pipes). Angular reevaluates a pure pipe only if it detects that its inputs have changed, compared to the previous time Angular called it.
+* **Caching using pure pipes**. You can move the heavy computation to a pure [pipe](guide/pipes). Angular reevaluates a pure pipe only if it detects that its inputs have changed, compared to the previous time Angular called it.
 * **Using memoization**. [Memoization](https://en.wikipedia.org/wiki/Memoization) is a similar technique to pure pipes, with the difference that pure pipes preserve only the last result from the computation where memoization could store multiple results.
 * **Avoid repaints/reflows in lifecycle hooks**. Certain [operations](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing/) cause the browser to either synchronously recalculate the layout of the page or re-render it. Since reflows and repaints are generally slow, you want to avoid performing them in every change detection cycle.
 

adev-es/src/content/best-practices/runtime-performance/zone-pollution.md

@@ -35,7 +35,7 @@ class AppComponent implements OnInit {
 
 The preceding snippet instructs Angular to call `setInterval` outside the Angular Zone and skip running change detection after `pollForUpdates` runs.
 
-Third-party libraries commonly trigger unnecessary change detection cycles because they weren't authored with Zone.js in mind. Avoid these extra cycles by calling library APIs outside the Angular zone:
+Third-party libraries commonly trigger unnecessary change detection cycles when their APIs are invoked within the Angular zone. This phenomenon particularly affects libraries that setup event listeners or initiate other tasks (such as timers, XHR requests, etc.). Avoid these extra cycles by calling library APIs outside the Angular zone:
 
 <docs-code header="Move the plot initialization outside of the Zone" language='ts' linenums>
 import { Component, NgZone, OnInit } from '@angular/core';
@@ -57,3 +57,67 @@ class AppComponent implements OnInit {
 Running `Plotly.newPlot('chart', data);` within `runOutsideAngular` instructs the framework that it shouldn’t run change detection after the execution of tasks scheduled by the initialization logic.
 
 For example, if `Plotly.newPlot('chart', data)` adds event listeners to a DOM element, Angular does not run change detection after the execution of their handlers.
+
+But sometimes, you may need to listen to events dispatched by third-party APIs. In such cases, it's important to remember that those event listeners will also execute outside of the Angular zone if the initialization logic was done there:
+
+<docs-code header="Check whether the handler is called outside of the Zone" language='ts' linenums>
+import { Component, NgZone, OnInit, output } from '@angular/core';
+import * as Plotly from 'plotly.js-dist-min';
+
+@Component(...)
+class AppComponent implements OnInit {
+  plotlyClick = output<Plotly.PlotMouseEvent>();
+
+  constructor(private ngZone: NgZone) {}
+
+  ngOnInit() {
+    this.ngZone.runOutsideAngular(() => {
+      this.createPlotly();
+    });
+  }
+
+  private async createPlotly() {
+    const plotly = await Plotly.newPlot('chart', data);
+
+    plotly.on('plotly_click', (event: Plotly.PlotMouseEvent) => {
+      // This handler will be called outside of the Angular zone because
+      // the initialization logic is also called outside of the zone. To check
+      // whether we're in the Angular zone, we can call the following:
+      console.log(NgZone.isInAngularZone());
+      this.plotlyClick.emit(event);
+    });
+  }
+}
+</docs-code>
+
+If you need to dispatch events to parent components and execute specific view update logic, you should consider re-entering the Angular zone to instruct the framework to run change detection or run change detection manually:
+
+<docs-code header="Re-enter the Angular zone when dispatching event" language='ts' linenums>
+import { Component, NgZone, OnInit, output } from '@angular/core';
+import * as Plotly from 'plotly.js-dist-min';
+
+@Component(...)
+class AppComponent implements OnInit {
+  plotlyClick = output<Plotly.PlotMouseEvent>();
+
+  constructor(private ngZone: NgZone) {}
+
+  ngOnInit() {
+    this.ngZone.runOutsideAngular(() => {
+      this.createPlotly();
+    });
+  }
+
+  private async createPlotly() {
+    const plotly = await Plotly.newPlot('chart', data);
+
+    plotly.on('plotly_click', (event: Plotly.PlotMouseEvent) => {
+      this.ngZone.run(() => {
+        this.plotlyClick.emit(event);
+      });
+    });
+  }
+}
+</docs-code>
+
+The scenario of dispatching events outside of the Angular zone may also arise. It's important to remember that triggering change detection (for example, manually) may result to the creation/update of views outside of the Angular zone.

adev-es/src/content/best-practices/style-guide.md

@@ -730,7 +730,7 @@ If the property is hard to construct a default value for, use `?` to explicitly
 
 You may want to have a required `@Input` field, meaning all your component users are required to pass that attribute.
 In such cases, use a default value.
-Just suppressing the TypeScript error with `!` is insufficient and should be avoided because it will prevent the type checker ensure the input value is provided.
+Just suppressing the TypeScript error with `!` is insufficient and should be avoided because it will prevent the type checker from ensuring the input value is provided.
 
 <docs-code header="app/heroes/hero/hero.component.ts" path="adev/src/content/examples/styleguide/src/05-18/app/heroes/hero/hero.component.avoid.ts" visibleRegion="example"/>